foundation(accuracy): B1 spans + B3 stable endpoint IDs + A4 AST↔regex parity

docs/accuracy/PARITY.md

@@ -0,0 +1,29 @@
+# AST ↔ Regex Parity — Documented Divergences
+
+Tracked under [issue #76](https://github.com/recost-dev/extension/issues/76). The
+parity test in `src/test/parity.test.ts` runs both detection paths against
+`src/test/fixtures/parity/`, normalises results to `(provider, method, line)`
+tuples, and fails on any divergence not listed below.
+
+## How to use this list
+
+- Adding a fixture: place it under `src/test/fixtures/parity/`. If both paths
+  are expected to detect the same calls, no entry is needed.
+- A divergence the test surfaces is either a bug (fix it) or a documented
+  intentional difference (add an entry below). The first option is preferred.
+- Entries are parsed by `parseAllowlist()` in `src/test/parity.ts` from the
+  fenced YAML block. Keep that block as the single source of truth.
+
+## Allowlist
+
+```yaml
+- file: wrapped-call.ts
+  reason: AST follows wrapper functions back to the SDK call; regex sees only the wrapper invocation by name.
+  astOnly: true
+- file: fetch-known-host.ts
+  reason: Multi-line fetch with an options object on subsequent lines — regex is line-based and cannot stitch the method across lines, AST sees the full call expression structurally.
+  astOnly: true
+- file: python-requests.py
+  reason: Multi-line requests.post() with URL on a separate line — regex requires URL on the same line as the call site, AST sees the full call expression structurally.
+  astOnly: true
+```

docs/accuracy/detection.md

@@ -143,6 +143,8 @@ import { client } from "../lib/clients";  // ← scanner must reach openai.ts
 
 ## A4. AST ↔ regex parity audit
 
+✅ **Landed: 2026-05-12** — see [issue #76](https://github.com/recost-dev/extension/issues/76). Parity runner lives at `src/test/parity.ts`, test entry at `src/test/parity.test.ts`, intentional-divergence allowlist at `docs/accuracy/PARITY.md`. Wired into `test:scanner` in `package.json` and runs in CI via `.github/workflows/test.yml`. First audit surfaced one regex bug (now fixed: `generic-http.ts` now does host-based provider attribution + drops the wrong-method GET fallback for multi-line fetch) and two structural multi-line cases (documented as `astOnly` in the allowlist).
+
 ### Problem
 The scanner has two detection paths for JS/TS/Python:
 - AST scanner (`src/ast/ast-scanner.ts`)
@@ -166,9 +168,9 @@ Currently there's no answer to either question. Silent disagreements mean either
 4. Fix bugs; document intentional divergences in a `PARITY.md` table; gate the test in CI.
 
 ### Acceptance criteria
-- [ ] Parity test runs in CI on every PR.
-- [ ] Every divergence the test produces is either fixed or annotated in `PARITY.md`.
-- [ ] Same `line` reported by both paths for every JS/TS/Python file where both detect a call.
+- [x] Parity test runs in CI on every PR.
+- [x] Every divergence the test produces is either fixed or annotated in `PARITY.md`.
+- [x] Same `line` reported by both paths for every JS/TS/Python file where both detect a call.
 
 ### Files
 - New: `src/test/parity.test.ts`

docs/accuracy/traceability.md

@@ -28,17 +28,17 @@ interface SourceSpan {
 }
 ```
 
-### Investigation steps
-1. Tree-sitter nodes already expose `startPosition` / `endPosition`. Wire them through `AstCallMatch`.
-2. Regex pattern scanners need a way to compute end position — easiest: re-scan with a more permissive regex that captures the full call expression, or use the source text + a balanced-paren walker.
-3. Update `EndpointRecord` / `ApiCallNode` to carry a span field; keep `line` as a derived shortcut for back-compat.
-4. Update the webview Endpoints + Graph views to highlight the span, not just the line.
+### ~~Investigation steps~~ (resolved — see implementation plan `docs/superpowers/plans/2026-05-12-b1-span-based-source-locations.md`)
+1. ~~Tree-sitter nodes already expose `startPosition` / `endPosition`. Wire them through `AstCallMatch`.~~ Done in T3/T4.
+2. ~~Regex pattern scanners need a way to compute end position — easiest: re-scan with a more permissive regex that captures the full call expression, or use the source text + a balanced-paren walker.~~ Shipped with line-wide span as the documented compromise (T7); tight regex spans require a `matchLine` API change tracked as future work.
+3. ~~Update `EndpointRecord` / `ApiCallNode` to carry a span field; keep `line` as a derived shortcut for back-compat.~~ `EndpointCallSite.span?` (T6/T9) and `ApiCallNode.span` (T8) both populated; `line` preserved alongside.
+4. ~~Update the webview Endpoints + Graph views to highlight the span, not just the line.~~ Reveal-by-span landed in `webview-provider`'s `openFile` handler and `ResultsPage` (T10).
 
 ### Acceptance criteria
-- [ ] `EndpointRecord` exposes `span: SourceSpan` with all four numbers populated.
-- [ ] Multi-line calls (>3 lines) have `endLine > startLine`.
-- [ ] Clicking a detection in the webview opens the editor with the span selected, not just the line scrolled into view.
-- [ ] Existing tests assertions on `line` continue to work (derive from span).
+- [x] `EndpointRecord` exposes `span: SourceSpan` with all four numbers populated. *(via `EndpointCallSite.span?` — optional only because legacy/synthetic inputs may omit it.)*
+- [x] Multi-line calls (>3 lines) have `endLine > startLine`. *(AST path — verified by `src/test/ast-call-visitor.test.ts` "span: multi-line call has endLine > startLine".)*
+- [ ] Clicking a detection in the webview opens the editor with the span selected, not just the line scrolled into view. *(Code landed in T10 commit `69ca79d`; **pending manual EDH verification** — F5 the dev host, scan a workspace with a multi-line OpenAI call, click the endpoint row, confirm full-call selection.)*
+- [x] Existing tests assertions on `line` continue to work (derive from span). *(`line` is preserved alongside `span` everywhere; all affected unit tests pass.)*
 
 ### Files
 - `src/ast/call-visitor.ts`
@@ -48,6 +48,8 @@ interface SourceSpan {
 - `src/intelligence/types.ts` (ApiCallNode)
 - `webview/src/components/ResultsPage.tsx` (open-file IPC)
 
+✅ Landed: 2026-05-12 on branch `foundation-parser-accuracy`. Acceptance criteria 1, 2, 4 automated-verified; #3 awaiting manual EDH check.
+
 ---
 
 ## B2. Dual locations for cross-file resolved calls
@@ -121,26 +123,28 @@ Key properties:
 - **Includes enclosing function name** — disambiguates two calls to the same method in the same file.
 - **URL templates masked** — `/users/123` and `/users/456` get the same ID (mask numeric IDs, UUIDs, etc.).
 
-### Investigation steps
-1. Add an enclosing-function-name extractor in `call-visitor.ts` (walk parent nodes for `function_declaration`, `method_definition`, `arrow_function` parent var name).
-2. Add `maskUrlDynamicParts(url)` in a util module — replaces numeric segments, UUIDs, and known ID patterns with `:id`.
-3. Wire into a single `computeEndpointId()` function. Use it in `EndpointRecord` construction.
-4. Migration: existing persisted state keyed by old IDs needs a fallback — log warning, ignore the old state, write new IDs on next scan.
+### ~~Investigation steps~~ (resolved — see implementation plan `docs/superpowers/plans/2026-05-12-b3-stable-endpoint-ids.md`)
+1. ~~Add an enclosing-function-name extractor in `call-visitor.ts` (walk parent nodes for `function_declaration`, `method_definition`, `arrow_function` parent var name).~~ Done in T2 (new module `src/ast/enclosing-function.ts`, used by both `endpoint-id.ts` and `ast-scanner.ts`).
+2. ~~Add `maskUrlDynamicParts(url)` in a util module — replaces numeric segments, UUIDs, and known ID patterns with `:id`.~~ Done in T1 (`src/scanner/url-template.ts`).
+3. ~~Wire into a single `computeEndpointId()` function. Use it in `EndpointRecord` construction.~~ Done in T3/T5/T6: `src/scanner/endpoint-id.ts` is the canonical hasher; `intelligence/builder.ts` and `scan-results.ts` both consume it; `webview-provider.ts`'s parallel synthetic-ID minter was migrated alongside (T7 scope expansion).
+4. ~~Migration: existing persisted state keyed by old IDs needs a fallback — log warning, ignore the old state, write new IDs on next scan.~~ Done in T7: `pruneSavedScenariosAgainst` drops saved simulator scenarios whose referenced endpoint IDs are absent from the current scan and persists the cleaned list to `recost.simulatorScenarios`. Includes a zero-endpoint guard to avoid wiping all scenarios on misconfigured/empty scans.
 
 ### Acceptance criteria
-- [ ] Endpoint IDs survive moving a call ±20 lines in the same file.
-- [ ] Endpoint IDs survive renaming a containing variable but not the function.
-- [ ] Two distinct calls to `openai.chat.completions.create` in the same file but different functions get distinct IDs.
-- [ ] `/api/users/123` and `/api/users/456` get the same ID.
-- [ ] Saved simulator scenarios and suppressed findings survive a scan after non-structural code changes.
+- [x] Endpoint IDs survive moving a call ±20 lines in the same file. *(T3 + T8: `computeEndpointId` has no `line`/`column`/`span` input; verified by tests "ID survives ±20 line move" and "end-to-end: same call, moved 20 lines, gets the same ID".)*
+- [x] Endpoint IDs survive renaming a containing variable but not the function. *(T3 test "ID survives renaming an unrelated containing variable"; T3 test "ID changes when enclosing function changes".)*
+- [x] Two distinct calls to `openai.chat.completions.create` in the same file but different functions get distinct IDs. *(T8 test "end-to-end: two calls in same file but different functions diverge"; supported by collision-disambiguation fallback `_L<line>` in `builder.ts` for same-function same-URL repeats.)*
+- [x] `/api/users/123` and `/api/users/456` get the same ID. *(T1 url-template masks numeric segments to `:id`; T3 test "URLs differing only by numeric ID produce the same endpoint ID".)*
+- [~] Saved simulator scenarios and suppressed findings survive a scan after non-structural code changes. *(Code path verified: stable IDs mean a re-scan after non-structural change produces the same IDs, so `pruneSavedScenariosAgainst` keeps scenarios. T7 Step 4 — F5 EDH, save a scenario, edit an unrelated file, re-scan, confirm scenario still loads — is **pending manual verification**.)*
 
 ### Files
 - New: `src/ast/enclosing-function.ts`
 - New: `src/scanner/url-template.ts`
-- `src/scanner/types.ts` (EndpointRecord id field)
-- Wherever endpoint IDs are currently generated (search for `id:` in scan-results / webview-provider)
+- New: `src/scanner/endpoint-id.ts` (+ test)
+- Modified: `src/analysis/types.ts` (`ApiCallInput.enclosingFunction?`), `src/ast/ast-scanner.ts` (emit `enclosingFunction` on every match), `src/scanner/core-scanner.ts` (pipe through), `src/intelligence/builder.ts` (use `computeEndpointId` + `_L<line>` collision fallback), `src/scan-results.ts` (use `computeEndpointId` + Set-based collision check), `src/webview-provider.ts` (parallel synthetic-ID migration + `pruneSavedScenariosAgainst`).
 
 ### Depends on
-- B1 (spans help identify the enclosing function reliably).
+- B1 (spans help identify the enclosing function reliably). *(B1 landed first; B3's `enclosingFunctionName` walker uses `node.parent` so the dependency is documentary, not blocking.)*
+
+✅ Landed: 2026-05-12 on branch `foundation-parser-accuracy`. Acceptance criteria 1–4 automated-verified across `src/test/url-template.test.ts`, `src/test/enclosing-function.test.ts`, and `src/test/endpoint-id.test.ts` (13 cases). Criterion #5 is code-complete but awaits manual EDH verification per T7 Step 4.
 
 ---