@monoes/monograph 1.5.6 → 1.5.7

package/src/health/vital-signs-snapshot.ts

@@ -1,72 +0,0 @@
-import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'fs';
-import { join } from 'path';
-
-export const SNAPSHOT_SCHEMA_VERSION = 7;
-
-export interface VitalSigns {
-  deadCodePct: number;
-  duplicationPct: number;
-  complexityHighPct: number;
-  complexityCriticalPct: number;
-  crapHighPct: number;
-  crapCriticalPct: number;
-  hotspotDensity: number;
-  busFactor: number;
-  unusedDepsPct: number;
-  maintainabilityIndex: number;
-}
-
-export interface HealthScore {
-  value: number;
-  grade: string;
-}
-
-export interface VitalSignsSnapshot {
-  schemaVersion: number;
-  timestamp: string; // ISO8601
-  vitalSigns: VitalSigns;
-  healthScore: HealthScore;
-}
-
-export function buildSnapshot(
-  vitalSigns: VitalSigns,
-  healthScore: HealthScore
-): VitalSignsSnapshot {
-  return {
-    schemaVersion: SNAPSHOT_SCHEMA_VERSION,
-    timestamp: new Date().toISOString(),
-    vitalSigns,
-    healthScore,
-  };
-}
-
-export function saveSnapshot(dir: string, snapshot: VitalSignsSnapshot): string {
-  if (!existsSync(dir)) {
-    mkdirSync(dir, { recursive: true });
-  }
-  const safeTimestamp = snapshot.timestamp.replace(/[:.]/g, '_');
-  const filepath = join(dir, `${safeTimestamp}.json`);
-  writeFileSync(filepath, JSON.stringify(snapshot, null, 2), 'utf-8');
-  return filepath;
-}
-
-export function loadSnapshots(dir: string): VitalSignsSnapshot[] {
-  if (!existsSync(dir)) {
-    return [];
-  }
-  const files = readdirSync(dir).filter((f) => f.endsWith('.json'));
-  const snapshots: VitalSignsSnapshot[] = [];
-  for (const file of files) {
-    try {
-      const raw = readFileSync(join(dir, file), 'utf-8');
-      const parsed = JSON.parse(raw) as VitalSignsSnapshot;
-      if (parsed.schemaVersion === SNAPSHOT_SCHEMA_VERSION) {
-        snapshots.push(parsed);
-      }
-    } catch {
-      // skip malformed files
-    }
-  }
-  snapshots.sort((a, b) => a.timestamp.localeCompare(b.timestamp));
-  return snapshots;
-}

package/src/health/vital-signs.ts

