@monoes/monograph 1.1.0 → 1.2.1

package/src/duplicates/detect/ranking.ts

@@ -0,0 +1,16 @@
+export function rankReduce(tokens: number[]): { ranked: number[]; maxRank: number } {
+  const hashToRank = new Map<number, number>();
+  let nextRank = 0;
+
+  const ranked = tokens.map((token) => {
+    let rank = hashToRank.get(token);
+    if (rank === undefined) {
+      rank = nextRank++;
+      hashToRank.set(token, rank);
+    }
+    return rank;
+  });
+
+  const maxRank = nextRank === 0 ? 0 : nextRank - 1;
+  return { ranked, maxRank };
+}

package/src/duplicates/detect/statistics.ts

@@ -0,0 +1,69 @@
+import type { RawGroup } from './extraction.js';
+
+export interface PipelineDuplicationStats {
+  totalFiles: number;
+  filesWithClones: number;
+  totalTokens: number;
+  duplicatedTokens: number;
+  totalLines: number;
+  duplicatedLines: number;
+  cloneGroups: number;
+  cloneInstances: number;
+  duplicationPct: number;
+}
+
+export function computePipelineStats(
+  groups: RawGroup[],
+  allFileIds: number[],
+  totalTokens: number,
+  totalLines: number,
+  fileLineCount: (fileId: number, offset: number, length: number) => number,
+): PipelineDuplicationStats {
+  const filesWithClones = new Set<number>();
+  const fileDupLines = new Map<number, Set<number>>();
+  let duplicatedTokens = 0;
+  let cloneInstances = 0;
+
+  for (const group of groups) {
+    for (const inst of group.instances) {
+      filesWithClones.add(inst.fileId);
+      cloneInstances++;
+
+      let lineSet = fileDupLines.get(inst.fileId);
+      if (!lineSet) {
+        lineSet = new Set<number>();
+        fileDupLines.set(inst.fileId, lineSet);
+      }
+
+      const lines = fileLineCount(inst.fileId, inst.offset, group.lcpLength);
+      for (let l = 0; l < lines; l++) {
+        lineSet.add(inst.offset + l);
+      }
+    }
+
+    if (group.instances.length > 1) {
+      duplicatedTokens += group.lcpLength * (group.instances.length - 1);
+    }
+  }
+
+  let duplicatedLines = 0;
+  for (const lineSet of fileDupLines.values()) {
+    duplicatedLines += lineSet.size;
+  }
+
+  duplicatedTokens = Math.min(duplicatedTokens, totalTokens);
+
+  const duplicationPct = totalLines > 0 ? (duplicatedLines / totalLines) * 100 : 0;
+
+  return {
+    totalFiles: allFileIds.length,
+    filesWithClones: filesWithClones.size,
+    totalTokens,
+    duplicatedTokens,
+    totalLines,
+    duplicatedLines,
+    cloneGroups: groups.length,
+    cloneInstances,
+    duplicationPct,
+  };
+}

package/src/duplicates/detect/suffix-array.ts

