Rule catalog

db

reliability

security

browser

egress

go

http

perf

react

redis

sql

Native analyses

Whole-graph/whole-repo analyses. Their ids join the same RuleConfig enable/severity/suppression surface as DSL rules. Each id is registered by its owning crate's own register_native_analyses — the kernel (crates/core) itself registers none, staying rule-vocabulary-free. Five crates register between them, each owning one subject: rules/native/rules-graph the dependency/dead-code graph rules plus the call-graph purity audit, rules/native/rules-http the single-tree HTTP/route rules, rules/native/rules-cross-layer the cross-layer/* multi-tree join rules, rules/native/rules-schema the schema rules, and crates/metrics the score computations. Which ids each owns is the table's answer, not this paragraph's — the roster is the register_native_analyses list in each of those crates, and the table below is the same set row by row. No id list is repeated here on purpose: the hand-written one this sentence replaced had drifted one id short of the table it introduces, and a list that must be re-counted by hand is a census in disguise. Two shapes the table does not spell out on its own: schema-structural/schema-usage are FAMILY gates over the 12 schema/* per-issue ids they report under — disabling a family switches its whole pass off while each schema/* id disables exactly the rule it names, both are honored, and every finding's message states both; and the crates/metrics ids are score computations, not findings-producing rules, that merely ride the same toggle/gating surface. Those metrics ids carry no severity at all — not because of how they register (every native id goes through the same stub), but because severity grades a finding and these emit none. The "Default severity" column therefore reads n/a for them rather than inventing a level for output that is never a finding. Each row says instead whether any shipped surface carries what it produces. zzop_engine::register_all_native composes the five.

The cross-layer/* ids are the multi-tree exception: they run over zzop_engine::analyze_trees's joined CrossLayerResult (every other row here runs per-tree), exposed as crossLayerFindings alongside crossLayer in analyzeTrees's output. None of them honor an inline suppression marker — they are disable-only: rules: { "<id>": "off" } in config, or disabledRules for embedders.

Not yet implemented: architecture rules (layer-violations, feature-envy — no crate is scaffolded for them yet), cognitive/nested-loop complexity scoring, precise taint-flow dataflow (today's security/taint-flow is a documented coarse v1 co-occurrence check), an auth-state-machine analysis, additional cross-file HTTP graph checks (API churn, frontend/backend spec drift), a JSX/React structural rule pack, and env/i18n sync checks — each needs either a whole-graph join the DSL can't express or real AST/JSX shape. (Raw-Worker route extraction — manual url.pathname dispatch in framework-less Workers/Node servers — shipped as the parser's pathname-dispatch provide vocabulary.)

Matchers

Every DSL rule declares exactly one matcher shape, drawn from the table below. Full field-by-field semantics are in the DSL reference; this is the short version.

All but one operate on a single file's SourceFile slice in isolation and cannot see a second file's content; io-scan is the exception, evaluating whole-tree over IO facts already composed across files. A rule's inline suppress marker is DERIVED from its id — zzop-<rule id>-ok, never authored as a field — and applies to the findings of every matcher except symbol-scan: a // zzop-<rule id>-ok comment on the finding's own line, or the single line directly above it, suppresses it. (io-scan, call-scan and literal-scan are multi-language by construction, so they honor a # comment leader as well as //.) The marker carries no pack prefix (security/hardcoded-secret → // zzop-hardcoded-secret-ok). symbol-scan findings have no source-line concept to anchor a suppress comment against, so they carry no inline marker. See dsl-reference.md in the repo for the full matcher field tables.

Write your own pack

A pack is one <id>.json file loaded from a configured packs directory — no first-party/third-party distinction exists at the interpreter level. Two spellings name that directory and they are not interchangeable: packs.extraDirs in a zzop.config.jsonc, or packsDir on an embedder's request object. A zzop/rules/ directory is also picked up without packs.extraDirs naming it. Here's a small line-scan rule, flagging a hardcoded debug header value that should come from config/env instead:

{
  "id": "debug-headers",
  "framework": "any",
  "schema_version": 1,
  "rules": [
    {
      "id": "hardcoded-debug-token",
      "severity": "warning",
      "message": "X-Debug-Token header set to a string literal — this bypasses per-environment config and risks shipping a real token. Read it from env/config instead.",
      "matcher": {
        "type": "line-scan",
        "file_pattern": "(?i)\\.(ts|tsx)$",
        "require_file": "X-Debug-Token",
        "skip_comment_lines": true,
        "line_pattern": "[\"']X-Debug-Token[\"']\\s*:\\s*[\"'][^\"'`]+[\"']",
        "snippet_max": 160
      }
    }
  ]
}

Both spellings accept either one directory or an array of directories. Each is loaded independently and then merged by pack id: if the same id shows up in more than one directory, the pack from the later directory in the list replaces the earlier one whole (not a per-rule merge) — this is how a caller adds packs alongside the bundled ones, or overrides a bundled pack outright, without forking the engine.

The message writes the cause and the fix, and stops there. Notice it names no suppress marker and no way to disable the rule: the engine appends both sentences to every finding at runtime — the marker (zzop-<id>-ok, derived from the id, spelled with the comment leaders that matcher kind actually honours) and the rules: { "<pack>/<rule>": "off" } disable hint. Writing either one yourself renders it twice, and a hand-written marker sentence goes stale the moment the matcher kind changes, because it names leaders the engine no longer honours.

Not every detection fits the matchers above. Reach for a native rule instead when the check needs declaration→use tracking (an identifier declared but never read), a cross-file join (resolving a constant or route handler defined in another file), call-graph BFS ("handler X, or something it calls transitively, does Y"), or real AST/JSX shape rather than text co-occurrence — cyclomatic/cognitive complexity and JSX-structural checks have no honest regex-over-lines encoding.