@monoes/monograph 1.5.5 → 1.5.7

package/src/analysis/dependency-health.ts

@@ -1,146 +0,0 @@
-/**
- * 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 },
-  };
-}
-
-/**
- * Format dependency health results as structured text for LLM consumption.
- */
-export function formatDependencyHealth(result: DependencyHealthResult): string {
-  const { score, details } = result;
-  const pct = (v: number) => `${(v * 100).toFixed(1)}%`;
-  const grade = score >= 0.9 ? 'Excellent' : score >= 0.75 ? 'Good' : score >= 0.5 ? 'Fair' : 'Poor';
-  const lines: string[] = [
-    `Dependency health score: ${pct(score)} (${grade})`,
-    `  Cycle penalty       : ${pct(details.cyclePenalty)}  (fraction of nodes in cycles; weight 35%)`,
-    `  Dead-code ratio     : ${pct(details.deadCodeRatio)}  (fraction of unreachable nodes; weight 25%)`,
-    `  Fan-out skew        : ${pct(details.fanSkew)}  (out-degree coefficient of variation / 4; weight 20%)`,
-    `  God-node density    : ${pct(details.godNodeConcentration)}  (max in-degree / total edges; weight 20%)`,
-  ];
-  const advice: string[] = [];
-  if (details.cyclePenalty > 0.1) advice.push('reduce circular imports (cyclePenalty high)');
-  if (details.deadCodeRatio > 0.1) advice.push('remove unreachable exports (deadCodeRatio high)');
-  if (details.fanSkew > 0.25) advice.push('break up high-fan-out modules (fanSkew high)');
-  if (details.godNodeConcentration > 0.1) advice.push('distribute hub dependencies (godNodeConcentration high)');
-  if (advice.length > 0) {
-    lines.push('  Recommendations: ' + advice.join('; '));
-  }
-  return lines.join('\n');
-}

package/src/analysis/duplicate-exports.ts

@@ -1,110 +0,0 @@
-import type { MonographDb } from '../storage/db.js';
-
-export interface DuplicateExportLocation {
-  nodeId: string;
-  filePath: string | null;
-  startLine: number | null;
-  label: string;
-}
-
-export interface DuplicateExportGroup {
-  exportName: string;
-  locations: DuplicateExportLocation[];
-  count: number;
-}
-
-export interface DuplicateExportsResult {
-  groups: DuplicateExportGroup[];
-  totalDuplicates: number;
-  affectedFiles: number;
-}
-
-interface ExportedRow {
-  id: string;
-  name: string;
-  file_path: string | null;
-  start_line: number | 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, start_line, 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, DuplicateExportLocation[]>();
-
-  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, startLine: row.start_line ?? null, 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,
-  };
-}
-
-/** Format DuplicateExportsResult as structured text with file:line hints for LLM navigation. */
-export function formatDuplicateExports(result: DuplicateExportsResult): string {
-  if (result.totalDuplicates === 0) {
-    return 'Duplicate exports: none detected.';
-  }
-
-  const lines: string[] = [
-    `Duplicate exports: ${result.totalDuplicates} name(s) exported from multiple files (${result.affectedFiles} file(s) affected).`,
-    '',
-  ];
-
-  for (const group of result.groups) {
-    lines.push(`  ${group.exportName} (${group.count} locations):`);
-    for (const loc of group.locations) {
-      const ref = loc.filePath
-        ? loc.startLine != null
-          ? `${loc.filePath}:${loc.startLine}`
-          : loc.filePath
-        : '(unknown)';
-      lines.push(`    ${loc.label}  ${ref}`);
-    }
-  }
-
-  lines.push('');
-  lines.push('Fix: consolidate duplicate exports into a single canonical location or rename to avoid conflicts.');
-  return lines.join('\n').trimEnd();
-}

package/src/analysis/fallow-suppression.ts

@@ -1,98 +0,0 @@
-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

@@ -1,47 +0,0 @@
-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

@@ -1,223 +0,0 @@
-import { readFileSync, readdirSync, lstatSync } 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[] {
-  // Pregroup dead exports by filePath to avoid O(F*D) nested scan
-  const deadByFile = new Map<string, Array<{ name: string; line: number }>>();
-  for (const e of deadExports) {
-    let arr = deadByFile.get(e.filePath);
-    if (!arr) {
-      arr = [];
-      deadByFile.set(e.filePath, arr);
-    }
-    arr.push({ name: e.name, line: e.line });
-  }
-
-  return flags.map(flag => {
-    if (flag.guardLineStart == null || flag.guardLineEnd == null) return flag;
-    const fileDeads = deadByFile.get(flag.filePath);
-    if (!fileDeads) return flag;
-    const start = flag.guardLineStart ?? 0;
-    const end = flag.guardLineEnd ?? Infinity;
-    const guarded = fileDeads
-      .filter(e => e.line >= start && e.line <= end)
-      .map(e => e.name);
-    return guarded.length > 0 ? { ...flag, guardedDeadExports: guarded } : flag;
-  });
-}
-
-function walkDir(dir: string, fn: (filePath: string) => void): void {
-  let dirents: import('fs').Dirent[];
-  try { dirents = readdirSync(dir, { withFileTypes: true }); } catch { return; }
-  for (const dirent of dirents) {
-    const entry = dirent.name;
-    if (entry === 'node_modules' || entry === '.git' || entry === 'dist' || entry === 'build') continue;
-    // Never follow symlinks — avoids infinite recursion on a symlink pointing to
-    // an ancestor directory, and avoids indexing a symlinked external tree as if
-    // it were part of the repo. Matches scan.ts's walk().
-    if (dirent.isSymbolicLink()) continue;
-    const full = join(dir, entry);
-    let st;
-    try { st = lstatSync(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 {
-  // Single pass over flags instead of 7 separate filter/map passes
-  const byKind: Record<FlagKind, number> = { EnvironmentVariable: 0, SdkCall: 0, ConfigObject: 0 };
-  const byConfidence: Record<FlagConfidence, number> = { High: 0, Medium: 0, Low: 0 };
-  const flagNames = new Set<string>();
-  const filePaths = new Set<string>();
-  let deadCodeOverlaps = 0;
-
-  for (const f of flags) {
-    byKind[f.kind]++;
-    byConfidence[f.confidence]++;
-    flagNames.add(f.flagName);
-    filePaths.add(f.filePath);
-    if ((f.guardedDeadExports?.length ?? 0) > 0) deadCodeOverlaps++;
-  }
-
-  return {
-    totalFlags: flags.length,
-    byKind,
-    byConfidence,
-    uniqueFlagNames: flagNames.size,
-    filesWithFlags: filePaths.size,
-    deadCodeOverlaps,
-  };
-}