codd-scan

CoDD Scan

Refresh the CoDD dependency graph from document frontmatter and source code so later commands (codd validate, codd impact, codd generate, codd verify) operate on current project state. Use this after requirements, design docs, implementation, or tests change.

When to Use

• After editing Markdown files with CoDD frontmatter
• After adding or changing source files that affect dependencies
• Before codd impact when you need a fresh graph
• When scan counts look stale or unexpectedly low

Preconditions

1. Resolve the target project root first. Prefer an absolute path when the working directory is ambiguous.
2. Check whether codd/codd.yaml exists under that path.
3. If codd/codd.yaml is missing, initialize CoDD before scanning:

codd init --project-name "<project-name>" --language "<language>" --dest <path>

1. If codd is not on PATH, use one of these:
   • pip install codd-dev
   • .venv/bin/codd scan --path <path>

Command

Run the scan from anywhere by passing the project root explicitly:

codd scan --path <path>

If you are already at the project root, codd scan --path . is sufficient.

What the Scan Does

1. Reads codd/codd.yaml
2. Rebuilds auto-generated graph data from project documents and source code
3. Preserves human-authored evidence
4. Prints a short summary of frontmatter coverage and graph size

How to Interpret the Result

Typical output includes:

Scan complete:
  Documents with frontmatter: <count>
  Graph: <nodes> nodes, <edges> edges
  Evidence: <total> total (...)

• Documents with frontmatter: how many Markdown documents in configured doc_dirs were successfully read as CoDD documents. If this is lower than expected, inspect missing frontmatter or wrong doc_dirs.
• nodes: the number of tracked artifacts in the graph. In document-centric projects this is usually close to the total number of requirements/design/test artifacts being tracked.
• edges: the total number of declared or inferred dependency relationships between those artifacts.
• orphan nodes: artifacts that have no surviving dependency relationship. They are often a sign of missing depends_on, stale docs, or a document that should be deleted. Some top-level requirements may be intentional exceptions, but unexplained orphans should always be reviewed.
• WARNING: lines: scan found suspicious input such as missing frontmatter or design docs with empty dependencies. Treat warnings as a prompt to run codd validate.
• SCAN_ERROR (if surfaced by your wrapper, report script, or higher-level UI): frontmatter could not be parsed or read cleanly. Treat it as a validation problem and inspect the document with codd validate --path <path>.