Add evidence-backed Structure view to Review Tutor

[ElbertePlinio]

Goal

Add an evidence-backed Structure view to Review Tutor so a reviewer can understand how changed files connect and how dependency topology changes without reading every file sequentially.

Parent work: #59
Current UI PR: #61

Product contract

• Diff remains the default and source of truth.
• Diff | Structure switches views over the same immutable input snapshot.
• Structure shows deterministic import/dependency topology, not inferred runtime architecture.
• Changed files are the default scope; optional one-hop neighbors provide context.
• Every shown connection has exact source or diff-line evidence.
• Added connections use semantic green, removed connections use dashed rose, unchanged context is muted, and the selected item owns the single ember highlight.
• Selecting a file or connection opens a compact evidence panel with Open in Diff; tutor integration comes only after the graph is trustworthy.
• Mobile and high zoom default to an accessible Connections list rather than forcing a cramped graph.
• Partial analysis is explicit: say no import data, never no dependencies.

Source fidelity

Source	Honest comparison
Worktree	index → working-tree patch
Staged	HEAD → index
Commit	first parent → commit; root/unsupported merge cases degrade explicitly
Range	merge-base → target
Pull request	base SHA → head SHA only when required Git objects are local
Pasted code	unavailable; do not guess

Remote PR objects must not be fetched or checked out automatically. When unavailable locally, provide a clearly labeled patch-only partial result.

Acceptance criteria

• Parse changed files, additions/deletions, and renames once in a DOM-free server module.
• Produce deterministic, sorted Structure snapshots from a bounded local analyzer.
• Support TypeScript/JavaScript import, re-export, require, and dynamic-import edges first.
• Represent added, removed, unchanged, unresolved, partial, truncated, and unavailable states honestly.
• Attach bounded exact evidence lines to every edge; no edge may exist only because a model inferred it.
• Limit scope to changed files plus at most one-hop neighbors.
• Expose one bearer-authenticated, Host/Origin-protected local endpoint.
• Add an accessible Connections list with evidence and Diff jumps before the graph canvas.
• Add a deterministic DOM/SVG Structure graph with stable positions and keyboard navigation.
• Preserve the existing diff, tutor, configuration, learning-log, responsive, security, and persistence behavior.
• Add Dart support next and Rust after TypeScript/JavaScript is proven.
• Pass functional, security, resource-limit, keyboard, responsive, and rendered visual acceptance.
• Stop at Ready for human review; Elberte alone authorizes merges.

Non-goals

• No whole-repository hairball, transitive expansion, call graph, runtime tracing, architecture score, or health badge.
• No LLM-generated edges or architecture verdicts.
• No cloud analysis, daemon, telemetry, external assets, source writes, PR actions, or automatic Git fetch/checkout.
• No force-directed physics, decorative animation, multicolor edge palette, or canvas-only inaccessible graph.
• No speculative analyzer plugin system.

PR plan

• PR 1 — comparison provenance and analysis core

  • Depends on: feat(review-tutor): redesign guided review interface #61 finished and human-approved.
  • Add DOM-free diff parsing with rename tracking.
  • Capture honest source comparison metadata.
  • Add deterministic TypeScript/JavaScript connection analysis and bounded evidence.
  • Add the authenticated Structure endpoint; no UI.
  • Validation: focused graph/protocol/security/resource tests plus bun run check.
  • Link: pending.

• PR 2 — accessible Connections list

  • Depends on: PR 1.
  • Add Diff | Structure, partial-state disclosure, per-file changed connections, compact evidence rows, and Open in Diff.
  • Make List mode the keyboard, screen-reader, mobile, and high-zoom baseline.
  • Validation: executable page tests and browser proof at 1440, 860, 390, and 400% zoom.
  • Link: pending.

• PR 3 — deterministic Structure graph

  • Depends on: PR 2.
  • Add stable layered DOM/SVG layout, directory clustering, node/edge selection, bounded filtering, and one-hop neighbor toggle.
  • Keep mobile/high zoom on List mode unless the user explicitly opens the graph.
  • Validation: small, partial, truncated, clustered, keyboard-only, and resize/zoom browser acceptance.
  • Link: pending.

• PR 4 — mobile-language and tutor integration

  • Depends on: PR 3.
  • Add Dart, then Rust, using private language-table entries rather than a plugin system.
  • Add Ask about this file/connection using exact evidence as the existing tutor selection.
  • Complete final design-lead, local-review, CI, and human-review gates.
  • Link: pending.

Traceability

Acceptance area	Slice	Validation	Status
Honest source provenance and deterministic edges	PR 1	graph fixtures across worktree/staged/commit/range/PR/paste	pending
Auth, limits, cancellation, and failure containment	PR 1	server security and bounded-read tests	pending
Evidence-first architectural review	PR 2	runtime DOM tests and Diff-jump browser flow	pending
Diagram comprehension and scale	PR 3	rendered small/large/partial graph acceptance	pending
Flutter/mobile relevance and tutor reuse	PR 4	Dart/Rust fixtures and real tutor question flow	pending

Resource and honesty limits

