@monoes/monograph 1.0.0 → 1.2.0

package/src/analysis/scripts.ts

@@ -0,0 +1,95 @@
+// Analyzes npm scripts fields and CI config files to derive additional
+// entry points for dead-code analysis.
+
+export interface ScriptCommand {
+  binary: string;
+  args: string[];
+  sourceScript: string;
+}
+
+export interface ScriptAnalysis {
+  entryPatterns: string[];
+  commands: ScriptCommand[];
+  binToPackage: Map<string, string>;
+}
+
+export interface CiAnalysis {
+  entryPatterns: string[];
+  detectedRunners: string[];
+}
+
+const PACKAGE_MANAGER_PREFIXES = ['npx', 'pnpm', 'yarn', 'bunx', 'nx', 'turbo'];
+const SHELL_OPERATORS = /&&|\|\||;|\|/;
+
+export function splitShellOperators(script: string): string[] {
+  return script.split(SHELL_OPERATORS).map(s => s.trim()).filter(Boolean);
+}
+
+export function skipInitialWrappers(parts: string[]): string[] {
+  const skip = new Set(['env', 'cross-env', 'dotenv', 'run-s', 'run-p', 'concurrently']);
+  let i = 0;
+  while (i < parts.length && (skip.has(parts[i]) || parts[i].includes('='))) i++;
+  return parts.slice(i);
+}
+
+export function parseScriptCommand(raw: string): ScriptCommand | null {
+  const segments = splitShellOperators(raw);
+  const first = segments[0];
+  if (!first) return null;
+
+  const tokens = first.split(/\s+/).filter(Boolean);
+  const adjusted = skipInitialWrappers(tokens);
+  if (!adjusted.length) return null;
+
+  let binary = adjusted[0];
+  let args = adjusted.slice(1);
+
+  if (PACKAGE_MANAGER_PREFIXES.includes(binary) && args.length) {
+    binary = args[0];
+    args = args.slice(1);
+  }
+
+  return { binary, args, sourceScript: raw };
+}
+
+export function filterProductionScripts(scripts: Record<string, string>): Record<string, string> {
+  const devKeys = /^(dev|test|lint|type-check|watch|storybook|e2e)/;
+  const result: Record<string, string> = {};
+  for (const [k, v] of Object.entries(scripts)) {
+    if (!devKeys.test(k)) result[k] = v;
+  }
+  return result;
+}
+
+export function analyzeScripts(
+  scripts: Record<string, string>,
+  _root?: string,
+): ScriptAnalysis {
+  const production = filterProductionScripts(scripts);
+  const commands: ScriptCommand[] = [];
+  const entryPatterns: string[] = [];
+
+  for (const raw of Object.values(production)) {
+    const cmd = parseScriptCommand(raw);
+    if (cmd) commands.push(cmd);
+  }
+
+  return { entryPatterns, commands, binToPackage: new Map() };
+}
+
+export function buildBinToPackageMap(packageJson: Record<string, unknown>): Map<string, string> {
+  const map = new Map<string, string>();
+  const name = packageJson['name'] as string | undefined;
+  if (!name) return map;
+  const bin = packageJson['bin'];
+  if (typeof bin === 'string') {
+    map.set(name, name);
+  } else if (typeof bin === 'object' && bin !== null) {
+    for (const k of Object.keys(bin as object)) map.set(k, name);
+  }
+  return map;
+}
+
+export function analyzeCiFiles(_root: string): CiAnalysis {
+  return { entryPatterns: [], detectedRunners: [] };
+}

package/src/analysis/shape-extractor.ts

