Rules reference
Every rule with its severity, category and evidence type. Generated from the same catalog the scanner uses, so it cannot drift.
Rule catalog
| Rule | Severity | Category | Evidence | What it means |
|---|---|---|---|---|
BROKEN_LOCAL_LINK | error | links | local-filesystem | A relative or repository-root link points at a file or directory that does not exist. |
BROKEN_ANCHOR | error | links | local-filesystem | A #fragment does not match any heading or id/name attribute in the target Markdown file (GitHub slug rules). |
PATH_CASE_MISMATCH | error | links | local-filesystem | The link resolves on case-insensitive filesystems (Windows/macOS) but breaks on Linux and GitHub. |
UNDEFINED_REFERENCE | error | links | local-static | A [text][label] reference has no matching [label]: url definition. |
MALFORMED_LINK | error | links | local-static | The URL contains invalid percent-encoding or NUL characters. |
UNSAFE_LINK_SCHEME | error | security | local-static | A link uses javascript:, file:, vbscript: or another non-web scheme. |
OUTSIDE_REPOSITORY_LINK | warning | links | local-static | A local link resolves outside the scanned root; it is reported and never opened. |
IMAGE_MISSING_ALT | warning | accessibility | local-static | Markdown or HTML image has no alt text (WCAG 1.1.1). |
UNCLOSED_CODE_FENCE | warning | structure | local-static | A fenced code block is never closed, so everything after it renders as code. |
CLI_UNKNOWN_SUBCOMMAND | error | commands | declared-contract | A documented command uses a subcommand absent from the cliContracts you declared. The declaration itself may be stale. |
CLI_UNKNOWN_FLAG | error | commands | declared-contract | A documented command uses a --flag absent from the cliContracts you declared. The declaration itself may be stale. |
PIPE_TO_SHELL | warning | security | local-static | A snippet pipes a download straight into a shell (curl | sh). Never executed by DocSutra; flagged for manual review. |
DESTRUCTIVE_COMMAND | warning | security | local-static | A snippet contains a destructive command (rm -rf, mkfs, dd, chmod -R 777 ...). Never executed; flagged for manual review. |
SECRET_IN_DOCS | error | security | local-static | Text matches a known credential format (GitHub/npm/AWS/Slack/Stripe/Google tokens, private keys). The value is redacted in all reports. |
DUPLICATE_HEADING | info | structure | local-static | Duplicate headings get -1, -2 suffixed anchors, which makes anchor links fragile. |
EMPTY_LINK_TEXT | warning | accessibility | local-static | A link has an empty label, which is unusable for screen-reader users (WCAG 2.4.4). |
HEADING_LEVEL_SKIP | info | accessibility | local-static | A heading jumps more than one level (for example h2 to h4), which weakens document structure. |
INVALID_FILE | error | structure | local-static | The file contains invalid UTF-8 or a NUL byte and was not analysed. |
Evidence types
| Type | Meaning |
|---|---|
local-filesystem | Verified by checking the real file system |
local-static | Derived from the document text alone |
declared-contract | Compared against a contract you declared; only as good as the declaration |
Finding status labels
Findings from a scan are always failed (a reproducible problem). The verification vocabulary used by the skills is: verified, failed, inferred, manual-review, not-run. A timestamp is never a certification.
Stability
Rule IDs are stable. New rules are added in minor versions; behaviour changes to existing rules are listed in the changelog.