clud-bug 0.6.34 → 0.7.0-rc.1

package/{lib/detect.js → src/core/detect.ts}

@@ -1,7 +1,11 @@
 import { readFile, readdir, stat } from 'node:fs/promises';
 import { join, extname } from 'node:path';
 
-const EXT_TO_LANG = {
+// Lookup tables for the project-shape detectors. Each map is `as const` so
+// downstream consumers can rely on the value types narrowing to the literal
+// strings rather than `string` — `_internal.EXT_TO_LANG['.ts']` resolves to
+// `'typescript'` for IDE navigation, not just `string`.
+export const EXT_TO_LANG = {
   '.ts': 'typescript', '.tsx': 'typescript',
   '.js': 'javascript', '.jsx': 'javascript', '.mjs': 'javascript', '.cjs': 'javascript',
   '.py': 'python',
@@ -14,12 +18,12 @@ const EXT_TO_LANG = {
   '.cs': 'csharp',
   '.c': 'c', '.h': 'c',
   '.cpp': 'cpp', '.cc': 'cpp', '.hpp': 'cpp',
-};
+} as const satisfies Record<string, string>;
 
 // Dependency name → search term hint passed to skills.sh.
 // Only well-known frameworks; obscure packages get filtered out so the
 // skills.sh query doesn't get drowned in noise.
-const DEP_TO_TERM = {
+export const DEP_TO_TERM = {
   'next': 'nextjs', 'react': 'react', 'vue': 'vue', 'svelte': 'svelte',
   '@angular/core': 'angular', 'solid-js': 'solid',
   'express': 'express', 'fastify': 'fastify', 'koa': 'koa', 'hono': 'hono',
@@ -29,16 +33,45 @@ const DEP_TO_TERM = {
   'vitest': 'vitest', 'jest': 'jest', 'playwright': 'playwright',
   '@playwright/test': 'playwright',
   'typescript': 'typescript',
-};
+} as const satisfies Record<string, string>;
 
-const PY_DEP_TO_TERM = {
+export const PY_DEP_TO_TERM = {
   'django': 'django', 'flask': 'flask', 'fastapi': 'fastapi',
   'click': 'click', 'typer': 'typer',
   'pytest': 'pytest', 'sqlalchemy': 'sqlalchemy',
   'pydantic': 'pydantic', 'numpy': 'numpy', 'pandas': 'pandas',
-};
+} as const satisfies Record<string, string>;
 
-async function fileExists(path) {
+// Result of running every detector + post-processing — the data shape callers
+// (bin/clud-bug.js, lib/update.js) read from. `description` is nullable
+// because the README fallback may not produce anything.
+export interface DetectedSignals {
+  name: string | null;
+  description: string | null;
+  languages: string[];
+  histogram: Record<string, number>;
+  searchTerms: string[];
+  primaryLanguage: string | null;
+}
+
+// Per-detector intermediate type — what each manifest-reader returns before
+// we aggregate. `languages` is the languages each manifest implies (e.g.
+// package.json implies ['javascript']) so we can union them in detect().
+interface DetectorResult {
+  name: string | null;
+  description: string | null;
+  languages: string[];
+  terms: string[];
+}
+
+interface PackageJson {
+  name?: string;
+  description?: string;
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+}
+
+async function fileExists(path: string): Promise<boolean> {
   try {
     await stat(path);
     return true;
@@ -47,15 +80,15 @@ async function fileExists(path) {
   }
 }
 
-async function readJsonSafe(path) {
+async function readJsonSafe<T = unknown>(path: string): Promise<T | null> {
   try {
-    return JSON.parse(await readFile(path, 'utf8'));
+    return JSON.parse(await readFile(path, 'utf8')) as T;
   } catch {
     return null;
   }
 }
 
-async function readTextSafe(path) {
+async function readTextSafe(path: string): Promise<string | null> {
   try {
     return await readFile(path, 'utf8');
   } catch {
@@ -63,26 +96,27 @@ async function readTextSafe(path) {
   }
 }
 
-async function detectFromPackageJson(root) {
-  const pkg = await readJsonSafe(join(root, 'package.json'));
+async function detectFromPackageJson(root: string): Promise<DetectorResult | null> {
+  const pkg = await readJsonSafe<PackageJson>(join(root, 'package.json'));
   if (!pkg) return null;
-  const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
-  const terms = new Set();
+  const deps: Record<string, string> = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+  const terms = new Set<string>();
   for (const dep of Object.keys(deps)) {
-    if (DEP_TO_TERM[dep]) terms.add(DEP_TO_TERM[dep]);
+    const term = (DEP_TO_TERM as Record<string, string>)[dep];
+    if (term) terms.add(term);
   }
   return {
-    name: pkg.name,
+    name: pkg.name ?? null,
     description: pkg.description || null,
     languages: ['javascript', ...(deps.typescript || pkg.devDependencies?.typescript ? ['typescript'] : [])],
     terms: [...terms],
   };
 }
 
-async function detectFromPyproject(root) {
+async function detectFromPyproject(root: string): Promise<DetectorResult | null> {
   const text = await readTextSafe(join(root, 'pyproject.toml'));
   if (!text) return null;
-  const terms = new Set();
+  const terms = new Set<string>();
   for (const [dep, term] of Object.entries(PY_DEP_TO_TERM)) {
     // crude but adequate match — full TOML parse would be overkill for the
     // dependency-name lookup we actually need
@@ -91,58 +125,59 @@ async function detectFromPyproject(root) {
   const nameMatch = text.match(/^\s*name\s*=\s*["']([^"']+)["']/m);
   const descMatch = text.match(/^\s*description\s*=\s*["']([^"']+)["']/m);
   return {
-    name: nameMatch?.[1] || null,
-    description: descMatch?.[1] || null,
+    name: nameMatch?.[1] ?? null,
+    description: descMatch?.[1] ?? null,
     languages: ['python'],
     terms: [...terms],
   };
 }
 
-async function detectFromRequirements(root) {
+async function detectFromRequirements(root: string): Promise<DetectorResult | null> {
   const text = await readTextSafe(join(root, 'requirements.txt'));
   if (!text) return null;
-  const terms = new Set();
+  const terms = new Set<string>();
   for (const line of text.split('\n')) {
-    const dep = line.split(/[<>=~ #]/)[0].trim().toLowerCase();
-    if (PY_DEP_TO_TERM[dep]) terms.add(PY_DEP_TO_TERM[dep]);
+    const dep = (line.split(/[<>=~ #]/)[0] ?? '').trim().toLowerCase();
+    const term = (PY_DEP_TO_TERM as Record<string, string>)[dep];
+    if (term) terms.add(term);
   }
   return { name: null, description: null, languages: ['python'], terms: [...terms] };
 }
 
-async function detectFromGoMod(root) {
+async function detectFromGoMod(root: string): Promise<DetectorResult | null> {
   const text = await readTextSafe(join(root, 'go.mod'));
   if (!text) return null;
   const moduleMatch = text.match(/^module\s+(\S+)/m);
   return {
-    name: moduleMatch?.[1]?.split('/').pop() || null,
+    name: moduleMatch?.[1]?.split('/').pop() ?? null,
     description: null,
     languages: ['go'],
     terms: [],
   };
 }
 
-async function detectFromCargo(root) {
+async function detectFromCargo(root: string): Promise<DetectorResult | null> {
   const text = await readTextSafe(join(root, 'Cargo.toml'));
   if (!text) return null;
   const nameMatch = text.match(/^\s*name\s*=\s*["']([^"']+)["']/m);
   const descMatch = text.match(/^\s*description\s*=\s*["']([^"']+)["']/m);
   return {
-    name: nameMatch?.[1] || null,
-    description: descMatch?.[1] || null,
+    name: nameMatch?.[1] ?? null,
+    description: descMatch?.[1] ?? null,
     languages: ['rust'],
     terms: [],
   };
 }
 
-async function detectFromGemfile(root) {
+async function detectFromGemfile(root: string): Promise<DetectorResult | null> {
   const text = await readTextSafe(join(root, 'Gemfile'));
   if (!text) return null;
   return { name: null, description: null, languages: ['ruby'], terms: [] };
 }
 
-async function fileHistogram(root) {
-  const counts = {};
-  async function walk(dir, depth) {
+async function fileHistogram(root: string): Promise<Record<string, number>> {
+  const counts: Record<string, number> = {};
+  async function walk(dir: string, depth: number): Promise<void> {
     if (depth > 3) return;
     let entries;
     try { entries = await readdir(dir, { withFileTypes: true }); } catch { return; }
@@ -154,7 +189,7 @@ async function fileHistogram(root) {
       if (entry.isDirectory()) {
         await walk(full, depth + 1);
       } else {
-        const lang = EXT_TO_LANG[extname(entry.name)];
+        const lang = (EXT_TO_LANG as Record<string, string>)[extname(entry.name)];
         if (lang) counts[lang] = (counts[lang] || 0) + 1;
       }
     }
@@ -163,7 +198,7 @@ async function fileHistogram(root) {
   return counts;
 }
 
-function firstParagraph(readme) {
+function firstParagraph(readme: string | null): string | null {
   if (!readme) return null;
   const lines = readme.split('\n').slice(0, 200);
   const paragraphs = lines.join('\n').split(/\n\s*\n/);
@@ -174,20 +209,22 @@ function firstParagraph(readme) {
   return null;
 }
 
-export async function detect(root) {
+export async function detect(root: string): Promise<DetectedSignals> {
   const detectors = [
     detectFromPackageJson, detectFromPyproject, detectFromRequirements,
     detectFromGoMod, detectFromCargo, detectFromGemfile,
   ];
-  const results = (await Promise.all(detectors.map(d => d(root)))).filter(Boolean);
+  const results = (await Promise.all(detectors.map(d => d(root)))).filter(
+    (r): r is DetectorResult => r !== null,
+  );
   const histogram = await fileHistogram(root);
   const readme = await readTextSafe(join(root, 'README.md'))
     || await readTextSafe(join(root, 'README'));
 
-  const languages = new Set();
-  const terms = new Set();
-  let name = null;
-  let description = null;
+  const languages = new Set<string>();
+  const terms = new Set<string>();
+  let name: string | null = null;
+  let description: string | null = null;
   for (const r of results) {
     for (const lang of r.languages) languages.add(lang);
     for (const term of r.terms) terms.add(term);
@@ -206,12 +243,22 @@ export async function detect(root) {
     languages: sortedLangs,
     histogram,
     searchTerms: [...new Set([...terms, ...sortedLangs.slice(0, 2)])],
-    primaryLanguage: sortedLangs[0] || null,
+    primaryLanguage: sortedLangs[0] ?? null,
   };
 }
 
-export function buildDescriptionLine(signals) {
-  const parts = [];
+// Input shape for buildDescriptionLine — a subset of DetectedSignals. We
+// don't reuse DetectedSignals directly because the callers (templates,
+// LLM-flow tests) often hand-build a subset rather than running detect().
+export interface DescriptionLineSignals {
+  name?: string | null;
+  description?: string | null;
+  primaryLanguage?: string | null;
+  searchTerms?: string[];
+}
+
+export function buildDescriptionLine(signals: DescriptionLineSignals): string {
+  const parts: string[] = [];
   if (signals.name) parts.push(`This project is "${signals.name}".`);
   if (signals.description) {
     // v0.6.25 / issue #89: when signals.description comes from a
@@ -226,7 +273,7 @@ export function buildDescriptionLine(signals) {
     parts.push(/[.!?]$/.test(desc) ? desc : `${desc}.`);
   }
   if (signals.primaryLanguage) {
-    const frameworks = [...new Set(signals.searchTerms)].filter(t =>
+    const frameworks = [...new Set(signals.searchTerms || [])].filter((t) =>
       !['typescript', 'javascript', 'python', 'go', 'rust', 'ruby'].includes(t));
     const frameworkPart = frameworks.length ? ` using ${frameworks.join(', ')}` : '';
     parts.push(`It's primarily ${signals.primaryLanguage}${frameworkPart}.`);
@@ -235,5 +282,11 @@ export function buildDescriptionLine(signals) {
   return parts.join(' ');
 }
 
-// Test seam: allow tests to inject the EXT_TO_LANG and DEP_TO_TERM tables
-export const _internal = { EXT_TO_LANG, DEP_TO_TERM, PY_DEP_TO_TERM, fileHistogram, firstParagraph };
+// Architect's anti-pattern fix (Phase 2): the JS source used a single
+// `export const _internal = { … }` namespace as a test seam. The TS port
+// promotes the table exports (EXT_TO_LANG, DEP_TO_TERM, PY_DEP_TO_TERM)
+// to direct top-level exports, and exposes the two helper functions
+// fileHistogram + firstParagraph as direct named exports too. Tests now
+// import each symbol by name. No `_internal` re-export — that pattern is
+// gone.
+export { fileHistogram, firstParagraph };

package/src/core/index.ts

@@ -0,0 +1,70 @@
+// Public API surface for `clud-bug/core` (consumed via the package's
+// `./core` exports map → `dist/core/index.js`).
+//
+// Each line re-exports one core module's public symbols. Modules are
+// added incrementally as the v0.7.0 TypeScript migration converts each
+// lib/* JS file.
+
+export { reviewPrompt, type ReviewPromptOptions, type ReviewPromptLanguage } from './prompts.js';
+export {
+  REVIEW_SCHEMA,
+  serializedReviewSchema,
+  type ReviewData,
+  type ReviewFinding,
+  type ReviewSummaryCounts,
+  type ReviewStatusHeader,
+  type FindingSeverity,
+  type PerSkillScanItem,
+  type DedicatedSection,
+} from './review-schema.js';
+export { renderReview, SEVERITY_LABEL } from './render-review.js';
+export {
+  detect,
+  buildDescriptionLine,
+  EXT_TO_LANG,
+  DEP_TO_TERM,
+  PY_DEP_TO_TERM,
+  fileHistogram,
+  firstParagraph,
+  type DetectedSignals,
+  type DescriptionLineSignals,
+} from './detect.js';
+export {
+  render,
+  renderFile,
+  pickTemplate,
+  templateLanguage,
+  DEFAULTS,
+  type RenderDefaults,
+  type RenderVars,
+  type TemplateLanguage,
+} from './render.js';
+export {
+  durationToGitSince,
+  renderAuditHeader,
+  type AuditHeaderInput,
+} from './audit.js';
+export {
+  API_BASE,
+  MAX_SKILLS,
+  SkillsClient,
+  normalizeList,
+  rankAndCap,
+  readReviewMode,
+  readAppliesTo,
+  appliesToPr,
+  partitionByReviewMode,
+  extractPerSkillLine,
+  selectReviewHeader,
+  extractFirstReviewHeaderLine,
+  selectReviewBody,
+  extractStatsHeader,
+  isCriticalReviewHeader,
+  classifyPerSkillOutcome,
+  type SkillDescriptor,
+  type RankableSkill,
+  type AppliesToRule,
+  type SkillWithOptionalContent,
+  type PrComment,
+  type ReviewStatsHeader,
+} from './skills.js';

package/{lib/prompts.js → src/core/prompts.ts}

@@ -6,7 +6,20 @@
 // per-section budgets, comment format updates) by editing one function
 // instead of three templates.
 
-const LANGUAGE_HINT_BLOCKS = {
+export type ReviewPromptLanguage = 'generic' | 'ts' | 'py';
+
+export interface ReviewPromptOptions {
+  projectDescription: string;
+  language?: ReviewPromptLanguage;
+}
+
+// Internal input type: caller may pass a malformed object (e.g. missing
+// projectDescription) and we throw at runtime. Use Partial so the type
+// system tracks that all fields could be missing — the explicit `undefined`
+// check below recovers a meaningful error message.
+type ReviewPromptInput = Partial<ReviewPromptOptions>;
+
+const LANGUAGE_HINT_BLOCKS: Record<ReviewPromptLanguage, readonly string[]> = {
   generic: ['- Broken or missing test coverage for new code'],
   ts: [
     '- Broken or missing test coverage for new code',
@@ -33,7 +46,8 @@ const LANGUAGE_HINT_BLOCKS = {
 //   - 'generic' (default): just "test coverage"
 //   - 'ts': test coverage + 4 TypeScript-specific bullets
 //   - 'py': 4 Python-specific bullets (replaces "test coverage")
-export function reviewPrompt({ projectDescription, language = 'generic' } = {}) {
+export function reviewPrompt(options: ReviewPromptInput = {}): string {
+  const { projectDescription, language = 'generic' } = options;
   if (projectDescription === undefined) {
     throw new Error('reviewPrompt: projectDescription is required');
   }

package/{lib/render-review.js → src/core/render-review.ts}

@@ -15,21 +15,52 @@
 // rendered shape is wrong). Centralising the markdown shape here means a
 // future format tweak edits one function rather than the prompt.
 
-const SEVERITY_EMOJI = { critical: '🔴', minor: '🟡', preexisting: '🟣' };
-const SEVERITY_LABEL = {
+import type {
+  DedicatedSection,
+  FindingSeverity,
+  PerSkillScanItem,
+  ReviewData,
+  ReviewFinding,
+  ReviewSummaryCounts,
+} from './review-schema.js';
+
+// Emoji constants: use explicit Unicode escape literals (`\u{HHHHH}`) so
+// every step of the TS→JS toolchain — tsc, vitest's transformer, the
+// publisher's tarball — emits the same byte sequence regardless of
+// editor encoding settings. Per SPEC §6 byte-identical contract:
+//   \u{1F534} = 🔴 (red circle, critical / "important")
+//   \u{1F7E1} = 🟡 (yellow circle, minor / "nit")
+//   \u{1F7E3} = 🟣 (purple circle, pre-existing)
+//   \u{1F41B} = 🐛 (bug, H2 anchor for `## 🐛 Clud Bug review`)
+const SEVERITY_EMOJI: Record<FindingSeverity, string> = {
+  critical: '\u{1F534}',
+  minor: '\u{1F7E1}',
+  preexisting: '\u{1F7E3}',
+};
+const SEVERITY_LABEL: Record<FindingSeverity, string> = {
   critical: 'important',
   minor: 'nit',
   preexisting: 'pre-existing',
 };
+// SEVERITY_LABEL is retained for callers that import the constant table
+// (the JS version exported it implicitly via module scope; keep the
+// export so future renderer extensions can reuse it).
+export { SEVERITY_LABEL };
+
+// Renderer input type — schema-aligned but defensively typed. The renderer
+// is the last line of defense against malformed JSON, so it accepts an
+// "unknown-ish" shape and degrades gracefully rather than throwing on
+// missing fields.
+type RenderReviewInput = Partial<ReviewData> & Record<string, unknown>;
 
 // Render the full summary comment markdown. `data` is the parsed JSON
-// matching the schema (see schema.js). Returns a string suitable for
-// `gh pr comment --body`.
-export function renderReview(data) {
+// matching the schema (see review-schema.ts). Returns a string suitable
+// for `gh pr comment --body`.
+export function renderReview(data: RenderReviewInput | null | undefined): string {
   if (!data || typeof data !== 'object') {
     throw new TypeError('renderReview: data must be an object');
   }
-  const out = [];
+  const out: string[] = [];
   out.push(renderHeader(data));
   out.push('');
   out.push(renderStatusLine(data.summary_counts));
@@ -77,9 +108,9 @@ export function renderReview(data) {
   return out.join('\n').replace(/\n{3,}/g, '\n\n').replace(/\s+$/, '') + '\n';
 }
 
-function renderHeader(data) {
+function renderHeader(data: RenderReviewInput): string {
   const verdict = data.status_header;
-  const base = '## 🐛 Clud Bug review';
+  const base = '## \u{1F41B} Clud Bug review';
   if (verdict === 'critical findings') return `${base} — critical findings`;
   if (verdict === 'clean') return `${base} — clean`;
   // 'bare' (non-strict-mode default) OR an unexpected verdict — render
@@ -87,7 +118,7 @@ function renderHeader(data) {
   return base;
 }
 
-function renderStatusLine(counts) {
+function renderStatusLine(counts: ReviewSummaryCounts | undefined): string {
   const c = sanitizeCounts(counts);
   return `**This round:** ${c.critical} critical · ${c.minor} minor · ${c.resolved_from_prior} resolved from prior · ${c.still_open} still open`;
 }
@@ -95,13 +126,13 @@ function renderStatusLine(counts) {
 // Severity-emoji stats header. Counts pre-existing in 🟣 even though
 // it's not in summary_counts (the prompt counts pre-existing separately
 // in preexisting_findings.length).
-function renderStatsHeader(counts) {
+function renderStatsHeader(counts: ReviewSummaryCounts | undefined): string {
   const c = sanitizeCounts(counts);
-  return `Found: ${c.critical} 🔴 / ${c.minor} 🟡 / ${c.preexisting} 🟣`;
+  return `Found: ${c.critical} \u{1F534} / ${c.minor} \u{1F7E1} / ${c.preexisting} \u{1F7E3}`;
 }
 
-function renderPerSkillScan(scan) {
-  const out = ['### Per-skill scan'];
+function renderPerSkillScan(scan: PerSkillScanItem[] | undefined): string[] {
+  const out: string[] = ['### Per-skill scan'];
   if (!Array.isArray(scan) || scan.length === 0) {
     out.push('- (no skills loaded — review proceeded against the baseline.)');
     return out;
@@ -116,14 +147,14 @@ function renderPerSkillScan(scan) {
   return out;
 }
 
-function renderDedicatedSection(section) {
+function renderDedicatedSection(section: DedicatedSection | undefined): string[] {
   if (!section || typeof section !== 'object') return [];
   const name = String(section.section_name || '').trim();
   const skill = String(section.skill || '').trim();
   const header = skill && name
     ? `### ${name} [${skill}]`
     : `### ${name || skill || 'Dedicated section'}`;
-  const out = [header, ''];
+  const out: string[] = [header, ''];
   if (Array.isArray(section.findings) && section.findings.length > 0) {
     // Dedicated-section findings use the same emoji-prefix block.
     // Default severity for dedicated sections is "critical" — they're
@@ -135,9 +166,10 @@ function renderDedicatedSection(section) {
   return out;
 }
 
-function renderFindings(findings, severity) {
-  const emoji = SEVERITY_EMOJI[severity] || '🔴';
-  const out = [];
+function renderFindings(findings: ReviewFinding[] | undefined, severity: FindingSeverity): string[] {
+  const emoji = SEVERITY_EMOJI[severity] || SEVERITY_EMOJI.critical;
+  const out: string[] = [];
+  if (!Array.isArray(findings)) return out;
   for (const f of findings) {
     if (!f || typeof f !== 'object') continue;
     const skill = String(f.skill || '').trim();
@@ -163,7 +195,7 @@ function renderFindings(findings, severity) {
   return out;
 }
 
-function renderSkillsReferenced(skills) {
+function renderSkillsReferenced(skills: string[] | undefined): string {
   if (!Array.isArray(skills) || skills.length === 0) {
     return 'Skills referenced: [none] — no installed skill applied to this diff.';
   }
@@ -172,12 +204,12 @@ function renderSkillsReferenced(skills) {
 
 // --- helpers ---
 
-function nonEmpty(arr) {
+function nonEmpty<T>(arr: T[] | undefined): arr is T[] {
   return Array.isArray(arr) && arr.length > 0;
 }
 
-function sanitizeCounts(counts) {
-  const c = counts && typeof counts === 'object' ? counts : {};
+function sanitizeCounts(counts: ReviewSummaryCounts | undefined): ReviewSummaryCounts {
+  const c = counts && typeof counts === 'object' ? counts : ({} as Partial<ReviewSummaryCounts>);
   return {
     critical: numOrZero(c.critical),
     minor: numOrZero(c.minor),
@@ -187,18 +219,18 @@ function sanitizeCounts(counts) {
   };
 }
 
-function numOrZero(v) {
+function numOrZero(v: unknown): number {
   const n = Number(v);
   return Number.isFinite(n) && n >= 0 ? Math.floor(n) : 0;
 }
 
-function locationAnchor(f) {
+function locationAnchor(f: ReviewFinding): string | null {
   const file = String(f.file || '').trim();
   if (!file) return null;
   const line = Number(f.line);
   return Number.isFinite(line) && line > 0 ? `${file}:${line}` : file;
 }
 
-function stripTrailingPunctuation(s) {
+function stripTrailingPunctuation(s: string): string {
   return s.replace(/[.!?]+$/, '');
 }

package/{lib/render.js → src/core/render.ts}

@@ -12,11 +12,28 @@ const PLACEHOLDER_RE = /\{\{([A-Z_]+)\}\}/g;
 // structured output to markdown. Pinning to the version that ran
 // `clud-bug init` guarantees the renderer's output shape matches the
 // prompt's expectations.
+//
+// IMPORTANT (v0.7.0 TS migration): the JS source lived at lib/render.js,
+// so `join(__dirname, '..', 'package.json')` reached the package root
+// from one level up. The TS port compiles to dist/core/render.js, which
+// is TWO levels deep (dist/core/) — so we walk up TWO levels to find
+// package.json. Without this adjustment, module-load would throw at
+// runtime with "ENOENT dist/package.json". Verify on rebuild via:
+//   node -e "import('./dist/core/render.js').then(m => console.log(m.DEFAULTS.CLUD_BUG_VERSION))"
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const PKG_VERSION = JSON.parse(
-  readFileSync(join(__dirname, '..', 'package.json'), 'utf8'),
+const PKG_VERSION: string = (
+  JSON.parse(readFileSync(join(__dirname, '..', '..', 'package.json'), 'utf8')) as { version: string }
 ).version;
 
+// Public shape of the DEFAULTS map. Tests assert presence of CCA_VERSION
+// and CLUD_BUG_VERSION; REVIEW_SCHEMA is the serialized schema string the
+// templates inject via the {{REVIEW_SCHEMA}} placeholder.
+export interface RenderDefaults {
+  CCA_VERSION: string;
+  CLUD_BUG_VERSION: string;
+  REVIEW_SCHEMA: string;
+}
+
 // Default values for substitution tokens that every template uses.
 // Callers can override per-render by passing the same key in `vars`.
 //
@@ -26,19 +43,26 @@ const PKG_VERSION = JSON.parse(
 // workflows mid-cycle. Bumping the pin requires a clud-bug release, which
 // makes the upgrade visible + lets users opt out by pinning a different
 // version in their own forked workflow.
-export const DEFAULTS = {
+export const DEFAULTS: RenderDefaults = {
   CCA_VERSION: 'v1.0.133',
   CLUD_BUG_VERSION: PKG_VERSION,
   REVIEW_SCHEMA: serializedReviewSchema(),
 };
 
+// Caller-supplied substitution vars: any extra placeholders the template
+// uses (REVIEW_PROMPT, PROJECT_DESCRIPTION, etc.). Values may be strings,
+// numbers, or anything String()-coercible. We accept a wider unknown type
+// because the JS callers freely pass numbers, arrays, etc., and the
+// String(value) coercion below handles them uniformly.
+export type RenderVars = Partial<RenderDefaults> & Record<string, unknown>;
+
 // Multi-line value substitution preserves YAML/Markdown indentation by
 // applying the placeholder line's leading whitespace to every
 // continuation line. Single-line values pass through unchanged so
 // existing tokens (CCA_VERSION, PROJECT_DESCRIPTION) keep current behavior.
-export function render(template, vars) {
-  const merged = { ...DEFAULTS, ...vars };
-  return template.replace(PLACEHOLDER_RE, (match, key, offset) => {
+export function render(template: string, vars: RenderVars): string {
+  const merged: Record<string, unknown> = { ...DEFAULTS, ...vars };
+  return template.replace(PLACEHOLDER_RE, (_match, key: string, offset: number) => {
     if (!(key in merged)) {
       throw new Error(`Missing template variable: ${key}`);
     }
@@ -48,7 +72,7 @@ export function render(template, vars) {
     }
     const lineStart = template.lastIndexOf('\n', offset - 1) + 1;
     const leadingWhitespaceMatch = template.slice(lineStart, offset).match(/^(\s*)/);
-    const indent = leadingWhitespaceMatch ? leadingWhitespaceMatch[1] : '';
+    const indent = leadingWhitespaceMatch ? (leadingWhitespaceMatch[1] ?? '') : '';
     return value
       .split('\n')
       .map((line, i) => (i === 0 || line === '' ? line : indent + line))
@@ -56,12 +80,12 @@ export function render(template, vars) {
   });
 }
 
-export async function renderFile(path, vars) {
+export async function renderFile(path: string, vars: RenderVars): Promise<string> {
   const tmpl = await readFile(path, 'utf8');
   return render(tmpl, vars);
 }
 
-export function pickTemplate(languages) {
+export function pickTemplate(languages: string[]): string {
   if (languages.includes('typescript') || languages.includes('javascript')) {
     return 'workflow-ts.yml.tmpl';
   }
@@ -74,7 +98,9 @@ export function pickTemplate(languages) {
 // Map a pickTemplate() filename to the language key that `reviewPrompt`
 // accepts. Keeps the mapping in one place so callers don't repeat the
 // switch when computing the REVIEW_PROMPT token.
-export function templateLanguage(tmplName) {
+export type TemplateLanguage = 'ts' | 'py' | 'generic';
+
+export function templateLanguage(tmplName: string): TemplateLanguage {
   if (tmplName === 'workflow-ts.yml.tmpl') return 'ts';
   if (tmplName === 'workflow-py.yml.tmpl') return 'py';
   return 'generic';