@@ -0,0 +1,88 @@
+export function buildSuffixArray(text: number[], _maxRank: number): number[] {
+  const n = text.length;
+  if (n === 0) return [];
+
+  const minVal = text.reduce((m, v) => (v < m ? v : m), text[0]);
+
+  let rank = new Int32Array(n);
+  for (let i = 0; i < n; i++) rank[i] = text[i] - minVal;
+
+  let sa = new Int32Array(n);
+  for (let i = 0; i < n; i++) sa[i] = i;
+
+  let tmp = new Int32Array(n);
+  const saTmp = new Int32Array(n);
+  let counts = new Int32Array(0);
+
+  let curMaxRank = 0;
+  for (let i = 0; i < n; i++) {
+    if (rank[i] > curMaxRank) curMaxRank = rank[i];
+  }
+
+  let k = 1;
+
+  while (k < n) {
+    const bucketCount = curMaxRank + 2;
+    if (counts.length < bucketCount + 1) {
+      counts = new Int32Array(bucketCount + 1);
+    } else {
+      counts.fill(0, 0, bucketCount + 1);
+    }
+
+    for (let idx = 0; idx < n; idx++) {
+      const i = sa[idx];
+      const r2 = i + k < n ? rank[i + k] + 1 : 0;
+      counts[r2]++;
+    }
+    let sum = 0;
+    for (let c = 0; c <= bucketCount; c++) {
+      const v = counts[c];
+      counts[c] = sum;
+      sum += v;
+    }
+    for (let idx = 0; idx < n; idx++) {
+      const i = sa[idx];
+      const r2 = i + k < n ? rank[i + k] + 1 : 0;
+      saTmp[counts[r2]++] = i;
+    }
+
+    counts.fill(0, 0, bucketCount + 1);
+    for (let idx = 0; idx < n; idx++) {
+      const i = saTmp[idx];
+      counts[rank[i]]++;
+    }
+    sum = 0;
+    for (let c = 0; c <= bucketCount; c++) {
+      const v = counts[c];
+      counts[c] = sum;
+      sum += v;
+    }
+    for (let idx = 0; idx < n; idx++) {
+      const i = saTmp[idx];
+      sa[counts[rank[i]]++] = i;
+    }
+
+    tmp[sa[0]] = 0;
+    for (let i = 1; i < n; i++) {
+      const prev = sa[i - 1];
+      const curr = sa[i];
+      const rp2 = prev + k < n ? rank[prev + k] : -1;
+      const rc2 = curr + k < n ? rank[curr + k] : -1;
+      const same = rank[prev] === rank[curr] && rp2 === rc2;
+      tmp[curr] = tmp[prev] + (same ? 0 : 1);
+    }
+
+    const newMaxRank = tmp[sa[n - 1]];
+    const swapRank = rank;
+    rank = tmp;
+    tmp = swapRank;
+
+    if (newMaxRank === n - 1) break;
+    curMaxRank = newMaxRank;
+    k *= 2;
+  }
+
+  const result: number[] = new Array(n);
+  for (let i = 0; i < n; i++) result[i] = sa[i];
+  return result;
+}

package/src/duplicates/families.ts

@@ -0,0 +1,95 @@
+export const MODULE_EXTRACTION_THRESHOLD = 50;
+
+export interface RefactoringSuggestion {
+  kind: 'ExtractFunction' | 'ExtractModule' | 'MergeDirectories';
+  description: string;
+  estimatedLines: number;
+  files: string[];
+}
+
+export interface CloneFamily {
+  files: string[];
+  groupCount: number;
+  totalDuplicatedLines: number;
+  suggestions: RefactoringSuggestion[];
+}
+
+interface RawGroupInput {
+  instances: Array<{ filePath: string; startLine: number; endLine: number }>;
+  duplicatedLines: number;
+}
+
+function fileSetKey(files: string[]): string {
+  return [...files].sort().join('\0');
+}
+
+function dirOf(filePath: string): string {
+  const normalized = filePath.replace(/\\/g, '/');
+  const idx = normalized.lastIndexOf('/');
+  return idx >= 0 ? normalized.slice(0, idx) : '';
+}
+
+function generateSuggestions(
+  files: string[],
+  groups: RawGroupInput[],
+  totalDuplicatedLines: number,
+): RefactoringSuggestion[] {
+  if (totalDuplicatedLines < MODULE_EXTRACTION_THRESHOLD) {
+    return groups.map((g) => ({
+      kind: 'ExtractFunction' as const,
+      description: `Extract shared function (${g.duplicatedLines} lines) from ${g.instances.map((i) => i.filePath.split('/').pop() ?? i.filePath).join(', ')}`,
+      estimatedLines: g.duplicatedLines,
+      files,
+    }));
+  }
+
+  const dirs = [...new Set(files.map(dirOf))];
+  if (dirs.length > 1 && files.length >= 3) {
+    return [
+      {
+        kind: 'MergeDirectories' as const,
+        description: `Consider merging ${dirs.length} directories with ${totalDuplicatedLines} shared lines`,
+        estimatedLines: totalDuplicatedLines,
+        files,
+      },
+    ];
+  }
+
+  return [
+    {
+      kind: 'ExtractModule' as const,
+      description: `Extract ${totalDuplicatedLines} duplicated lines into a shared module`,
+      estimatedLines: totalDuplicatedLines,
+      files,
+    },
+  ];
+}
+
+export function groupRawGroupsIntoFamilies(groups: RawGroupInput[]): CloneFamily[] {
+  const familyMap = new Map<string, { files: Set<string>; groups: RawGroupInput[] }>();
+
+  for (const group of groups) {
+    const files = group.instances.map((i) => i.filePath);
+    const key = fileSetKey(files);
+    if (!familyMap.has(key)) {
+      familyMap.set(key, { files: new Set(files), groups: [] });
+    }
+    familyMap.get(key)!.groups.push(group);
+  }
+
+  const families: CloneFamily[] = [];
+
+  for (const { files, groups: fg } of familyMap.values()) {
+    const fileList = [...files].sort();
+    const totalDuplicatedLines = fg.reduce((s, g) => s + g.duplicatedLines, 0);
+    families.push({
+      files: fileList,
+      groupCount: fg.length,
+      totalDuplicatedLines,
+      suggestions: generateSuggestions(fileList, fg, totalDuplicatedLines),
+    });
+  }
+
+  families.sort((a, b) => b.totalDuplicatedLines - a.totalDuplicatedLines);
+  return families;
+}

