@davmash/bygone 0.11.0 → 0.11.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # 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

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
@@ -376,31 +378,61 @@ 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 read-only comparison beside your
-source editor without moving keyboard focus. Switching source files updates that
-same pane. The left side is the file at HEAD; the right side is your editor buffer,
-including unsaved edits. Edit, undo, and save in the source editor as usual.
-
-**Pin** keeps the current file and baseline commit while buffer edits continue to
-update. **Resume Following** selects the active or last source editor. **Refresh**
-reads HEAD again when following; a pinned comparison retains its baseline. HEAD
-also refreshes on file activation and when the VS Code window regains focus.
-After external Git changes while the window stays focused, use Refresh.
-
-The controls show the repository, relative file path, commit, and saved/unsaved
-state. Clean files say **No changes from HEAD**. Untracked files, files absent at
-the current path in HEAD, and unborn repositories use an explicitly absent
-baseline. Renames are compared at the new path; following does not infer history.
-**View File History** pauses following and opens the history viewer. **Manual
-Compare…** pauses following and compares the source with another selected file.
-Closing the pane stops following. A restored pane starts paused after reload.
-
-Following supports trusted local Git worktrees, including linked worktrees and
-files in multiple repositories. Both versions must be text, at most 128 KiB and
-5,000 lines; Git baselines must be UTF-8. Untitled, remote, virtual, notebook,
-symlink, binary, and oversized files show an unavailable state. Open the source
-file outside a native SCM diff to follow it. Git failures clear the old comparison
-and show an error instead of treating a failed read as an empty baseline.
+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
 

package/bin/bygone.js

@@ -40,7 +40,17 @@ if (tokenMatches('completion', args[0])) {
     process.exit(0);
 }
 
