fix(lint): report an unparseable source instead of scoring it clean (#10653)

Four validators in packages/lint parsed authored source with
`ts.createSourceFile` and never read `parseDiagnostics`. The call cannot
throw, so a source with syntax errors came back as a recovery tree, was
walked like any other, and produced no findings. Two of the sites wrapped
the parse in a `try/catch` that never ran; deleting only those would have
closed nothing.

Adds a lint-local checked parse (`checked-parse.ts`) that reads the
diagnostics and RETURNS them, and wires four advisory rule ids onto it.
Additive: every finding these rules produce today they still produce.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DdCnBGcHeufjrq7drTD3wt

Author: claude

.changeset/lint-checked-parse-findings.md

@@ -0,0 +1,35 @@
+---
+"@objectstack/lint": minor
+---
+
+Report an unparseable source instead of scoring it CLEAN (#10653).
+
+Four validators parsed authored source with `ts.createSourceFile` and never read
+`parseDiagnostics`. That call **cannot throw**, so a source with syntax errors
+came back as a tree built by error recovery, got walked like any other, and
+produced no findings — a source the validator could not read, reported as a
+source with nothing to report. Two of the sites carried a `try/catch` around the
+parse that never once ran.
+
+Each now reports what it could not read, as a finding the author receives rather
+than as an exit — a publish-time validator is handed metadata by someone else,
+so ending the process on their input is not its call. Four new advisory
+(`warning`) rule ids, all additive: every finding these rules produce today they
+still produce, including from a partially recovered tree.
+
+- `react-page-source-unparseable` — `kind:'react'` page source
+  (`validateReactPageProps`)
+- `startup-source-unparseable` — plugin source (`findStartupRegistryVerdicts`)
+- `hook-body-source-unparseable` — L2 hook body (`validateHookBodyWrites`)
+- `action-body-source-unparseable` — L2 action body (`validateActionBodyWrites`)
+
+New exports: the four rule-id constants, plus `describeParseFailure`,
+`PARSE_FAILURE_HINT` and the `SourceParseFailure` / `CheckedParse` /
+`CheckedParseOptions` types. `ExtractedHookBodyWriteSet` gains an optional
+`parseFailure`, so a consumer of the extractor can tell "wrote nothing" from
+"could not be read" — the distinction that was missing.
+
+Nothing is removed or renamed, and no source that parses gains a finding. A
+stack whose authored sources all parse lints exactly as before; one carrying a
+source with a syntax error gains a warning that names the file, line and column
+instead of silently skipping the checks.

packages/lint/src/checked-parse.test.ts

@@ -0,0 +1,132 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+//
+// #10653 — the premise, pinned. Every claim in `checked-parse.ts`'s header is a
+// measurement, and a measurement that lives only in a comment is one nobody
+// re-runs. The two that matter:
+//
+//   1. `ts.createSourceFile` does not throw on a wreck. That is what makes the
+//      `try/catch` this module replaced dead code, and what makes the unread
+//      `parseDiagnostics` the LIVE path. If a future TypeScript ever starts
+//      throwing, `cannot throw` below fails and the callers' catch-free parses
+//      need revisiting — loudly, rather than by a caller crashing in the field.
+//   2. The diagnostics are REACHED. `parseDiagnostics` is internal to the
+//      compiler and typed optional here, so a rename would make every checked
+//      parse silently return "no failure" — the exact green-line-that-lies this
+//      module exists to remove, wearing its own badge. `the property is really
+//      there` is the non-vacuity proof (#4690: a check that has only ever been
+//      green must be tellable apart from a dead one).
+//
+// The test imports `typescript` directly, which the RULES may not do — they take
+// the compiler as a parameter and load it lazily (`lazy-deps.test.ts` guards
+// that). A test file is not on the kernel boot path.
+import ts from 'typescript';
+import { describe, it, expect } from 'vitest';
+
+import { createSourceFileChecked, describeParseFailure } from './checked-parse.js';
+
+/** Wrecks, and the ScriptKind each is measured under. */
+const WRECKS: ReadonlyArray<{ label: string; source: string; kind: ts.ScriptKind }> = [
+  {
+    label: 'merge-conflict markers',
+    source: '<<<<<<< HEAD\nconst a = 1;\n=======\nconst a = 2;\n>>>>>>> other\n',
+    kind: ts.ScriptKind.TS,
+  },
+  { label: 'truncated function body', source: 'export function f() {\n  const x = 1;\n', kind: ts.ScriptKind.TS },
+  { label: 'unterminated string', source: "const s = 'oops;\n", kind: ts.ScriptKind.TS },
+  { label: 'unterminated block comment', source: 'function f() {\n  /* TODO\n}\n', kind: ts.ScriptKind.TS },
+  { label: 'unterminated template literal', source: 'const s = `oops;\n', kind: ts.ScriptKind.TS },
+  { label: 'a JSX element read as TS', source: 'const a = <div>hi</div>;\n', kind: ts.ScriptKind.TS },
+];
+
+const parse = (source: string, kind: ts.ScriptKind, synthesizedLinesBefore?: number) =>
+  createSourceFileChecked(ts, 'probe.tsx', source, {
+    target: ts.ScriptTarget.Latest,
+    setParentNodes: true,
+    scriptKind: kind,
+    ...(synthesizedLinesBefore === undefined ? {} : { synthesizedLinesBefore }),
+  });
+
+describe('createSourceFileChecked — the premise (#10653)', () => {
+  it.each(WRECKS)('cannot throw: $label', ({ source, kind }) => {
+    // The claim is about `createSourceFile` itself, so it is called RAW here —
+    // going through the helper would prove only that the helper does not throw.
+    expect(() => ts.createSourceFile('probe.tsx', source, ts.ScriptTarget.Latest, true, kind)).not.toThrow();
+  });
+
+  it.each(WRECKS)('reports a failure instead of a clean tree: $label', ({ source, kind }) => {
+    const { failure } = parse(source, kind);
+    expect(failure, 'a source that does not parse must come back with a failure').toBeDefined();
+    expect(failure!.count).toBeGreaterThan(0);
+    expect(failure!.message.length).toBeGreaterThan(0);
+    expect(failure!.line).toBeGreaterThanOrEqual(1);
+    expect(failure!.column).toBeGreaterThanOrEqual(1);
+  });
+
+  it('the property is really there — non-vacuity of the whole module (#4690)', () => {
+    // If `parseDiagnostics` is ever renamed or dropped, the optional read in
+    // checked-parse.ts yields undefined and EVERY checked parse in this package
+    // goes quietly back to scoring wreckage clean. Nothing else would fail. So
+    // the property is asserted directly, on the compiler, once.
+    const sf = ts.createSourceFile('probe.ts', 'const a = ;\n', ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    const diagnostics = (sf as unknown as { parseDiagnostics?: readonly ts.Diagnostic[] }).parseDiagnostics;
+    expect(Array.isArray(diagnostics), '`SourceFile.parseDiagnostics` is gone — checked-parse.ts is now inert').toBe(
+      true,
+    );
+    expect(diagnostics!.length).toBeGreaterThan(0);
+  });
+});
+
+describe('createSourceFileChecked — a source that DOES parse', () => {
+  it.each([
+    ['plain TS', 'export const a: number = 1;\n', ts.ScriptKind.TS],
+    ['TSX with JSX', 'export default function P() {\n  return <ObjectForm objectName="a" />;\n}\n', ts.ScriptKind.TSX],
+    ['empty', '', ts.ScriptKind.TS],
+  ] as const)('reports no failure: %s', (_label, source, kind) => {
+    expect(parse(source, kind).failure).toBeUndefined();
+  });
+
+  it('the SAME source under the wrong ScriptKind is a failure, not an opinion', () => {
+    // The ScriptKind hat: `<div>…</div>` is a JSX element in TSX and a wreck in
+    // TS. Both verdicts are correct for their kind, and neither is silent.
+    const jsx = 'const a = <div>hi</div>;\n';
+    expect(parse(jsx, ts.ScriptKind.TSX).failure).toBeUndefined();
+    expect(parse(jsx, ts.ScriptKind.TS).failure).toBeDefined();
+  });
+});
+
+describe('createSourceFileChecked — position reporting', () => {
+  it('reports the line the error is on', () => {
+    const { failure } = parse('const a = 1;\nconst b = 2;\nconst c = ;\n', ts.ScriptKind.TS);
+    expect(failure!.line).toBe(3);
+  });
+
+  it('subtracts the caller-synthesised lines, so a wrapper never shifts the blame', () => {
+    // What validate-hook-body-writes.ts does: the author wrote `const c = ;` on
+    // line 2 of their BODY, and the wrapper puts it on line 3 of what is parsed.
+    const body = 'const a = 1;\nconst c = ;\n';
+    const wrapped = `async function __body(ctx) {\n${body}\n}`;
+    expect(parse(wrapped, ts.ScriptKind.TS).failure!.line, 'raw: the wrapper line counts').toBe(3);
+    expect(parse(wrapped, ts.ScriptKind.TS, 1).failure!.line, "remapped: the author's own line").toBe(2);
+  });
+
+  it('clamps to line 1 — a diagnostic on a synthesised line never points above the source', () => {
+    // A diagnostic that lands ON the wrapper's own first line would remap to 0,
+    // which is not a line anybody wrote.
+    const failure = parse('const a = ;\n', ts.ScriptKind.TS, 5).failure!;
+    expect(failure.line).toBe(1);
+  });
+
+  it('counts every diagnostic, and names the first', () => {
+    const failure = parse('<<<<<<< HEAD\nconst a = 1;\n=======\nconst a = 2;\n>>>>>>> other\n', ts.ScriptKind.TS)
+      .failure!;
+    expect(failure.count).toBeGreaterThan(1);
+    expect(describeParseFailure(failure)).toContain(`${failure.count} syntax errors in total`);
+    expect(describeParseFailure(failure)).toContain(failure.message);
+  });
+
+  it('a single diagnostic is described without a count', () => {
+    const failure = parse('const a = ;\n', ts.ScriptKind.TS).failure!;
+    expect(failure.count).toBe(1);
+    expect(describeParseFailure(failure)).not.toContain('in total');
+  });
+});

packages/lint/src/checked-parse.ts

@@ -0,0 +1,173 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+//
+// `@objectstack/lint`'s ONE answer to "did this source actually parse?" (#10653).
+//
+// ## The defect this closes — and it is NOT the `try/catch` it replaced
+//
+// **`ts.createSourceFile` never throws.** Hand it merge-conflict markers, an
+// unterminated comment or a truncated body and it returns a `SourceFile` built
+// by error recovery, indistinguishable from any other: the errors are parked on
+// `parseDiagnostics`, which nothing in this package read. A validator then walks
+// that wreckage, finds none of the shapes it is looking for, and returns an
+// empty finding list — **a source the validator could not read, reported as a
+// source with nothing to report.**
+//
+// The three call sites this module was extracted from each carried a
+// `try/catch` around the parse, and two of them read as if the catch were the
+// guard. It never ran. Measured here on 2026-08-21 against TypeScript 6.0.3 —
+// every one of these returns a tree, throws nothing, and is walked as if clean:
+//
+//   source                        ScriptKind.TS   ScriptKind.TSX   threw?
+//   ---------------------------   -------------   --------------   ------
+//   merge-conflict markers        3 diagnostics   3 diagnostics     no
+//   truncated function body       1 diagnostic    1 diagnostic      no
+//   unterminated string           1 diagnostic    1 diagnostic      no
+//   unterminated block comment    1 diagnostic    1 diagnostic      no
+//   a JSX element                 1 diagnostic    0                 no
+//
+// The last row is the same defect wearing the `ScriptKind` hat, and it is why
+// the answer lives in one module rather than three: the question "did this
+// parse?" has one right answer and three places that were getting it wrong in
+// slightly different ways. `checked-parse.test.ts` pins the measurement so the
+// premise above cannot rot into a comment nobody re-ran — including the row
+// that matters most, that the diagnostics are REACHED (see the non-vacuity
+// case there, and `parseDiagnostics` below).
+//
+// ## Why a returned FINDING rather than a refusal
+//
+// `scripts/ts-parse.mjs` answers the same question for repo tooling and answers
+// it by REFUSING — correct there, because a `scripts/**` gate audits a tree its
+// own author controls. A publish-time validator is in the opposite position: it
+// is handed metadata by someone else, and ending the process on their input is
+// not its call. So this module reports, and every caller turns the report into
+// a finding the author receives at authoring time. Nothing here throws, and
+// nothing here decides severity — that belongs to the rule.
+//
+// ## Why lint-local, and not the two neighbours it could have been
+//
+//   • NOT `scripts/ts-parse.mjs`: `@objectstack/lint` is PUBLISHED and packs
+//     `dist, README.md, CHANGELOG.md`. A published package that asks repo
+//     tooling whether something parsed trades this bug for a worse one — the
+//     objection `invoked-as.mjs` already argued for its own `packages/cli`
+//     sibling, and the reason #10606 existed at all.
+//   • NOT a new shared `@objectstack/…` package: a published dependency built
+//     for four call sites, argued down in the same place.
+//
+// The TypeScript module is a PARAMETER, never an import: `@objectstack/lint`
+// sits on the kernel boot path and `typescript` is ~9 MB of CJS, so every
+// caller here loads it lazily and only when a source actually needs parsing.
+// This module must therefore stay type-only in its imports (`lazy-deps.test.ts`
+// is the guard).
+import type ts from 'typescript';
+
+/**
+ * `parseDiagnostics` is where the parser parks syntax errors, and it is not on
+ * the public `SourceFile` type — the property is internal to the compiler and
+ * reached here by a narrowing cast rather than by `as any`.
+ *
+ * Declaring it OPTIONAL is deliberate: if a future TypeScript renames or drops
+ * it, this reads `undefined` and every checked parse silently returns to the
+ * behaviour this module exists to remove — a green line about a source nobody
+ * could read. That failure mode is invisible by construction, so it is pinned
+ * in `checked-parse.test.ts` instead of being trusted here.
+ */
+interface SourceFileWithParseDiagnostics {
+  readonly parseDiagnostics?: readonly ts.Diagnostic[];
+}
+
+/** What a caller needs to tell an author WHICH source went unread, and where. */
+export interface SourceParseFailure {
+  /** The first parse diagnostic, in the compiler's own wording, flattened to one line. */
+  message: string;
+  /** 1-based line, in the AUTHORED source's coordinates (see `synthesizedLinesBefore`). */
+  line: number;
+  /** 1-based column. */
+  column: number;
+  /** How many parse diagnostics in total — `message` is the first of `count`. */
+  count: number;
+}
+
+/** A parse plus the verdict on whether it succeeded. `failure` absent ⇒ it parsed. */
+export interface CheckedParse {
+  /**
+   * The tree, ALWAYS returned — including when `failure` is set. Error recovery
+   * produces a partial tree, and a caller that already reports findings from it
+   * keeps doing so: the fix here is the missing SIGNAL, not the removal of
+   * whatever the recovered tree could still be read for.
+   */
+  sourceFile: ts.SourceFile;
+  /** Set when the parser reported at least one syntax diagnostic. */
+  failure?: SourceParseFailure;
+}
+
+export interface CheckedParseOptions {
+  target: ts.ScriptTarget;
+  setParentNodes: boolean;
+  scriptKind: ts.ScriptKind;
+  /**
+   * Lines the CALLER synthesised ahead of the authored source, subtracted from
+   * the reported position so it lands in the author's coordinates.
+   *
+   * `validate-hook-body-writes.ts` parses an L2 hook body wrapped in
+   * `async function __body(ctx) {\n…\n}` — the shape the runtime compiles it
+   * into — so its diagnostics are one line low. The reported line is clamped to
+   * at least 1, so a diagnostic that lands on a synthesised line is attributed
+   * to the nearest AUTHORED line and never to a line the author did not write.
+   */
+  synthesizedLinesBefore?: number;
+}
+
+/**
+ * `ts.createSourceFile`, with the diagnostics READ.
+ *
+ * Never throws and never exits: the verdict comes back as data.
+ */
+export function createSourceFileChecked(
+  tsc: typeof ts,
+  fileName: string,
+  source: string,
+  options: CheckedParseOptions,
+): CheckedParse {
+  const sourceFile = tsc.createSourceFile(
+    fileName,
+    source,
+    options.target,
+    options.setParentNodes,
+    options.scriptKind,
+  );
+  const diagnostics = (sourceFile as unknown as SourceFileWithParseDiagnostics).parseDiagnostics;
+  if (!diagnostics || diagnostics.length === 0) return { sourceFile };
+
+  const first = diagnostics[0]!;
+  const { line, character } = sourceFile.getLineAndCharacterOfPosition(first.start ?? 0);
+  const offset = options.synthesizedLinesBefore ?? 0;
+  return {
+    sourceFile,
+    failure: {
+      message: tsc.flattenDiagnosticMessageText(first.messageText, ' '),
+      line: Math.max(1, line + 1 - offset),
+      column: character + 1,
+      count: diagnostics.length,
+    },
+  };
+}
+
+/**
+ * The one wording every caller's message embeds, so three findings about the
+ * same defect do not describe it three ways.
+ */
+export function describeParseFailure(failure: SourceParseFailure): string {
+  const more = failure.count > 1 ? `; ${failure.count} syntax errors in total` : '';
+  return `line ${failure.line}, column ${failure.column}: ${failure.message}${more}`;
+}
+
+/**
+ * The hint every caller's finding carries. It says what the finding IS — a
+ * statement about what the checker could read, not a second syntax verdict —
+ * because a source that does not parse is not scored, and an author who reads
+ * "no problems found" about it would be reading a green line that lied.
+ */
+export const PARSE_FAILURE_HINT =
+  'The source is parsed (never executed) so it can be checked. A source with syntax errors is only ' +
+  'partially recovered, so the checks that follow may have skipped real problems — fix the syntax ' +
+  'error and re-run to get a verdict that covers the whole source.';

packages/lint/src/index.ts

@@ -58,6 +58,7 @@ export {
   STARTUP_VERDICT_HINT,
   STARTUP_OPEN_VOCABULARY_VERDICT,
   STARTUP_VERDICT_ASSERTIVE_WORDING,
+  STARTUP_SOURCE_UNPARSEABLE,
 } from './lint-startup-registry-verdict.js';
 export type {
   StartupRegistryVerdictFinding,
@@ -147,8 +148,16 @@ export {
   REACT_CHART_AXIS_UNKNOWN,
   REACT_CHART_DRILLDOWN_INVALID,
   REACT_BLOCK_NEEDS_RECORD_CONTEXT,
+  REACT_PAGE_SOURCE_UNPARSEABLE,
 } from './validate-react-page-props.js';
 export type { ReactPropFinding, ReactPropSeverity } from './validate-react-page-props.js';
+
+// [#10653] The package-local checked parse behind the three `*-source-unparseable`
+// rules above and below. Exported because a consumer that receives one of those
+// findings may want the failure's shape (line/column/count) rather than
+// re-parsing the message string — the same reason the rule ids are exported.
+export { describeParseFailure, PARSE_FAILURE_HINT } from './checked-parse.js';
+export type { SourceParseFailure, CheckedParse, CheckedParseOptions } from './checked-parse.js';
 export { validatePageSourceStyling, PAGE_SOURCE_CLASSNAME } from './validate-page-source-styling.js';
 export type { SourceStyleFinding, SourceStyleSeverity } from './validate-page-source-styling.js';
 
@@ -506,6 +515,7 @@ export {
   HOOK_BODY_WRITE_EXCLUSIONS,
   HOOK_BODY_WRITE_UNKNOWN_FIELD,
   HOOK_BODY_WRITE_UNPROVISIONED_ANCHOR,
+  HOOK_BODY_SOURCE_UNPARSEABLE,
 } from './validate-hook-body-writes.js';
 export type {
   HookBodyWriteFinding,
@@ -530,6 +540,7 @@ export {
   ACTION_BODY_WRITE_UNKNOWN_FIELD,
   ACTION_BODY_WRITE_UNPROVISIONED_ANCHOR,
   ACTION_RECORD_WRITE_DISCARDED,
+  ACTION_BODY_SOURCE_UNPARSEABLE,
 } from './validate-action-body-writes.js';
 export type {
   ActionBodyWriteFinding,