Reality

A working, local-first React and Next.js code-review tool. Explore a codebase through its routes and static relationships, compare committed revisions, and drill into portable source evidence. No AI account, database, GitHub integration, or cloud service is required.

Intent → system observations → evidence → source. Findings are review prompts, not proof of runtime behavior or security.

Fastest check

From the root of a React or Next.js repository, run:

# First inventory in the terminal
npx reality-code-review@latest

# Analyze the same folder and start the web UI
npx reality-code-review@latest web

The first command checks the current folder and prints a color-coded ASCII map of the screens, server endpoints, stored data, access checks, outside services, test setup, captured authorship provenance, observed code paths, and practical verification suggestions. reality overview REPORT also prints a plain-English repository story generated entirely from code facts and fixed sentence templates—no AI or LLM is used. The second command creates a temporary report, starts Reality locally, waits until the UI answers successfully, and only then opens it in the default browser. Press Ctrl+C when you are finished. Pass --no-open if you only want the printed browser address. No report command or configuration is required for a repository containing one React or Next.js app. Using @latest prevents an older project-local installation from shadowing the current release.

To install the short command once and reuse it:

# Install in one project, then run through npx.
npm install --save-dev reality-code-review
npx reality

# Or install it for every repository.
npm install --global reality-code-review
reality
reality web

Use reality check /path/to/repository or reality web /path/to/repository for another folder, reality --json for machine-readable inventory output, and reality --help for advanced commands. Color is enabled in interactive terminals; --color forces it and --no-color or the standard NO_COLOR environment variable disables it. A monorepo containing multiple React or Next.js apps still needs --app apps/example so Reality does not guess which application you meant.

The Screens journey view starts with a screen picker and purpose list. Select a screen to see its immediate incoming and outgoing links in three columns. Redirects appear separately, shared menu navigation and uncertain destinations expand on demand, and Show all connections opens the optional whole-app map. Link labels are shown when readable text is available in the source.

Authorship evidence

Reality does not guess whether code “looks AI-written.” It reads optional, snapshot-bound records from .reality/provenance.jsonl and reports AI-ATTESTED, AI-DECLARED, HUMAN-REVIEWED, STALE, INVALID, or UNKNOWN. Run reality authorship for only this inventory; the normal reality check includes it automatically. Missing evidence is always unknown, never proof of human authorship.

Each line of the manifest is one JSON object:

{
  "schemaVersion": "1",
  "id": "run-42:page",
  "kind": "ai-generated",
  "path": "app/page.tsx",
  "startLine": 1,
  "endLine": 48,
  "fileSha256": "FULL_64_CHARACTER_SHA256_OF_THE_FILE",
  "producer": "Codex",
  "model": "MODEL_NAME",
  "createdAt": "2026-09-14T10:00:00.000Z"
}

kind may be ai-generated, ai-assisted, or human-reviewed. The SHA-256 covers the complete UTF-8 file; line numbers identify the claimed range. A matching unsigned record is a declaration. For cryptographic attestation, add keyId and a base64 Ed25519 signature, then place the corresponding PEM public key in .reality.json under provenance.trustedKeys. The signature covers canonical JSON for the record without signature; integrations can import signingPayload from packages/engine/authorship.ts. A trusted signature verifies the provenance claim and file integrity, not the truthfulness of the original producer or the runtime quality of the code.

Start the demo

Requirements: Node.js 22+, npm, and Git. From this directory:

npm ci
npm run demo
npm run dev

Open http://127.0.0.1:3000. The default view loads reports/demo-diff.json. Select the high-priority ownership finding, inspect the before/after evidence, and expand its textual diff. Use Application for routes and observations, Analysis coverage for unresolved boundaries, and Source changes for full embedded file diffs.

The demo generator creates a local Git repository at packages/fixtures/demo with tags demo-base and demo-head. It never installs or executes the fixture. Its two revisions deliberately demonstrate guard removal, an added POST handler and external destination, a database write change, Prisma field changes, a removed Pages API endpoint, a package addition, and business logic changes. This is analysis test data, not a deployable application.

npm run demo is repeatable and preserves an existing demo repository. Source definitions are checked in under packages/fixtures/scenarios.ts; the generated nested repository is ignored by the parent Git repository. Sample JSON reports are included and usable even before generating the demo.