Start with conservative caps and return a valid partial snapshot when exceeded. The implementation plan must bound changed files, nodes, edges, analyzer output, evidence per edge, line length, runtime, and child processes. Binary, oversized, unsupported, aliased, or unresolved inputs are omitted with explicit reasons rather than guessed.

Feature flag decision

No flag while Review Tutor remains a private, unreleased prototype and each user-visible slice is independently complete. If packaging or release exposure lands before this work is complete, stop and add a default-off reviewTutorStructureView flag with the full enable-and-remove lifecycle before merging user-visible graph work.

Validation

bun run typecheck
bun run lint
bun run test
bun run test:coverage
bun run build
bun run check

Rendered proof must cover 1440px desktop, the 860px boundary, 390px mobile, and 400% zoom. Final aesthetic acceptance returns to the named Pickforge design lead.

Status

Current status: Deferred / planned

Do not start implementation until #61 is finished, manually approved, and its final disposition is recorded in #59.

Next action when resumed: run a read-only TypeScript/JavaScript analysis spike on several real PR snapshots and lock the analyzer payload before source edits.

[ElbertePlinio]

Agent plan — resumed

Per the recorded next action: running a read-only TypeScript/JavaScript analysis spike on real PR snapshots now to lock the analyzer payload before source edits. PR 1 (comparison provenance + analysis core) follows in worktree feat/review-tutor-structure-core, stacked on #64's branch so Elberte can review the whole Review Tutor chain (#65 → #64 → #62 slices) in one batch. Each slice still stops at Ready for human review.

Current status: In progress (spike)
Next: lock analyzer payload, dispatch PR 1 implementation

[ElbertePlinio]

Progress update — PR 1 (analysis core) built, under review

• read-only spike on real snapshots (static imports only in-repo; explicit type imports via verbatimModuleSyntax; .js→.ts bundler specifiers; no tsconfig aliases)
• DOM-free diff parser with rename tracking, lexical TS/JS analyzer, deterministic cached snapshot, GET /api/structure behind the existing auth (149 focused tests, full check 442 passed | 25 skipped)
• serious-backend panel (3 independent reviewers): 1 P1 (semicolon-free code could fabricate an edge) + ~10 P2 (regex/property-call false edges, non-BMP offsets, silent caps, rename side-awareness, multi-line status) — fix batch in progress
• targeted fix verification, then PR stacked on feat(review-tutor): coalesce answer streaming and add tab question ownership #66

Schema decisions locked for PR 2–4:

• StructureEdge.status gains modified: a binding-only change to an existing import collapses to one edge with both evidence lines (never green + rose for the same pair).
• comparison.from/comparison.to carry the fidelity table explicitly (e.g. index → working tree); PR = patch-only partial, never fetched.
• Out-of-scope targets read "matches no changed file: no import data outside the changed set" — one-hop neighbors remain PR 3.

Next: fix verification, PR 1 ready for human review (batched chain #65 → #66 → PR 1).

[ElbertePlinio]

PR 1 is open: #67 (stacked on #66) at 82ebb32.

• analysis core + GET /api/structure; 47 focused structure tests; full check 466 passed | 25 skipped, 81.25% statements
• 3-reviewer panel + two fix-verification rounds (review ceiling); the last two-line opensRegex guard (keyword-named member before / is division) is disclosed in the PR body as validated-but-not-re-reviewed
• CI on feat(review-tutor): add structure analysis core and endpoint #67
• human review (batched chain feat(review-tutor): honor session model scope and add package docs #65 → feat(review-tutor): coalesce answer streaming and add tab question ownership #66 → feat(review-tutor): add structure analysis core and endpoint #67)

Next: PR 2 (accessible Connections list) — design contract first, stacked on #67.

[ElbertePlinio]

Design contract — Review Tutor Structure PR 2 (Connections list)

Status: locked
Design lead: Fable 5 (this session)
Mode: targeted (inside the existing Review Tutor product window)

Outcome

• User and job: a reviewer who wants to know how the changed files connect without reading every file; keyboard, screen-reader, mobile, and high-zoom users get this as the baseline (graph is PR 3).
• Desired result: a Diff | Structure | Learning log peer view where Structure lists changed files and their evidence-backed connections, discloses partial analysis honestly, and jumps to the exact diff line.
• Success evidence: rendered states at 1440 / 860 / 390 / 360@4x; keyboard-only walkthrough; page tests for fetch, states, jump, and a11y semantics.

Context

• Product/platform: local browser page served by the Pi extension; vanilla DOM in page-script.ts string, styles in page-styles.ts, static shell in page.ts; happy-dom tests.
• Existing system to preserve: dark operator chrome, Geist/Geist Mono tokens (--ember, --green, --rose, --amber, --muted, hairlines, radii, --control-h-touch), the tablist pattern (view-diff/view-log, setView), sticky file heads, live-region announcements, stable stateful nodes, 860px stacked mode, mobile drawer.
• Repo constraints: no framework, no external assets, no protocol change (GET /api/structure from PR 1 is the only new call), no server change in this slice.
• Data: StructureSnapshot from PR 1 (files[], edges[] with status added|removed|modified|unchanged, typeOnly, kind, bounded evidence[], comparison.from/to/partial/reasons, limits.truncated/omitted).

Direction

• Concept: a dense, truthful ledger of connections — file groups with connection rows and inline evidence — not a dashboard.
• Hierarchy and primary action: 1) comparison line + partial disclosure; 2) file groups (path, status, ±counts); 3) connection rows (target, kind, status); 4) evidence lines with Open in Diff as the primary action. Selecting a row is the single ember focal point.
• Density/rhythm: same row rhythm as the diff file heads; connection rows 32px (44px on touch); evidence in mono 12px; group headers sticky like .file-head.
• Type/color/shape: paths in Geist Mono; kind and type as small uppercase mono chips (existing label style); semantic status: added = --green text + solid 2px left rule, removed = --rose + dashed left rule, modified = --amber chip "edited" with muted text, unchanged = --muted; selected row = ember outline/rule, exactly one at a time. No new colors.
• Motion: none new; expand/collapse instant; respect reduced motion.
• References — take: GitHub "files changed" grouping density; VS Code problems panel evidence rows. Reject: force-directed graphs, badges/scores, multicolor edge palettes, decorative animation.
• Anti-goals: no graph canvas, no whole-repo listing, no inferred edges, no verdicts, no "no dependencies" wording.

