rvlib-shipkit 0.22.2 → 0.23.0

package/src/ts/imports.ts

@@ -0,0 +1,255 @@
+// Rewrites local imports for extension-carrying absolute specifiers:
+//  1. converts relative paths (./foo, ../../bar) to the canonical absolute
+//     form: root-relative ('src/...'), or package-name-relative
+//     ('rvlib-x/src/...') when the target lives inside a sub-package
+//  2. adds real file extensions (.ts, .tsx, .d.ts)
+//  3. validates that every resolved path exists on disk
+//
+// Handles single-line + multi-line static imports/exports, side-effect
+// imports, dynamic import(), declare-module augmentations, and the tsc
+// substitutions (.js -> .ts/.tsx/.d.ts, .ts -> .tsx). Leaves alone: comments,
+// string-embedded imports (codegen), asset imports (.css, .png, .json, ...),
+// bundler suffixes (?raw, ?url), template-literal specifiers, packages.
+import { readdirSync, readFileSync, writeFileSync, existsSync, type Dirent } from 'fs'
+import { dirname, extname, isAbsolute, join, relative, resolve } from 'path'
+import { canonicalSpecifier, isSkipped, loadConfig, resolvePackageSpecifier, toPosix, type RvtConfig } from 'rvlib-shipkit/src/ts/config.ts'
+import { templateLineMask } from 'rvlib-shipkit/src/ts/source-mask.ts'
+
+const ASSET_EXTENSIONS = new Set([
+   '.png', '.jpg', '.jpeg', '.gif', '.svg', '.webp', '.ico',
+   '.mp3', '.wav', '.ogg', '.mp4', '.webm',
+   '.css', '.scss', '.less', '.sass',
+   '.html', '.json', '.md', '.txt',
+   '.woff', '.woff2', '.eot', '.ttf',
+   '.graphql', '.gql',
+])
+
+function shouldSkipSpecifier(specifier: string): boolean {
+   if (specifier.includes('?')) return true // ?raw / ?inline / ?url bundler syntax
+   if (specifier.includes('${')) return true // template-literal codegen
+   const ext = extname(specifier).toLowerCase()
+   if (ext !== '' && ASSET_EXTENSIONS.has(ext)) return true
+   return false
+}
+
+// ─── extension resolution (with an exists cache — the walk is hot) ──────────
+const existsCache = new Map<string, boolean>()
+const cachedExists = (p: string): boolean => {
+   let r = existsCache.get(p)
+   if (r == null) {
+      r = existsSync(p)
+      existsCache.set(p, r)
+   }
+   return r
+}
+export const clearExistsCache = (): void => existsCache.clear()
+
+function resolveFileExtension(absPath: string): string | null {
+   if (/\.(d\.ts|tsx?|json)$/.test(absPath) && cachedExists(absPath)) return absPath
+   // tsc substitution: a .ts specifier can point at a .tsx file
+   if (/\.ts$/.test(absPath) && !/\.d\.ts$/.test(absPath)) {
+      const tsx = absPath.replace(/\.ts$/, '.tsx')
+      if (cachedExists(tsx)) return tsx
+   }
+   // .js/.jsx -> .ts/.tsx/.d.ts mapping; a real .js wins over a sibling .d.ts
+   if (/\.jsx?$/.test(absPath)) {
+      const base = absPath.replace(/\.jsx?$/, '')
+      for (const ext of ['.ts', '.tsx']) if (cachedExists(base + ext)) return base + ext
+      if (cachedExists(absPath)) return absPath
+      if (cachedExists(`${base}.d.ts`)) return `${base}.d.ts`
+   }
+   for (const c of [`${absPath}.ts`, `${absPath}.tsx`, `${absPath}.d.ts`, `${absPath}.js`, `${absPath}.jsx`, join(absPath, 'index.ts'), join(absPath, 'index.tsx')]) {
+      if (cachedExists(c)) return c
+   }
+   return null
+}
+
+// ─── line-level rewrite ─────────────────────────────────────────────────────
+export type ImportsResult = {
+   filePath: string
+   changes: { line: number; before: string; after: string }[]
+   errors: { line: number; specifier: string; reason: string }[]
+}
+
+const REL = '\\.\\.?\\/[^\'"]*'
+const relRes = {
+   static: new RegExp(`(?:import|export)\\s+(?:.*?\\s+)?from\\s+(['"])(${REL})\\1`, 'g'),
+   multiline: new RegExp(`}\\s*from\\s+(['"])(${REL})\\1`, 'g'),
+   sideEffect: new RegExp(`^(\\s*import\\s+)(['"])(${REL})\\2`, 'g'),
+   dynamic: new RegExp(`import\\(\\s*(['"])(${REL})\\1\\s*\\)`, 'g'),
+}
+const absRes = (roots: string[]) => {
+   const ABS = `(?:${roots.map((r) => r.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|')})\\/[^'"]*`
+   return {
+      static: new RegExp(`(?:import|export)\\s+(?:.*?\\s+)?from\\s+(['"])(${ABS})\\1`, 'g'),
+      multiline: new RegExp(`}\\s*from\\s+(['"])(${ABS})\\1`, 'g'),
+      sideEffect: new RegExp(`^(\\s*import\\s+)(['"])(${ABS})\\2`, 'g'),
+      dynamic: new RegExp(`import\\(\\s*(['"])(${ABS})\\1\\s*\\)`, 'g'),
+      declareModule: new RegExp(`declare\\s+module\\s+(['"])(${ABS})\\1`, 'g'),
+   }
+}
+
+export function rewriteFile(filePath: string, cfg: RvtConfig, save: boolean): ImportsResult | null {
+   if (cfg.roots.length === 0) throw new Error('rvt: no roots configured — set tsconfig "paths" or package.json "rvt".roots')
+   const content = readFileSync(filePath, 'utf8')
+   const fileDir = dirname(filePath)
+   const lines = content.split('\n')
+   const changes: ImportsResult['changes'] = []
+   const errors: ImportsResult['errors'] = []
+   const seenErrors = new Set<string>()
+   // absolute specifiers to re-validate: repo roots + discovered package names
+   const A = absRes([...cfg.roots, ...cfg.packages.map((p) => p.name)])
+
+   const pushError = (lineNum: number, specifier: string, reason: string): void => {
+      const key = `${lineNum}:${specifier}`
+      if (seenErrors.has(key)) return
+      seenErrors.add(key)
+      errors.push({ line: lineNum, specifier, reason })
+   }
+
+   // resolve a specifier and return its canonical form (or null: leave alone):
+   // package-name specifier when the target lives inside a sub-package,
+   // repo-root path otherwise
+   const resolveNew = (specifier: string, lineNum: number, isRelative: boolean): string | null => {
+      if (shouldSkipSpecifier(specifier)) return null
+      const viaPackage = isRelative ? null : resolvePackageSpecifier(specifier, cfg)
+      const absPath = isRelative ? resolve(fileDir, specifier) : resolve(cfg.root, viaPackage ?? specifier)
+      const resolved = resolveFileExtension(absPath)
+      if (resolved == null) {
+         pushError(lineNum, specifier, 'could not resolve file on disk')
+         return null
+      }
+      const rel = toPosix(relative(cfg.root, resolved))
+      const next = canonicalSpecifier(rel, cfg)
+      if (next === rel && !cfg.roots.some((r) => rel.startsWith(`${r}/`))) {
+         pushError(lineNum, specifier, `resolved outside allowed roots (${cfg.roots.join(', ')}): ${rel}`)
+         return null
+      }
+      return next === specifier ? null : next
+   }
+   const sub = (match: string, quote: string, specifier: string, lineNum: number, isRelative: boolean): string => {
+      const next = resolveNew(specifier, lineNum, isRelative)
+      return next == null ? match : match.replace(`${quote}${specifier}${quote}`, `${quote}${next}${quote}`)
+   }
+
+   let inBlockComment = false
+   // template-literal content is TEXT, not code (a codegen emitting import
+   // lines inside a backtick block must not be scanned or rewritten)
+   const templateMask = templateLineMask(lines)
+   const newLines = lines.map((line, lineIdx) => {
+      const lineNum = lineIdx + 1
+      const trimmed = line.trimStart()
+
+      if (templateMask?.[lineIdx]) return line
+
+      if (inBlockComment) {
+         if (trimmed.includes('*/')) inBlockComment = false
+         return line
+      }
+      if (trimmed.startsWith('/*')) {
+         inBlockComment = !trimmed.includes('*/')
+         return line
+      }
+      // cheap prefilter: line must look import-shaped at all
+      if (!line.includes('from ') && !line.includes('import(') && !line.includes('declare module') && !/^\s*import\s+['"]/.test(line)) return line
+      if (trimmed.startsWith('//')) return line
+      // string-embedded imports (codegen) and template-literal content
+      if (/^\s*(const|let|var|return)\s/.test(line) && /[`'"].*(?:import|export).*from\s/.test(line)) return line
+      if (trimmed.startsWith('`') || trimmed.startsWith("'") || trimmed.startsWith('"')) return line
+
+      let newLine = line
+      newLine = newLine.replace(relRes.static, (m, q, s) => sub(m, q, s, lineNum, true))
+      newLine = newLine.replace(relRes.multiline, (m, q, s) => sub(m, q, s, lineNum, true))
+      newLine = newLine.replace(relRes.sideEffect, (m, prefix, q, s) => {
+         const next = resolveNew(s, lineNum, true)
+         return next == null ? m : `${prefix}${q}${next}${q}`
+      })
+      newLine = newLine.replace(relRes.dynamic, (m, q, s) => sub(m, q, s, lineNum, true))
+      newLine = newLine.replace(A.static, (m, q, s) => sub(m, q, s, lineNum, false))
+      newLine = newLine.replace(A.multiline, (m, q, s) => sub(m, q, s, lineNum, false))
+      newLine = newLine.replace(A.sideEffect, (m, prefix, q, s) => {
+         const next = resolveNew(s, lineNum, false)
+         return next == null ? m : `${prefix}${q}${next}${q}`
+      })
+      newLine = newLine.replace(A.dynamic, (m, q, s) => sub(m, q, s, lineNum, false))
+      newLine = newLine.replace(A.declareModule, (m, q, s) => sub(m, q, s, lineNum, false))
+
+      if (newLine !== line) changes.push({ line: lineNum, before: line.trim(), after: newLine.trim() })
+      return newLine
+   })
+
+   if (changes.length === 0 && errors.length === 0) return null
+   if (save && changes.length > 0) writeFileSync(filePath, newLines.join('\n'), 'utf8')
+   return { filePath, changes, errors }
+}
+
+// ─── walker + CLI ───────────────────────────────────────────────────────────
+function walk(cfg: RvtConfig, dir: string, cb: (filePath: string) => void): void {
+   let entries: Dirent[]
+   try {
+      entries = readdirSync(dir, { withFileTypes: true })
+   } catch {
+      return
+   }
+   for (const entry of entries) {
+      const fullPath = join(dir, entry.name)
+      const rel = toPosix(relative(cfg.root, fullPath))
+      if (entry.isDirectory()) {
+         if (!isSkipped(rel, cfg)) walk(cfg, fullPath, cb)
+      } else if (entry.isFile() && /\.tsx?$/.test(entry.name)) {
+         // .d.ts included: they carry import() type expressions that need rewriting
+         cb(fullPath)
+      }
+   }
+}
+
+/** `files` = files CHANGED; `scanned` = files actually visited (a green run
+ *  over zero files is indistinguishable from a green run over 3000 without
+ *  it); `missingRoots` = configured roots absent on disk */
+export type ImportsRun = { files: number; scanned: number; roots: string[]; missingRoots: string[]; changes: number; errors: { file: string; line: number; specifier: string; reason: string }[] }
+
+export function runImports(opts: { save?: boolean; files?: string[]; cfg?: RvtConfig } = {}): ImportsRun {
+   const cfg = opts.cfg ?? loadConfig()
+   clearExistsCache()
+   const save = opts.save === true
+   const run: ImportsRun = { files: 0, scanned: 0, roots: cfg.roots, missingRoots: [], changes: 0, errors: [] }
+   const process1 = (fp: string): void => {
+      const abs = isAbsolute(fp) ? fp : resolve(cfg.root, fp)
+      run.scanned++
+      const result = rewriteFile(abs, cfg, save)
+      if (result == null) return
+      run.files++
+      run.changes += result.changes.length
+      for (const e of result.errors) run.errors.push({ file: toPosix(relative(cfg.root, abs)), ...e })
+   }
+   if (opts.files != null && opts.files.length > 0) {
+      for (const fp of opts.files) process1(fp)
+   } else {
+      for (const r of cfg.roots) {
+         const abs = join(cfg.root, r)
+         if (existsSync(abs)) walk(cfg, abs, process1)
+         else run.missingRoots.push(r)
+      }
+   }
+   return run
+}
+
+// modes: (none)=preview · --check = CI gate (exit 1 if anything would change)
+// · --fix = rewrite in place · <file...> = fix exactly these files (on-save hook)
+export function importsCli(argv: string[]): number {
+   const flags = argv.filter((a) => a.startsWith('--'))
+   const files = argv.filter((a) => !a.startsWith('--'))
+   const check = flags.includes('--check')
+   const save = !check && (files.length > 0 || flags.includes('--fix') || flags.includes('--save'))
+   const run = runImports({ save, files: files.length > 0 ? files : undefined })
+   const mode = save ? 'fix' : check ? 'check (ci gate)' : 'preview (use --fix to write)'
+   console.log(`imports [${mode}]: ${run.changes} rewrite(s) across ${run.files} file(s), ${run.scanned} scanned, ${run.errors.length} error(s)`)
+   // a gate that scanned nothing is not a passing gate — say so instead of
+   // printing the same green as a full run
+   for (const r of run.missingRoots) console.log(`  WARN configured root '${r}' does not exist — drop it from package.json "rvt".roots or create it`)
+   if (run.scanned === 0)
+      console.log(`  scanned 0 files — roots (${run.roots.join(', ')}) hold no .ts/.tsx; this gate is checking NOTHING${check ? ', which fails the gate' : ''}`)
+   for (const e of run.errors) console.log(`  ${e.file}:${e.line} -> '${e.specifier}' (${e.reason})`)
+   if (check && run.changes > 0) console.log('non-absolute imports found — run `rvt imports --fix` and commit the result.')
+   return run.errors.length > 0 || (check && (run.changes > 0 || run.scanned === 0)) ? 1 : 0
+}

package/src/ts/rename.ts

@@ -0,0 +1,238 @@
+// Rename / move a file or folder AND update every exact occurrence of its
+// repo-relative path across all tracked + untracked source files.
+//
+// Assumes non-relative import paths with explicit extensions, e.g.
+//   import { X } from 'src/foo/bar.ts'
+// so the exact path string is a reliable search key.
+//
+// Modes:
+//   file -> file path            renames the file
+//   file -> existing folder      moves the file into that folder (keeps name)
+//   file -> path ending with /   same, creates folder if missing
+//   folder -> folder path        renames the folder (recursive replacement)
+import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'fs'
+import { basename, dirname, extname, join, relative, resolve } from 'path'
+import { canonicalSpecifier, isSkipped, loadConfig, toPosix, type RvtConfig } from 'rvlib-shipkit/src/ts/config.ts'
+
+const BINARY_EXTS = new Set([
+   '.png', '.jpg', '.jpeg', '.gif', '.webp', '.ico', '.bmp', '.tiff',
+   '.mp3', '.mp4', '.wav', '.webm', '.ogg', '.mov', '.avi',
+   '.pdf', '.zip', '.gz', '.tar', '.7z', '.rar',
+   '.woff', '.woff2', '.ttf', '.otf', '.eot',
+   '.wasm', '.node', '.keystore', '.jks', '.p12', '.pem',
+   '.psd', '.sketch', '.lockb',
+])
+
+/** the nearest ancestor package.json of a repo-relative path, whatever the
+ *  configured roots say. Its `name` plus the path below it IS the specifier a
+ *  sibling module imports. */
+function enclosingPackage(repoRoot: string, relPath: string): { name: string; dir: string } | null {
+   const segs = toPosix(relPath).split('/')
+   for (let i = segs.length - 1; i > 0; i--) {
+      const dir = segs.slice(0, i).join('/')
+      const manifest = join(repoRoot, dir, 'package.json')
+      if (!existsSync(manifest)) continue
+      try {
+         const name = (JSON.parse(readFileSync(manifest, 'utf8')) as { name?: string }).name
+         if (name != null && name !== '') return { name, dir }
+      } catch {
+         // an unparseable manifest is not a package boundary
+      }
+   }
+   return null
+}
+
+export type RenameResult = {
+   srcRel: string
+   dstRel: string
+   isFolder: boolean
+   hits: { file: string; count: number }[]
+   totalRefs: number
+   suspicious: string[]
+   applied: boolean
+}
+
+export function runRename(srcArg: string, dstArg: string, opts: { apply?: boolean; cfg?: RvtConfig } = {}): RenameResult {
+   const cfg = opts.cfg ?? loadConfig()
+   const repoRoot = cfg.root
+
+   const srcAbs = resolve(repoRoot, srcArg)
+   if (!existsSync(srcAbs)) throw new Error(`source does not exist: ${srcAbs}`)
+   const srcIsFolder = statSync(srcAbs).isDirectory()
+
+   let dstAbs = resolve(repoRoot, dstArg)
+   const dstEndsWithSep = /[/\\]$/.test(dstArg)
+   const dstIsExistingFolder = existsSync(dstAbs) && statSync(dstAbs).isDirectory()
+   // file -> folder: move into folder, keep basename
+   if (!srcIsFolder && (dstIsExistingFolder || dstEndsWithSep)) dstAbs = join(dstAbs, basename(srcAbs))
+   if (existsSync(dstAbs)) throw new Error(`destination already exists: ${dstAbs}`)
+
+   const srcRel = toPosix(relative(repoRoot, srcAbs))
+   const dstRel = toPosix(relative(repoRoot, dstAbs))
+   if (srcRel === dstRel) throw new Error('src == dst, nothing to do')
+   if (srcRel.startsWith('..')) throw new Error(`source outside repo: ${srcRel}`)
+   if (dstRel.startsWith('..')) throw new Error(`destination outside repo: ${dstRel}`)
+
+   // both spellings of the path are search keys: the repo-relative form and,
+   // when inside a sub-package, the package-name form imports actually use.
+   // The package is found by walking UP from the file, never by the configured
+   // roots: the content scan is repo-wide, so the specifier derivation must be
+   // too. A repo whose packages live outside `roots` (a docs tree that ships
+   // libs) otherwise renamed the file and rewrote NOTHING, silently.
+   const pairs: { from: string; to: string }[] = [{ from: srcRel, to: dstRel }]
+   const srcCanon = canonicalSpecifier(srcRel, cfg)
+   if (srcCanon !== srcRel) pairs.push({ from: srcCanon, to: canonicalSpecifier(dstRel, cfg) })
+   else {
+      const owner = enclosingPackage(repoRoot, srcRel)
+      if (owner != null && dstRel.startsWith(`${owner.dir}/`))
+         pairs.push({
+            from: `${owner.name}${srcRel.slice(owner.dir.length)}`,
+            to: `${owner.name}${dstRel.slice(owner.dir.length)}`,
+         })
+   }
+
+   const pkgDirs = cfg.packages.map((p) => p.dir)
+   // scan all tracked + untracked (non-ignored) files
+   const ls = Bun.spawnSync(['git', 'ls-files', '-co', '--exclude-standard', '-z'], { cwd: repoRoot })
+   const allFiles = ls.stdout.toString().split('\u0000').filter(Boolean)
+
+   const hits: { file: string; count: number }[] = []
+   let totalRefs = 0
+   for (const file of allFiles) {
+      if (isSkipped(file, cfg, pkgDirs)) continue
+      if (BINARY_EXTS.has(extname(file).toLowerCase())) continue
+      let content: string
+      try {
+         content = readFileSync(join(repoRoot, file), 'utf8')
+      } catch {
+         continue
+      }
+      const nul = content.indexOf('\u0000')
+      if (nul !== -1 && nul < 4096) continue // cheap binary sniff
+      const count = scanPairs(content, pairs).count
+      if (count > 0) {
+         hits.push({ file, count })
+         totalRefs += count
+      }
+   }
+
+   const suspicious = pairs.flatMap((p) => findSuspiciousContexts(repoRoot, p.from, hits))
+   // a file naming the BASENAME without matching any full path form is a
+   // near-miss the rewrite cannot make: a regex-escaped path in a test, a doc
+   // line, a specifier built from parts. Reported, never rewritten, because
+   // guessing at those is how a rename corrupts a repo
+   // the STEM, not the filename: a regex-escaped path writes `foo\.ts`, so the
+   // extension never matches literally
+   const srcBase = basename(srcRel).replace(/\.[^.]+$/, '')
+   if (!srcIsFolder && srcBase.length > 3) {
+      const hitFiles = new Set(hits.map((h) => h.file))
+      const baseRe = new RegExp(`(?<![\\w-])${srcBase.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?![\\w-])`)
+      for (const file of allFiles) {
+         if (hitFiles.has(file) || file === srcRel || isSkipped(file, cfg, pkgDirs)) continue
+         if (BINARY_EXTS.has(extname(file).toLowerCase())) continue
+         let content: string
+         try { content = readFileSync(join(repoRoot, file), 'utf8') } catch { continue }
+         if (baseRe.test(content)) suspicious.push(`${file}: names '${srcBase}' without a rewritable path — check it by hand`)
+      }
+   }
+
+   if (opts.apply === true) {
+      for (const h of hits) {
+         const full = join(repoRoot, h.file)
+         const before = readFileSync(full, 'utf8')
+         const after = scanPairs(before, pairs).text
+         if (after !== before) writeFileSync(full, after)
+      }
+      const dstDir = dirname(dstAbs)
+      if (!existsSync(dstDir)) mkdirSync(dstDir, { recursive: true })
+      const mv = Bun.spawnSync(['git', 'mv', srcAbs, dstAbs], { cwd: repoRoot, stdout: 'pipe', stderr: 'pipe' })
+      if (mv.exitCode !== 0) renameSync(srcAbs, dstAbs) // untracked file: plain fs move
+   }
+
+   return { srcRel, dstRel, isFolder: srcIsFolder, hits, totalRefs, suspicious, applied: opts.apply === true }
+}
+
+export function renameCli(argv: string[]): number {
+   const apply = argv.includes('-x') || argv.includes('--apply')
+   const paths = argv.filter((a) => !a.startsWith('-'))
+   if (paths.length !== 2) {
+      console.log('usage: rvt rename <src> <dst> [-x|--apply]   (dry-run by default)')
+      return 2
+   }
+   let r: RenameResult
+   try {
+      r = runRename(paths[0]!, paths[1]!, { apply })
+   } catch (e) {
+      console.error(String(e instanceof Error ? e.message : e))
+      return 1
+   }
+   console.log(`rename: ${r.srcRel} -> ${r.dstRel}`)
+   console.log(`type:   ${r.isFolder ? 'folder (recursive)' : 'file'}`)
+   console.log(`refs:   ${r.totalRefs} across ${r.hits.length} file(s)`)
+   for (const h of r.hits) console.log(`  ${h.count.toString().padStart(4)}  ${h.file}`)
+   if (r.suspicious.length > 0) {
+      console.log('\nwarning: possible substring overreach (inspect before applying):')
+      for (const s of r.suspicious) console.log(`  ${s}`)
+   }
+   if (!r.applied) console.log('\ndry-run. pass -x or --apply to commit.')
+   else console.log(`\napplied: ${r.srcRel} -> ${r.dstRel} (${r.totalRefs} refs rewritten)`)
+   return 0
+}
+
+// simultaneous multi-needle replace: earliest match wins (longest needle on a
+// tie) and the scan continues PAST the replacement — sequential split/join
+// would let one pair's output feed the next (the package form is a substring
+// of the repo form, so that corrupts content)
+function scanPairs(text: string, pairs: { from: string; to: string }[]): { text: string; count: number } {
+   let out = ''
+   let i = 0
+   let count = 0
+   while (true) {
+      let at = -1
+      let hit: { from: string; to: string } | null = null
+      for (const p of pairs) {
+         if (p.from.length === 0) continue
+         const idx = text.indexOf(p.from, i)
+         if (idx === -1) continue
+         if (at === -1 || idx < at || (idx === at && p.from.length > (hit?.from.length ?? 0))) {
+            at = idx
+            hit = p
+         }
+      }
+      if (hit == null) {
+         out += text.slice(i)
+         return { text: out, count }
+      }
+      out += text.slice(i, at) + hit.to
+      i = at + hit.from.length
+      count++
+   }
+}
+
+// matches where the char right after the needle continues the path
+// (letter, digit, _, -) — likely substring overreach into a sibling name
+function findSuspiciousContexts(repoRoot: string, needle: string, hitList: { file: string }[]): string[] {
+   const bad = /[A-Za-z0-9_-]/
+   const out: string[] = []
+   for (const h of hitList) {
+      let content: string
+      try {
+         content = readFileSync(join(repoRoot, h.file), 'utf8')
+      } catch {
+         continue
+      }
+      let i = 0
+      while (true) {
+         const idx = content.indexOf(needle, i)
+         if (idx === -1) break
+         const after = content[idx + needle.length]
+         if (after != null && bad.test(after)) {
+            const lineStart = content.lastIndexOf('\n', idx) + 1
+            const lineEnd = content.indexOf('\n', idx)
+            out.push(`${h.file}: ${content.slice(lineStart, lineEnd === -1 ? content.length : lineEnd).trim()}`)
+         }
+         i = idx + needle.length
+      }
+   }
+   return out
+}

package/src/ts/source-graph-cli.ts

@@ -0,0 +1,19 @@
+#!/usr/bin/env bun
+// the source-graph verbs, as one small binary the gate spawns: imports,
+// cycles, rename. They live in shipkit rather than in a dependency, because a
+// tool the gate REQUIRES must never be a published version behind the repo it
+// gates (field: `shipkit mv` renamed a file and rewrote zero references,
+// because the copy it resolved predated the fix).
+import { cyclesCli } from 'rvlib-shipkit/src/ts/cycles.ts'
+import { importsCli } from 'rvlib-shipkit/src/ts/imports.ts'
+import { renameCli } from 'rvlib-shipkit/src/ts/rename.ts'
+
+const [verb, ...rest] = process.argv.slice(2)
+const run = (): number => {
+    if (verb === 'imports') return importsCli(rest)
+    if (verb === 'cycles') return cyclesCli(rest)
+    if (verb === 'rename' || verb === 'mv') return renameCli(rest)
+    console.log('usage: imports [--fix] | cycles | rename <src> <dst> [--apply]')
+    return 2
+}
+process.exit(run())

package/src/ts/source-mask.ts

@@ -0,0 +1,26 @@
+// which lines sit inside a multiline template literal — shared by the import
+// rewriter and the cycle scanner so one concern has one handler.
+//
+// the walk is a per-line backtick parity toggle over SANITIZED lines (quoted
+// strings and line comments blanked first). regex literals can still carry a
+// stray backtick and desync the walk, so the result is only trusted when the
+// file ENDS outside a template: valid source cannot end inside one, an
+// in-template EOF means the walk desynced and callers scan unmasked (a loud
+// false positive beats a silent unscanned tail).
+
+/** true per line = the line STARTS inside a multiline template literal.
+ *  null = the parity walk desynced (EOF inside a template), do not mask. */
+export function templateLineMask(lines: string[]): boolean[] | null {
+   let inTemplate = false
+   const mask = lines.map((line) => {
+      const startedIn = inTemplate
+      const sanitized = line
+         .replace(/'(?:\\.|[^'\\])*'/g, "''")
+         .replace(/"(?:\\.|[^"\\])*"/g, '""')
+         .replace(/(^|\s)\/\/.*$/, '$1')
+      const backticks = (sanitized.match(/(?<!\\)`/g) ?? []).length
+      if (backticks % 2 === 1) inTemplate = !inTemplate
+      return startedIn
+   })
+   return inTemplate ? null : mask
+}