@monoes/monograph 1.5.6 → 1.5.7

package/src/graph/re-exports/propagate.ts

@@ -1,95 +0,0 @@
-import type { ModuleNode } from '../node-types.js';
-
-export interface Edge {
-  sourceIdx: number;
-  targetIdx: number;
-  importedName?: string;
-  exportedName?: string;
-  isTypeOnly: boolean;
-}
-
-export function propagateStarReExport(
-  modules: ModuleNode[],
-  edges: Edge[],
-  edgesByTarget: Map<number, number[]>,
-  barrelId: number,
-  barrelIdx: number,
-  sourceIdx: number,
-  entryStarTargets: Set<number>,
-): boolean {
-  const barrel = modules[barrelIdx];
-  const source = modules[sourceIdx];
-  const before = barrel.exports.length;
-
-  const existingNames = new Set(barrel.exports.map(e => e.name));
-
-  for (const sym of source.exports) {
-    if (!existingNames.has(sym.name)) {
-      barrel.exports.push({ ...sym, isReExport: true });
-      existingNames.add(sym.name);
-    }
-  }
-
-  const changed = barrel.exports.length > before;
-
-  if (changed && entryStarTargets.has(barrelId)) {
-    const upstreamEdgeIndices = edgesByTarget.get(barrelIdx) ?? [];
-    for (const ei of upstreamEdgeIndices) {
-      const edge = edges[ei];
-      if (edge.importedName === undefined) {
-        propagateStarReExport(
-          modules,
-          edges,
-          edgesByTarget,
-          modules[edge.targetIdx].fileId,
-          edge.targetIdx,
-          barrelIdx,
-          entryStarTargets,
-        );
-      }
-    }
-  }
-
-  return changed;
-}
-
-export function propagateNamedReExport(
-  modules: ModuleNode[],
-  barrelId: number,
-  barrelIdx: number,
-  sourceIdx: number,
-  importedName: string,
-  exportedName: string,
-  existingRefs: Set<number>,
-): boolean {
-  const source = modules[sourceIdx];
-  const barrel = modules[barrelIdx];
-
-  const sourceSym = source.exports.find(e => e.name === importedName);
-  if (!sourceSym) return false;
-
-  const existing = barrel.exports.find(e => e.name === exportedName);
-  if (existing) return false;
-
-  barrel.exports.push({
-    name: exportedName,
-    isType: sourceSym.isType,
-    isReExport: true,
-    line: sourceSym.line,
-  });
-
-  for (const refId of existingRefs) {
-    const refIdx = modules.findIndex(m => m.fileId === refId);
-    if (refIdx !== -1) {
-      const refMod = modules[refIdx];
-      const alreadyRefs = refMod.references.some(
-        r => r.name === exportedName && r.fromFile === barrel.filePath,
-      );
-      if (!alreadyRefs) {
-        refMod.references.push({ name: exportedName, kind: 'Unknown', fromFile: barrel.filePath });
-      }
-    }
-  }
-
-  return true;
-}

package/src/graph/reachability.ts

