fix(tooling): make an unparseable source REFUSE instead of scoring clean (#10573)

`ts.createSourceFile` never throws. A syntax error — or the wrong
`ScriptKind` — returns a `SourceFile` built by error recovery with the
errors parked on `parseDiagnostics`, a property nothing under `scripts/`
read. Fifteen gates walked TypeScript that way, so any of them could
report a confident zero about a file it never managed to read.

This was not latent. `check-engine-double-contract.mjs` forced
`ts.ScriptKind.TSX` on all 2504 `*.{test,spec}.{ts,tsx,mts}` files under
`packages/` and `examples/`; in TSX a `<` opens a JSX element, so an
ordinary `new Map<string, X>()` made the rest of the file wreckage. 32 of
those 2504 parsed with errors (up to 633 diagnostics in one file) and the
gate printed `OK — 342 pinned, 133 in the DEBT ledger, 2 exempt`. Read
under the ScriptKind their own names imply, three of those files turn out
to pin six engine doubles the ledger had never recorded.

- `scripts/ts-parse.mjs` — the one sanctioned parse. Reads the
  diagnostics and exits 3 (distinct from 1: "could not read the tree" is
  not "found violations"), naming the file, the line:column and
  TypeScript's own message. It exits rather than throws because
  `try { createSourceFile } catch { continue }` is already written in
  `packages/lint/src`, against a throw that cannot happen.
- `scripts/check-parse-guard.mjs` — the half that makes it hold. A raw
  `ts.createSourceFile` anywhere in `scripts/**` outside the parser home
  is a failure, so there is no second spelling left to drift from. Same
  shape as `invoked-as.mjs` + `check-entry-guard.mjs`, and for the same
  measured reason.
- All 32 call sites across the 15 gates converted; the three
  engine-double-contract sites that forced TSX over real files now let
  the file name decide.
- `engine-double-contract.pinned.json` grows by the 6 rows that became
  visible: 342 -> 348 pinned, 0 lost.

Fixes: #10133


Claude-Session: https://claude.ai/code/session_01DdCnBGcHeufjrq7drTD3wt

Co-authored-by: Claude <noreply@anthropic.com>

Author: claude[bot]

scripts/check-driver-memory-census.mjs

@@ -108,6 +108,7 @@ import { join, dirname, relative, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { execFileSync } from 'node:child_process';
 import ts from 'typescript';
+import { parseSourceFile } from './ts-parse.mjs';
 
 const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
 const LEDGER_PATH = join(ROOT, 'scripts', 'driver-memory-census.ledger.json');
@@ -229,7 +230,7 @@ function classify(node) {
 
 /** Every occurrence of the specifier in one source text, classified. */
 export function scanSource(fileName, text) {
-  const sf = ts.createSourceFile(fileName, text, ts.ScriptTarget.Latest, true);
+  const sf = parseSourceFile(fileName, text);
   const found = [];
   const visit = (node) => {
     if ((ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) && namesPackage(node.text)) {

scripts/check-durability-degradation-log-level.mjs

@@ -240,6 +240,7 @@ import { readFileSync, readdirSync, statSync, existsSync } from 'node:fs';
 import { join, relative, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import ts from 'typescript';
+import { parseSourceFile } from './ts-parse.mjs';
 
 const ROOT = fileURLToPath(new URL('..', import.meta.url));
 const BASELINE_PATH = join(ROOT, 'scripts', 'durability-degradation.baseline.json');
@@ -2441,7 +2442,7 @@ function runReadSeamRule({ list = false } = {}) {
         for (const file of collectSourceFiles(join(ROOT, root))) {
             const text = readFileSync(file, 'utf8');
             if (!text.includes('catch')) continue;
-            const sf = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+            const sf = parseSourceFile(file, text, ts.ScriptKind.TS);
             analyzeReadSeams(sf, relative(ROOT, file).split(sep).join('/'), findings, seams, {
                 usedDiscriminators,
             });
@@ -2716,7 +2717,7 @@ function run({ list = false } = {}) {
     for (const file of files) {
         const text = readFileSync(file, 'utf8');
         if (!text.includes('catch')) continue;
-        const sf = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+        const sf = parseSourceFile(file, text, ts.ScriptKind.TS);
         analyzeSourceFile(sf, relative(ROOT, file).split(sep).join('/'), findings, seams, {
             usedPropagationSites,
             summaryBranches,
@@ -3815,7 +3816,7 @@ function selfTest() {
 
     let failures = 0;
     for (const c of cases) {
-        const sf = ts.createSourceFile('t.ts', c.code, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+        const sf = parseSourceFile('t.ts', c.code, ts.ScriptKind.TS);
         const findings = [];
         const seams = [];
         const summaryBranches = [];
@@ -4481,7 +4482,7 @@ function selfTestReadSeams() {
 
     let failures = 0;
     for (const c of cases) {
-        const sf = ts.createSourceFile('t.ts', c.code, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+        const sf = parseSourceFile('t.ts', c.code, ts.ScriptKind.TS);
         const findings = [];
         const seams = [];
         const usedDiscriminators = new Set();

scripts/check-engine-double-contract.mjs

@@ -275,6 +275,7 @@ import { readFileSync, readdirSync, existsSync, writeFileSync } from 'node:fs';
 import { join, dirname, relative, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import ts from 'typescript';
+import { parseSourceFile } from './ts-parse.mjs';
 
 const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
 const BASELINE_PATH = join(ROOT, 'scripts', 'engine-double-contract.baseline.json');
@@ -816,7 +817,7 @@ function localFunctions(sourceFile) {
  * #5393 hit and #5480 removed the excuse for.
  */
 function scanSource(fileName, text, slice = SLICES[0], opts = {}) {
-  const sf = ts.createSourceFile(fileName, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+  const sf = parseSourceFile(fileName, text);
   const pinnedNames = pinnedImportsOf(sf, slice);
   const locals = localFunctions(sf);
   const doubles = [];
@@ -960,7 +961,7 @@ function declaredBindings(sf) {
  * construct left the population without any verdict being recorded.
  */
 function censusSource(fileName, text, slice) {
-  const sf = ts.createSourceFile(fileName, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+  const sf = parseSourceFile(fileName, text);
   const declared = declaredBindings(sf);
   const unrecognised = [];
   const scopedOut = [];
@@ -1202,7 +1203,7 @@ function censusRecognizer() {
     const rel = relative(ROOT, abs).split(sep).join('/');
     const text = readFileSync(abs, 'utf8');
     if (!/\b(delete|update)\s*[(:,}]/.test(text)) continue;
-    const sf = ts.createSourceFile(abs, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+    const sf = parseSourceFile(abs, text);
 
     const consider = (props) => {
       for (const m of props) {
@@ -1802,7 +1803,7 @@ function envelopeImportsOf(sourceFile) {
  * caller-supplied id, in a function that answers a receipt.
  */
 function scanSeams(fileName, text) {
-  const sf = ts.createSourceFile(fileName, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+  const sf = parseSourceFile(fileName, text, ts.ScriptKind.TS);
   const envelopeNames = envelopeImportsOf(sf);
   const localFns = localFunctions(sf);
   const methodFns = classMethods(sf);
@@ -1949,7 +1950,7 @@ function declaredFunctionNames(sourceFile) {
 function fileDeclaresFunction(file, fn) {
   const abs = join(ROOT, file);
   if (!existsSync(abs)) return false;
-  const sf = ts.createSourceFile(file, readFileSync(abs, 'utf8'), ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+  const sf = parseSourceFile(file, readFileSync(abs, 'utf8'), ts.ScriptKind.TS);
   return declaredFunctionNames(sf).has(fn);
 }
 
@@ -3517,7 +3518,7 @@ ${body}
   // (`scalarWhereIdOf` is where "scalar" means something) and this pins it
   // where a mutation can reach it.
   const whereIdOf = (src) => {
-    const f = ts.createSourceFile('t.ts', src, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    const f = parseSourceFile('t.ts', src, ts.ScriptKind.TS);
     let lit = null;
     const v = (n) => { if (!lit && ts.isObjectLiteralExpression(n) && propertyNamed(n, 'where')) lit = n; ts.forEachChild(n, v); };
     v(f);
@@ -3929,7 +3930,7 @@ class Svc {
   // a walker blind to one of them would classify that seam's loss as the
   // quieter story — and the classifier would still look healthy.
   const namesOf = (src) => declaredFunctionNames(
-    ts.createSourceFile('d.ts', src, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS));
+    parseSourceFile('d.ts', src, ts.ScriptKind.TS));
   expect('declaredFunctionNames reads a top-level function declaration (`callData`s shape)',
     namesOf('export async function callData(deps) { return 1; }').has('callData'));
   expect('…an OBJECT LITERAL method (`protocol.updateData` / the MCP bridge’s shape)',
@@ -4053,7 +4054,7 @@ const engine: any = { registry: {}, insert: async (o: string, d: any) => d, find
   // another would print a confident table and hide the same blind spot the
   // constants did.
   const kindsOf = (src) => {
-    const sf = ts.createSourceFile('k.test.ts', src, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+    const sf = parseSourceFile('k.test.ts', src, ts.ScriptKind.TSX);
     const out = [];
     const visit = (n) => {
       if (ts.isObjectLiteralExpression(n) || ts.isClassDeclaration(n)) {
@@ -4076,7 +4077,7 @@ const engine: any = { registry: {}, insert: async (o: string, d: any) => d, find
   expect('#9943 — a method body is its own kind too', kindsOf('const e = { async update(o, d) {} };') === 'method body');
 
   const assignSites = (src) => objectAssignSites(
-    ts.createSourceFile('a.test.ts', src, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX), SCANNED_VERBS,
+    parseSourceFile('a.test.ts', src, ts.ScriptKind.TSX), SCANNED_VERBS,
   );
   let sites = assignSites('const ql = Object.assign(makeQl(), { async find() { return []; }, async insert() { return null; } });');
   expect('#8553 — an Object.assign override varying OTHER engine members reads as BASE-accounted '

scripts/check-filter-alias-parity.mjs

@@ -87,6 +87,7 @@ import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import ts from 'typescript';
+import { parseSourceFile } from './ts-parse.mjs';
 
 const ROOT = join(fileURLToPath(new URL('.', import.meta.url)), '..');
 
@@ -108,7 +109,7 @@ const FILTER_SLOT = 'where';
 class UnreadableShape extends Error {}
 
 function parse(path, text) {
-    return ts.createSourceFile(path, text, ts.ScriptTarget.Latest, true);
+    return parseSourceFile(path, text);
 }
 
 /** Every node in a subtree, depth-first. */

scripts/check-init-service-contract.mjs

@@ -82,6 +82,7 @@ import { readFileSync, readdirSync, statSync } from 'node:fs';
 import { join, relative, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import ts from 'typescript';
+import { parseSourceFile } from './ts-parse.mjs';
 
 const ROOT = join(fileURLToPath(new URL('.', import.meta.url)), '..');
 
@@ -393,7 +394,7 @@ function scan(files = discoverFiles()) {
     // would be filtered out here before the AST ever saw it, which is the same
     // silent-hole failure this file's #4772 note is about.
     if (!PREFILTER_TOKENS.some((token) => text.includes(token))) continue;
-    const src = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true);
+    const src = parseSourceFile(file, text);
     for (const unit of collectPluginUnits(file, src)) {
       units.push({ ...unit, initCalls: initServiceCalls(unit, src) });
     }
@@ -501,7 +502,7 @@ function selfTest() {
   const assert = (cond, msg) => { if (!cond) { console.error('✗ self-test: ' + msg); process.exit(1); } };
 
   const auditSource = (code) => {
-    const src = ts.createSourceFile('fixture.ts', code, ts.ScriptTarget.Latest, true);
+    const src = parseSourceFile('fixture.ts', code);
     const units = collectPluginUnits('fixture.ts', src).map((u) => ({ ...u, initCalls: initServiceCalls(u, src) }));
     return auditUnits(units);
   };

scripts/check-kernel-hook-pairs.mjs

@@ -71,6 +71,7 @@ import { readFileSync, readdirSync, statSync } from 'node:fs';
 import { join, relative, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import ts from 'typescript';
+import { parseSourceFile } from './ts-parse.mjs';
 import { isEntrypoint } from './invoked-as.mjs';
 
 const ROOT = join(fileURLToPath(new URL('.', import.meta.url)), '..');
@@ -104,7 +105,7 @@ const HOOK_NAME = /^kernel:[A-Za-z][A-Za-z0-9_:-]*$/;
 // ── Scanning ─────────────────────────────────────────────────────────────────
 
 function parse(fileName, source) {
-    return ts.createSourceFile(fileName, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    return parseSourceFile(fileName, source, ts.ScriptKind.TS);
 }
 
 /** The identifier a call expression ends in: `a.b.c(x)` → `c`, `c(x)` → `c`. */

scripts/check-meta-type-normalized.mjs

@@ -82,6 +82,7 @@ import { readFileSync, readdirSync, statSync } from 'node:fs';
 import { join, relative, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import ts from 'typescript';
+import { parseSourceFile } from './ts-parse.mjs';
 
 const ROOT = join(fileURLToPath(new URL('.', import.meta.url)), '..');
 
@@ -145,7 +146,7 @@ function walkFiles(dir, out) {
 /** Every raw-param decision site in one file. */
 function findViolations(file) {
     const text = readFileSync(file, 'utf8');
-    const source = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true);
+    const source = parseSourceFile(file, text);
     const found = [];
 
     const record = (node, kind) => {
@@ -198,7 +199,7 @@ function selfTest() {
         const ok2 = RestServer.metaTypeSingular(req.params.type) === 'book';
         const ok3 = metaType === 'doc';
     `;
-    const source = ts.createSourceFile('fixture.ts', fixture, ts.ScriptTarget.Latest, true);
+    const source = parseSourceFile('fixture.ts', fixture);
     const hits = [];
     const visit = (node) => {
         if (ts.isBinaryExpression(node) && COMPARISON_OPS.has(node.operatorToken.kind)

scripts/check-org-identifier.mjs

@@ -269,6 +269,7 @@ import { execFileSync } from 'node:child_process';
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import ts from 'typescript';
+import { parseSourceFile } from './ts-parse.mjs';
 import { maskComments } from './js-comment-mask.mjs';
 
 const ROOTS = ['examples', 'apps', 'packages'];
@@ -499,7 +500,7 @@ function parse(text, file) {
   // `scriptKind` left to the parser so `.tsx` / `.jsx` / `.mjs` are inferred
   // from the name. The parser is error-tolerant: a file it cannot fully parse
   // still yields the nodes around the failure rather than throwing.
-  return ts.createSourceFile(file, text, ts.ScriptTarget.Latest, /* setParentNodes */ true);
+  return parseSourceFile(file, text);
 }
 
 // ── the gate ──────────────────────────────────────────────────────────────