@davmash/bygone 0.10.1 → 0.11.1

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 0.11.1
+
+- Added pinned evidence reviews in the CLI and VS Code, with explicit refresh, source validation, and return-to-review navigation
+- Connected evidence ranges to synchronized working-file and symbol editing while preserving historical review snapshots
+- Added dependency-guided review navigation and improved modern TypeScript syntax coverage, metadata resolution, and report validation
+
+## 0.11.0
+
+- Added experimental JS/TS and Python symbol evidence with declaration diffs, symbol trees, analysis diagnostics, and shared Files/Symbols navigation
+- Added pinned symbol tour stops and full-file context in live presentations and portable exports
+- Added the local Strand declaration matcher for JS/TS, Python, Java, Go, Rust, C#, Ruby, PHP, C, Lua, and experimental Mojo, with bounded analysis and explicit ambiguity reporting
+- Kept Java and RefactoringMiner optional: exact-only generation records partial coverage, and Strand provides local inference without a JVM
+- Added opt-in VS Code active-editor following with a live HEAD-to-buffer diff, Pin/Resume/Refresh controls, and safe handoffs to history and manual comparison
+- Fixed following for macOS directory aliases and files at the 5,000-line limit, with regression coverage on current and minimum-supported VS Code
+- Hardened correspondence artifact validation, parser budgets, and symbol owner matching
+- Updated Electron, DOMPurify, fast-uri, and packaging dependencies to resolve security advisories
+
+macOS desktop downloads are unsigned and not notarized. If Gatekeeper reports
+the app as damaged, run `xattr -cr /Applications/Bygone.app`, then reopen it.
+
+## 0.10.2
+
+- Prioritized matching named lines before brackets to preserve block correspondences across nesting and indentation changes
+- Aligned changed indentation highlights to the start of each line while preserving highlights on edited text
+
 ## 0.10.1
 
 - Fixed desktop tours showing unstyled HTML after temporary asset cleanup during long-running app sessions

package/README.md