@@ -1,101 +0,0 @@
-// Extended vital-signs metric struct for project-wide trend tracking.
-// Extends the basic snapshot with interfacing risk, LOC, coverage model, coupling.
-
-export const VITAL_SIGNS_SCHEMA_VERSION = 7;
-
-export type CoverageModel = 'none' | 'static' | 'cloud' | 'partial';
-
-export interface SizeBinProfile {
-  smallPct: number;    // < 50 LOC
-  mediumPct: number;   // 50–150 LOC
-  largePct: number;    // 151–300 LOC
-  xlargePct: number;   // > 300 LOC
-}
-
-export interface InterfacingProfile {
-  lowParamPct: number;    // 0–2 params
-  mediumParamPct: number; // 3–4 params
-  highParamPct: number;   // 5–7 params
-  xlParamPct: number;     // 8+ params
-}
-
-export interface VitalSignsCounts {
-  unusedExports: number;
-  deadFiles: number;
-  circularDeps: number;
-  boundaryViolations: number;
-  cloneGroups: number;
-  duplicatedLinesPct: number;
-  highComplexityFunctions: number;
-}
-
-export interface VitalSigns {
-  schemaVersion: number;
-  createdAt: string;
-  projectPath: string;
-
-  // Health score
-  healthScore: number;
-  healthGrade: 'A' | 'B' | 'C' | 'D' | 'F';
-
-  // Issue counts
-  counts: VitalSignsCounts;
-
-  // Risk profiles
-  sizeRisk: SizeBinProfile;
-  interfacingRisk: InterfacingProfile;
-
-  // Fan-in/out metrics
-  fanIn95th: number;
-  couplingConcentrationPct: number;
-
-  // Size
-  totalLoc: number;
-  totalFiles: number;
-  totalNodes: number;
-  totalEdges: number;
-
-  // Coverage
-  coverageModel: CoverageModel;
-  runtimeHotFunctionsPct?: number;
-  runtimeColdFunctionsPct?: number;
-
-  // Optional git context
-  gitSha?: string;
-  gitBranch?: string;
-}
-
-export function createVitalSigns(partial: Partial<VitalSigns> & Pick<VitalSigns, 'projectPath'>): VitalSigns {
-  const now = new Date().toISOString();
-  return {
-    schemaVersion: VITAL_SIGNS_SCHEMA_VERSION,
-    createdAt: now,
-    healthScore: 0,
-    healthGrade: 'F',
-    counts: {
-      unusedExports: 0, deadFiles: 0, circularDeps: 0, boundaryViolations: 0,
-      cloneGroups: 0, duplicatedLinesPct: 0, highComplexityFunctions: 0,
-    },
-    sizeRisk: { smallPct: 0, mediumPct: 0, largePct: 0, xlargePct: 0 },
-    interfacingRisk: { lowParamPct: 0, mediumParamPct: 0, highParamPct: 0, xlParamPct: 0 },
-    fanIn95th: 0,
-    couplingConcentrationPct: 0,
-    totalLoc: 0,
-    totalFiles: 0,
-    totalNodes: 0,
-    totalEdges: 0,
-    coverageModel: 'none',
-    ...partial,
-  };
-}
-
-export function formatVitalSignsSummary(vs: VitalSigns): string {
-  return [
-    `Health: ${vs.healthGrade} (${vs.healthScore.toFixed(1)}/100)`,
-    `Files: ${vs.totalFiles}  LOC: ${vs.totalLoc}  Nodes: ${vs.totalNodes}`,
-    `Unused exports: ${vs.counts.unusedExports}  Dead files: ${vs.counts.deadFiles}`,
-    `Duplication: ${vs.counts.duplicatedLinesPct.toFixed(1)}%  Clones: ${vs.counts.cloneGroups}`,
-    `Circular deps: ${vs.counts.circularDeps}  Boundary violations: ${vs.counts.boundaryViolations}`,
-    `Coverage model: ${vs.coverageModel}`,
-  ].join('\n');
-}

package/src/index.ts

