@monoes/monograph 1.1.0 → 1.2.0

package/src/results/types.ts

@@ -0,0 +1,149 @@
+export type DependencyLocation = 'Dependencies' | 'DevDependencies' | 'OptionalDependencies' | 'PeerDependencies';
+
+export interface UnusedFile {
+  filePath: string;
+  sizeBytes?: number;
+}
+
+export interface UnusedExport {
+  filePath: string;
+  exportName: string;
+  line?: number;
+  col?: number;
+  isType?: boolean;
+}
+
+export interface UnusedMember {
+  filePath: string;
+  memberName: string;
+  parentName?: string;
+  kind?: 'method' | 'property' | 'getter' | 'setter' | 'accessor' | 'constructor';
+  line?: number;
+}
+
+export interface UnusedDependency {
+  name: string;
+  location: DependencyLocation;
+}
+
+export interface CircularDependency {
+  cycle: string[];
+}
+
+export interface BoundaryViolation {
+  fromFile: string;
+  toFile: string;
+  fromBoundary: string;
+  toBoundary: string;
+}
+
+export interface StaleSuppression {
+  filePath: string;
+  line: number;
+  kind: string;
+  comment: string;
+}
+
+export interface PrivateTypeLeak {
+  filePath: string;
+  exportName: string;
+  leakedType: string;
+  line?: number;
+}
+
+export interface DuplicateExport {
+  exportName: string;
+  files: string[];
+}
+
+export interface AnalysisResults {
+  unusedFiles: UnusedFile[];
+  unusedExports: UnusedExport[];
+  unusedTypes: UnusedExport[];
+  privateTypeLeaks: PrivateTypeLeak[];
+  unusedDependencies: UnusedDependency[];
+  unusedEnumMembers: UnusedMember[];
+  unusedClassMembers: UnusedMember[];
+  unresolvedImports: Array<{ filePath: string; specifier: string; line?: number }>;
+  unlistedDependencies: UnusedDependency[];
+  duplicateExports: DuplicateExport[];
+  circularDependencies: CircularDependency[];
+  boundaryViolations: BoundaryViolation[];
+  staleSuppressions: StaleSuppression[];
+}
+
+export function makeEmptyAnalysisResults(): AnalysisResults {
+  return {
+    unusedFiles: [],
+    unusedExports: [],
+    unusedTypes: [],
+    privateTypeLeaks: [],
+    unusedDependencies: [],
+    unusedEnumMembers: [],
+    unusedClassMembers: [],
+    unresolvedImports: [],
+    unlistedDependencies: [],
+    duplicateExports: [],
+    circularDependencies: [],
+    boundaryViolations: [],
+    staleSuppressions: [],
+  };
+}
+
+export function totalIssues(results: AnalysisResults): number {
+  return (
+    results.unusedFiles.length +
+    results.unusedExports.length +
+    results.unusedTypes.length +
+    results.privateTypeLeaks.length +
+    results.unusedDependencies.length +
+    results.unusedEnumMembers.length +
+    results.unusedClassMembers.length +
+    results.unresolvedImports.length +
+    results.unlistedDependencies.length +
+    results.duplicateExports.length +
+    results.circularDependencies.length +
+    results.boundaryViolations.length +
+    results.staleSuppressions.length
+  );
+}
+
+export function hasIssues(results: AnalysisResults): boolean {
+  return totalIssues(results) > 0;
+}
+
+export function mergeAnalysisResults(a: AnalysisResults, b: AnalysisResults): AnalysisResults {
+  return {
+    unusedFiles: [...a.unusedFiles, ...b.unusedFiles],
+    unusedExports: [...a.unusedExports, ...b.unusedExports],
+    unusedTypes: [...a.unusedTypes, ...b.unusedTypes],
+    privateTypeLeaks: [...a.privateTypeLeaks, ...b.privateTypeLeaks],
+    unusedDependencies: [...a.unusedDependencies, ...b.unusedDependencies],
+    unusedEnumMembers: [...a.unusedEnumMembers, ...b.unusedEnumMembers],
+    unusedClassMembers: [...a.unusedClassMembers, ...b.unusedClassMembers],
+    unresolvedImports: [...a.unresolvedImports, ...b.unresolvedImports],
+    unlistedDependencies: [...a.unlistedDependencies, ...b.unlistedDependencies],
+    duplicateExports: [...a.duplicateExports, ...b.duplicateExports],
+    circularDependencies: [...a.circularDependencies, ...b.circularDependencies],
+    boundaryViolations: [...a.boundaryViolations, ...b.boundaryViolations],
+    staleSuppressions: [...a.staleSuppressions, ...b.staleSuppressions],
+  };
+}
+
+export function filterResultsByFile(results: AnalysisResults, filePaths: Set<string>): AnalysisResults {
+  return {
+    unusedFiles: results.unusedFiles.filter(r => filePaths.has(r.filePath)),
+    unusedExports: results.unusedExports.filter(r => filePaths.has(r.filePath)),
+    unusedTypes: results.unusedTypes.filter(r => filePaths.has(r.filePath)),
+    privateTypeLeaks: results.privateTypeLeaks.filter(r => filePaths.has(r.filePath)),
+    unusedDependencies: results.unusedDependencies,
+    unusedEnumMembers: results.unusedEnumMembers.filter(r => filePaths.has(r.filePath)),
+    unusedClassMembers: results.unusedClassMembers.filter(r => filePaths.has(r.filePath)),
+    unresolvedImports: results.unresolvedImports.filter(r => filePaths.has(r.filePath)),
+    unlistedDependencies: results.unlistedDependencies,
+    duplicateExports: results.duplicateExports,
+    circularDependencies: results.circularDependencies.filter(c => c.cycle.some(f => filePaths.has(f))),
+    boundaryViolations: results.boundaryViolations.filter(b => filePaths.has(b.fromFile)),
+    staleSuppressions: results.staleSuppressions.filter(r => filePaths.has(r.filePath)),
+  };
+}

package/src/scope-resolution/evidence-weights.ts

@@ -0,0 +1,41 @@
+/**
+ * Evidence weight constants for scope-based resolution.
+ */
+
+export const EvidenceWeights = {
+  local: 0.55,
+  import: 0.45,
+  reexport: 0.4,
+  namespace: 0.4,
+  wildcard: 0.3,
+
+  scopeChainPerDepth: -0.02,
+
+  typeBindingByMroDepth: [0.5, 0.42, 0.36, 0.32, 0.3] as const,
+
+  ownerMatch: 0.2,
+  kindMatch: 0.0,
+
+  arityMatchCompatible: 0.1,
+  arityMatchUnknown: 0.0,
+  arityMatchIncompatible: -0.15,
+
+  globalQualified: 0.35,
+  globalName: 0.1,
+
+  dynamicImportUnresolved: 0.02,
+
+  unlinkedImportMultiplier: 0.5,
+} as const;
+
+export function typeBindingWeightAtDepth(mroDepth: number): number {
+  const table = EvidenceWeights.typeBindingByMroDepth;
+  if (mroDepth < 0) return table[0];
+  if (mroDepth >= table.length) return table[table.length - 1]!;
+  return table[mroDepth]!;
+}
+
+export function composeWeights(...weights: number[]): number {
+  const sum = weights.reduce((s, w) => s + w, 0);
+  return Math.min(1.0, Math.max(0.0, sum));
+}

package/src/search/ast-chunker.ts