@@ -214,6 +214,8 @@ Contributors should consult the internal [product surface overview](./docs/produ
 
 `bygone tour context [<head>] --base <base>` produces a provider-neutral change dossier with bounded patches, changed ranges, file roles, symbol hints, commits, renames, and explicit binary omissions for an LLM to consume.
 
+`bygone dependencies [<head>] --base <base>` compares static JS/TS module dependencies, labels initialization versus deferred use, and lists unchanged consumers of changed modules. Add `--json` for exact source evidence, or use `bygone tour context --base <base> --dependencies` to include it in a change dossier. See [dependency evidence](docs/dependencies.md) for resolution rules and coverage limits. These analysis commands run through the npm/source Node CLI.
+
 The desktop app also includes `Help -> Install Command Line Tools...` for non-npm installs. Homebrew cask installs can provide the `bygone` command automatically.
 
 ### macOS says the app is damaged
@@ -352,6 +354,10 @@ The wrapper scripts are:
 
 ## Commands
 
+- `Bygone: Follow Active Editor`
+- `Bygone: Pin Following File`
+- `Bygone: Resume Following`
+- `Bygone: Refresh Following Comparison`
 - `Bygone: Compare Active File With…`
 - `Bygone: Compare Selected Files`
 - `Bygone: Compare with Selected`
@@ -370,6 +376,64 @@ panes edit through VS Code documents, so changes participate in dirty state,
 undo, save, and external-document updates. Historical and non-local inputs are
 read-only. Desktop hand-offs are unavailable in remote extension hosts.
 
+## Follow the active VS Code editor
+
+Run **Bygone: Follow Active Editor** to open one comparison beside your source
+editor without moving keyboard focus. Switching source files updates that pane.
+The left side is HEAD; the right side is the VS Code document, including unsaved
+edits. Edit either the source pane or Bygone's working pane: both update the same
+document. Save, Undo and Redo in Bygone use that document's save and edit history.
+Typing neither saves the file nor stages it.
+
+Source Control offers **Open Staged Changes in Bygone** (HEAD → index) and
+**Open Working Changes in Bygone** (index → working buffer), in the file's inline
+and context menus. Staged views exclude unsaved edits and are read-only. Native
+stage, unstage, discard, commit and checkout operations refresh live comparisons.
+The selected policy stays in place when a file leaves its SCM group; an empty
+comparison shows that there are now no changes. Enable `bygone.followScmDiffs`
+to follow supported native Git diff tabs during a following session. This does
+not change the SCM tree's default click behavior.
+
+Use **Bygone: Compare Symbol in Bygone**, or enable `bygone.followSymbol` to follow
+Outline, Go to Symbol and cursor selections. Symbol focus preserves the selected
+comparison and uses the existing Strand matching engine. JavaScript and TypeScript
+are supported within the selected file pair, including Git-reported renames.
+Dirty-buffer selections in staged views require a verified mapping to the index.
+Unsupported or ambiguous selections show a reason and retain file context or a
+known one-sided symbol. **Show File Context** returns to the whole comparison;
+**Reveal Source** opens the working document or the exact read-only snapshot.
+
+Working symbol slices are editable. Edits before a declaration move its tracked
+range; temporary syntax errors keep its editing range usable. Replacing or deleting
+the declaration externally returns to file context. If a concurrent edit makes a
+pending write stale, Bygone preserves the attempted text in an untitled recovery
+document instead of overwriting the source. Pending drafts are also recovered
+when the panel closes or the extension starts again after a reload.
+
+**Pin** keeps the target, baseline and symbol focus. A pinned working endpoint
+continues to reflect edits; a pinned staged view holds both snapshots. Git changes
+show a notice until **Resume Following** resolves current endpoints. **Refresh**
+updates live comparisons; pinned snapshots remain fixed. Source navigation within
+the selected file preserves SCM policy; a different ordinary file selects HEAD →
+working. **View File History** and **Manual Compare…** pause following and open
+separate views. A restored following panel starts paused.
+
+Labels identify the repository, paths, comparison policy and saved/unsaved state.
+New/deleted files and unborn HEAD use explicit absent endpoints. Following supports
+trusted local Git worktrees, including linked worktrees and multiple repositories.
+Each selected endpoint must be text, at most 128 KiB and 5,000 lines; Git snapshots
+must be UTF-8. Conflicts, unsupported diff inputs, symlinks, binary, remote,
+virtual and notebook inputs show an explicit unavailable state. Git failures clear
+the previous comparison. Arbitrary cross-file symbol moves and hunk staging inside
+Bygone are outside this integration.
+
+Use **Bygone: Open Evidence Review** to inspect pinned requirement evidence, edit
+the working counterpart, and return to the original review. See the
+[evidence workflow and PR Reviewer bridge](docs/evidence-review.md).
+
+See the [integration contract and verification record](docs/vscode-integration.md)
+for snapshot/edit safeguards, analysis budgets and reproducible Extension Host tests.
+
 ## Limitations
 
 - Bygone is intentionally diff-focused; merge tooling is not exposed as a product feature.

package/bin/bygone.js

@@ -40,7 +40,24 @@ if (tokenMatches('completion', args[0])) {
     process.exit(0);
 }
 
-if (tokenMatches('tourCommand', args[0])) {
+if (args[0] === 'evidence') {
+    try { require('../cli/evidence').runEvidenceCommand(args.slice(1), cliCwd); }
+    catch (error) { process.stderr.write(`Could not process evidence: ${error.message}\n`); process.exitCode = 1; }
+} else if (args[0] === 'dependencies') {
+    try {
+        require('../cli/dependencies').runDependenciesCommand(args.slice(1), cliCwd);
+    } catch (error) {
+        process.stderr.write(`Could not analyze dependencies: ${error.message}\n`);
+        process.exitCode = 1;
+    }
+} else if (args[0] === 'correspondence') {
+    try {
+        require('../cli/correspondence').importCorrespondenceCommand(args.slice(1), cliCwd);
+    } catch (error) {
+        process.stderr.write(`Could not import correspondence: ${error.message}\n`);
+        process.exitCode = 1;
+    }
+} else if (tokenMatches('tourCommand', args[0])) {
     try {
         runTourCommand(args.slice(1), cliCwd, packageRoot);
     } catch (error) {

package/cli/commandSpec.js

@@ -13,10 +13,13 @@ const CLI_SPEC = Object.freeze({
         'bygone --read-only <desktop-arguments...>',
         'bygone review [<head>] [--base <base>]',
         'bygone -C <directory> <command-or-path> [...]',
-        'bygone present [<head>] [--base <base>] [--tour <file.bygone>]',
+        'bygone present [<head>] [--base <base>] [--tour <file.bygone>] [--correspondence <artifact.json>]',
         'bygone tour validate <file.bygone> [--json]',
         'bygone tour compile <file.bygone> [--output <tour.json>]',
-        'bygone tour context [<head>] [--base <base>] [--output <context.json>]',
+        'bygone tour context [<head>] [--base <base>] [--output <context.json>] [--correspondence <artifact.json>] [--dependencies]',
+        'bygone evidence <inspect|import|refresh|tour> <review.json> [--head <revision>] [--output <new-file>]',
+        'bygone dependencies [<head>] [--base <base>] [--json] [--output <graph.json>]',
+        'bygone correspondence import <report.json> [<head>] [--base <base>] [--case <id>] --output <artifact.json>',
         'bygone tour coverage <file.bygone> [--json] [--minimum-coverage <0-100>]',
         'bygone tour export <file.bygone> --output <tour.html> [--profile minimal|full] [--runtime embedded|cdn]',
         'bygone <bygone://open/v1?...>',
@@ -26,6 +29,7 @@ const CLI_SPEC = Object.freeze({
         'bygone --test'
     ],
     entries: [
+        { id: 'evidence', kind: 'command', tokens: ['evidence'], description: 'Inspect, import, refresh, or present pinned review evidence', argument: 'path' },
         {
             id: 'review',
             kind: 'command',
@@ -33,6 +37,18 @@ const CLI_SPEC = Object.freeze({
             description: 'Review a committed branch against its merge base',
             argument: 'git-ref'
         },
+        {
+            id: 'dependencies', kind: 'command', tokens: ['dependencies'],
+            description: 'Compare static JS/TS module dependencies at committed revisions', argument: 'git-ref'
+        },
+        {
+            id: 'dependencyContext', kind: 'option', tokens: ['--dependencies'],
+            description: 'Include static module dependency evidence in tour context', argument: 'none'
+        },
+        {
+            id: 'correspondence', kind: 'command', tokens: ['correspondence'],
+            description: 'Import externally produced symbol correspondence evidence', argument: 'path'
+        },
         {
             id: 'completion',
             kind: 'command',
@@ -110,6 +126,10 @@ const CLI_SPEC = Object.freeze({
             description: 'Use an authored .bygone presentation',
             argument: 'path'
         },
+        {
+            id: 'correspondenceEvidence', kind: 'option', tokens: ['--correspondence'],
+            description: 'Use pinned symbol evidence in present or tour context', argument: 'path'
+        },
         {
             id: 'readOnly',
             kind: 'global',

package/cli/completions.js

@@ -35,7 +35,7 @@ function generateZshCompletion() {
     const reviewOptions = entriesByIds(['base', 'help'])
         .flatMap((entry) => entry.tokens.map((token) => `        '${token}:${escapeSingleQuoted(entry.description)}'`))
         .join('\n');
-    const presentOptions = entriesByIds(['base', 'tour', 'help'])
+    const presentOptions = entriesByIds(['base', 'tour', 'correspondenceEvidence', 'help'])
         .flatMap((entry) => entry.tokens.map((token) => `        '${token}:${escapeSingleQuoted(entry.description)}'`))
         .join('\n');
     const legacyOptions = entriesByIds(['branch', 'base', 'help'])
@@ -93,16 +93,24 @@ ${historyOptions}
             elif [[ "$words[3]" == "context" ]]; then
                 if [[ "$previous" == ${shellAlternation(tokensFor('base'))} ]]; then
                     _bygone_git_refs
-                elif [[ "$previous" == "--output" || "$previous" == "-o" ]]; then
+                elif [[ "$previous" == "--output" || "$previous" == "-o" || "$previous" == "--correspondence" ]]; then
                     _files
                 else
-                    compadd -- --base --output -o --max-patch-bytes --max-total-patch-bytes
+                    compadd -- --base --output -o --max-patch-bytes --max-total-patch-bytes --correspondence --dependencies
                     _bygone_git_refs
                 fi
             elif [[ "$words[3]" == "coverage" || "$words[3]" == "validate" || "$words[3]" == "compile" ]]; then
                 _files -g '*.bygone' -g '*.bygone.yaml'
             fi
             ;;
+        dependencies)
+            if [[ "$previous" == "--output" || "$previous" == "-o" ]]; then
+                _files
+            else
+                compadd -- --base --json --output -o
+                _bygone_git_refs
+            fi
+            ;;
         review)
             if [[ "$previous" == ${shellAlternation(tokensFor('base'))} ]]; then
                 _bygone_git_refs
@@ -112,7 +120,7 @@ ${historyOptions}
             fi
             ;;
         present)
-            if [[ "$previous" == ${shellAlternation(tokensFor('tour'))} ]]; then
+            if [[ "$previous" == ${shellAlternation(tokensFor('tour'))} || "$previous" == "--correspondence" ]]; then
                 _files -g '*.bygone' -g '*.bygone.yaml'
             elif [[ "$previous" == ${shellAlternation(tokensFor('base'))} ]]; then
                 _bygone_git_refs
@@ -152,7 +160,7 @@ compdef _bygone bygone
 function generateBashCompletion() {
     const rootTokens = completionEntries().flatMap((entry) => entry.tokens).join(' ');
     const reviewTokens = entriesByIds(['base', 'help']).flatMap((entry) => entry.tokens).join(' ');
-    const presentTokens = entriesByIds(['base', 'tour', 'help']).flatMap((entry) => entry.tokens).join(' ');
+    const presentTokens = entriesByIds(['base', 'tour', 'correspondenceEvidence', 'help']).flatMap((entry) => entry.tokens).join(' ');
     const legacyTokens = entriesByIds(['branch', 'base', 'help']).flatMap((entry) => entry.tokens).join(' ');
     const historyTokens = entriesByIds(['includeStaged', 'help']).flatMap((entry) => entry.tokens).join(' ');
     const baseTokens = tokensFor('base').join('|');
@@ -188,17 +196,25 @@ _bygone() {
                 refs="$(_bygone_git_refs)"
                 if [[ "$prev" =~ ^(${baseTokens})$ ]]; then
                     COMPREPLY=( $(compgen -W "$refs" -- "$cur") )
-                elif [[ "$prev" == "--output" || "$prev" == "-o" ]]; then
+                elif [[ "$prev" == "--output" || "$prev" == "-o" || "$prev" == "--correspondence" ]]; then
                     COMPREPLY=( $(compgen -f -- "$cur") )
                     compopt -o filenames 2>/dev/null || true
                 else
-                    COMPREPLY=( $(compgen -W '--base --output -o --max-patch-bytes --max-total-patch-bytes '"$refs" -- "$cur") )
+                    COMPREPLY=( $(compgen -W '--base --output -o --max-patch-bytes --max-total-patch-bytes --correspondence --dependencies '"$refs" -- "$cur") )
                 fi
             else
                 COMPREPLY=( $(compgen -W '--json --output -o' -- "$cur") $(compgen -f -- "$cur") )
                 compopt -o filenames 2>/dev/null || true
             fi
             ;;
+        dependencies)
+            if [[ "$prev" == "--output" || "$prev" == "-o" ]]; then
+                COMPREPLY=( $(compgen -f -- "$cur") )
+                compopt -o filenames 2>/dev/null || true
+            else
+                COMPREPLY=( $(compgen -W '--base --json --output -o '"$(_bygone_git_refs)" -- "$cur") )
+            fi
+            ;;
         review)
             refs="$(_bygone_git_refs)"
             if [[ "$prev" =~ ^(${baseTokens})$ ]]; then
@@ -209,7 +225,7 @@ _bygone() {
             ;;
         present)
             refs="$(_bygone_git_refs)"
-            if [[ "$prev" == "--tour" ]]; then
+            if [[ "$prev" == "--tour" || "$prev" == "--correspondence" ]]; then
                 COMPREPLY=( $(compgen -f -- "$cur") )
                 compopt -o filenames 2>/dev/null || true
             elif [[ "$prev" =~ ^(${baseTokens})$ ]]; then
@@ -261,6 +277,11 @@ function generateFishCompletion() {
     }
 
     lines.push(
+        "complete -c bygone -n 'string match -q \"*tour context*\" -- (commandline -opc)' -l dependencies -d 'Include static module dependency evidence'",
+        "complete -c bygone -n '__fish_seen_subcommand_from dependencies' -l base -r -a '(__bygone_git_refs)' -d 'Set the dependency comparison base'",
+        "complete -c bygone -n '__fish_seen_subcommand_from dependencies' -l json -d 'Print dependency evidence as JSON'",
+        "complete -c bygone -n '__fish_seen_subcommand_from dependencies' -l output -s o -r -d 'Write dependency evidence'",
+        "complete -c bygone -n '__fish_seen_subcommand_from dependencies' -a '(__bygone_git_refs)' -d 'Git ref'",
         "complete -c bygone -n '__fish_seen_subcommand_from completion' -a 'zsh bash fish' -d 'Shell'",
         "complete -c bygone -n '__fish_seen_subcommand_from tour' -a 'context coverage validate compile export schema' -d 'Tour action'",
         "complete -c bygone -n 'string match -q \"*tour context*\" -- (commandline -opc)' -l base -r -a '(__bygone_git_refs)' -d 'Set the change-context base ref'",
@@ -274,6 +295,7 @@ function generateFishCompletion() {
         "complete -c bygone -n '__fish_seen_subcommand_from review' -a '(__bygone_git_refs)' -d 'Git ref'",
         `complete -c bygone -n '__fish_seen_subcommand_from present' ${fishTokens(tokensFor('base'))} -r -a '(__bygone_git_refs)' -d '${escapeSingleQuoted(getCliEntry('base').description)}'`,
         `complete -c bygone -n '__fish_seen_subcommand_from present' ${fishTokens(tokensFor('tour'))} -r -d '${escapeSingleQuoted(getCliEntry('tour').description)}'`,
+        `complete -c bygone ${fishTokens(tokensFor('correspondenceEvidence'))} -r -d 'Use pinned symbol correspondence evidence'`,
         "complete -c bygone -n '__fish_seen_subcommand_from present' -a '(__bygone_git_refs)' -d 'Git ref'",
         `complete -c bygone -n 'string match -q "*--branch-diff*" -- (commandline -opc)' ${fishTokens(tokensFor('branch'))} -r -a '(__bygone_git_refs)' -d '${escapeSingleQuoted(getCliEntry('branch').description)}'`,
         `complete -c bygone -n 'string match -q "*--branch-diff*" -- (commandline -opc)' ${fishTokens(tokensFor('base'))} -r -a '(__bygone_git_refs)' -d '${escapeSingleQuoted(getCliEntry('base').description)}'`,

package/cli/correspondence.js

@@ -0,0 +1,71 @@
+const path = require('path');
+const { lstatSync, mkdirSync, statSync, writeFileSync } = require('fs');
+const { resolveBranchReviewRange } = require('../out/gitComparison');
+const { importChangeCorrespondence, readCorrespondenceJson } = require('../out/changeCorrespondence');
+
+function importCorrespondenceCommand(args, cwd, output = process.stdout) {
+    if (args[0] !== 'import') throw new Error('Usage: bygone correspondence import <report.json> [<head>] --base <base> [--case <id>] --output <artifact.json>');
+    const options = {};
+    const positional = [];
+    for (let i = 1; i < args.length; i++) {
+        const arg = args[i];
+        if (['--base', '--case', '--output', '-o'].includes(arg)) {
+            if (!args[i + 1] || args[i + 1].startsWith('-')) throw new Error(`${arg} requires a value.`);
+            options[arg === '-o' ? '--output' : arg] = args[++i];
+        } else if (arg.startsWith('-')) throw new Error(`Unknown correspondence option: ${arg}`);
+        else positional.push(arg);
+    }
+    if (!positional.length || positional.length > 2 || !options['--output']) throw new Error('Provide a producer report, at most one head ref, and --output.');
+    const reportPath = path.resolve(cwd, positional[0]);
+    const destination = path.resolve(cwd, options['--output']);
+    assertDestinationAvailable(reportPath, destination);
+    const report = readCorrespondenceJson(reportPath);
+    if (!report || typeof report !== 'object') throw new Error('Invalid correspondence report.');
+    let selected = report;
+    if (Array.isArray(report.cases)) {
+        if (!options['--case']) throw new Error('A multi-case producer report requires --case.');
+        const matches = report.cases.filter(c => c.id === options['--case']);
+        if (matches.length !== 1) throw new Error('Select exactly one existing producer case.');
+        selected = matches[0];
+    } else if (options['--case']) throw new Error('--case requires a multi-case producer report.');
+    const range = resolveBranchReviewRange(cwd, positional[1] || 'HEAD', options['--base']);
+    const artifact = importChangeCorrespondence(range.repoRoot, selected, { baseOid: range.mergeBaseOid, headOid: range.headOid });
+    mkdirSync(path.dirname(destination), { recursive: true });
+    try {
+        writeFileSync(destination, JSON.stringify(artifact, null, 2) + '\n', { encoding: 'utf8', flag: 'wx', mode: 0o600 });
+    } catch (error) {
+        if (error?.code === 'EEXIST') throw new Error(`The correspondence output already exists at ${destination}; choose a new path.`, { cause: error });
+        throw new Error(`Could not create correspondence output at ${destination}: ${error.message}`, { cause: error });
+    }
+    output.write(`Wrote ${artifact.relations.length} inferred correspondences (${artifact.status}) to ${destination}\n`);
+    return artifact;
+}
+
+function assertDestinationAvailable(reportPath, destination) {
+    if (sameActualFile(reportPath, destination)) {
+        throw new Error('The imported artifact must not overwrite the producer report or any of its symlink/hardlink aliases.');
+    }
+    try {
+        lstatSync(destination);
+    } catch (error) {
+        if (error?.code === 'ENOENT') return;
+        throw new Error(`Could not inspect correspondence output at ${destination}: ${error.message}`, { cause: error });
+    }
+    throw new Error(`The correspondence output already exists at ${destination}; choose a new path.`);
+}
+
+function sameActualFile(first, second) {
+    if (first === second) return true;
+    try {
+        const left = statSync(first);
+        const right = statSync(second);
+        if (left.dev !== undefined && left.ino !== undefined
+            && left.dev === right.dev && left.ino === right.ino
+            && left.ino !== 0 && right.ino !== 0) return true;
+    } catch {
+        return false;
+    }
+    return false;
+}
+
+module.exports = { importCorrespondenceCommand };

package/cli/dependencies.js

@@ -0,0 +1,62 @@
+const { mkdirSync, writeFileSync } = require('fs');
+const path = require('path');
+
+function runDependenciesCommand(args, cwd, output = process.stdout) {
+    let headRef, baseRef, outputPath;
+    let json = false;
+    for (let index = 0; index < args.length; index++) {
+        const arg = args[index];
+        if (arg === '--json') { json = true; continue; }
+        if (['--base', '-m', '--main', '--output', '-o'].includes(arg)) {
+            const value = args[++index];
+            if (!value || value.startsWith('-')) throw new Error(`${arg} requires a value.`);
+            if (['--output', '-o'].includes(arg)) outputPath = value;
+            else baseRef = value;
+        } else if (arg.startsWith('-') || headRef) throw new Error(`Unexpected dependencies argument: ${arg}`);
+        else headRef = arg;
+    }
+    const { buildDependencyGraph } = require('../out/dependencyGraph.js');
+    const report = buildDependencyGraph(cwd, { headRef, baseRef });
+    if (outputPath) {
+        const resolved = path.resolve(cwd, outputPath);
+        mkdirSync(path.dirname(resolved), { recursive: true });
+        writeFileSync(resolved, `${JSON.stringify(report, null, 2)}\n`);
+        output.write(`Wrote dependency evidence to ${resolved}\n`);
+    } else output.write(json ? `${JSON.stringify(report, null, 2)}\n` : renderDependencyReport(report));
+    return report;
+}
+
+function renderDependencyReport(report) {
+    const complete = report.base.coverage.indexComplete && report.head.coverage.indexComplete;
+    const lines = [
+        `Module dependencies: ${report.range.baseOid.slice(0, 7)} → ${report.range.headOid.slice(0, 7)}`,
+        `Static JS/TS evidence; initialization labels describe syntax, not observed execution.`,
+        `Index coverage: ${complete ? 'complete within supported scope' : 'PARTIAL — deltas and consumer lists may be incomplete'}`
+    ];
+    for (const side of ['base', 'head']) {
+        const snapshot = report[side];
+        const coverage = snapshot.coverage;
+        lines.push(`${side}: ${coverage.indexedFiles}/${coverage.candidateFiles} source files, ${snapshot.edges.length} sites, ${coverage.unresolvedEdges} unresolved, ${snapshot.diagnostics.length + coverage.omittedDiagnostics} diagnostics`);
+    }
+    const site = edge => `${edge.source.file}:${edge.source.line}:${edge.source.column} → ${edge.target ?? edge.specifier ?? '<computed>'} [${edge.relationship}; ${edge.phase}; ${edge.loading}; ${edge.resolution}]`;
+    const groups = [
+        ['Added module edges', report.changes.added], ['Removed module edges', report.changes.removed],
+        ['Unchanged consumers (base)', report.unchangedConsumers.base], ['Unchanged consumers (head)', report.unchangedConsumers.head]
+    ];
+    for (const [label, edges] of groups) {
+        lines.push(`\n${label}: ${edges.length}`);
+        for (const edge of edges.slice(0, 50)) {
+            lines.push(`  ${site(edge)}`);
+            if (edge.source.link) lines.push(`    ${edge.source.link}`);
+        }
+        if (edges.length > 50) lines.push(`  ${edges.length - 50} more sites; use --json for the bounded full report.`);
+    }
+    for (const side of ['base', 'head']) {
+        lines.push(`\n${side} diagnostics:`);
+        for (const item of report[side].diagnostics.slice(0, 10)) lines.push(`  ${item.file ? `${item.file}: ` : ''}${item.code}: ${item.message}`);
+        if (report[side].diagnostics.length > 10) lines.push('  More diagnostics in --json.');
+    }
+    lines.push('\nUse --json or --output <file> for all indexed edges, potential initialization calls, exact source ranges, and scope assumptions.');
+    return `${lines.join('\n')}\n`;
+}
+module.exports = { runDependenciesCommand, renderDependencyReport };

package/cli/evidence.js

@@ -0,0 +1,67 @@
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const workspace = require('../out/reviewWorkspace');
+const { parseReview } = require('../out/requirements');
+const { inspectDependencies } = require('../out/reviewDependencies');
+
+function runEvidenceCommand(args, cwd) {
+    const [action, input, ...rest] = args;
+    if (!['inspect', 'import', 'refresh', 'tour'].includes(action) || !input) throw new Error('Usage: bygone evidence <inspect|import|refresh|tour> <review.json> [--head <revision>] [--requirements <review.json>] [--correspondence <artifact.json>] [--dependencies <report.json>] [--output <new-file>]');
+    const options = {};
+    for (let i = 0; i < rest.length; i += 2) {
+        if (!['--head', '--requirements', '--correspondence', '--dependencies', '--output'].includes(rest[i]) || !rest[i + 1] || options[rest[i]]) throw new Error('Invalid or duplicate evidence option');
+        options[rest[i]] = rest[i + 1];
+    }
+    const root = workspace.repositoryRoot(cwd), file = path.resolve(cwd, input);
+    const loaded = workspace.loadReview(root, file);
+    // Reports must describe the sanitized artifact that is actually imported.
+    const review = action === 'import' ? { ...loaded, decisions: [] } : loaded;
+    const absolute = key => options[key] ? path.resolve(cwd, options[key]) : undefined;
+    const output = absolute('--output');
+    if (action === 'refresh') {
+        if (!output || !options['--head']) throw new Error('Refresh requires --head and a new --output file');
+        const revised = options['--requirements'] ? parseReview(workspace.readEvidenceJson(absolute('--requirements'))) : review;
+        if (revised.repository !== review.repository || revised.base !== review.base || revised.head !== review.head) throw new Error('Requirement update must identify the original repository and comparison');
+        const requirements = revised.requirements;
+        const result = workspace.refreshWorkspace(root, review, options['--head'], absolute('--correspondence'), requirements);
+        workspace.writeReview(output, result.review);
+        process.stdout.write(JSON.stringify({ output, transitions: result.transitions }, null, 2) + '\n'); return;
+    }
+    const report = workspace.inspectWorkspace(root, review);
+    const dependencies = options['--dependencies'] ? inspectDependencies(root, review, workspace.readEvidenceJson(absolute('--dependencies'))) : undefined;
+    if (action === 'import') {
+        if (!output) throw new Error('Import requires a new --output file');
+        // Compatible producers export this versioned shape directly. Never manufacture an inspection decision.
+        workspace.writeReview(output, review);
+        process.stdout.write(JSON.stringify({ output, report, dependencies }, null, 2) + '\n'); return;
+    }
+    if (action === 'tour') {
+        if (!output) throw new Error('Tour requires a new --output file');
+        const anchors = {}, steps = [];
+        for (const requirement of report.requirements) for (const link of requirement.links) {
+            if (link.resolution.status !== 'valid') continue;
+            const text = workspace.sourceText(root, link.ref), needle = link.resolution.text;
+            let at = -1, occurrence = 0;
+            do { at = text.indexOf(needle, at + 1); occurrence++; } while (at >= 0 && at < link.ref.start);
+            if (at !== link.ref.start) throw new Error('Cannot represent source reference as a tour anchor');
+            const id = `evidence-${steps.length + 1}`;
+            anchors[id] = { file: link.ref.path, revision: link.ref.revision === review.base ? 'base' : 'head', contains: needle, occurrence };
+            steps.push({ id, title: `${requirement.id}: ${link.role}`, body: `${link.rationale}\nVerification: ${requirement.verification}; inspection: ${requirement.reviewer}. Reference validity does not establish fulfillment.`, focus: id,
+                requirement: { id: requirement.id, text: requirement.text, source: requirement.sources.map(s => s.title).join('; ') } });
+        }
+        if (!steps.length) throw new Error('No valid evidence links to present; use evidence inspect for missing/broken evidence');
+        const tour = { version: 6, title: 'Requirement evidence', range: { base: review.base, head: review.head }, anchors, connections: [],
+            chapters: [{ id: 'requirements', title: 'Requirement evidence', scenes: [{ id: 'evidence', kind: 'walkthrough', title: 'Inspect recorded evidence',
+                summary: 'Pinned references, execution records, and human inspection remain separate.', tags: [],
+                bullets: report.requirements.filter(r => !r.implementationLinked || !r.testLinked).map(r => `${r.id}: missing implementation or test links`),
+                takeaway: 'This tour supplies inspection context, not an approval decision.', steps }] }] };
+        // Validate before publishing an artifact. The existing tour engine owns presentation.
+        require('../out/changeTour').buildChangeTourManifest(root, { source: tour });
+        fs.writeFileSync(output, JSON.stringify(tour, null, 2) + '\n', { flag: 'wx' });
+        process.stdout.write(`Created ${output}\nOpen: bygone -C ${JSON.stringify(root)} present --tour ${JSON.stringify(output)}\n`); return;
+    }
+    const result = JSON.stringify({ review, report, dependencies }, null, 2) + '\n';
+    if (output) fs.writeFileSync(output, result, { flag: 'wx' }); else process.stdout.write(result);
+}
+module.exports = { runEvidenceCommand };