@monoes/monograph 1.5.5 → 1.5.7

package/src/results/types.ts

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

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

@@ -1,206 +0,0 @@
-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/diacritic.ts

@@ -1,7 +0,0 @@
-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/hybrid-query.ts

@@ -1,65 +0,0 @@
-/**
- * BM25 search (FTS5) with the historical "hybrid" entry-point signature.
- *
- * Monograph search is BM25-only. The former embedding/vector branch
- * (gated on MONOGRAPH_EMBEDDINGS=true) was removed — it was never run in
- * practice (the embeddings table stayed empty) and did a JS cosine full
- * scan. The exported function signatures are unchanged so callers do not
- * need to change.
- */
-
-import type Database from 'better-sqlite3';
-import type { RankedResult } from './rrf.js';
-import { ftsSearch } from '../storage/fts-store.js';
-import { normalizeSearchTerm } from './diacritic.js';
-
-export interface HybridQueryOptions {
-  limit?: number;
-  label?: string;
-  /** @deprecated Embeddings are disabled — this option is ignored; search is BM25-only. */
-  embedder?: unknown;
-}
-
-export interface HybridResult extends RankedResult {
-  id: string;
-  name: string;
-  normLabel: string;
-  filePath: string | null;
-  label: string;
-  score: number;
-  /** First line of the symbol in its source file (1-based, null if unknown). */
-  startLine?: number | null;
-  /** Last line of the symbol in its source file (1-based, null if unknown). */
-  endLine?: number | null;
-}
-
-/**
- * Run a BM25 (FTS5) search. Despite the name, this is BM25-only — the
- * vector branch was removed; the `embedder` option is ignored.
- */
-export async function hybridQuery(
-  db: Database.Database,
-  query: string,
-  options: HybridQueryOptions = {},
-): Promise<HybridResult[]> {
-  const { limit = 20, label } = options;
-
-  // Normalize the query for text-based lookups (strip diacritics, lowercase, trim)
-  const normalizedQuery = normalizeSearchTerm(query);
-
-  // ── BM25 via FTS5 ──────────────────────────────────────────────────────────
-  const bm25Limit = Math.max(limit, 50);
-  const bm25Raw = ftsSearch(db, normalizedQuery, bm25Limit, label);
-  const bm25Results: RankedResult[] = bm25Raw.map((r) => ({
-    id: r.id,
-    name: r.name,
-    normLabel: r.normLabel,
-    filePath: r.filePath,
-    label: r.label,
-    score: r.rank,
-    startLine: r.startLine,
-    endLine: r.endLine,
-  }));
-
-  return bm25Results.slice(0, limit) as HybridResult[];
-}

package/src/search/rrf.ts

@@ -1,51 +0,0 @@
-/**
- * Reciprocal Rank Fusion (RRF)
- *
- * Merges two ranked result lists using the formula:
- *   score(d) = sum over each list of: 1 / (K + rank_of_d_in_list)
- *
- * where rank is 1-based.
- *
- * Reference: Cormack, Clarke & Buettcher (SIGIR 2009).
- */
-
-export interface RankedResult {
-  id: string;
-  score: number;
-  [key: string]: unknown;
-}
-
-/**
- * Merge two ranked lists via RRF and return results sorted by fused score descending.
- *
- * @param list1 - First ranked list (ordered by relevance, best first)
- * @param list2 - Second ranked list (ordered by relevance, best first)
- * @param K     - RRF constant (default 60, per the original paper)
- */
-export function mergeRanks(
-  list1: RankedResult[],
-  list2: RankedResult[],
-  K = 60,
-): RankedResult[] {
-  const scoreMap = new Map<string, { rrf: number; payload: RankedResult }>();
-
-  const addList = (list: RankedResult[]) => {
-    list.forEach((item, idx) => {
-      const rank = idx + 1; // 1-based
-      const contribution = 1 / (K + rank);
-      const existing = scoreMap.get(item.id);
-      if (existing) {
-        existing.rrf += contribution;
-      } else {
-        scoreMap.set(item.id, { rrf: contribution, payload: item });
-      }
-    });
-  };
-
-  addList(list1);
-  addList(list2);
-
-  return [...scoreMap.values()]
-    .sort((a, b) => b.rrf - a.rrf)
-    .map(({ rrf, payload }) => ({ ...payload, score: rrf }));
-}

package/src/security/safe-fetch.ts