-if (args[0] === 'correspondence') {
+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) {

package/cli/commandSpec.js

@@ -16,7 +16,9 @@ const CLI_SPEC = Object.freeze({
         '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>] [--correspondence <artifact.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]',
@@ -27,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',
@@ -34,6 +37,14 @@ 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'

package/cli/completions.js

@@ -96,13 +96,21 @@ ${historyOptions}
                 elif [[ "$previous" == "--output" || "$previous" == "-o" || "$previous" == "--correspondence" ]]; then
                     _files
                 else
-                    compadd -- --base --output -o --max-patch-bytes --max-total-patch-bytes --correspondence
+                    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
@@ -192,13 +200,21 @@ _bygone() {
                     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 --correspondence '"$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
@@ -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'",

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 };

package/cli/tour.js

@@ -34,13 +34,21 @@ function runTourCommand(args, cwd, packageRoot, output = process.stdout) {
         return { action: 'schema' };
     }
     if (options.action === 'context') {
+        const range = options.dependencies
+            ? require('../out/gitComparison.js').resolveBranchReviewRange(cwd, options.headRef, options.baseRef)
+            : undefined;
         const context = buildChangeTourContext(cwd, {
+            range,
             headRef: options.headRef,
             baseRef: options.baseRef,
             correspondencePath: options.correspondencePath ? path.resolve(cwd, options.correspondencePath) : undefined,
             maxPatchBytes: options.maxPatchBytes,
             maxTotalPatchBytes: options.maxTotalPatchBytes
         });
+        if (options.dependencies) {
+            const { buildDependencyGraph } = require('../out/dependencyGraph.js');
+            context.dependencies = buildDependencyGraph(cwd, { range });
+        }
         return writeJsonResult('change-tour context', context, options.outputPath, cwd, output);
     }
 
@@ -150,6 +158,7 @@ function parseContextArgs(args) {
     let maxPatchBytes;
     let correspondencePath;
     let maxTotalPatchBytes;
+    let dependencies = false;
     for (let index = 0; index < args.length; index += 1) {
         const arg = args[index];
         if (arg === '--base' || arg === '-m' || arg === '--main') {
@@ -162,6 +171,7 @@ function parseContextArgs(args) {
             outputPath = args[++index];
             continue;
         }
+        if (arg === '--dependencies') { dependencies = true; continue; }
         if (arg === '--correspondence') {
             if (!args[index + 1] || args[index + 1].startsWith('-')) throw new Error('--correspondence requires a file path.');
             correspondencePath = args[++index];
@@ -187,7 +197,7 @@ function parseContextArgs(args) {
         if (headRef) throw new Error('tour context accepts at most one head ref.');
         headRef = arg;
     }
-    return { action: 'context', headRef, baseRef, outputPath, maxPatchBytes, maxTotalPatchBytes, ...(correspondencePath ? { correspondencePath } : {}) };
+    return { action: 'context', headRef, baseRef, outputPath, maxPatchBytes, maxTotalPatchBytes, ...(correspondencePath ? { correspondencePath } : {}), ...(dependencies ? { dependencies } : {}) };
 }
 
 function writeJsonResult(label, value, outputPath, cwd, output) {

package/completions/_bygone

@@ -13,7 +13,9 @@ _bygone() {
     local previous="${words[CURRENT-1]}"
     local -a root_items review_options present_options legacy_options history_options shells tour_actions
     root_items=(
+        'evidence:Inspect, import, refresh, or present pinned review evidence'
         'review:Review a committed branch against its merge base'
+        'dependencies:Compare static JS/TS module dependencies at committed revisions'
         'correspondence:Import externally produced symbol correspondence evidence'
         'completion:Print shell completion source'
         'present:Open an app-hosted tour of a committed branch range'
@@ -83,13 +85,21 @@ _bygone() {
                 elif [[ "$previous" == "--output" || "$previous" == "-o" || "$previous" == "--correspondence" ]]; then
                     _files
                 else
-                    compadd -- --base --output -o --max-patch-bytes --max-total-patch-bytes --correspondence
+                    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" == (--base|-m|--main) ]]; then
                 _bygone_git_refs

package/completions/bygone

@@ -12,7 +12,7 @@ _bygone() {
     first="${COMP_WORDS[1]}"
 
     if (( COMP_CWORD == 1 )); then
-        COMPREPLY=( $(compgen -W 'review correspondence completion present tour --diff --history --git-diff --branch-diff --test --read-only -C -h --help -v --version' -- "$cur") $(compgen -f -- "$cur") )
+        COMPREPLY=( $(compgen -W 'evidence review dependencies correspondence completion present tour --diff --history --git-diff --branch-diff --test --read-only -C -h --help -v --version' -- "$cur") $(compgen -f -- "$cur") )
         compopt -o filenames 2>/dev/null || true
         return
     fi
@@ -32,13 +32,21 @@ _bygone() {
                     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 --correspondence '"$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" =~ ^(--base|-m|--main)$ ]]; then

package/completions/bygone.fish

@@ -4,7 +4,9 @@ function __bygone_git_refs
     printf "%s\n" HEAD INDEX WORKTREE
 end
 
+complete -c bygone -n '__fish_use_subcommand' -a evidence -r -d 'Inspect, import, refresh, or present pinned review evidence'
 complete -c bygone -n '__fish_use_subcommand' -a review -d 'Review a committed branch against its merge base'
+complete -c bygone -n '__fish_use_subcommand' -a dependencies -d 'Compare static JS/TS module dependencies at committed revisions'
 complete -c bygone -n '__fish_use_subcommand' -a correspondence -r -d 'Import externally produced symbol correspondence evidence'
 complete -c bygone -n '__fish_use_subcommand' -a completion -d 'Print shell completion source'
 complete -c bygone -n '__fish_use_subcommand' -a present -d 'Open an app-hosted tour of a committed branch range'
@@ -18,6 +20,11 @@ complete -c bygone -n '__fish_use_subcommand' -l read-only -d 'Open live Explore
 complete -c bygone -n '__fish_use_subcommand' -s C -r -d 'Run as if Bygone started in this directory'
 complete -c bygone -n '__fish_use_subcommand' -s h -l help -d 'Show command help'
 complete -c bygone -n '__fish_use_subcommand' -s v -l version -d 'Show the installed version'
+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'

package/docs/dependencies.md

@@ -0,0 +1,94 @@
+# Dependency evidence
+
+The Node CLI (npm installation or `node bin/bygone.js` in a source checkout)
+compares JS/TS module dependencies at the merge base and head of a committed
+review range:
+
+```sh
+bygone dependencies HEAD --base main
+bygone dependencies HEAD --base main --json
+bygone dependencies HEAD --base main --output dependencies.json
+bygone tour context HEAD --base main --dependencies --output context.json
+```
+
+The text report lists added/removed module edges and direct, unchanged consumers
+of changed files. Each site includes a `bygone://` link to its committed source.
+JSON includes both bounded snapshot graphs, potential initialization calls and
+constructors, diagnostics, and exact evidence coordinates. Ordinary tour context
+generation is unchanged. The desktop and VS Code interfaces do not yet have a
+graph view; these commands use the Node CLI rather than the desktop launcher.
+
+## Reading an edge
+
+Relationship, phase, and loading are separate fields. Static evidence can describe
+initialization or later invocation; it is not a runtime trace.
+
+- `import`, `reexport`, `require`, and `dynamic-import` describe syntax.
+- `type` marks explicitly type-only dependencies and dependencies in declaration files. `module-init` marks syntax
+  evaluated while a module initializes; a lazy-loaded module can initialize much
+  later than process startup. `invocation` marks function/callback bodies.
+  `unknown` retains sites where the extractor cannot assign a phase safely.
+- `eager` distinguishes ordinary imports/require from `deferred` dynamic imports and namespace `import defer` declarations. Deferred namespace evaluation has `unknown` phase because namespace use determines when evaluation occurs.
+  A dynamic import at top level is still labeled `module-init`. A `require` inside
+  a function is `invocation` even though the require operation itself is eager.
+- `resolution: resolved` means the TypeScript resolver found a committed target
+  under the selected compiler options. It does not prove execution, runtime loader
+  equivalence, or the identity of a shadowable `require` binding.
+- `unresolved`, `computed`, and `invalid-config` preserve unknown targets. Builtins,
+  external packages, and computed specifiers commonly remain unresolved.
+
+Potential initialization calls are syntax sites, not inferred function-call
+edges. Registration calls can appear here; their callback bodies are classified
+separately. IIFE bodies are conservatively labeled invocation with a diagnostic.
+Instance field initializers have unknown timing; static fields and class static
+blocks inherit the enclosing evaluation phase. Conditions are not evaluated.
+Non-explicit type import elision and transpiler-specific emission are not modeled.
+
+## Historical resolution and coverage
+
+Both graphs are built from Git tree/blob objects at immutable OIDs. Dirty files,
+installed packages, symlink targets, compiler plugins and target code are never
+read or executed for resolution. The nearest committed `tsconfig.json` (or
+`jsconfig.json`) supplies compiler options, including relative `extends`, `baseUrl`
+and `paths`. Missing/invalid config is diagnosed. Without a config, analysis uses
+TypeScript's Node-style resolution with JavaScript enabled. The report records
+the analyzer's TypeScript version; it need not match the target project's compiler.
+The dependency analyzer uses an isolated TypeScript 5.9.3 parser/resolver (without changing Strand or the extension compiler), including `bundler` resolution and modern syntax such as `using`. Package-based config extension and bundler runtime plugins remain outside scope. Malformed package metadata produces partial coverage; resolution that needs that metadata is `invalid-config`, without a fallback target.
+Project references do not provide symbol binding or build output reconstruction.
+
+Limits apply per snapshot: 2,000 source/config files, 1 MiB per file, 16 MiB total
+input and 20,000 dependency/initialization records. Source-ancestor package.json, tsconfig.json and jsconfig.json files, plus their relative config inheritance closure, share the input budget and are read first. Directory imports can load other required package metadata on demand through the same bounds. Unrelated JSON, package files and lockfiles do not consume this budget. Relative inheritance supports transitive and array parents within the same bounds. Only UTF-8 text is parsed.
+The dependency analysis budget is 30 seconds, including standalone Git range
+discovery and both snapshots. It is checked between parsing/resolution operations;
+it is not a hard interrupt inside the parser. Tour context reuses its pinned range,
+and its ordinary context generation is outside this budget. Git tree enumeration is
+bounded to 16 MiB. Up to 1,000 diagnostics per snapshot are retained with an omitted
+count. Programmatic callers may lower these limits.
+
+`coverage` reports supported source candidates, indexed/omitted files, unresolved
+edges and whether indexing completed within the supported scope. Configuration,
+parser and scope diagnostics matter even when an endpoint was found. A resolved
+target can itself be outside the indexed subset. Partial graphs produce provisional
+deltas and consumer lists; missing edges never establish independence. Submodules,
+non-JS/TS languages and installed `node_modules` are outside scope.
+
+The delta compares module endpoints, relationship, phase and loading, aligning
+Git-detected renames. Source spelling/location and repeated occurrences alone do
+not constitute new module edges. When a module edge changes, all matching source
+sites appear in the delta. Alias/config retargeting can change dependencies of an
+unchanged file. Consumer lists are one hop and include type-only edges, with phases
+retained so callers can filter them. They are not a transitive impact analysis.
+
+Every source reference contains a commit OID, Git blob OID, repository-relative
+path, UTF-16 half-open range, one-based line/column, and SHA-256 of the selected
+UTF-8 text. Links are local to the repository that generated the report. Equal
+base/head revisions and paths outside the deep-link grammar retain coordinates
+without a link. No source content is embedded in the dependency report itself.
+
+Runtime trace ingestion, resolved symbol/call graphs and visual graph layout are
+later slices. No workload is run to generate this evidence.
+
+The [validation corpus and measured results](../scripts/dependency-benchmark/README.md)
+cover labeled module edges, source evidence, bounded scale and pinned public
+repositories. The historical baseline documents compatibility and metadata gaps; the follow-up validation records their fixes. Complete indexing is not proof that runtime
+loading is valid.