README Reality Check

README Reality Check is a deterministic, local-first static analyzer for JavaScript and TypeScript repositories. It verifies setup, installation, and run instructions in README files against facts that are present in the repository.

It is not a general README linter or documentation generator. It only reports claims it can verify with repository evidence, and skips ambiguous shell syntax rather than guessing.

What it checks

Rule	Finding
RRC001	A documented package script does not exist in the resolved package.json.
RRC002	A documented local path does not exist.
RRC003	A documented package manager does not match the repository's sole lockfile.
RRC004	A documented .env.example or .env.sample source file does not exist.

For example, if a README contains npm run dev but package.json has no dev script:

README.md:3 ERROR RRC001 Script "dev" is not defined in package.json.
  evidence: package.json — Available scripts: build
  suggestion: Add the "dev" script or update the README command.

1 finding(s): 1 error(s), 0 warning(s), 0 notice(s).

CLI

Install the CLI locally to pin the version used by your project:

npm install --save-dev readme-reality
npx readme-reality check

You can also run it without a global installation:

npx readme-reality check

This documentation becomes active with npm release 0.1.2.

GitHub Action

- uses: givoxxs/readme-reality@v0
  with:
    root: .
    fail-on: error

The Action creates file annotations and a Markdown Job Summary, sets errors and warnings outputs, and needs only contents: read permission.

Inputs

Input	Default	Description
root	.	Repository-relative directory to analyze.
config	—	Path to .readme-reality.yml, relative to root.
fail-on	error	error, warning, or never.

Configuration

Use an optional .readme-reality.yml:

version: 1
readmes:
  include: [README.md, apps/*/README.md, packages/*/README.md]
  exclude: []
rules:
  script-exists: { enabled: true, severity: error }
  path-exists: { enabled: true, severity: error }
  package-manager: { enabled: true, severity: warning, allowed: [] }
  env-template: { enabled: true, severity: error }
failOn: error

Limitations

• The MVP targets JavaScript and TypeScript repositories only.
• README commands are never executed.
• The shell parser supports only a conservative subset of shell syntax.
• Ambiguous syntax, variables, substitutions, URLs, globs, home-relative paths, and paths outside the repository are skipped.
• RRC003 skips repositories with multiple lockfiles.

Security model

Repository and README content are untrusted input. Analysis uses local filesystem reads only: it does not use an LLM, make network requests, load scanned project code, inspect secrets, or run README commands. Paths are normalized, config and scanned symlinks are constrained to the repository root, and the Action is intended for pull_request, not pull_request_target.

See SECURITY.md for the threat model.

Development

npm ci
npm run lint
npm run typecheck
npm test
npm run build

License

MIT © 2026 Phan Van Toan.