@monoes/monograph 1.1.0 → 1.2.0

package/src/analysis/dependency-health.ts

@@ -0,0 +1,121 @@
+/**
+ * Dependency health scoring.
+ *
+ * Produces a composite [0, 1] score by combining four sub-metrics:
+ *
+ *  1. Cycle penalty   — fraction of nodes involved in cycles (lower = worse)
+ *  2. Dead-code ratio — fraction of nodes that are unreachable / unused
+ *  3. Fan-out skew    — coefficient of variation of out-degrees (high skew = god nodes)
+ *  4. God-node concentration — max in-degree / total edges (hub dominance)
+ *
+ * Final score = 1 − weighted average of penalties.
+ * All individual penalty components are clamped to [0, 1].
+ */
+
+export interface DependencyHealthEdge {
+  sourceId: string;
+  targetId: string;
+}
+
+export interface DependencyHealthInput {
+  /** All node IDs in the graph. */
+  nodes: string[];
+  /** All directed edges. */
+  edges: DependencyHealthEdge[];
+  /** Pre-computed number of cycles (e.g., from detectCycles). */
+  cycleCount: number;
+  /** Pre-computed count of dead nodes (e.g., from detectDeadCode). */
+  deadNodeCount: number;
+}
+
+export interface DependencyHealthDetails {
+  /** Fraction of nodes involved in cycles in [0, 1]. */
+  cyclePenalty: number;
+  /** Fraction of dead nodes in [0, 1]. */
+  deadCodeRatio: number;
+  /** Coefficient of variation for out-degree distribution (normalised to [0,1]). */
+  fanSkew: number;
+  /** Max in-degree / total edge count — hub dominance in [0, 1]. */
+  godNodeConcentration: number;
+}
+
+export interface DependencyHealthResult {
+  /** Composite health score in [0, 1] where 1 is perfectly healthy. */
+  score: number;
+  details: DependencyHealthDetails;
+}
+
+function stdDev(values: number[]): number {
+  if (values.length === 0) return 0;
+  const mean = values.reduce((a, b) => a + b, 0) / values.length;
+  const variance = values.reduce((a, b) => a + (b - mean) ** 2, 0) / values.length;
+  return Math.sqrt(variance);
+}
+
+function clamp(x: number): number {
+  return Math.max(0, Math.min(1, x));
+}
+
+/**
+ * Compute a composite dependency health score for the given graph.
+ */
+export function dependencyHealth(input: DependencyHealthInput): DependencyHealthResult {
+  const { nodes, edges, cycleCount, deadNodeCount } = input;
+  const n = nodes.length;
+  const m = edges.length;
+
+  if (n === 0) {
+    return {
+      score: 1,
+      details: { cyclePenalty: 0, deadCodeRatio: 0, fanSkew: 0, godNodeConcentration: 0 },
+    };
+  }
+
+  // 1. Cycle penalty: cycleCount is the number of nodes in cycles (from topologicalLevelSort)
+  //    Normalised by node count. Capped at 1.
+  const cyclePenalty = clamp(cycleCount / n);
+
+  // 2. Dead-code ratio
+  const deadCodeRatio = clamp(deadNodeCount / n);
+
+  // 3. Fan-out skew: coefficient of variation of out-degrees, normalised
+  const outDegree = new Map<string, number>(nodes.map(id => [id, 0]));
+  for (const { sourceId } of edges) {
+    outDegree.set(sourceId, (outDegree.get(sourceId) ?? 0) + 1);
+  }
+  const outValues = [...outDegree.values()];
+  const outMean = outValues.reduce((a, b) => a + b, 0) / n;
+  const cv = outMean > 0 ? stdDev(outValues) / outMean : 0;
+  // CV > 2 → very skewed; normalise to [0,1] by clamping at 4
+  const fanSkew = clamp(cv / 4);
+
+  // 4. God-node concentration: max in-degree / total edges
+  const inDegree = new Map<string, number>(nodes.map(id => [id, 0]));
+  for (const { targetId } of edges) {
+    inDegree.set(targetId, (inDegree.get(targetId) ?? 0) + 1);
+  }
+  // Use reduce instead of spread to avoid RangeError on graphs with 65k+ nodes
+  const maxInDeg = inDegree.size > 0
+    ? [...inDegree.values()].reduce((a, b) => Math.max(a, b), 0)
+    : 0;
+  const godNodeConcentration = m > 0 ? clamp(maxInDeg / m) : 0;
+
+  // Weighted composite penalty (weights sum to 1)
+  const W_CYCLE = 0.35;
+  const W_DEAD = 0.25;
+  const W_FAN = 0.20;
+  const W_GOD = 0.20;
+
+  const penalty =
+    W_CYCLE * cyclePenalty +
+    W_DEAD * deadCodeRatio +
+    W_FAN * fanSkew +
+    W_GOD * godNodeConcentration;
+
+  const score = clamp(1 - penalty);
+
+  return {
+    score,
+    details: { cyclePenalty, deadCodeRatio, fanSkew, godNodeConcentration },
+  };
+}

