staleless audit

staleless audit

npx staleless audit [path]

Audit runs on a repository that may have no documentation at all, and answers one question: what is absent?

It is not lint

This is the whole distinction:

	lint	audit
Needs nav.yaml and pages	Yes	No
Question	Is this right?	What is missing?
Runs on a stranger’s repository	No	Yes

Free, forever, on every tier

No account, no token, nothing phoned home, no nagging. Files on disk and git log, and nothing else.

That is what makes the number trustworthy as well as free: everything it reports can be checked by hand.

Flags

pathpositional

The codebase to read. Defaults to the current folder.

--content <dir>string

Where the documentation is. --docs is the same flag.

Worked out on its own when not given, and it refuses rather than guess when it cannot tell. A wrong corpus is a wrong score.

--include <path>string

Only read code under this path. For a monorepo, where the whole repository is not the question anybody has.

--fail-on-findingsflag

Answer 1 when it finds something. Off by default: audit reports, it does not gate.

The score

score = round(100 × Σ(weight × covered / total) / Σ(weight))

Four components:

Component	Weight	What it measures
Capabilities	40	Functions and commands a reader came for.
Settings	20	Environment variables and configuration.
API	20	Operations in your specification.
Freshness	20	Pages that have fallen behind the code.

Capabilities carry twice any other component because they are what a reader came for. A documented setting on an undocumented function is a footnote to a page nobody can write.

Three properties of the number

It is a pure function of the counts. Nothing reads a clock, a random number, a network or a file. Two runs over the same tree produce the same number.

It is reconstructible. Every component is printed with what was covered, out of how many, at what weight. Do the arithmetic and disagree with a specific part rather than with the number.

A component with nothing to measure is dropped, and the remaining weights are renormalised. A repository with no OpenAPI file has no API to be wrong about, and scoring it 0 out of 20 would punish a project for not using a format.

The output carries the tool’s version and the formula’s version, so two numbers are only compared when they mean the same thing.

Tip

Run this before you write anything. It is the cheapest way to find out which twenty pages are worth writing first.