Skip to content

feat(review-tutor): add structure analysis core and endpoint - #67

Merged
ElbertePlinio merged 1 commit into
mainfrom
feat/review-tutor-structure-core
Aug 25, 2026
Merged

feat(review-tutor): add structure analysis core and endpoint#67
ElbertePlinio merged 1 commit into
mainfrom
feat/review-tutor-structure-core

Conversation

@ElbertePlinio

Copy link
Copy Markdown
Member

Refs #62 — PR 1 of 4 (comparison provenance and analysis core). Stacked on #66 (base feat/review-tutor-hardening); part of the batched Review Tutor chain #65#66 → this → later #62 slices. No UI in this slice.

What changed

  • src/structure.ts (new): DOM-free unified diff parser with rename/copy/binary/mode handling, a lexical (non-executing) TypeScript/JavaScript connection analyzer (static import, re-export, require, dynamic import, side-effect imports; explicit type-only detection), comment/string/regex masking so no edge can come from a literal, candidate-path resolution (.js.ts, extensionless, index, modern extensions), and deterministic snapshot assembly.
  • Structure types and STRUCTURE_LIMITS in src/protocol.ts. rt/1 untouched (server-generated payload). Edge status includes modified for binding-only changes to an existing import (one edge, both evidence lines — never a green+rose pair). comparison.from/to encode the source-fidelity table explicitly; PR sources are patch-only partial and nothing is fetched.
  • GET /api/structure behind the existing bearer/Host/Origin gate, cached per input snapshot, 409 typed error without an input.
  • Honesty rules from the issue enforced: every edge carries exact evidence lines; out-of-scope targets read "matches no changed file: no import data outside the changed set"; hunk-less, binary, unsupported, malformed, and merge-commit inputs degrade with explicit reasons; every cap (files, edges, evidence, line length, diff lines, omission rows, per-file statements) is applied before work and recorded as an explicit omission with truncated: true.

Tested

  • 45 focused structure tests (171 in the package): renames both directions, multi-hunk and multi-line statements, semicolon-free code, regex literals and member calls, non-BMP offsets, every edge kind, duplicate merge, modified collapse, all source kinds' comparison endpoints, every cap, byte-identical determinism, route auth 401 / 409 / cache invalidation on source switch.
  • bun run check: see the CI run; local coverage 81.1% statements (structure.ts 96.5%).

Not tested

  • Real-repo scale beyond the fixtures (a large-PR run happens in PR 2 when the list renders it).
  • Dart/Rust (PR 4), one-hop neighbors (PR 3).

Risks

  • Analyzer is lexical by design; exotic syntax (regex-vs-division ambiguity) fails safe toward no edge, never a fabricated one.

Local review: serious-backend class — three independent reviewers (correctness, security/resource limits, tests/conformance), two targeted fix-verification rounds (three reviewed HEADs, the review ceiling). Disclosure for the human reviewer: the final verification found one remaining P2 (a keyword used as a member name, e.g. obj.return / 2, was misread as a regex opener and hid a real import on the same line). Its fix is the last two-line guard in opensRegex plus the test "treats a keyword-named member before a slash as division"; it was validated by the full gate but not independently re-reviewed. Not release-note-worthy (platform packages repo).

Human gate: stops at ready for human review; merge only on Elberte's authorization.

Parse the input diff without the DOM, track renames, analyze
TypeScript and JavaScript connections lexically with bounded exact
evidence, and serve a deterministic, cached, honestly partial
structure snapshot from an authenticated local route.
@ElbertePlinio
ElbertePlinio force-pushed the feat/review-tutor-structure-core branch from 497c5fa to 73f7e7e Compare August 25, 2026 19:09
@ElbertePlinio
ElbertePlinio merged commit 34fe17c into main Aug 25, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant