repro-surgeon 0.1.0

package/dist/transforms.js

@@ -0,0 +1,188 @@
+import ts from 'typescript';
+import { isLegalPath } from "./protection.js";
+import { matchesPath } from "./snapshot.js";
+const SOURCE_EXTENSIONS = /\.(?:[cm]?[jt]sx?)$/i;
+const PROTECTED_BASENAME = /^(?:package(?:-lock)?\.json|npm-shrinkwrap\.json|yarn\.lock|pnpm-lock\.yaml|bun\.lockb?)$/i;
+function compareText(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function isPreserved(path, config) {
+    return matchesPath(path, config.preserve);
+}
+function isProtectedPath(path, config) {
+    const basename = path.slice(path.lastIndexOf('/') + 1);
+    return PROTECTED_BASENAME.test(basename) || isLegalPath(path) || isPreserved(path, config);
+}
+function scriptKind(path) {
+    if (/\.tsx$/i.test(path))
+        return ts.ScriptKind.TSX;
+    if (/\.jsx$/i.test(path))
+        return ts.ScriptKind.JSX;
+    if (/\.(?:mjs|cjs|js)$/i.test(path))
+        return ts.ScriptKind.JS;
+    return ts.ScriptKind.TS;
+}
+function diagnostics(sourceFile) {
+    return sourceFile.parseDiagnostics;
+}
+function parseSource(path, source) {
+    const parsed = ts.createSourceFile(path, source, ts.ScriptTarget.Latest, true, scriptKind(path));
+    return diagnostics(parsed).length === 0 ? parsed : null;
+}
+function listItemRange(items, index, sourceFile) {
+    const item = items[index];
+    if (!item)
+        throw new Error('list item index is out of bounds');
+    if (items.length === 1)
+        return { start: item.getStart(sourceFile), end: item.end, label: 'list item' };
+    const next = items[index + 1];
+    if (next)
+        return { start: item.getStart(sourceFile), end: next.getStart(sourceFile), label: 'list item' };
+    const previous = items[index - 1];
+    if (!previous)
+        throw new Error('missing previous list item');
+    return { start: previous.end, end: item.end, label: 'list item' };
+}
+function isDirective(statement) {
+    return ts.isExpressionStatement(statement) && ts.isStringLiteral(statement.expression);
+}
+function statementRanges(statements, label) {
+    const ranges = [];
+    let inPrologue = true;
+    for (const statement of statements) {
+        if (inPrologue && isDirective(statement))
+            continue;
+        inPrologue = false;
+        ranges.push({
+            start: statement.getStart(),
+            end: statement.end,
+            label: `${label} ${ts.SyntaxKind[statement.kind]}`,
+        });
+    }
+    return ranges;
+}
+function buildCandidates(path, original, ranges, kind, valid) {
+    const seen = new Set();
+    const candidates = [];
+    const firstLineEnd = original.startsWith('#!') ? original.indexOf('\n') + 1 : 0;
+    const legalComments = [];
+    const scanner = ts.createScanner(ts.ScriptTarget.Latest, false, ts.LanguageVariant.Standard, original);
+    for (let token = scanner.scan(); token !== ts.SyntaxKind.EndOfFileToken; token = scanner.scan()) {
+        if (token !== ts.SyntaxKind.SingleLineCommentTrivia && token !== ts.SyntaxKind.MultiLineCommentTrivia)
+            continue;
+        const text = scanner.getTokenText();
+        if (text.startsWith('/*!') || /@license|@preserve|copyright|SPDX-License-Identifier|SPDX-FileCopyrightText|permission is hereby granted/i.test(text)) {
+            legalComments.push({ start: scanner.getTokenPos(), end: scanner.getTextPos() });
+        }
+    }
+    for (const range of ranges) {
+        const start = firstLineEnd > 0 && range.start < firstLineEnd ? firstLineEnd : range.start;
+        if (start < 0 || range.end <= start || range.end > original.length)
+            continue;
+        if (legalComments.some(comment => start < comment.end && range.end > comment.start))
+            continue;
+        const content = original.slice(0, start) + original.slice(range.end);
+        if (content === original || !valid(content) || seen.has(content))
+            continue;
+        seen.add(content);
+        candidates.push({
+            id: `${kind}:${path}:${start}:${range.end}:${range.label}`,
+            kind,
+            description: `Remove ${range.label} from ${path}`,
+            paths: [path],
+            edits: [{ path, content: Buffer.from(content) }],
+            start,
+            end: range.end,
+        });
+    }
+    candidates.sort((left, right) => compareText(left.paths[0], right.paths[0]) ||
+        left.start - right.start ||
+        left.end - right.end ||
+        compareText(left.description, right.description));
+    return candidates.map(({ start: _start, end: _end, ...candidate }) => candidate);
+}
+export function syntaxCandidates(snapshot, config) {
+    const all = [];
+    for (const [path, entry] of [...snapshot.entries()].sort(([a], [b]) => compareText(a, b))) {
+        if (!SOURCE_EXTENSIONS.test(path) || isProtectedPath(path, config))
+            continue;
+        const source = entry.content.toString('utf8');
+        const sourceFile = parseSource(path, source);
+        if (!sourceFile)
+            continue;
+        const ranges = statementRanges(sourceFile.statements, 'top-level statement');
+        const visit = (node) => {
+            if (ts.isImportDeclaration(node) && node.importClause) {
+                const bindings = node.importClause.namedBindings;
+                if (bindings && ts.isNamedImports(bindings)) {
+                    bindings.elements.forEach((element, index) => {
+                        const range = listItemRange(bindings.elements, index, sourceFile);
+                        ranges.push({ ...range, label: `import specifier ${element.name.text}` });
+                    });
+                }
+            }
+            if (ts.isVariableStatement(node)) {
+                const declarations = node.declarationList.declarations;
+                declarations.forEach((_declaration, index) => {
+                    const range = declarations.length === 1
+                        ? { start: node.getStart(), end: node.end, label: 'variable declaration' }
+                        : { ...listItemRange(declarations, index, sourceFile), label: 'variable declaration' };
+                    ranges.push(range);
+                });
+            }
+            if (ts.isBlock(node))
+                ranges.push(...statementRanges(node.statements, 'statement'));
+            if (ts.isObjectLiteralExpression(node)) {
+                node.properties.forEach((property, index) => {
+                    const range = listItemRange(node.properties, index, sourceFile);
+                    const name = property.name && ts.isIdentifier(property.name) ? ` ${property.name.text}` : '';
+                    ranges.push({ ...range, label: `object member${name}` });
+                });
+            }
+            if (ts.isJsxElement(node) || ts.isJsxFragment(node)) {
+                node.children.forEach((child) => {
+                    if (ts.isJsxText(child) && child.getText(sourceFile).trim() === '')
+                        return;
+                    ranges.push({ start: child.getFullStart(), end: child.end, label: 'JSX child' });
+                });
+            }
+            ts.forEachChild(node, visit);
+        };
+        visit(sourceFile);
+        all.push(...buildCandidates(path, source, ranges, 'syntax', (candidate) => parseSource(path, candidate) !== null));
+    }
+    return all.sort((left, right) => compareText(left.id, right.id));
+}
+export function jsonCandidates(snapshot, config) {
+    const all = [];
+    for (const [path, entry] of [...snapshot.entries()].sort(([a], [b]) => compareText(a, b))) {
+        if (!/\.jsonc?$/i.test(path) || isProtectedPath(path, config))
+            continue;
+        const source = entry.content.toString('utf8');
+        if (ts.parseConfigFileTextToJson(path, source).error)
+            continue;
+        const sourceFile = ts.parseJsonText(path, source);
+        if (diagnostics(sourceFile).length > 0)
+            continue;
+        const ranges = [];
+        const visit = (node) => {
+            if (ts.isObjectLiteralExpression(node)) {
+                node.properties.forEach((property, index) => {
+                    const range = listItemRange(node.properties, index, sourceFile);
+                    const key = property.name && ts.isStringLiteral(property.name) ? ` ${property.name.text}` : '';
+                    ranges.push({ ...range, label: `JSON member${key}` });
+                });
+            }
+            else if (ts.isArrayLiteralExpression(node)) {
+                node.elements.forEach((_element, index) => {
+                    ranges.push({ ...listItemRange(node.elements, index, sourceFile), label: 'JSON array item' });
+                });
+            }
+            ts.forEachChild(node, visit);
+        };
+        visit(sourceFile);
+        all.push(...buildCandidates(path, source, ranges, 'json', candidate => !ts.parseConfigFileTextToJson(path, candidate).error));
+    }
+    return all.sort((left, right) => compareText(left.id, right.id));
+}
+//# sourceMappingURL=transforms.js.map

package/dist/transforms.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transforms.js","sourceRoot":"","sources":["../src/transforms.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,207 @@
+export interface FileEntry {
+    content: Buffer;
+    mode: number;
+}
+export type Snapshot = Map<string, FileEntry>;
+export interface Oracle {
+    exitCode: number;
+    allOf: string[];
+    noneOf: string[];
+}
+export interface Config {
+    version: 1;
+    name: string;
+    command: string[];
+    oracle: Oracle;
+    adapter: 'auto' | 'next' | 'generic';
+    budget: {
+        maxEvaluations: number;
+        maxSeconds: number;
+    };
+    runs: {
+        baseline: number;
+        candidate: number;
+        final: number;
+    };
+    execution: {
+        timeoutMs: number;
+        maxOutputBytes: number;
+        installTimeoutMs: number;
+        allowInstallScripts: boolean;
+        env: string[];
+    };
+    reduce: {
+        files: boolean;
+        syntax: boolean;
+        json: boolean;
+        dependencies: boolean;
+    };
+    include: string[];
+    exclude: string[];
+    preserve: string[];
+}
+export interface RunOptions {
+    cwd: string;
+    timeoutMs: number;
+    maxOutputBytes: number;
+    env?: Record<string, string>;
+    signal?: AbortSignal;
+}
+export interface CommandResult {
+    exitCode: number | null;
+    signal: string | null;
+    timedOut: boolean;
+    aborted: boolean;
+    outputLimitExceeded: boolean;
+    stdout: string;
+    stderr: string;
+    durationMs: number;
+    error?: string;
+}
+export type Outcome = 'reproduced' | 'absent' | 'invalid';
+export interface OracleResult {
+    status: Outcome;
+    reason: string;
+    matched: string[];
+    missing: string[];
+    forbidden: string[];
+    diagnostics: string[];
+}
+export interface Observation {
+    execution: CommandResult;
+    oracle: OracleResult;
+}
+export interface FileEdit {
+    path: string;
+    content: Buffer | null;
+}
+export type TransformKind = 'files' | 'syntax' | 'json' | 'dependencies';
+export interface Transformation {
+    id: string;
+    kind: TransformKind;
+    description: string;
+    paths: string[];
+    edits: FileEdit[];
+}
+export interface ProjectGraph {
+    imports: Record<string, string[]>;
+    external: Record<string, string[]>;
+    unresolved: Record<string, string[]>;
+}
+export interface AdapterInfo {
+    name: 'next' | 'generic';
+    version: string | null;
+    router: 'app' | 'pages' | 'mixed' | 'none';
+    entrypoints: string[];
+    protectedPaths: string[];
+    warnings: string[];
+}
+export interface Metrics {
+    files: number;
+    bytes: number;
+    sourceBytes: number;
+    dependencies: number;
+}
+export interface ReviewFinding {
+    path: string;
+    kind: string;
+    message: string;
+}
+export interface Inventory {
+    snapshot: Snapshot;
+    excluded: {
+        path: string;
+        reason: string;
+    }[];
+    warnings: string[];
+}
+export interface Trial {
+    index: number;
+    candidateHash: string;
+    kind: TransformKind;
+    description: string;
+    paths: string[];
+    status: Outcome;
+    accepted: boolean;
+    reason: string;
+    durationMs: number;
+    before: Metrics;
+    after: Metrics;
+    confirmations: number;
+    diagnostics: string[];
+}
+export interface RuntimeInfo {
+    node: string;
+    npm: string;
+    platform: string;
+    arch: string;
+    tool: string;
+}
+export interface Verification {
+    status: 'pending' | 'verified' | 'failed';
+    runs: number;
+    reason: string;
+    snapshotHash: string;
+    environment: 'fresh-directory';
+}
+export interface RunState {
+    version: 1;
+    id: string;
+    sourceRoot: string;
+    createdAt: string;
+    updatedAt: string;
+    config: Config;
+    configHash: string;
+    runtime: RuntimeInfo;
+    originalHash: string;
+    bestHash: string;
+    initial: Metrics;
+    current: Metrics;
+    adapter: AdapterInfo;
+    status: 'calibrating' | 'reducing' | 'paused' | 'verifying' | 'complete' | 'failed';
+    stopReason: string;
+    evaluations: number;
+    elapsedMs: number;
+    baseline: OracleResult[];
+    trials: Trial[];
+    rejectedHashes: string[];
+    excluded: {
+        path: string;
+        reason: string;
+    }[];
+    warnings: string[];
+    verification: Verification;
+    reviewFindings: ReviewFinding[];
+}
+export interface RunReport {
+    version: 1;
+    id: string;
+    name: string;
+    createdAt: string;
+    status: RunState['status'];
+    stopReason: string;
+    command: string[];
+    oracle: Oracle;
+    runtime: RuntimeInfo;
+    adapter: AdapterInfo;
+    initial: Metrics;
+    current: Metrics;
+    evaluations: number;
+    elapsedMs: number;
+    baseline: {
+        completed: number;
+        required: number;
+    };
+    trials: Trial[];
+    files: {
+        path: string;
+        bytes: number;
+    }[];
+    excluded: {
+        path: string;
+        reason: string;
+    }[];
+    warnings: string[];
+    verification: Verification;
+    reviewFindings: ReviewFinding[];
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/docs/architecture.md

@@ -0,0 +1,91 @@
+# Architecture
+
+Repro Surgeon turns a failing application into a smaller source project that another developer can install and run. Every accepted change must preserve the configured failure oracle. The final export is checked again from a fresh directory and dependency installation.
+
+## Contract
+
+The input is an owned, single-package npm project, an argv command, an exact expected exit code, and distinctive required output fragments. Optional forbidden fragments rule out known competing failures. A successful reduction is the smallest snapshot found within the run's budget that repeatedly matches this contract. This is evidence about the configured observation, not a proof that two failures have the same semantic root cause.
+
+The default release targets deterministic command and Next.js build failures on Linux and macOS with Node.js 22.18 or newer and npm 10 or newer. Framework support is based on executed cases, not inference from a dependency name. Browser interactions and service-backed failures can be authored as finite commands, but automatic recording, server management, monorepos and other package managers require separate adapters and validation.
+
+## Lifecycle
+
+1. `init` writes a versioned JSON configuration from an explicit command and target text. It never guesses the user's failure silently.
+2. `doctor` inventories a project, identifies its adapter, and reports unsupported dependencies or environmental requirements without executing project code.
+3. `reduce` snapshots the input into a new run directory, provisions dependencies, and calibrates three uncached baseline runs.
+4. Hierarchical file reductions and syntax/data transformations are evaluated in disposable working directories. Two uncached confirmations are required before a candidate becomes the accepted state.
+5. Each decision is checkpointed atomically. `resume` validates the saved state and runtime, recalibrates the accepted snapshot, and continues with the remaining or explicitly expanded budget.
+6. The exporter writes the reduced source, its lockfile, reproduction instructions, an independent assertion runner, and an evidence manifest. It scans retained material for review findings.
+7. The exact export is copied to a fresh directory, installed with `npm ci`, and checked three times without reduction caches. Only then can the result say it is verified.
+8. Offline HTML and JSON reports expose real metrics, accepted changes, rejected/invalid trials, remaining files, failure checks, verification and review findings.
+
+## Components
+
+| Module | Responsibility |
+|---|---|
+| `config.ts` | Parse, normalize and validate versioned user configuration |
+| `runner.ts` | Shell-free bounded child execution, environment construction, cancellation and process-tree cleanup |
+| `oracle.ts` | Classify executions and normalize diagnostic observations |
+| `snapshot.ts` | Safe inventory, immutable content, hashing, materialization and integrity checks |
+| `transforms.ts` | Deterministic syntax and JSON candidates with narrow source edits |
+| `graph.ts` | Static import graph and Next.js structure as search hints |
+| `dependencies.ts` | npm lock integrity, installation and dependency-removal candidates |
+| `engine.ts` | Baselines, hierarchical reduction, budgets, confirmations and events |
+| `state.ts` | Atomic checkpoints, snapshot storage, resume compatibility and run locking |
+| `export.ts` | Standalone reproduction, independent verifier and clean verification |
+| `report.ts` | Safe, accessible offline HTML and machine-readable evidence |
+| `cli.ts` | Commands, progress, errors and exit semantics |
+
+These are modules in one package. A package network would add release coordination without improving the first user's workflow.
+
+## Execution and failure identity
+
+The oracle has three outcomes. `reproduced` means normal termination with the exact expected exit and all required fragments, with no forbidden fragments. `absent` means a normal execution did not match. `invalid` means the execution could not establish an observation: failed setup, spawn error, signal, timeout, cancellation or output overflow. Invalid outcomes can never preserve a candidate.
+
+Required positive fragments cannot be empty. Broad phrases such as “failed” should be replaced with a diagnostic identifier, offending symbol, location or other distinctive signal. A fixed control and a deliberately different failure are the strongest checks of an oracle. The tool displays its exact predicate and diagnostic observations; it does not silently strengthen or weaken them. A missing-import diagnostic may itself be the target, so the engine cannot blanket-ban that error family.
+
+Baseline and final checks require three runs; acceptance requires two. Repetition is not a statistical guarantee of determinism. A failed calibration stops the run. Candidate caches skip previously rejected snapshots; they never supply confirmation or final verification.
+
+Commands are argv arrays and use no implicit shell. The working directory, temporary home, installation configuration and build outputs are owned by the run. The environment inherits only operating-system essentials plus explicitly named variables. Logs are bounded and private to the run; report data contains summaries, not raw source/log dumps. Terminal control sequences are removed from displayed excerpts.
+
+Local execution is not a security sandbox. Only run projects and commands you trust. npm installation scripts are disabled by default and can be enabled explicitly when required. Network access is needed for uncached packages and may also be used by the supplied command. Repro Surgeon has no telemetry or source-upload service.
+
+## Source and dependency integrity
+
+The original project is read into an immutable snapshot. Git history, installed dependencies, generated output, environment files and known credential files are excluded. Ordinary untracked files are included; ignore rules and explicit overrides are visible in the inventory. Symlinks are rejected or excluded without following them. Export and state paths must not overlap the source. No command executes inside the original project.
+
+Package manifests, lockfiles, licenses and notices are protected from generic file deletion. The package manager owns dependency reconciliation. Source candidates share only a tool-provisioned dependency installation for the same manifest/lock hash; they never link to the user's `node_modules`. Each candidate restores accepted source and clears build artifacts. Dependency changes use a new installation and cannot resolve removed dependencies from a stale tree. Retained package versions and integrity fields must not drift during lock reconciliation.
+
+Projects with workspace, local file/link dependencies or private registry requirements are diagnosed explicitly. A portable export cannot quietly depend on the original checkout or developer credentials. Required environment variable names are reported; values are not copied into exported configuration.
+
+## Search
+
+The objective is lower source bytes, then fewer files; dependency bytes and counts are reported separately. The scheduler is deterministic and serial by default. It starts with hierarchical file partitions and complements so it can remove mutually dependent irrelevant groups. It then tries syntax declarations/statements/import members/JSX children and JSON members/array items. Static imports, aliases and framework conventions prioritize candidates; only execution decides acceptance.
+
+Range-based edits preserve unrelated formatting. Directives, shebangs, framework entry files, licenses and user-pinned paths receive conservative handling. Parseable source must remain parseable after structural edits. Files that already contain syntax errors can still be removed but are not structurally rewritten. JSON fixtures are reduced without changing package metadata. Dependency trials run after broad source reductions. Every accepted change restarts applicable search passes because new opportunities may appear.
+
+All trials have stable content hashes. A checkpoint records config, runtime, baseline, current accepted snapshot, attempts, decisions, metrics and accumulated budget. Resuming from a valid accepted snapshot may repeat proposal enumeration, but cached rejected hashes and deterministic ordering prevent repeated execution. Interrupted trials are never marked accepted. Corrupted checkpoints and incompatible runtime/configuration are refused.
+
+## Export and report
+
+The export preserves the source license and notices and places generated metadata under a reserved `.repro/` directory to avoid altering application scripts. The original command still fails as expected. A standalone verifier returns success only when that expected failure matches. It must work without installing Repro Surgeon.
+
+All final source bytes, including generated verification metadata, are copied into a new validation directory before fresh installation and repeated checks. The checkpoint records the runtime and package manager. Its verification record stores the outcome, completed check count, reason, export snapshot hash and fresh-directory method; individual final command observations are not persisted. A clean directory on the same host is described exactly that way; container results are identified separately.
+
+Review findings include likely secrets, absolute local paths, private package references and retained files. Findings are prompts for inspection, never privacy certification. The CLI never publishes a reproduction. The report is self-contained, escapes every untrusted string, uses no network resources, and labels accepted, rejected and invalid trials in text as well as color.
+
+## Release acceptance
+
+- Each CLI command has meaningful success and failure-path coverage.
+- Oracle controls reject a different error, timeout, signal and missing executable.
+- Source hashes remain unchanged after success, failure and cancellation.
+- File grouping, JavaScript/TypeScript/JSX, JSON, dependency integrity, checkpoint corruption, resume and export have executed regression cases.
+- Packaged installation runs the complete example and independent exported verifier.
+- Pinned App Router and Pages Router examples run through the real Next.js build command.
+- Three independently chosen public bug cases are recorded with provenance, exact commands, controls, results and limitations. Seeded cases and reconstructions are labeled.
+- CI executes the claimed runtime/OS matrix. Independent review checks correctness and the report's accessibility and rendering.
+- README, license, contributing guide, security policy, issue templates, changelog and release artifacts are present and accurate. No fabricated benchmark, endorsement or adoption claim.
+
+## Prior art
+
+The search builds on [delta debugging](https://www.st.cs.uni-saarland.de/papers/tse2002/). [treereduce](https://github.com/langston-barrett/treereduce) already supplies syntax-aware property-preserving reduction. [Replay](https://www.replay.io/debugging) investigates recorded execution. Repro Surgeon's intended contribution is a complete local application-source workflow with explicit failure checks and independently verified exports. Comparative superiority remains an empirical question.

package/docs/configuration.md

@@ -0,0 +1,73 @@
+# Configuration
+
+`repro-surgeon.json` is strict JSON. Unknown fields and invalid values fail early. `command` and `oracle` are required; everything else has a default.
+
+```json
+{
+  "version": 1,
+  "name": "My reproduction",
+  "command": ["npm", "run", "build"],
+  "oracle": {
+    "exitCode": 1,
+    "allOf": ["a distinctive diagnostic"],
+    "noneOf": []
+  },
+  "adapter": "auto",
+  "budget": { "maxEvaluations": 200, "maxSeconds": 900 },
+  "runs": { "baseline": 3, "candidate": 2, "final": 3 },
+  "execution": {
+    "timeoutMs": 60000,
+    "maxOutputBytes": 1048576,
+    "installTimeoutMs": 120000,
+    "allowInstallScripts": false,
+    "env": []
+  },
+  "reduce": { "files": true, "syntax": true, "json": true, "dependencies": true },
+  "include": [],
+  "exclude": [],
+  "preserve": []
+}
+```
+
+## Command and oracle
+
+`command` is an argv array, run from a disposable copy of the project. There is no implicit shell, so redirection, pipes, globs and shell substitutions are literal arguments. Put a multi-step check in a script and name that script explicitly. Prefer portable executable names such as `node` and `npm`; absolute paths may not work for a recipient.
+
+The oracle matches combined stdout/stderr after terminal-control normalization. `exitCode` is an integer from 0 through 255. `allOf` must contain at least one non-empty, case-sensitive literal fragment. Every required fragment must occur, and no `noneOf` fragment may occur. These are literals, not regular expressions. A normal nonmatching exit is `absent`; execution/setup failures are `invalid`.
+
+Pin a checker with `preserve` when its assertion must remain unchanged. A target that prints its own entire diagnostic can sometimes be reduced to that print; a precise external assertion and controls make the observation more useful. A match alone does not prove a semantic root cause.
+
+## Search and execution limits
+
+`maxEvaluations` counts actual candidate observations, including confirmation runs, plus failed dependency preparations. Baseline and export checks do not consume this count. `maxSeconds` covers calibration and search, including their setup. Inventory and the initial npm availability probe precede this timer. Filesystem cleanup/checkpoint work may finish shortly after a deadline, but an incomplete confirmation cannot be accepted.
+
+After calibrated search reaches a budget, independent export verification runs separately. Each final target has `timeoutMs`, each new installation has `installTimeoutMs`, and output is bounded by `maxOutputBytes` combined across both streams. Set appropriate limits for your application. Abort remains available during final verification.
+
+All limits must be positive safe integers. Baseline and final repetition counts cannot be below 3; candidate counts cannot be below 2. Increasing repetition can expose flakes but does not prove determinism.
+
+`allowInstallScripts` defaults to false. Set it to true only for trusted dependencies whose lifecycle setup is necessary. Source-mutating install scripts may prevent independent verification; the exact exported source must still match its manifest after installation.
+
+`env` lists variable **names**, not values. Essential OS settings such as PATH and locale are inherited; HOME and npm config/cache locations belong to the run. The tool sets CI, disables Next.js telemetry and requests plain output. Required values must be supplied independently by a recipient and are never embedded automatically. Avoid forwarding credentials. Explicitly forwarding loader or module-path variables changes your execution environment and can undermine portability.
+
+## Paths and adapters
+
+`include`, `exclude`, and `preserve` accept project-relative paths, directory prefixes and glob patterns using `/` separators. Ordinary `.gitignore` rules, including nested rules, apply. `include` can override an ignore rule; explicit `exclude` wins. Neither can reintroduce hard-excluded material such as `.env` (including `.env.example`), `.npmrc`, credential keys, `node_modules`, `.git`, `.next`, `dist`, `build`, `.repro` or symbolic links.
+
+`preserve` prevents eligible source from being deleted or rewritten; it does not include a file excluded from the initial inventory. Pinning either `package.json` or `package-lock.json` disables dependency reduction. Package metadata and license/notice files receive default protection from generic reductions.
+
+`adapter` is `auto`, `next` or `generic`. Next.js detection records router and entrypoints, protects framework paths conservatively and guides file proposals. Protection of an entrypoint's path does not pin its contents; use `preserve` if its contents must remain unchanged. Heuristics never replace execution checks.
+
+The snapshot limit is 128 MiB of included source. Installed dependencies are excluded from that limit and from source-byte metrics. Reported source bytes exclude `package.json` and lock metadata. Total snapshot bytes include them. Neither metric includes the generated `.repro` verifier or installed dependencies.
+
+## CLI results
+
+| Command | Purpose |
+|---|---|
+| `init [project] --match TEXT -- COMMAND ARGS` | Write configuration without overwriting an existing file |
+| `doctor [project] [--config FILE] [--json]` | Inventory and runtime/dependency diagnosis; no project code execution |
+| `reduce [project] --out DIRECTORY [--config FILE]` | Start a new run outside the source tree |
+| `resume DIRECTORY [--max-evaluations N] [--max-seconds N]` | Continue an accepted checkpoint with total-budget overrides |
+| `verify EXPORTED_DIRECTORY [--json]` | Independently check the exported source |
+| `report RUN_DIRECTORY [--json]` | Rebuild offline HTML and JSON from the checkpoint |
+
+`--json` keeps progress on stderr and emits a structured result on stdout. Exit 0 means the requested command succeeded; `reduce`/`resume`/`verify` require verified export for exit 0. Exit 1 means unverified/paused result, exit 2 means an input or operational error, and an interrupted reduction returns 130 when a result can be checkpointed. Do not treat the application's expected nonzero exit as the CLI's failure.