openlore 2.0.0

package/dist/core/analyzer/architecture-writer.js

@@ -0,0 +1,209 @@
+/**
+ * Architecture Writer
+ *
+ * Shared logic for building a high-level architecture overview from cached
+ * static analysis artifacts (dependency-graph.json + llm-context.json).
+ *
+ * Used by:
+ *   - MCP tool `get_architecture_overview` (mcp.ts)
+ *   - `openlore analyze` — writes ARCHITECTURE.md to the project root
+ */
+import { writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+// ============================================================================
+// HELPERS
+// ============================================================================
+/**
+ * Infer a module cluster's architectural role from aggregate metrics.
+ */
+export function inferClusterRole(entryCount, hubCount, fileCount) {
+    if (entryCount > fileCount * 0.5)
+        return 'entry_layer'; // most files are entry points
+    if (hubCount > 0 && entryCount > 0)
+        return 'orchestrator'; // both hubs and entries
+    if (hubCount > 0)
+        return 'core_utilities'; // heavily depended-on helpers
+    if (entryCount > 0)
+        return 'api_layer'; // exposed but not hub-heavy
+    return 'internal'; // implementation detail
+}
+// ============================================================================
+// BUILD
+// ============================================================================
+/**
+ * Build an ArchitectureOverview from pre-loaded dependency graph and LLM context.
+ * Both can be null if one artifact is missing; at least one must be non-null.
+ *
+ * @param depGraph  Parsed dependency-graph.json (or null)
+ * @param ctx       Parsed llm-context.json (or null)
+ * @param absDir    Absolute project root path — used to normalize cluster file paths
+ */
+export function buildArchitectureOverview(depGraph, ctx, absDir) {
+    // Cluster files use absolute paths; call graph uses relative paths.
+    // Normalise both to relative using absDir as base.
+    const toRel = (p) => p.startsWith(absDir) ? p.slice(absDir.length + 1) : p;
+    // Build sets of relative filePaths for hubs / entry points from call graph
+    const hubFiles = new Set((ctx?.callGraph?.hubFunctions ?? []).map(h => toRel(h.filePath)));
+    const entryFiles = new Set((ctx?.callGraph?.entryPoints ?? []).map(e => toRel(e.filePath)));
+    // Build inter-cluster dependency edges from dep graph edges
+    const clusterOfFile = new Map(); // absolute path → cluster id
+    for (const cl of depGraph?.clusters ?? []) {
+        for (const fileId of cl.files) {
+            clusterOfFile.set(fileId, cl.id);
+        }
+    }
+    const clusterEdges = new Map();
+    for (const edge of depGraph?.edges ?? []) {
+        const from = clusterOfFile.get(edge.source);
+        const to = clusterOfFile.get(edge.target);
+        if (from && to && from !== to) {
+            if (!clusterEdges.has(from))
+                clusterEdges.set(from, new Set());
+            clusterEdges.get(from).add(to);
+        }
+    }
+    // Summarize clusters
+    const clusters = (depGraph?.clusters ?? [])
+        .map(cl => {
+        const relFiles = cl.files.map(toRel);
+        const clusterHubCount = relFiles.filter(f => hubFiles.has(f)).length;
+        const clusterEntryCount = relFiles.filter(f => entryFiles.has(f)).length;
+        const role = inferClusterRole(clusterEntryCount, clusterHubCount, cl.files.length);
+        const dependsOn = [...(clusterEdges.get(cl.id) ?? [])];
+        return {
+            id: cl.id,
+            name: cl.name ?? cl.id,
+            fileCount: cl.files.length,
+            role,
+            entryPointCount: clusterEntryCount,
+            hubCount: clusterHubCount,
+            dependsOn,
+            keyFiles: relFiles
+                .filter(f => hubFiles.has(f) || entryFiles.has(f))
+                .slice(0, 5),
+        };
+    })
+        .sort((a, b) => b.fileCount - a.fileCount);
+    const globalEntryPoints = (ctx?.callGraph?.entryPoints ?? [])
+        .slice(0, 20)
+        .map(n => ({ name: n.name, file: n.filePath, language: n.language }));
+    const criticalHubs = (ctx?.callGraph?.hubFunctions ?? [])
+        .slice(0, 10)
+        .map(n => ({ name: n.name, file: n.filePath, fanIn: n.fanIn, fanOut: n.fanOut }));
+    return {
+        generatedAt: new Date().toISOString(),
+        summary: {
+            totalFiles: depGraph?.statistics.nodeCount ?? 0,
+            totalClusters: clusters.length,
+            totalEdges: depGraph?.statistics.edgeCount ?? 0,
+            cycles: depGraph?.cycles.length ?? 0,
+            layerViolations: ctx?.callGraph?.layerViolations?.length ?? 0,
+        },
+        clusters,
+        globalEntryPoints,
+        criticalHubs,
+    };
+}
+// ============================================================================
+// MARKDOWN RENDERER
+// ============================================================================
+const ROLE_BADGE = {
+    entry_layer: 'entry layer',
+    orchestrator: 'orchestrator',
+    core_utilities: 'core utilities',
+    api_layer: 'API layer',
+    internal: 'internal',
+};
+/**
+ * Render an ArchitectureOverview as a Markdown document (ARCHITECTURE.md).
+ */
+export function renderArchitectureMarkdown(overview) {
+    const { summary, clusters, globalEntryPoints, criticalHubs } = overview;
+    const lines = [];
+    lines.push('# Architecture Overview');
+    lines.push('');
+    lines.push(`> Generated by \`openlore analyze\` on ${overview.generatedAt.slice(0, 10)}.`);
+    lines.push('> Re-run `openlore analyze` to refresh.');
+    lines.push('');
+    // Summary table
+    lines.push('## Summary');
+    lines.push('');
+    lines.push('| Metric | Value |');
+    lines.push('|--------|-------|');
+    lines.push(`| Files | ${summary.totalFiles} |`);
+    lines.push(`| Module clusters | ${summary.totalClusters} |`);
+    lines.push(`| Dependency edges | ${summary.totalEdges} |`);
+    if (summary.cycles > 0) {
+        lines.push(`| ⚠️ Cycles | ${summary.cycles} |`);
+    }
+    if (summary.layerViolations > 0) {
+        lines.push(`| ⚠️ Layer violations | ${summary.layerViolations} |`);
+    }
+    lines.push('');
+    // Cluster map
+    lines.push('## Module Clusters');
+    lines.push('');
+    lines.push('Clusters are groups of tightly coupled files detected by static dependency analysis.');
+    lines.push('');
+    lines.push('| Cluster | Role | Files | Depends on |');
+    lines.push('|---------|------|-------|------------|');
+    for (const cl of clusters) {
+        const role = ROLE_BADGE[cl.role] ?? cl.role;
+        const deps = cl.dependsOn.length > 0
+            ? cl.dependsOn.map(id => clusters.find(c => c.id === id)?.name ?? id).join(', ')
+            : '—';
+        lines.push(`| **${cl.name}** | \`${role}\` | ${cl.fileCount} | ${deps} |`);
+    }
+    lines.push('');
+    // Per-cluster detail (only for clusters with key files)
+    const withKeys = clusters.filter(cl => cl.keyFiles.length > 0);
+    if (withKeys.length > 0) {
+        lines.push('### Key files per cluster');
+        lines.push('');
+        for (const cl of withKeys) {
+            lines.push(`**${cl.name}** (\`${ROLE_BADGE[cl.role] ?? cl.role}\`)`);
+            for (const f of cl.keyFiles) {
+                lines.push(`- \`${f}\``);
+            }
+            lines.push('');
+        }
+    }
+    // Entry points
+    if (globalEntryPoints.length > 0) {
+        lines.push('## Entry Points');
+        lines.push('');
+        lines.push('Functions with no internal callers — the public-facing roots of the codebase.');
+        lines.push('');
+        for (const ep of globalEntryPoints) {
+            lines.push(`- \`${ep.name}\` — \`${ep.file}\` (${ep.language})`);
+        }
+        lines.push('');
+    }
+    // Critical hubs
+    if (criticalHubs.length > 0) {
+        lines.push('## Critical Hubs');
+        lines.push('');
+        lines.push('High fan-in functions — many callers depend on them. Modify with care.');
+        lines.push('');
+        lines.push('| Function | File | Fan-in | Fan-out |');
+        lines.push('|----------|------|--------|---------|');
+        for (const hub of criticalHubs) {
+            lines.push(`| \`${hub.name}\` | \`${hub.file}\` | ${hub.fanIn} | ${hub.fanOut} |`);
+        }
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+// ============================================================================
+// FILE WRITER
+// ============================================================================
+/**
+ * Write ARCHITECTURE.md to the project root.
+ * Returns the path written.
+ */
+export async function writeArchitectureMd(rootPath, overview) {
+    const outPath = join(rootPath, 'ARCHITECTURE.md');
+    await writeFile(outPath, renderArchitectureMarkdown(overview), 'utf-8');
+    return outPath;
+}
+//# sourceMappingURL=architecture-writer.js.map

package/dist/core/analyzer/architecture-writer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"architecture-writer.js","sourceRoot":"","sources":["../../../src/core/analyzer/architecture-writer.ts"],"names":[],"mappings":"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"}

package/dist/core/analyzer/artifact-generator.d.ts

@@ -0,0 +1,261 @@
+/**
+ * Analysis Artifact Generator
+ *
+ * Takes all analysis results and generates structured output files
+ * that will be consumed by the LLM generation phase and optionally by humans.
+ */
+import type { RepositoryMap } from './repository-mapper.js';
+import type { DependencyGraphResult } from './dependency-graph.js';
+import type { UIComponent } from './ui-component-extractor.js';
+import type { SchemaTable } from './schema-extractor.js';
+import type { RouteInventory } from './http-route-parser.js';
+import type { MiddlewareEntry } from './middleware-extractor.js';
+import type { EnvVar } from './env-extractor.js';
+/**
+ * Heuristic to detect test/spec files across languages.
+ * Excludes them from call graph analysis — test helpers inflate fanIn,
+ * and test functions are never "unreachable" by definition.
+ *
+ * Patterns covered:
+ *   TypeScript/JS: *.test.ts, *.spec.ts, *.test.tsx, __tests__/*, test_*.ts
+ *   Python:        test_*.py, *_test.py, tests/*.py
+ *   Go:            *_test.go
+ *   Rust:          files with #[cfg(test)] (not detectable here — excluded by directory pattern)
+ *   Java/Kotlin:   *Test.java, *Spec.kt
+ */
+export declare function isTestFile(filePath: string): boolean;
+/**
+ * Architecture layer information
+ */
+export interface ArchitectureLayer {
+    name: string;
+    purpose: string;
+    files: string[];
+    representativeFile: string | null;
+}
+/**
+ * Detected domain (maps to OpenSpec spec)
+ */
+export interface DetectedDomain {
+    name: string;
+    suggestedSpecPath: string;
+    files: string[];
+    entities: string[];
+    keyFile: string | null;
+}
+/**
+ * Entry point information
+ */
+export interface EntryPointInfo {
+    file: string;
+    type: 'application-entry' | 'api-entry' | 'test-entry' | 'build-entry';
+    initializes: string[];
+}
+/**
+ * Data flow information
+ */
+export interface DataFlowInfo {
+    sources: string[];
+    sinks: string[];
+    transformers: string[];
+}
+/**
+ * Key files by category
+ */
+export interface KeyFiles {
+    schemas: string[];
+    config: string[];
+    auth: string[];
+    database: string[];
+    routes: string[];
+    services: string[];
+}
+/**
+ * Repository structure (JSON artifact)
+ */
+export interface RepoStructure {
+    projectName: string;
+    projectType: string;
+    frameworks: string[];
+    architecture: {
+        pattern: 'layered' | 'modular' | 'microservices' | 'monolith' | 'unknown';
+        layers: ArchitectureLayer[];
+    };
+    domains: DetectedDomain[];
+    entryPoints: EntryPointInfo[];
+    dataFlow: DataFlowInfo;
+    keyFiles: KeyFiles;
+    /** Detected UI components (React, Vue, Svelte, Angular) */
+    uiComponents: UIComponent[];
+    /** Detected database schema tables */
+    schemas: SchemaTable[];
+    /** Aggregated HTTP route inventory */
+    routeInventory: RouteInventory;
+    /** Detected middleware entries */
+    middleware: MiddlewareEntry[];
+    /** Detected environment variables */
+    envVars: EnvVar[];
+    statistics: {
+        totalFiles: number;
+        analyzedFiles: number;
+        skippedFiles: number;
+        avgFileScore: number;
+        nodeCount: number;
+        edgeCount: number;
+        cycleCount: number;
+        clusterCount: number;
+    };
+}
+/**
+ * LLM context phase
+ */
+export interface LLMContextPhase {
+    purpose: string;
+    files: Array<{
+        path: string;
+        content?: string;
+        tokens: number;
+    }>;
+    totalTokens?: number;
+    estimatedTokens?: number;
+}
+/**
+ * LLM context preparation
+ */
+export interface LLMContext {
+    phase1_survey: LLMContextPhase;
+    phase2_deep: LLMContextPhase;
+    phase3_validation: LLMContextPhase;
+    /** Compact signatures for ALL analyzed files — used by Stage 1 instead of bare file paths */
+    signatures?: import('./signature-extractor.js').FileSignatureMap[];
+    /** Static call graph: function→function relationships across all TS/Python files */
+    callGraph?: import('./call-graph.js').SerializedCallGraph;
+}
+/**
+ * All generated artifacts
+ */
+export interface AnalysisArtifacts {
+    repoStructure: RepoStructure;
+    summaryMarkdown: string;
+    dependencyDiagram: string;
+    llmContext: LLMContext;
+}
+/**
+ * Optional enrichment data produced by new extractors, passed into generate().
+ */
+export interface EnrichmentData {
+    uiComponents?: UIComponent[];
+    schemas?: SchemaTable[];
+    routeInventory?: RouteInventory;
+    middleware?: MiddlewareEntry[];
+    envVars?: EnvVar[];
+}
+/**
+ * Options for artifact generation
+ */
+export interface ArtifactGeneratorOptions {
+    /** Root directory of the project */
+    rootDir: string;
+    /** Output directory for artifacts */
+    outputDir: string;
+    /** Maximum files to include in LLM deep analysis */
+    maxDeepAnalysisFiles?: number;
+    /** Maximum files for validation phase */
+    maxValidationFiles?: number;
+    /** Approximate tokens per character for estimation */
+    tokensPerChar?: number;
+}
+/**
+ * Convert a serialised RepoStructure (from repo-structure.json on disk) back
+ * to a minimal RepositoryMap-compatible object.  Only the fields that
+ * consumers of the cached-analysis path actually use are populated; the
+ * file-level arrays (`allFiles`, `highValueFiles`, etc.) are left empty
+ * because the original per-file data is not persisted to disk.
+ */
+export declare function repoStructureToRepoMap(rs: RepoStructure): RepositoryMap;
+/**
+ * Generates analysis artifacts from repository map and dependency graph
+ */
+export declare class AnalysisArtifactGenerator {
+    private options;
+    constructor(options: ArtifactGeneratorOptions);
+    /**
+     * Generate all artifacts
+     */
+    generate(repoMap: RepositoryMap, depGraph: DependencyGraphResult, enrichment?: EnrichmentData): Promise<AnalysisArtifacts>;
+    /**
+     * Generate and save all artifacts to disk
+     */
+    generateAndSave(repoMap: RepositoryMap, depGraph: DependencyGraphResult, enrichment?: EnrichmentData): Promise<AnalysisArtifacts>;
+    /**
+     * Generate repo-structure.json
+     */
+    private generateRepoStructure;
+    /**
+     * Format project type for display
+     */
+    private formatProjectType;
+    /**
+     * Detect architecture pattern from code structure
+     */
+    private detectArchitecturePattern;
+    /**
+     * Generate architecture layers
+     */
+    private generateArchitectureLayers;
+    /**
+     * Generate domains from clusters
+     */
+    private generateDomains;
+    /**
+     * Normalize domain name for OpenSpec path
+     */
+    private normalizeDomainName;
+    /**
+     * Extract potential entity names from files
+     */
+    private extractEntities;
+    /**
+     * Generate entry points information
+     */
+    private generateEntryPoints;
+    /**
+     * Generate data flow information
+     */
+    private generateDataFlow;
+    /**
+     * Generate key files by category
+     */
+    private generateKeyFiles;
+    /**
+     * Generate SUMMARY.md
+     */
+    private generateSummaryMarkdown;
+    /**
+     * Format project type for human reading
+     */
+    private formatProjectTypeReadable;
+    /**
+     * Generate dependency diagram in Mermaid format
+     */
+    private generateDependencyDiagram;
+    /**
+     * Generate LLM context preparation
+     */
+    private generateLLMContext;
+}
+/**
+ * Writes the full call graph (nodes, edges, classes, inheritance) to SQLite.
+ * Full rebuild on every analyze — incremental updates handled by the watcher.
+ * Additive alongside llm-context.json; backward compat preserved.
+ */
+export declare function writeEdgesToSQLite(callGraph: import('./call-graph.js').SerializedCallGraph, dbPath: string, rootPath?: string): Promise<void>;
+/**
+ * Generate all artifacts
+ */
+export declare function generateArtifacts(repoMap: RepositoryMap, depGraph: DependencyGraphResult, options: ArtifactGeneratorOptions): Promise<AnalysisArtifacts>;
+/**
+ * Generate and save all artifacts
+ */
+export declare function generateAndSaveArtifacts(repoMap: RepositoryMap, depGraph: DependencyGraphResult, options: ArtifactGeneratorOptions): Promise<AnalysisArtifacts>;
+//# sourceMappingURL=artifact-generator.d.ts.map

package/dist/core/analyzer/artifact-generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact-generator.d.ts","sourceRoot":"","sources":["../../../src/core/analyzer/artifact-generator.ts"],"names":[],"mappings":"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"}