@@ -1,99 +0,0 @@
-import { ModuleNode, ModuleNodeFlags, setFlag } from './node-types.js';
-
-export interface ReachabilityOptions {
-  runtimeEntries?: Set<number>;
-  testEntries?: Set<number>;
-}
-
-function bfsReachable(
-  nodes: Map<number, ModuleNode>,
-  edges: Map<number, number[]>,
-  entryPoints: number[],
-): Set<number> {
-  const visited = new Set<number>();
-  const queue: number[] = [];
-
-  for (const ep of entryPoints) {
-    if (nodes.has(ep) && !visited.has(ep)) {
-      visited.add(ep);
-      queue.push(ep);
-    }
-  }
-
-  let i = 0;
-  while (i < queue.length) {
-    const current = queue[i++];
-    const neighbors = edges.get(current) ?? [];
-    for (const neighbor of neighbors) {
-      if (!visited.has(neighbor) && nodes.has(neighbor)) {
-        visited.add(neighbor);
-        queue.push(neighbor);
-      }
-    }
-  }
-
-  return visited;
-}
-
-function setsEqual(a: Set<number>, b: Set<number>): boolean {
-  if (a.size !== b.size) return false;
-  for (const v of a) {
-    if (!b.has(v)) return false;
-  }
-  return true;
-}
-
-export function markReachable(
-  nodes: Map<number, ModuleNode>,
-  edges: Map<number, number[]>,
-  entryPoints: number[],
-  opts?: ReachabilityOptions,
-): void {
-  const entrySet = new Set(entryPoints);
-  const visited = bfsReachable(nodes, edges, entryPoints);
-
-  const runtimeEntries = opts?.runtimeEntries;
-  const testEntries = opts?.testEntries;
-
-  const runtimeSame = runtimeEntries === undefined || setsEqual(runtimeEntries, entrySet);
-  const runtimeVisited = runtimeSame
-    ? null
-    : bfsReachable(nodes, edges, [...(runtimeEntries ?? [])]);
-
-  const testVisited =
-    !testEntries || testEntries.size === 0
-      ? null
-      : bfsReachable(nodes, edges, [...testEntries]);
-
-  for (const [id, node] of nodes) {
-    if (visited.has(id)) {
-      setFlag(node, ModuleNodeFlags.REACHABLE);
-    }
-    if (runtimeVisited ? runtimeVisited.has(id) : visited.has(id)) {
-      setFlag(node, ModuleNodeFlags.RUNTIME_REACHABLE);
-    }
-    if (testVisited?.has(id)) {
-      setFlag(node, ModuleNodeFlags.TEST_REACHABLE);
-    }
-  }
-}
-
-export function collectReachable(nodes: Map<number, ModuleNode>): Set<number> {
-  const result = new Set<number>();
-  for (const [id, node] of nodes) {
-    if ((node.flags & ModuleNodeFlags.REACHABLE) !== 0) {
-      result.add(id);
-    }
-  }
-  return result;
-}
-
-export function collectUnreachable(
-  nodes: Map<number, ModuleNode>,
-  allFileIds: number[],
-): number[] {
-  return allFileIds.filter(id => {
-    const node = nodes.get(id);
-    return !node || (node.flags & ModuleNodeFlags.REACHABLE) === 0;
-  });
-}

package/src/graph/regex-search.ts