Behavior

• Main flow: click Structure tab → first visit per input fetches /api/structure (status "Analyzing structure…" in the live region) → list renders → click/Enter on a connection row toggles its evidence (aria-expanded) and makes it the selected row → Open in Diff on an evidence line switches to Diff, navigates to that file, scrolls the line into view, and moves focus to it (reuse existing file navigation and line anchoring). Input change resets Structure state and refetches on next visit.
• Required states: no input (same empty pattern as Diff); loading; error (typed message + Retry button); analyzed but zero connections ("No connections among changed files. Unchanged neighbours are outside this view."); partial/truncated disclosure (amber hairline notice: one sentence + <details> "N reasons" list); unanalyzed file (group shows the exact reason inline, muted); removed file (rose status, removed rows); modified edge; type-only chip; selected + expanded row; focus-visible on every control.
• Responsive: ≥1040 shares the diff pane width; 860 stacked mode unchanged; ≤520 rows wrap target path under the kind chip, controls ≥44px; 360@4x no horizontal overflow, sticky headers still readable.
• A11y: tab added to the existing tablist with roving tabindex; each file group is a section with aria-labelledby; rows are buttons with aria-expanded and aria-controls; evidence lists are ul; status conveyed in text (chip) not color alone; contrast ≥4.5:1 for all text; announcements on view switch, load, error; prefers-reduced-motion respected.

Implementation boundary

• Reuse: tablist + setView, .file-head, label/chip styles, announce, notice card style, existing file/line navigation helpers, existing fetch/auth helpers (bearer from session).
• May change: page-script.ts (structure state, fetch, render, jump), page-styles.ts (structure styles), page.ts (static shell: tab + section), test/page.test.ts or a new test/structure-page.test.ts.
• Must not change: diff rendering, selection, composer, tutor/SSE flow, learning log, config rail/drawer, protocol/server, security headers, existing tests' expectations.
• Design deviations require: return to the design lead; update this contract.

Acceptance proof

• Sizes: 1440×900, 860×900, 390×844, 360×800 at device scale 4 (400% zoom proxy).
• Captures: list loaded (mixed statuses + type chip), row selected + evidence expanded, partial notice open, unanalyzed + removed file groups, empty (zero connections), error with Retry, keyboard focus ring on a row and on Open in Diff, Diff view after jump with the target line in view.
• Interaction: tab switching announces; Open in Diff lands focus on the line; Escape/Tab order sane; no ember outside the selected row.
• Automated: page tests for fetch-once-per-input, all states, jump wiring, a11y attributes, no horizontal overflow at 360; bun run check.

[ElbertePlinio]

PR 1 #67 is Ready for human review at 82ebb32 (base feat/review-tutor-hardening, mergeable).

• required CI passed: check, Gitleaks, Dependency audit, Database (run 32671827836)
• panel + fix verification: clean except the disclosed final two-line guard (see PR body)

PR 2 (Connections list) is in implementation under the locked design contract above, stacked on #67. No merge attempted; chain #65 → #66 → #67 → PR 2 awaits one batched human review.

[ElbertePlinio]

PR 2 (Connections list) is open and stacked on #67; design accepted against DESIGN-PRINCIPLES.md (left status rules and empty containers removed); review panel running. PR 1 #67 is green on main and awaiting Elberte's merge.

[ElbertePlinio]

Design contract amendment (PR 2, design lead): group heads are not sticky, and the +N −M counts are removed from structure group heads (they duplicate the Diff file heads; removing them also fixes path truncation at 360px). File groups with no rows and no reason are not rendered. Rationale: DESIGN-PRINCIPLES.md rules 1, 3, 5. Panel findings (2 correctness P2s, 7 UI P2s, test-integrity gaps) are being fixed in one batch on #71.