@monoes/monograph 1.5.5 → 1.5.7

package/src/analysis/project-state.ts

@@ -1,95 +0,0 @@
-export interface ProjectFile {
-  fileId: number;
-  path: string;
-  canonicalPath?: string;
-  sizeBytes?: number;
-}
-
-export interface WorkspaceEntry {
-  root: string;
-  name?: string;
-  packageJson?: Record<string, unknown>;
-}
-
-export interface ProjectState {
-  files: ProjectFile[];
-  pathToId: Map<string, number>;
-  /** O(1) lookup by numeric fileId */
-  idToFile: Map<number, ProjectFile>;
-  workspaces: WorkspaceEntry[];
-}
-
-export function makeProjectState(files: ProjectFile[], workspaces: WorkspaceEntry[]): ProjectState {
-  // Build both lookup maps in a single pass to avoid intermediate arrays
-  const pathToId = new Map<string, number>();
-  const idToFile = new Map<number, ProjectFile>();
-  for (const f of files) {
-    pathToId.set(f.path, f.fileId);
-    idToFile.set(f.fileId, f);
-  }
-  return { files, pathToId, idToFile, workspaces };
-}
-
-export function fileById(state: ProjectState, fileId: number): ProjectFile | undefined {
-  // O(1) lookup via idToFile map instead of O(N) linear scan
-  return state.idToFile.get(fileId);
-}
-
-export function idForPath(state: ProjectState, filePath: string): number | undefined {
-  return state.pathToId.get(filePath);
-}
-
-export function workspaceForFile(state: ProjectState, fileId: number): WorkspaceEntry | undefined {
-  const file = fileById(state, fileId);
-  if (!file) return undefined;
-  const normalized = file.path.replace(/\\/g, '/');
-  let bestMatch: WorkspaceEntry | undefined;
-  let bestLen = 0;
-  for (const ws of state.workspaces) {
-    const wsPath = ws.root.replace(/\\/g, '/');
-    if (normalized.startsWith(wsPath + '/') || normalized === wsPath) {
-      if (wsPath.length > bestLen) {
-        bestLen = wsPath.length;
-        bestMatch = ws;
-      }
-    }
-  }
-  return bestMatch;
-}
-
-export function filesInWorkspace(state: ProjectState, workspace: WorkspaceEntry): ProjectFile[] {
-  const wsPath = workspace.root.replace(/\\/g, '/');
-  return state.files.filter(f => {
-    const fp = f.path.replace(/\\/g, '/');
-    return fp.startsWith(wsPath + '/') || fp === wsPath;
-  });
-}
-
-export class PackageResolver {
-  private entries: Array<{ root: string; name: string }>;
-
-  constructor(workspaces: WorkspaceEntry[]) {
-    // Combine filter + map into a single for-of loop to avoid 2 intermediate arrays
-    const named: Array<{ root: string; name: string }> = [];
-    for (const w of workspaces) {
-      if (w.name) named.push({ root: w.root, name: w.name });
-    }
-    named.sort((a, b) => b.root.length - a.root.length);
-    this.entries = named;
-  }
-
-  resolvePackage(filePath: string): string | undefined {
-    const normalized = filePath.replace(/\\/g, '/');
-    for (const entry of this.entries) {
-      const rootNorm = entry.root.replace(/\\/g, '/');
-      if (normalized.startsWith(rootNorm + '/') || normalized === rootNorm) {
-        return entry.name;
-      }
-    }
-    return undefined;
-  }
-
-  resolveRoot(packageName: string): string | undefined {
-    return this.entries.find(e => e.name === packageName)?.root;
-  }
-}

package/src/analysis/regression-config.ts

