# Lint rules Generated by `npm run docs` from `src/lint/rules.ts`: every rule `staleproof lint` knows, its default severity, where it looks, and what a finding says. Change a severity or turn a rule off in `.staleproof.toml` (`[rules] "rule-id" = "off" | "info" | "warning" | "error"`); silence one line with ``. See [Lint](lint.md). | Rule | Severity | Checks | Fix | |---|---|---|---| | [`path-missing`](#path-missing) | error | agent files, READMEs, docs | yes | | [`line-out-of-range`](#line-out-of-range) | warning | agent files, READMEs, docs | no | | [`link-broken`](#link-broken) | error | agent files, READMEs, docs | yes | | [`anchor-missing`](#anchor-missing) | warning | agent files, READMEs, docs | yes | | [`command-missing`](#command-missing) | error | agent files, READMEs, docs | planned | | [`cli-command-unknown`](#cli-command-unknown) | error | agent files, READMEs, docs | planned | | [`cli-flag-unknown`](#cli-flag-unknown) | error | agent files, READMEs, docs | planned | | [`env-unused`](#env-unused) | warning | agent files, READMEs, docs, env files | planned | | [`env-undocumented`](#env-undocumented) | info | env files | planned | | [`symbol-missing`](#symbol-missing) | error | agent files, READMEs, docs | planned | | [`docstring-param-unknown`](#docstring-param-unknown) | error | docstrings | planned | | [`docstring-param-undocumented`](#docstring-param-undocumented) | info | docstrings | planned | | [`example-unknown-keyword`](#example-unknown-keyword) | error | code examples | yes | | [`example-too-many-arguments`](#example-too-many-arguments) | error | code examples | no | | [`example-missing-argument`](#example-missing-argument) | error | code examples | no | | [`example-missing-import`](#example-missing-import) | error | code examples | yes | | [`example-missing-attribute`](#example-missing-attribute) | error | code examples | yes | | [`example-removed`](#example-removed) | error | code examples | yes | ## path-missing A code span names a file or directory of the repository that does not exist. Readers and coding agents open the path, find nothing, and guess. Moved and deleted files are the most common drift in agent instructions. - Default severity: **error** - Checks: agent files, READMEs, docs Reported on: ```text Config lives in `src/settings/defaults.ts`. ``` Message: `src/settings/defaults.ts` does not exist in the repository. ## line-out-of-range A `path:line` reference points past the end of the file. Line references rot as files shrink; the reader lands on the wrong code. - Default severity: **warning** - Checks: agent files, READMEs, docs Reported on: ```text See `src/cli.ts:812`. ``` Message: `src/cli.ts` has 523 lines; line 812 does not exist. ## link-broken A relative link points to a file that does not exist. Broken links in docs and agent files send readers (and agents following them) nowhere. - Default severity: **error** - Checks: agent files, READMEs, docs Reported on: ```text Read the [deploy guide](docs/deploy.md). ``` Message: The link target `docs/deploy.md` does not exist. ## anchor-missing A link to `#anchor` matches no heading in the target page. Renamed headings silently break deep links: the page opens at the top. - Default severity: **warning** - Checks: agent files, READMEs, docs Reported on: ```text See [options](cli.md#global-flags). ``` Message: `cli.md` has no heading `#global-flags`. ## command-missing *Planned: listed so configs that name it stay valid; it reports nothing yet.* A documented command (`npm run x`, `make x`, `just x`, `uv run x`, ...) is not defined by the repository. Setup and contributing steps are run verbatim, by people and by agents; a renamed script fails the first step. - Default severity: **error** - Checks: agent files, READMEs, docs Reported on: ```text Run `npm run lint:docs` before pushing. ``` Message: `lint:docs` is not a script in package.json. ## cli-command-unknown *Planned: listed so configs that name it stay valid; it reports nothing yet.* The repository's own CLI is shown with a subcommand it does not have. CLI docs drift with every rename; users copy the command and get a usage error. - Default severity: **error** - Checks: agent files, READMEs, docs Reported on: ```text `mytool sync --all` ``` Message: `mytool` has no command `sync` (commands: pull, push). ## cli-flag-unknown *Planned: listed so configs that name it stay valid; it reports nothing yet.* The repository's own CLI is shown with an option it does not accept. Removed and renamed flags are a classic source of copy-paste failures. - Default severity: **error** - Checks: agent files, READMEs, docs Reported on: ```text `mytool push --force-all` ``` Message: `mytool push` has no option `--force-all`. ## env-unused *Planned: listed so configs that name it stay valid; it reports nothing yet.* A documented environment variable is never read by the code. Users set it and nothing changes; usually the variable was renamed. - Default severity: **warning** - Checks: agent files, READMEs, docs, env files Reported on: ```text Set `DATABASE_URI` to your database. ``` Message: `DATABASE_URI` is documented but no code reads it. ## env-undocumented *Planned: listed so configs that name it stay valid; it reports nothing yet.* The code reads an environment variable the repository's env file does not list. New settings that never reach `.env.example` are found by reading the source. - Default severity: **info** - Checks: env files Reported on: ```text process.env.REDIS_TLS ``` Message: `REDIS_TLS` is read in src/db.ts but not listed in .env.example. ## symbol-missing *Planned: listed so configs that name it stay valid; it reports nothing yet.* A code span names a member of a repository class or module that does not exist. Prose that names `Client.query_v2` after it was renamed teaches readers and agents an API that is gone. - Default severity: **error** - Checks: agent files, READMEs, docs Reported on: ```text Call `Client.query_v2()`. ``` Message: `Client` has no member `query_v2`. ## docstring-param-unknown *Planned: listed so configs that name it stay valid; it reports nothing yet.* A docstring documents a parameter the function's signature does not have. Docstrings feed IDE hovers, API reference sites and agents; a renamed parameter makes them wrong everywhere. - Default severity: **error** - Checks: docstrings Reported on: ```text Args: timeout_ms: ... ``` Message: `connect` has no parameter `timeout_ms` (parameters: host, port, timeout). ## docstring-param-undocumented *Planned: listed so configs that name it stay valid; it reports nothing yet.* A docstring documents some parameters but not all of them. Partly documented signatures usually mean a parameter was added without its docs. - Default severity: **info** - Checks: docstrings Reported on: ```text def connect(host, port, tls): """Args: host, port""" ``` Message: `connect` documents host, port but not `tls`. ## example-unknown-keyword A docs code example passes a keyword argument the function does not accept. The example raises a TypeError when copied. - Default severity: **error** - Checks: code examples Reported on: ```text Client(hostname="db.local") ``` Message: `Client` has no parameter `hostname`. ## example-too-many-arguments A docs code example passes more positional arguments than the function takes. The example raises a TypeError when copied. - Default severity: **error** - Checks: code examples Reported on: ```text g.query("MATCH (n) RETURN n", {}, 30) ``` Message: `Graph.query` takes at most 2 positional arguments; the example passes 3. ## example-missing-argument A docs code example leaves out a required argument. The example raises a TypeError when copied. - Default severity: **error** - Checks: code examples Reported on: ```text UserList.as_view() ``` Message: `View.as_view` requires `name`. ## example-missing-import A docs code example imports a name the package does not export. The example fails at its first line. - Default severity: **error** - Checks: code examples Reported on: ```text from miniclient import connect ``` Message: `miniclient` has no `connect`. ## example-missing-attribute A docs code example calls an attribute the class or module does not have. The example raises an AttributeError when copied. - Default severity: **error** - Checks: code examples Reported on: ```text client.create_constraint(...) ``` Message: `FalkorDB` has no attribute `create_constraint`. ## example-removed A docs code example calls a symbol that was removed. The example fails when copied. - Default severity: **error** - Checks: code examples Reported on: ```text legacy_connect() ``` Message: `legacy_connect` was removed.