@pikku/inspector 0.12.49 → 0.12.50

package/src/utils/schema-generator.ts

@@ -1,6 +1,12 @@
 import * as ts from 'typescript'
 import { createHash } from 'crypto'
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  statSync,
+  writeFileSync,
+} from 'fs'
 import { dirname, join, resolve } from 'path'
 import { createGenerator, RootlessError } from 'ts-json-schema-generator'
 import { register } from 'tsx/esm/api'
@@ -75,6 +81,7 @@ let cachedParsedConfig: ts.ParsedCommandLine | undefined
 let cachedTsconfigPath: string | undefined
 let cachedCustomTypesContent: string | undefined
 let cachedTSSchemas: Record<string, JSONValue> | undefined
+let cachedTSSchemaDeps: SchemaDep[] | undefined
 
 const SCHEMA_CACHE_VERSION = 1
 
@@ -118,32 +125,102 @@ function schemaCacheFile(cacheDir: string): string {
   return join(cacheDir, 'ts-schemas.json')
 }
 
-function readDiskTSSchemas(
+/** One file the generated schemas were derived from, as of when they were generated. */
+export type SchemaDep = { path: string; mtimeMs: number; size: number }
+
+/**
+ * The files a set of generated schemas was actually derived from.
+ *
+ * The cache key alone cannot answer whether the schemas are stale. It hashes the
+ * *synthesized* custom-types source, but a named type — `KnowledgeBundle`,
+ * `DbSchema`, anything a function declares as its input or output — appears
+ * there only as a name; its definition is resolved out of a project file or a
+ * dependency's `.d.ts`. Edit one of those and the key is unchanged, so a stale
+ * schema is served for a type that no longer looks like that. The failure is
+ * silent and outlives `rm -rf .pikku`, because this cache lives in
+ * `node_modules/.cache`.
+ *
+ * The program is rooted at the virtual file, so its source files are exactly the
+ * transitive closure the schemas depend on — nothing wider, nothing missed.
+ * Default-lib files are skipped: they change only when TypeScript itself does,
+ * which the inspector version in the key already covers.
+ */
+function fingerprintSchemaDeps(program: ts.Program): SchemaDep[] {
+  const deps: SchemaDep[] = []
+  for (const sourceFile of program.getSourceFiles()) {
+    if (program.isSourceFileDefaultLibrary(sourceFile)) continue
+    try {
+      const stat = statSync(sourceFile.fileName)
+      deps.push({
+        path: sourceFile.fileName,
+        mtimeMs: stat.mtimeMs,
+        size: stat.size,
+      })
+    } catch {
+      // The virtual root has no file on disk. Its content is the custom-types
+      // source, which the cache key already hashes.
+    }
+  }
+  return deps
+}
+
+/**
+ * Whether every file the schemas were derived from is still exactly as it was.
+ *
+ * mtime-and-size rather than a content hash: this runs on the cache-hit path,
+ * where the whole point is to answer in milliseconds without building a TS
+ * program. Anything that rewrites a file — a dependency rebuild, a checkout, an
+ * edit — moves its mtime, and a missing file reads as changed, so the answer errs
+ * toward regenerating.
+ */
+function schemaDepsUnchanged(deps: unknown): boolean {
+  if (!Array.isArray(deps)) return false
+  for (const dep of deps as SchemaDep[]) {
+    if (!dep || typeof dep.path !== 'string') return false
+    try {
+      const stat = statSync(dep.path)
+      if (stat.mtimeMs !== dep.mtimeMs || stat.size !== dep.size) return false
+    } catch {
+      return false
+    }
+  }
+  return true
+}
+
+export function readDiskTSSchemas(
   logger: InspectorLogger,
   cacheDir: string,
   key: string
-): Record<string, JSONValue> | null {
+): { schemas: Record<string, JSONValue>; deps: SchemaDep[] } | null {
   const file = schemaCacheFile(cacheDir)
   if (!existsSync(file)) return null
   try {
     const parsed = JSON.parse(readFileSync(file, 'utf-8'))
-    if (parsed?.key === key && parsed.schemas) return parsed.schemas
+    if (parsed?.key !== key || !parsed.schemas) return null
+    if (!schemaDepsUnchanged(parsed.deps)) {
+      logger.debug(
+        'Discarding TS-schema cache: a type it was built from changed'
+      )
+      return null
+    }
+    return { schemas: parsed.schemas, deps: parsed.deps }
   } catch (e) {
     logger.debug(`Ignoring unreadable TS-schema cache: ${(e as Error).message}`)
   }
   return null
 }
 
-function writeDiskTSSchemas(
+export function writeDiskTSSchemas(
   logger: InspectorLogger,
   cacheDir: string,
   key: string,
-  schemas: Record<string, JSONValue>
+  schemas: Record<string, JSONValue>,
+  deps: SchemaDep[]
 ): void {
   const file = schemaCacheFile(cacheDir)
   try {
     mkdirSync(dirname(file), { recursive: true })
-    writeFileSync(file, JSON.stringify({ key, schemas }))
+    writeFileSync(file, JSON.stringify({ key, schemas, deps }))
   } catch (e) {
     logger.debug(`Failed to persist TS-schema cache: ${(e as Error).message}`)
   }
@@ -234,7 +311,7 @@ function generateTSSchemas(
   additionalTypes?: string[],
   additionalProperties: boolean = false,
   generatedZodSchemas?: Record<string, JSONValue>
-): Record<string, JSONValue> {
+): { schemas: Record<string, JSONValue>; deps: SchemaDep[] } {
   const schemasSet = new Set(typesMap.customTypes.keys())
   for (const { inputs, outputs } of Object.values(functionMeta)) {
     const types = [...(inputs || []), ...(outputs || [])]
@@ -277,7 +354,7 @@ function generateTSSchemas(
     (s) => !PRIMITIVE_TYPES.has(s) && !generatedZodSchemas?.[s]
   )
   if (uncoveredSchemas.length === 0) {
-    return {}
+    return { schemas: {}, deps: [] }
   }
   logger.debug(
     `generateTSSchemas needed for ${uncoveredSchemas.length} types: ${uncoveredSchemas.slice(0, 3).join(', ')}${uncoveredSchemas.length > 3 ? '...' : ''}`
@@ -335,7 +412,28 @@ function generateTSSchemas(
     }
   })
 
-  return schemas
+  // Fingerprinted here, while the program is still alive — it is released as soon
+  // as the schemas are out of it.
+  return { schemas, deps: fingerprintSchemaDeps(program) }
+}
+
+/**
+ * Where the RUNTIME value of a schema lives, given where TypeScript resolved it.
+ *
+ * A schema imported from a built workspace package resolves to that package's
+ * declaration file, and importing a `.d.ts` yields a module with no exports at
+ * all — every one of them is a type. The value is in the emitted JS beside it, so
+ * that is what gets imported.
+ *
+ * Falls back to the original path when no sibling JS exists, which keeps the
+ * "could not find exported schema" error pointing at the file the developer
+ * actually wrote.
+ */
+export const schemaRuntimeFile = (sourceFile: string): string => {
+  const match = /\.d\.([cm]?)ts$/.exec(sourceFile)
+  if (!match) return sourceFile
+  const emitted = sourceFile.replace(/\.d\.([cm]?)ts$/, '.$1js')
+  return existsSync(emitted) ? emitted : sourceFile
 }
 
 /**
@@ -472,7 +570,9 @@ async function generateZodSchemas(
 
   // Collect unique source files and batch-import them in parallel
   const uniqueSourceFiles = [
-    ...new Set([...schemaLookup.values()].map((ref) => ref.sourceFile)),
+    ...new Set(
+      [...schemaLookup.values()].map((ref) => schemaRuntimeFile(ref.sourceFile))
+    ),
   ]
   logger.debug(
     `[TIMING] Zod schemas: ${schemaLookup.size} schemas from ${uniqueSourceFiles.length} files`
@@ -492,12 +592,13 @@ async function generateZodSchemas(
   const fallbackSchemas: [string, SchemaRef][] = []
 
   for (const [schemaName, ref] of schemaLookup.entries()) {
-    const mod = importedModules?.get(ref.sourceFile)
+    const runtimeFile = schemaRuntimeFile(ref.sourceFile)
+    const mod = importedModules?.get(runtimeFile)
     if (mod) {
       const zodSchema = mod[ref.variableName]
       if (!zodSchema) {
         errors.push(
-          `Could not find exported schema '${ref.variableName}' in ${ref.sourceFile} for ${schemaName}. Available exports: ${Object.keys(mod).join(', ')}`
+          `Could not find exported schema '${ref.variableName}' in ${runtimeFile} for ${schemaName}. Available exports: ${Object.keys(mod).join(', ')}`
         )
         continue
       }
@@ -531,12 +632,13 @@ async function generateZodSchemas(
       `Falling back to register() import for ${fallbackSchemas.length} schema(s)`
     )
     for (const [schemaName, ref] of fallbackSchemas) {
+      const runtimeFile = schemaRuntimeFile(ref.sourceFile)
       try {
-        const module = await importWithRegister(ref.sourceFile)
+        const module = await importWithRegister(runtimeFile)
         const zodSchema = module[ref.variableName]
         if (!zodSchema) {
           errors.push(
-            `Could not find exported schema '${ref.variableName}' in ${ref.sourceFile} for ${schemaName}. Available exports: ${Object.keys(module).join(', ')}`
+            `Could not find exported schema '${ref.variableName}' in ${runtimeFile} for ${schemaName}. Available exports: ${Object.keys(module).join(', ')}`
           )
           continue
         }
@@ -595,8 +697,15 @@ export async function generateAllSchemas(
     requiredTypes
   )
 
-  // Fast path: same process, types unchanged — reuse the in-memory result.
-  if (cachedTSSchemas && cachedCustomTypesContent === customTypesContent) {
+  // Fast path: same process, types unchanged — reuse the in-memory result. The
+  // dep check is what makes this correct under `pikku dev`, where the process
+  // outlives the edits: the custom-types source is identical whenever a named
+  // type changes shape without changing its name.
+  if (
+    cachedTSSchemas &&
+    cachedCustomTypesContent === customTypesContent &&
+    schemaDepsUnchanged(cachedTSSchemaDeps)
+  ) {
     logger.debug('Reusing cached TS schemas (types unchanged)')
     return { ...cachedTSSchemas, ...zodSchemas }
   }
@@ -612,12 +721,13 @@ export async function generateAllSchemas(
     if (disk) {
       logger.debug('Reusing on-disk TS schemas (types unchanged across runs)')
       cachedCustomTypesContent = customTypesContent
-      cachedTSSchemas = disk
-      return { ...disk, ...zodSchemas }
+      cachedTSSchemas = disk.schemas
+      cachedTSSchemaDeps = disk.deps
+      return { ...disk.schemas, ...zodSchemas }
     }
   }
 
-  const tsSchemas = generateTSSchemas(
+  const { schemas: tsSchemas, deps: tsSchemaDeps } = generateTSSchemas(
     logger,
     config.tsconfig,
     customTypesContent,
@@ -639,9 +749,16 @@ export async function generateAllSchemas(
 
   cachedCustomTypesContent = customTypesContent
   cachedTSSchemas = tsSchemas
+  cachedTSSchemaDeps = tsSchemaDeps
 
   if (config.cacheDir && cacheKey) {
-    writeDiskTSSchemas(logger, config.cacheDir, cacheKey, tsSchemas)
+    writeDiskTSSchemas(
+      logger,
+      config.cacheDir,
+      cacheKey,
+      tsSchemas,
+      tsSchemaDeps
+    )
   }
 
   return { ...tsSchemas, ...zodSchemas }