@@ -1,111 +0,0 @@
-export * from './types.js';
-export * from './storage/db.js';
-export * from './storage/node-store.js';
-export * from './storage/edge-store.js';
-export * from './storage/fts-store.js';
-export * from './pipeline/runner.js';
-export * from './pipeline/types.js';
-export * from './pipeline/orchestrator.js';
-export * from './graph/loader.js';
-export * from './graph/analyzer.js';
-export * from './graph/diff.js';
-export * from './graph/dfs.js';
-export * from './watch/watcher.js';
-export * from './export/json.js';
-export * from './export/html.js';
-export * from './export/cypher.js';
-export * from './export/graphml.js';
-export * from './export/svg.js';
-export * from './export/obsidian.js';
-export * from './export/canvas.js';
-export * from './export/mermaid.js';
-export * from './mcp-tools/index.js';
-export * from './staleness/git-staleness.js';
-export * from './search/rrf.js';
-export * from './search/hybrid-query.js';
-export * from './groups/group-config.js';
-export * from './groups/group-search.js';
-export * from './groups/contract-bridge.js';
-export * from './groups/contract-registry.js';
-export * from './groups/group-sync.js';
-export * from './mcp-tools/group-query.js';
-export * from './mcp-tools/group-list.js';
-export * from './mcp-tools/group-sync.js';
-// wiki/wiki-store.js intentionally not re-exported: its WikiPage conflicts with mcp-tools/wiki.ts's WikiPage
-export * from './wiki/prompt-builder.js';
-export * from './wiki/wiki-generator.js';
-export * from './wiki/gist-publisher.js';
-export * from './web/server.js';
-export * from './web/api.js';
-export * from './web/async-jobs.js';
-export * from './web/react-ui.js';
-export * from './web/analyze-api.js';
-export * from './web/mcp-http.js';
-export * from './mcp-resources/index.js';
-export * from './analysis/shape-extractor.js';
-export * from './mcp-tools/tool-map.js';
-export * from './mcp-tools/shape-check.js';
-export * from './mcp-tools/neighbors.js';
-// mcp-tools/graph-query.js re-exported via mcp-tools/index.js to avoid queryGraph duplicate
-export * from './mcp-tools/explain.js';
-export * from './security/sensitive-files.js';
-export * from './validation/extraction-validator.js';
-export * from './security/safe-fetch.js';
-export * from './cache/extraction-cache.js';
-export * from './pipeline/phases/variables.js';
-export * from './pipeline/cluster-only.js';
-export * from './pipeline/phases/field-access.js';
-export * from './pipeline/phases/wildcard-synthesis.js';
-export * from './cli/hooks-install.js';
-export * from './cli/augment.js';
-export * from './cli/setup.js';
-export * from './cli/ai-context.js';
-export * from './cli/doctor.js';
-export * from './cli/eval-server.js';
-export * from './cli/skill-gen.js';
-export * from './cli/check-update.js';
-export * from './skills/platform-skills.js';
-export * from './reporting/graph-report.js';
-export * from './analysis/surprise-scorer.js';
-export * from './analysis/file-classifier.js';
-export * from './pipeline/phases/evidence.js';
-export * from './registry/repo-registry.js';
-export * from './search/ast-chunker.js';
-export * from './wiki/providers.js';
-export * from './pipeline/phases/variables-phase.js';
-export * from './pipeline/phases/wildcard-phase.js';
-export * from './pipeline/phases/framework-detect.js';
-export * from './pipeline/phases/import-resolver.js';
-export * from './analysis/benchmark.js';
-export * from './analysis/cluster-quality.js';
-export * from './analysis/node-similarity.js';
-export * from './graph/ripple-impact.js';
-export * from './analysis/dependency-health.js';
-export * from './parsers/named-bindings.js';
-export * from './parsers/language-parsers.js';
-export * from './cache/augment-cache.js';
-export * from './scope-resolution/evidence-weights.js';
-export * from './export/csv.js';
-export * from './mcp-tools/list-repos.js';
-export * from './mcp-tools/query.js';
-export * from './search/diacritic.js';
-export * from './ingest/url-ingest.js';
-export * from './analysis/corpus-health.js';
-export * from './groups/grpc-extractor.js';
-export * from './groups/topic-extractor.js';
-export * from './groups/service-boundary.js';
-export * from './graph/topo-sort.js';
-export * from './graph/wcc.js';
-export * from './graph/pagerank.js';
-export * from './graph/dead-code.js';
-export * from './graph/import-chain.js';
-export * from './graph/cycles.js';
-export * from './graph/edge-filter.js';
-export * from './graph/node-search.js';
-export * from './graph/merge.js';
-export * from './graph/regex-search.js';
-export * from './graph/normalize-id.js';
-export * from './export/adjacency-matrix.js';
-export * from './ingest/query-memory.js';
-export * from './ingest/git-clone.js';
-export * from './ingest/transcribe.js';

package/src/ingest/git-clone.ts

