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

Functional specification

Exactly what the tool does from a user's point of view: commands, inputs, outputs, behaviours and exit codes.

Capabilities

IDCapabilityStatus
F1Discover .md, .mdx, .markdown files (bounded count and size, symlinks skipped)Implemented
F2Verify local links, root-relative links, directory links and heading anchorsImplemented
F3Detect case-only path mismatches (works on Windows/macOS, breaks on Linux)Implemented on case-insensitive filesystems
F4Resolve inline, full, collapsed and shortcut reference linksImplemented
F5Accessibility hints: image alt, empty link text, heading level skipsImplemented
F6Compare documented commands to a declared CLI contractImplemented
F7Classify shell snippets by risk without executing themImplemented
F8Detect credentials and redact them in all outputsImplemented
F9Reports in JSON, Markdown, HTML, SARIF with ledger and provenanceImplemented
F10Baseline comparison and CI gatingImplemented
F11Inline and config suppression, countedImplemented
F12Install 16 skills into project folders for five hostsImplemented (activation unverified)
F13Loopback read-only report serverImplemented
F14External link checking, snippet execution, API/schema comparisonNot implemented

Commands

docsutra scan [--root PATH] [--config FILE] [--format all|json|md|html|sarif]
              [--out-dir DIR] [--out FILE] [--fail-on error|warning|none] [--baseline OLD.json]
docsutra diff --before OLD.json --after NEW.json [--out diff.json]
docsutra install-skills --host claude --target PATH
docsutra doctor
docsutra serve --report audit.json
docsutra version

scan

Exit codes

CodeMeaning
0No findings at or above the --fail-on level
1At least one finding at or above the level (default error)
2Usage, configuration or runtime error (for example unknown config key, unreadable baseline)

Severity model

SeverityMeaningFails the build by default
errorReproducibly wrong: broken link, missing anchor, leaked credentialYes
warningLikely problem or risk: missing alt text, pipe-to-shellOnly with --fail-on warning
infoStructure suggestion: duplicate heading, skipped heading levelNo

Report contents

  1. Verdict (PASS, PASS WITH WARNINGS, FAIL) and counts.
  2. Verification ledger: per check, performed / passed / failed.
  3. Findings grouped by file: rule, line, message, context excerpt (redacted), suggested fix, evidence method, stable ID.
  4. Not checked: external URLs, unexecuted shell lines, suppressed findings, limitations.
  5. Rules triggered, with meaning.
  6. Provenance: tool/rules/schema versions, Node and OS, git revision, SHA-256 input fingerprint, per-file hashes, reproduce command.

Configuration

docsutra.config.json is validated strictly. Allowed keys: schemaVersion, ignore, maxFiles, maxBytes, ignoreRules, cliContracts, failOn. Any other key exits with code 2.

Suppression

Add <!-- docsutra-disable-next-line RULE_ID --> on the line before the one to silence, or list rules in ignoreRules. Suppressed findings are counted in the report so they cannot hide silently.

Out of scope by design

The scanner never runs commands, never contacts a URL, never edits files, and never sends data to an AI provider.