@@ -1,113 +0,0 @@
-const PRIVATE_IP_PATTERNS: RegExp[] = [
-  /^127\./,
-  /^10\./,
-  /^192\.168\./,
-  /^172\.(1[6-9]|2\d|3[01])\./,
-  /^169\.254\./,
-  /^::1$|\[::1\]/,
-  /^fc00:|^\[fc00:/i,
-  /^fe80:|^\[fe80:/i,
-  // IPv4-mapped IPv6 (e.g. ::ffff:192.168.1.1) — covers private ranges via mapped form
-  /^::ffff:/i,
-  /^\[::ffff:/i,
-];
-
-const CLOUD_METADATA_HOSTS = new Set([
-  'metadata.google.internal',
-  'metadata.goog',
-  '169.254.169.254',
-]);
-
-/**
- * Returns true if the given URL resolves to a private, loopback, or cloud
- * metadata address that should be blocked to prevent SSRF attacks.
- */
-export function isPrivateUrl(rawUrl: string): boolean {
-  let url: URL;
-  try {
-    url = new URL(rawUrl);
-  } catch {
-    return false;
-  }
-  const host = url.hostname;
-  if (host === 'localhost') return true;
-  if (CLOUD_METADATA_HOSTS.has(host)) return true;
-  return PRIVATE_IP_PATTERNS.some(p => p.test(host));
-}
-
-/**
- * Validates that a URL is safe to fetch: must use http/https and must not
- * resolve to a private or reserved address.
- * @throws {Error} if the URL is invalid, uses an unsupported scheme, or is private
- */
-export function validateUrl(rawUrl: string): void {
-  let url: URL;
-  try {
-    url = new URL(rawUrl);
-  } catch {
-    throw new Error(`Invalid URL: ${rawUrl}`);
-  }
-  if (!['http:', 'https:'].includes(url.protocol)) {
-    throw new Error(`Unsupported scheme: ${url.protocol}`);
-  }
-  if (isPrivateUrl(rawUrl)) {
-    throw new Error(`URL resolves to private/reserved address: ${url.hostname}`);
-  }
-}
-
-/**
- * Fetches the content of a URL after validating it is safe (not private/internal).
- * Enforces a maximum response size and request timeout.
- *
- * @param rawUrl - The URL to fetch
- * @param opts.maxBytes - Maximum allowed response size in bytes (default 10 MB)
- * @param opts.timeoutMs - Request timeout in milliseconds (default 10 000)
- * @returns The response body as a string
- * @throws {Error} if the URL is unsafe, the request fails, or the response is too large
- */
-export async function safeFetch(
-  rawUrl: string,
-  opts: { maxBytes?: number; timeoutMs?: number } = {},
-): Promise<string> {
-  validateUrl(rawUrl);
-  const { maxBytes = 10 * 1024 * 1024, timeoutMs = 10_000 } = opts;
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), timeoutMs);
-  try {
-    const res = await fetch(rawUrl, { signal: controller.signal });
-    if (!res.ok) throw new Error(`HTTP ${res.status}: ${rawUrl}`);
-
-    // Stream the body incrementally so we can enforce maxBytes before
-    // the full response is loaded into memory (prevents memory exhaustion
-    // on large/malicious payloads).
-    if (!res.body) {
-      throw new Error(`Response body is missing: ${rawUrl}`);
-    }
-    const reader = (res.body as ReadableStream<Uint8Array>).getReader();
-    const decoder = new TextDecoder();
-    const chunks: string[] = [];
-    let totalBytes = 0;
-
-    try {
-      while (true) {
-        const { value, done } = await reader.read();
-        if (done) break;
-        if (value) {
-          totalBytes += value.byteLength;
-          if (totalBytes > maxBytes) {
-            throw new Error(`Response exceeds ${maxBytes} bytes: ${rawUrl}`);
-          }
-          chunks.push(decoder.decode(value, { stream: true }));
-        }
-      }
-      // Flush any remaining bytes held in the decoder
-      chunks.push(decoder.decode());
-    } finally {
-      reader.releaseLock();
-    }
-
-    return chunks.join('');
-  } finally {
-    clearTimeout(timer);
-  }
-}

package/src/security/sensitive-files.ts

@@ -1,24 +0,0 @@
-import { basename as pathBasename } from 'path';
-
-const SENSITIVE_PATTERNS: RegExp[] = [
-  /^\.env(\.|$)/i,
-  /^\.netrc$/i,
-  /\baws_credentials\b/i,
-  /\bcredentials?\b.*\.(json|yaml|yml|toml|ini|cfg)$/i,
-  /\bsecrets?\b.*\.(json|yaml|yml|toml|ini|cfg)$/i,
-  /\bsecret[_-]?key\b/i,
-  /\bapi[_-]?key\b.*\.(json|txt)$/i,
-  /\bpasswd\b/i,
-  /\bpassword[s]?\b.*\.(txt|json|yaml|yml)$/i,
-  /\btoken\b.*\.(txt|json|env)$/i,
-  /\b(id_rsa|id_dsa|id_ecdsa|id_ed25519)(\.pub)?$/i,
-  /\.(pem|key|pfx|p12|p8|pkcs8)$/i,
-  /\bservice[_-]?account\b.*\.json$/i,
-  /\bkeystore\b/i,
-  /\bvault[_-]?token\b/i,
-];
-
-export function isSensitiveFile(filePath: string): boolean {
-  const base = pathBasename(filePath);
-  return SENSITIVE_PATTERNS.some(p => p.test(base) || p.test(filePath));
-}