package/src/analysis/duplicate-exports.ts

@@ -0,0 +1,74 @@
+import type { MonographDb } from '../storage/db.js';
+
+export interface DuplicateExportGroup {
+  exportName: string;
+  locations: Array<{ nodeId: string; filePath: string | null; label: string }>;
+  count: number;
+}
+
+export interface DuplicateExportsResult {
+  groups: DuplicateExportGroup[];
+  totalDuplicates: number;
+  affectedFiles: number;
+}
+
+interface ExportedRow {
+  id: string;
+  name: string;
+  file_path: string | null;
+  label: string;
+}
+
+/** Generic names that are too common to be meaningful duplicates. */
+const GENERIC_NAMES = new Set(['default', 'index', 'module']);
+
+export function detectDuplicateExports(db: MonographDb): DuplicateExportsResult {
+  const rows = db.prepare(
+    `SELECT id, name, file_path, label
+     FROM nodes
+     WHERE is_exported = 1
+       AND label IN ('Function','Class','Method','Interface','Const','TypeAlias','Enum','Variable')`
+  ).all() as ExportedRow[];
+
+  // Group by normalized name
+  const groups = new Map<string, Array<{ nodeId: string; filePath: string | null; label: string }>>();
+
+  for (const row of rows) {
+    const normalized = row.name.toLowerCase().trim();
+    if (GENERIC_NAMES.has(normalized)) continue;
+
+    let list = groups.get(normalized);
+    if (!list) {
+      list = [];
+      groups.set(normalized, list);
+    }
+    list.push({ nodeId: row.id, filePath: row.file_path, label: row.label });
+  }
+
+  // Filter to duplicates only (count > 1)
+  const duplicateGroups: DuplicateExportGroup[] = [];
+  const affectedFileSet = new Set<string>();
+
+  for (const [name, locations] of groups) {
+    if (locations.length <= 1) continue;
+
+    duplicateGroups.push({
+      exportName: name,
+      locations,
+      count: locations.length,
+    });
+
+    for (const loc of locations) {
+      if (loc.filePath) affectedFileSet.add(loc.filePath);
+    }
+  }
+
+  // Sort by count descending
+  duplicateGroups.sort((a, b) => b.count - a.count);
+
+  return {
+    groups: duplicateGroups,
+    totalDuplicates: duplicateGroups.length,
+    affectedFiles: affectedFileSet.size,
+  };
+}

package/src/analysis/fallow-suppression.ts