@@ -1,232 +0,0 @@
-import type { MonographNode, MonographEdge } from '../types.js';
-import type { MonographDb } from '../storage/db.js';
-
-// ── Node regex search ──────────────────────────────────────────────────────────
-
-export interface RegexNodeMatch {
-  node: MonographNode;
-  /** Which field of the node matched. */
-  field: 'name' | 'filePath' | 'language' | 'label';
-}
-
-/**
- * Search nodes whose name, filePath, language, or label matches the given
- * regular expression.
- *
- * @param db      - The MonographDb instance.
- * @param pattern - A RegExp (or a string that will be compiled to one).
- * @param fields  - Which fields to test; default: ['name', 'filePath'].
- */
-export function regexSearchNodes(
-  db: MonographDb,
-  pattern: RegExp | string,
-  fields: Array<'name' | 'filePath' | 'language' | 'label'> = ['name', 'filePath'],
-  limit = 200,
-): RegexNodeMatch[] {
-  const re = typeof pattern === 'string' ? new RegExp(pattern) : pattern;
-
-  // Scan all rows and apply regex filter in JS, then cap at limit.
-  // LIMIT in SQL would silently miss matches beyond the first N rows.
-  const rows = db.prepare(
-    `SELECT id, label, name, norm_label, file_path, start_line, end_line,
-            community_id, is_exported, language, properties
-     FROM nodes`,
-  ).all() as {
-    id: string;
-    label: string;
-    name: string;
-    norm_label: string;
-    file_path: string | null;
-    start_line: number | null;
-    end_line: number | null;
-    community_id: number | null;
-    is_exported: number;
-    language: string | null;
-    properties: string | null;
-  }[];
-
-  const results: RegexNodeMatch[] = [];
-
-  for (const r of rows) {
-    for (const field of fields) {
-      const value =
-        field === 'name' ? r.name :
-        field === 'filePath' ? (r.file_path ?? '') :
-        field === 'language' ? (r.language ?? '') :
-        r.label;
-
-      if (value && re.test(value)) {
-        const node: MonographNode = {
-          id: r.id,
-          label: r.label as MonographNode['label'],
-          name: r.name,
-          normLabel: r.norm_label,
-          filePath: r.file_path ?? undefined,
-          startLine: r.start_line ?? undefined,
-          endLine: r.end_line ?? undefined,
-          communityId: r.community_id ?? undefined,
-          isExported: r.is_exported === 1,
-          language: r.language ?? undefined,
-          properties: r.properties ? (JSON.parse(r.properties) as Record<string, unknown>) : undefined,
-        };
-        results.push({ node, field });
-        break;
-      }
-    }
-    if (results.length >= limit) break;
-  }
-
-  return results;
-}
-
-// ── Edge regex search ──────────────────────────────────────────────────────────
-
-export interface RegexEdgeMatch {
-  edge: MonographEdge;
-  /** Which field of the edge matched. */
-  field: 'relation' | 'confidence' | 'reason';
-}
-
-/**
- * Search edges whose relation, confidence, or reason matches the given
- * regular expression.
- *
- * @param db      - The MonographDb instance.
- * @param pattern - A RegExp (or a string that will be compiled to one).
- * @param fields  - Which fields to test; default: ['relation', 'reason'].
- */
-export function regexSearchEdges(
-  db: MonographDb,
-  pattern: RegExp | string,
-  fields: Array<'relation' | 'confidence' | 'reason'> = ['relation', 'reason'],
-  limit = 200,
-): RegexEdgeMatch[] {
-  const re = typeof pattern === 'string' ? new RegExp(pattern) : pattern;
-
-  const rows = db.prepare(
-    `SELECT id, source_id, target_id, relation, confidence, confidence_score, reason
-     FROM edges`,
-  ).all() as {
-    id: string;
-    source_id: string;
-    target_id: string;
-    relation: string;
-    confidence: string;
-    confidence_score: number;
-    reason: string | null;
-  }[];
-
-  const results: RegexEdgeMatch[] = [];
-
-  for (const r of rows) {
-    const edge: MonographEdge = {
-      id: r.id,
-      sourceId: r.source_id,
-      targetId: r.target_id,
-      relation: r.relation as MonographEdge['relation'],
-      confidence: r.confidence as MonographEdge['confidence'],
-      confidenceScore: r.confidence_score,
-      reason: r.reason ?? undefined,
-    };
-
-    for (const field of fields) {
-      const value =
-        field === 'relation' ? r.relation :
-        field === 'confidence' ? r.confidence :
-        (r.reason ?? '');
-
-      if (value && re.test(value)) {
-        results.push({ edge, field });
-        break;
-      }
-    }
-    if (results.length >= limit) break;
-  }
-
-  return results;
-}
-
-// ── In-memory variants ─────────────────────────────────────────────────────────
-
-export function regexSearchNodesInMemory(
-  nodes: MonographNode[],
-  pattern: RegExp | string,
-  fields: Array<'name' | 'filePath' | 'language' | 'label'> = ['name', 'filePath'],
-): RegexNodeMatch[] {
-  const re = typeof pattern === 'string' ? new RegExp(pattern) : pattern;
-  const results: RegexNodeMatch[] = [];
-
-  for (const node of nodes) {
-    for (const field of fields) {
-      const value =
-        field === 'name' ? node.name :
-        field === 'filePath' ? (node.filePath ?? '') :
-        field === 'language' ? (node.language ?? '') :
-        node.label;
-
-      if (value && re.test(value)) {
-        results.push({ node, field });
-        break;
-      }
-    }
-  }
-
-  return results;
-}
-
-export function regexSearchEdgesInMemory(
-  edges: MonographEdge[],
-  pattern: RegExp | string,
-  fields: Array<'relation' | 'confidence' | 'reason'> = ['relation', 'reason'],
-): RegexEdgeMatch[] {
-  const re = typeof pattern === 'string' ? new RegExp(pattern) : pattern;
-  const results: RegexEdgeMatch[] = [];
-
-  for (const edge of edges) {
-    for (const field of fields) {
-      const value =
-        field === 'relation' ? edge.relation :
-        field === 'confidence' ? edge.confidence :
-        (edge.reason ?? '');
-
-      if (value && re.test(value)) {
-        results.push({ edge, field });
-        break;
-      }
-    }
-  }
-
-  return results;
-}
-
-// ── LLM formatters ─────────────────────────────────────────────────────────────
-
-/**
- * Format node regex match results as structured text for LLM consumption.
- */
-export function formatRegexNodeMatches(matches: RegexNodeMatch[], pattern: string): string {
-  if (matches.length === 0) return `No nodes matching /${pattern}/.`;
-  const lines: string[] = [`${matches.length} node(s) matching /${pattern}/:`];
-  for (const m of matches) {
-    const loc = m.node.filePath
-      ? ` ${m.node.filePath}${m.node.startLine != null ? `:${m.node.startLine}` : ''}`
-      : '';
-    lines.push(`  [${m.field}] ${m.node.label} ${m.node.name}${loc}`);
-  }
-  return lines.join('\n');
-}
-
-/**
- * Format edge regex match results as structured text for LLM consumption.
- */
-export function formatRegexEdgeMatches(matches: RegexEdgeMatch[], pattern: string): string {
-  if (matches.length === 0) return `No edges matching /${pattern}/.`;
-  const lines: string[] = [`${matches.length} edge(s) matching /${pattern}/:`];
-  for (const m of matches) {
-    lines.push(
-      `  [${m.field}] ${m.edge.sourceId} -[${m.edge.relation}]-> ${m.edge.targetId}` +
-      (m.edge.reason ? `  // ${m.edge.reason}` : ''),
-    );
-  }
-  return lines.join('\n');
-}