@@ -0,0 +1,202 @@
+// ── Types ──────────────────────────────────────────────────────────────────────
+
+export interface RouteShape {
+  returnedKeys: string[];
+  accessedKeys: string[];
+  mismatches: string[];
+  extra: string[];
+  status: 'MATCH' | 'MISMATCH' | 'UNKNOWN';
+}
+
+// ── Internal helpers ──────────────────────────────────────────────────────────
+
+/**
+ * Given source starting at the opening `{`, walk char-by-char tracking brace
+ * depth and return the substring of the outermost object literal (excluding
+ * the surrounding braces).
+ */
+function extractObjectBody(source: string, start: number): string {
+  let depth = 0;
+  let bodyStart = -1;
+
+  for (let i = start; i < source.length; i++) {
+    const ch = source[i];
+    if (ch === '{') {
+      depth++;
+      if (depth === 1) bodyStart = i + 1;
+    } else if (ch === '}') {
+      depth--;
+      if (depth === 0) {
+        return source.slice(bodyStart, i);
+      }
+    }
+  }
+  return '';
+}
+
+/**
+ * Split an object body string by top-level commas (ignoring commas nested
+ * inside `{}`, `[]`, or `()`).
+ */
+function splitTopLevel(body: string): string[] {
+  const parts: string[] = [];
+  let depth = 0;
+  let start = 0;
+
+  for (let i = 0; i < body.length; i++) {
+    const ch = body[i];
+    if (ch === '{' || ch === '[' || ch === '(') depth++;
+    else if (ch === '}' || ch === ']' || ch === ')') depth--;
+    else if (ch === ',' && depth === 0) {
+      parts.push(body.slice(start, i));
+      start = i + 1;
+    }
+  }
+  const last = body.slice(start).trim();
+  if (last.length > 0) parts.push(last);
+  return parts;
+}
+
+/**
+ * Extract the property key from a single key–value segment such as:
+ *   `  id: 123`       → 'id'
+ *   `  name: ...`     → 'name'
+ *   `  ...spread`     → null  (spread, skip)
+ *   `  shorthand`     → 'shorthand'  (computed or shorthand)
+ */
+function segmentToKey(segment: string): string | null {
+  const trimmed = segment.trim();
+  if (trimmed.startsWith('...')) return null; // spread
+  if (trimmed.startsWith('[')) return null;   // computed key
+  const colonIdx = trimmed.indexOf(':');
+  if (colonIdx > 0) {
+    const key = trimmed.slice(0, colonIdx).trim();
+    if (/^\w+$/.test(key)) return key;
+    return null;
+  }
+  // shorthand property
+  if (/^\w+$/.test(trimmed)) return trimmed;
+  return null;
+}
+
+// ── Public API ────────────────────────────────────────────────────────────────
+
+/**
+ * Scan source code for patterns that indicate JSON response keys:
+ *   `.json({ key1: ..., key2: ... })`
+ *   `NextResponse.json({ key: ... })`
+ *   `return { key1: ..., key2: ... }`
+ *
+ * Returns unique keys sorted alphabetically. Returns [] if no patterns found.
+ */
+export function extractHandlerReturnKeys(source: string): string[] {
+  const keys = new Set<string>();
+
+  // Anchors to look for before an opening brace
+  const anchors = [
+    /\.json\s*\(\s*(?=\{)/g,
+    /NextResponse\.json\s*\(\s*(?=\{)/g,
+    /return\s+(?=\{)/g,
+  ];
+
+  for (const anchorRe of anchors) {
+    let match: RegExpExecArray | null;
+    anchorRe.lastIndex = 0;
+    while ((match = anchorRe.exec(source)) !== null) {
+      // Find the opening brace starting from end of the match
+      const braceIdx = source.indexOf('{', match.index + match[0].length - 1);
+      if (braceIdx === -1) continue;
+
+      const body = extractObjectBody(source, braceIdx);
+      const segments = splitTopLevel(body);
+      for (const seg of segments) {
+        const key = segmentToKey(seg);
+        if (key) keys.add(key);
+      }
+    }
+  }
+
+  return Array.from(keys).sort();
+}
+
+/**
+ * Scan source code for property accesses on known response variable names:
+ *   `data.key`
+ *   `const { key1, key2 } = data`
+ *
+ * `varNames` defaults to common response variable names if not supplied.
+ * Returns unique keys sorted alphabetically.
+ */
+export function extractAccessedKeys(
+  source: string,
+  varNames: string[] = ['data', 'result', 'response', 'res', 'json', 'body'],
+): string[] {
+  const keys = new Set<string>();
+
+  for (const varName of varNames) {
+    const escaped = varName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+    // Dot access: varName.key (not followed by `(` — exclude method calls)
+    const dotRe = new RegExp(`\\b${escaped}\\.(\\w+)(?!\\s*\\()`, 'g');
+    let m: RegExpExecArray | null;
+    while ((m = dotRe.exec(source)) !== null) {
+      keys.add(m[1]);
+    }
+
+    // Destructuring: const { key1, key2 } = varName
+    // or `const { key1: alias, key2 } = varName`
+    const destructRe = new RegExp(
+      `\\{([^}]*)\\}\\s*=\\s*${escaped}\\b`,
+      'g',
+    );
+    while ((m = destructRe.exec(source)) !== null) {
+      const inner = m[1];
+      for (const part of inner.split(',')) {
+        const trimmed = part.trim();
+        if (!trimmed || trimmed.startsWith('...')) continue;
+        // Handle `key: alias` — take the key (left side)
+        const colonIdx = trimmed.indexOf(':');
+        const key = colonIdx >= 0 ? trimmed.slice(0, colonIdx).trim() : trimmed;
+        if (/^\w+$/.test(key)) keys.add(key);
+      }
+    }
+  }
+
+  return Array.from(keys).sort();
+}
+
+/**
+ * Compare what a handler returns vs what consumers access.
+ *
+ * - MATCH: all accessed keys are present in returned keys
+ * - MISMATCH: one or more accessed keys are missing from returned keys
+ * - UNKNOWN: either set is empty
+ */
+export function compareShapes(
+  returnedKeys: string[],
+  accessedKeys: string[],
+): RouteShape {
+  if (returnedKeys.length === 0 || accessedKeys.length === 0) {
+    return {
+      returnedKeys,
+      accessedKeys,
+      mismatches: [],
+      extra: [],
+      status: 'UNKNOWN',
+    };
+  }
+
+  const returnedSet = new Set(returnedKeys);
+  const accessedSet = new Set(accessedKeys);
+
+  const mismatches = accessedKeys.filter((k) => !returnedSet.has(k));
+  const extra = returnedKeys.filter((k) => !accessedSet.has(k));
+
+  return {
+    returnedKeys,
+    accessedKeys,
+    mismatches,
+    extra,
+    status: mismatches.length === 0 ? 'MATCH' : 'MISMATCH',
+  };
+}

package/src/analysis/since-duration.ts

@@ -0,0 +1,42 @@
+export interface SinceDuration {
+  gitAfter: string;
+  display: string;
+}
+
+function isIsoDate(s: string): boolean {
+  return /^\d{4}-\d{2}-\d{2}$/.test(s);
+}
+
+function plural(n: number, word: string): string {
+  return `${n} ${word}${n !== 1 ? 's' : ''}`;
+}
+
+export function parseSince(input: string): SinceDuration {
+  if (isIsoDate(input)) return { gitAfter: input, display: input };
+  const m = input.match(/^(\d+)([a-zA-Z]+)$/);
+  if (!m) throw new Error(`--since requires a unit suffix (e.g., 6m, 90d, 1y), got: ${input}`);
+  const num = parseInt(m[1], 10);
+  if (num === 0) throw new Error('--since duration must be greater than 0');
+  const unit = m[2].toLowerCase();
+  if (unit === 'd' || unit === 'day' || unit === 'days') {
+    const label = plural(num, 'day');
+    return { gitAfter: `${label} ago`, display: label };
+  }
+  if (unit === 'w' || unit === 'week' || unit === 'weeks') {
+    const label = plural(num, 'week');
+    return { gitAfter: `${label} ago`, display: label };
+  }
+  if (unit === 'm' || unit === 'month' || unit === 'months') {
+    const label = plural(num, 'month');
+    return { gitAfter: `${label} ago`, display: label };
+  }
+  if (unit === 'y' || unit === 'year' || unit === 'years') {
+    const label = plural(num, 'year');
+    return { gitAfter: `${label} ago`, display: label };
+  }
+  throw new Error(`unknown duration unit '${unit}' in --since. Use d/w/m/y (e.g., 6m, 90d, 1y)`);
+}
+
+export function sinceDurationToGitFlag(s: SinceDuration): string {
+  return `--after="${s.gitAfter}"`;
+}

package/src/analysis/suppression-context.ts

@@ -0,0 +1,95 @@
+export type IssueKind =
+  | '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 Suppression {
+  line: number;
+  commentLine: number;
+  kind: IssueKind | null;
+}
+
+export interface StaleSuppression {
+  path: string;
+  line: number;
+  col: number;
+  isFileLevel: boolean;
+  issueKind: IssueKind | null;
+}
+
+const NON_CORE_KINDS: Set<IssueKind> = new Set([
+  'complexity', 'coverage-gaps', 'feature-flag', 'code-duplication',
+  'unused-dependency', 'unused-dev-dependency', 'unlisted-dependency',
+  'type-only-dependency', 'test-only-dependency', 'stale-suppression',
+]);
+
+interface FileSuppressionRecord {
+  suppressions: Suppression[];
+  used: boolean[];
+}
+
+export class SuppressionContext {
+  private readonly byFile: Map<string, FileSuppressionRecord>;
+
+  constructor(modules: Array<{ filePath: string; suppressions: Suppression[] }>) {
+    this.byFile = new Map();
+    for (const m of modules) {
+      if (m.suppressions.length > 0) {
+        this.byFile.set(m.filePath, { suppressions: m.suppressions, used: new Array(m.suppressions.length).fill(false) });
+      }
+    }
+  }
+
+  isSuppressed(filePath: string, line: number, kind: IssueKind): boolean {
+    const rec = this.byFile.get(filePath);
+    if (!rec) return false;
+    for (let i = 0; i < rec.suppressions.length; i++) {
+      const s = rec.suppressions[i];
+      const matched = s.line === 0 ? (s.kind === null || s.kind === kind) : (s.line === line && (s.kind === null || s.kind === kind));
+      if (matched) { rec.used[i] = true; return true; }
+    }
+    return false;
+  }
+
+  isFileSuppressed(filePath: string, kind: IssueKind): boolean {
+    const rec = this.byFile.get(filePath);
+    if (!rec) return false;
+    for (let i = 0; i < rec.suppressions.length; i++) {
+      const s = rec.suppressions[i];
+      if (s.line === 0 && (s.kind === null || s.kind === kind)) { rec.used[i] = true; return true; }
+    }
+    return false;
+  }
+
+  get(filePath: string): Suppression[] | undefined { return this.byFile.get(filePath)?.suppressions; }
+
+  usedCount(): number {
+    let n = 0;
+    for (const rec of this.byFile.values()) n += rec.used.filter(Boolean).length;
+    return n;
+  }
+
+  findStale(): StaleSuppression[] {
+    const stale: StaleSuppression[] = [];
+    for (const [filePath, rec] of this.byFile) {
+      for (let i = 0; i < rec.suppressions.length; i++) {
+        if (rec.used[i]) continue;
+        const s = rec.suppressions[i];
+        if (s.kind !== null && NON_CORE_KINDS.has(s.kind)) continue;
+        stale.push({ path: filePath, line: s.commentLine, col: 0, isFileLevel: s.line === 0, issueKind: s.kind });
+      }
+    }
+    return stale;
+  }
+}
+
+export function isSuppressed(suppressions: Suppression[], line: number, kind: IssueKind): boolean {
+  return suppressions.some(s => s.line === 0 ? (s.kind === null || s.kind === kind) : (s.line === line && (s.kind === null || s.kind === kind)));
+}
+
+export function isFileSuppressed(suppressions: Suppression[], kind: IssueKind): boolean {
+  return suppressions.some(s => s.line === 0 && (s.kind === null || s.kind === kind));
+}

package/src/analysis/suppressions.ts

@@ -0,0 +1,77 @@
+export type SuppressionKind =
+  | 'unused-export'
+  | 'unused-file'
+  | 'unused-member'
+  | 'complexity'
+  | 'coverage-gaps'
+  | 'code-duplication'
+  | 'dead-code'
+  | 'boundary'
+  | 'codeowners';
+
+export const NON_CORE_KINDS: SuppressionKind[] = [
+  'complexity',
+  'coverage-gaps',
+  'code-duplication',
+];
+
+export interface Suppression {
+  path: string;
+  line: number;
+  col: number;
+  kind: SuppressionKind;
+  comment?: string;
+}
+
+export interface StaleSuppression extends Suppression {
+  description(): string;
+  explanation(): string;
+}
+
+export interface SuppressionContext {
+  suppressions: Suppression[];
+  consumed: Set<string>; // key: `${path}:${line}:${kind}`
+}
+
+export function createSuppressionContext(suppressions: Suppression[]): SuppressionContext {
+  return {
+    suppressions: [...suppressions],
+    consumed: new Set<string>(),
+  };
+}
+
+export function suppressionKey(s: Suppression): string {
+  return `${s.path}:${s.line}:${s.kind}`;
+}
+
+export function markConsumed(
+  ctx: SuppressionContext,
+  path: string,
+  line: number,
+  kind: SuppressionKind,
+): void {
+  ctx.consumed.add(`${path}:${line}:${kind}`);
+}
+
+export function findStale(ctx: SuppressionContext): StaleSuppression[] {
+  return ctx.suppressions
+    .filter((s) => {
+      const key = suppressionKey(s);
+      const isConsumed = ctx.consumed.has(key);
+      const isNonCore = NON_CORE_KINDS.includes(s.kind);
+      // Keep (return as stale) if NOT consumed AND NOT a non-core kind
+      return !isConsumed && !isNonCore;
+    })
+    .map((s): StaleSuppression => {
+      return {
+        ...s,
+        description(): string {
+          return `Stale suppression of kind "${s.kind}" at ${s.path}:${s.line}:${s.col}`;
+        },
+        explanation(): string {
+          const comment = s.comment ? ` (comment: "${s.comment}")` : '';
+          return `The suppression for "${s.kind}" at line ${s.line} in "${s.path}" was never matched by an actual issue${comment}. It can be safely removed.`;
+        },
+      };
+    });
+}

package/src/analysis/surprise-scorer.ts

@@ -0,0 +1,74 @@
+// ── Types ──────────────────────────────────────────────────────────────────────
+
+export interface ScoredNode {
+  id: string;
+  degree: number;           // total in+out edges
+  avgDegree: number;        // average degree across the graph
+  crossCommunityEdges: number;  // edges crossing community boundaries
+  totalEdges: number;       // total edges (for ratio)
+  stalenessScore: number;   // 0=fresh, 1=stale
+  communityId?: string;
+}
+
+export interface SurpriseOptions {
+  degreeWeight?: number;        // default 0.4
+  crossCommunityWeight?: number; // default 0.4
+  stalenessWeight?: number;     // default 0.2
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.max(min, Math.min(max, value));
+}
+
+// ── Core function ─────────────────────────────────────────────────────────────
+
+/**
+ * Compute a multi-factor surprise score for a single node.
+ *
+ * The score combines:
+ * - Degree anomaly: how far the node's degree deviates from the graph average
+ * - Cross-community ratio: what fraction of edges cross community boundaries
+ * - Staleness: how stale the node is (from git-based staleness scoring)
+ *
+ * @returns A value in [0, 1] where higher means more surprising / worth investigating.
+ */
+export function computeSurpriseScore(node: ScoredNode, opts: SurpriseOptions = {}): number {
+  const degreeWeight = opts.degreeWeight ?? 0.4;
+  const crossCommunityWeight = opts.crossCommunityWeight ?? 0.4;
+  const stalenessWeight = opts.stalenessWeight ?? 0.2;
+
+  // Factor 1: degree anomaly — nodes with unusually high or low connectivity
+  const degreeAnomaly = clamp(
+    Math.abs(node.degree - node.avgDegree) / (node.avgDegree + 1),
+    0,
+    1,
+  );
+
+  // Factor 2: cross-community ratio — edges that bridge different communities
+  const crossCommunityRatio = node.totalEdges > 0
+    ? node.crossCommunityEdges / node.totalEdges
+    : 0;
+
+  // Factor 3: staleness — stale nodes are surprising because they may be outdated
+  const staleness = clamp(node.stalenessScore, 0, 1);
+
+  return degreeWeight * degreeAnomaly
+    + crossCommunityWeight * crossCommunityRatio
+    + stalenessWeight * staleness;
+}
+
+// ── Batch helper ──────────────────────────────────────────────────────────────
+
+/**
+ * Score a collection of nodes and return them sorted by surprise score descending.
+ */
+export function scoreNodes(
+  nodes: ScoredNode[],
+  opts?: SurpriseOptions,
+): Array<ScoredNode & { surpriseScore: number }> {
+  return nodes
+    .map(node => ({ ...node, surpriseScore: computeSurpriseScore(node, opts) }))
+    .sort((a, b) => b.surpriseScore - a.surpriseScore);
+}