@clear-capabilities/agentic-security-scanner 0.136.9 → 0.137.1

package/src/ir/parser-php.js

@@ -10,12 +10,35 @@
 //   - return
 //   - foreach as loop-header + assign
 //   - PHP superglobals ($_GET, $_POST, $_REQUEST, etc.) as ident sources
+//   - control flow (R8): `if`/`else`/`while`/`foreach`/`try`/`catch`/
+//     `finally`/`switch` bodies are recursed into — the statement splitter
+//     now flushes on a closing `}` (see the `}`-flush comment near
+//     `_splitStatements` below) instead of only on `;`, so a sink nested
+//     inside a braced control-flow body is reachable rather than being
+//     dropped or folded into a bogus call node. This took three fix rounds
+//     to get line-number-exact (see the PRD R8 status entry in
+//     `docs/DETECTION_GAP_REMEDIATION_PRD.md` for the full history) — the
+//     CFG shape itself was correct from the first round. NOTE: C-style
+//     `for` is deliberately NOT in this list — PHP has no `for`-loop
+//     recognizer at all (never in R8's scope, still true today); a sink
+//     inside `for ($i=0; $i<3; $i++) { ... }` still folds into a bogus
+//     `call:for` node and is lost entirely, the exact failure mode R8
+//     exists to fix, unfixed for this one construct.
 //
 // What we do NOT model:
 //   - arrow functions (fn($x) => expr)
 //   - traits / interfaces
 //   - anonymous classes
-//   - control flow (if/for/while/switch) — body is straight-line
+//   - C-style `for` loops (see the note above — no recognizer exists)
+//   - the PHP 8 `match` expression (analogous gap to Java's arrow-form
+//     `switch` — this is the one modern control-flow SHAPE R8 did not
+//     cover, as opposed to the R8 fix's own scope, which is bodies of
+//     control-flow statements PHP already recognized)
+//   - `elseif`/`else if` chains (pre-existing, not touched by R8)
+//   - `if`/`else`'s pre-existing greedy-capture-group bug: the then-body
+//     capture group unconditionally swallows through to the else-body's
+//     own closing `}`, dropping the else-body's first statement
+//     (pre-existing, confirmed present before R8, not fixed by it)
 
 import * as crypto from 'node:crypto';
 import { callSitesFromCfg } from './call-sites.js';
@@ -30,37 +53,221 @@ const FUNC_RE = new RegExp(
   '(?:\\s*:\\s*\\??[A-Za-z_]\\w*)?' +   // optional return type
   '\\s*\\{', 'g');
 