For production-mode local serving:

npm run build
npm run reality -- serve ./reports/demo-diff.json --port 3017

Analyze directly in the web UI

For normal use, start in the repository you want to inspect:

reality web

Reality analyzes the current files automatically and prints the local URL. The controls below are available when you want to connect a different repository or compare revisions.

1. Click Connect repository in the top bar.
2. Paste the absolute path to your local Git repository root and click Connect folder.
3. Select the detected React or Next.js application. A monorepo with multiple apps requires a choice.
4. Choose Current files or Compare revisions. For comparisons, choose the base and head refs and optionally use their merge base.
5. Click Run analysis. Progress appears in the panel; the report opens on Overview automatically.

Overview starts with What this repository factually does: a rule-based explanation of what exists, how entry points are statically connected, what authorship provenance supports, and what remains unproven. The fixed left sidebar opens dedicated pages for Screens, Server Endpoints, Stored Data, Access Checks, Outside Services, and Test Setup. Screens begins with a top-down journey map built from explicit links, router navigation, redirects, and shared Next.js layouts. It distinguishes reachable screens, other starting points, disconnected screens, dynamic links, outside websites, and missing destinations; selecting a node focuses its incoming and outgoing paths. Below it, detected headings, labels, controls, links, and connections become a visual screen guide with a small static interface outline. Server Endpoints shows where each behind-the-scenes action appears to start and how it passes through access checks, stored data, or outside services; an unidentified caller stays explicitly unknown. Technical routes and source are collapsed as supporting evidence. Change findings remain available from the expandable section on Overview.

A Change summary appears above Workspace and Reality Diff. It groups saved findings into review areas, orders them by review priority, and explains what changed, why it may matter, and what to check next. Every observation opens its original finding and evidence. Expand the summary to see all areas; extraction failures and unresolved paths stay visible. Snapshot reports explicitly make no change claims.

The summary uses deterministic templates in packages/engine/summary.ts. It requires no AI key or network access, does not infer feature intent from filenames, and never promotes declared intent to a proven implementation claim. Priority comes from the underlying finding rules; it is potential impact, not a measured runtime effect. Old portable JSON reports work without a schema migration because the summary is derived from their saved findings and entities.

The Workspace tab is a simple GitHub-style source review: changed files on the left, original before/after code on the right, separate line numbers, and additions/deletions marked with both color and symbols. Unchanged sections can be expanded. Snapshot analysis shows captured current source without inventing a prior version. Failed extraction stays labeled unknown. Reality Diff, coverage and portable JSON import/export are still available.

The folder field accepts a path on the machine running Reality. It is not a browser folder upload or a native OS folder-picker dialog. No source is uploaded to GitHub or another service. The connection remains available in the panel during this page session and expires after an hour of inactivity or a server restart. Reopening the panel lets you rerun the analysis; refreshing the page loads the report originally supplied to the server, so export a report to preserve it.

The API requires a same-origin request to a loopback host and an explicit repository connection. Analysis runs in a separate Node process with a two-minute limit and a 32 MiB report limit; only one analysis runs at a time. You can cancel a running analysis. No target scripts execute and no reports are written into the target repository by this flow. For GitHub-hosted code, clone it locally first; OAuth/remote GitHub integration remains outside this update.

To try the complete UI flow, connect packages/fixtures/demo using its absolute path, choose Compare revisions, set base to demo-base and head to demo-head, then run analysis.

Analyze your own website with the CLI

# Eligible tracked and untracked files currently on disk.
npm run reality -- analyze --repo /path/to/repository --app . --out /tmp/current.json

# Exact committed contents; no branch checkout or worktree changes.
npm run reality -- diff --repo /path/to/repository --app . --base main --head HEAD --out /tmp/diff.json

# Merge base of main and HEAD against HEAD.
npm run reality -- diff --repo /path/to/repository --app . --base main --head HEAD --merge-base --out /tmp/pr.json

# Supply the human's declared intent.
npm run reality -- diff --repo /path/to/repository --base main --intent "Add account export" --out /tmp/diff.json

# Review only this saved report; loopback binding is enforced.
npm run reality -- serve /tmp/diff.json

# Print the same current-snapshot overview shown by “What’s built”.
npm run reality -- overview /tmp/diff.json