@@ -1,246 +0,0 @@
-/**
- * Git Clone Utility with SSRF Protection
- *
- * Shallow-clones repositories into ~/.monograph/repos/{name}/.
- * If already cloned, runs `git pull --ff-only` instead.
- *
- * SSRF protection: only https:// and http:// are allowed,
- * and private/internal IP ranges are blocked.
- */
-
-import { spawn } from 'child_process';
-import path from 'path';
-import os from 'os';
-import fs from 'fs/promises';
-import { isIP } from 'net';
-
-// ── SSRF validation ───────────────────────────────────────────────────────────
-
-const BLOCKED_HOSTNAMES = new Set([
-  'localhost',
-  'metadata.google.internal',
-  'metadata.azure.com',
-  'metadata.internal',
-  'metadata.goog',
-]);
-
-/**
- * Validate a git URL to prevent SSRF attacks.
- *
- * Blocks:
- * - Non-http(s) schemes
- * - Private IPv4 ranges (127.x, 10.x, 172.16-31.x, 192.168.x, 169.254.x, etc.)
- * - IPv6 private ranges (::1, fc00::/7, fe80::/10, ::ffff:...)
- * - Cloud metadata hostnames
- * - Numeric IP encodings (decimal/hex)
- *
- * @throws {Error} with a descriptive message if the URL is not safe.
- */
-export function validateGitUrl(url: string): void {
-  let parsed: URL;
-  try {
-    parsed = new URL(url);
-  } catch {
-    throw new Error('Invalid URL');
-  }
-
-  if (!['https:', 'http:'].includes(parsed.protocol)) {
-    throw new Error('Only https:// and http:// git URLs are allowed');
-  }
-
-  const host = parsed.hostname.toLowerCase();
-
-  if (BLOCKED_HOSTNAMES.has(host)) {
-    throw new Error('Cloning from private/internal addresses is not allowed');
-  }
-
-  // Strip IPv6 brackets
-  let normalizedHost = host;
-  if (host.startsWith('[') && host.endsWith(']')) {
-    normalizedHost = host.slice(1, -1);
-  }
-
-  // Detect IPv6
-  const isIPv6 = isIP(normalizedHost) === 6 || normalizedHost.includes(':');
-  if (isIPv6) {
-    assertNotPrivateIPv6(normalizedHost);
-    return;
-  }
-
-  // Detect IPv4
-  if (isIP(normalizedHost) === 4) {
-    assertNotPrivateIPv4(normalizedHost);
-    return;
-  }
-
-  // Block numeric IP encodings (decimal: 2130706433, hex: 0x7f000001)
-  if (/^\d+$/.test(host) || /^0x[0-9a-f]+$/i.test(host)) {
-    throw new Error('Cloning from private/internal addresses is not allowed');
-  }
-
-  // Standard IPv4 dotted-notation private checks
-  if (
-    /^127\./.test(host) ||
-    /^10\./.test(host) ||
-    /^172\.(1[6-9]|2\d|3[01])\./.test(host) ||
-    /^192\.168\./.test(host) ||
-    /^169\.254\./.test(host) ||
-    /^0\./.test(host) ||
-    host === '0.0.0.0' ||
-    /^100\.(6[4-9]|[7-9]\d|1[01]\d|12[0-7])\./.test(host) ||
-    /^198\.1[89]\./.test(host)
-  ) {
-    throw new Error('Cloning from private/internal addresses is not allowed');
-  }
-}
-
-function assertNotPrivateIPv6(ip: string): void {
-  const lower = ip.toLowerCase();
-  if (lower === '::1' || lower === '0:0:0:0:0:0:0:1') {
-    throw new Error('Cloning from private/internal addresses is not allowed');
-  }
-  if (lower === '::' || lower === '0:0:0:0:0:0:0:0') {
-    throw new Error('Cloning from private/internal addresses is not allowed');
-  }
-  if (lower.startsWith('fc') || lower.startsWith('fd')) {
-    throw new Error('Cloning from private/internal addresses is not allowed');
-  }
-  if (
-    lower.startsWith('fe80') ||
-    lower.startsWith('fe8') ||
-    lower.startsWith('fe9') ||
-    lower.startsWith('fea') ||
-    lower.startsWith('feb')
-  ) {
-    throw new Error('Cloning from private/internal addresses is not allowed');
-  }
-  if (lower.startsWith('::ffff:') || lower.includes(':ffff:')) {
-    throw new Error('Cloning from private/internal addresses is not allowed');
-  }
-}
-
-function assertNotPrivateIPv4(ip: string): void {
-  const parts = ip.split('.').map(Number);
-  const [a, b] = parts;
-  if (
-    a === 127 ||
-    a === 10 ||
-    (a === 172 && b >= 16 && b <= 31) ||
-    (a === 192 && b === 168) ||
-    (a === 169 && b === 254) ||
-    a === 0 ||
-    (a === 100 && b >= 64 && b <= 127) ||
-    (a === 198 && (b === 18 || b === 19))
-  ) {
-    throw new Error('Cloning from private/internal addresses is not allowed');
-  }
-}
-
-// ── URL helpers ────────────────────────────────────────────────────────────────
-
-/**
- * Extract the repository name from an HTTPS or SSH git URL.
- *
- * @example
- * extractRepoName('https://github.com/org/repo.git') // 'repo'
- * extractRepoName('git@github.com:org/repo.git')     // 'repo'
- */
-export function extractRepoName(url: string): string {
-  const cleaned = url.replace(/\/+$/, '');
-  const lastSegment = cleaned.split(/[/:]/).pop() ?? 'unknown';
-  const name = lastSegment.replace(/\.git$/, '');
-  // Guard against path traversal: reject segments containing .. or path separators
-  if (!name || name.includes('..') || name.includes('/') || name.includes('\\')) {
-    return 'unknown-repo';
-  }
-  return name;
-}
-
-/**
- * Get the default clone target directory for a repository name.
- * Repositories are stored in `~/.monograph/repos/{repoName}`.
- */
-export function getCloneDir(repoName: string): string {
-  return path.join(os.homedir(), '.monograph', 'repos', repoName);
-}
-
-// ── Clone / pull ───────────────────────────────────────────────────────────────
-
-export interface CloneProgress {
-  phase: 'cloning' | 'pulling';
-  message: string;
-}
-
-/**
- * Clone or pull a git repository with SSRF protection.
- *
- * - If `targetDir/.git` does not exist: `git clone --depth 1 <url> <targetDir>`
- * - If `targetDir/.git` exists: `git pull --ff-only`
- *
- * The URL is validated against SSRF rules before any network operation.
- *
- * @param url       - The git remote URL (must be https:// or http://).
- * @param targetDir - Local directory to clone into.
- * @param onProgress - Optional progress callback.
- * @returns Resolves to `targetDir` on success.
- */
-export async function cloneOrPull(
-  url: string,
-  targetDir: string,
-  onProgress?: (progress: CloneProgress) => void,
-): Promise<string> {
-  // Always validate before any operation
-  validateGitUrl(url);
-
-  const hasGitDir = await fs.access(path.join(targetDir, '.git')).then(
-    () => true,
-    () => false,
-  );
-
-  if (hasGitDir) {
-    onProgress?.({ phase: 'pulling', message: 'Pulling latest changes…' });
-    await runGit(['pull', '--ff-only'], targetDir);
-  } else {
-    await fs.mkdir(path.dirname(targetDir), { recursive: true });
-    onProgress?.({ phase: 'cloning', message: `Cloning ${url}…` });
-    await runGit(['clone', '--depth', '1', url, targetDir]);
-  }
-
-  return targetDir;
-}
-
-// ── git subprocess ─────────────────────────────────────────────────────────────
-
-function runGit(args: string[], cwd?: string): Promise<void> {
-  return new Promise((resolve, reject) => {
-    const proc = spawn('git', args, {
-      cwd,
-      stdio: ['ignore', 'pipe', 'pipe'],
-      env: {
-        ...process.env,
-        GIT_TERMINAL_PROMPT: '0',
-        GIT_ASKPASS: process.platform === 'win32' ? 'echo' : '/bin/true',
-      },
-    });
-
-    let stderr = '';
-    proc.stderr.on('data', (chunk: Buffer) => {
-      stderr += chunk;
-    });
-
-    proc.on('close', code => {
-      if (code === 0) {
-        resolve();
-      } else {
-        if (stderr.trim()) {
-          console.error(`git ${args[0]} stderr: ${stderr.trim()}`);
-        }
-        reject(new Error(`git ${args[0]} failed (exit code ${code})`));
-      }
-    });
-
-    proc.on('error', err => {
-      reject(new Error(`Failed to spawn git: ${err.message}`));
-    });
-  });
-}

