rvlib-shipkit 0.22.1 → 0.23.0

package/src/ts/cycles.ts

@@ -0,0 +1,205 @@
+// zero-dep circular import detector. The repo uses absolute repo-root import
+// specifiers ('src/...') with explicit .ts extensions, so resolution is string
+// identity: crawl .ts/.tsx files, regex out the runtime import specifiers
+// (type-only imports don't count), build the graph, tarjan the SCCs, enumerate
+// elementary cycles. Runs on a bare checkout, no install needed.
+import { readdirSync, readFileSync } from 'fs'
+import { dirname, join } from 'path'
+import { isSkipped, loadConfig, resolvePackageSpecifier, toPosix, type RvtConfig } from 'rvlib-shipkit/src/ts/config.ts'
+import { templateLineMask } from 'rvlib-shipkit/src/ts/source-mask.ts'
+
+const CYCLE_CAP = 500 // bail loudly instead of exploding on a pathological graph
+
+function crawl(cfg: RvtConfig, dir: string, out: string[]): void {
+   let entries
+   try {
+      entries = readdirSync(join(cfg.root, dir), { withFileTypes: true })
+   } catch {
+      return
+   }
+   for (const entry of entries) {
+      const rel = `${dir}/${entry.name}`
+      if (entry.isDirectory()) {
+         if (!isSkipped(rel, cfg)) crawl(cfg, rel, out)
+      } else if (/\.tsx?$/.test(entry.name) && !entry.name.endsWith('.d.ts')) {
+         out.push(rel)
+      }
+   }
+}
+
+// strip comments (line comments only when preceded by whitespace, so
+// 'http://...' survives) and type-only import/export statements, then extract
+// the remaining runtime specifiers
+export function extractSpecs(content: string): string[] {
+   // template-literal content is text, a codegen emitting import lines inside
+   // a backtick block is not an import of this module. single-line templates
+   // strip in place, multiline ones blank via the shared mask (null mask =
+   // desynced walk, scan everything rather than eat code between backticks)
+   const rawLines = content.split('\n')
+   const mask = templateLineMask(rawLines)
+   const demasked = mask == null ? content : rawLines.map((l, i) => (mask[i] ? '' : l)).join('\n')
+   const cleaned = demasked
+      .replace(/\/\*[\s\S]*?\*\//g, '')
+      .replace(/(^|\s)\/\/[^\n]*/g, '$1')
+      .replace(/`(?:\\.|[^`\\\n])*`/g, '``')
+      .replace(/\b(?:import|export)\s+type\s[^'"]*?from\s*(['"])[^'"\n]*\1/g, '')
+   const specs: string[] = []
+   // import x from / export { x } from — skipped when every specifier is `type X` (erased at runtime)
+   for (const m of cleaned.matchAll(/\b(?:import|export)\s([^'";]*?)from\s*['"]([^'"\n]+)['"]/g)) {
+      const clause = (m[1] ?? '').trim()
+      if (/^\{[^{}]*\}$/.test(clause)) {
+         const items = clause.slice(1, -1).split(',').map((s) => s.trim()).filter((s) => s !== '')
+         if (items.length > 0 && items.every((s) => /^type\s/.test(s))) continue
+      }
+      if (m[2] != null) specs.push(m[2])
+   }
+   for (const re of [
+      /\bimport\s*['"]([^'"\n]+)['"]/g, // side-effect import
+      /\b(?:import|require)\s*\(\s*['"]([^'"\n]+)['"]\s*\)/g, // dynamic import / require
+   ]) {
+      for (const m of cleaned.matchAll(re)) {
+         if (m[1] != null) specs.push(m[1])
+      }
+   }
+   return specs
+}
+
+function resolveSpec(cfg: RvtConfig, fromFile: string, spec: string, fileSet: Set<string>): string | null {
+   let base: string
+   const viaPackage = resolvePackageSpecifier(spec, cfg)
+   if (spec.startsWith('./') || spec.startsWith('../')) {
+      base = toPosix(join(dirname(fromFile), spec))
+   } else if (viaPackage != null) {
+      base = viaPackage // package-name specifier → the sub-package's dir
+   } else if (cfg.roots.some((r) => spec.startsWith(`${r}/`))) {
+      base = spec
+   } else {
+      return null // third-party
+   }
+   for (const candidate of [base, base.replace(/\.js$/, '.ts'), `${base}.ts`, `${base}.tsx`, `${base}/index.ts`, `${base}/index.tsx`]) {
+      if (fileSet.has(candidate)) return candidate
+   }
+   return null
+}
+
+// tarjan strongly connected components, iterative to survive deep graphs
+function tarjanSCCs(nodes: string[], adj: Map<string, string[]>): string[][] {
+   const index = new Map<string, number>()
+   const low = new Map<string, number>()
+   const onStack = new Set<string>()
+   const stack: string[] = []
+   const sccs: string[][] = []
+   let counter = 0
+   for (const start of nodes) {
+      if (index.has(start)) continue
+      const work: [string, number][] = [[start, 0]]
+      while (work.length > 0) {
+         const frame = work[work.length - 1]!
+         const v = frame[0]
+         if (frame[1] === 0) {
+            index.set(v, counter)
+            low.set(v, counter)
+            counter++
+            stack.push(v)
+            onStack.add(v)
+         }
+         const neighbors = adj.get(v) ?? []
+         let recursed = false
+         while (frame[1] < neighbors.length) {
+            const w = neighbors[frame[1]]!
+            frame[1]++
+            if (!index.has(w)) {
+               work.push([w, 0])
+               recursed = true
+               break
+            } else if (onStack.has(w)) {
+               low.set(v, Math.min(low.get(v)!, index.get(w)!))
+            }
+         }
+         if (recursed) continue
+         if (low.get(v) === index.get(v)) {
+            const scc: string[] = []
+            while (true) {
+               const w = stack.pop()!
+               onStack.delete(w)
+               scc.push(w)
+               if (w === v) break
+            }
+            sccs.push(scc)
+         }
+         work.pop()
+         if (work.length > 0) {
+            const parent = work[work.length - 1]![0]
+            low.set(parent, Math.min(low.get(parent)!, low.get(v)!))
+         }
+      }
+   }
+   return sccs
+}
+
+// elementary cycles inside one SCC: dfs from each node, only through nodes ranked >= start
+function cyclesInSCC(scc: string[], adj: Map<string, string[]>): string[][] {
+   const rank = new Map(scc.map((n, i) => [n, i]))
+   const cycles: string[][] = []
+   for (const start of scc) {
+      const startRank = rank.get(start)!
+      const path: string[] = [start]
+      const onPath = new Set([start])
+      const dfs = (v: string): void => {
+         if (cycles.length >= CYCLE_CAP) return
+         for (const w of adj.get(v) ?? []) {
+            const r = rank.get(w)
+            if (r == null || r < startRank) continue
+            if (w === start) cycles.push([...path])
+            else if (!onPath.has(w)) {
+               path.push(w)
+               onPath.add(w)
+               dfs(w)
+               path.pop()
+               onPath.delete(w)
+            }
+         }
+      }
+      dfs(start)
+   }
+   return cycles
+}
+
+export function findCircularDependencies(cfg: RvtConfig = loadConfig()): string[][] {
+   const files: string[] = []
+   for (const root of cfg.roots) crawl(cfg, root, files)
+   files.sort()
+   const fileSet = new Set(files)
+   const adj = new Map<string, string[]>()
+   for (const file of files) {
+      const targets = new Set<string>()
+      for (const spec of extractSpecs(readFileSync(join(cfg.root, file), 'utf8'))) {
+         const target = resolveSpec(cfg, file, spec, fileSet)
+         if (target != null && target !== file) targets.add(target)
+      }
+      adj.set(file, [...targets].sort())
+   }
+   const cycles: string[][] = []
+   for (const scc of tarjanSCCs(files, adj)) {
+      if (scc.length < 2) continue
+      cycles.push(...cyclesInSCC(scc.sort(), adj))
+   }
+   if (cycles.length >= CYCLE_CAP) {
+      throw new Error(`cycle enumeration hit the cap (${CYCLE_CAP}); graph is pathologically cyclic`)
+   }
+   return cycles
+}
+
+// exit 0 when cycles <= max, 1 otherwise — the arg is a CI ratchet
+export function cyclesCli(argv: string[]): number {
+   const parsed = Number(argv[0] ?? '1')
+   const max = Number.isFinite(parsed) && parsed >= 0 ? parsed : 1 // 0 is a legit ratchet
+   const started = performance.now()
+   const cycles = findCircularDependencies()
+   cycles.forEach((cycle, ix) => {
+      console.log(`Cycle ${ix + 1}:`)
+      cycle.forEach((node, cix) => console.log(`  ${cix + 1}. ${node}`))
+   })
+   console.log(`${cycles.length} cycles found in ${Math.round(performance.now() - started)}ms (max allowed: ${max})`)
+   return cycles.length > max ? 1 : 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
+}