@monoes/monograph 1.1.0 → 1.2.0

package/src/coverage/runtime.ts

@@ -0,0 +1,249 @@
+import type { MonographDb } from '../storage/db.js';
+
+export type RuntimeClassification =
+  | 'SafeToDelete'          // graph-dead AND not covered at runtime
+  | 'ReviewRequired'        // graph-dead BUT has runtime coverage
+  | 'LowTraffic'            // covered but <5% call rate
+  | 'Active'                // actively covered
+  | 'CoverageUnavailable';  // in graph but no coverage data for this file
+
+export interface FunctionCoverageEntry {
+  nodeId: string;
+  name: string;
+  filePath: string | null;
+  startLine: number | null;
+  covered: boolean;
+  callCount: number;
+  classification: RuntimeClassification;
+}
+
+export interface RuntimeCoverageReport {
+  entries: FunctionCoverageEntry[];
+  safeToDelete: number;
+  reviewRequired: number;
+  active: number;
+  coverageUnavailable: number;
+  blastRadius: string[];   // active entry-point file paths (covered + reachable)
+}
+
+// V8 coverage format (subset of what Node/Chrome produces)
+export interface V8CoverageFunction {
+  functionName: string;
+  url: string;          // file URL like 'file:///path/to/file.js'
+  ranges: Array<{ startOffset: number; endOffset: number; count: number }>;
+}
+
+export interface V8Coverage {
+  result: Array<{
+    url: string;
+    functions: V8CoverageFunction[];
+  }>;
+}
+
+interface CoverageMapEntry {
+  covered: boolean;
+  callCount: number;
+}
+
+interface SymbolNodeRow {
+  id: string;
+  name: string;
+  file_path: string | null;
+  start_line: number | null;
+  properties: string | null;
+}
+
+export function analyzeRuntimeCoverage(
+  db: MonographDb,
+  coverage: V8Coverage,
+  repoRoot?: string
+): RuntimeCoverageReport {
+  // Build a map: filePath -> Map<functionName, CoverageMapEntry>
+  const fileCoverageMap = new Map<string, Map<string, CoverageMapEntry>>();
+
+  for (const scriptCov of coverage.result) {
+    let filePath = scriptCov.url;
+
+    // Strip file:// prefix
+    if (filePath.startsWith('file://')) {
+      filePath = filePath.slice('file://'.length);
+    }
+
+    // Resolve relative to repoRoot if provided and path is relative
+    if (repoRoot && !filePath.startsWith('/')) {
+      filePath = repoRoot.replace(/\/$/, '') + '/' + filePath;
+    }
+
+    const fnMap = fileCoverageMap.get(filePath) ?? new Map<string, CoverageMapEntry>();
+
+    for (const fn of scriptCov.functions) {
+      const covered = fn.ranges.some(r => r.count > 0);
+      const callCount = fn.ranges.reduce((max, r) => Math.max(max, r.count), 0);
+      const existing = fnMap.get(fn.functionName);
+      if (!existing || callCount > existing.callCount) {
+        fnMap.set(fn.functionName, { covered, callCount });
+      }
+    }
+
+    fileCoverageMap.set(filePath, fnMap);
+  }
+
+  // Helper: normalize a file path for lookup
+  function normalizeForLookup(fp: string): string {
+    return fp.replace(/\\/g, '/');
+  }
+
+  // Build alternate lookup: basename -> filePath list
+  const filePathIndex = new Map<string, string[]>();
+  for (const fp of fileCoverageMap.keys()) {
+    const norm = normalizeForLookup(fp);
+    filePathIndex.set(norm, (filePathIndex.get(norm) ?? []).concat(fp));
+    // Also store by just the filename for relative matching
+    const parts = norm.split('/');
+    const base = parts[parts.length - 1];
+    if (base && base !== norm) {
+      filePathIndex.set(base, (filePathIndex.get(base) ?? []).concat(fp));
+    }
+  }
+
+  // Compute total call count across all functions for LowTraffic threshold
+  let totalCallCount = 0;
+  for (const fnMap of fileCoverageMap.values()) {
+    for (const entry of fnMap.values()) {
+      totalCallCount += entry.callCount;
+    }
+  }
+  const lowTrafficThreshold = totalCallCount * 0.05;
+
+  // Query all Symbol nodes that are Functions/Methods
+  const rows = db.prepare(`
+    SELECT id, name, file_path, start_line, properties
+    FROM nodes
+    WHERE label IN ('Function', 'Method')
+  `).all() as SymbolNodeRow[];
+
+  const entries: FunctionCoverageEntry[] = [];
+
+  for (const row of rows) {
+    const props = row.properties ? JSON.parse(row.properties) : {};
+    const reachabilityRole: string = props.reachabilityRole ?? '';
+
+    let fnEntry: CoverageMapEntry | null = null;
+
+    if (row.file_path) {
+      const normFilePath = normalizeForLookup(row.file_path);
+
+      // Try exact match first
+      const exactFnMap = fileCoverageMap.get(normFilePath) ?? fileCoverageMap.get(row.file_path);
+      if (exactFnMap) {
+        const match = exactFnMap.get(row.name);
+        if (match) fnEntry = match;
+        // If no exact function name match, aggregate all functions for this file
+        if (!fnEntry) {
+          // Best-effort: file is covered if any function is covered
+          let fileCovered = false;
+          let fileMaxCount = 0;
+          for (const e of exactFnMap.values()) {
+            if (e.covered) fileCovered = true;
+            fileMaxCount = Math.max(fileMaxCount, e.callCount);
+          }
+          if (exactFnMap.size > 0) {
+            fnEntry = { covered: fileCovered, callCount: fileMaxCount };
+          }
+        }
+      } else {
+        // Try relative path matching
+        for (const [covPath, fnMap] of fileCoverageMap.entries()) {
+          if (covPath.endsWith(normFilePath) || normFilePath.endsWith(covPath.replace(/.*\//, ''))) {
+            const match = fnMap.get(row.name);
+            if (match) { fnEntry = match; break; }
+            // Aggregate file-level coverage
+            let fileCovered = false;
+            let fileMaxCount = 0;
+            for (const e of fnMap.values()) {
+              if (e.covered) fileCovered = true;
+              fileMaxCount = Math.max(fileMaxCount, e.callCount);
+            }
+            if (fnMap.size > 0) {
+              fnEntry = { covered: fileCovered, callCount: fileMaxCount };
+              break;
+            }
+          }
+        }
+      }
+    }
+
+    let classification: RuntimeClassification;
+    let covered = false;
+    let callCount = 0;
+
+    if (!fnEntry) {
+      classification = 'CoverageUnavailable';
+    } else {
+      covered = fnEntry.covered;
+      callCount = fnEntry.callCount;
+
+      if (!covered && reachabilityRole === 'unreachable') {
+        classification = 'SafeToDelete';
+      } else if (covered && reachabilityRole === 'unreachable') {
+        classification = 'ReviewRequired';
+      } else if (covered && callCount < lowTrafficThreshold) {
+        classification = 'LowTraffic';
+      } else if (covered) {
+        classification = 'Active';
+      } else {
+        // not covered, not unreachable — treat as unavailable
+        classification = 'CoverageUnavailable';
+      }
+    }
+
+    entries.push({
+      nodeId: row.id,
+      name: row.name,
+      filePath: row.file_path,
+      startLine: row.start_line,
+      covered,
+      callCount,
+      classification,
+    });
+  }
+
+  // Aggregate counts
+  let safeToDelete = 0;
+  let reviewRequired = 0;
+  let active = 0;
+  let coverageUnavailable = 0;
+
+  const blastRadiusSet = new Set<string>();
+
+  for (const entry of entries) {
+    switch (entry.classification) {
+      case 'SafeToDelete': safeToDelete++; break;
+      case 'ReviewRequired': reviewRequired++; break;
+      case 'Active': active++; break;
+      case 'CoverageUnavailable': coverageUnavailable++; break;
+    }
+
+    // BlastRadius: Active nodes with reachabilityRole === 'runtime'
+    if (entry.classification === 'Active' && entry.filePath) {
+      const nodeProps = entries.find(e => e.nodeId === entry.nodeId);
+      // Re-query to get reachabilityRole for blast radius check
+      const nodeRow = db.prepare(`SELECT properties FROM nodes WHERE id = ?`).get(entry.nodeId) as { properties: string | null } | undefined;
+      if (nodeRow) {
+        const p = nodeRow.properties ? JSON.parse(nodeRow.properties) : {};
+        if (p.reachabilityRole === 'runtime') {
+          blastRadiusSet.add(entry.filePath);
+        }
+      }
+    }
+  }
+
+  return {
+    entries,
+    safeToDelete,
+    reviewRequired,
+    active,
+    coverageUnavailable,
+    blastRadius: Array.from(blastRadiusSet),
+  };
+}

package/src/coverage/upload-inventory.ts

@@ -0,0 +1,84 @@
+// Walks source files, extracts function declarations, and uploads a keyed inventory
+// for the "untracked functions" three-state coverage model.
+
+export const INVENTORY_MAX_FUNCTIONS = 200_000;
+
+export interface InventoryFunction {
+  name: string;
+  filePath: string;
+  startLine: number;   // 1-based, Istanbul-compatible
+  endLine: number;
+}
+
+export interface UploadInventoryArgs {
+  projectId: string;
+  root: string;
+  pathPrefix?: string;
+  apiKey?: string;
+  apiBase?: string;
+  failOnDirty?: boolean;
+}
+
+export interface UploadInventoryResult {
+  uploaded: number;
+  skipped: number;
+  warnings: string[];
+}
+
+/** Rebase container WORKDIR path prefix to repo-relative path. */
+export function normalizePathPrefix(raw: string): string {
+  return raw.replace(/\\/g, '/').replace(/\/$/, '');
+}
+
+/** Attempt to derive a project ID slug from a git remote URL. */
+export function parseGitRemoteToProjectId(url: string): string {
+  const match = url.match(/[:/]([^/]+\/[^/]+?)(?:\.git)?$/);
+  return match ? match[1].replace('/', '_') : 'unknown';
+}
+
+/** Extract function inventory from a source text (heuristic, no full AST). */
+export function extractFunctionInventory(source: string, filePath: string): InventoryFunction[] {
+  const results: InventoryFunction[] = [];
+  const lines = source.split('\n');
+  const funcRe = /(?:^|\s)(?:function|async function|const|let|var)\s+([a-zA-Z_$][\w$]*)\s*(?:=\s*(?:async\s*)?\(|[(<])/;
+  const arrowRe = /(?:^|\s)(?:const|let|var)\s+([a-zA-Z_$][\w$]*)\s*=\s*(?:async\s*)?\(/;
+  const methodRe = /^\s*(?:async\s+)?([a-zA-Z_$][\w$]*)\s*\(/;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const m = funcRe.exec(line) ?? arrowRe.exec(line) ?? methodRe.exec(line);
+    if (m && m[1] && !['if', 'while', 'for', 'switch', 'catch'].includes(m[1])) {
+      results.push({ name: m[1], filePath, startLine: i + 1, endLine: i + 1 });
+    }
+  }
+  return results;
+}
+
+/** Upload a function inventory to the cloud API. */
+export async function uploadInventory(
+  args: UploadInventoryArgs,
+  functions: InventoryFunction[],
+): Promise<UploadInventoryResult> {
+  const base = args.apiBase ?? 'https://api.fallow.cloud/v1';
+  const capped = functions.slice(0, INVENTORY_MAX_FUNCTIONS);
+  const warnings: string[] = [];
+  if (functions.length > INVENTORY_MAX_FUNCTIONS) {
+    warnings.push(`Inventory capped at ${INVENTORY_MAX_FUNCTIONS} functions (${functions.length} found)`);
+  }
+
+  const res = await fetch(`${base}/projects/${encodeURIComponent(args.projectId)}/inventory`, {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${args.apiKey ?? ''}`,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({ functions: capped, pathPrefix: args.pathPrefix }),
+  });
+
+  if (!res.ok) {
+    warnings.push(`Upload failed: HTTP ${res.status}`);
+    return { uploaded: 0, skipped: functions.length, warnings };
+  }
+
+  return { uploaded: capped.length, skipped: functions.length - capped.length, warnings };
+}

package/src/coverage/upload-source-maps.ts

@@ -0,0 +1,97 @@
+// Uploads .map source map files to the cloud for bundled runtime coverage remapping.
+
+export interface UploadSourceMapsArgs {
+  projectId: string;
+  sourceDir: string;
+  include?: string[];
+  exclude?: string[];
+  stripPath?: string;
+  concurrency?: number;
+  retries?: number;
+  failFast?: boolean;
+  apiKey?: string;
+  apiBase?: string;
+}
+
+export interface SourceMapFile {
+  originalPath: string;
+  uploadPath: string;
+  sizeBytes: number;
+}
+
+export interface UploadSourceMapsResult {
+  uploaded: number;
+  failed: number;
+  skipped: number;
+  warnings: string[];
+}
+
+/** Strip a path prefix from a file path. */
+export function applyStripPath(filePath: string, strip: string): string {
+  const normalized = filePath.replace(/\\/g, '/');
+  const s = strip.replace(/\\/g, '/').replace(/\/$/, '') + '/';
+  return normalized.startsWith(s) ? normalized.slice(s.length) : normalized;
+}
+
+/** Collect .map files from a directory (shallow heuristic — no actual fs walk in library mode). */
+export function collectSourceMaps(
+  files: string[],
+  include: string[] = ['**/*.map'],
+  exclude: string[] = ['node_modules'],
+  stripPath?: string,
+): SourceMapFile[] {
+  return files
+    .filter(f => f.endsWith('.map'))
+    .filter(f => !exclude.some(e => f.includes(e)))
+    .filter(f => include.length === 0 || include.some(_p => f.endsWith('.map')))
+    .map(f => ({
+      originalPath: f,
+      uploadPath: stripPath ? applyStripPath(f, stripPath) : f,
+      sizeBytes: 0,
+    }));
+}
+
+/** Upload source map files to the cloud API. */
+export async function uploadSourceMaps(
+  args: UploadSourceMapsArgs,
+  files: SourceMapFile[],
+): Promise<UploadSourceMapsResult> {
+  const base = args.apiBase ?? 'https://api.fallow.cloud/v1';
+  const concurrency = args.concurrency ?? 4;
+  let uploaded = 0;
+  let failed = 0;
+  const warnings: string[] = [];
+
+  const chunks: SourceMapFile[][] = [];
+  for (let i = 0; i < files.length; i += concurrency) {
+    chunks.push(files.slice(i, i + concurrency));
+  }
+
+  for (const chunk of chunks) {
+    const results = await Promise.allSettled(chunk.map(async f => {
+      const res = await fetch(
+        `${base}/projects/${encodeURIComponent(args.projectId)}/source-maps`,
+        {
+          method: 'POST',
+          headers: {
+            Authorization: `Bearer ${args.apiKey ?? ''}`,
+            'Content-Type': 'application/json',
+          },
+          body: JSON.stringify({ path: f.uploadPath }),
+        },
+      );
+      if (!res.ok) throw new Error(`HTTP ${res.status} for ${f.uploadPath}`);
+    }));
+    for (const r of results) {
+      if (r.status === 'fulfilled') uploaded++;
+      else {
+        failed++;
+        warnings.push(r.reason instanceof Error ? r.reason.message : String(r.reason));
+        if (args.failFast) break;
+      }
+    }
+    if (args.failFast && failed > 0) break;
+  }
+
+  return { uploaded, failed, skipped: 0, warnings };
+}

package/src/discover/entry-points.ts

@@ -0,0 +1,51 @@
+export type EntryPointCategory = "all" | "runtime" | "test";
+
+export type EntryPointSource =
+  | 'package-json-main'
+  | 'package-json-bin'
+  | 'package-json-exports'
+  | 'tsconfig'
+  | 'workspace'
+  | 'config'
+  | 'manual';
+
+export interface CategorizedEntryPoints {
+  all: string[];
+  runtime: string[];
+  test: string[];
+}
+
+export const OUTPUT_DIRS: string[] = ["dist", "build", "out", "esm", "cjs", ".next", ".nuxt", ".output"];
+
+export function isTestEntryPoint(filePath: string): boolean {
+  return (
+    filePath.includes("/__tests__/") ||
+    filePath.includes(".test.") ||
+    filePath.includes(".spec.") ||
+    filePath.includes("/test/") ||
+    filePath.includes("/tests/")
+  );
+}
+
+export function categorizeEntryPoints(entryPoints: string[]): CategorizedEntryPoints {
+  const result: CategorizedEntryPoints = { all: [], runtime: [], test: [] };
+
+  for (const ep of entryPoints) {
+    result.all.push(ep);
+    if (isTestEntryPoint(ep)) {
+      result.test.push(ep);
+    } else {
+      result.runtime.push(ep);
+    }
+  }
+
+  return result;
+}
+
+export function formatSkippedEntryWarning(filePath: string, reason: string): string {
+  return `Skipped entry point ${filePath}: ${reason}`;
+}
+
+export function deduplicateEntryPoints(entries: string[]): string[] {
+  return [...new Set(entries)];
+}

package/src/discover/infrastructure-entries.ts

@@ -0,0 +1,175 @@
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+export type InfraFileKind =
+  | 'dockerfile'
+  | 'docker-compose'
+  | 'procfile'
+  | 'fly-toml'
+  | 'render-yaml'
+  | 'railway-toml'
+  | 'heroku-procfile';
+
+export interface InfraEntryPoint {
+  filePath: string;
+  kind: InfraFileKind;
+  discoveredEntries: string[];
+}
+
+const JSTS = /\.(js|ts|mjs|cjs)$/;
+
+const STATIC_CANDIDATES: Array<{ filename: string; kind: InfraFileKind }> = [
+  { filename: 'Dockerfile', kind: 'dockerfile' },
+  { filename: 'Procfile', kind: 'heroku-procfile' },
+  { filename: 'fly.toml', kind: 'fly-toml' },
+  { filename: 'render.yaml', kind: 'render-yaml' },
+  { filename: 'railway.toml', kind: 'railway-toml' },
+  { filename: 'docker-compose.yml', kind: 'docker-compose' },
+  { filename: 'docker-compose.yaml', kind: 'docker-compose' },
+];
+
+const COMMON_SUBDIRS = ['app', 'src', 'backend', 'server', 'api', 'services'];
+
+function safeRead(filePath: string): string | null {
+  try {
+    return readFileSync(filePath, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+function safeLs(dir: string): string[] {
+  try {
+    return readdirSync(dir) as string[];
+  } catch {
+    return [];
+  }
+}
+
+function parseByKind(kind: InfraFileKind, content: string): string[] {
+  switch (kind) {
+    case 'dockerfile':
+      return parseDockerfileEntries(content);
+    case 'heroku-procfile':
+    case 'procfile':
+      return parseProcfileEntries(content);
+    case 'docker-compose':
+      return parseDockerComposeEntries(content);
+    case 'fly-toml':
+    case 'render-yaml':
+    case 'railway-toml':
+      return parseTomlYamlCommandEntries(content);
+  }
+}
+
+function parseDockerComposeEntries(content: string): string[] {
+  const entries: string[] = [];
+  for (const line of content.split('\n')) {
+    const t = line.trim();
+    if (!t.startsWith('command:') && !t.startsWith('entrypoint:')) continue;
+    for (const token of t.split(/\s+/)) {
+      if (JSTS.test(token)) entries.push(token);
+    }
+  }
+  return entries;
+}
+
+function parseTomlYamlCommandEntries(content: string): string[] {
+  const entries: string[] = [];
+  for (const line of content.split('\n')) {
+    const t = line.trim();
+    if (!/^(command|entrypoint)\s*[=:]/.test(t)) continue;
+    for (const token of t.split(/\s+/)) {
+      if (JSTS.test(token)) entries.push(token);
+    }
+  }
+  return entries;
+}
+
+function probeDir(dir: string, seen: Set<string>, results: InfraEntryPoint[]): void {
+  for (const { filename, kind } of STATIC_CANDIDATES) {
+    const filePath = join(dir, filename);
+    if (seen.has(filePath) || !existsSync(filePath)) continue;
+    seen.add(filePath);
+    const content = safeRead(filePath);
+    if (content !== null) {
+      results.push({ filePath, kind, discoveredEntries: parseByKind(kind, content) });
+    }
+  }
+
+  for (const entry of safeLs(dir)) {
+    if (entry.startsWith('Dockerfile.') || entry.startsWith('dockerfile.')) {
+      const filePath = join(dir, entry);
+      if (seen.has(filePath)) continue;
+      seen.add(filePath);
+      const content = safeRead(filePath);
+      if (content !== null) {
+        results.push({ filePath, kind: 'dockerfile', discoveredEntries: parseDockerfileEntries(content) });
+      }
+    }
+  }
+}
+
+export function detectInfraFiles(projectRoot: string): InfraEntryPoint[] {
+  const results: InfraEntryPoint[] = [];
+  const seen = new Set<string>();
+
+  probeDir(projectRoot, seen, results);
+  for (const sub of COMMON_SUBDIRS) {
+    probeDir(join(projectRoot, sub), seen, results);
+  }
+
+  return results;
+}
+
+export function parseDockerfileEntries(content: string): string[] {
+  const entries: string[] = [];
+
+  for (const line of content.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith('CMD') && !trimmed.startsWith('ENTRYPOINT')) continue;
+
+    const jsonMatch = trimmed.match(/\[([^\]]+)\]/);
+    if (jsonMatch) {
+      try {
+        const parts = JSON.parse(`[${jsonMatch[1]}]`) as unknown[];
+        for (const part of parts) {
+          if (typeof part === 'string' && JSTS.test(part)) entries.push(part);
+        }
+      } catch {
+        // malformed JSON array — fall through to shell-form parse below
+        const rest = trimmed.replace(/^(CMD|ENTRYPOINT)\s+/, '');
+        for (const token of rest.split(/\s+/)) {
+          if (JSTS.test(token)) entries.push(token);
+        }
+      }
+      continue;
+    }
+
+    const rest = trimmed.replace(/^(CMD|ENTRYPOINT)\s+/, '');
+    for (const token of rest.split(/\s+/)) {
+      if (JSTS.test(token)) entries.push(token);
+    }
+  }
+
+  return entries;
+}
+
+export function parseProcfileEntries(content: string): string[] {
+  const entries: string[] = [];
+
+  for (const line of content.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+
+    const colonIdx = trimmed.indexOf(':');
+    if (colonIdx === -1) continue;
+
+    const command = trimmed.slice(colonIdx + 1).trim();
+    for (const token of command.split(/\s+/)) {
+      if (JSTS.test(token)) entries.push(token);
+    }
+  }
+
+  return entries;
+}

package/src/duplicates/detect/concatenation.ts

@@ -0,0 +1,37 @@
+export interface ConcatenationResult {
+  text: number[];
+  fileOf: number[];
+  fileOffsets: number[];
+}
+
+export function concatenateWithSentinels(
+  fileTokens: Array<{ fileId: number; tokens: number[] }>,
+): ConcatenationResult {
+  const sentinelCount = Math.max(0, fileTokens.length - 1);
+  const totalLen = fileTokens.reduce((s, f) => s + f.tokens.length, 0) + sentinelCount;
+
+  const text: number[] = [];
+  const fileOf: number[] = [];
+  const fileOffsets: number[] = [];
+
+  let sentinel = -1;
+
+  for (let i = 0; i < fileTokens.length; i++) {
+    const { fileId, tokens } = fileTokens[i];
+    fileOffsets.push(text.length);
+
+    for (const r of tokens) {
+      text.push(r);
+      fileOf.push(fileId);
+    }
+
+    if (i + 1 < fileTokens.length) {
+      text.push(sentinel);
+      fileOf.push(-1);
+      sentinel -= 1;
+    }
+  }
+
+  void totalLen;
+  return { text, fileOf, fileOffsets };
+}