ci(superdoc): per-file checkJs gate for public-contract drift (SD-2863) (#3044)

* ci(superdoc): per-file checkJs gate for public-contract drift (SD-2863)

The existing audit gates (declarations, consumer matrix, public-type
assertion list) all check the published artifact. None of them catch
the case where a public JSDoc typedef drifts from the implementation
that consumes it — the IT-300 / IT-338 / SD-2514 class. Enabling
project-wide `checkJs: true` cascades through `customConditions:
["source"]` resolution and surfaces ~6500 errors across 439 files,
which is its own multi-PR ratchet rather than a gate.

Lands the per-file pattern instead: each file in the gate adds
`// @ts-check`, the gate script runs `tsc --noEmit` against the
existing project tsconfig and filters output to the curated file list.
A regression on a gated file fails CI; pre-existing errors elsewhere
are ignored and tracked under follow-up tickets.

First file under the gate is `packages/superdoc/src/helpers/
schema-introspection.js`. The probe immediately surfaced one real drift:
the `extensions` parameter was typed `Array` (no type argument), which
collapses to `Array<any>` for consumers — exactly the SD-2514 class.
Replaced with `NonNullable<EditorOptions['extensions']>` so the
parameter pulls its real shape from the public `EditorOptions` type.

Adding more files later: add `// @ts-check` as the first line and
append the path to `CHECKED_FILES` in `check-jsdoc.cjs`. Follow-up
tickets cover the next files (use-find-replace, use-password-prompt,
SuperDoc.js, etc.) one at a time.

* ci(superdoc): fail check:jsdoc on tsc invocation errors (SD-2863)

The gate scanned tsc output for diagnostics in CHECKED_FILES, but did
not check whether tsc actually ran. Two silent-pass modes existed:

- spawnSync sets result.error (e.g. ENOENT on a missing tsc binary,
  signal, permission denied). result.status is null, stdout/stderr are
  empty, and the script reports OK.
- tsc exits non-zero with a structural error (missing tsconfig, internal
  crash) that does not match the (line,col) regex. allErrors is empty,
  so the gate reports OK on a build that never type-checked anything.

Both now exit 1 with the captured failure context.

* ci(superdoc): require @ts-check on gated files and fail on signal kill (SD-2863)

Reviewer flagged two more silent-pass modes the previous patch missed:

- A path can be in CHECKED_FILES without the file containing
  `// @ts-check`. Because the project tsconfig sets `checkJs: false`,
  TypeScript skips the file entirely, allErrors stays empty, and the
  gate reports OK even though the file has fully drifted.
- spawnSync can return with `result.status === null` and `result.signal`
  set when tsc is killed by a signal (SIGKILL/OOM/SIGTERM) mid-run. If
  the partial output happens to contain parseable diagnostics that
  match no gated file, the structural-failure branch does not fire.

Both fail explicitly now. Pre-flight refuses to run tsc unless every
gated file exists and contains `// @ts-check` in its first 4 KiB; the
post-spawn check fails on `result.signal !== null`. Verified locally
by deleting the directive and by killing a fake tsc with SIGKILL.

Author: caio-pizzol

.github/workflows/ci-superdoc.yml

@@ -113,6 +113,13 @@ jobs:
       - name: Typecheck
         run: pnpm run type-check
 
+      - name: Public-contract checkJs (SD-2863)
+        # Gated subset of public-contract files run with `// @ts-check`. The
+        # script greps tsc output for errors in the curated file list and
+        # ignores the wider 1500+ errors from the broader super-editor source
+        # tree (those are tracked under SD-2863 follow-up tickets).
+        run: pnpm --filter superdoc run check:jsdoc
+
       - name: Consumer typecheck (matrix)
         # The matrix script owns the published-package validation path:
         # it packs superdoc, installs the tarball into the standalone

packages/superdoc/package.json

@@ -112,6 +112,7 @@
     "postbuild": "node ./scripts/ensure-types.cjs && node ./scripts/audit-bundle.cjs && node ./scripts/audit-declarations.cjs",
     "audit:declarations": "node ./scripts/audit-declarations.cjs",
     "audit:declarations:informational": "node ./scripts/audit-declarations.cjs --informational",
+    "check:jsdoc": "node ./scripts/check-jsdoc.cjs",
     "build:es": "vite build && pnpm run postbuild",
     "watch:es": "vite build --watch",
     "build:cdn": "vite build --config vite.config.cdn.js",

packages/superdoc/scripts/check-jsdoc.cjs

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+/**
+ * SD-2863: per-file checkJs gate for the public-contract surface.
+ *
+ * Why this exists in this shape (and not as a plain `tsc -p tsconfig.checkjs.json`):
+ *
+ * The codebase uses `customConditions: ["source"]`, which makes TypeScript
+ * resolve `import { Editor } from '@superdoc/super-editor'` to the source
+ * `.js`/`.ts` files of the workspace package. With `// @ts-check` enabled on
+ * any file in this package, TS follows those imports and type-checks the
+ * super-editor source too — about 6500 errors. Those errors are real (they
+ * are the broader SD-2863 work) but they are not what this PR is trying to
+ * gate. The gate here is "files in CHECKED_FILES must stay clean."
+ *
+ * The script:
+ *
+ *   1. Runs `tsc --noEmit -p packages/superdoc/tsconfig.json`. Because each
+ *      file in CHECKED_FILES has `// @ts-check`, TS reports errors on those
+ *      files even though the project-wide `checkJs` is `false`.
+ *   2. Filters the tsc output to errors whose path matches an entry in
+ *      CHECKED_FILES.
+ *   3. Exits non-zero if any matched the filter; exits zero if not.
+ *
+ * Adding a new file to the gate:
+ *
+ *   1. Add `// @ts-check` as the first line of the file.
+ *   2. Add the file's path (relative to `packages/superdoc/`) to
+ *      CHECKED_FILES below.
+ *   3. Run `node packages/superdoc/scripts/check-jsdoc.cjs` and fix what
+ *      surfaces.
+ *
+ * The intent is for CHECKED_FILES to grow over time as the team ratchets
+ * checkJs across the public-contract surface. SD-2863 lands the pattern;
+ * follow-up tickets land the additional files.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const CHECKED_FILES = [
+  'src/helpers/schema-introspection.js',
+];
+
+const packageDir = path.resolve(__dirname, '..');
+const repoRoot = path.resolve(packageDir, '..', '..');
+
+const tscBin = path.join(repoRoot, 'node_modules', '.bin', 'tsc');
+const tsconfigPath = path.join(packageDir, 'tsconfig.json');
+
+// Pre-flight: every file in CHECKED_FILES must opt into `// @ts-check`.
+// The project's tsconfig sets `checkJs: false`, so a JS file without the
+// directive is not type-checked at all. Without this guard, removing or
+// forgetting the directive on a listed file makes the gate silently stop
+// covering it — the script keeps reporting OK even though the file has
+// drifted.
+const missingDirective = [];
+const missingFiles = [];
+for (const rel of CHECKED_FILES) {
+  const abs = path.join(packageDir, rel);
+  if (!fs.existsSync(abs)) {
+    missingFiles.push(rel);
+    continue;
+  }
+  // The directive only takes effect when it precedes any non-comment
+  // statement, so it lives near the top. 4 KiB is plenty of margin for
+  // a leading license/doc block.
+  const head = fs.readFileSync(abs, 'utf8').slice(0, 4096);
+  if (!/^\s*\/\/\s*@ts-check\b/m.test(head)) {
+    missingDirective.push(rel);
+  }
+}
+
+if (missingFiles.length > 0) {
+  console.error('[check-jsdoc] gated files do not exist:');
+  for (const f of missingFiles) console.error(`  - ${f}`);
+  process.exit(1);
+}
+if (missingDirective.length > 0) {
+  console.error('[check-jsdoc] gated files are missing the `// @ts-check` directive:');
+  for (const f of missingDirective) console.error(`  - ${f}`);
+  console.error('Each gated file must opt into checkJs explicitly.');
+  console.error('Add `// @ts-check` as the first non-blank line, then re-run.');
+  process.exit(1);
+}
+
+const result = spawnSync(tscBin, ['--noEmit', '-p', tsconfigPath], {
+  encoding: 'utf8',
+  cwd: repoRoot,
+});
+
+// Fail fast if tsc itself could not be spawned (ENOENT on the binary,
+// EACCES, etc.). Without this guard, a missing `tsc` leaves
+// `result.error` set, empty stdout/stderr, and the rest of the script
+// would happily report "OK" because it found zero parseable errors.
+if (result.error) {
+  console.error(`[check-jsdoc] failed to invoke tsc at ${tscBin}: ${result.error.message}`);
+  process.exit(1);
+}
+
+// Killed by a signal (SIGKILL/OOM/SIGTERM) mid-run. spawnSync sets
+// `result.status` to null in that case and may leave partial output
+// containing parseable diagnostics, which would otherwise sneak past
+// the structural-failure check below.
+if (result.signal !== null) {
+  console.error(`[check-jsdoc] tsc was killed by signal: ${result.signal}`);
+  process.exit(1);
+}
+
+const output = `${result.stdout || ''}${result.stderr || ''}`;
+
+// Match each `path/to/file(line,col): error TSxxxx: ...` row. tsc emits
+// paths relative to the cwd we ran from (repoRoot).
+const allErrors = output
+  .split('\n')
+  .filter((line) => /\.[jt]sx?\(\d+,\d+\):\s+error\s+TS\d+:/.test(line));
+
+// Catch the structural-failure mode: tsc exited non-zero but produced no
+// parseable diagnostics. That means the failure is something like a
+// missing tsconfig, an internal compiler crash, or a config error,
+// rather than a normal type-check fail; the gate cannot reason about it.
+if (result.status !== 0 && allErrors.length === 0) {
+  console.error('[check-jsdoc] tsc exited with a non-zero status but produced no parseable diagnostics.');
+  console.error(`Status: ${result.status}`);
+  console.error(`Output:\n${output || '(empty)'}`);
+  process.exit(1);
+}
+
+const checkedAbsolute = CHECKED_FILES.map((rel) => path.join(packageDir, rel));
+
+const isCheckedError = (line) => {
+  const match = line.match(/^([^(]+)\(\d+,\d+\):/);
+  if (!match) return false;
+  const filePath = path.resolve(repoRoot, match[1]);
+  return checkedAbsolute.includes(filePath);
+};
+
+const checkedErrors = allErrors.filter(isCheckedError);
+
+console.log('[check-jsdoc] SD-2863 public-contract checkJs gate');
+console.log('='.repeat(72));
+console.log(`Files under gate: ${CHECKED_FILES.length}`);
+for (const f of CHECKED_FILES) {
+  console.log(`  - ${f}`);
+}
+console.log();
+
+if (checkedErrors.length === 0) {
+  console.log(`OK    ${CHECKED_FILES.length} gated file${CHECKED_FILES.length === 1 ? '' : 's'} clean.`);
+  console.log(`      (${allErrors.length} non-gated error${allErrors.length === 1 ? '' : 's'} in the wider tsc run, ignored — see SD-2863 follow-up tickets.)`);
+  process.exit(0);
+}
+
+console.log(`FAIL  ${checkedErrors.length} error${checkedErrors.length === 1 ? '' : 's'} in gated files:`);
+for (const line of checkedErrors) {
+  console.log(`        ${line}`);
+}
+console.log();
+console.log('Each error means a public-contract JSDoc has drifted from the implementation.');
+console.log('Fix the type or the code so they match. Adding `// @ts-ignore` is not the answer.');
+process.exit(1);

packages/superdoc/src/helpers/schema-introspection.js

@@ -1,9 +1,10 @@
+// @ts-check
 import { Editor, getRichTextExtensions, getStarterExtensions } from '@superdoc/super-editor';
 
 /**
  * @typedef {Object} SchemaIntrospectionOptions
  * @property {import('@superdoc/super-editor').Editor} [editor] - Existing Editor instance to introspect.
- * @property {Array} [extensions] - Extension list to build a schema from.
+ * @property {NonNullable<import('@superdoc/super-editor').EditorOptions['extensions']>} [extensions] - Extension list to build a schema from.
  * @property {'docx' | 'text' | 'html'} [mode] - Editor mode when building a schema. Defaults to 'docx'.
  */