@@ -1,36 +0,0 @@
-import { readFileSync, writeFileSync } from 'fs';
-
-export interface Tolerance {
-  type: 'absolute' | 'percentage';
-  value: number;
-}
-
-export function parseTolerance(s: string): Tolerance {
-  const pct = s.match(/^(\d+(?:\.\d+)?)%$/);
-  if (pct) return { type: 'percentage', value: parseFloat(pct[1]!) };
-  const abs = s.match(/^(\d+)$/);
-  if (abs) return { type: 'absolute', value: parseInt(abs[1]!, 10) };
-  return { type: 'absolute', value: 0 };
-}
-
-export function toleranceExceeded(tol: Tolerance, baseline: number, current: number): boolean {
-  const delta = current - baseline;
-  if (delta <= 0) return false;
-  if (tol.type === 'absolute') return delta > tol.value;
-  return delta / Math.max(1, baseline) * 100 > tol.value;
-}
-
-export function saveBaselineToConfig(configPath: string, counts: Record<string, number>): void {
-  let content: string;
-  try { content = readFileSync(configPath, 'utf8'); }
-  catch { content = '{}'; }
-  let parsed: Record<string, unknown>;
-  try { parsed = JSON.parse(stripJsonComments(content)); }
-  catch { parsed = {}; }
-  parsed['regression'] = { ...((parsed['regression'] as Record<string, unknown>) ?? {}), baseline: counts };
-  writeFileSync(configPath, JSON.stringify(parsed, null, 2));
-}
-
-function stripJsonComments(text: string): string {
-  return text.replace(/\/\/[^\n]*/g, '').replace(/\/\*[\s\S]*?\*\//g, '');
-}

package/src/analysis/rule-overrides.ts

@@ -1,81 +0,0 @@
-export interface RuleSet {
-  allow: string[];
-  deny: string[];
-}
-
-export interface RuleOverride {
-  pattern: string;
-  rules: RuleSet;
-}
-
-export function matchesGlob(filePath: string, pattern: string): boolean {
-  // Escape dots
-  let regexStr = pattern.replace(/\./g, '\\.');
-  // Replace **/ with a group that matches any path segments (including none)
-  regexStr = regexStr.replace(/\*\*\//g, '(?:.+/)?');
-  // Replace remaining * with [^/]* to match within a segment only
-  regexStr = regexStr.replace(/\*/g, '[^/]*');
-  // Anchor at end
-  regexStr = regexStr + '$';
-
-  const regex = new RegExp(regexStr);
-  return regex.test(filePath);
-}
-
-export function resolveRulesForFile(filePath: string, overrides: RuleOverride[]): RuleSet | null {
-  for (const override of overrides) {
-    if (matchesGlob(filePath, override.pattern)) {
-      return override.rules;
-    }
-  }
-  return null;
-}
-
-export function applyRules<T extends { filePath?: string | null; ruleCode?: string }>(
-  issues: T[],
-  globalRules: RuleSet,
-  overrides: RuleOverride[],
-): T[] {
-  return issues.filter((issue) => {
-    const filePath = issue.filePath ?? '';
-    const effectiveRules = resolveRulesForFile(filePath, overrides) ?? globalRules;
-
-    const ruleCode = issue.ruleCode;
-    if (ruleCode == null) {
-      // No ruleCode — keep by default
-      return true;
-    }
-
-    // Keep if ruleCode is NOT in allow list
-    return !effectiveRules.allow.includes(ruleCode);
-  });
-}
-
-// ── Round 8: severity helpers ──────────────────────────────────────────────
-
-export type IssueSeverity = 'error' | 'warn' | 'off';
-
-export interface RuleWithSeverity {
-  name: string;
-  severity: IssueSeverity;
-}
-
-/** Returns true if any rule currently set to 'error' has findings in results. */
-export function hasErrorSeverityIssues(
-  rules: RuleWithSeverity[],
-  resultCounts: Record<string, number>,
-): boolean {
-  return rules
-    .filter(r => r.severity === 'error')
-    .some(r => (resultCounts[r.name] ?? 0) > 0);
-}
-
-/** Bulk-upgrade all 'warn' severity rules to 'error' for strict CI gates. */
-export function promoteWarnsToErrors(rules: RuleWithSeverity[]): RuleWithSeverity[] {
-  return rules.map(r => r.severity === 'warn' ? { ...r, severity: 'error' as IssueSeverity } : r);
-}
-
-/** Downgrade all 'error' severity rules to 'warn'. */
-export function demoteErrorsToWarns(rules: RuleWithSeverity[]): RuleWithSeverity[] {
-  return rules.map(r => r.severity === 'error' ? { ...r, severity: 'warn' as IssueSeverity } : r);
-}

package/src/analysis/scripts.ts

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

@@ -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));
-}