ts-procedures 8.1.0 → 8.2.0

package/src/codegen/bundle-size.test.ts

@@ -69,7 +69,7 @@ describe('bundle size budget', () => {
     // This isn't a strict assertion — it surfaces the actual numbers to the
     // test output so reviewers can update PERROUTEDELTA_BASELINE in the
     // comment above without having to re-run locally.
-    // eslint-disable-next-line no-console
+     
     console.log(`[bundle-size] 100 routes, scope file = ${totalChars} chars stripped, per-route = ${perRouteDelta.toFixed(1)}`)
     expect(totalChars).toBeGreaterThan(0)
   })

package/src/codegen/constants.ts

@@ -1 +1,10 @@
-export const CODEGEN_HEADER = '// Auto-generated by ts-procedures-codegen — do not edit'
+import pkg from '../../package.json' with { type: 'json' }
+
+/**
+ * Stable, version-agnostic token embedded in every generated file (across all
+ * targets). The marker-based prune in `writeGeneratedFiles` uses this to tell
+ * generator-owned files apart from hand-written ones — so it must NOT include
+ * the package version (an orphan left by an older release must still match).
+ */
+export const CODEGEN_SIGNATURE = 'ts-procedures-codegen'
+export const CODEGEN_HEADER = `// Auto-generated by ${CODEGEN_SIGNATURE} (v${pkg.version}) — do not edit`

package/src/codegen/e2e.test.ts

@@ -476,7 +476,7 @@ describe('E2E: generateClient full pipeline', () => {
 
     for (const file of ['users.ts', 'events.ts', 'index.ts', '_errors.ts']) {
       const content = readFileSync(join(tmpDir, file), 'utf-8')
-      expect(content).toContain('// Auto-generated by ts-procedures-codegen — do not edit')
+      expect(content).toContain('// Auto-generated by ts-procedures-codegen')
     }
   })
 

package/src/codegen/emit-errors.test.ts

