Documentation
¶
Overview ¶
Package drift detects mismatches between what a CANARY token claims and what the repository actually shows: code committed after a token's UPDATED date (code-drift), tokens that have aged past the staleness window (stale), and — when a CANARY index database is present — documentation that has fallen out of sync with its source (doc-drift). CANARY: REQ=CP-278; FEATURE="DriftDetect"; ASPECT=Engine; STATUS=TESTED; TEST=TestCANARY_CBIN_305_Detect_CodeDriftPositive,TestCANARY_CBIN_305_Detect_CodeDriftNegative,TestCANARY_CBIN_305_Detect_CodeDriftSameDayNotDrift,TestCANARY_CBIN_305_Detect_NonGitRootSoftSkip,TestCANARY_CBIN_305_Detect_UntrackedFileSoftSkip,TestCANARY_CBIN_305_Detect_Stale,TestCANARY_CBIN_305_Detect_StaleIgnoresNonTestedBenched,TestCANARY_CBIN_305_Detect_DocDrift,TestCANARY_CBIN_305_Detect_DocDriftNoDB,TestCANARY_CBIN_305_Detect_CodeDriftDedupesPerFile,TestCANARY_CBIN_305_Detect_CachesGitLogPerFile; UPDATED=2026-08-29
Index ¶
Constants ¶
const ( KindCodeDrift = "code-drift" KindStale = "stale" KindDocDrift = "doc-drift" )
Kind values for Finding.Kind.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Finding ¶
type Finding struct {
ReqID string `json:"req_id"`
File string `json:"file"`
Kind string `json:"kind"` // code-drift | stale | doc-drift
Detail string `json:"detail"`
}
Finding is one detected drift signal for a requirement.
func Detect ¶
func Detect(root string, rep canaryscan.Report, staleDays int, refTime time.Time) ([]Finding, error)
Detect scans rep for drift signals relative to root:
- code-drift: a token's file was committed (per git history) after the token's UPDATED date. Skips silently (no error, no finding) when root is not a git repository, git is unavailable, or the file is untracked.
- stale: TESTED/BENCHED tokens older than staleDays, using the same rule as canaryscan.Stale. staleDays <= 0 falls back to canaryscan.DefaultStaleDays.
- doc-drift: when root/.canary/canary.db exists, tokens whose DocStatus is DOC_STALE or DOC_MISSING. Skips silently (no error, no finding) when no database is present.
If refTime is zero, time.Now().UTC() is used (mirroring canaryscan.Stale).
Source Files