+// Returns `{ text, line }[]` — `line` is the 1-indexed line, relative to the
+// START of `body`, of the first non-whitespace character of that statement.
+// This is computed from the ACTUAL scan position (a running `curLine`
+// incremented on every physical `\n` encountered, including ones skipped
+// inside a `//` comment) rather than by re-counting newlines inside the
+// already-trimmed statement text afterwards — that reconstruction is lossy:
+// `.trim()` discards any leading blank lines (or blanked-out characters —
+// see parser-php.js's `_blankSpans`/`_buildCfg` module-level lowering) before
+// a statement's real content, so a caller that tried to recover the line by
+// counting embedded newlines would silently undercount by exactly the
+// number of blank lines that preceded the statement. This was the root
+// cause of PHP module-level findings reporting the wrong line and, in turn,
+// making the line-scoped `agentic-security-ignore` suppression pragma inert
+// for them (Finding 2 of the R14(b) final whole-branch review).
+// True when the next non-whitespace, non-comment token starting at
+// `body[i + 1]` is one of the `else`/`catch`/`finally` continuation
+// keywords — the ones that must stay glued to a preceding `}` rather than
+// starting a new split entry (see the R8 comment at the `}`-flush call
+// site below). Both whitespace AND comments (`//` and `/* */`) are
+// skipped, mirroring `_splitStatements`' own comment-skip logic.
+//
+// R8 fix round 3: whitespace-only skipping was a real regression this
+// task introduced (not a pre-existing limitation, as an earlier version of
+// this comment incorrectly claimed). `} /* mid */ else { ... }` or
+// `}\n// explain\nelse { ... }` are unremarkable, real PHP shapes — a
+// comment explaining WHY an else/catch/finally branch exists is a normal
+// thing to write immediately above it. With whitespace-only skipping, the
+// comment defeated the lookahead, the `}`-flush fired anyway, and the
+// entire `else`/`catch`/`finally` body was silently dropped from the CFG.
+// For `catch`/`finally` specifically this is confirmed a clean, provable
+// fix (see the `catch`/`finally` regression tests in
+// `test/parser-php-control-flow.test.js`, which fail without this change
+// and pass with it) — `_scanTryCatchFinally`'s balanced-brace scanning has
+// no competing bug to interact with. For `else` specifically, this
+// lookahead fix is still correct and necessary, but its OUTCOME is masked
+// in practice by `ifMatch`'s own separate, pre-existing, out-of-scope
+// greedy-capture bug (the then-body group unconditionally swallows
+// through to the else-body's own closing `}`, dropping the else body
+// regardless of whether a comment was ever involved — confirmed by
+// testing commit `735ef63`, before this task started, with an identical
+// comment-free else fixture: already broken then, for an unrelated
+// reason). `ifMatch` and `_scanTryCatchFinally` both already tolerate an
+// ordinary `\s*`/whitespace gap between `}` and the keyword; skipping
+// comments here too keeps this lookahead in sync with what those
+// recognizers can actually parse once the flush is correctly suppressed.
+function _continuationKeywordAhead(body, i) {
+  let j = i + 1;
+  let moved = true;
+  while (moved) {
+    moved = false;
+    while (j < body.length && /\s/.test(body[j])) { j++; moved = true; }
+    if (body[j] === '/' && body[j + 1] === '/') {
+      while (j < body.length && body[j] !== '\n') j++;
+      moved = true;
+      continue;
+    }
+    if (body[j] === '/' && body[j + 1] === '*') {
+      j += 2;
+      while (j < body.length && !(body[j] === '*' && body[j + 1] === '/')) j++;
+      if (j < body.length) j += 2; // past the closing '*/'
+      moved = true;
+      continue;
+    }
+  }
+  for (const kw of ['else', 'catch', 'finally']) {
+    if (body.startsWith(kw, j)) {
+      const after = body[j + kw.length];
+      if (after === undefined || !/\w/.test(after)) return true;
+    }
+  }
+  return false;
+}
+
 function _splitStatements(body) {
   const out = [];
   let buf = '';
+  let bufLine = null; // line of the first non-whitespace char seen in `buf` so far
+  let curLine = 1;    // line of body[i], the character currently under the cursor
   let depth = 0;
   let inStr = null;
   let escape = false;
+  const push = (c) => {
+    buf += c;
+    if (bufLine === null && !/\s/.test(c)) bufLine = curLine;
+  };
   for (let i = 0; i < body.length; i++) {
     const c = body[i];
-    if (escape) { buf += c; escape = false; continue; }
+    if (escape) { push(c); escape = false; if (c === '\n') curLine++; continue; }
     if (inStr) {
-      buf += c;
-      if (c === '\\') { escape = true; continue; }
+      push(c);
+      if (c === '\\') { escape = true; if (c === '\n') curLine++; continue; }
       if (c === inStr) inStr = null;
+      if (c === '\n') curLine++;
       continue;
     }
-    if (c === '"' || c === '\'') { inStr = c; buf += c; continue; }
+    if (c === '"' || c === '\'') { inStr = c; push(c); continue; }
     if (c === '/' && body[i + 1] === '/') {
       while (i < body.length && body[i] !== '\n') i++;
+      // R8 fix round 2: push the newline that terminated the comment into
+      // `buf` (not just bump `curLine`). Comment text itself is still
+      // dropped (never pushed) — only the LINE it displaced is preserved,
+      // same principle `_blankSpans`/`_blank` already use elsewhere in
+      // this file (blank content out, keep line structure intact, don't
+      // delete it outright). Without this, the flushed statement text
+      // this comment lived inside ends up with FEWER newlines than the
+      // real source has, so `_buildCfg`'s newline-counting line
+      // computation for a nested body silently undercounts by exactly the
+      // number of newlines lost to comments — the sink line reported to
+      // the caller (and therefore the `agentic-security-ignore` pragma
+      // line it must match) is wrong for any control-flow body containing
+      // an otherwise-unrelated `//` comment.
+      if (i < body.length) { push('\n'); curLine++; }
+      continue;
+    }
+    if (c === '/' && body[i + 1] === '*') {
+      // Block comment (incl. PHPDoc, e.g. `/** @param string $x */`).
+      // Skip to the matching `*/`, counting any newlines crossed so line
+      // tracking stays accurate for whatever follows — same contract the
+      // `//` handling above upholds. Bounded even when unterminated (`i`
+      // simply runs to `body.length` and the outer `for` loop ends).
+      // R8 fix round 2: same newline-preservation fix as the `//` handler
+      // above, but a block comment can span MANY lines — push one `\n`
+      // into `buf` for every newline it displaces, not just one, or a
+      // multi-line block comment inside a control-flow body would still
+      // undercount by (newlines - 1).
+      i += 2; // past the opening '/*'
+      while (i < body.length && !(body[i] === '*' && body[i + 1] === '/')) {
+        if (body[i] === '\n') { curLine++; push('\n'); }
+        i++;
+      }
+      if (i < body.length) i++; // land on the '/' of '*/'; skipped, contributing no statement text
       continue;
     }
     if (c === '{' || c === '(' || c === '[') depth++;
-    if (c === '}' || c === ')' || c === ']') depth--;
+    if (c === '}' || c === ')' || c === ']') {
+      depth--;
+      // R8: a `}` that returns the shared depth counter to 0 ends a
+      // braced control-flow body (if/while/foreach/try/switch) — flush a
+      // statement boundary here too, not just on `;` at depth 0. PHP has
+      // no `{}`-based object/array-literal syntax (arrays use `[...]`,
+      // tracked by the same counter but not this trigger), so this cannot
+      // mis-fire mid-expression the way it would for a language with `{}`
+      // object initializers. A `}` that closes a lambda/closure body
+      // passed as a call argument (`usort($arr, function($a,$b){...})`)
+      // does NOT trigger this — that `}` returns depth from 2 to 1 (still
+      // inside usort's outer `(`), not to 0.
+      //
+      // EXCEPTION: do not flush when the next non-whitespace token is
+      // `else`, `catch`, or `finally` — those must stay glued onto the
+      // SAME statement as the preceding `}` for `ifMatch` and the
+      // try/catch/finally recognizer in `_buildCfg` to see
+      // `if (...) { ... } else { ... }` or
+      // `try { ... } catch (...) { ... } finally { ... }` as one
+      // contiguous blob (`ifMatch` is anchored end-to-end with `$` and
+      // spans the whole construct; the try/catch/finally recognizer scans
+      // the whole construct by hand for the same reason). A blind
+      // flush-on-every-`}` here would silently split `if`/`else` and
+      // multi-clause `try` into two statements each, which is a strictly
+      // WORSE regression than the "must be last statement in scope" bug
+      // this task fixes — an
+      // `else`/`catch`/`finally` body would be dropped from the CFG
+      // entirely, not just occasionally mis-split.
+      if (c === '}' && depth === 0 && !_continuationKeywordAhead(body, i)) {
+        push(c);
+        const t = buf.trim();
+        if (t) out.push({ text: t, line: bufLine ?? curLine });
+        buf = '';
+        bufLine = null;
+        continue;
+      }
+    }
     if (c === ';' && depth === 0) {
       const t = buf.trim();
-      if (t) out.push(t);
+      if (t) out.push({ text: t, line: bufLine ?? curLine });
       buf = '';
+      bufLine = null;
       continue;
     }
-    buf += c;
+    // R8: a `switch` body's `case <expr>:` / `default:` labels are
+    // terminated by `:`, not `;` or `}` — without this, the label text
+    // stays glued onto whatever real statement follows it (no `;` or `}`
+    // separates them), and that combined blob then fails BOTH the
+    // assignment and call-statement shapes in `_lowerStmt` (neither
+    // starts with `$var =` nor a bare identifier-call), silently
+    // dropping the case body's first statement entirely — worse than the
+    // brief's anticipated "label falls through to `_lowerStmt` and
+    // returns null harmlessly" behavior. Scoped tightly (buf must be
+    // EXACTLY `case <expr>` or `default`) so it can't mis-fire on a
+    // ternary's `:`, which leaves buf holding something that never
+    // matches either pattern.
+    //
+    // Excludes `::` (PHP's static-access / class-constant / PHP 8.1
+    // enum-case operator, e.g. `case Foo::BAR:` or `case Status::Active:`)
+    // via the adjacent-char check below — without it, `case Foo::BAR:`'s
+    // FIRST `:` already makes buf read "case Foo", which matches the case
+    // pattern just as eagerly as the real terminating `:` after `BAR`
+    // does, mis-splitting mid-token and dropping that case's body. Both
+    // colons of a `::` pair are skipped (checking one neighbor character
+    // each is enough: the first colon sees `body[i+1] === ':'`, the
+    // second sees `body[i-1] === ':'`), so only a genuine lone `:` can
+    // ever terminate a label.
+    if (c === ':' && depth === 0 && body[i + 1] !== ':' && body[i - 1] !== ':') {
+      const t = buf.trim();
+      if (/^case\s+[\s\S]+$/.test(t) || t === 'default') {
+        out.push({ text: t, line: bufLine ?? curLine });
+        buf = '';
+        bufLine = null;
+        continue;
+      }
+    }
+    push(c);
+    if (c === '\n') curLine++;
   }
-  if (buf.trim()) out.push(buf.trim());
+  const t = buf.trim();
+  if (t) out.push({ text: t, line: bufLine ?? curLine });
   return out;
 }
 
