fix(spec): file-description skips doc blocks the lazify codemod detached from their symbols

Author: claude

packages/spec/scripts/file-description.test.ts

@@ -198,16 +198,26 @@ describe('findModuleDocBlock — a block documents a symbol, or it documents the
   });
 
   it('keeps a header the lazify codemod separated from the imports', () => {
-    // `scripts/lazify-schemas.ts` inserts its import after the leading run of
-    // comments and imports — and that run swallows a doc block, so a header can
-    // end up with imports on both sides. It is still a header.
+    // `api/analytics.zod.ts`, as it really is on `main`. `lazify-schemas.ts`
+    // inserts its import after the leading run of comments and imports — and
+    // that run swallows a doc block, so a header can end up with imports on
+    // both sides. It is still a header, and the banner is why: the block was
+    // not sitting against the declaration before the codemod ran either.
+    //
+    // ⚠️ This case used to be written WITHOUT the banner, and that reduction
+    // dropped the one line carrying the verdict (#13263) — see the case below,
+    // which is that bannerless shape and now asserts the opposite.
     const source = [
       "import { z } from 'zod';",
       '',
       '/**',
       ' * Analytics API Protocol',
       ' */',
       '',
+      '// ==========================================',
+      '// 1. API Endpoints',
+      '// ==========================================',
+      '',
       "import { lazySchema } from '../shared/lazy-schema';",
       'export const AnalyticsEndpoint = z.enum([]);',
       '',
@@ -220,6 +230,143 @@ describe('findModuleDocBlock — a block documents a symbol, or it documents the
   });
 });
 
