ts-procedures 8.1.1 → 8.2.0

package/src/codegen/targets/_shared/write-files.test.ts

@@ -1,8 +1,14 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
-import { mkdir, readFile, rm, writeFile, stat, mkdtemp } from 'node:fs/promises'
+import { mkdir, readFile, rm, writeFile, stat, mkdtemp, readdir } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { writeGeneratedFiles } from './write-files.js'
+import { CODEGEN_HEADER } from '../../constants.js'
+
+/** Build file contents that carry the package signature (a generated file). */
+function signed(body = 'export const x = 1\n'): string {
+  return `${CODEGEN_HEADER}\n\n${body}`
+}
 
 describe('writeGeneratedFiles', () => {
   describe('dryRun mode', () => {
@@ -32,22 +38,46 @@ describe('writeGeneratedFiles', () => {
       await expect(stat(dir)).rejects.toBeInstanceOf(Error)
     })
 
-    it('logs a clean-outDir notice when cleanOutDir is true', async () => {
-      await writeGeneratedFiles([], '/out', { dryRun: true, cleanOutDir: true })
-      expect(logSpy).toHaveBeenCalledWith('[dry-run] Would clean outDir: /out')
-    })
-
-    it('does not log clean-outDir when cleanOutDir is false', async () => {
-      await writeGeneratedFiles([{ path: '/out/x', code: 'x' }], '/out', { dryRun: true })
-      const messages = logSpy.mock.calls.map((c: unknown[]) => c[0])
-      expect(messages.find((m: unknown) => String(m).includes('Would clean'))).toBeUndefined()
-    })
-
     it('counts bytes as utf-8', async () => {
       // "é" is 2 bytes in utf-8.
       await writeGeneratedFiles([{ path: '/x/e.txt', code: 'é' }], '/x', { dryRun: true })
       expect(logSpy).toHaveBeenCalledWith('[dry-run] Would write: /x/e.txt (2 bytes)')
     })
+
+    it('logs would-remove for an orphaned generated file under cleanOutDir, without deleting it', async () => {
+      const outDir = await mkdtemp(join(tmpdir(), 'write-files-dry-'))
+      try {
+        await writeFile(join(outDir, 'orphan.ts'), signed(), 'utf-8')
+
+        await writeGeneratedFiles(
+          [{ path: join(outDir, 'fresh.ts'), code: signed() }],
+          outDir,
+          { dryRun: true, cleanOutDir: true },
+        )
+
+        expect(logSpy).toHaveBeenCalledWith(
+          `[dry-run] Would remove orphaned generated file: ${join(outDir, 'orphan.ts')}`,
+        )
+        // Nothing was actually removed.
+        expect(await readFile(join(outDir, 'orphan.ts'), 'utf-8')).toBe(signed())
+      } finally {
+        await rm(outDir, { recursive: true, force: true })
+      }
+    })
+
+    it('does not log a would-remove notice when cleanOutDir is false', async () => {
+      const outDir = await mkdtemp(join(tmpdir(), 'write-files-dry-'))
+      try {
+        await writeFile(join(outDir, 'orphan.ts'), signed(), 'utf-8')
+        await writeGeneratedFiles([{ path: join(outDir, 'x.ts'), code: signed() }], outDir, {
+          dryRun: true,
+        })
+        const messages = logSpy.mock.calls.map((c: unknown[]) => String(c[0]))
+        expect(messages.find((m: string) => m.includes('Would remove'))).toBeUndefined()
+      } finally {
+        await rm(outDir, { recursive: true, force: true })
+      }
+    })
   })
 
   describe('real write mode', () => {
@@ -79,32 +109,113 @@ describe('writeGeneratedFiles', () => {
       expect(await readFile(join(nested, 'x.txt'), 'utf-8')).toBe('x')
     })
 
-    it('removes outDir when cleanOutDir is true before writing', async () => {
-      // Pre-populate a stale file.
-      await mkdir(outDir, { recursive: true })
-      await writeFile(join(outDir, 'stale.txt'), 'stale', 'utf-8')
-
-      await writeGeneratedFiles(
-        [{ path: join(outDir, 'fresh.txt'), code: 'fresh' }],
-        outDir,
-        { cleanOutDir: true },
-      )
-
-      await expect(readFile(join(outDir, 'stale.txt'), 'utf-8')).rejects.toBeInstanceOf(Error)
-      expect(await readFile(join(outDir, 'fresh.txt'), 'utf-8')).toBe('fresh')
+    describe('cleanOutDir (marker-based prune)', () => {
+      it('removes an orphaned generated file that is no longer emitted', async () => {
+        // A previously-generated scope file that this run does not re-emit.
+        await writeFile(join(outDir, 'orphan-scope.ts'), signed(), 'utf-8')
+
+        await writeGeneratedFiles(
+          [{ path: join(outDir, 'fresh.ts'), code: signed() }],
+          outDir,
+          { cleanOutDir: true },
+        )
+
+        await expect(readFile(join(outDir, 'orphan-scope.ts'), 'utf-8')).rejects.toBeInstanceOf(
+          Error,
+        )
+        expect(await readFile(join(outDir, 'fresh.ts'), 'utf-8')).toBe(signed())
+      })
+
+      it('never deletes a file that lacks the package signature', async () => {
+        // Hand-written file the developer co-located in the output dir.
+        await writeFile(join(outDir, 'hand-written.ts'), 'export const mine = 1\n', 'utf-8')
+        // Even a file that merely imports from ts-procedures (no -codegen token).
+        await writeFile(
+          join(outDir, 'helper.ts'),
+          "import { createClient } from 'ts-procedures/client'\n",
+          'utf-8',
+        )
+
+        await writeGeneratedFiles(
+          [{ path: join(outDir, 'fresh.ts'), code: signed() }],
+          outDir,
+          { cleanOutDir: true },
+        )
+
+        expect(await readFile(join(outDir, 'hand-written.ts'), 'utf-8')).toBe(
+          'export const mine = 1\n',
+        )
+        expect(await readFile(join(outDir, 'helper.ts'), 'utf-8')).toBe(
+          "import { createClient } from 'ts-procedures/client'\n",
+        )
+      })
+
+      it('does not delete a signed file that is part of the current output', async () => {
+        // Pre-existing signed file that IS re-emitted this run — it should be
+        // overwritten, not removed-then-rewritten in a way that loses it.
+        await writeFile(join(outDir, 'users.ts'), signed('old'), 'utf-8')
+
+        await writeGeneratedFiles(
+          [{ path: join(outDir, 'users.ts'), code: signed('new') }],
+          outDir,
+          { cleanOutDir: true },
+        )
+
+        expect(await readFile(join(outDir, 'users.ts'), 'utf-8')).toBe(signed('new'))
+      })
+
+      it('prunes orphans left by a different package version (version-agnostic)', async () => {
+        // A file generated by an older release: different version in the header.
+        const oldHeader = '// Auto-generated by ts-procedures-codegen (v0.0.1) — do not edit'
+        await writeFile(join(outDir, 'legacy.ts'), `${oldHeader}\n\nexport const y = 2\n`, 'utf-8')
+
+        await writeGeneratedFiles(
+          [{ path: join(outDir, 'fresh.ts'), code: signed() }],
+          outDir,
+          { cleanOutDir: true },
+        )
+
+        await expect(readFile(join(outDir, 'legacy.ts'), 'utf-8')).rejects.toBeInstanceOf(Error)
+      })
+
+      it('skips subdirectories entirely', async () => {
+        const sub = join(outDir, 'nested')
+        await mkdir(sub, { recursive: true })
+        await writeFile(join(sub, 'inner.ts'), signed(), 'utf-8')
+
+        await writeGeneratedFiles(
+          [{ path: join(outDir, 'fresh.ts'), code: signed() }],
+          outDir,
+          { cleanOutDir: true },
+        )
+
+        // The nested dir and its signed file are untouched.
+        expect(await readFile(join(sub, 'inner.ts'), 'utf-8')).toBe(signed())
+        const entries = await readdir(outDir)
+        expect(entries).toContain('nested')
+      })
+
+      it('does not throw when outDir does not exist yet', async () => {
+        const fresh = join(outDir, 'brand-new')
+        await expect(
+          writeGeneratedFiles([{ path: join(fresh, 'a.ts'), code: signed() }], fresh, {
+            cleanOutDir: true,
+          }),
+        ).resolves.toBeUndefined()
+        expect(await readFile(join(fresh, 'a.ts'), 'utf-8')).toBe(signed())
+      })
     })
 
-    it('does not remove outDir when cleanOutDir is false', async () => {
-      await mkdir(outDir, { recursive: true })
+    it('does not remove anything when cleanOutDir is false', async () => {
+      await writeFile(join(outDir, 'orphan.ts'), signed(), 'utf-8')
       await writeFile(join(outDir, 'keep.txt'), 'keep', 'utf-8')
 
-      await writeGeneratedFiles(
-        [{ path: join(outDir, 'new.txt'), code: 'new' }],
-        outDir,
-      )
+      await writeGeneratedFiles([{ path: join(outDir, 'new.ts'), code: signed() }], outDir)
 
+      // Even a signed orphan stays put when cleanOutDir is not requested.
+      expect(await readFile(join(outDir, 'orphan.ts'), 'utf-8')).toBe(signed())
       expect(await readFile(join(outDir, 'keep.txt'), 'utf-8')).toBe('keep')
-      expect(await readFile(join(outDir, 'new.txt'), 'utf-8')).toBe('new')
+      expect(await readFile(join(outDir, 'new.ts'), 'utf-8')).toBe(signed())
     })
   })
 })

package/src/codegen/targets/_shared/write-files.ts

@@ -1,4 +1,6 @@
-import { mkdir, rm, writeFile } from 'node:fs/promises'
+import { mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { CODEGEN_SIGNATURE } from '../../constants.js'
 
 export interface GeneratedFile {
   path: string
@@ -8,10 +10,46 @@ export interface GeneratedFile {
 export interface WriteOptions {
   /** When true, log what would happen instead of touching the filesystem. */
   dryRun?: boolean
-  /** When true, recursively delete `outDir` before writing. */
+  /**
+   * When true, remove orphaned generated files from `outDir` before writing —
+   * i.e. files this run no longer emits that carry the `ts-procedures-codegen`
+   * signature. Files lacking the signature (hand-written, other tools' output)
+   * are never touched.
+   */
   cleanOutDir?: boolean
 }
 
+/** Only the head of a file is read to detect the signature; it lives at the top. */
+const SIGNATURE_SCAN_BYTES = 512
+
+/**
+ * Returns the top-level files in `outDir` that carry the package signature but
+ * are NOT part of `written` — the orphans left behind by a prior run whose
+ * scope/route no longer exists. Subdirectories are skipped (targets emit flat),
+ * and any file without the signature is left untouched.
+ */
+async function findOrphans(outDir: string, written: Set<string>): Promise<string[]> {
+  let entries
+  try {
+    entries = await readdir(outDir, { withFileTypes: true })
+  } catch (err) {
+    // Nothing to prune if the dir doesn't exist yet (first run).
+    if ((err as { code?: string }).code === 'ENOENT') return []
+    throw err
+  }
+
+  const orphans: string[] = []
+  for (const entry of entries) {
+    if (!entry.isFile()) continue
+    const path = join(outDir, entry.name)
+    if (written.has(path)) continue // re-emitted this run — it will be overwritten
+    const buf = await readFile(path)
+    const head = buf.subarray(0, SIGNATURE_SCAN_BYTES).toString('utf-8')
+    if (head.includes(CODEGEN_SIGNATURE)) orphans.push(path)
+  }
+  return orphans
+}
+
 /**
  * Persists the generated files to disk (or simulates the writes under
  * `dryRun`). Centralises the dryRun / cleanOutDir / mkdir / writeFile
@@ -20,10 +58,11 @@ export interface WriteOptions {
  *
  * Behaviour:
  * - `dryRun: true` — logs `[dry-run] Would write: <path> (<bytes> bytes)` per
- *   file, plus a leading `[dry-run] Would clean outDir: <outDir>` when
- *   `cleanOutDir: true`. No filesystem mutation.
- * - `dryRun: false` (default) — when `cleanOutDir`, recursively removes
- *   `outDir`; then ensures it exists; then writes each file as utf-8.
+ *   file, plus `[dry-run] Would remove orphaned generated file: <path>` for
+ *   each prunable orphan when `cleanOutDir: true`. No filesystem mutation.
+ * - `dryRun: false` (default) — when `cleanOutDir`, removes orphaned generated
+ *   files (signed by `ts-procedures-codegen`, no longer emitted); then ensures
+ *   `outDir` exists; then writes each file as utf-8.
  */
 export async function writeGeneratedFiles(
   files: readonly GeneratedFile[],
@@ -31,10 +70,13 @@ export async function writeGeneratedFiles(
   opts: WriteOptions = {},
 ): Promise<void> {
   const { dryRun = false, cleanOutDir = false } = opts
+  const written = new Set(files.map((f) => f.path))
 
   if (dryRun) {
     if (cleanOutDir) {
-      console.log(`[dry-run] Would clean outDir: ${outDir}`)
+      for (const orphan of await findOrphans(outDir, written)) {
+        console.log(`[dry-run] Would remove orphaned generated file: ${orphan}`)
+      }
     }
     for (const f of files) {
       const bytes = Buffer.byteLength(f.code, 'utf-8')
@@ -44,7 +86,10 @@ export async function writeGeneratedFiles(
   }
 
   if (cleanOutDir) {
-    await rm(outDir, { recursive: true, force: true })
+    for (const orphan of await findOrphans(outDir, written)) {
+      await rm(orphan, { force: true })
+      console.log(`[ts-procedures-codegen] Removed orphaned generated file: ${orphan}`)
+    }
   }
   await mkdir(outDir, { recursive: true })
   for (const f of files) {

package/src/codegen/targets/kotlin/__fixtures__/users-golden.kt

@@ -1,5 +1,6 @@
 package com.example.api
 
+// ts-procedures-codegen — do not edit
 // Source hash: <PLACEHOLDER>
 
 import kotlinx.serialization.Contextual

package/src/codegen/targets/kotlin/emit-scope-kotlin.ts

@@ -1,7 +1,7 @@
 import type { ScopeGroup } from '../../group-routes.js'
 import type { KotlinEmitter } from './ajsc-adapter.js'
 import { emitKotlinRoute, type EmitRouteOpts } from './emit-route-kotlin.js'
-import { kotlinPackageDecl, kotlinSourceHashHeader, kotlinImports } from './format-kotlin.js'
+import { kotlinPackageDecl, kotlinSignatureHeader, kotlinSourceHashHeader, kotlinImports } from './format-kotlin.js'
 import { indent } from '../_shared/indent.js'
 import { pickDefined } from '../_shared/pick-defined.js'
 import { pascalCase } from '../_shared/pascal-case.js'
@@ -49,9 +49,10 @@ export function emitKotlinScope(
     : `object ${scopeName} {\n${innerScope}\n}`
 
   const importsBlock = kotlinImports(allImports)
+  const headerBlock = [kotlinSignatureHeader(), kotlinSourceHashHeader(opts.sourceHash)].join('\n')
   const parts = [
     kotlinPackageDecl(opts.kotlinPackage),
-    kotlinSourceHashHeader(opts.sourceHash),
+    headerBlock,
     importsBlock,
     scopeBlock,
   ].filter((p) => p.length > 0)

package/src/codegen/targets/kotlin/format-kotlin.test.ts

@@ -1,15 +1,24 @@
 import { describe, expect, it } from 'vitest'
 import {
   kotlinPackageDecl,
+  kotlinSignatureHeader,
   kotlinSourceHashHeader,
   kotlinImports,
 } from './format-kotlin.js'
+import { CODEGEN_SIGNATURE } from '../../constants.js'
 
 describe('format-kotlin', () => {
   it('emits a package declaration', () => {
     expect(kotlinPackageDecl('com.example.api')).toBe('package com.example.api')
   })
 
+  it('emits a signature header line carrying the package token', () => {
+    const header = kotlinSignatureHeader()
+    expect(header).toBe(`// ${CODEGEN_SIGNATURE} — do not edit`)
+    // The marker-based prune depends on this token being present.
+    expect(header).toContain(CODEGEN_SIGNATURE)
+  })
+
   it('emits a source-hash header line', () => {
     expect(kotlinSourceHashHeader('abc123')).toBe('// Source hash: abc123')
   })

package/src/codegen/targets/kotlin/format-kotlin.ts

@@ -1,7 +1,18 @@
+import { CODEGEN_SIGNATURE } from '../../constants.js'
+
 export function kotlinPackageDecl(pkg: string): string {
   return `package ${pkg}`
 }
 
+/**
+ * Stable signature comment embedded at the top of every generated Kotlin file.
+ * Carries the version-agnostic `ts-procedures-codegen` token so the marker-based
+ * prune in `writeGeneratedFiles` can recognise generated Kotlin files as owned.
+ */
+export function kotlinSignatureHeader(): string {
+  return `// ${CODEGEN_SIGNATURE} — do not edit`
+}
+
 export function kotlinSourceHashHeader(hash: string): string {
   return `// Source hash: ${hash}`
 }

package/src/codegen/targets/swift/format-swift.ts

@@ -1,5 +1,9 @@
+import { CODEGEN_SIGNATURE } from '../../constants.js'
+
 export function swiftHeader(sourceHash: string): string {
-  return `// Generated by ts-procedures-codegen — do not edit.\n// Source hash: ${sourceHash}`
+  // The marker-based prune in `writeGeneratedFiles` relies on CODEGEN_SIGNATURE
+  // appearing in this header.
+  return `// Generated by ${CODEGEN_SIGNATURE} — do not edit.\n// Source hash: ${sourceHash}`
 }
 
 export function swiftImports(imports: string[]): string {