package/src/duplicates/normalize.ts

@@ -0,0 +1,58 @@
+import type { SourceToken, TokenKind } from './token-types.js';
+
+export type DetectionMode = 'Exact' | 'NormalizeIdentifiers' | 'NormalizeLiterals' | 'NormalizeAll';
+
+export interface ResolvedNormalization {
+  normalizeIdentifiers: boolean;
+  normalizeLiterals: boolean;
+  normalizeKeywords: boolean;
+}
+
+export interface HashedToken {
+  hash: number;
+  originalIndex: number;
+}
+
+export function resolveNormalization(mode: DetectionMode): ResolvedNormalization {
+  switch (mode) {
+    case 'Exact':
+      return { normalizeIdentifiers: false, normalizeLiterals: false, normalizeKeywords: false };
+    case 'NormalizeIdentifiers':
+      return { normalizeIdentifiers: true, normalizeLiterals: false, normalizeKeywords: false };
+    case 'NormalizeLiterals':
+      return { normalizeIdentifiers: false, normalizeLiterals: true, normalizeKeywords: false };
+    case 'NormalizeAll':
+      return { normalizeIdentifiers: true, normalizeLiterals: true, normalizeKeywords: true };
+  }
+}
+
+export function normalizeAndHash(tokens: SourceToken[], mode: DetectionMode): HashedToken[] {
+  return normalizeAndHashResolved(tokens, resolveNormalization(mode));
+}
+
+export function normalizeAndHashResolved(tokens: SourceToken[], norm: ResolvedNormalization): HashedToken[] {
+  return tokens.map((tok, i) => ({
+    hash: hashTokenResolved(tok.kind, norm),
+    originalIndex: i,
+  }));
+}
+
+export function hashTokenResolved(kind: TokenKind, norm: ResolvedNormalization): number {
+  if (norm.normalizeIdentifiers && kind.kind === 'Identifier') return djb2('__ID__');
+  if (norm.normalizeLiterals) {
+    if (kind.kind === 'StringLiteral') return djb2('__STR__');
+    if (kind.kind === 'NumericLiteral') return djb2('__NUM__');
+    if (kind.kind === 'TemplateLiteral') return djb2('__TPL__');
+  }
+  if (norm.normalizeKeywords && kind.kind === 'Keyword') return djb2('__KW__');
+  return djb2(JSON.stringify(kind));
+}
+
+function djb2(s: string): number {
+  let h = 5381;
+  for (let i = 0; i < s.length; i++) {
+    h = ((h << 5) + h) ^ s.charCodeAt(i);
+    h = h >>> 0;
+  }
+  return h;
+}

package/src/duplicates/shingle-filter.ts

