@monoes/monograph 1.1.0 → 1.2.0

package/src/duplicates/tokenize/index.ts

@@ -0,0 +1,104 @@
+import type { FileTokens, SourceToken } from '../token-types.js';
+import { emptyTokens } from '../token-types.js';
+import * as path from 'node:path';
+
+const STYLE_EXTS = new Set(['.css', '.scss', '.sass', '.less', '.styl']);
+const SFC_EXTS = new Set(['.vue', '.svelte']);
+const SCRIPT_OPEN_RE = /<script(?:[^>]*lang=["'](?:ts|typescript)["'][^>]*)?\s*>/i;
+const SCRIPT_CLOSE_RE = /<\/script>/i;
+
+export function tokenizeFile(filePath: string, source: string, skipImports: boolean): FileTokens {
+  const ext = path.extname(filePath).toLowerCase();
+  if (STYLE_EXTS.has(ext)) return emptyTokens(source);
+  if (SFC_EXTS.has(ext)) return tokenizeSfc(source, false, skipImports);
+  if (ext === '.astro') return tokenizeAstro(source, false, skipImports);
+  if (ext === '.mdx') return tokenizeMdx(source, false, skipImports);
+  return tokenizeJsTs(filePath, source, false, skipImports);
+}
+
+export function tokenizeFileCrossLanguage(
+  filePath: string,
+  source: string,
+  stripTypes: boolean,
+  skipImports: boolean,
+): FileTokens {
+  const ext = path.extname(filePath).toLowerCase();
+  if (STYLE_EXTS.has(ext)) return emptyTokens(source);
+  if (SFC_EXTS.has(ext)) return tokenizeSfc(source, stripTypes, skipImports);
+  if (ext === '.astro') return tokenizeAstro(source, stripTypes, skipImports);
+  if (ext === '.mdx') return tokenizeMdx(source, stripTypes, skipImports);
+  return tokenizeJsTs(filePath, source, stripTypes, skipImports);
+}
+
+export function tokenizeSfc(source: string, stripTypes: boolean, skipImports: boolean): FileTokens {
+  const scriptMatch = source.match(SCRIPT_OPEN_RE);
+  if (!scriptMatch) return emptyTokens(source);
+  const start = source.indexOf(scriptMatch[0]) + scriptMatch[0].length;
+  const closeMatch = source.slice(start).match(SCRIPT_CLOSE_RE);
+  if (!closeMatch) return emptyTokens(source);
+  const scriptSource = source.slice(start, start + closeMatch.index!);
+  return tokenizeJsTs('component.ts', scriptSource, stripTypes, skipImports);
+}
+
+export function tokenizeAstro(source: string, stripTypes: boolean, skipImports: boolean): FileTokens {
+  const frontmatterEnd = source.indexOf('---', 3);
+  if (!source.startsWith('---') || frontmatterEnd === -1) return emptyTokens(source);
+  const frontmatter = source.slice(3, frontmatterEnd);
+  return tokenizeJsTs('astro.ts', frontmatter, stripTypes, skipImports);
+}
+
+export function tokenizeMdx(source: string, stripTypes: boolean, skipImports: boolean): FileTokens {
+  const lines = source.split('\n');
+  const codeLines = lines.filter(l => l.match(/^(import|export)\s/));
+  return tokenizeJsTs('mdx.ts', codeLines.join('\n'), stripTypes, skipImports);
+}
+
+export function tokenizeJsTs(
+  _filePath: string,
+  source: string,
+  _stripTypes: boolean,
+  skipImports: boolean,
+): FileTokens {
+  const lineCount = (source.match(/\n/g)?.length ?? 0) + 1;
+  const tokens: SourceToken[] = [];
+  const tokenRe = /\/\/[^\n]*|\/\*[\s\S]*?\*\/|"(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'|`(?:[^`\\]|\\.)*`|(\d+(?:\.\d+)?(?:[eE][+-]?\d+)?)|([a-zA-Z_$][a-zA-Z0-9_$]*)|([^\s\w"'`])/g;
+  const KEYWORDS = new Set([
+    'var','let','const','function','return','if','else','for','while','do',
+    'switch','case','break','continue','default','throw','try','catch','finally',
+    'new','delete','typeof','instanceof','in','of','void','this','super',
+    'class','extends','import','export','from','as','async','await','yield',
+    'static','get','set','type','interface','enum','implements','abstract',
+    'declare','readonly','keyof','satisfies','true','false','null',
+  ]);
+  const IMPORT_KWS = new Set(['import','export','from','require']);
+
+  let inImport = false;
+  let match: RegExpExecArray | null;
+  while ((match = tokenRe.exec(source)) !== null) {
+    const raw = match[0];
+    if (raw.startsWith('//') || raw.startsWith('/*')) continue;
+    const pos = match.index;
+    const span = { start: pos, end: pos + raw.length };
+
+    if (match[2]) {
+      const word = match[2];
+      if (word === 'import' || word === 'export') inImport = true;
+      else if (word === ';' || word === '\n') inImport = false;
+      if (skipImports && inImport && IMPORT_KWS.has(word)) continue;
+      if (word === 'true' || word === 'false') {
+        tokens.push({ kind: { kind: 'BooleanLiteral', value: word === 'true' }, span });
+      } else if (word === 'null') {
+        tokens.push({ kind: { kind: 'NullLiteral' }, span });
+      } else if (KEYWORDS.has(word)) {
+        tokens.push({ kind: { kind: 'Keyword', kwType: word.charAt(0).toUpperCase() + word.slice(1) as any }, span });
+      } else {
+        tokens.push({ kind: { kind: 'Identifier', name: word }, span });
+      }
+    } else if (match[1]) {
+      tokens.push({ kind: { kind: 'NumericLiteral' }, span });
+    } else if (raw.startsWith('"') || raw.startsWith("'") || raw.startsWith('`')) {
+      tokens.push({ kind: { kind: raw.startsWith('`') ? 'TemplateLiteral' : 'StringLiteral' }, span });
+    }
+  }
+  return { tokens, source, lineCount };
+}

package/src/error/fallow-error.ts

@@ -0,0 +1,94 @@
+export type FallowErrorKind =
+  | { kind: 'FileReadError'; path: string; cause?: string }
+  | { kind: 'ParseError'; path?: string; message: string }
+  | { kind: 'ResolveError'; specifier: string; fromFile?: string }
+  | { kind: 'ConfigError'; field?: string; message: string }
+  | { kind: 'GitError'; command: string; message: string }
+  | { kind: 'IoError'; message: string };
+
+export interface FallowErrorOptions {
+  code?: string;
+  help?: string;
+  context?: string;
+}
+
+export class FallowError extends Error {
+  readonly errorKind: FallowErrorKind;
+  readonly code?: string;
+  readonly help?: string;
+  readonly context?: string;
+
+  constructor(kind: FallowErrorKind, opts: FallowErrorOptions = {}) {
+    super(FallowError.formatMessage(kind));
+    this.name = 'FallowError';
+    this.errorKind = kind;
+    this.code = opts.code;
+    this.help = opts.help;
+    this.context = opts.context;
+  }
+
+  withHelp(help: string): FallowError {
+    return new FallowError(this.errorKind, { code: this.code, help, context: this.context });
+  }
+
+  withContext(context: string): FallowError {
+    return new FallowError(this.errorKind, { code: this.code, help: this.help, context });
+  }
+
+  withCode(code: string): FallowError {
+    return new FallowError(this.errorKind, { code, help: this.help, context: this.context });
+  }
+
+  format(): string {
+    const parts: string[] = [this.message];
+    if (this.code) parts.unshift(`[${this.code}]`);
+    if (this.context) parts.push(`  Context: ${this.context}`);
+    if (this.help) parts.push(`  Help: ${this.help}`);
+    return parts.join('\n');
+  }
+
+  static formatMessage(kind: FallowErrorKind): string {
+    switch (kind.kind) {
+      case 'FileReadError': return `Failed to read file: ${kind.path}${kind.cause ? ` (${kind.cause})` : ''}`;
+      case 'ParseError': return `Parse error${kind.path ? ` in ${kind.path}` : ''}: ${kind.message}`;
+      case 'ResolveError': return `Cannot resolve '${kind.specifier}'${kind.fromFile ? ` from ${kind.fromFile}` : ''}`;
+      case 'ConfigError': return `Configuration error${kind.field ? ` (${kind.field})` : ''}: ${kind.message}`;
+      case 'GitError': return `Git error running '${kind.command}': ${kind.message}`;
+      case 'IoError': return `I/O error: ${kind.message}`;
+    }
+  }
+
+  static fileRead(filePath: string, cause?: string): FallowError {
+    return new FallowError({ kind: 'FileReadError', path: filePath, cause }, { code: 'E001' });
+  }
+
+  static parse(message: string, filePath?: string): FallowError {
+    return new FallowError({ kind: 'ParseError', path: filePath, message }, { code: 'E002' });
+  }
+
+  static resolve(specifier: string, fromFile?: string): FallowError {
+    return new FallowError({ kind: 'ResolveError', specifier, fromFile }, { code: 'E003' });
+  }
+
+  static config(message: string, field?: string): FallowError {
+    return new FallowError({ kind: 'ConfigError', field, message }, { code: 'E004' });
+  }
+
+  static git(command: string, message: string): FallowError {
+    return new FallowError({ kind: 'GitError', command, message }, { code: 'E005' });
+  }
+
+  static io(message: string): FallowError {
+    return new FallowError({ kind: 'IoError', message }, { code: 'E006' });
+  }
+}
+
+export function isFallowError(err: unknown): err is FallowError {
+  return err instanceof FallowError;
+}
+
+export function formatFallowError(err: unknown): string {
+  if (err instanceof FallowError) return err.format();
+  if (err instanceof Error) return err.message;
+  return String(err);
+}

package/src/error.ts

@@ -0,0 +1,47 @@
+export type OutputFormat = 'text' | 'json' | 'compact';
+
+export interface MonographError {
+  code: string;
+  message: string;
+  details?: string;
+}
+
+export function emitError(message: string, exitCode: number, output: OutputFormat): MonographError {
+  const err: MonographError = { code: `E${exitCode}`, message };
+  if (output === 'json') {
+    process.stderr.write(JSON.stringify({ error: err }) + '\n');
+  } else {
+    process.stderr.write(`Error: ${message}\n`);
+  }
+  return err;
+}
+
+export function formatError(err: MonographError, output: OutputFormat): string {
+  if (output === 'json') return JSON.stringify({ error: err });
+  return `Error [${err.code}]: ${err.message}${err.details ? '\n' + err.details : ''}`;
+}
+
+export class MonographAnalysisError extends Error {
+  constructor(
+    message: string,
+    public readonly code: string,
+    public readonly details?: string,
+  ) {
+    super(message);
+    this.name = 'MonographAnalysisError';
+  }
+}
+
+export class MonographConfigError extends MonographAnalysisError {
+  constructor(message: string, details?: string) {
+    super(message, 'CONFIG_ERROR', details);
+    this.name = 'MonographConfigError';
+  }
+}
+
+export class MonographResolveError extends MonographAnalysisError {
+  constructor(message: string, details?: string) {
+    super(message, 'RESOLVE_ERROR', details);
+    this.name = 'MonographResolveError';
+  }
+}

package/src/export/adjacency-matrix.ts

@@ -0,0 +1,127 @@
+import type { MonographNode, MonographEdge } from '../types.js';
+import type { MonographDb } from '../storage/db.js';
+
+// ── Output types ───────────────────────────────────────────────────────────────
+
+export interface AdjacencyMatrix {
+  /** Ordered node ids (row/column headers). */
+  nodeIds: string[];
+  /** Ordered node names, parallel to nodeIds. */
+  nodeNames: string[];
+  /** n×n matrix where matrix[i][j] = number of edges from nodeIds[i] to nodeIds[j]. */
+  matrix: number[][];
+}
+
+// ── Builder ────────────────────────────────────────────────────────────────────
+
+/**
+ * Build an adjacency matrix from a set of nodes and edges.
+ *
+ * Multi-edges (same source→target pair) are counted, so the matrix
+ * contains edge-counts rather than simple 0/1 booleans.
+ *
+ * @param nodes - The node list (defines row/column order).
+ * @param edges - The edge list.
+ * @returns An AdjacencyMatrix with nodeIds, nodeNames, and the n×n matrix.
+ */
+export function buildAdjacencyMatrix(
+  nodes: MonographNode[],
+  edges: MonographEdge[],
+): AdjacencyMatrix {
+  const nodeIds = nodes.map(n => n.id);
+  const nodeNames = nodes.map(n => n.name);
+  const indexMap = new Map<string, number>(nodeIds.map((id, i) => [id, i]));
+  const n = nodeIds.length;
+
+  if (n > 5000) {
+    throw new Error(
+      `adjacency matrix would be ${n}×${n} (${n * n} cells). ` +
+      'Pass a pre-filtered node list via the nodeIds parameter, or use a different export format.'
+    );
+  }
+
+  const matrix: number[][] = Array.from({ length: n }, () => new Array<number>(n).fill(0));
+
+  for (const edge of edges) {
+    const si = indexMap.get(edge.sourceId);
+    const ti = indexMap.get(edge.targetId);
+    if (si !== undefined && ti !== undefined) {
+      matrix[si][ti]++;
+    }
+  }
+
+  return { nodeIds, nodeNames, matrix };
+}
+
+// ── DB-backed variant ──────────────────────────────────────────────────────────
+
+/**
+ * Build an adjacency matrix directly from a MonographDb.
+ * Optionally restrict to a subset of node ids.
+ */
+export function buildAdjacencyMatrixFromDb(
+  db: MonographDb,
+  nodeIds?: string[],
+): AdjacencyMatrix {
+  let nodeRows: { id: string; name: string }[];
+
+  if (nodeIds && nodeIds.length > 0) {
+    const ph = nodeIds.map(() => '?').join(',');
+    nodeRows = db
+      .prepare(`SELECT id, name FROM nodes WHERE id IN (${ph})`)
+      .all(...nodeIds) as { id: string; name: string }[];
+  } else {
+    nodeRows = db.prepare('SELECT id, name FROM nodes').all() as { id: string; name: string }[];
+  }
+
+  const nodes: MonographNode[] = nodeRows.map(r => ({
+    id: r.id,
+    label: 'Function' as MonographNode['label'], // placeholder; only id/name needed here
+    name: r.name,
+    normLabel: r.name.toLowerCase(),
+    isExported: false,
+  }));
+
+  const nodeIdSet = new Set(nodeRows.map(r => r.id));
+
+  let edgeRows: { source_id: string; target_id: string }[];
+  if (nodeIds && nodeIds.length > 0) {
+    const ph = nodeIds.map(() => '?').join(',');
+    edgeRows = db
+      .prepare(`SELECT source_id, target_id FROM edges WHERE source_id IN (${ph}) AND target_id IN (${ph})`)
+      .all(...nodeIds, ...nodeIds) as { source_id: string; target_id: string }[];
+  } else {
+    edgeRows = db.prepare('SELECT source_id, target_id FROM edges').all() as {
+      source_id: string;
+      target_id: string;
+    }[];
+  }
+
+  const edges: MonographEdge[] = edgeRows
+    .filter(r => nodeIdSet.has(r.source_id) && nodeIdSet.has(r.target_id))
+    .map((r, i) => ({
+      id: `e${i}`,
+      sourceId: r.source_id,
+      targetId: r.target_id,
+      relation: 'REFERENCES' as MonographEdge['relation'],
+      confidence: 'EXTRACTED' as MonographEdge['confidence'],
+      confidenceScore: 1,
+    }));
+
+  return buildAdjacencyMatrix(nodes, edges);
+}
+
+// ── CSV serialiser ─────────────────────────────────────────────────────────────
+
+/**
+ * Serialise an AdjacencyMatrix to a CSV string.
+ * The first row and first column are node names (headers).
+ */
+export function adjacencyMatrixToCsv(am: AdjacencyMatrix): string {
+  const escape = (s: string) => `"${s.replace(/"/g, '""')}"`;
+  const header = ['', ...am.nodeNames.map(escape)].join(',');
+  const rows = am.matrix.map((row, i) =>
+    [escape(am.nodeNames[i]), ...row.map(String)].join(','),
+  );
+  return [header, ...rows].join('\n');
+}

package/src/export/analysis-json.ts

@@ -0,0 +1,87 @@
+// Schema-versioned JSON envelope builders for CLI analysis results.
+
+export const ANALYSIS_JSON_SCHEMA_VERSION = 1;
+
+export interface AnalysisEnvelopeOptions {
+  elapsedMs?: number;
+  entryCount?: number;
+  schemaVersion?: number;
+}
+
+export interface AnalysisResultsEnvelope {
+  schemaVersion: number;
+  kind: 'analysis';
+  elapsedMs: number;
+  entryCount: number;
+  totalIssues: number;
+  results: unknown;
+}
+
+export interface HealthResultsEnvelope {
+  schemaVersion: number;
+  kind: 'health';
+  elapsedMs: number;
+  totalFindings: number;
+  includesExplanations: boolean;
+  results: unknown;
+}
+
+export interface DuplicationResultsEnvelope {
+  schemaVersion: number;
+  kind: 'duplication';
+  elapsedMs: number;
+  cloneGroups: number;
+  includesExplanations: boolean;
+  results: unknown;
+}
+
+export function buildAnalysisResultsEnvelope(
+  results: unknown,
+  totalIssues: number,
+  opts: AnalysisEnvelopeOptions = {},
+): AnalysisResultsEnvelope {
+  return {
+    schemaVersion: opts.schemaVersion ?? ANALYSIS_JSON_SCHEMA_VERSION,
+    kind: 'analysis',
+    elapsedMs: opts.elapsedMs ?? 0,
+    entryCount: opts.entryCount ?? 0,
+    totalIssues,
+    results,
+  };
+}
+
+export function buildHealthResultsEnvelope(
+  results: unknown,
+  totalFindings: number,
+  opts: AnalysisEnvelopeOptions & { includesExplanations?: boolean } = {},
+): HealthResultsEnvelope {
+  return {
+    schemaVersion: opts.schemaVersion ?? ANALYSIS_JSON_SCHEMA_VERSION,
+    kind: 'health',
+    elapsedMs: opts.elapsedMs ?? 0,
+    totalFindings,
+    includesExplanations: opts.includesExplanations ?? false,
+    results,
+  };
+}
+
+export function buildDuplicationResultsEnvelope(
+  results: unknown,
+  cloneGroups: number,
+  opts: AnalysisEnvelopeOptions & { includesExplanations?: boolean } = {},
+): DuplicationResultsEnvelope {
+  return {
+    schemaVersion: opts.schemaVersion ?? ANALYSIS_JSON_SCHEMA_VERSION,
+    kind: 'duplication',
+    elapsedMs: opts.elapsedMs ?? 0,
+    cloneGroups,
+    includesExplanations: opts.includesExplanations ?? false,
+    results,
+  };
+}
+
+export function stripRootPrefix(obj: unknown, rootPrefix: string): unknown {
+  const json = JSON.stringify(obj);
+  const escaped = rootPrefix.replace(/[/\\]/g, s => `\\${s}`);
+  return JSON.parse(json.replace(new RegExp(escaped, 'g'), ''));
+}

package/src/export/badge.ts

@@ -0,0 +1,105 @@
+export interface BadgeOptions {
+  label?: string;      // left label text (default: 'monograph')
+  value: string;       // right value text (e.g. 'A' or '87/100')
+  color?: string;      // hex color (auto-determined from grade if omitted)
+  uniqueId?: string;   // SVG element ID prefix (default: 'mg')
+}
+
+/** Map a letter grade to a shield-style hex color (without leading #). */
+export function gradeToColor(grade: string): string {
+  switch (grade.trim().toUpperCase()) {
+    case 'A': return '4c1';
+    case 'B': return '97ca00';
+    case 'C': return 'dfb317';
+    case 'D': return 'fe7d37';
+    case 'F': return 'e05d44';
+    default:  return '9f9f9f';
+  }
+}
+
+/** Approximate text width using Verdana 11px metrics: ~6.5px per char + 10px padding. */
+function textWidth(text: string): number {
+  return Math.round(text.length * 6.5 + 10);
+}
+
+/**
+ * Generate a self-contained shields.io-style SVG health-grade badge.
+ * Returns the SVG string; callers can write it to a file or embed it inline.
+ */
+export function generateBadge(options: BadgeOptions): string {
+  const label = options.label ?? 'monograph';
+  const { value } = options;
+  const id = options.uniqueId ?? 'mg';
+
+  // Determine color: caller-supplied (strip leading #) or derived from grade
+  let colorHex: string;
+  if (options.color) {
+    colorHex = options.color.replace(/^#/, '');
+  } else {
+    colorHex = gradeToColor(value);
+  }
+
+  const labelW = textWidth(label);
+  const valueW = textWidth(value);
+  const totalW = labelW + valueW;
+
+  // X centres for text (SVG font-size="110" means 11px in a 10x-scaled coordinate space)
+  const lx = Math.round(labelW / 2);
+  const rx = labelW + Math.round(valueW / 2);
+
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${totalW}" height="20">
+  <linearGradient id="${id}-lg" x2="0" y2="100%">
+    <stop offset="0" stop-color="#bbb" stop-opacity=".1"/>
+    <stop offset="1" stop-opacity=".1"/>
+  </linearGradient>
+  <rect width="${totalW}" height="20" rx="3" fill="#555"/>
+  <rect x="${labelW}" width="${valueW}" height="20" rx="3" fill="#${colorHex}"/>
+  <rect width="${totalW}" height="20" rx="3" fill="url(#${id}-lg)"/>
+  <g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" font-size="110">
+    <text x="${lx * 10}" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="${(labelW - 10) * 10}">${label}</text>
+    <text x="${lx * 10}" y="140" transform="scale(.1)" textLength="${(labelW - 10) * 10}">${label}</text>
+    <text x="${rx * 10}" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="${(valueW - 10) * 10}">${value}</text>
+    <text x="${rx * 10}" y="140" transform="scale(.1)" textLength="${(valueW - 10) * 10}">${value}</text>
+  </g>
+</svg>`;
+}
+
+// ── Round 10: health terminal badge ───────────────────────────────────────────
+
+export type HealthGradeLetter = 'A' | 'B' | 'C' | 'D' | 'F';
+
+export interface HealthBadgeOptions {
+  grade: HealthGradeLetter;
+  score: number;
+  label?: string;
+  ansiColors?: boolean;
+}
+
+const GRADE_ANSI_BG: Record<HealthGradeLetter, string> = {
+  A: '\x1b[42m', // green
+  B: '\x1b[32m', // dark green
+  C: '\x1b[43m', // yellow
+  D: '\x1b[33m', // dark yellow
+  F: '\x1b[41m', // red
+};
+
+const ANSI_RESET = '\x1b[0m';
+const ANSI_BOLD = '\x1b[1m';
+
+export function renderHealthTerminalBadge(opts: HealthBadgeOptions): string {
+  const label = opts.label ?? 'health';
+  const score = Math.round(opts.score);
+  if (!opts.ansiColors) {
+    return `[${label}: ${opts.grade} (${score}/100)]`;
+  }
+  const bg = GRADE_ANSI_BG[opts.grade];
+  return `${ANSI_BOLD}${bg} ${label.toUpperCase()}: ${opts.grade} (${score}/100) ${ANSI_RESET}`;
+}
+
+export function healthScoreToGrade(score: number): HealthGradeLetter {
+  if (score >= 90) return 'A';
+  if (score >= 75) return 'B';
+  if (score >= 60) return 'C';
+  if (score >= 45) return 'D';
+  return 'F';
+}