fix(docs): map exact source aliases in built checks

scripts/doc-typecheck-paths.spec.ts

@@ -0,0 +1,17 @@
+import { describe, expect, it } from 'vitest'
+import { builtDeclarationPath } from './doc-typecheck-paths.ts'
+
+describe('builtDeclarationPath', () => {
+  it('maps package source directories and exact entry files to built declarations', () => {
+    expect(builtDeclarationPath('./packages/*/*/src')).toBe('./packages/*/*/lib/types')
+    expect(builtDeclarationPath('./packages/support/invariants/src/index.ts'))
+      .toBe('./packages/support/invariants/lib/types/index.d.ts')
+    expect(builtDeclarationPath('./packages/core/session/src/invariant.ts'))
+      .toBe('./packages/core/session/lib/types/invariant.d.ts')
+  })
+
+  it('rejects aliases without a supported source target', () => {
+    expect(() => builtDeclarationPath('./packages/support/invariants/source/index.ts'))
+      .toThrow('cannot map workspace source path')
+  })
+})

scripts/doc-typecheck-paths.ts

@@ -0,0 +1,11 @@
+/** Map one workspace source alias target to its declaration-build target. */
+export function builtDeclarationPath(candidate: string): string {
+  if (candidate.endsWith('/src')) {
+    return `${candidate.slice(0, -'/src'.length)}/lib/types`
+  }
+  const sourceFile = /^(.*)\/src\/(.+)\.ts$/.exec(candidate)
+  if (sourceFile?.[1] && sourceFile[2]) {
+    return `${sourceFile[1]}/lib/types/${sourceFile[2]}.d.ts`
+  }
+  throw new Error(`doc-typecheck: cannot map workspace source path to built declarations: ${candidate}`)
+}

scripts/doc-typecheck.ts

@@ -8,6 +8,7 @@ import { execFileSync } from 'node:child_process'
 import { globSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
 import { join, relative, resolve } from 'node:path'
 import ts from 'typescript'
+import { builtDeclarationPath } from './doc-typecheck-paths.ts'
 import { extractFences } from './md-fences.ts'
 
 const root = resolve(import.meta.dirname, '..')
@@ -65,12 +66,7 @@ function builtTypeCompilerOptions(): ts.CompilerOptions {
   if (parsed.options.paths === undefined) throw new Error('doc-typecheck: root tsconfig has no workspace paths')
   const paths = Object.fromEntries(Object.entries(parsed.options.paths).map(([specifier, candidates]) => [
     specifier,
-    candidates.map((candidate) => {
+    candidates.map(builtDeclarationPath),
-      if (!candidate.endsWith('/src')) {
-        throw new Error(`doc-typecheck: cannot map workspace source path to built declarations: ${candidate}`)
-      }
-      return `${candidate.slice(0, -'/src'.length)}/lib/types`
-    }),
   ]))
   const options: ts.CompilerOptions = {
     ...parsed.options,