@monoes/monograph 1.0.0 → 1.2.0

package/src/graph/resolve/specifier.ts

@@ -0,0 +1,120 @@
+import * as path from 'node:path';
+import * as fs from 'node:fs';
+import type { ResolveContext, ResolveResult, FileId } from './types.js';
+import { extractPackageNameFromNodeModulesPath } from './path-info.js';
+
+const STYLE_EXTS = new Set(['.css', '.scss', '.sass', '.less', '.styl']);
+const JS_TS_EXTS = new Set(['.ts', '.tsx', '.mts', '.cts', '.js', '.jsx', '.mjs', '.cjs']);
+
+export function isStyleFile(filePath: string): boolean {
+  return STYLE_EXTS.has(path.extname(filePath).toLowerCase());
+}
+
+export function isJsTsExtension(filePath: string): boolean {
+  return JS_TS_EXTS.has(path.extname(filePath).toLowerCase());
+}
+
+export function isPlainCssFile(filePath: string): boolean {
+  return path.extname(filePath).toLowerCase() === '.css';
+}
+
+export function isBareStyleSubpath(specifier: string): boolean {
+  return !specifier.startsWith('.') && STYLE_EXTS.has(path.extname(specifier).toLowerCase());
+}
+
+export function pathAliasPatternMatches(pattern: string, specifier: string): boolean {
+  if (pattern.endsWith('*')) {
+    return specifier.startsWith(pattern.slice(0, -1));
+  }
+  return specifier === pattern;
+}
+
+export function matchesNearestTsconfigPathAlias(root: string, fromFile: string, specifier: string): boolean {
+  const tsconfigPath = nearestTsconfigPath(root, fromFile);
+  if (!tsconfigPath) return false;
+  try {
+    const raw = fs.readFileSync(tsconfigPath, 'utf8');
+    const json = JSON.parse(stripJsonComments(raw));
+    const paths: Record<string, string[]> = json?.compilerOptions?.paths ?? {};
+    return Object.keys(paths).some(p => pathAliasPatternMatches(p, specifier));
+  } catch {
+    return false;
+  }
+}
+
+export function nearestTsconfigPath(root: string, fromFile: string): string | null {
+  let dir = path.dirname(fromFile);
+  while (dir.startsWith(root)) {
+    const candidate = path.join(dir, 'tsconfig.json');
+    if (fs.existsSync(candidate)) return candidate;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+export function resolveSpecifier(
+  ctx: ResolveContext,
+  fromFile: string,
+  specifier: string,
+  fromStyle: boolean,
+): ResolveResult {
+  if (specifier.startsWith('.') || specifier.startsWith('/')) {
+    const resolved = resolveRelative(ctx, fromFile, specifier);
+    if (resolved) return resolved;
+    if (fromStyle) {
+      const scss = tryScssPartialFallback(ctx, fromFile, specifier);
+      if (scss) return scss;
+    }
+    return { kind: 'Unresolvable', specifier };
+  }
+
+  for (const [pattern, target] of ctx.pathAliases) {
+    if (pathAliasPatternMatches(pattern, specifier)) {
+      const mapped = specifier.replace(pattern.replace('*', ''), target.replace('*', ''));
+      const r = resolveRelative(ctx, ctx.root, mapped);
+      if (r) return r;
+    }
+  }
+
+  const pkg = extractPackageNameFromNodeModulesPath(specifier) ?? specifier.split('/')[0];
+  return { kind: 'NpmPackage', name: pkg };
+}
+
+function resolveRelative(ctx: ResolveContext, fromFile: string, specifier: string): ResolveResult | null {
+  const fromDir = path.dirname(fromFile);
+  const base = path.resolve(fromDir, specifier);
+
+  const directId = ctx.pathToId.get(base) ?? ctx.rawPathToId.get(base);
+  if (directId !== undefined) return { kind: 'InternalModule', fileId: directId };
+
+  const exts = ['.ts', '.tsx', '.mts', '.cts', '.js', '.jsx', '.mjs', '.cjs'];
+  for (const ext of exts) {
+    const id = ctx.pathToId.get(base + ext) ?? ctx.rawPathToId.get(base + ext);
+    if (id !== undefined) return { kind: 'InternalModule', fileId: id };
+  }
+
+  for (const ext of exts) {
+    const id = ctx.pathToId.get(path.join(base, 'index' + ext));
+    if (id !== undefined) return { kind: 'InternalModule', fileId: id };
+  }
+
+  return null;
+}
+
+function tryScssPartialFallback(ctx: ResolveContext, fromFile: string, specifier: string): ResolveResult | null {
+  const fromDir = path.dirname(fromFile);
+  const base = path.resolve(fromDir, specifier);
+  const dir = path.dirname(base);
+  const name = '_' + path.basename(base);
+  for (const ext of ['.scss', '.sass', '.css']) {
+    const id = ctx.pathToId.get(path.join(dir, name + ext));
+    if (id !== undefined) return { kind: 'InternalModule', fileId: id };
+  }
+  return null;
+}
+
+function stripJsonComments(s: string): string {
+  return s.replace(/\/\/[^\n]*/g, '').replace(/\/\*[\s\S]*?\*\//g, '');
+}

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

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

package/src/graph/resolve/types.ts

@@ -0,0 +1,108 @@
+export type FileId = number;
+
+export type ResolveResult =
+  | { kind: 'InternalModule'; fileId: FileId }
+  | { kind: 'ExternalFile'; path: string }
+  | { kind: 'NpmPackage'; name: string }
+  | { kind: 'Unresolvable'; specifier: string };
+
+export interface ImportInfo {
+  specifier: string;
+  isDynamic?: boolean;
+  isTypeOnly?: boolean;
+  span?: { start: number; end: number };
+}
+
+export interface ReExportInfo {
+  specifier: string;
+  isTypeOnly?: boolean;
+}
+
+export interface ResolvedImport {
+  info: ImportInfo;
+  target: ResolveResult;
+}
+
+export interface ResolvedReExport {
+  info: ReExportInfo;
+  target: ResolveResult;
+}
+
+export interface DynamicImportPattern {
+  pattern: string;
+  fromFile: string;
+}
+
+export interface ResolvedModule {
+  fileId: FileId;
+  path: string;
+  resolvedImports: ResolvedImport[];
+  resolvedReExports: ResolvedReExport[];
+  resolvedDynamicImports: ResolvedImport[];
+  resolvedDynamicPatterns: Array<[DynamicImportPattern, FileId[]]>;
+  unusedImportBindings: Set<string>;
+  typeReferencedImportBindings: string[];
+  valueReferencedImportBindings: string[];
+  hasCjsExports: boolean;
+}
+
+export interface CanonicalFallback {
+  files: DiscoveredFile[];
+  map: Map<string, FileId> | null;
+}
+
+export interface DiscoveredFile {
+  path: string;
+  fileId: FileId;
+  canonicalPath?: string;
+}
+
+export interface WorkspaceInfo {
+  root: string;
+  name?: string;
+}
+
+export interface ResolveContext {
+  pathToId: Map<string, FileId>;
+  rawPathToId: Map<string, FileId>;
+  workspaceRoots: Map<string, string>;
+  pathAliases: Array<[string, string]>;
+  scssIncludePaths: string[];
+  root: string;
+  canonicalFallback?: CanonicalFallback;
+  tsconfigWarned: Set<string>;
+  activePlugins: string[];
+  extraConditions: string[];
+}
+
+export const OUTPUT_DIRS = ['dist', 'build', 'out', 'esm', 'cjs', '.next', '.nuxt', '.svelte-kit'] as const;
+
+export const SOURCE_EXTS = ['ts', 'tsx', 'mts', 'cts', 'js', 'jsx', 'mjs', 'cjs'] as const;
+
+export const RN_PLATFORM_PREFIXES = ['.web', '.ios', '.android', '.native'] as const;
+
+export function getOrBuildCanonicalMap(fallback: CanonicalFallback): Map<string, FileId> {
+  if (!fallback.map) {
+    fallback.map = new Map(
+      fallback.files
+        .filter(f => f.canonicalPath)
+        .map(f => [f.canonicalPath!, f.fileId])
+    );
+  }
+  return fallback.map;
+}
+
+export function makeResolvedModule(fileId: FileId, path: string): ResolvedModule {
+  return {
+    fileId,
+    path,
+    resolvedImports: [],
+    resolvedReExports: [],
+    resolvedDynamicImports: [],
+    resolvedDynamicPatterns: [],
+    unusedImportBindings: new Set(),
+    typeReferencedImportBindings: [],
+    valueReferencedImportBindings: [],
+    hasCjsExports: false,
+  };
+}

package/src/graph/resolve/upgrades.ts

@@ -0,0 +1,32 @@
+import type { ResolvedModule } from './types.js';
+
+export function applySpecifierUpgrades(resolved: ResolvedModule[]): void {
+  const internalBySpecifier = new Map<string, number>();
+
+  for (const mod of resolved) {
+    for (const ri of mod.resolvedImports) {
+      if (ri.target.kind === 'InternalModule') {
+        internalBySpecifier.set(ri.info.specifier, ri.target.fileId);
+      }
+    }
+  }
+
+  for (const mod of resolved) {
+    for (const ri of mod.resolvedImports) {
+      if (ri.target.kind === 'NpmPackage') {
+        const internalId = internalBySpecifier.get(ri.info.specifier);
+        if (internalId !== undefined) {
+          ri.target = { kind: 'InternalModule', fileId: internalId };
+        }
+      }
+    }
+    for (const rr of mod.resolvedReExports) {
+      if (rr.target.kind === 'NpmPackage') {
+        const internalId = internalBySpecifier.get(rr.info.specifier);
+        if (internalId !== undefined) {
+          rr.target = { kind: 'InternalModule', fileId: internalId };
+        }
+      }
+    }
+  }
+}

package/src/graph/ripple-impact.ts

@@ -0,0 +1,71 @@
+/**
+ * Ripple / cascade impact analysis.
+ *
+ * Given a starting node, perform a multi-hop BFS through *directed* edges and
+ * compute how far a change can propagate.  Each depth level is assigned a
+ * decaying weight so that direct dependents (depth 1) contribute more to the
+ * totalScore than transitive dependents.
+ *
+ * Default decay factor: 0.5 per hop (configurable).
+ */
+
+export interface RippleEdge {
+  sourceId: string;
+  targetId: string;
+}
+
+export interface RippleResult {
+  /** Nodes reachable at each depth, starting at depth 1 (direct neighbors). */
+  byDepth: Record<number, string[]>;
+  /** Weighted sum: Σ(count_at_depth * decay^depth). */
+  totalScore: number;
+}
+
+/**
+ * Compute the ripple impact of changing `startNodeId`.
+ *
+ * @param startNodeId  The node whose change we are propagating.
+ * @param edges        Directed edges in the graph.
+ * @param maxDepth     Maximum BFS depth (default 3).
+ * @param decayFactor  Weight multiplier per depth level (default 0.5).
+ */
+export function rippleImpact(
+  startNodeId: string,
+  edges: RippleEdge[],
+  maxDepth = 3,
+  decayFactor = 0.5,
+): RippleResult {
+  // Build directed adjacency (source → targets)
+  const outgoing = new Map<string, string[]>();
+  for (const { sourceId, targetId } of edges) {
+    if (!outgoing.has(sourceId)) outgoing.set(sourceId, []);
+    outgoing.get(sourceId)!.push(targetId);
+  }
+
+  if (!outgoing.has(startNodeId)) {
+    return { byDepth: {}, totalScore: 0 };
+  }
+
+  const visited = new Set<string>([startNodeId]);
+  const byDepth: Record<number, string[]> = {};
+  let frontier = [startNodeId];
+  let totalScore = 0;
+
+  for (let depth = 1; depth <= maxDepth; depth++) {
+    const nextFrontier: string[] = [];
+    for (const node of frontier) {
+      for (const neighbor of outgoing.get(node) ?? []) {
+        if (!visited.has(neighbor)) {
+          visited.add(neighbor);
+          nextFrontier.push(neighbor);
+        }
+      }
+    }
+    if (nextFrontier.length === 0) break;
+    byDepth[depth] = nextFrontier;
+    totalScore += nextFrontier.length * Math.pow(decayFactor, depth);
+    frontier = nextFrontier;
+  }
+
+  return { byDepth, totalScore };
+}

package/src/graph/risk-profile.ts

@@ -0,0 +1,134 @@
+import type { MonographDb } from '../storage/db.js';
+
+export interface SizeBin {
+  label: string;    // e.g. '1-10 lines'
+  min: number;
+  max: number;
+  count: number;
+  percentage: number;
+}
+
+export interface RiskProfileReport {
+  functionSizeDistribution: SizeBin[];
+  paramCountDistribution: SizeBin[];
+  riskSummary: {
+    largeFunction: number;    // LOC > 100
+    longParamList: number;    // params > 5
+    highRisk: number;         // BOTH large AND long param list
+  };
+  p50loc: number;
+  p90loc: number;
+  p95loc: number;
+}
+
+interface FunctionNode {
+  start_line: number | null;
+  end_line: number | null;
+  properties: string | null;
+}
+
+const LOC_BINS: Array<{ label: string; min: number; max: number }> = [
+  { label: '1-10 lines',   min: 1,   max: 10  },
+  { label: '11-25 lines',  min: 11,  max: 25  },
+  { label: '26-50 lines',  min: 26,  max: 50  },
+  { label: '51-100 lines', min: 51,  max: 100 },
+  { label: '101-250 lines',min: 101, max: 250 },
+  { label: '250+ lines',   min: 251, max: Infinity },
+];
+
+const PARAM_BINS: Array<{ label: string; min: number; max: number }> = [
+  { label: '0-2 params', min: 0, max: 2 },
+  { label: '3-5 params', min: 3, max: 5 },
+  { label: '6-8 params', min: 6, max: 8 },
+  { label: '9+ params',  min: 9, max: Infinity },
+];
+
+function percentile(sorted: number[], p: number): number {
+  if (sorted.length === 0) return 0;
+  const idx = Math.floor(sorted.length * p);
+  return sorted[Math.min(idx, sorted.length - 1)];
+}
+
+export function computeRiskProfile(db: MonographDb): RiskProfileReport {
+  const rows = db.prepare(`
+    SELECT start_line, end_line, properties
+    FROM nodes
+    WHERE label IN ('Function', 'Method')
+  `).all() as FunctionNode[];
+
+  const locs: number[] = [];
+  const params: number[] = [];
+
+  for (const row of rows) {
+    if (row.start_line === null || row.end_line === null) continue;
+    const loc = row.end_line - row.start_line + 1;
+    if (loc < 1) continue;
+    locs.push(loc);
+
+    let paramCount = 0;
+    if (row.properties) {
+      try {
+        const props = JSON.parse(row.properties) as Record<string, unknown>;
+        if (typeof props['paramCount'] === 'number') {
+          paramCount = props['paramCount'];
+        }
+      } catch {
+        // ignore malformed JSON
+      }
+    }
+    params.push(paramCount);
+  }
+
+  const total = locs.length;
+
+  // ── LOC distribution ───────────────────────────────────────────────────────
+  const functionSizeDistribution: SizeBin[] = LOC_BINS.map(bin => {
+    const count = locs.filter(l => l >= bin.min && l <= bin.max).length;
+    return {
+      label: bin.label,
+      min: bin.min,
+      max: bin.max === Infinity ? 999999 : bin.max,
+      count,
+      percentage: total > 0 ? Math.round((count / total) * 1000) / 10 : 0,
+    };
+  });
+
+  // ── Param distribution ─────────────────────────────────────────────────────
+  const paramCountDistribution: SizeBin[] = PARAM_BINS.map(bin => {
+    const count = params.filter(p => p >= bin.min && p <= bin.max).length;
+    return {
+      label: bin.label,
+      min: bin.min,
+      max: bin.max === Infinity ? 999999 : bin.max,
+      count,
+      percentage: total > 0 ? Math.round((count / total) * 1000) / 10 : 0,
+    };
+  });
+
+  // ── Risk summary ───────────────────────────────────────────────────────────
+  let largeFunction = 0;
+  let longParamList = 0;
+  let highRisk = 0;
+  for (let i = 0; i < locs.length; i++) {
+    const large = locs[i] > 100;
+    const longParam = (params[i] ?? 0) > 5;
+    if (large) largeFunction++;
+    if (longParam) longParamList++;
+    if (large && longParam) highRisk++;
+  }
+
+  // ── Percentiles ────────────────────────────────────────────────────────────
+  const sortedLocs = [...locs].sort((a, b) => a - b);
+  const p50loc = percentile(sortedLocs, 0.50);
+  const p90loc = percentile(sortedLocs, 0.90);
+  const p95loc = percentile(sortedLocs, 0.95);
+
+  return {
+    functionSizeDistribution,
+    paramCountDistribution,
+    riskSummary: { largeFunction, longParamList, highRisk },
+    p50loc,
+    p90loc,
+    p95loc,
+  };
+}

package/src/graph/shingle-filter.ts

@@ -0,0 +1,143 @@
+export interface ShingleFilter {
+  add(id: string, tokens: string[]): void;
+  candidates(tokens: string[], topK?: number): string[];   // fast pre-filter
+}
+
+/**
+ * Generate k-shingles (k-grams) from a token array.
+ * Each shingle is the concatenation of k consecutive tokens joined by a space.
+ */
+function kShingles(tokens: string[], k: number): string[] {
+  if (tokens.length < k) return [tokens.join(' ')];
+  const shingles: string[] = [];
+  for (let i = 0; i <= tokens.length - k; i++) {
+    shingles.push(tokens.slice(i, i + k).join(' '));
+  }
+  return shingles;
+}
+
+/**
+ * Simple string hash that produces a non-negative 32-bit integer.
+ * Uses a djb2-style hash.
+ */
+function hashString(s: string): number {
+  let h = 5381;
+  for (let i = 0; i < s.length; i++) {
+    h = ((h << 5) + h) ^ s.charCodeAt(i);
+    h = h >>> 0; // keep unsigned 32-bit
+  }
+  return h;
+}
+
+/**
+ * Compute a MinHash signature for a set of shingles using
+ * numHashes linear hash functions: h_i(x) = (a_i * x + b_i) % prime
+ */
+function minHashSignature(shingles: string[], numHashes: number): Uint32Array {
+  const PRIME = 4294967311; // first prime > 2^32
+  const sig = new Uint32Array(numHashes).fill(0xffffffff);
+
+  // Deterministic seeds derived from hash index
+  for (const shingle of shingles) {
+    const x = hashString(shingle);
+    for (let i = 0; i < numHashes; i++) {
+      // Deterministic a, b per hash function — use index-based seeds
+      const a = ((i * 2654435761 + 0x9e3779b9) >>> 0);
+      const b = ((i * 2246822519 + 0x85ebca6b) >>> 0);
+      // Linear hash modulo prime (BigInt for correctness)
+      const hashVal = Number((BigInt(a) * BigInt(x) + BigInt(b)) % BigInt(PRIME)) >>> 0;
+      if (hashVal < sig[i]) {
+        sig[i] = hashVal;
+      }
+    }
+  }
+  return sig;
+}
+
+export function createShingleFilter(k = 5, numHashes = 128): ShingleFilter {
+  // Each entry: { sig: Uint32Array }
+  const index = new Map<string, Uint32Array>();
+
+  // LSH: split numHashes into bands of rows
+  // Standard LSH: numBands * numRows = numHashes, threshold ≈ (1/numBands)^(1/numRows)
+  // We target threshold ~0.5: solve (1/b)^(1/r) = 0.5 with b*r = numHashes
+  // A reasonable split is sqrt(numHashes) bands of sqrt(numHashes) rows each.
+  const numBands = Math.round(Math.sqrt(numHashes));
+  const numRows = Math.floor(numHashes / numBands);
+
+  function getBandKey(id: string, band: number, sig: Uint32Array): string {
+    const parts: number[] = [];
+    for (let r = 0; r < numRows; r++) {
+      const idx = band * numRows + r;
+      if (idx < numHashes) parts.push(sig[idx]);
+    }
+    return `b${band}:${parts.join(',')}`;
+  }
+
+  // Band bucket → list of candidate IDs
+  const bandBuckets = new Map<string, string[]>();
+
+  return {
+    add(id: string, tokens: string[]): void {
+      const shingles = kShingles(tokens, k);
+      const sig = minHashSignature(shingles, numHashes);
+      index.set(id, sig);
+
+      // Insert into LSH band buckets
+      for (let band = 0; band < numBands; band++) {
+        const key = getBandKey(id, band, sig);
+        const bucket = bandBuckets.get(key);
+        if (bucket) {
+          bucket.push(id);
+        } else {
+          bandBuckets.set(key, [id]);
+        }
+      }
+    },
+
+    candidates(tokens: string[], topK = 10): string[] {
+      const shingles = kShingles(tokens, k);
+      const querySig = minHashSignature(shingles, numHashes);
+
+      // Collect candidate IDs via LSH band matching
+      const candidateScores = new Map<string, number>();
+
+      for (let band = 0; band < numBands; band++) {
+        const key = getBandKey('__query__', band, querySig);
+        // Manually compute the key for the query signature
+        const parts: number[] = [];
+        for (let r = 0; r < numRows; r++) {
+          const idx = band * numRows + r;
+          if (idx < numHashes) parts.push(querySig[idx]);
+        }
+        const queryKey = `b${band}:${parts.join(',')}`;
+        const bucket = bandBuckets.get(queryKey);
+        if (bucket) {
+          for (const id of bucket) {
+            candidateScores.set(id, (candidateScores.get(id) ?? 0) + 1);
+          }
+        }
+      }
+
+      if (candidateScores.size === 0) return [];
+
+      // Compute Jaccard estimate from signature agreement for ranked results
+      const ranked = [...candidateScores.keys()].map(id => {
+        const sig = index.get(id)!;
+        let matches = 0;
+        for (let i = 0; i < numHashes; i++) {
+          if (sig[i] === querySig[i]) matches++;
+        }
+        const jaccardEst = matches / numHashes;
+        return { id, jaccardEst };
+      });
+
+      // Filter by estimated Jaccard > 0.5 and return topK
+      return ranked
+        .filter(r => r.jaccardEst > 0.5)
+        .sort((a, b) => b.jaccardEst - a.jaccardEst)
+        .slice(0, topK)
+        .map(r => r.id);
+    },
+  };
+}