+/**
+ * #13263 — an injected import is not a separator.
+ *
+ * `lazify-schemas.ts` injects its `lazySchema` import at the END of the file's
+ * leading run of comments, blank lines and imports, and its regex for that run
+ * counts a doc block among the comments. A module written as an import, a blank
+ * line, `Service Status Enum` and then `export const ServiceStatus` therefore
+ * came out of the codemod with the import BETWEEN the block and its symbol —
+ * and condition 3, which skipped only blank lines, then read the block as
+ * documenting nothing. 28 reference pages opened with one schema's comment, and
+ * `gen:skill-refs` copied each first line into the published skill indexes.
+ *
+ * The tightening applies only INSIDE the import block and stops at a comment of
+ * any kind, which is what the four `keeps` cases below pin: without the first
+ * limb, three real headers written above their imports go blank; without the
+ * second, `api/analytics` and `system/cache` do.
+ *
+ * MEASURED over `packages/spec/src` (193 sources, base `3322527f`): 28 pages
+ * lose a misattributed opening, 0 change to a different block, 165 are
+ * byte-identical. The corpus limb at the end of this file re-derives that
+ * rather than restating it.
+ */
+describe('findModuleDocBlock — #13263: an import injected between a block and its symbol', () => {
+  it('rejects a block the codemod separated from the declaration it documents', () => {
+    // `api/discovery.zod.ts`, `data/field.zod.ts`, and 26 more. This is the
+    // previous case's source with the banner removed — the whole difference.
+    const source = [
+      "import { z } from 'zod';",
+      '',
+      '/**',
+      ' * Service Status Enum',
+      ' * Describes the operational state of a service in the discovery response.',
+      ' */',
+      "import { lazySchema } from '../shared/lazy-schema';",
+      "export const ServiceStatus = z.enum(['available', 'stub']);",
+      '',
+    ].join('\n');
+    expect(findModuleDocBlock(source)).toBeNull();
+  });
+
+  it('rejects it across a blank line and several injected imports', () => {
+    // `automation/flow.zod.ts` has five between the block and `FlowNodeAction`;
+    // `data/object.zod.ts` six. Distance in plumbing lines is not a signal.
+    const source = [
+      "import { z } from 'zod';",
+      "import { ProtectionSchema } from '../shared/protection.zod';",
+      '',
+      '/**',
+      ' * Flow Node Types — built-in seed set (ADR-0018).',
+      ' */',
+      "import { lazySchema } from '../shared/lazy-schema';",
+      "import { retiredKey } from '../shared/retired-key';",
+      "import { strictObject } from '../shared/strict-object';",
+      '',
+      "export const FlowNodeAction = z.enum(['start', 'end']);",
+      '',
+    ].join('\n');
+    expect(findModuleDocBlock(source)).toBeNull();
+  });
+
+  it('rejects it across a MULTI-LINE import — continuation lines are plumbing too', () => {
+    // `data/document.zod.ts` and `kernel/execution-context.zod.ts` reach their
+    // declaration only over a wrapped import's `Foo,` and `} from '…';` lines.
+    const source = [
+      "import { z } from 'zod';",
+      '',
+      '/**',
+      ' * Document Version Schema',
+      ' */',
+      'import {',
+      '  MetadataProtectionFields,',
+      '  ProtectionSchema,',
+      "} from '../kernel/metadata-protection.zod';",
+      'export const DocumentVersionSchema = z.object({});',
+      '',
+    ].join('\n');
+    expect(findModuleDocBlock(source)).toBeNull();
+  });
+
+  it('keeps a header written ABOVE the imports, even with a declaration right after them', () => {
+    // `system/doc.zod.ts`, `cloud/template-manifest.zod.ts`,
+    // `api/error-code-ledger.zod.ts`. The codemod injects AFTER the last
+    // import, so a block preceding every import preceded them beforehand too —
+    // the position is the proof, and dropping this limb blanks all three.
+    const source = [
+      '// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.',
+      '',
+      '/**',
+      ' * Package Documentation Metadata Protocol (ADR-0046)',
+      ' */',
+      '',
+      "import { z } from 'zod';",
+      "import { lazySchema } from '../shared/lazy-schema';",
+      '',
+      'export const DocSchema = z.object({});',
+      '',
+    ].join('\n');
+    expect(opening(findModuleDocBlock(source))).toBe('Package Documentation Metadata Protocol (ADR-0046)');
+  });
+
+  it('keeps a header inside the imports when the next schema carries its own JSDoc', () => {
+    // `system/cache.zod.ts` — its block names itself ("This File") and the
+    // declaration beyond the injected import is already documented, so that
+    // import says nothing about what the block documents.
+    const source = [
+      "import { z } from 'zod';",
+      "import { CronExpressionInputSchema } from '../shared/expression.zod';",
+      '',
+      '/**',
+      ' * Application-Level Cache Protocol',
+      ' */',
+      "import { lazySchema } from '../shared/lazy-schema';",
+      '',
+      '/** Cache eviction strategy. */',
+      "export const CacheStrategySchema = z.enum(['lru']);",
+      '',
+    ].join('\n');
+    expect(opening(findModuleDocBlock(source))).toBe('Application-Level Cache Protocol');
+  });
+
+  it('keeps a block with no declaration on the far side at all', () => {
+    // A module that is nothing but re-exports — the plumbing runs to the end of
+    // the file, so there is no symbol for the block to have been torn from.
+    const source = [
+      "import { z } from 'zod';",
+      '',
+      '/**',
+      ' * Environment Artifact Envelope — re-export',
+      ' */',
+      "export { EnvironmentArtifactSchema } from './artifact.zod';",
+      "export type { EnvironmentArtifact } from './artifact.zod';",
+      '',
+    ].join('\n');
+    expect(opening(findModuleDocBlock(source))).toBe('Environment Artifact Envelope — re-export');
+  });
+});
+
 describe('renderFileDescription', () => {
   // `fromCategory` is the directory the rendered module lives in (#6484); these
   // cases reference `automation/` and are written as if from there.
@@ -1023,6 +1170,58 @@ describe('corpus — no reference source donates a symbol comment to its page',
     expect(openingOf('api/error-code-ledger.zod.ts'))
       .toBe('Error-Code Ledger (ADR-0112 D3).');
   });
+
+  /**
+   * #13263's corpus limb — the half that cannot rot.
+   *
+   * Re-derives the verdict from the real tree instead of restating a file list:
+   * a selected block that sits inside the import block must have a COMMENT on
+   * the far side of that plumbing, never a declaration. A source that acquires
+   * the codemod shape later cannot quietly re-acquire a wrong page description,
+   * and the three headers written above their imports are pinned by name in the
+   * `#6145` case above, so neither direction can drift alone.
+   */
+  it('never selects a block with a declaration on the far side of the imports', () => {
+    const PLUMBING = /^(?:import\b|export\s*(?:\*|\{|type\s*\{))/;
+    const offenders: string[] = [];
+    for (const file of zodFiles) {
+      const source = fs.readFileSync(file, 'utf-8');
+      const block = findModuleDocBlock(source);
+      if (block === null) continue;
+      const lines = source.split('\n');
+      const marker = `/**${block}*/`;
+      const at = source.indexOf(marker);
+      if (at < 0) continue; // already reported by the case above
+      const startLine = source.slice(0, at).split('\n').length - 1;
+      const endLine = startLine + marker.split('\n').length - 1;
+      if (!lines.slice(0, startLine).some(l => PLUMBING.test(l))) continue; // above the imports
+
+      for (let i = endLine + 1; i < lines.length; i++) {
+        const line = lines[i];
+        if (line.trim() === '') continue;
+        if (line.trimStart().startsWith('/')) break; // a comment ends the preamble
+        if (PLUMBING.test(line)) continue;
+        if (!/^[A-Za-z_$@]/.test(line)) continue; // continuation / closing punctuation
+        offenders.push(`${path.relative(SRC_DIR, file)} → ${line.slice(0, 60)}`);
+        break;
+      }
+    }
+    expect(offenders).toEqual([]);
+  });
+
+  it('publishes no description for the modules whose opening was one schema\'s doc', () => {
+    const openingOf = (rel: string) =>
+      opening(findModuleDocBlock(fs.readFileSync(path.join(SRC_DIR, rel), 'utf-8')));
+
+    // Four of the 28, one per shape: the plain single injected import, the run
+    // of five, the wrapped import, and the one whose page-wide blast radius the
+    // card measured (`gen:skill-refs` shipped `Field Type Enum` as the pointer
+    // row for a module of ~40 field schemas).
+    expect(openingOf('api/discovery.zod.ts')).toBeNull();
+    expect(openingOf('automation/flow.zod.ts')).toBeNull();
+    expect(openingOf('kernel/execution-context.zod.ts')).toBeNull();
+    expect(openingOf('data/field.zod.ts')).toBeNull();
+  });
 });
 
 /**

packages/spec/scripts/lib/file-description.ts

@@ -33,7 +33,8 @@
  *    and this repo writes module headers on either side of them); the first
  *    `const`/`export const`/… does.
  * 3. **Documenting nothing** — the block is not immediately followed by a
- *    declaration.
+ *    declaration, and — when the block sits INSIDE the import block — no
+ *    declaration sits on the far side of that plumbing either.
  *
  * (3) is the load-bearing one, and it is simply TSDoc's own rule read back: a
  * doc block belongs to the declaration it immediately precedes, which is why
@@ -42,8 +43,51 @@
  * as the Realtime page's opening paragraph was the generator inventing a second
  * meaning for text that already had one. "Immediately" means blank lines only:
  * nobody separates a JSDoc from its symbol with a `// ═══` banner, so a banner
- * (or another doc block, or an import) between the two marks the end of the
- * preamble rather than an attachment.
+ * (or another doc block) between the two marks the end of the preamble rather
+ * than an attachment.
+ *
+ * ## An import between a block and its symbol is not a separator (#13263)
+ *
+ * The one exception to that last sentence, and it is not a judgement call — it
+ * is a codemod. `scripts/lazify-schemas.ts` injects
+ * `import { lazySchema } from '…/shared/lazy-schema';` at the END of the file's
+ * leading run of comments, blank lines and imports, and the regex it uses for
+ * that run counts a doc block among the comments (its comment alternative is
+ * slash-star, any run, star-slash — a doc block matches it). So when a module
+ * was written as an `import { z } from 'zod';`, a blank line, a doc block
+ * reading `Service Status Enum`, and then `export const ServiceStatus`,
+ * the run swallowed the doc block and the injected import landed BETWEEN the
+ * block and the symbol it documents. Nothing about the block changed; only the
+ * detector's view of it did. Reading that import as "the preamble ends here"
+ * republished 28 symbol comments as their pages' subjects, `api/discovery`'s
+ * `Service Status Enum` and `data/field`'s `Field Type Enum` among them — and
+ * `gen:skill-refs` copied each one's first line into the PUBLISHED skill
+ * indexes, so the misattribution shipped to customer projects.
+ *
+ * Hence condition 3's second half: a declaration reachable across nothing but
+ * blank lines and plumbing is still the block's subject. Two things keep this a
+ * tightening rather than a demotion of the spelling `MODULE_PLUMBING` exists to
+ * permit — measured over all 193 reference sources, and both are load-bearing:
+ *
+ * - **It applies only INSIDE the import block.** A header written ABOVE the
+ *   imports is where the codemod cannot have put it: the injection point is
+ *   after the last import, so a block preceding every import was preceding them
+ *   before the codemod ran too. Without that half, `api/error-code-ledger`,
+ *   `cloud/template-manifest` and `system/doc` — three real headers whose
+ *   imports happen to be followed directly by a declaration — lose their
+ *   opening paragraph.
+ * - **A comment of any kind on the far side still ends the preamble.** A `// ═══`
+ *   banner or a second doc block means the block did NOT sit against the
+ *   declaration before the codemod ran, so the injection tells us nothing.
+ *   `api/analytics` (banner) and `system/cache` (the next schema's own JSDoc)
+ *   keep their headers through exactly this clause.
+ *
+ * What it deliberately does NOT decide is the block that sits inside the import
+ * list with a comment on the far side: `system/cache` and `shared/mapping` are
+ * genuine headers there and seven others are detached symbol docs, and no
+ * positional or structural signal separates them — only the prose does. That
+ * residue needs an explicit `@module` marker or a corpus pass, not a cleverer
+ * detector; #13263 records the reading, module by module.
  *
  * When no block qualifies, the module has no description and the page prints
  * none. 宁可缺,不要错 — a missing paragraph is a gap the reader can see, while
@@ -255,6 +299,40 @@ function nextNonBlankLine(lines: readonly string[], from: number): number | null
   return i < lines.length ? i : null;
 }
 
+/**
+ * Is there a declaration on the far side of the plumbing that starts at `from`
+ * — i.e. does everything between hold nothing but blank lines and imports?
+ *
+ * Only ever asked of a block that sits INSIDE the import block, where the one
+ * thing known to put an import between a doc block and its symbol is the lazify
+ * codemod (see the module comment). Answering `true` there restores the verdict
+ * the block had before that import was injected.
+ *
+ * A comment of any kind — a `// ═══` banner, a second doc block, an import's
+ * own explanatory note — answers `false` instead of being walked over. That is
+ * the same boundary `nextNonBlankLine` draws and for the same reason: it means
+ * the block was NOT sitting against the declaration beforehand either, so the
+ * injected import carries no information about what the block documents. It is
+ * what keeps `api/analytics` (banner) and `system/cache` (the next schema's own
+ * JSDoc) opening with their real module headers.
+ *
+ * Continuation and closing lines of a multi-line import (`  Foo,`,
+ * `} from './x';`) are plumbing too — they open with neither an identifier
+ * character nor a comment delimiter, exactly as `findModuleDocBlock`'s own walk
+ * reads them.
+ */
+function declarationBeyondPlumbing(lines: readonly string[], from: number): boolean {
+  for (let i = from; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.trim() === '') continue;
+    if (line.trimStart().startsWith('/')) return false; // a comment ends the preamble
+    if (MODULE_PLUMBING.test(line)) continue;
+    if (!startsDeclaration(line)) continue; // continuation / closing punctuation
+    return true;
+  }
+  return false;
+}
+
 /**
  * The module's own doc block, INNER text only (delimiters stripped, `*` line
  * prefixes intact) — or `null` when the module does not have one.
@@ -271,6 +349,12 @@ function nextNonBlankLine(lines: readonly string[], from: number): number | null
 export function findModuleDocBlock(source: string): string | null {
   const lines = source.split('\n');
 
+  // Whether the walk has passed an import / re-export, i.e. whether a block
+  // found from here on sits INSIDE the import block rather than above it. Only
+  // there can the lazify codemod have put an import between a block and its
+  // symbol, so only there does the far-side check below apply (#13263).
+  let insideImportBlock = false;
+
   let i = 0;
   while (i < lines.length) {
     const line = lines[i];
@@ -280,13 +364,16 @@ export function findModuleDocBlock(source: string): string | null {
       if (end >= lines.length) return null; // unterminated — nothing to trust
       const next = nextNonBlankLine(lines, end + 1);
       if (next !== null && startsDeclaration(lines[next])) return null; // documents a symbol
+      // …and the same verdict when only injected plumbing stands between the
+      // two: the import moved, the attachment did not.
+      if (insideImportBlock && declarationBeyondPlumbing(lines, end + 1)) return null;
       const raw = lines.slice(i, end + 1).join('\n');
       return raw.slice(raw.indexOf('/**') + 3, raw.lastIndexOf('*/'));
     }
 
     if (line.startsWith('/*')) { i = endOfBlockComment(lines, i) + 1; continue; }
     if (line.trim() === '' || line.trim().startsWith('//') || !/^\S/.test(line)) { i++; continue; }
-    if (MODULE_PLUMBING.test(line)) { i++; continue; }
+    if (MODULE_PLUMBING.test(line)) { insideImportBlock = true; i++; continue; }
     if (startsDeclaration(line)) return null; // header zone closed before any block
 
     i++; // closing punctuation of a multi-line import / re-export