@monoes/monograph 1.5.6 → 1.5.8

package/src/analysis/shape-extractor.ts

@@ -1,202 +0,0 @@
-// ── 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

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

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

@@ -1,80 +0,0 @@
-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',
-];
-
-// Set for O(1) membership check in findStale hot path
-const NON_CORE_KINDS_SET = new Set<SuppressionKind>(NON_CORE_KINDS);
-
-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_SET.has(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

@@ -1,74 +0,0 @@
-// ── 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);
-}