@@ -129,9 +336,21 @@ function _lowerExpr(text) {
     return { kind: 'call', callee: funcCall.callee, args: _splitTopLevelCommas(funcCall.argsText).map(_lowerExpr) };
   }
   // Concat with .
+  //
+  // The `parts.length > 1` guard is load-bearing, not defensive tidiness:
+  // when every `.` in `s` is nested inside brackets or strings (e.g.
+  // `s = '"y.z"'` in `["health" => "check.status"]`), `_splitTopLevelDot`
+  // returns `[s]` — the input unchanged, as a single part — and mapping
+  // `_lowerExpr` over it recurses on the IDENTICAL string forever (stack
+  // overflow). Before R14(b) this was only reachable from inside function
+  // bodies; the module-level lowering now feeds every top-level statement
+  // through here too, so real files (e.g. a top-level array literal with a
+  // dotted string value) hit it and the per-file catch in `ir/index.js`
+  // silently dropped the whole file from Layer-2 analysis. Same shape as
+  // parser-cs.js's `_splitTopLevelPlus` guard.
   if (s.includes('.') && /["'\$]/.test(s)) {
-    const parts = _splitTopLevelDot(s).map(_lowerExpr);
-    return { kind: 'tpl', parts };
+    const rawParts = _splitTopLevelDot(s);
+    if (rawParts.length > 1) return { kind: 'tpl', parts: rawParts.map(_lowerExpr) };
   }
   // Member: $obj->prop
   if (/^\$[\w]+(?:->[\w]+)+$/.test(s)) {
@@ -246,6 +465,70 @@ function _qid(file, name, line, body) {
   return `${file}::${name}@${line}#${sha}`;
 }
 
+// FUNC_RE's leading alternation `(?:^|[\n;{}]|<\?php|<\?)` matches a single
+// "boundary" character/token that belongs to whatever precedes the function
+// (a statement terminator, a brace, or the PHP open tag) — not to the
+// function itself. `m.index` always points at the START of that boundary,
+// so including it verbatim in the function's span would blank away e.g. the
+// `;` that terminates the PRECEDING top-level statement once the whole file
+// is lowered in a single _buildCfg pass (see _blankSpans below), silently
+// merging that statement with whatever gap text follows the function. This
+// returns how many characters of the boundary token were actually consumed
+// so the function's span can be made to start right after it.
+function _funcBoundaryLen(code, idx) {
+  if (idx > 0) {
+    const c = code[idx];
+    if (c === '\n' || c === ';' || c === '{' || c === '}') return 1;
+  }
+  if (/^<\?php/i.test(code.slice(idx, idx + 5))) return 5;
+  if (/^<\?/.test(code.slice(idx, idx + 2))) return 2;
+  return 0;
+}
+
+// Blank out every real function's span in a COPY of the full source
+// (replace its characters with spaces, preserving every newline exactly).
+// This lets the WHOLE file be lowered in a single _buildCfg call at
+// startLine=1 for the module-level CFG, which keeps every remaining
+// statement's reported line number exactly equal to its real source line —
+// no character is ever deleted, only turned into a space, so nothing can
+// shift. This replaces the old per-gap slicing + per-gap startLine
+// re-derivation, which mis-tracked lines whenever a gap slice started with
+// leading blank/newline characters and broke the line-scoped
+// `agentic-security-ignore` suppression pragma for module-level findings.
+function _blankSpans(code, spans) {
+  let out = '';
+  let cursor = 0;
+  for (const span of spans) {
+    if (span.start > cursor) out += code.slice(cursor, span.start);
+    out += _blank(code.slice(span.start, span.end));
+    cursor = span.end;
+  }
+  out += code.slice(cursor);
+  return out;
+}
+
+function _blank(text) {
+  return text.replace(/[^\n]/g, ' ');
+}
+
+// Blanks a leading PHP open tag (`<?php` or `<?`) if the file starts with
+// one. Only the true start of the file is handled (matching the previous
+// behavior's `cursor === 0` scope) — this is a real fix, not dead code:
+// when top-level content sits between the open tag and the first function
+// declaration (e.g. `<?php\n$x = [...];\nfunction f(){}`), the tag is NOT
+// part of any function's span (the boundary FUNC_RE actually consumed
+// before `function f` is the `;`, not the tag — see _funcBoundaryLen), so
+// it survives into the blanked text as literal `<?php` characters. Left
+// unblanked, that text glues onto the front of the first top-level
+// statement (`<?php\n$x = [...]`), which then fails every `_lowerStmt`
+// pattern (all anchored at the true start of the statement) and silently
+// drops it. Blanking (not deleting) the tag keeps line numbers exact.
+function _blankLeadingOpenTag(text) {
+  const m = text.match(/^<\?(?:php)?/i);
+  if (!m) return text;
+  return _blank(m[0]) + text.slice(m[0].length);
+}
+
 let _nid = 0;
 function _nextId() { return `pn${++_nid}`; }
 
@@ -263,66 +546,284 @@ function _linkNodes(nodes, src, dst) {
   if (!nodes[dst].pred.includes(src)) nodes[dst].pred.push(src);
 }
 
-function _buildCfg(bodyText, nodes, prevId, startLine) {
+// R8 fix round 1: counts `\n` in `s` up to (not including) `upTo`. `s` here
+// is the RAW, untrimmed statement text `_buildCfg` is currently processing
+// (not a `.trim()`-mangled reconstruction — the exact lossy pattern the
+// module header comment above `_splitStatements` warns against), so a
+// direct count is safe and exact, not an approximation.
+function _countNewlines(s, upTo) {
+  let n = 0;
+  const end = Math.min(upTo, s.length);
+  for (let i = 0; i < end; i++) if (s[i] === '\n') n++;
+  return n;
+}
+
+// Scans a balanced `{ ... }` block starting at `s[openIdx] === '{'`.
+// String-aware (a `{`/`}` inside a quoted string doesn't perturb depth),
+// mirroring `_splitStatements`' own string handling. Returns the index
+// just past the matching `}`, or -1 if unbalanced/not found.
+function _matchBraceBlock(s, openIdx) {
+  if (s[openIdx] !== '{') return -1;
+  let depth = 0;
+  let inStr = null;
+  let escape = false;
+  for (let i = openIdx; i < s.length; i++) {
+    const c = s[i];
+    if (escape) { escape = false; continue; }
+    if (inStr) {
+      if (c === '\\') { escape = true; continue; }
+      if (c === inStr) inStr = null;
+      continue;
+    }
+    if (c === '"' || c === '\'') { inStr = c; continue; }
+    if (c === '{') depth++;
+    else if (c === '}') {
+      depth--;
+      if (depth === 0) return i + 1;
+    }
+  }
+  return -1;
+}
+
+// R8 fix round 1 (Important): manually scans a
+// `try { ... } (catch (...) { ... })* (finally { ... })?` construct by hand
+// rather than delegating to one greedy-capture-group regex. The regex this
+// replaced (`^try\s*\{([\s\S]*)\}\s*catch\s*\(([^)]*)\)\s*\{([\s\S]*)\}
+// (?:\s*finally\s*\{([\s\S]*)\})?\s*$`) has two real bugs: its catch-body
+// group is GREEDY, so for `try{}catch(E $e){A}finally{B}` it swallows
+// through to finally's OWN closing `}` (not catch's), making the trailing
+// `(?:\s*finally...)?` group match nothing — `finally` bodies were dead
+// code, never actually reachable. And it unconditionally REQUIRES a catch
+// clause, so the equally-valid `try { ... } finally { ... }` (no catch) PHP
+// shape was invisible entirely, both bodies dropped. Neither is fixable by
+// tweaking the regex (lazy-matching the catch group just breaks nested-
+// brace bodies the other way); balanced-brace scanning is the correct fix.
+//
+// Only the FIRST catch clause is modeled in the CFG (matches this task's
+// brief scope — multi-catch BLOCK form, `catch(A){}catch(B){}`, was
+// already an accepted, documented partial-capture degrade before this fix,
+// confirmed non-crashing; union-type catches, `catch (A|B $e) {}`, are
+// unaffected and fully supported, same as before). Every catch clause
+// present is still scanned past correctly (not just the first) so a
+// trailing `finally` is located at its real position rather than
+// mismatched against a later catch's own content.
+//
+// Returns null if `s` isn't `try { ... }` shaped at all. Otherwise:
+//   { tryBody, tryBodyOffset, catchBody, catchBodyOffset,
+//     finallyBody, finallyBodyOffset }
+// A body that isn't present is `null` with `-1` for its offset. Each
+// `*Offset` is `s`'s own character offset of that body's first character —
+// paired with `_countNewlines`, this gives the caller (`_buildCfg`) the
+// EXACT absolute source line for each clause, not just the try-body's
+// (which happens to share `line`'s value for ordinary K&R style, but
+// catch/finally clauses generally start several lines later).
+function _scanTryCatchFinally(s) {
+  const head = /^try\s*/.exec(s);
+  if (!head) return null;
+  let i = head[0].length;
+  if (s[i] !== '{') return null;
+  const tryBodyOffset = i + 1;
+  const tryEnd = _matchBraceBlock(s, i);
+  if (tryEnd < 0) return null;
+  const tryBody = s.slice(tryBodyOffset, tryEnd - 1);
+  i = tryEnd;
+
+  let catchBody = null;
+  let catchBodyOffset = -1;
+  let sawCatch = false;
+  for (;;) {
+    const rest = s.slice(i);
+    const ws = /^\s*/.exec(rest)[0];
+    i += ws.length;
+    const cm = /^catch\s*\(/.exec(s.slice(i));
+    if (!cm) break;
+    const parenStart = i + cm[0].length - 1;
+    const parenEnd = s.indexOf(')', parenStart);
+    if (parenEnd < 0) return null;
+    let j = parenEnd + 1;
+    const ws2 = /^\s*/.exec(s.slice(j))[0];
+    j += ws2.length;
+    if (s[j] !== '{') return null;
+    const bodyOffset = j + 1;
+    const bodyEnd = _matchBraceBlock(s, j);
+    if (bodyEnd < 0) return null;
+    if (!sawCatch) {
+      catchBody = s.slice(bodyOffset, bodyEnd - 1);
+      catchBodyOffset = bodyOffset;
+      sawCatch = true;
+    }
+    i = bodyEnd;
+  }
+
+  let finallyBody = null;
+  let finallyBodyOffset = -1;
+  {
+    const ws = /^\s*/.exec(s.slice(i))[0];
+    let j = i + ws.length;
+    const fm = /^finally\s*/.exec(s.slice(j));
+    if (fm) {
+      j += fm[0].length;
+      if (s[j] === '{') {
+        const bodyOffset = j + 1;
+        const bodyEnd = _matchBraceBlock(s, j);
+        if (bodyEnd < 0) return null;
+        finallyBody = s.slice(bodyOffset, bodyEnd - 1);
+        finallyBodyOffset = bodyOffset;
+        i = bodyEnd;
+      }
+    }
+  }
+
+  // PHP requires at least one of catch/finally; a bare `try {}` alone
+  // isn't valid PHP and isn't a shape this recognizer should claim.
+  if (!sawCatch && finallyBody === null) return null;
+  // Whatever remains must be only trailing whitespace, or this wasn't a
+  // clean try/catch/finally statement after all — fall through to the
+  // generic `_lowerStmt` path (safe no-op) rather than claiming a bad
+  // match.
+  if (s.slice(i).trim() !== '') return null;
+
+  return { tryBody, tryBodyOffset, catchBody, catchBodyOffset, finallyBody, finallyBodyOffset };
+}
+
+// `startLine` is the absolute source line of the FIRST character of
+// `bodyText`. Each statement's absolute line is `startLine + stmt.line - 1`
+// (`stmt.line` from _splitStatements is already 1-indexed and relative to
+// `bodyText`), so — unlike the old incremental `line++`/`line += newlines+1`
+// bookkeeping this replaced — no line is ever derived by re-counting
+// newlines in already-trimmed text. That old scheme silently dropped any
+// blank line (or, at module level, any blanked-out function span — see
+// `_blankSpans`) that preceded a statement, which is exactly what made
+// module-level PHP findings report the wrong source line.
+function _buildCfg(bodyText, nodes, prevId, startLine, depth = 0) {
+  if (depth > 12) return prevId;
   const stmts = _splitStatements(bodyText);
   let prev = prevId;
-  let line = startLine;
   for (const stmt of stmts) {
-    const s = stmt.trim();
-    if (!s || s.startsWith('//') || s.startsWith('#')) { line++; continue; }
+    const s = stmt.text;
+    const line = startLine + stmt.line - 1;
+    if (!s || s.startsWith('//') || s.startsWith('#')) continue;
 
-    const ifMatch = s.match(/^if\s*\((.+?)\)\s*\{([\s\S]*)\}(?:\s*else\s*\{([\s\S]*)\})?\s*$/s);
+    // R8 fix round 2: `line` (the absolute source line of `s`'s FIRST
+    // character — the `if`/`while`/`foreach`/`switch` keyword itself) is
+    // NOT a safe stand-in for a body's own start line in general. Fix
+    // round 1 used flat `line` for these four recognizers on the
+    // assumption that K&R-style `{` on the same physical line as the
+    // keyword makes the body start on that same line — true only when
+    // the header between the keyword and `{` is a single physical line
+    // AND contains no comment that ate a newline without contributing one
+    // back to `s` (fix round 1 also missed that a comment anywhere inside
+    // `s` — not just inside the header — undercounts newlines the same
+    // way; that half is fixed by `_splitStatements` now pushing a `\n`
+    // for every newline a skipped comment displaces, above). A `d`-flagged
+    // regex exposes each capture group's real character offset within
+    // `s` via `.indices`, so `_countNewlines(s, offset)` gives the body's
+    // EXACT absolute line regardless of how many lines the header itself
+    // spans or how many comments precede the body — the same precise
+    // per-clause technique the try/catch/finally recognizer below already
+    // uses (there, offsets come from the balanced-brace scanner instead
+    // of regex `.indices`, same principle).
+    const ifMatch = s.match(/^if\s*\((.+?)\)\s*\{([\s\S]*)\}(?:\s*else\s*\{([\s\S]*)\})?\s*$/ds);
     if (ifMatch) {
       const ifNode = _addNode(nodes, { kind: 'if', cond: _lowerExpr(ifMatch[1]), line });
       _linkNodes(nodes, prev, ifNode);
       const join = _addNode(nodes, { kind: 'noop', line });
-      const thenTail = _buildCfg(ifMatch[2], nodes, ifNode, line + 1);
+      const thenStartLine = line + _countNewlines(s, ifMatch.indices[2][0]);
+      const thenTail = _buildCfg(ifMatch[2], nodes, ifNode, thenStartLine, depth + 1);
       _linkNodes(nodes, thenTail, join);
       if (ifMatch[3]) {
-        const elseTail = _buildCfg(ifMatch[3], nodes, ifNode, line + 1);
+        const elseStartLine = line + _countNewlines(s, ifMatch.indices[3][0]);
+        const elseTail = _buildCfg(ifMatch[3], nodes, ifNode, elseStartLine, depth + 1);
         _linkNodes(nodes, elseTail, join);
       } else {
         _linkNodes(nodes, ifNode, join);
       }
       prev = join;
-      line += (s.match(/\n/g) || []).length + 1;
       continue;
     }
 
-    const whileMatch = s.match(/^while\s*\((.+?)\)\s*\{([\s\S]*)\}\s*$/s);
+    const whileMatch = s.match(/^while\s*\((.+?)\)\s*\{([\s\S]*)\}\s*$/ds);
     if (whileMatch) {
       const header = _addNode(nodes, { kind: 'loop-header', line });
       _linkNodes(nodes, prev, header);
-      const bodyTail = _buildCfg(whileMatch[2], nodes, header, line + 1);
+      const bodyStartLine = line + _countNewlines(s, whileMatch.indices[2][0]);
+      const bodyTail = _buildCfg(whileMatch[2], nodes, header, bodyStartLine, depth + 1);
       _linkNodes(nodes, bodyTail, header);
       const join = _addNode(nodes, { kind: 'noop', line });
       _linkNodes(nodes, header, join);
       prev = join;
-      line += (s.match(/\n/g) || []).length + 1;
       continue;
     }
 
-    const foreachMatch = s.match(/^foreach\s*\((.+?)\s+as\s+(?:\$\w+\s*=>\s*)?(\$\w+)\)\s*\{([\s\S]*)\}\s*$/s);
+    const foreachMatch = s.match(/^foreach\s*\((.+?)\s+as\s+(?:\$\w+\s*=>\s*)?(\$\w+)\)\s*\{([\s\S]*)\}\s*$/ds);
     if (foreachMatch) {
       const header = _addNode(nodes, { kind: 'loop-header', line });
       _linkNodes(nodes, prev, header);
       const assignId = _addNode(nodes, { kind: 'assign', target: foreachMatch[2], source: _lowerExpr(foreachMatch[1]), line });
       _linkNodes(nodes, header, assignId);
-      const bodyTail = _buildCfg(foreachMatch[3], nodes, assignId, line + 1);
+      const bodyStartLine = line + _countNewlines(s, foreachMatch.indices[3][0]);
+      const bodyTail = _buildCfg(foreachMatch[3], nodes, assignId, bodyStartLine, depth + 1);
       _linkNodes(nodes, bodyTail, header);
       const join = _addNode(nodes, { kind: 'noop', line });
       _linkNodes(nodes, header, join);
       prev = join;
-      line += (s.match(/\n/g) || []).length + 1;
+      continue;
+    }
+
+    const tryScan = /^try\s*\{/.test(s) ? _scanTryCatchFinally(s) : null;
+    if (tryScan) {
+      const tryNode = _addNode(nodes, { kind: 'noop', line });
+      _linkNodes(nodes, prev, tryNode);
+      const join = _addNode(nodes, { kind: 'noop', line });
+      // Same exact-offset technique as the if/while/foreach/switch bodies
+      // above, just fed by `_scanTryCatchFinally`'s balanced-brace-scan
+      // offsets instead of a `d`-flagged regex's `.indices` (there's no
+      // single regex to attach `.indices` to here — that's the whole
+      // reason this recognizer scans by hand). catch/finally clauses
+      // especially do NOT start on `line` (the `try` keyword's own line)
+      // in general — they start wherever their own `catch (...) {` /
+      // `finally {` happens to land, often several lines later.
+      const tryStartLine = line + _countNewlines(s, tryScan.tryBodyOffset);
+      const tryTail = _buildCfg(tryScan.tryBody, nodes, tryNode, tryStartLine, depth + 1);
+      let tail = tryTail;
+      if (tryScan.catchBody !== null) {
+        const catchNode = _addNode(nodes, { kind: 'noop', line });
+        _linkNodes(nodes, tail, catchNode);
+        const catchStartLine = line + _countNewlines(s, tryScan.catchBodyOffset);
+        tail = _buildCfg(tryScan.catchBody, nodes, catchNode, catchStartLine, depth + 1);
+      }
+      if (tryScan.finallyBody !== null) {
+        const finallyNode = _addNode(nodes, { kind: 'noop', line });
+        _linkNodes(nodes, tail, finallyNode);
+        const finallyStartLine = line + _countNewlines(s, tryScan.finallyBodyOffset);
+        tail = _buildCfg(tryScan.finallyBody, nodes, finallyNode, finallyStartLine, depth + 1);
+      }
+      _linkNodes(nodes, tail, join);
+      prev = join;
+      continue;
+    }
+
+    const switchMatch = s.match(/^switch\s*\((.+?)\)\s*\{([\s\S]*)\}\s*$/ds);
+    if (switchMatch) {
+      const switchNode = _addNode(nodes, { kind: 'if', cond: _lowerExpr(switchMatch[1]), line });
+      _linkNodes(nodes, prev, switchNode);
+      const join = _addNode(nodes, { kind: 'noop', line });
+      // PHP switch/case bodies fall through by default (no per-case
+      // braces) — lower the whole switchBlock body as ONE linear sequence
+      // under the switch node, matching this plan's "linear-but-complete"
+      // target rather than modeling per-case branch/skip semantics.
+      const bodyStartLine = line + _countNewlines(s, switchMatch.indices[2][0]);
+      const bodyTail = _buildCfg(switchMatch[2], nodes, switchNode, bodyStartLine, depth + 1);
+      _linkNodes(nodes, bodyTail, join);
+      prev = join;
       continue;
     }
 
     const node = _lowerStmt(s, line);
-    if (!node) { line++; continue; }
+    if (!node) continue;
     const id = _addNode(nodes, node);
     _linkNodes(nodes, prev, id);
     prev = id;
-    line += (s.match(/\n/g) || []).length + 1;
   }
   return prev;
 }
@@ -333,6 +834,7 @@ export function parsePhpFile(file, code) {
   if (code.length > 1_000_000) return null;
 
   const functions = [];
+  const spans = []; // {start, end}: source ranges fully consumed by a matched function (signature through closing brace)
   FUNC_RE.lastIndex = 0;
   _nid = 0;
   let m;
@@ -353,7 +855,25 @@ export function parsePhpFile(file, code) {
     const nodes = {};
     const entry = _addNode(nodes, { kind: 'entry', line: startLine });
     const exit = _addNode(nodes, { kind: 'exit', line: startLine });
-    const tail = _buildCfg(extracted.body, nodes, entry, startLine + 1);
+    // R8 fix round 3: the function body's `startLine` must be derived from
+    // `braceIdx` (the function's actual opening `{`), not from `startLine + 1`
+    // (a flat one-line offset from `m.index`, the FUNC_RE match start —
+    // typically a preceding boundary character/token, not the function
+    // itself). `startLine + 1` is only correct when `{` sits on the very
+    // next physical line after wherever `m.index` landed, which holds for
+    // ordinary same-line-brace, single-line-signature functions but breaks
+    // for: Allman brace style (`{` on its own line — off by 1), a
+    // multi-line function signature (off by 2-3, one per extra signature
+    // line), and a function preceded by blank lines (off by however many
+    // blank lines precede it — a nearly universal real-world style). This
+    // reproduces the exact same pragma-inert/wrong-line-suppresses symptom
+    // fix rounds 1-2 already fixed for control-flow bodies, just at the
+    // function-body base line instead of a nested recursion site — pre-
+    // existing to this task (confirmed byte-identical across the original
+    // commit and both prior fix rounds), not something this task's own
+    // changes introduced, but it defeats the same user-facing goal so it's
+    // fixed here rather than left for a separate task.
+    const tail = _buildCfg(extracted.body, nodes, entry, _lineAt(code, braceIdx + 1));
     _linkNodes(nodes, tail, exit);
     const cfg = { entry, exit, nodes };
     functions.push({
@@ -362,11 +882,49 @@ export function parsePhpFile(file, code) {
       cfg,
       calls: callSitesFromCfg(cfg),
     });
+    // span.end is exclusive (points after the closing brace), so interior and trailing
+    // gaps both work correctly without special casing. extracted.end points AT the brace,
+    // so we add 1 to make it exclusive. We keep FUNC_RE.lastIndex at extracted.end
+    // (the brace position) so subsequent function matches can use it as a boundary.
+    // span.start is m.index PLUS the boundary token FUNC_RE consumed ahead of the
+    // function itself (see _funcBoundaryLen) — the boundary char/tag belongs to
+    // whatever precedes the function, not to the function's own blanked span.
+    spans.push({ start: m.index + _funcBoundaryLen(code, m.index), end: extracted.end + 1 });
     // Don't skip past the closing brace: for `<?php function h(){...} function m(){...}`
     // that brace is the only boundary character available to anchor the next
     // function's match (there's no newline/semicolon between them), and advancing
     // past it here would make the following function declaration unmatchable.
     FUNC_RE.lastIndex = extracted.end;
   }
-  return functions.length ? { file, functions, topLevel: null } : null;
+
+  // R14(b): lower top-level (module-scope) statements into a synthetic
+  // <module> function, mirroring parser-js.js's Program-level lowering.
+  // Every real function's span is blanked (see _blankSpans) in a copy of
+  // the full source, and the WHOLE blanked text is lowered in a single
+  // _buildCfg call at startLine=1 — this keeps every remaining statement's
+  // reported line number exactly equal to its real source line, since no
+  // character is ever deleted, only blanked to a space (newlines always
+  // survive). No new statement-classification logic is needed.
+  spans.sort((a, b) => a.start - b.start);
+  const blanked = _blankLeadingOpenTag(_blankSpans(code, spans));
+  const modNodes = {};
+  const modEntry = _addNode(modNodes, { kind: 'entry', line: 1 });
+  const modExit = _addNode(modNodes, { kind: 'exit', line: 1 });
+  const modTail = _buildCfg(blanked, modNodes, modEntry, 1);
+  _linkNodes(modNodes, modTail, modExit);
+  const modHasContent = Object.values(modNodes).some(n => n.kind !== 'entry' && n.kind !== 'exit');
+  let topLevel = null;
+  if (modHasContent) {
+    const moduleCfg = { entry: modEntry, exit: modExit, nodes: modNodes };
+    const modQid = _qid(file, '<module>', 1, code);
+    functions.push({
+      qid: modQid,
+      name: '<module>', line: 1, params: [], file,
+      cfg: moduleCfg,
+      calls: callSitesFromCfg(moduleCfg),
+    });
+    topLevel = modQid;
+  }
+
+  return functions.length ? { file, functions, topLevel } : null;
 }