@@ -0,0 +1,98 @@
+export type FallowIssueKind =
+  | 'unused-file'
+  | 'unused-export'
+  | 'unused-type'
+  | 'private-type-leak'
+  | 'unused-dependency'
+  | 'unused-dev-dependency'
+  | 'unused-enum-member'
+  | 'unused-class-member'
+  | 'unresolved-import'
+  | 'unlisted-dependency'
+  | 'duplicate-export'
+  | 'code-duplication'
+  | 'circular-dependency'
+  | 'type-only-dependency'
+  | 'test-only-dependency'
+  | 'boundary-violation'
+  | 'coverage-gaps'
+  | 'feature-flag'
+  | 'complexity'
+  | 'stale-suppression';
+
+export interface FallowSuppression {
+  line: number;
+  commentLine: number;
+  kind: FallowIssueKind | null;
+}
+
+const DISCRIMINANT_MAP: Record<FallowIssueKind, number> = {
+  'unused-file': 1,
+  'unused-export': 2,
+  'unused-type': 3,
+  'private-type-leak': 4,
+  'unused-dependency': 5,
+  'unused-dev-dependency': 6,
+  'unused-enum-member': 7,
+  'unused-class-member': 8,
+  'unresolved-import': 9,
+  'unlisted-dependency': 10,
+  'duplicate-export': 11,
+  'code-duplication': 12,
+  'circular-dependency': 13,
+  'type-only-dependency': 14,
+  'test-only-dependency': 15,
+  'boundary-violation': 16,
+  'coverage-gaps': 17,
+  'feature-flag': 18,
+  'complexity': 19,
+  'stale-suppression': 20,
+};
+
+const DISCRIMINANT_REVERSE: FallowIssueKind[] = [
+  'unused-file',
+  'unused-export',
+  'unused-type',
+  'private-type-leak',
+  'unused-dependency',
+  'unused-dev-dependency',
+  'unused-enum-member',
+  'unused-class-member',
+  'unresolved-import',
+  'unlisted-dependency',
+  'duplicate-export',
+  'code-duplication',
+  'circular-dependency',
+  'type-only-dependency',
+  'test-only-dependency',
+  'boundary-violation',
+  'coverage-gaps',
+  'feature-flag',
+  'complexity',
+  'stale-suppression',
+];
+
+const VALID_KINDS = new Set<string>(Object.keys(DISCRIMINANT_MAP));
+
+export function parseFallowIssueKind(s: string): FallowIssueKind | undefined {
+  if (s === 'circular-dependencies') return 'circular-dependency';
+  if (VALID_KINDS.has(s)) return s as FallowIssueKind;
+  return undefined;
+}
+
+export function issueKindToDiscriminant(kind: FallowIssueKind): number {
+  return DISCRIMINANT_MAP[kind];
+}
+
+export function issueKindFromDiscriminant(d: number): FallowIssueKind | undefined {
+  if (d <= 0 || d > 20) return undefined;
+  return DISCRIMINANT_REVERSE[d - 1];
+}
+
+export function isFallowSuppression(line: number): boolean {
+  return line === 0 || line > 0;
+}
+
+export function isFileWideSuppression(suppression: FallowSuppression): boolean {
+  return suppression.line === 0;
+}

package/src/analysis/feature-flags-config.ts