package/src/ingest/query-memory.ts

@@ -1,132 +0,0 @@
-/**
- * Q&A memory feedback loop.
- *
- * Mirrors graphify's `save_query_result`: saves question/answer pairs as
- * Markdown files with YAML front-matter into a memory directory.  On the next
- * rebuild those files are treated as document nodes, so the graph grows smarter
- * from both what you add AND what you ask.
- *
- * Intended for use after `monographQuery` / `monographExplain` calls so that
- * insights are persisted and available during future pipeline runs.
- */
-
-import { mkdirSync, writeFileSync } from 'fs';
-import { join } from 'path';
-
-// ── Types ──────────────────────────────────────────────────────────────────────
-
-export interface SaveQueryResultOptions {
-  /** Question / query string. */
-  question: string;
-  /** Answer produced by the graph query. */
-  answer: string;
-  /**
-   * Directory where memory files are written.
-   * Defaults to `<cwd>/monograph-out/memory`.
-   */
-  memoryDir?: string;
-  /** Free-form query type label (e.g. "query", "explain", "impact"). Default: "query". */
-  queryType?: string;
-  /**
-   * Up to 10 node ids / names that were the primary sources for the answer.
-   * These are stored in front-matter so a future extraction pass can wire up
-   * edges to the originating nodes.
-   */
-  sourceNodes?: string[];
-}
-
-export interface SaveQueryResultOutput {
-  /** Absolute path of the written Markdown file. */
-  filePath: string;
-  /** ISO-8601 timestamp of when the file was written. */
-  writtenAt: string;
-}
-
-// ── Helpers ────────────────────────────────────────────────────────────────────
-
-function yamlStr(s: string): string {
-  return s.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, ' ').replace(/\r/g, '');
-}
-
-function slug(question: string): string {
-  return question
-    .toLowerCase()
-    .replace(/[^\w]/g, '_')
-    .slice(0, 50)
-    .replace(/^_+|_+$/g, '');
-}
-
-function isoNow(): string {
-  return new Date().toISOString();
-}
-
-function timestamp(): string {
-  return new Date().toISOString().replace(/[-:T]/g, '').replace(/\..+/, '').slice(0, 15);
-}
-
-// ── Main export ────────────────────────────────────────────────────────────────
-
-/**
- * Save a Q&A query result as a Markdown file in the memory directory.
- *
- * The file has YAML front-matter that monograph's document extractor reads
- * as node metadata.  The body contains the question and answer in a
- * human-readable format.
- *
- * @param options - Query options including question, answer, and target dir.
- * @returns The file path and write timestamp.
- */
-export function saveQueryResult(options: SaveQueryResultOptions): SaveQueryResultOutput {
-  const {
-    question,
-    answer,
-    memoryDir = join(process.cwd(), 'monograph-out', 'memory'),
-    queryType = 'query',
-    sourceNodes,
-  } = options;
-
-  mkdirSync(memoryDir, { recursive: true });
-
-  const now = isoNow();
-  const ts = timestamp();
-  const s = slug(question);
-  const filename = `query_${ts}_${s}.md`;
-  const filePath = join(memoryDir, filename);
-
-  const frontmatterLines = [
-    '---',
-    `type: "${queryType}"`,
-    `date: "${now}"`,
-    `question: "${yamlStr(question)}"`,
-    'contributor: "monograph"',
-  ];
-
-  if (sourceNodes && sourceNodes.length > 0) {
-    const limited = sourceNodes.slice(0, 10);
-    const nodesStr = limited.map(n => `"${yamlStr(n)}"`).join(', ');
-    frontmatterLines.push(`source_nodes: [${nodesStr}]`);
-  }
-
-  frontmatterLines.push('---');
-
-  const bodyLines = [
-    '',
-    `# Q: ${question}`,
-    '',
-    '## Answer',
-    '',
-    answer,
-  ];
-
-  if (sourceNodes && sourceNodes.length > 0) {
-    bodyLines.push('', '## Source Nodes', '');
-    for (const n of sourceNodes) {
-      bodyLines.push(`- ${n}`);
-    }
-  }
-
-  const content = [...frontmatterLines, ...bodyLines].join('\n');
-  writeFileSync(filePath, content, 'utf-8');
-
-  return { filePath, writtenAt: now };
-}