@@ -109,7 +109,7 @@ describe('emitErrorsFile', () => {
 
   it('includes the auto-generated header comment', async () => {
     const result = await emitErrorsFile([procedureErrorDoc])
-    expect(result).toContain('// Auto-generated by ts-procedures-codegen — do not edit')
+    expect(result).toContain('// Auto-generated by ts-procedures-codegen')
   })
 
   it('returns undefined when no errors have schemas', async () => {

package/src/codegen/emit-index.test.ts

@@ -31,7 +31,7 @@ const adminUsersGroup: ScopeGroup = {
 describe('emitIndexFile', () => {
   it('includes the auto-generated header comment', () => {
     const output = emitIndexFile([usersGroup])
-    expect(output).toContain('// Auto-generated by ts-procedures-codegen — do not edit')
+    expect(output).toContain('// Auto-generated by ts-procedures-codegen')
   })
 
   it('imports createClient as a value and client types for the factory', () => {

package/src/codegen/emit-scope.test.ts

@@ -271,7 +271,7 @@ describe('emitScopeFile', () => {
   describe('RPC scope', () => {
     it('includes the auto-generated header comment', async () => {
       const output = await emitScopeFile(rpcGroup)
-      expect(output).toContain('// Auto-generated by ts-procedures-codegen — do not edit')
+      expect(output).toContain('// Auto-generated by ts-procedures-codegen')
     })
 
     it('imports ClientInstance and ProcedureCallOptions but not TypedStream', async () => {

package/src/codegen/pipeline.test.ts

@@ -7,6 +7,7 @@ import { mkdirSync, rmSync, readFileSync, existsSync, writeFileSync } from 'node
 import { join } from 'node:path'
 import { tmpdir } from 'node:os'
 import type { DocEnvelope } from '../implementations/types.js'
+import { CODEGEN_HEADER } from './constants.js'
 
 // ---------------------------------------------------------------------------
 // Fixtures
@@ -140,7 +141,7 @@ describe('generateClient pipeline', () => {
 
     for (const file of ['users.ts', 'billing.ts', 'index.ts']) {
       const content = readFileSync(join(tmpDir, file), 'utf-8')
-      expect(content).toContain('// Auto-generated by ts-procedures-codegen — do not edit')
+      expect(content).toContain('// Auto-generated by ts-procedures-codegen')
     }
   })
 
@@ -172,7 +173,7 @@ describe('generateClient pipeline', () => {
     expect(paths).toContain(join(dryDir, 'billing.ts'))
     expect(paths).toContain(join(dryDir, 'index.ts'))
     for (const file of files) {
-      expect(file.code).toContain('// Auto-generated by ts-procedures-codegen — do not edit')
+      expect(file.code).toContain('// Auto-generated by ts-procedures-codegen')
     }
   })
 
@@ -186,8 +187,8 @@ describe('generateClient pipeline', () => {
     // Verify both files have auto-generated header and source hash
     const typesFile = files.find((f) => f.path.endsWith('_types.ts'))!
     const clientFile = files.find((f) => f.path.endsWith('_client.ts'))!
-    expect(typesFile.code).toContain('// Auto-generated by ts-procedures-codegen — do not edit')
-    expect(clientFile.code).toContain('// Auto-generated by ts-procedures-codegen — do not edit')
+    expect(typesFile.code).toContain('// Auto-generated by ts-procedures-codegen')
+    expect(clientFile.code).toContain('// Auto-generated by ts-procedures-codegen')
     const typesLines = typesFile.code.split('\n')
     expect(typesLines[1]).toMatch(/^\/\/ Source hash: [a-f0-9]{32}$/)
     const clientLines = clientFile.code.split('\n')
@@ -290,30 +291,58 @@ describe('generateClient pipeline', () => {
     expect(content).not.toContain('createScopeBindings')
   })
 
-  it('cleanOutDir: true removes stale files before writing', async () => {
+  it('cleanOutDir: true removes orphaned generated files before writing', async () => {
     tmpDir = makeTmpDir()
-    const stale = join(tmpDir, 'stale.ts')
-    writeFileSync(stale, '// stale', 'utf-8')
-    expect(existsSync(stale)).toBe(true)
+    // A previously-generated scope file (carries the package signature) that
+    // this envelope no longer emits.
+    const orphan = join(tmpDir, 'old-scope.ts')
+    writeFileSync(orphan, `${CODEGEN_HEADER}\n\nexport const gone = 1\n`, 'utf-8')
+    expect(existsSync(orphan)).toBe(true)
 
     await generateClient({ envelope, outDir: tmpDir, cleanOutDir: true })
 
-    expect(existsSync(stale)).toBe(false)
+    expect(existsSync(orphan)).toBe(false)
     expect(existsSync(join(tmpDir, 'index.ts'))).toBe(true)
     expect(existsSync(join(tmpDir, 'users.ts'))).toBe(true)
   })
 
-  it('cleanOutDir: false (default) leaves unrelated files in place', async () => {
+  it('cleanOutDir: true never removes hand-written files lacking the signature', async () => {
     tmpDir = makeTmpDir()
+    const handWritten = join(tmpDir, 'hand-written.ts')
+    writeFileSync(handWritten, 'export const mine = 1\n', 'utf-8')
+
+    await generateClient({ envelope, outDir: tmpDir, cleanOutDir: true })
+
+    expect(existsSync(handWritten)).toBe(true)
+    expect(existsSync(join(tmpDir, 'index.ts'))).toBe(true)
+  })
+
+  it('prunes orphaned generated files by default (cleanOutDir defaults to true)', async () => {
+    tmpDir = makeTmpDir()
+    const orphan = join(tmpDir, 'old-scope.ts')
+    writeFileSync(orphan, `${CODEGEN_HEADER}\n\nexport const gone = 1\n`, 'utf-8')
+    // Hand-written file is still safe even with pruning on by default.
     const keep = join(tmpDir, 'keep.ts')
     writeFileSync(keep, '// keep', 'utf-8')
 
     await generateClient({ envelope, outDir: tmpDir })
 
+    expect(existsSync(orphan)).toBe(false)
     expect(existsSync(keep)).toBe(true)
     expect(existsSync(join(tmpDir, 'index.ts'))).toBe(true)
   })
 
+  it('cleanOutDir: false opts out of pruning, leaving orphaned generated files', async () => {
+    tmpDir = makeTmpDir()
+    const orphan = join(tmpDir, 'old-scope.ts')
+    writeFileSync(orphan, `${CODEGEN_HEADER}\n\nexport const gone = 1\n`, 'utf-8')
+
+    await generateClient({ envelope, outDir: tmpDir, cleanOutDir: false })
+
+    expect(existsSync(orphan)).toBe(true)
+    expect(existsSync(join(tmpDir, 'index.ts'))).toBe(true)
+  })
+
   it('cleanOutDir works when outDir does not exist', async () => {
     tmpDir = makeTmpDir()
     const nested = join(tmpDir, 'nested', 'missing')

package/src/codegen/pipeline.ts

@@ -43,7 +43,7 @@ export type { GeneratedFile } from './targets/_shared/write-files.js'
  * `_shared/write-files.ts`).
  */
 export async function runPipeline(options: PipelineOptions): Promise<GeneratedFile[]> {
-  const { envelope, outDir, ajsc: ajscOpts, dryRun = false, namespaceTypes = false, selfContained = false, cleanOutDir = false } = options
+  const { envelope, outDir, ajsc: ajscOpts, dryRun = false, namespaceTypes = false, selfContained = false, cleanOutDir = true } = options
   const serviceName = options.serviceName ?? 'Api'
   validateServiceName(serviceName)
 

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 {

package/src/codegen/test-helpers/golden.ts

@@ -22,7 +22,7 @@ export async function assertGoldenOrUpdate(produced: string, goldenPath: string)
       '// Source hash: <PLACEHOLDER>',
     )
     await writeFile(goldenPath, goldenContent, 'utf-8')
-    // eslint-disable-next-line no-console
+     
     console.log(`[golden-test] Wrote golden: ${goldenPath}`)
     return
   }

package/src/create-http-stream.ts

@@ -1,8 +1,8 @@
 import { ProcedureError, ProcedureRegistrationError, ProcedureValidationError, ProcedureYieldValidationError } from './errors.js'
 import { computeSchema } from './schema/compute-schema.js'
-import { Prettify, TSchemaLib } from './schema/types.js'
+import type { Prettify, TSchemaLib } from './schema/types.js'
 import { captureDefinitionInfo } from './stack-utils.js'
-import {
+import type {
   HttpMethod, TBuilderConfig, TStreamContext,
   THttpStreamProcedureRegistration, TProcedureRegistration, TStreamProcedureRegistration, THttpProcedureRegistration,
 } from './types.js'

package/src/create-http.ts

@@ -1,9 +1,8 @@
 import { ProcedureError, ProcedureRegistrationError, ProcedureValidationError } from './errors.js'
 import { computeSchema } from './schema/compute-schema.js'
-import { Prettify, TSchemaLib } from './schema/types.js'
+import type { Prettify, TSchemaLib } from './schema/types.js'
 import { captureDefinitionInfo } from './stack-utils.js'
-import {
-  HttpMethod,
+import type {
   TBuilderConfig,
   TCreateHttpConfig,
   TLocalContext,

package/src/create-stream.test.ts

@@ -1,4 +1,4 @@
-/* eslint-disable @typescript-eslint/no-unused-vars */
+ 
 import { describe, expect, it, test } from 'vitest'
 import { Procedures } from './index.js'
 import { v } from 'suretype'

package/src/create-stream.ts

@@ -1,8 +1,8 @@
 import { ProcedureError, ProcedureRegistrationError, ProcedureValidationError, ProcedureYieldValidationError } from './errors.js'
 import { computeSchema } from './schema/compute-schema.js'
-import { Prettify, TSchemaLib } from './schema/types.js'
+import type { Prettify, TSchemaLib } from './schema/types.js'
 import { captureDefinitionInfo } from './stack-utils.js'
-import {
+import type {
   TBuilderConfig,
   THttpProcedureRegistration,
   THttpStreamProcedureRegistration,

package/src/create.test.ts

@@ -1,4 +1,4 @@
-/* eslint-disable @typescript-eslint/no-unused-vars */
+ 
 import { describe, expect, it, test } from 'vitest'
 import { Procedures } from './index.js'
 import { v } from 'suretype'

package/src/create.ts

@@ -1,8 +1,8 @@
 import { ProcedureError, ProcedureRegistrationError, ProcedureValidationError } from './errors.js'
 import { computeSchema } from './schema/compute-schema.js'
-import { Prettify, TSchemaLib } from './schema/types.js'
+import type { Prettify, TSchemaLib } from './schema/types.js'
 import { captureDefinitionInfo } from './stack-utils.js'
-import {
+import type {
   TBuilderConfig,
   THttpProcedureRegistration,
   THttpStreamProcedureRegistration,

package/src/errors.test.ts

@@ -4,7 +4,7 @@ import {
   ProcedureValidationError,
   ProcedureRegistrationError,
 } from './errors.js'
-import { DefinitionInfo } from './stack-utils.js'
+import type { DefinitionInfo } from './stack-utils.js'
 
 describe('Error Classes', () => {
   test('ProcedureError has correct properties', () => {