@phuetz/code-buddy 1.6.1 → 2.1.0

package/dist/analytics/dashboard.js

@@ -15,6 +15,7 @@ import fs from 'fs-extra';
 import * as path from 'path';
 import * as os from 'os';
 import { LRUCache } from '../utils/lru-cache.js';
+import { readJsonAtomic, writeJsonAtomic } from '../utils/atomic-write.js';
 // Model pricing (per 1M tokens)
 const MODEL_PRICING = {
     'grok-4-latest': { input: 3.0, output: 15.0 },
@@ -99,19 +100,19 @@ export class AnalyticsDashboard extends EventEmitter {
             // Load sessions
             const sessionsPath = path.join(this.dataDir, 'sessions.json');
             if (await fs.pathExists(sessionsPath)) {
-                const data = await fs.readJSON(sessionsPath);
+                const data = await readJsonAtomic(sessionsPath, {});
                 this.sessions.fromObject(data);
             }
             // Load tools
             const toolsPath = path.join(this.dataDir, 'tools.json');
             if (await fs.pathExists(toolsPath)) {
-                const data = await fs.readJSON(toolsPath);
+                const data = await readJsonAtomic(toolsPath, {});
                 this.tools.fromObject(data);
             }
             // Load daily stats
             const statsPath = path.join(this.dataDir, 'daily-stats.json');
             if (await fs.pathExists(statsPath)) {
-                const data = await fs.readJSON(statsPath);
+                const data = await readJsonAtomic(statsPath, {});
                 this.dailyStats.fromObject(data);
             }
         }
@@ -124,9 +125,9 @@ export class AnalyticsDashboard extends EventEmitter {
      */
     async saveData() {
         try {
-            await fs.writeJSON(path.join(this.dataDir, 'sessions.json'), this.sessions.toObject(), { spaces: 2 });
-            await fs.writeJSON(path.join(this.dataDir, 'tools.json'), this.tools.toObject(), { spaces: 2 });
-            await fs.writeJSON(path.join(this.dataDir, 'daily-stats.json'), this.dailyStats.toObject(), { spaces: 2 });
+            await writeJsonAtomic(path.join(this.dataDir, 'sessions.json'), this.sessions.toObject(), { mode: 0o600 });
+            await writeJsonAtomic(path.join(this.dataDir, 'tools.json'), this.tools.toObject(), { mode: 0o600 });
+            await writeJsonAtomic(path.join(this.dataDir, 'daily-stats.json'), this.dailyStats.toObject(), { mode: 0o600 });
         }
         catch {
             // Ignore save errors
@@ -613,7 +614,7 @@ export class AnalyticsDashboard extends EventEmitter {
      */
     async saveConfig() {
         const configPath = path.join(this.dataDir, 'config.json');
-        await fs.writeJSON(configPath, this.config, { spaces: 2 });
+        await writeJsonAtomic(configPath, this.config, { mode: 0o600 });
     }
     /**
      * Reset all analytics

package/dist/analytics/index.d.ts

@@ -15,5 +15,7 @@ export { PersistentAnalytics, CostBudget, UsageEvent, AnalyticsSummary, CostAler
 export { MetricsDashboard, getMetricsDashboard, resetMetricsDashboard, type DashboardMetrics, type TokenMetrics, type CostMetrics, type ToolMetrics, type SessionMetrics, type PerformanceMetrics, } from './metrics-dashboard.js';
 export { ToolAnalytics, getToolAnalytics, resetToolAnalytics, type ToolExecution, type ToolStats, type ToolChain, type ToolSuggestion, type ToolAnalyticsSnapshot, } from './tool-analytics.js';
 export { CostPredictor, type CostPrediction, } from './cost-predictor.js';
+export { aggregateCostReport, buildCostReport, inferCostProvider, parseCostSince, type CostBreakdown, type CostGroupBy, type CostPricing, type CostPricingResolver, type CostReport, type CostReportOptions, type CostSessionEntry, type CostTokenTotals, } from './cost-report.js';
 export { BudgetAlertManager, type BudgetAlert, type BudgetAlertConfig, } from './budget-alerts.js';
 export { PrometheusExporter, getPrometheusExporter, createMetricsCollector, type PrometheusConfig, } from './prometheus-exporter.js';
+export { explainRepository, type RepoExplainDepth, type RepoExplanation, type RepoExplanationInput, } from './repo-explainer.js';

package/dist/analytics/index.js

@@ -15,6 +15,8 @@ export { PersistentAnalytics, getPersistentAnalytics, resetPersistentAnalytics,
 export { MetricsDashboard, getMetricsDashboard, resetMetricsDashboard, } from './metrics-dashboard.js';
 export { ToolAnalytics, getToolAnalytics, resetToolAnalytics, } from './tool-analytics.js';
 export { CostPredictor, } from './cost-predictor.js';
+export { aggregateCostReport, buildCostReport, inferCostProvider, parseCostSince, } from './cost-report.js';
 export { BudgetAlertManager, } from './budget-alerts.js';
 export { PrometheusExporter, getPrometheusExporter, createMetricsCollector, } from './prometheus-exporter.js';
+export { explainRepository, } from './repo-explainer.js';
 //# sourceMappingURL=index.js.map

package/dist/analytics/repo-explainer-collector.d.ts

@@ -0,0 +1,13 @@
+/** Read-only, best-effort collection for `buddy explain`. */
+import type { RepoExplainDepth, RepoExplanationInput } from './repo-explainer.js';
+export interface RepoExplanationCollectorOptions {
+    rootPath: string;
+    depth: RepoExplainDepth;
+    generatedAt: Date;
+}
+/**
+ * Collect every source independently. Failures are converted to notices, so a
+ * readable artifact can still be produced for an empty directory, a non-Git
+ * project, malformed manifests, or an unavailable Code Explorer binary.
+ */
+export declare function collectRepoExplanationInput(options: RepoExplanationCollectorOptions): Promise<RepoExplanationInput>;

package/dist/analytics/repo-explainer-collector.js

@@ -0,0 +1,351 @@
+/** Read-only, best-effort collection for `buddy explain`. */
+import { execFileSync } from 'node:child_process';
+import { realpathSync } from 'node:fs';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import fg from 'fast-glob';
+import { RepoProfiler } from '../agent/repo-profiler.js';
+import { CodeExplorerManager } from '../plugins/code-explorer/CodeExplorerManager.js';
+import { generateDocs } from '../tools/doc-generator.js';
+import { logger } from '../utils/logger.js';
+import { generateEvolutionReport } from './code-evolution.js';
+import { generateHeatmap } from './codebase-heatmap.js';
+import { analyzeComplexity } from './complexity-analyzer.js';
+const TREE_IGNORES = [
+    '**/.git/**',
+    '**/.codebuddy/**',
+    '**/.codeexplorer/**',
+    '**/.gitnexus/**',
+    '**/node_modules/**',
+    '**/vendor/**',
+    '**/dist/**',
+    '**/build/**',
+    '**/out/**',
+    '**/target/**',
+    '**/coverage/**',
+    '**/.next/**',
+    '**/.nuxt/**',
+    '**/.cache/**',
+    '**/__pycache__/**',
+    '**/.venv/**',
+    '**/venv/**',
+];
+const JS_TS_EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.jsx']);
+const EVOLUTION_EXTENSIONS = new Set([
+    '.ts',
+    '.tsx',
+    '.js',
+    '.jsx',
+    '.py',
+    '.go',
+    '.rs',
+    '.java',
+    '.cpp',
+    '.c',
+    '.h',
+]);
+const TEST_RE = /(?:^|\/)(?:tests?|__tests__|spec)(?:\/|$)|\.(?:test|spec)\.[^/]+$|_test\.[^/]+$/i;
+async function bestEffort(stage, fallback, notices, operation) {
+    try {
+        return await operation();
+    }
+    catch (error) {
+        logger.debug(`[repo-explainer] ${stage} unavailable`, {
+            error: error instanceof Error ? error.message : String(error),
+        });
+        notices.push(`${stage} indisponible; le reste de l’analyse a continué.`);
+        return fallback;
+    }
+}
+function normalizePath(value) {
+    return value.replace(/\\/g, '/').replace(/^\.\//, '');
+}
+async function collectFileTree(rootPath, depth, notices) {
+    const entries = await fg('**/*', {
+        cwd: rootPath,
+        absolute: false,
+        onlyFiles: true,
+        dot: true,
+        followSymbolicLinks: false,
+        objectMode: true,
+        stats: true,
+        suppressErrors: true,
+        deep: depth === 'quick' ? 8 : 20,
+        ignore: TREE_IGNORES,
+    });
+    const limit = depth === 'quick' ? 8_000 : 30_000;
+    const sorted = entries
+        .map((entry) => ({
+        path: normalizePath(entry.path),
+        sizeBytes: entry.stats?.size ?? 0,
+    }))
+        .sort((left, right) => left.path.localeCompare(right.path));
+    if (sorted.length > limit) {
+        notices.push(`Arbre borné à ${limit.toLocaleString('fr-FR')} fichiers sur ${sorted.length.toLocaleString('fr-FR')}.`);
+    }
+    return sorted.slice(0, limit);
+}
+async function readPrefix(filePath, maxBytes) {
+    const handle = await fs.open(filePath, 'r');
+    try {
+        const buffer = Buffer.alloc(maxBytes);
+        const { bytesRead } = await handle.read(buffer, 0, maxBytes, 0);
+        return buffer.toString('utf8', 0, bytesRead);
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function readReadmeExcerpt(rootPath, files) {
+    const readme = files.find((file) => /^readme(?:\.[^/]*)?$/i.test(file.path));
+    if (!readme)
+        return undefined;
+    const content = await readPrefix(path.join(rootPath, readme.path), 48 * 1024);
+    return content.trim() || undefined;
+}
+function isGitRepository(rootPath) {
+    try {
+        const topLevel = execFileSync('git', ['rev-parse', '--show-toplevel'], {
+            cwd: rootPath,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+            timeout: 5_000,
+        }).trim();
+        return realpathSync(topLevel) === realpathSync(rootPath);
+    }
+    catch {
+        return false;
+    }
+}
+function analysisPriority(file) {
+    const normalized = file.path.toLowerCase();
+    let priority = Math.min(file.sizeBytes ?? 0, 2_000_000);
+    if (/(?:^|\/)(?:index|main|app|server|cli)\.(?:ts|tsx|js|jsx)$/.test(normalized)) {
+        priority += 5_000_000;
+    }
+    if (normalized.includes('/agent/') || normalized.includes('/core/'))
+        priority += 1_000_000;
+    return priority;
+}
+function selectJsTsFiles(files, maxFiles) {
+    return files
+        .filter((file) => JS_TS_EXTENSIONS.has(path.extname(file.path).toLowerCase()) &&
+        !TEST_RE.test(file.path) &&
+        (file.sizeBytes ?? 0) <= 2 * 1024 * 1024)
+        .sort((left, right) => analysisPriority(right) - analysisPriority(left) || left.path.localeCompare(right.path))
+        .slice(0, maxFiles);
+}
+function exactGlobPatterns(files) {
+    return files.map((file) => fg.escapePath(file.path));
+}
+function mergeKnownLineCounts(files, profile) {
+    const counts = new Map((profile?.cartography?.fileStats.largestFiles ?? []).map((file) => [
+        normalizePath(file.path),
+        file.lines,
+    ]));
+    return files.map((file) => {
+        const lines = counts.get(file.path);
+        return lines === undefined ? file : { ...file, lines };
+    });
+}
+function codeExplorerCandidates(profile, docs) {
+    const components = profile?.cartography?.components;
+    const candidates = [
+        ...(components?.facades.map((entry) => entry.name) ?? []),
+        ...(components?.agents.map((entry) => entry.name) ?? []),
+        ...(components?.keyExports.flatMap((entry) => entry.exports) ?? []),
+        ...(docs?.modules.flatMap((module) => module.entries.map((entry) => entry.name)) ?? []),
+    ];
+    return [...new Set(candidates.filter((candidate) => /^[A-Za-z_$][\w$]*$/.test(candidate)))]
+        .filter((candidate) => !/^(?:index|main|default|config|options|result)$/i.test(candidate))
+        .slice(0, 3);
+}
+function safeFreshnessGit(args, cwd) {
+    const match = /^rev-list --count ([0-9a-fA-F]+)\.\.HEAD$/.exec(args);
+    const commit = match?.[1];
+    if (!commit)
+        throw new Error('Unsafe Code Explorer commit range');
+    return execFileSync('git', ['rev-list', '--count', `${commit}..HEAD`], {
+        cwd,
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+        timeout: 10_000,
+    }).trim();
+}
+function collectCodeExplorer(rootPath, profile, docs) {
+    const manager = new CodeExplorerManager(rootPath);
+    try {
+        const stats = manager.getStats();
+        if (!stats.indexed)
+            return { indexed: false };
+        const freshness = manager.getFreshness(safeFreshnessGit, { autoIndex: false });
+        let mermaid = '';
+        let target;
+        for (const candidate of codeExplorerCandidates(profile, docs)) {
+            mermaid = manager.generateDiagram(candidate);
+            if (mermaid) {
+                target = candidate;
+                break;
+            }
+        }
+        return {
+            indexed: true,
+            stale: freshness.stale || stats.stale,
+            ...(freshness.commitsBehind !== undefined ? { commitsBehind: freshness.commitsBehind } : {}),
+            symbols: stats.symbols,
+            relations: stats.relations,
+            processes: stats.processes,
+            clusters: stats.clusters,
+            ...(mermaid ? { mermaid } : {}),
+            ...(target ? { target } : {}),
+        };
+    }
+    finally {
+        manager.dispose();
+    }
+}
+function emptyComplexity() {
+    return {
+        files: [],
+        summary: {
+            totalFiles: 0,
+            totalFunctions: 0,
+            averageComplexity: 0,
+            maxComplexity: 0,
+            totalLinesOfCode: 0,
+            complexFunctions: 0,
+            veryComplexFunctions: 0,
+            overallRating: 'A',
+        },
+        hotspots: [],
+        recommendations: [],
+        generatedAt: new Date(0),
+    };
+}
+function emptyHeatmap() {
+    return {
+        files: [],
+        summary: {
+            totalFiles: 0,
+            totalCommits: 0,
+            totalAdditions: 0,
+            totalDeletions: 0,
+            hotspots: [],
+            coldspots: [],
+            topAuthors: [],
+        },
+        generatedAt: new Date(0),
+    };
+}
+function emptyEvolution() {
+    const date = new Date(0);
+    return {
+        dataPoints: [],
+        summary: {
+            startDate: date,
+            endDate: date,
+            startLoc: 0,
+            endLoc: 0,
+            locChange: 0,
+            locChangePercent: 0,
+            startFiles: 0,
+            endFiles: 0,
+            fileChange: 0,
+            avgCommitsPerDay: 0,
+        },
+        trends: { locTrend: 'stable', fileTrend: 'stable', velocity: 0 },
+        generatedAt: date,
+    };
+}
+function emptyDocs() {
+    return { modules: [], totalEntries: 0, generatedAt: new Date(0) };
+}
+/**
+ * Collect every source independently. Failures are converted to notices, so a
+ * readable artifact can still be produced for an empty directory, a non-Git
+ * project, malformed manifests, or an unavailable Code Explorer binary.
+ */
+export async function collectRepoExplanationInput(options) {
+    const rootPath = path.resolve(options.rootPath);
+    const notices = [];
+    let files = await bestEffort('Arbre de fichiers', [], notices, () => collectFileTree(rootPath, options.depth, notices));
+    const profile = await bestEffort('Profil du dépôt', undefined, notices, () => new RepoProfiler(rootPath).inspect());
+    files = mergeKnownLineCounts(files, profile);
+    const readmeExcerpt = await bestEffort('Lecture du README', undefined, notices, () => readReadmeExcerpt(rootPath, files));
+    const jsTsFiles = selectJsTsFiles(files, options.depth === 'quick' ? 260 : 1_500);
+    const complexity = jsTsFiles.length === 0
+        ? emptyComplexity()
+        : await bestEffort('Analyse de complexité', emptyComplexity(), notices, () => analyzeComplexity({
+            rootPath,
+            include: exactGlobPatterns(jsTsFiles),
+            exclude: [],
+            complexityThreshold: 10,
+            maxHotspots: options.depth === 'quick' ? 20 : 50,
+        }));
+    const documentedFiles = jsTsFiles.slice(0, options.depth === 'quick' ? 100 : 700);
+    const documentation = documentedFiles.length === 0
+        ? emptyDocs()
+        : await bestEffort('Inventaire documentaire du code', emptyDocs(), notices, () => generateDocs({
+            rootDir: rootPath,
+            include: exactGlobPatterns(documentedFiles),
+            exclude: [],
+            exportedOnly: true,
+            includePrivate: false,
+        }));
+    const gitAvailable = isGitRepository(rootPath);
+    const heatmap = gitAvailable
+        ? await bestEffort('Heatmap Git', emptyHeatmap(), notices, () => generateHeatmap({
+            repoPath: rootPath,
+            days: options.depth === 'quick' ? 90 : 365,
+            maxFiles: options.depth === 'quick' ? 100 : 300,
+        }))
+        : emptyHeatmap();
+    const sourceExtensions = [
+        ...new Set(files
+            .map((file) => path.extname(file.path).toLowerCase())
+            .filter((extension) => EVOLUTION_EXTENSIONS.has(extension))),
+    ];
+    const sourceFileCount = Math.max(files.filter((file) => EVOLUTION_EXTENSIONS.has(path.extname(file.path).toLowerCase())).length, profile?.cartography?.fileStats.totalSourceFiles ?? 0);
+    const evolutionLimit = options.depth === 'quick' ? 120 : 350;
+    let evolution = emptyEvolution();
+    if (gitAvailable && sourceExtensions.length > 0 && sourceFileCount <= evolutionLimit) {
+        evolution = await bestEffort('Évolution du code', emptyEvolution(), notices, () => generateEvolutionReport({
+            repoPath: rootPath,
+            dataPoints: options.depth === 'quick' ? 3 : 6,
+            days: options.depth === 'quick' ? 90 : 365,
+            extensions: sourceExtensions,
+        }));
+    }
+    else if (gitAvailable && sourceFileCount > evolutionLimit) {
+        notices.push(`Évolution historique détaillée ignorée au-delà de ${evolutionLimit} fichiers source; la heatmap Git reste active.`);
+    }
+    const codeExplorer = await bestEffort('Code Explorer', { indexed: false }, notices, () => collectCodeExplorer(rootPath, profile, documentation));
+    return {
+        rootPath,
+        rootName: path.basename(rootPath) || 'repo',
+        depth: options.depth,
+        generatedAt: options.generatedAt.toISOString(),
+        files,
+        profile: {
+            name: profile?.name,
+            description: profile?.description,
+            readmeExcerpt,
+            languages: profile?.languages,
+            framework: profile?.framework,
+            packageManager: profile?.packageManager,
+            testFramework: profile?.testFramework,
+            entryPoints: profile?.entryPoints,
+            commands: profile?.commands,
+            topDependencies: profile?.topDependencies,
+        },
+        cartography: profile?.cartography,
+        complexity,
+        heatmap,
+        evolution,
+        documentation,
+        codeExplorer,
+        git: { available: gitAvailable },
+        notices,
+    };
+}
+//# sourceMappingURL=repo-explainer-collector.js.map

package/dist/analytics/repo-explainer.d.ts

@@ -0,0 +1,224 @@
+/**
+ * Repository explainer
+ *
+ * Pure synthesis layer for `buddy explain`. Heavy and fallible collection is
+ * deliberately kept outside this module: callers inject a file tree, profile,
+ * analytics reports, documentation inventory, and an optional Code Explorer
+ * graph. Given the same input this module always returns the same explanation.
+ */
+export type RepoExplainDepth = 'quick' | 'deep';
+export interface RepoFileInput {
+    path: string;
+    sizeBytes?: number;
+    lines?: number;
+}
+export interface RepoProfileInput {
+    name?: string;
+    description?: string;
+    readmeExcerpt?: string;
+    languages?: string[];
+    framework?: string;
+    frameworks?: string[];
+    packageManager?: string;
+    testFramework?: string;
+    entryPoints?: string[];
+    commands?: Record<string, string | undefined>;
+    topDependencies?: string[];
+}
+export interface RepoArchitectureLayerInput {
+    name: string;
+    directory: string;
+    fileCount: number;
+}
+export interface RepoCartographyInput {
+    architecture?: {
+        style?: string;
+        layers?: RepoArchitectureLayerInput[];
+        maxDepth?: number;
+    };
+    fileStats?: {
+        largestFiles?: Array<{
+            path: string;
+            lines: number;
+        }>;
+        totalSourceFiles?: number;
+        totalTestFiles?: number;
+    };
+    importGraph?: {
+        hotModules?: Array<{
+            module: string;
+            importedBy: number;
+        }>;
+        circularRisks?: Array<{
+            a: string;
+            b: string;
+        }>;
+    };
+    importEdges?: Array<[string, string]>;
+}
+export interface RepoComplexityFileInput {
+    filePath: string;
+    maxComplexity: number;
+    averageComplexity?: number;
+    totalLinesOfCode: number;
+    maintainabilityIndex?: number;
+}
+export interface RepoComplexityHotspotInput {
+    filePath: string;
+    name?: string;
+    cyclomaticComplexity: number;
+    cognitiveComplexity?: number;
+    linesOfCode?: number;
+}
+export interface RepoComplexityInput {
+    files: RepoComplexityFileInput[];
+    hotspots?: RepoComplexityHotspotInput[];
+    summary?: {
+        totalFiles?: number;
+        totalFunctions?: number;
+        averageComplexity?: number;
+        maxComplexity?: number;
+        overallRating?: string;
+    };
+}
+export interface RepoHeatFileInput {
+    filePath: string;
+    commits: number;
+    additions: number;
+    deletions: number;
+    churnScore: number;
+    heatLevel?: string;
+}
+export interface RepoHeatmapInput {
+    files: RepoHeatFileInput[];
+}
+export interface RepoEvolutionInput {
+    dataPoints?: unknown[];
+    summary?: {
+        locChange?: number;
+        locChangePercent?: number;
+        fileChange?: number;
+    };
+    trends?: {
+        locTrend?: 'growing' | 'shrinking' | 'stable';
+        fileTrend?: 'growing' | 'shrinking' | 'stable';
+        velocity?: number;
+    };
+}
+export interface RepoDocumentationInput {
+    modules: Array<{
+        path: string;
+        description?: string;
+        entries: Array<{
+            name: string;
+            kind: string;
+            description?: string;
+        }>;
+    }>;
+    totalEntries?: number;
+}
+export interface RepoCodeExplorerInput {
+    indexed: boolean;
+    stale?: boolean;
+    commitsBehind?: number;
+    symbols?: number;
+    relations?: number;
+    processes?: number;
+    clusters?: number;
+    mermaid?: string;
+    target?: string;
+}
+export interface RepoExplanationInput {
+    rootPath?: string;
+    rootName: string;
+    depth: RepoExplainDepth;
+    generatedAt: string;
+    files: RepoFileInput[];
+    profile?: RepoProfileInput;
+    cartography?: RepoCartographyInput;
+    complexity?: RepoComplexityInput;
+    heatmap?: RepoHeatmapInput;
+    evolution?: RepoEvolutionInput;
+    documentation?: RepoDocumentationInput;
+    codeExplorer?: RepoCodeExplorerInput;
+    git?: {
+        available: boolean;
+    };
+    notices?: string[];
+}
+export interface RepoLanguageSummary {
+    name: string;
+    files: number;
+    percent: number;
+}
+export interface RepoEntryPoint {
+    path: string;
+    reason: string;
+    exportedSymbols: string[];
+}
+export interface RepoModuleSummary {
+    name: string;
+    directory: string;
+    fileCount: number;
+    purpose: string;
+}
+export interface RepoDependencyDiagram {
+    mermaid: string;
+    source: 'code-explorer' | 'file-analysis';
+    note: string;
+}
+export type RepoRiskLevel = 'critical' | 'high' | 'medium' | 'low';
+export interface RepoHotspot {
+    path: string;
+    score: number;
+    level: RepoRiskLevel;
+    maxComplexity?: number;
+    lines?: number;
+    sizeBytes?: number;
+    churn?: number;
+    commits?: number;
+    reasons: string[];
+}
+export interface RepoExplanation {
+    repo: {
+        name: string;
+        purpose: string;
+        depth: RepoExplainDepth;
+        generatedAt: string;
+        totalFiles: number;
+        sourceFiles: number;
+        testFiles: number;
+    };
+    overview: {
+        languages: RepoLanguageSummary[];
+        frameworks: string[];
+        packageManager?: string;
+        testFramework?: string;
+        dependencies: string[];
+        entryPoints: RepoEntryPoint[];
+    };
+    architecture: {
+        style: string;
+        modules: RepoModuleSummary[];
+        diagram: RepoDependencyDiagram;
+        centralModules: Array<{
+            path: string;
+            importedBy: number;
+        }>;
+    };
+    risks: {
+        hotspots: RepoHotspot[];
+        complexity?: RepoComplexityInput['summary'];
+        evolution?: RepoEvolutionInput;
+        gitAvailable: boolean;
+    };
+    gettingStarted: {
+        path: string[];
+        docs: string[];
+        tests: string[];
+        commands: Record<string, string>;
+    };
+    limitations: string[];
+}
+/** Build a complete, render-agnostic repository explanation. */
+export declare function explainRepository(input: RepoExplanationInput): RepoExplanation;