@@ -0,0 +1,47 @@
+export interface SdkPattern {
+  packageName: string;
+  displayName: string;
+  callPatterns: RegExp[];
+}
+
+export const KNOWN_SDK_PATTERNS: SdkPattern[] = [
+  {
+    packageName: 'launchdarkly-js-client-sdk',
+    displayName: 'LaunchDarkly',
+    callPatterns: [/ldClient\.variation\s*\(/, /\.variation\s*\(/],
+  },
+  {
+    packageName: '@statsig/js-client',
+    displayName: 'Statsig',
+    callPatterns: [/\.checkGate\s*\(/, /\.getExperiment\s*\(/, /Statsig\.checkGate/],
+  },
+  {
+    packageName: 'unleash-client',
+    displayName: 'Unleash',
+    callPatterns: [/\.isEnabled\s*\(/, /unleash\.isEnabled/],
+  },
+  {
+    packageName: '@growthbook/growthbook',
+    displayName: 'GrowthBook',
+    callPatterns: [/\.isOn\s*\(/, /\.evalFeature\s*\(/, /growthbook\.isOn/],
+  },
+  {
+    packageName: 'configcat-js',
+    displayName: 'ConfigCat',
+    callPatterns: [/\.getValueAsync\s*\(/, /configcat\.getValue/],
+  },
+  {
+    packageName: 'flagsmith',
+    displayName: 'Flagsmith',
+    callPatterns: [/flagsmith\.hasFeature\s*\(/, /flagsmith\.getValue\s*\(/],
+  },
+  {
+    packageName: '@splitsoftware/splitio',
+    displayName: 'Split',
+    callPatterns: [/\.getTreatment\s*\(/, /splitClient\.getTreatment/],
+  },
+];
+
+export function detectSdkFromPackageJson(deps: Record<string, string>): SdkPattern[] {
+  return KNOWN_SDK_PATTERNS.filter(sdk => deps[sdk.packageName] !== undefined);
+}

package/src/analysis/feature-flags.ts

@@ -0,0 +1,198 @@
+import { readFileSync, readdirSync, statSync } from 'fs';
+import { join, extname } from 'path';
+
+export type FlagKind = 'EnvironmentVariable' | 'SdkCall' | 'ConfigObject';
+export type FlagConfidence = 'High' | 'Medium' | 'Low';
+
+export interface FeatureFlag {
+  filePath: string;
+  flagName: string;
+  kind: FlagKind;
+  confidence: FlagConfidence;
+  line: number;
+  col: number;
+  sdkName?: string;
+  guardLineStart?: number;
+  guardLineEnd?: number;
+  guardedDeadExports?: string[];
+}
+
+export interface FlagsConfig {
+  sdkPatterns: string[];
+  envPrefixes: string[];
+}
+
+export const DEFAULT_FLAGS_CONFIG: FlagsConfig = {
+  envPrefixes: ['FEATURE_', 'FF_', 'FLAG_', 'ENABLE_', 'DISABLE_', 'AB_', 'EXP_', 'EXPERIMENT_'],
+  sdkPatterns: [
+    'launchdarkly', 'ld-client', '@launchdarkly',
+    'statsig', '@statsig',
+    'unleash', 'unleash-client',
+    'growthbook', '@growthbook',
+    'configcat', 'config-cat',
+    'flagsmith',
+    'split-io', '@splitsoftware',
+  ],
+};
+
+// SDK method patterns that signal flag evaluation
+const SDK_CALL_PATTERNS = [
+  /\.variation\s*\(/,
+  /\.isEnabled\s*\(/,
+  /\.checkGate\s*\(/,
+  /\.getExperiment\s*\(/,
+  /\.isOn\s*\(/,
+  /\.getFeature\s*\(/,
+  /\.getTreatment\s*\(/,
+  /\.evaluate\s*\(/,
+  /featureIsEnabled\s*\(/,
+  /getFlag\s*\(/,
+  /flagEnabled\s*\(/,
+];
+
+const ENV_VAR_RE = /process\.env\.([A-Z][A-Z0-9_]+)/g;
+const CONFIG_OBJECT_RE = /(?:featureFlags?|flags?|features?)\s*[\[.]\s*['"]([A-Za-z][A-Za-z0-9_-]*)['"]|(?:isEnabled|isActive|isOn)\s*\(\s*['"]([A-Za-z][A-Za-z0-9_-]*)['"]/g;
+
+function isSourceFile(filePath: string): boolean {
+  const ext = extname(filePath).toLowerCase();
+  return ['.ts', '.tsx', '.js', '.jsx', '.mts', '.mjs', '.cts', '.cjs'].includes(ext);
+}
+
+function detectFlagsInLine(
+  line: string,
+  lineNum: number,
+  filePath: string,
+  config: FlagsConfig,
+): FeatureFlag[] {
+  const found: FeatureFlag[] = [];
+
+  // Environment variable flags
+  let m: RegExpExecArray | null;
+  const envRe = new RegExp(ENV_VAR_RE.source, 'g');
+  while ((m = envRe.exec(line)) !== null) {
+    const varName = m[1]!;
+    const isFlag = config.envPrefixes.some(p => varName.startsWith(p));
+    if (isFlag) {
+      found.push({
+        filePath, flagName: varName, kind: 'EnvironmentVariable',
+        confidence: 'High', line: lineNum, col: m.index + 1,
+      });
+    }
+  }
+
+  // SDK call patterns
+  for (const pattern of SDK_CALL_PATTERNS) {
+    const sdkMatch = pattern.exec(line);
+    if (sdkMatch) {
+      // Try to extract the flag name from the first string argument
+      const argMatch = line.slice(sdkMatch.index).match(/\(\s*['"]([^'"]+)['"]/);
+      if (argMatch) {
+        found.push({
+          filePath, flagName: argMatch[1]!, kind: 'SdkCall',
+          confidence: 'High', line: lineNum, col: sdkMatch.index + 1,
+          sdkName: detectSdkName(line),
+        });
+      }
+    }
+  }
+
+  // Config object heuristics
+  const configRe = new RegExp(CONFIG_OBJECT_RE.source, 'g');
+  while ((m = configRe.exec(line)) !== null) {
+    const flagName = m[1] ?? m[2];
+    if (flagName) {
+      found.push({
+        filePath, flagName, kind: 'ConfigObject',
+        confidence: 'Medium', line: lineNum, col: m.index + 1,
+      });
+    }
+  }
+
+  return found;
+}
+
+function detectSdkName(line: string): string {
+  const lower = line.toLowerCase();
+  if (lower.includes('launchdarkly') || lower.includes('ldclient')) return 'LaunchDarkly';
+  if (lower.includes('statsig')) return 'Statsig';
+  if (lower.includes('unleash')) return 'Unleash';
+  if (lower.includes('growthbook')) return 'GrowthBook';
+  if (lower.includes('configcat')) return 'ConfigCat';
+  if (lower.includes('flagsmith')) return 'Flagsmith';
+  if (lower.includes('split')) return 'Split';
+  return 'unknown';
+}
+
+export function analyzeFeatureFlags(
+  rootDir: string,
+  config: FlagsConfig = DEFAULT_FLAGS_CONFIG,
+): FeatureFlag[] {
+  const flags: FeatureFlag[] = [];
+  walkDir(rootDir, filePath => {
+    if (!isSourceFile(filePath)) return;
+    let content: string;
+    try { content = readFileSync(filePath, 'utf8'); } catch { return; }
+    const lines = content.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+      const detected = detectFlagsInLine(lines[i]!, i + 1, filePath, config);
+      flags.push(...detected);
+    }
+  });
+  return flags;
+}
+
+export function crossReferenceWithDeadCode(
+  flags: FeatureFlag[],
+  deadExports: Array<{ filePath: string; name: string; line: number }>,
+): FeatureFlag[] {
+  return flags.map(flag => {
+    if (flag.guardLineStart == null || flag.guardLineEnd == null) return flag;
+    const guarded = deadExports
+      .filter(e => e.filePath === flag.filePath &&
+        e.line >= (flag.guardLineStart ?? 0) &&
+        e.line <= (flag.guardLineEnd ?? Infinity))
+      .map(e => e.name);
+    return guarded.length > 0 ? { ...flag, guardedDeadExports: guarded } : flag;
+  });
+}
+
+function walkDir(dir: string, fn: (filePath: string) => void): void {
+  let entries: string[];
+  try { entries = readdirSync(dir); } catch { return; }
+  for (const entry of entries) {
+    if (entry === 'node_modules' || entry === '.git' || entry === 'dist' || entry === 'build') continue;
+    const full = join(dir, entry);
+    let st;
+    try { st = statSync(full); } catch { continue; }
+    if (st.isDirectory()) walkDir(full, fn);
+    else if (st.isFile()) fn(full);
+  }
+}
+
+export interface FlagsSummary {
+  totalFlags: number;
+  byKind: Record<FlagKind, number>;
+  byConfidence: Record<FlagConfidence, number>;
+  uniqueFlagNames: number;
+  filesWithFlags: number;
+  deadCodeOverlaps: number;
+}
+
+export function summarizeFlags(flags: FeatureFlag[]): FlagsSummary {
+  return {
+    totalFlags: flags.length,
+    byKind: {
+      EnvironmentVariable: flags.filter(f => f.kind === 'EnvironmentVariable').length,
+      SdkCall: flags.filter(f => f.kind === 'SdkCall').length,
+      ConfigObject: flags.filter(f => f.kind === 'ConfigObject').length,
+    },
+    byConfidence: {
+      High: flags.filter(f => f.confidence === 'High').length,
+      Medium: flags.filter(f => f.confidence === 'Medium').length,
+      Low: flags.filter(f => f.confidence === 'Low').length,
+    },
+    uniqueFlagNames: new Set(flags.map(f => f.flagName)).size,
+    filesWithFlags: new Set(flags.map(f => f.filePath)).size,
+    deadCodeOverlaps: flags.filter(f => (f.guardedDeadExports?.length ?? 0) > 0).length,
+  };
+}

package/src/analysis/file-classifier.ts

@@ -0,0 +1,84 @@
+import { extname } from 'path';
+
+export type FileType = 'CODE' | 'DOCUMENT' | 'PAPER' | 'IMAGE' | 'VIDEO';
+
+const CODE_EXTENSIONS = new Set([
+  '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs',
+  '.py', '.pyw', '.java', '.kt', '.kts', '.go',
+  '.rs', '.rb', '.php', '.swift', '.cs', '.cpp',
+  '.c', '.h', '.hpp', '.cc', '.m', '.r', '.scala',
+  '.lua', '.sh', '.bash', '.zsh', '.ps1', '.psm1',
+  '.sql', '.graphql', '.gql', '.proto', '.yaml', '.yml',
+  '.toml', '.json', '.xml', '.html', '.css', '.scss',
+  '.sass', '.less', '.vue', '.svelte', '.astro',
+]);
+
+const DOCUMENT_EXTENSIONS = new Set([
+  '.md', '.mdx', '.rst', '.txt', '.pdf', '.docx',
+  '.doc', '.odt', '.rtf', '.tex', '.adoc',
+]);
+
+const IMAGE_EXTENSIONS = new Set([
+  '.png', '.jpg', '.jpeg', '.gif', '.svg', '.webp',
+  '.ico', '.bmp', '.tiff', '.tif',
+]);
+
+const VIDEO_EXTENSIONS = new Set([
+  '.mp4', '.mkv', '.avi', '.mov', '.webm', '.flv',
+  '.wmv', '.m4v',
+]);
+
+const PAPER_URL_PATTERNS = [
+  /arxiv\.org/,
+  /semanticscholar\.org/,
+  /openreview\.net/,
+  /dl\.acm\.org/,
+  /ieeexplore\.ieee\.org/,
+  /springer\.com\/article/,
+];
+
+const PAPER_FILENAME_SIGNALS = [
+  /(^|[^a-zA-Z])(attention|transformer|neural|deep.?learn|bert|gpt|llm|arxiv)([^a-zA-Z]|$)/i,
+  /\d{4}\.\d{4,5}/,
+];
+
+export function classifyFile(pathOrUrl: string): FileType {
+  if (PAPER_URL_PATTERNS.some(p => p.test(pathOrUrl))) return 'PAPER';
+
+  const ext = extname(pathOrUrl).toLowerCase();
+
+  if (IMAGE_EXTENSIONS.has(ext)) return 'IMAGE';
+  if (VIDEO_EXTENSIONS.has(ext)) return 'VIDEO';
+
+  if (DOCUMENT_EXTENSIONS.has(ext)) {
+    if (ext === '.pdf' && PAPER_FILENAME_SIGNALS.some(p => p.test(pathOrUrl))) return 'PAPER';
+    return 'DOCUMENT';
+  }
+
+  if (CODE_EXTENSIONS.has(ext)) return 'CODE';
+
+  return 'CODE';
+}
+
+const PAPER_CONTENT_SIGNALS: RegExp[] = [
+  /\\cite\{/,
+  /\[\d{1,3}\](?:\[\d{1,3}\])+/,
+  /\bEq(?:uation|n)?\.\s*\d+/i,
+  /\bdoi:\s*10\.\d{4,}/i,
+  /^Abstract\b/im,
+  /\bWe propose\b/i,
+  /\bProceedings\s+of\b/i,
+  /\b(Journal|Preprint|arXiv)\b/i,
+  /\d{4}\.\d{4,5}/,
+  /\b\d+\(\d+\):\d+-\d+\b/,
+  /\\bibliography\{/,
+  /\bTable of Contents\b.*\n.*\bIntroduction\b/is,
+];
+
+const PAPER_CONTENT_THRESHOLD = 1;
+
+export function classifyContent(text: string): FileType {
+  const matches = PAPER_CONTENT_SIGNALS.filter(p => p.test(text)).length;
+  if (matches >= PAPER_CONTENT_THRESHOLD) return 'PAPER';
+  return 'DOCUMENT';
+}

package/src/analysis/git-changed-files.ts

@@ -0,0 +1,62 @@
+import { execSync } from 'node:child_process';
+import * as path from 'node:path';
+
+const GIT_REF_ALLOWLIST = /^[a-zA-Z0-9._/~^@{}[\]:-]+$/;
+const DANGEROUS_PATTERNS = /\.\.|`|\$\(|;|&&|\|\|/;
+
+export function validateGitRef(ref: string): void {
+  if (!GIT_REF_ALLOWLIST.test(ref) || DANGEROUS_PATTERNS.test(ref)) {
+    throw new Error(`Invalid git ref: ${JSON.stringify(ref)} — only alphanumeric, dots, slashes, hyphens, and common git ref characters are allowed`);
+  }
+}
+
+export function resolveGitToplevel(cwd: string): string {
+  try {
+    return execSync('git rev-parse --show-toplevel', { cwd, encoding: 'utf8' }).trim();
+  } catch {
+    return cwd;
+  }
+}
+
+export function collectGitPaths(root: string, since?: string): string[] {
+  try {
+    let cmd: string;
+    if (since) {
+      validateGitRef(since);
+      cmd = `git diff --name-only --diff-filter=ACM ${since}`;
+    } else {
+      cmd = 'git ls-files';
+    }
+    const output = execSync(cmd, { cwd: root, encoding: 'utf8' });
+    return output
+      .split('\n')
+      .map(l => l.trim())
+      .filter(l => l.length > 0)
+      .map(l => path.resolve(root, l));
+  } catch {
+    return [];
+  }
+}
+
+export function tryGetChangedFiles(root: string, since?: string): string[] | null {
+  if (!since) return null;
+  try {
+    validateGitRef(since);
+    return collectGitPaths(root, since);
+  } catch {
+    return null;
+  }
+}
+
+export function filterResultsByChangedFiles<T extends { filePath: string }>(
+  results: T[],
+  changedFiles: string[],
+): T[] {
+  const changedSet = new Set(changedFiles.map(f => path.normalize(f)));
+  return results.filter(r => changedSet.has(path.normalize(r.filePath)));
+}
+
+export function getChangedFilesSince(root: string, since: string): string[] {
+  validateGitRef(since);
+  return collectGitPaths(root, since);
+}