docs

func CalculateFullHash ¶

func CalculateFullHash(filePath string) (string, error)

CalculateFullHash returns full 64-character SHA256 hash. Use this for database storage if full hash precision is needed.

func CalculateHash ¶

func CalculateHash(filePath string) (string, error)

CalculateHash computes SHA256 hash of documentation file with line ending normalization. Returns first 16 characters (64 bits) for abbreviated display in CANARY tokens.

Line endings are normalized to LF (\n) before hashing to ensure cross-platform consistency between Windows (CRLF) and Unix/Mac (LF) systems.

Example:

hash, err := docs.CalculateHash("docs/user/auth.md")
// Returns: "8f434346648f6b96" (first 16 chars of SHA256)

func CheckMultipleDocumentation ¶

func CheckMultipleDocumentation(token *storage.Token) (map[string]string, error)

CheckMultipleDocumentation handles tokens with multiple DOC paths (comma-separated), resolving each relative path against the process's current working directory. It is a compatibility delegate to CheckMultipleDocumentationIn("." , token); see CheckStaleness for why callers that know their project root should prefer the *In variant.

Example:

// Token with: DOC=user:docs/user.md,api:docs/api.md
results, err := docs.CheckMultipleDocumentation(token)
// Returns: {"docs/user.md": "DOC_CURRENT", "docs/api.md": "DOC_STALE"}

func CheckMultipleDocumentationIn ¶ added in v0.3.6

func CheckMultipleDocumentationIn(root string, token *storage.Token) (map[string]string, error)

CheckMultipleDocumentationIn is CheckMultipleDocumentation with an explicit root; each parsed doc path is checked via CheckStalenessIn(root, ...), so every relative path in a multi-doc token resolves under the same root rather than the process's CWD.

func CheckStaleness ¶

func CheckStaleness(token *storage.Token) (string, error)

CheckStaleness compares documentation file hash to token DOC_HASH field, resolving a relative token.DocPath against the process's current working directory. It is a compatibility delegate to CheckStalenessIn("." , token); callers that know their project root (every CLI command under pkg/cmds/doc) should call CheckStalenessIn directly so a relative DocPath never gets silently resolved against the wrong directory (C5-07).

Returns one of: DOC_CURRENT, DOC_STALE, DOC_MISSING, DOC_UNHASHED, or DOC_ERROR.

Example:

status, err := docs.CheckStaleness(token)
if status == "DOC_STALE" {
    fmt.Printf("Documentation for %s is outdated\n", token.ReqID)
}

func CheckStalenessIn ¶ added in v0.3.6

func CheckStalenessIn(root string, token *storage.Token) (string, error)

CheckStalenessIn is CheckStaleness with an explicit root: a relative token.DocPath resolves via filepath.Join(root, DocPath); an absolute DocPath is used as given. A relative path that, once joined and cleaned, does not lie under root (e.g. a DOC field poisoned with "../../etc/x") is never read -- it reports DOC_ERROR rather than escaping root. status/report commands are read-only, so this function only resolves and confine-checks; it never mutates anything.

Status meanings:

• DOC_CURRENT: File hash matches token DOC_HASH (documentation is up-to-date)
• DOC_STALE: File hash differs from token DOC_HASH (documentation needs updating)
• DOC_MISSING: Documentation file does not exist at the resolved path
• DOC_UNHASHED: Token has no DOC_HASH field (hash tracking not enabled)
• DOC_ERROR: The path escapes root, or the file exists but could not be stat'd/hashed (e.g. a permission error) -- distinct from DOC_MISSING so a caller can count and surface it rather than silently skipping it.