package/src/graph/regression.ts

@@ -1,199 +0,0 @@
-import type Database from 'better-sqlite3';
-import { loadBaseline, extractFindingsFromDb, type BaselineData } from './baseline.js';
-
-// ── Tolerance ─────────────────────────────────────────────────────────────────
-
-export class Tolerance {
-  private readonly pct: boolean;
-  private readonly value: number;
-
-  private constructor(pct: boolean, value: number) {
-    this.pct = pct;
-    this.value = value;
-  }
-
-  /**
-   * Parse a tolerance specification.
-   * Accepts "2%" (percentage relative to baseline) or "5" (absolute count).
-   * Throws if the spec is malformed or negative.
-   */
-  static parse(spec: string): Tolerance {
-    if (!spec || typeof spec !== 'string') {
-      throw new Error(`Invalid tolerance spec: "${spec}"`);
-    }
-    const trimmed = spec.trim();
-    if (trimmed.endsWith('%')) {
-      const raw = trimmed.slice(0, -1);
-      const value = parseFloat(raw);
-      if (isNaN(value) || value < 0) {
-        throw new Error(`Invalid percentage tolerance: "${spec}"`);
-      }
-      return new Tolerance(true, value);
-    }
-    const value = parseFloat(trimmed);
-    if (isNaN(value) || value < 0) {
-      throw new Error(`Invalid absolute tolerance: "${spec}"`);
-    }
-    return new Tolerance(false, value);
-  }
-
-  /**
-   * Returns true if the delta from baseline to current exceeds tolerance.
-   * Only positive deltas (regressions) can violate tolerance.
-   * Special case: if baseline is 0 and current > 0, percentage tolerance is always exceeded.
-   */
-  exceeded(baseline: number, current: number): boolean {
-    const delta = current - baseline;
-    if (delta <= 0) return false; // improvement or stable — never violated
-    if (this.pct) {
-      if (baseline === 0) return true; // any increase from zero exceeds percentage tolerance
-      const pctChange = (delta / baseline) * 100;
-      return pctChange > this.value;
-    }
-    return delta > this.value;
-  }
-
-  toString(): string {
-    return this.pct ? `${this.value}%` : String(this.value);
-  }
-}
-
-// ── Interfaces ────────────────────────────────────────────────────────────────
-
-export interface RegressionMetric {
-  metric: string;
-  baseline: number;
-  current: number;
-  delta: number;
-  tolerance: string;
-  violated: boolean;
-}
-
-export interface RegressionOutcome {
-  passed: boolean;
-  violations: RegressionMetric[];
-  checkedMetrics: RegressionMetric[];
-  summary: string;
-}
-
-// ── Finding type → metric name mapping ────────────────────────────────────────
-
-const FINDING_TYPE_TO_METRIC: Record<string, string> = {
-  god_node: 'godNodeCount',
-  surprise: 'surpriseCount',
-  bridge_node: 'bridgeNodeCount',
-  unreachable_export: 'unreachableExportCount',
-  ambiguous_edge: 'ambiguousEdgeCount',
-};
-
-/** Canonical metric names — defined once to avoid duplicating the same literal Set/Object. */
-const METRIC_NAMES = Object.values(FINDING_TYPE_TO_METRIC);
-const METRIC_NAME_SET = new Set(METRIC_NAMES);
-
-/** Module-level cache for parsed Tolerance objects — avoids re-parsing identical specs. */
-const toleranceCache = new Map<string, Tolerance>();
-function parseTolerance(spec: string): Tolerance {
-  let t = toleranceCache.get(spec);
-  if (!t) { t = Tolerance.parse(spec); toleranceCache.set(spec, t); }
-  return t;
-}
-
-// ── checkRegression ───────────────────────────────────────────────────────────
-
-/**
- * Compare current DB state against a named baseline.
- *
- * @param db - better-sqlite3 Database instance
- * @param baselinePath - path to the baseline JSON file
- * @param toleranceSpec - e.g. "5%" or "10" — applied to ALL metrics unless metricTolerances provided
- * @param metricTolerances - per-metric tolerance overrides, e.g. { godNodeCount: "2", surpriseCount: "10%" }
- */
-export function checkRegression(
-  db: Database.Database,
-  baselinePath: string,
-  toleranceSpec: string,
-  metricTolerances?: Record<string, string>,
-): RegressionOutcome {
-  const baseline: BaselineData | null = loadBaseline(baselinePath);
-
-  // Compute current counts from DB using shared METRIC_NAMES init
-  const currentFindings = extractFindingsFromDb(db, '');
-  const currentCounts: Record<string, number> = Object.fromEntries(METRIC_NAMES.map(m => [m, 0]));
-  for (const f of currentFindings) {
-    const metricName = FINDING_TYPE_TO_METRIC[f.type];
-    if (metricName && METRIC_NAME_SET.has(metricName)) {
-      currentCounts[metricName]++;
-    }
-  }
-
-  // Compute baseline counts using shared METRIC_NAMES init
-  const baselineCounts: Record<string, number> = Object.fromEntries(METRIC_NAMES.map(m => [m, 0]));
-  if (baseline) {
-    for (const f of baseline.findings) {
-      const metricName = FINDING_TYPE_TO_METRIC[f.type];
-      if (metricName && METRIC_NAME_SET.has(metricName)) {
-        baselineCounts[metricName]++;
-      }
-    }
-  }
-
-  // Default tolerance — use cached parse to avoid rebuilding on repeated calls with same spec
-  const defaultTolerance = parseTolerance(toleranceSpec);
-
-  // Check each metric — per-metric tolerances also cached
-  const checkedMetrics: RegressionMetric[] = [];
-  for (const metric of METRIC_NAMES) {
-    const baselineVal = baselineCounts[metric] ?? 0;
-    const currentVal = currentCounts[metric] ?? 0;
-    const delta = currentVal - baselineVal;
-
-    const metricSpec = metricTolerances?.[metric];
-    const tol = metricSpec ? parseTolerance(metricSpec) : defaultTolerance;
-    const tolStr = tol.toString();
-    const violated = tol.exceeded(baselineVal, currentVal);
-
-    checkedMetrics.push({
-      metric,
-      baseline: baselineVal,
-      current: currentVal,
-      delta,
-      tolerance: tolStr,
-      violated,
-    });
-  }
-
-  const violations = checkedMetrics.filter(m => m.violated);
-  const passed = violations.length === 0;
-
-  const baselineName = baselinePath.split('/').pop()?.replace(/\.json$/, '') ?? baselinePath;
-  const summary = passed
-    ? `Regression check PASSED — no violations against baseline "${baselineName}" (tolerance: ${toleranceSpec})`
-    : `Regression check FAILED — ${violations.length} violation(s) against baseline "${baselineName}" (tolerance: ${toleranceSpec})`;
-
-  return { passed, violations, checkedMetrics, summary };
-}
-
-/**
- * Format a RegressionOutcome as structured text for LLM consumption.
- * Shows pass/fail status, per-metric results, and actionable violation details.
- */
-export function formatRegressionOutcome(outcome: RegressionOutcome): string {
-  const lines: string[] = [outcome.summary];
-
-  lines.push('\nMetrics:');
-  for (const m of outcome.checkedMetrics) {
-    const sign = m.delta > 0 ? `+${m.delta}` : String(m.delta);
-    const status = m.violated ? 'VIOLATED' : 'ok';
-    lines.push(`  ${m.metric}: baseline=${m.baseline} current=${m.current} delta=${sign} tolerance=${m.tolerance} [${status}]`);
-  }
-
-  if (outcome.violations.length > 0) {
-    lines.push('\nViolations requiring attention:');
-    for (const v of outcome.violations) {
-      const sign = v.delta > 0 ? `+${v.delta}` : String(v.delta);
-      lines.push(`  ${v.metric} exceeded tolerance ${v.tolerance} (delta ${sign}): investigate new ${v.metric.replace(/Count$/, '')} introductions`);
-    }
-  }
-
-  return lines.join('\n');
-}

