@monoes/monograph 1.1.0 → 1.2.0

package/src/graph/regression.ts

@@ -0,0 +1,174 @@
+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',
+};
+
+// ── 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
+  const currentFindings = extractFindingsFromDb(db, '');
+  const currentCounts: Record<string, number> = {
+    godNodeCount: 0,
+    surpriseCount: 0,
+    bridgeNodeCount: 0,
+    unreachableExportCount: 0,
+    ambiguousEdgeCount: 0,
+  };
+  for (const f of currentFindings) {
+    const metricName = FINDING_TYPE_TO_METRIC[f.type];
+    if (metricName && metricName in currentCounts) {
+      currentCounts[metricName]++;
+    }
+  }
+
+  // Compute baseline counts
+  const baselineCounts: Record<string, number> = {
+    godNodeCount: 0,
+    surpriseCount: 0,
+    bridgeNodeCount: 0,
+    unreachableExportCount: 0,
+    ambiguousEdgeCount: 0,
+  };
+  if (baseline) {
+    for (const f of baseline.findings) {
+      const metricName = FINDING_TYPE_TO_METRIC[f.type];
+      if (metricName && metricName in baselineCounts) {
+        baselineCounts[metricName]++;
+      }
+    }
+  }
+
+  // Default tolerance
+  const defaultTolerance = Tolerance.parse(toleranceSpec);
+
+  // Check each metric
+  const checkedMetrics: RegressionMetric[] = [];
+  for (const metric of Object.keys(currentCounts)) {
+    const baselineVal = baselineCounts[metric] ?? 0;
+    const currentVal = currentCounts[metric] ?? 0;
+    const delta = currentVal - baselineVal;
+
+    const metricSpec = metricTolerances?.[metric];
+    const tol = metricSpec ? Tolerance.parse(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 };
+}

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

@@ -0,0 +1,45 @@
+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;
+}

package/src/graph/resolve/dynamic-imports.ts