# Analyze current files and print the overview directly (JSON is also available).
npm run reality -- overview --repo /path/to/repository --app .
npm run --silent reality -- overview /tmp/diff.json --json

# Machine-readable stdout; use npm --silent to suppress npm's own banner.
npm run --silent reality -- diff --repo /path/to/repository --base main --json > /tmp/report.json

Progress is written to stderr. --fail-on high|medium|low|info is optional; exit 2 means that the explicitly requested threshold was met. Exit 1 means fatal input/analysis failure. Exit 0 may still describe a partial analysis; always inspect status, errors, and coverage.

The default CLI raises a coverage warning only for files that failed extraction and unresolved local source imports. Unlinked function calls and unresolved package imports remain available in the detailed coverage report but do not inflate the warning: these are common static-analysis boundaries, not thousands of independent failures.

A dirty working tree is displayed during revision comparison; uncommitted changes are excluded. Working analysis has a content identifier and makes no before/after claims. Use an explicit --app apps/site if a monorepo contains multiple React or Next.js packages. Omit --out for console-only analysis. An explicitly selected output may be inside a target; otherwise Reality does not write to that target.

Configuration

Copy .reality.example.json to the target repository root as .reality.json. Settings are declarative and validated; target config code is never evaluated.

• authorizationGuards: module specifier, exported symbol, and authentication/ownership/authorization kind. Direct import matches with resolved declarations are stronger observations; unresolved imports and name-only matches remain candidates.
• databaseClients: imported Prisma client identities. Member calls are inventoried as read/other or write call sites.
• externalClients: imported SDK identities to inventory alongside fetch. A call site is not proof a network request executed.
• provenance.trustedKeys: explicit Ed25519 public keys used to verify signed authorship records.
• exclude: repository-relative glob patterns. Artifact directories and .env files are excluded by default.
• appDirectory: default scope, overridden by --app.

A diff uses the head snapshot's configuration on both sides, with its provenance and digest recorded. This avoids interpreting a rule configuration edit as a source authorization change. Configuration migration is not itself analyzed.

What is implemented

• Independent TypeScript engine, shared Zod contracts and exported JSON Schema, Node CLI, Next.js/React review UI.
• In-memory TypeScript compiler host; syntax parsing, symbol resolution, separate import and direct-call edges. Relative imports, inline tsconfig paths, and simple local package exports resolve without installed target dependencies.
• Next.js App and Pages Router inventories, plus JSX and object-based React Router declarations, React entry points, dynamic segments, route groups, named/aliased HTTP exports, straightforward Pages method comparisons, middleware/proxy and server/client markers.
• Configured guard calls, arguments and handler conditionals; data and external call observations; a conservative line-oriented Prisma field parser; direct package and likely test inventories.
• Severity and certainty tracked separately. Graph traversal is bounded. Cycles are handled; import-only paths are labeled. File renames reported through Git, URL-based route IDs avoid route-group rename churn.
• Comments/formatting suppressed from semantic findings but retained in diffs. Unclassified source changes remain visible, including alongside classified observations when existing implementation also changed.
• Portable source text, bounded excerpts, snapshot-specific line numbers and textual diffs. Imported reports are size checked and validated. React renders repository content as text.
• Search, category/certainty/route filters, before/after details, affected paths, offline JSON import/export, responsive layout and keyboard-operable native controls.

Coverage boundaries

The static fixture suite exercises React applications with common React Router declarations and declared Next.js 14.2, 15.5 and 16.0 conventions, across TypeScript/TSX and JavaScript/JSX. It does not install or run those target framework versions. Reality's UI is production-built with the exact Next.js version in package-lock.json.

Unsupported or incomplete areas are explicit: inherited tsconfig options, complex conditional package exports, namespace/re-export guard matching, higher-order dispatch, complete control flow and authorization, runtime rewrites/matchers, interception/parallel routing, ORM semantics, and SQL. Prisma support is a strict line-oriented subset, not the Prisma compiler. It inventories model fields and annotations, not migration effects or complete schema validity. Unsupported schema syntax makes comparisons unknown.

For React, Reality inventories literal path values in common <Route> and object-based React Router declarations. Nested relative-path composition, routes assembled dynamically, lazy route-module conventions, and other router libraries are not resolved. When no supported router declaration exists, a detected App component is shown as the root screen candidate rather than inventing additional URLs.

