staleless impact

staleless impact

npx staleless impact --changed src/api/teams.ts,src/api/members.ts

A diff names files. Nobody can turn a list of files into a list of pages by hand on a codebase of any size. This does it.

Flags

--changed <a,b>string

The files this pull request touched. Comma-separated, or one per line.

--repo <dir>string

The code to read. Defaults to the current folder.

--content <dir>string

The documentation to compare it against. Defaults to the same folder.

--advisoryflag

Report everything and never fail.

--jsonflag

Machine-readable output, for a pull request comment.

What it matches on

Two rules, and the difference between them is the precision story:

Matched anywhere on a page. A route path such as /teams/{id}/invite and an environment variable name such as DATABASE_URL. Both are distinctive enough that a text hit means what it looks like.

Matched narrowly. Other names, because a common English word that happens to be a function name would match every page.

There are no confidence scores. The rule either matched a name or it did not, and a number would only look like judgement.

The answer

src/api/teams.ts changed.
  docs/pages/api/teams.md:42     /teams/{id}/invite
  docs/pages/guides/members.md:8 /teams/{id}/invite

Each hit carries the page, the line, and the text that matched, so a reviewer can open the exact place and disagree with the rule.

In GitHub Actions

- name: Which pages describe what changed
  run: |
    FILES=$(git diff --name-only origin/${{ github.base_ref }}... | paste -sd,)
    npx staleless impact --changed "$FILES" --advisory

Use --advisory at first. Impact tells a reviewer where to look; it should not block a code change until your team wants it to.

Why this shipped before the rest

Pulse can mark a page for review when the code it describes changes, and that needs the history of your code repository, which is a different repository from the content one.

Running impact in CI on every pull request answers the same question today, which is why it exists as a command first.

Exit codes

Code	Meaning
0	No page describes any of those files.
1	Pages found.
2	Could not run.