@@ -0,0 +1,37 @@
+export const SHINGLE_SIZE = 7;
+
+export function buildShingleSet(tokens: number[], k: number = SHINGLE_SIZE): Set<string> {
+  const result = new Set<string>();
+  if (tokens.length < k) return result;
+  for (let i = 0; i <= tokens.length - k; i++) {
+    result.add(tokens.slice(i, i + k).join(','));
+  }
+  return result;
+}
+
+export function filterToFocusCandidates(
+  focusFileTokens: Map<number, number[]>,
+  allFileTokens: Map<number, number[]>,
+  k: number = SHINGLE_SIZE,
+): Set<number> {
+  const focusShingles = new Set<string>();
+  for (const tokens of focusFileTokens.values()) {
+    for (const shingle of buildShingleSet(tokens, k)) {
+      focusShingles.add(shingle);
+    }
+  }
+
+  const candidates = new Set<number>();
+  for (const [fileId, tokens] of allFileTokens) {
+    if (focusFileTokens.has(fileId)) continue;
+    const fileShingles = buildShingleSet(tokens, k);
+    for (const s of fileShingles) {
+      if (focusShingles.has(s)) {
+        candidates.add(fileId);
+        break;
+      }
+    }
+  }
+
+  return candidates;
+}

package/src/duplicates/token-types.ts

@@ -0,0 +1,62 @@
+export type KeywordType =
+  | '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';
+
+export type OperatorType =
+  | 'Assign' | 'Add' | 'Sub' | 'Mul' | 'Div' | 'Mod' | 'Exp'
+  | 'Eq' | 'NEq' | 'StrictEq' | 'StrictNEq' | 'Lt' | 'Gt' | 'LtEq' | 'GtEq'
+  | 'And' | 'Or' | 'Not' | 'BitwiseAnd' | 'BitwiseOr' | 'BitwiseXor' | 'BitwiseNot'
+  | 'ShiftLeft' | 'ShiftRight' | 'UnsignedShiftRight'
+  | 'NullishCoalescing' | 'OptionalChaining' | 'Spread' | 'Ternary' | 'Arrow' | 'Comma'
+  | 'AddAssign' | 'SubAssign' | 'MulAssign' | 'DivAssign' | 'ModAssign' | 'ExpAssign'
+  | 'AndAssign' | 'OrAssign' | 'NullishAssign'
+  | 'BitwiseAndAssign' | 'BitwiseOrAssign' | 'BitwiseXorAssign'
+  | 'ShiftLeftAssign' | 'ShiftRightAssign' | 'UnsignedShiftRightAssign'
+  | 'Increment' | 'Decrement';
+
+export type PunctuationType =
+  | 'OpenParen' | 'CloseParen' | 'OpenBrace' | 'CloseBrace'
+  | 'OpenBracket' | 'CloseBracket' | 'Semicolon' | 'Colon' | 'Dot';
+
+export type TokenKind =
+  | { kind: 'Keyword'; kwType: KeywordType }
+  | { kind: 'Identifier'; name: string }
+  | { kind: 'StringLiteral' }
+  | { kind: 'NumericLiteral' }
+  | { kind: 'BooleanLiteral'; value: boolean }
+  | { kind: 'NullLiteral' }
+  | { kind: 'TemplateLiteral' }
+  | { kind: 'RegExpLiteral' }
+  | { kind: 'Operator'; opType: OperatorType }
+  | { kind: 'Punctuation'; punctType: PunctuationType };
+
+export interface Span {
+  start: number;
+  end: number;
+}
+
+export interface SourceToken {
+  kind: TokenKind;
+  span: Span;
+}
+
+export interface FileTokens {
+  tokens: SourceToken[];
+  source: string;
+  lineCount: number;
+}
+
+export function pointSpan(pos: number): Span {
+  return { start: pos, end: pos + 1 };
+}
+
+export function emptyTokens(source: string): FileTokens {
+  const lineCount = (source.match(/\n/g)?.length ?? 0) + 1;
+  return { tokens: [], source, lineCount };
+}

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';
+  }
+}