package/src/graph/resolve/discover-types.ts

@@ -1,45 +0,0 @@
-export type FileId = number & { readonly __brand: 'FileId' };
-
-export function fileId(n: number): FileId {
-  return n as FileId;
-}
-
-export type EntryPointSource =
-  | { kind: 'package-json-main' }
-  | { kind: 'package-json-module' }
-  | { kind: 'package-json-exports' }
-  | { kind: 'package-json-bin' }
-  | { kind: 'package-json-script' }
-  | { kind: 'plugin'; name: string }
-  | { kind: 'test-file' }
-  | { kind: 'default-index' }
-  | { kind: 'manual-entry' }
-  | { kind: 'infrastructure-config' }
-  | { kind: 'dynamically-loaded' };
-
-export interface FallowEntryPoint {
-  path: string;
-  source: EntryPointSource;
-}
-
-export function formatEntryPointSource(source: EntryPointSource): string {
-  switch (source.kind) {
-    case 'package-json-main':    return 'package.json[main]';
-    case 'package-json-module':  return 'package.json[module]';
-    case 'package-json-exports': return 'package.json[exports]';
-    case 'package-json-bin':     return 'package.json[bin]';
-    case 'package-json-script':  return 'package.json[scripts]';
-    case 'plugin':               return `plugin:${source.name}`;
-    case 'test-file':            return 'test-file';
-    case 'default-index':        return 'default-index';
-    case 'manual-entry':         return 'manual';
-    case 'infrastructure-config': return 'infra-config';
-    case 'dynamically-loaded':   return 'dynamic';
-  }
-}
-
-export interface FallowDiscoveredFile {
-  id: FileId;
-  path: string;
-  sizeBytes: number;
-}