@@ -0,0 +1,102 @@
+// Resolve import() calls into structured import entries.
+
+export type DynamicImportPattern =
+  | { kind: 'string'; value: string }
+  | { kind: 'template'; prefix: string; suffix: string }
+  | { kind: 'expression' };
+
+export interface DynamicImportInfo {
+  pattern: DynamicImportPattern;
+  importedNames: string[];   // destructured: `const { a } = await import('./x')` → ['a']
+  namespaceLocal?: string;   // `const ns = await import('./x')` → 'ns'
+  isSideEffect: boolean;
+  line: number;
+}
+
+export interface ResolvedDynamicImport {
+  source: DynamicImportInfo;
+  resolvedPaths: string[];   // matched file paths
+  isGlob: boolean;
+}
+
+/** Parse dynamic import calls from source text. */
+export function parseDynamicImports(source: string): DynamicImportInfo[] {
+  const results: DynamicImportInfo[] = [];
+  const lines = source.split('\n');
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (!line.includes('import(')) continue;
+
+    // Template literal: import(`./routes/${name}`)
+    const tmplM = /import\(`([^`]*)\$\{[^}]+\}([^`]*)`\)/.exec(line);
+    if (tmplM) {
+      results.push({
+        pattern: { kind: 'template', prefix: tmplM[1], suffix: tmplM[2] },
+        importedNames: [],
+        isSideEffect: true,
+        line: i + 1,
+      });
+      continue;
+    }
+
+    // String literal: import('./foo')
+    const strM = /import\(\s*['"`]([^'"`]+)['"`]\s*\)/.exec(line);
+    if (!strM) continue;
+
+    const path = strM[1];
+
+    // Destructured await: const { a, b } = await import('./x')
+    const destructM = /const\s+\{([^}]+)\}\s*=\s*await\s+import/.exec(line);
+    if (destructM) {
+      const names = destructM[1].split(',').map(s => s.trim().split(/\s+as\s+/)[0].trim()).filter(Boolean);
+      results.push({ pattern: { kind: 'string', value: path }, importedNames: names, isSideEffect: false, line: i + 1 });
+      continue;
+    }
+
+    // Namespace: const ns = await import('./x')
+    const nsM = /const\s+([a-zA-Z_$][\w$]*)\s*=\s*await\s+import/.exec(line);
+    if (nsM) {
+      results.push({ pattern: { kind: 'string', value: path }, importedNames: [], namespaceLocal: nsM[1], isSideEffect: false, line: i + 1 });
+      continue;
+    }
+
+    // Bare side-effect: await import('./x') or import('./x').then(...)
+    results.push({ pattern: { kind: 'string', value: path }, importedNames: [], isSideEffect: true, line: i + 1 });
+  }
+
+  return results;
+}
+
+/** Expand a template-literal import to a glob pattern. */
+export function templateToGlob(prefix: string, suffix: string): string {
+  return `${prefix}*${suffix}`;
+}
+
+/** Match a glob pattern against a list of file paths (simple prefix+suffix matching). */
+export function matchGlob(pattern: string, files: string[]): string[] {
+  const [pre, suf = ''] = pattern.split('*');
+  return files.filter(f => f.includes(pre) && (suf === '' || f.endsWith(suf)));
+}
+
+/** Resolve a single dynamic import info against a list of known file paths. */
+export function resolveSingleDynamicImport(
+  info: DynamicImportInfo,
+  allFiles: string[],
+  currentDir: string,
+): ResolvedDynamicImport {
+  if (info.pattern.kind === 'expression') {
+    return { source: info, resolvedPaths: [], isGlob: false };
+  }
+  if (info.pattern.kind === 'template') {
+    const glob = templateToGlob(
+      currentDir + '/' + info.pattern.prefix,
+      info.pattern.suffix,
+    );
+    return { source: info, resolvedPaths: matchGlob(glob, allFiles), isGlob: true };
+  }
+  // String literal
+  const target = info.pattern.value;
+  const resolved = allFiles.find(f => f.endsWith(target.replace(/^\.\//, '/'))) ?? target;
+  return { source: info, resolvedPaths: [resolved], isGlob: false };
+}

package/src/graph/resolve/fallbacks.ts

@@ -0,0 +1,79 @@
+import * as path from 'node:path';
+import type { ResolveContext, ResolveResult, FileId, DynamicImportPattern, DiscoveredFile } from './types.js';
+import { OUTPUT_DIRS } from './types.js';
+import { extractPackageNameFromNodeModulesPath } from './path-info.js';
+
+export function trySourceFallback(canonical: string, pathToId: Map<string, FileId>): FileId | null {
+  const normalized = canonical.replace(/\\/g, '/');
+  for (const outDir of OUTPUT_DIRS) {
+    const pattern = `/${outDir}/`;
+    if (normalized.includes(pattern)) {
+      const sourcePath = normalized.replace(pattern, '/src/');
+      const id = pathToId.get(sourcePath);
+      if (id !== undefined) return id;
+    }
+  }
+  return null;
+}
+
+export function tryPnpmWorkspaceFallback(
+  canonical: string,
+  pathToId: Map<string, FileId>,
+  workspaceRoots: Map<string, string>,
+): FileId | null {
+  const normalized = canonical.replace(/\\/g, '/');
+  const pnpmStore = 'node_modules/.pnpm/';
+  const idx = normalized.indexOf(pnpmStore);
+  if (idx === -1) return null;
+  const afterStore = normalized.slice(idx + pnpmStore.length);
+  const nodeModulesIdx = afterStore.indexOf('/node_modules/');
+  if (nodeModulesIdx === -1) return null;
+  const subpath = afterStore.slice(nodeModulesIdx + '/node_modules/'.length);
+  for (const [, wsRoot] of workspaceRoots) {
+    const candidate = path.join(wsRoot, 'node_modules', subpath);
+    const id = pathToId.get(candidate);
+    if (id !== undefined) return id;
+  }
+  return null;
+}
+
+export function tryWorkspacePackageFallback(
+  ctx: ResolveContext,
+  specifier: string,
+): ResolveResult | null {
+  for (const [pkgName, wsRoot] of ctx.workspaceRoots) {
+    if (specifier === pkgName || specifier.startsWith(pkgName + '/')) {
+      const subpath = specifier.slice(pkgName.length);
+      const candidate = path.join(wsRoot, subpath || 'index');
+      const id = ctx.pathToId.get(candidate);
+      if (id !== undefined) return { kind: 'InternalModule', fileId: id };
+    }
+  }
+  return null;
+}
+
+export function makeGlobFromPattern(pattern: DynamicImportPattern): string {
+  return pattern.pattern
+    .replace(/\$\{[^}]+\}/g, '*')
+    .replace(/\+/g, '*')
+    .replace(/\(\?:[^)]+\)/g, '*');
+}
+
+export function tryScssIncludePathFallback(
+  ctx: ResolveContext,
+  _fromFile: string,
+  specifier: string,
+  fromStyle: boolean,
+): ResolveResult | null {
+  if (!fromStyle) return null;
+  for (const includePath of ctx.scssIncludePaths) {
+    const candidate = path.join(includePath, specifier);
+    const id = ctx.pathToId.get(candidate);
+    if (id !== undefined) return { kind: 'InternalModule', fileId: id };
+    for (const ext of ['.scss', '.sass', '.css']) {
+      const withExt = ctx.pathToId.get(candidate + ext);
+      if (withExt !== undefined) return { kind: 'InternalModule', fileId: withExt };
+    }
+  }
+  return null;
+}

package/src/graph/resolve/index.ts

@@ -0,0 +1,68 @@
+import type { ResolveContext, ResolvedModule, DiscoveredFile, WorkspaceInfo, FileId } from './types.js';
+import { makeResolvedModule } from './types.js';
+import { resolveStaticImports } from './static-imports.js';
+import { resolveReExports } from './re-exports.js';
+import { applySpecifierUpgrades } from './upgrades.js';
+import { extractPackageNameFromNodeModulesPath } from './path-info.js';
+
+export * from './types.js';
+export * from './path-info.js';
+export * from './specifier.js';
+export * from './static-imports.js';
+export * from './require-imports.js';
+export * from './re-exports.js';
+export * from './fallbacks.js';
+export * from './react-native.js';
+export * from './upgrades.js';
+
+export interface ModuleInfo {
+  fileId: FileId;
+  path: string;
+  imports: Array<{ specifier: string; isDynamic?: boolean; isTypeOnly?: boolean }>;
+  reExports: Array<{ specifier: string; isTypeOnly?: boolean }>;
+  hasCjsExports?: boolean;
+}
+
+export function resolveAllImports(
+  modules: ModuleInfo[],
+  files: DiscoveredFile[],
+  workspaces: WorkspaceInfo[],
+  activePlugins: string[],
+  pathAliases: Array<[string, string]>,
+  scssIncludePaths: string[],
+  root: string,
+  extraConditions: string[],
+): ResolvedModule[] {
+  const pathToId = new Map<string, FileId>(files.map(f => [f.path, f.fileId]));
+  const rawPathToId = new Map<string, FileId>(
+    files.filter(f => f.canonicalPath).map(f => [f.canonicalPath!, f.fileId])
+  );
+  const workspaceRoots = new Map<string, string>(
+    workspaces.filter(w => w.name).map(w => [w.name!, w.root])
+  );
+
+  const ctx: ResolveContext = {
+    pathToId,
+    rawPathToId,
+    workspaceRoots,
+    pathAliases,
+    scssIncludePaths,
+    root,
+    tsconfigWarned: new Set(),
+    activePlugins,
+    extraConditions,
+  };
+
+  const resolved = modules.map(mod => {
+    const rm = makeResolvedModule(mod.fileId, mod.path);
+    rm.resolvedImports = resolveStaticImports(ctx, mod.path, mod.imports);
+    rm.resolvedReExports = resolveReExports(ctx, mod.path, mod.reExports);
+    rm.hasCjsExports = mod.hasCjsExports ?? false;
+    return rm;
+  });
+
+  applySpecifierUpgrades(resolved);
+  return resolved;
+}
+
+export { extractPackageNameFromNodeModulesPath };

package/src/graph/resolve/path-info.ts

@@ -0,0 +1,41 @@
+const PATH_ALIAS_PREFIXES = ['@/', '~/', '#', '@@/'];
+const PASCAL_SCOPE_RE = /^@[A-Z]/;
+const PACKAGE_NAME_RE = /^(@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/i;
+
+export function isPathAlias(specifier: string): boolean {
+  for (const prefix of PATH_ALIAS_PREFIXES) {
+    if (specifier.startsWith(prefix)) return true;
+  }
+  return PASCAL_SCOPE_RE.test(specifier);
+}
+
+export function isBareSpecifier(specifier: string): boolean {
+  if (specifier.startsWith('.') || specifier.startsWith('/')) return false;
+  if (specifier.startsWith('node:') || specifier.startsWith('bun:')) return false;
+  if (/^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(specifier)) return false;
+  return true;
+}
+
+export function isValidPackageName(name: string): boolean {
+  return PACKAGE_NAME_RE.test(name);
+}
+
+export function extractPackageName(specifier: string): string {
+  if (specifier.startsWith('@')) {
+    const parts = specifier.split('/');
+    return parts.length >= 2 ? `${parts[0]}/${parts[1]}` : specifier;
+  }
+  return specifier.split('/')[0];
+}
+
+export function extractPackageNameFromNodeModulesPath(path: string): string | null {
+  const normalized = path.replace(/\\/g, '/');
+  const idx = normalized.lastIndexOf('node_modules/');
+  if (idx === -1) return null;
+  const after = normalized.slice(idx + 'node_modules/'.length);
+  if (after.startsWith('@')) {
+    const parts = after.split('/');
+    return parts.length >= 2 ? `${parts[0]}/${parts[1]}` : null;
+  }
+  return after.split('/')[0] || null;
+}

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

@@ -0,0 +1,14 @@
+import type { ResolveContext, ResolvedReExport, ReExportInfo } from './types.js';
+import { resolveSpecifier, isStyleFile } from './specifier.js';
+
+export function resolveReExports(
+  ctx: ResolveContext,
+  filePath: string,
+  reExports: ReExportInfo[],
+): ResolvedReExport[] {
+  const fromStyle = isStyleFile(filePath);
+  return reExports.map(info => ({
+    info,
+    target: resolveSpecifier(ctx, filePath, info.specifier, fromStyle),
+  }));
+}

package/src/graph/resolve/react-native.ts

@@ -0,0 +1,27 @@
+const REACT_NATIVE_PLUGINS = ['react-native', 'expo', '@react-native'];
+const BASE_EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs'];
+const RN_SUFFIXES = ['.native', '.ios', '.android', '.web'];
+const BASE_CONDITIONS = ['import', 'require', 'default'];
+const RN_CONDITIONS = ['react-native', 'browser', 'module'];
+
+export function hasReactNativePlugin(activePlugins: string[]): boolean {
+  return activePlugins.some(p => REACT_NATIVE_PLUGINS.some(rn => p.includes(rn)));
+}
+
+export function buildExtensions(activePlugins: string[]): string[] {
+  if (!hasReactNativePlugin(activePlugins)) return BASE_EXTENSIONS;
+  const rnExts: string[] = [];
+  for (const suffix of RN_SUFFIXES) {
+    for (const ext of ['.ts', '.tsx', '.js', '.jsx']) {
+      rnExts.push(suffix + ext);
+    }
+  }
+  return [...rnExts, ...BASE_EXTENSIONS];
+}
+
+export function buildConditionNames(activePlugins: string[], extraConditions: string[]): string[] {
+  const conditions = [...BASE_CONDITIONS];
+  if (hasReactNativePlugin(activePlugins)) conditions.unshift(...RN_CONDITIONS);
+  conditions.push(...extraConditions);
+  return [...new Set(conditions)];
+}

package/src/graph/resolve/require-imports.ts

@@ -0,0 +1,18 @@
+import type { ResolveContext, ResolvedImport, ImportInfo } from './types.js';
+import { resolveSpecifier } from './specifier.js';
+
+export interface RequireCallInfo {
+  specifier: string;
+  span?: { start: number; end: number };
+}
+
+export function resolveRequireImports(
+  ctx: ResolveContext,
+  filePath: string,
+  requireCalls: RequireCallInfo[],
+): ResolvedImport[] {
+  return requireCalls.map(req => {
+    const info: ImportInfo = { specifier: req.specifier, isDynamic: true, span: req.span };
+    return { info, target: resolveSpecifier(ctx, filePath, req.specifier, false) };
+  });
+}