Test discovery does not execute tests or establish coverage. Server-action markers identify candidates, not exposed URLs. Import paths are not runtime traces. Repeated calls use within-symbol ordinals, so reordering identical call names can cause matching noise. Function identities can be ambiguous for repeated nested names or overloads. Rename matching is best effort.

Source reads are bounded to 30,000 repository entries, 512 KiB per file, and 20 MiB per source snapshot; oversized files appear as extraction failures. Reports are limited to 32 MiB. Git reads use argument arrays, validated refs, and no checkout. Symlinks are skipped, and real paths must stay inside the repository. Exported reports intentionally contain source; review them before sharing. There is no automatic secret scanner for credentials embedded in source literals.

Checks and maintenance

npm run typecheck
npm test
npm run build
npm run benchmark
npm run schema
npm run format:check

Tests cover seeded changes, partial parsing, ignored/symlink files, dirty Git snapshots, deterministic findings, CLI exit codes, immutable evidence, hostile text escaping, monorepo/package resolution and stable route identities. npm run benchmark creates and deletes an isolated synthetic Git fixture and writes actual metrics to reports/benchmark.json.

The report's memory metric is the Node process lifetime peak resident set (resourceUsage().maxRSS converted to bytes), not an isolated per-analysis allocation measurement. See docs/HANDOFF.md for checks performed during delivery.

Code map

| Location | Responsibility | | ----------------------------------- | --------------------------------------------------- | | packages/schema/index.ts | Versioned report and configuration contracts | | packages/engine/snapshot.ts | Safe Git and working-directory snapshots | | packages/engine/extract.ts | AST, routes, symbols, calls and observations | | packages/engine/index.ts | Frozen configuration, comparison, evidence, reports | | apps/cli/index.ts | Commands, exports, exit codes and local serving | | apps/web/app/workspace.tsx | Side-by-side source workspace | | apps/web/app/repository-panel.tsx | Repository connection and analysis controls | | apps/web/lib/local-server.ts | Confined local API and analyzer process | | apps/web/app/review.tsx | Review interface and local report import/export | | packages/fixtures/scenarios.ts | Reviewable sample source before/after | | tests/ | Behavioral and portable UI rendering tests |

See docs/REPORT-FORMAT.md for report consumers and docs/HANDOFF.md for delivery notes.

Troubleshooting

• No React or Next.js application found: ensure the chosen snapshot declares react or next in its package metadata and use a repository-relative --app.
• Missing ref: fetch or create the desired revision yourself. Reality never fetches target code automatically.
• Unresolved aliases: add supported inline path mappings; inherited configs and executable Next config are not loaded.
• Partial report: review failed files and diagnostics. Do not interpret missing entities as removals where extraction failed.
• Port in use: run reality web --port 3017; advanced report serving also accepts reality serve REPORT --port 3017.
• import type parse failure in Reality's own app/layout.tsx: update to [email protected] or newer. Earlier global packages could incorrectly exclude their own TSX interface from Next's transform.
• No default report: run npm run demo or use Open a report. A JSON report can be moved independently of its repository.
• No findings: this means no changes were detected by enabled rules in analyzed scope, not that the code is safe or equivalent.

Implementation references: Next.js route handlers, Next.js proxy convention, and the TypeScript compiler API.

What has been built

Choose What’s built in the full sidebar or Simple view to review the current analyzed snapshot, even for a brand-new app without a comparison. Its visual map connects route entry points to access checks, database calls, and outside requests when a bounded direct-call path was observed. Six selectable tiles describe screens, server endpoints, stored data, access checks, outside services, and test setup. Each observation expands to its saved source excerpt and snapshot reference. Each category suggests a manual verification step. Snapshot reports open this overview by default in Simple view; comparisons also offer What changed.

Counts describe detected code observations in the selected app scope, not completed product features. Map lines are static direct-call paths, not proof of runtime execution. The map does not invent relationships, infer AI authorship from code style, or claim tests passed. It displays authorship only when provenance was captured, keeping unknown, declared, attested, and human-reviewed states distinct. Missing observations and source, coverage gaps, and stated intent remain explicitly distinguished from verified functionality. reality overview exposes the same grouping, verification guidance, source references, and observed connections in terminal or JSON form.