DocSutra AIDocumentation Truth Audit - v0.2.1 - by Vatsal Shah

Technical architecture

Modules, data flow, contracts, design decisions and trade-offs. Written so a new contributor can navigate the code in minutes.

Design principles

  1. Offline and deterministic. Same input, same findings, same IDs. Only timestamps and duration vary.
  2. Untrusted input. Every scanned file is data. Nothing in it is executed or obeyed.
  3. Honest evidence. Every finding names its evidence method; every report states what was not checked.
  4. Zero runtime dependencies. Only Node.js built-ins. Smaller supply-chain risk, simpler installs.
  5. Pure core, thin edges. Parsing and rules are functions; file and process I/O sit at the boundaries.

Pipeline

Scan pipelineMarkdown files flow through discovery, parsing, rule checks and reporting into four output formats. No network and no command execution.Discover.md .mdxParseheadings, linksRules18 rulesLedger+ provenanceJSON / SARIFMarkdownHTML

Trust boundaries

Trust boundariesScanned repository content is untrusted input to the DocSutra process. The only outputs are report files in a user chosen folder. Network and command execution are blocked by design.UntrustedMarkdown filescode fenceslinks, front mattertreated as data onlyDocSutra processread-only scannerno networkno command executionsecrets redactedOutputaudit.jsonaudit.md / .htmlaudit.sarif

Module map

PathResponsibility
packages/core/files.mjsBounded discovery, symlink skipping, link target resolution (root-relative, directory, case check)
packages/core/markdown.mjsLine scanner: headings, anchors, links, references, code, comments, front matter
packages/core/commands.mjsShell snippet classification and declared-CLI-contract checks
packages/core/security.mjsCredential patterns, redaction, excerpt creation
packages/core/rules.mjsVersioned rule catalog (severity, category, evidence type)
packages/core/config.mjsStrict config validation
packages/core/audit.mjsOrchestrates a scan, builds the ledger, applies suppression, returns the report object
packages/reporter/index.mjsJSON, Markdown, HTML and SARIF renderers; multi-file writer
packages/cli/index.mjsArgument parsing, commands, exit codes
packages/adapters/skills.mjsSafe project-local skill installer for five hosts
packages/server/index.mjsLoopback read-only report server
packages/index.mjsPublic programmatic API
scripts/Benchmark, evidence, skill and documentation builders

Data model

The report (schemaVersion 2.0.0) is a single JSON object: tool, toolVersion, rulesVersion, mode, createdAt, environment, inputFingerprint, summary, ledger, rules, files, findings, limitations. A finding has id, rule, severity, category, file, line, message, subject, suggestion, excerpt, status, verificationMethod, confidence. The JSON Schema is in schemas/audit.schema.json.

Finding ID = first 16 hex characters of SHA-256 over rule | file | line | subject. Stable across runs, which is what makes baseline comparison work. Moving a line changes its ID; that limit is documented.

Key algorithms

Design decisions

DecisionReasonTrade-off
Custom scanner instead of a Markdown AST libraryZero dependencies; precise control of what is supportedNot full CommonMark; documented in the coverage matrix
Declared CLI contracts instead of running --helpRunning tools executes codeContract can go stale; reports say so
Report is one self-contained HTML file with no scriptsSafe to open and archive; strict CSPFiltering uses CSS only
Static classification of snippets, no executionSafety firstNo runtime verification of examples
Strict config validationTypos should not silently disable checksSlightly less forgiving

Extending

Add a rule in four steps: register it in rules.mjs, emit it from audit.mjs or a core module, add a case to benchmark/corpus with its label in labels.json, and add a unit test. The benchmark gate in CI fails if precision or recall drops.