@@ -0,0 +1,206 @@
+export interface ChunkOptions {
+  maxTokens?: number;  // default 512
+  overlap?: number;    // default 50 (token overlap between adjacent chunks)
+  minTokens?: number;  // default 20  (discard chunks smaller than this)
+}
+
+export interface Chunk {
+  text: string;
+  startLine: number;
+  endLine: number;
+  kind: 'function' | 'class' | 'block' | 'comment' | 'import' | 'other';
+}
+
+const IMPORT_RE = /^(import\s|export\s*\{[^}]*\}\s*from)/;
+const FUNCTION_RE = /^(export\s+)?(async\s+)?function\s+\w+|^(export\s+)?const\s+\w+\s*=\s*(async\s+)?\(/;
+const CLASS_RE = /^(export\s+)?(abstract\s+)?class\s+\w+/;
+const COMMENT_RE = /^(\/\/|\/\*| \*)/;
+
+type LineKind = 'function' | 'class' | 'block' | 'comment' | 'import' | 'other';
+
+function estimateTokens(text: string): number {
+  return Math.ceil(text.length / 4);
+}
+
+function classifyLine(line: string): LineKind {
+  const trimmed = line.trimStart();
+  if (IMPORT_RE.test(trimmed)) return 'import';
+  if (FUNCTION_RE.test(trimmed)) return 'function';
+  if (CLASS_RE.test(trimmed)) return 'class';
+  if (COMMENT_RE.test(trimmed)) return 'comment';
+  return 'other';
+}
+
+interface LineGroup {
+  lines: string[];
+  startLine: number; // 1-based
+  kind: LineKind;
+}
+
+function groupLines(sourceLines: string[]): LineGroup[] {
+  const groups: LineGroup[] = [];
+  let i = 0;
+
+  while (i < sourceLines.length) {
+    const line = sourceLines[i];
+    const trimmed = line.trim();
+
+    // Skip blank lines (treat them as other with 0 tokens — they'll be filtered)
+    if (trimmed === '') {
+      i++;
+      continue;
+    }
+
+    const kind = classifyLine(trimmed);
+
+    // For groupable kinds (import, comment), collect consecutive matching lines
+    if (kind === 'import' || kind === 'comment') {
+      const startIdx = i;
+      const collected: string[] = [line];
+      i++;
+      while (i < sourceLines.length) {
+        const next = sourceLines[i].trim();
+        if (next === '') break;
+        const nextKind = classifyLine(next);
+        if (nextKind === kind) {
+          collected.push(sourceLines[i]);
+          i++;
+        } else {
+          break;
+        }
+      }
+      groups.push({ lines: collected, startLine: startIdx + 1, kind });
+    } else if (kind === 'function' || kind === 'class') {
+      // Collect the block: track brace depth
+      const startIdx = i;
+      const collected: string[] = [line];
+      i++;
+      let depth = (line.match(/\{/g) || []).length - (line.match(/\}/g) || []).length;
+
+      // If no opening brace on the first line yet, keep reading until we have one
+      while (i < sourceLines.length && depth <= 0) {
+        const cur = sourceLines[i];
+        collected.push(cur);
+        depth += (cur.match(/\{/g) || []).length - (cur.match(/\}/g) || []).length;
+        i++;
+      }
+
+      // Now consume until depth returns to 0
+      while (i < sourceLines.length && depth > 0) {
+        const cur = sourceLines[i];
+        collected.push(cur);
+        depth += (cur.match(/\{/g) || []).length - (cur.match(/\}/g) || []).length;
+        i++;
+      }
+
+      groups.push({ lines: collected, startLine: startIdx + 1, kind });
+    } else {
+      // 'other': collect consecutive non-blank other lines into one group
+      const startIdx = i;
+      const collected: string[] = [line];
+      i++;
+      while (i < sourceLines.length) {
+        const next = sourceLines[i].trim();
+        if (next === '') break;
+        const nextKind = classifyLine(next);
+        if (nextKind === 'other') {
+          collected.push(sourceLines[i]);
+          i++;
+        } else {
+          break;
+        }
+      }
+      groups.push({ lines: collected, startLine: startIdx + 1, kind });
+    }
+  }
+
+  return groups;
+}
+
+function splitGroupIntoChunks(
+  group: LineGroup,
+  maxTokens: number,
+  overlap: number,
+): Chunk[] {
+  const lines = group.lines;
+  const result: Chunk[] = [];
+
+  // Tokens per line (estimated)
+  const lineTokens = lines.map(l => estimateTokens(l));
+
+  let start = 0; // index into lines[]
+
+  while (start < lines.length) {
+    let tokenCount = 0;
+    let end = start;
+
+    while (end < lines.length && tokenCount + lineTokens[end] <= maxTokens) {
+      tokenCount += lineTokens[end];
+      end++;
+    }
+
+    // If we couldn't advance even one line (single line exceeds maxTokens), force include it
+    if (end === start) {
+      end = start + 1;
+    }
+
+    const chunkLines = lines.slice(start, end);
+    const text = chunkLines.join('\n');
+    const startLine = group.startLine + start;
+    const endLine = group.startLine + end - 1;
+
+    result.push({ text, startLine, endLine, kind: group.kind });
+
+    if (end >= lines.length) break;
+
+    // Calculate how many lines from the end of this chunk to include as overlap
+    // for the next chunk's start. Count back until overlap token budget is met.
+    let overlapTokens = 0;
+    let overlapLineCount = 0;
+    for (let j = end - 1; j >= start; j--) {
+      if (overlapTokens + lineTokens[j] > overlap) break;
+      overlapTokens += lineTokens[j];
+      overlapLineCount++;
+    }
+
+    // Next start is (end - overlapLineCount), but must be strictly > start to avoid looping
+    const nextStart = Math.max(start + 1, end - overlapLineCount);
+    start = nextStart;
+  }
+
+  return result;
+}
+
+export function chunkSource(source: string, options?: ChunkOptions): Chunk[] {
+  const maxTokens = options?.maxTokens ?? 512;
+  const overlap = options?.overlap ?? 50;
+  const minTokens = options?.minTokens ?? 5;
+
+  if (!source || source.trim() === '') return [];
+
+  const sourceLines = source.split('\n');
+  const groups = groupLines(sourceLines);
+
+  const chunks: Chunk[] = [];
+
+  for (const group of groups) {
+    const text = group.lines.join('\n');
+    const tokens = estimateTokens(text);
+
+    if (tokens <= maxTokens) {
+      chunks.push({
+        text,
+        startLine: group.startLine,
+        endLine: group.startLine + group.lines.length - 1,
+        kind: group.kind,
+      });
+    } else {
+      // Split into sub-chunks with overlap
+      const subChunks = splitGroupIntoChunks(group, maxTokens, overlap);
+      chunks.push(...subChunks);
+    }
+  }
+
+  // Discard chunks below minTokens
+  return chunks.filter(c => estimateTokens(c.text) >= minTokens);
+}

package/src/search/device-config.ts

@@ -0,0 +1,31 @@
+export type EmbedDevice = 'cpu' | 'cuda' | 'mps';
+
+export interface EmbedDeviceConfig {
+  device?: EmbedDevice;
+  threads?: number;
+}
+
+/**
+ * Resolves the compute device to use for local embedders.
+ *
+ * Priority:
+ *  1. Explicit `config.device` if provided
+ *  2. 'mps' on macOS (darwin) when not explicitly overridden
+ *  3. 'cuda' when CUDA_VISIBLE_DEVICES env var is set (non-empty)
+ *  4. 'cpu' as fallback
+ */
+export function resolveDevice(config?: EmbedDeviceConfig): EmbedDevice {
+  if (config?.device) {
+    return config.device;
+  }
+
+  if (process.platform === 'darwin') {
+    return 'mps';
+  }
+
+  if (process.env['CUDA_VISIBLE_DEVICES']) {
+    return 'cuda';
+  }
+
+  return 'cpu';
+}

package/src/search/diacritic.ts

@@ -0,0 +1,7 @@
+export function stripDiacritics(text: string): string {
+  return text.normalize('NFD').replace(/[̀-ͯ]/g, '');
+}
+
+export function normalizeSearchTerm(term: string): string {
+  return stripDiacritics(term.trim().toLowerCase());
+}

package/src/search/embed-batch.ts

@@ -0,0 +1,148 @@
+/**
+ * Batch-embed all symbol nodes that don't yet have an embedding stored.
+ */
+
+import type Database from 'better-sqlite3';
+import type { EmbedderFn } from './embedder.js';
+import type { EmbedDeviceConfig } from './device-config.js';
+import type { HttpEmbedderConfig } from './http-embedder.js';
+import { upsertEmbedding, countEmbeddings } from '../storage/embedding-store.js';
+import { embedText } from './embedder.js';
+
+const BATCH_SIZE = 32;
+
+export interface EmbedBatchConfig {
+  device?: EmbedDeviceConfig;
+  remote?: HttpEmbedderConfig; // if set, use HttpEmbedder instead of local
+  batchSize?: number;          // override default batch size
+}
+
+/**
+ * Embed a list of text strings and return an array of embedding vectors.
+ *
+ * If `config.remote` is provided, delegates to `HttpEmbedder`.
+ * Otherwise falls back to the local HuggingFace embedder.
+ *
+ * @param texts  - Strings to embed
+ * @param config - Optional device/remote/batchSize config
+ */
+export async function embedBatch(
+  texts: string[],
+  config?: EmbedBatchConfig,
+): Promise<number[][]> {
+  // Store device config in a local variable (passed through for future use)
+  const _device = config?.device;
+  void _device;
+
+  if (config?.remote) {
+    const { HttpEmbedder } = await import('./http-embedder.js');
+    const embedder = new HttpEmbedder(config.remote);
+    return embedder.embedBatch(texts);
+  }
+
+  // Local embedder path
+  const { getEmbedder } = await import('./embedder.js');
+  const embedderFn = await getEmbedder();
+  const batchSize = config?.batchSize ?? BATCH_SIZE;
+  const results: number[][] = [];
+
+  for (let i = 0; i < texts.length; i += batchSize) {
+    const batch = texts.slice(i, i + batchSize);
+    const batchResults = await Promise.all(
+      batch.map(async (text) => {
+        const vector = await embedText(text, embedderFn);
+        return Array.from(vector);
+      }),
+    );
+    results.push(...batchResults);
+  }
+
+  return results;
+}
+
+export interface EmbedAllResult {
+  embedded: number;
+  skipped: number;
+}
+
+/**
+ * Embed all nodes that are missing embeddings.
+ *
+ * Nodes are fetched in batches of BATCH_SIZE to avoid loading the entire DB
+ * into memory at once.
+ *
+ * @param db       - Open monograph database
+ * @param embedder - Feature extraction pipeline function
+ * @param force    - When true, re-embed nodes even if they already have an embedding
+ */
+const CODE_LABELS = new Set(['Function', 'Method', 'Class', 'Module', 'Interface', 'Enum', 'Struct', 'Constructor', 'Variable', 'Const', 'TypeAlias']);
+
+export async function embedAll(
+  db: Database.Database,
+  embedder: EmbedderFn,
+  force = false,
+  codeOnly = false,
+): Promise<EmbedAllResult> {
+  let embedded = 0;
+  let skipped = 0;
+
+  // Fetch all node IDs and their name+normLabel (used as the text to embed)
+  const rows = db
+    .prepare(
+      `SELECT id, name, norm_label, label, file_path
+       FROM nodes
+       ORDER BY rowid`,
+    )
+    .all() as { id: string; name: string; norm_label: string; label: string; file_path: string | null }[];
+
+  const filteredRows = codeOnly ? rows.filter((r) => CODE_LABELS.has(r.label)) : rows;
+
+  // Build set of node IDs that already have embeddings
+  const existingIds = force
+    ? new Set<string>()
+    : new Set(
+        (
+          db.prepare('SELECT node_id FROM embeddings').all() as { node_id: string }[]
+        ).map((r) => r.node_id),
+      );
+
+  // Filter to only rows that need embedding
+  const toEmbed = filteredRows.filter((r) => !existingIds.has(r.id));
+  skipped = filteredRows.length - toEmbed.length;
+
+  // Process in batches
+  for (let i = 0; i < toEmbed.length; i += BATCH_SIZE) {
+    const batch = toEmbed.slice(i, i + BATCH_SIZE);
+    await Promise.all(
+      batch.map(async (row) => {
+        const text = buildNodeText(row);
+        try {
+          const vector = await embedText(text, embedder);
+          upsertEmbedding(db, row.id, vector);
+          embedded++;
+        } catch {
+          // Skip nodes that fail to embed (e.g. empty name)
+          skipped++;
+        }
+      }),
+    );
+  }
+
+  return { embedded, skipped };
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function buildNodeText(row: {
+  name: string;
+  norm_label: string;
+  label: string;
+  file_path: string | null;
+}): string {
+  const parts: string[] = [row.name, row.label];
+  if (row.norm_label && row.norm_label !== row.name) parts.push(row.norm_label);
+  if (row.file_path) parts.push(row.file_path);
+  return parts.join(' ');
+}
+
+export { countEmbeddings };

package/src/search/embedder.ts

@@ -0,0 +1,60 @@
+/**
+ * Lazy singleton for the HuggingFace FeatureExtractionPipeline.
+ *
+ * Uses dynamic import so that:
+ *  1. Tests can mock `getEmbedder` without installing the package.
+ *  2. @huggingface/transformers is optional at import time; callers receive a
+ *     clear error if the package is unavailable.
+ *
+ * Model: Snowflake/snowflake-arctic-embed-xs (384 dimensions)
+ */
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type EmbedderFn = (text: string | string[], options?: Record<string, unknown>) => Promise<any>;
+
+let cachedEmbedder: EmbedderFn | null = null;
+
+/**
+ * Returns (and caches) a FeatureExtractionPipeline for
+ * 'Snowflake/snowflake-arctic-embed-xs'.
+ *
+ * Throws a descriptive error if @huggingface/transformers is not installed.
+ */
+export async function getEmbedder(): Promise<EmbedderFn> {
+  if (cachedEmbedder) return cachedEmbedder;
+
+  let pipeline: (task: string, model: string, opts?: Record<string, unknown>) => Promise<EmbedderFn>;
+  try {
+    // Dynamic import so the dep is optional at bundle time
+    const hf = await import('@huggingface/transformers');
+    pipeline = hf.pipeline as typeof pipeline;
+  } catch {
+    throw new Error(
+      '@huggingface/transformers is not installed. ' +
+        'Run `npm install @huggingface/transformers` to enable embedding support.',
+    );
+  }
+
+  cachedEmbedder = await pipeline('feature-extraction', 'Snowflake/snowflake-arctic-embed-xs', {
+    dtype: 'fp32',
+  });
+  return cachedEmbedder;
+}
+
+/** Reset the cached singleton — used only in tests. */
+export function resetEmbedderCache(): void {
+  cachedEmbedder = null;
+}
+
+/**
+ * Embed a single text string and return a 384-dim Float32Array.
+ * Pooling: mean. Normalisation: L2 (so cosine ≡ dot product).
+ */
+export async function embedText(
+  text: string,
+  embedder: EmbedderFn,
+): Promise<Float32Array> {
+  const output = await embedder(text, { pooling: 'mean', normalize: true });
+  // HuggingFace Tensor: output.data is Float32Array
+  return output.data as Float32Array;
+}

package/src/search/exact-search.ts

@@ -0,0 +1,45 @@
+import type Database from 'better-sqlite3';
+
+export interface ExactSearchResult {
+  id: string;
+  score: number;
+}
+
+export interface ExactSearchOptions {
+  limit?: number;
+}
+
+function cosineSimilarity(a: Float32Array, b: Float32Array): number {
+  let dot = 0, normA = 0, normB = 0;
+  const len = Math.min(a.length, b.length);
+  for (let i = 0; i < len; i++) {
+    dot += a[i]! * b[i]!;
+    normA += a[i]! * a[i]!;
+    normB += b[i]! * b[i]!;
+  }
+  const denom = Math.sqrt(normA) * Math.sqrt(normB);
+  return denom === 0 ? 0 : dot / denom;
+}
+
+export function exactVectorSearch(
+  db: Database.Database,
+  queryVector: Float32Array,
+  options: ExactSearchOptions = {},
+): ExactSearchResult[] {
+  const { limit = 10 } = options;
+
+  const rows = db.prepare(`
+    SELECT e.node_id as id, e.vector FROM embeddings e
+    INNER JOIN nodes n ON n.id = e.node_id
+  `).all() as { id: string; vector: Buffer }[];
+
+  if (rows.length === 0) return [];
+
+  return rows
+    .map(row => {
+      const vec = new Float32Array(row.vector.buffer, row.vector.byteOffset, row.vector.byteLength / 4);
+      return { id: row.id, score: cosineSimilarity(queryVector, vec) };
+    })
+    .sort((a, b) => b.score - a.score)
+    .slice(0, limit);
+}