codesight 1.3.1 → 1.4.0

package/dist/eval.js

@@ -0,0 +1,184 @@
+/**
+ * Evaluation suite: runs codesight on fixture repos and measures
+ * precision, recall, and F1 against ground truth.
+ */
+import { readFile, writeFile, mkdir, rm } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { collectFiles, detectProject } from "./scanner.js";
+import { detectRoutes } from "./detectors/routes.js";
+import { detectSchemas } from "./detectors/schema.js";
+import { detectComponents } from "./detectors/components.js";
+import { detectConfig } from "./detectors/config.js";
+import { detectMiddleware } from "./detectors/middleware.js";
+function calcMetrics(detected, expected) {
+    let tp = 0;
+    let fp = 0;
+    let fn = 0;
+    for (const item of detected) {
+        if (expected.has(item))
+            tp++;
+        else
+            fp++;
+    }
+    for (const item of expected) {
+        if (!detected.has(item))
+            fn++;
+    }
+    const precision = tp + fp > 0 ? tp / (tp + fp) : 1;
+    const recall = tp + fn > 0 ? tp / (tp + fn) : 1;
+    const f1 = precision + recall > 0 ? (2 * precision * recall) / (precision + recall) : 0;
+    return {
+        precision: Math.round(precision * 1000) / 1000,
+        recall: Math.round(recall * 1000) / 1000,
+        f1: Math.round(f1 * 1000) / 1000,
+        truePositives: tp,
+        falsePositives: fp,
+        falseNegatives: fn,
+    };
+}
+async function createTempRepo(fixture) {
+    const tmpDir = join((await import("node:os")).tmpdir(), `codesight-eval-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`);
+    for (const [filePath, content] of Object.entries(fixture.files)) {
+        const fullPath = join(tmpDir, filePath);
+        await mkdir(dirname(fullPath), { recursive: true });
+        await writeFile(fullPath, content);
+    }
+    return tmpDir;
+}
+async function evalFixture(fixturePath) {
+    const repoJson = JSON.parse(await readFile(join(fixturePath, "repo.json"), "utf-8"));
+    const groundTruth = JSON.parse(await readFile(join(fixturePath, "ground-truth.json"), "utf-8"));
+    // Create temp repo from fixture
+    const tmpDir = await createTempRepo(repoJson);
+    const startTime = Date.now();
+    try {
+        // Run codesight detectors
+        const project = await detectProject(tmpDir);
+        const files = await collectFiles(tmpDir, 10);
+        const [routes, schemas, components, config, middleware] = await Promise.all([
+            detectRoutes(files, project),
+            detectSchemas(files, project),
+            detectComponents(files, project),
+            detectConfig(files, project),
+            detectMiddleware(files, project),
+        ]);
+        const runtime = Date.now() - startTime;
+        // Compare routes: method:path
+        const detectedRoutes = new Set(routes.map((r) => `${r.method}:${r.path}`));
+        const expectedRoutes = new Set((groundTruth.routes || []).map((r) => `${r.method}:${r.path}`));
+        // Compare models: name
+        const detectedModels = new Set(schemas.map((s) => s.name.toLowerCase()));
+        const expectedModels = new Set((groundTruth.models || []).map((m) => m.name.toLowerCase()));
+        // Compare env vars
+        const detectedEnvVars = new Set(config.envVars.map((e) => e.name));
+        const expectedEnvVars = new Set(groundTruth.envVars || []);
+        const result = {
+            name: repoJson.name,
+            routes: calcMetrics(detectedRoutes, expectedRoutes),
+            models: calcMetrics(detectedModels, expectedModels),
+            envVars: calcMetrics(detectedEnvVars, expectedEnvVars),
+            runtime,
+        };
+        // Components (if ground truth has them)
+        if (groundTruth.components && groundTruth.components.length > 0) {
+            const detectedComps = new Set(components.map((c) => c.name));
+            const expectedComps = new Set(groundTruth.components.map((c) => c.name));
+            result.components = calcMetrics(detectedComps, expectedComps);
+        }
+        // Middleware
+        if (groundTruth.middleware && groundTruth.middleware.length > 0) {
+            const detectedMw = new Set(middleware.map((m) => m.name));
+            const expectedMw = new Set(groundTruth.middleware);
+            result.middleware = calcMetrics(detectedMw, expectedMw);
+        }
+        return result;
+    }
+    finally {
+        // Cleanup temp dir
+        await rm(tmpDir, { recursive: true, force: true }).catch(() => { });
+    }
+}
+function formatPercent(n) {
+    return `${(n * 100).toFixed(1)}%`;
+}
+function printMetrics(label, m) {
+    console.log(`    ${label.padEnd(14)} P: ${formatPercent(m.precision).padStart(6)}  R: ${formatPercent(m.recall).padStart(6)}  F1: ${formatPercent(m.f1).padStart(6)}  (TP:${m.truePositives} FP:${m.falsePositives} FN:${m.falseNegatives})`);
+}
+export async function runEval() {
+    // Find eval fixtures
+    const __dirname = dirname(fileURLToPath(import.meta.url));
+    const evalDir = join(__dirname, "..", "eval", "fixtures");
+    let fixtureNames;
+    try {
+        const { readdir } = await import("node:fs/promises");
+        fixtureNames = await readdir(evalDir);
+    }
+    catch {
+        // Try from dist path
+        const altDir = join(__dirname, "..", "..", "eval", "fixtures");
+        const { readdir } = await import("node:fs/promises");
+        fixtureNames = await readdir(altDir);
+        // Override evalDir for the loop below
+        return runEvalFromDir(altDir, fixtureNames);
+    }
+    return runEvalFromDir(evalDir, fixtureNames);
+}
+async function runEvalFromDir(evalDir, fixtureNames) {
+    console.log(`\n  codesight eval — precision/recall benchmarks\n`);
+    const results = [];
+    let totalPrecision = 0;
+    let totalRecall = 0;
+    let totalF1 = 0;
+    let metricCount = 0;
+    for (const name of fixtureNames) {
+        const fixturePath = join(evalDir, name);
+        // Check if it has repo.json
+        try {
+            await import("node:fs/promises").then((fs) => fs.stat(join(fixturePath, "repo.json")));
+        }
+        catch {
+            continue;
+        }
+        process.stdout.write(`  ${name}...`);
+        const result = await evalFixture(fixturePath);
+        results.push(result);
+        console.log(` ${result.runtime}ms`);
+        printMetrics("Routes", result.routes);
+        printMetrics("Models", result.models);
+        printMetrics("Env vars", result.envVars);
+        if (result.components)
+            printMetrics("Components", result.components);
+        if (result.middleware)
+            printMetrics("Middleware", result.middleware);
+        console.log("");
+        // Accumulate for averages
+        const metrics = [result.routes, result.models, result.envVars];
+        if (result.components)
+            metrics.push(result.components);
+        if (result.middleware)
+            metrics.push(result.middleware);
+        for (const m of metrics) {
+            totalPrecision += m.precision;
+            totalRecall += m.recall;
+            totalF1 += m.f1;
+            metricCount++;
+        }
+    }
+    if (results.length === 0) {
+        console.log("  No fixtures found. Add fixtures to eval/fixtures/");
+        return;
+    }
+    // Summary
+    const avgP = totalPrecision / metricCount;
+    const avgR = totalRecall / metricCount;
+    const avgF1 = totalF1 / metricCount;
+    const totalRuntime = results.reduce((s, r) => s + r.runtime, 0);
+    console.log("  ──────────────────────────────────────────");
+    console.log(`  Fixtures:           ${results.length}`);
+    console.log(`  Avg precision:      ${formatPercent(avgP)}`);
+    console.log(`  Avg recall:         ${formatPercent(avgR)}`);
+    console.log(`  Avg F1:             ${formatPercent(avgF1)}`);
+    console.log(`  Total runtime:      ${totalRuntime}ms`);
+    console.log("");
+}

package/dist/index.js

@@ -14,7 +14,8 @@ import { calculateTokenStats } from "./detectors/tokens.js";
 import { writeOutput } from "./formatter.js";
 import { generateAIConfigs } from "./generators/ai-config.js";
 import { generateHtmlReport } from "./generators/html-report.js";
-const VERSION = "1.3.1";
+import { loadConfig, mergeCliConfig } from "./config.js";
+const VERSION = "1.4.0";
 const BRAND = "codesight";
 function printHelp() {
     console.log(`
@@ -35,9 +36,15 @@ function printHelp() {
     --benchmark          Show detailed token savings breakdown
     --profile <tool>     Generate optimized config (claude-code|cursor|codex|copilot|windsurf)
     --blast <file>       Show blast radius for a file
+    --telemetry          Run token telemetry (real before/after measurement)
+    --eval               Run precision/recall benchmarks on eval fixtures
     -v, --version        Show version
     -h, --help           Show this help
 
+  Config:
+    Reads codesight.config.(ts|js|json) or package.json "codesight" field.
+    See docs for disableDetectors, customRoutePatterns, plugins, and more.
+
   Examples:
     npx ${BRAND}                    # Scan current directory
     npx ${BRAND} --init             # Scan + generate AI config files
@@ -45,6 +52,8 @@ function printHelp() {
     npx ${BRAND} --watch            # Watch mode, re-scan on changes
     npx ${BRAND} --mcp              # Start MCP server
     npx ${BRAND} --hook             # Install git pre-commit hook
+    npx ${BRAND} --telemetry        # Measure real token savings
+    npx ${BRAND} --eval             # Run accuracy benchmarks
     npx ${BRAND} ./my-project       # Scan specific directory
 `);
 }
@@ -57,7 +66,7 @@ async function fileExists(path) {
         return false;
     }
 }
-async function scan(root, outputDirName, maxDepth) {
+async function scan(root, outputDirName, maxDepth, userConfig = {}) {
     const outputDir = join(root, outputDirName);
     console.log(`\n  ${BRAND} v${VERSION}`);
     console.log(`  Scanning: ${root}\n`);
@@ -73,17 +82,39 @@ async function scan(root, outputDirName, maxDepth) {
     process.stdout.write("  Collecting files...");
     const files = await collectFiles(root, maxDepth);
     console.log(` ${files.length} files`);
-    // Step 3: Run all detectors in parallel
+    // Step 3: Run all detectors in parallel (respecting disableDetectors config)
     process.stdout.write("  Analyzing...");
-    const [rawRoutes, schemas, components, libs, config, middleware, graph] = await Promise.all([
-        detectRoutes(files, project),
-        detectSchemas(files, project),
-        detectComponents(files, project),
-        detectLibs(files, project),
-        detectConfig(files, project),
-        detectMiddleware(files, project),
-        detectDependencyGraph(files, project),
+    const disabled = new Set(userConfig.disableDetectors || []);
+    const [rawRoutes, schemas, components, libs, configResult, middleware, graph] = await Promise.all([
+        disabled.has("routes") ? Promise.resolve([]) : detectRoutes(files, project),
+        disabled.has("schema") ? Promise.resolve([]) : detectSchemas(files, project),
+        disabled.has("components") ? Promise.resolve([]) : detectComponents(files, project),
+        disabled.has("libs") ? Promise.resolve([]) : detectLibs(files, project),
+        disabled.has("config") ? Promise.resolve({ envVars: [], configFiles: [], dependencies: {}, devDependencies: {} }) : detectConfig(files, project),
+        disabled.has("middleware") ? Promise.resolve([]) : detectMiddleware(files, project),
+        disabled.has("graph") ? Promise.resolve({ edges: [], hotFiles: [] }) : detectDependencyGraph(files, project),
     ]);
+    // Step 3b: Run plugin detectors
+    if (userConfig.plugins) {
+        for (const plugin of userConfig.plugins) {
+            if (plugin.detector) {
+                try {
+                    const pluginResult = await plugin.detector(files, project);
+                    if (pluginResult.routes)
+                        rawRoutes.push(...pluginResult.routes);
+                    if (pluginResult.schemas)
+                        schemas.push(...pluginResult.schemas);
+                    if (pluginResult.components)
+                        components.push(...pluginResult.components);
+                    if (pluginResult.middleware)
+                        middleware.push(...pluginResult.middleware);
+                }
+                catch (err) {
+                    console.warn(`\n  Warning: plugin "${plugin.name}" failed: ${err.message}`);
+                }
+            }
+        }
+    }
     // Step 4: Enrich routes with contract info
     const routes = await enrichRouteContracts(rawRoutes, project);
     // Report AST vs regex detection
@@ -106,7 +137,7 @@ async function scan(root, outputDirName, maxDepth) {
         schemas,
         components,
         libs,
-        config,
+        config: configResult,
         middleware,
         graph,
         tokenStats: { outputTokens: 0, estimatedExplorationTokens: 0, saved: 0, fileCount: files.length },
@@ -126,7 +157,7 @@ async function scan(root, outputDirName, maxDepth) {
     Models:       ${schemas.length}
     Components:   ${components.length}
     Libraries:    ${libs.length}
-    Env vars:     ${config.envVars.length}
+    Env vars:     ${configResult.envVars.length}
     Middleware:    ${middleware.length}
     Import links: ${graph.edges.length}
     Hot files:    ${graph.hotFiles.length}
@@ -234,6 +265,8 @@ async function main() {
     let doBenchmark = false;
     let doProfile = "";
     let doBlast = "";
+    let doTelemetry = false;
+    let doEval = false;
     for (let i = 0; i < args.length; i++) {
         const arg = args[i];
         if ((arg === "-o" || arg === "--output") && args[i + 1]) {
@@ -273,6 +306,12 @@ async function main() {
         else if (arg === "--blast" && args[i + 1]) {
             doBlast = args[++i];
         }
+        else if (arg === "--telemetry") {
+            doTelemetry = true;
+        }
+        else if (arg === "--eval") {
+            doEval = true;
+        }
         else if (!arg.startsWith("-")) {
             targetDir = resolve(arg);
         }
@@ -283,13 +322,58 @@ async function main() {
         await startMCPServer();
         return;
     }
+    // Eval mode (standalone, no scan needed)
+    if (doEval) {
+        const { runEval } = await import("./eval.js");
+        await runEval();
+        return;
+    }
     const root = resolve(targetDir);
+    // Load config file
+    const fileConfig = await loadConfig(root);
+    const config = mergeCliConfig(fileConfig, {
+        maxDepth: maxDepth !== 10 ? maxDepth : undefined,
+        outputDir: outputDirName !== ".codesight" ? outputDirName : undefined,
+        profile: doProfile || undefined,
+    });
+    // Apply config overrides
+    if (config.maxDepth)
+        maxDepth = config.maxDepth;
+    if (config.outputDir)
+        outputDirName = config.outputDir;
     // Install git hook
     if (doHook) {
         await installGitHook(root, outputDirName);
     }
-    // Run scan
-    const result = await scan(root, outputDirName, maxDepth);
+    // Run scan (passes config for disabled detectors + plugins)
+    let result = await scan(root, outputDirName, maxDepth, config);
+    // Run plugin post-processors
+    if (config.plugins) {
+        for (const plugin of config.plugins) {
+            if (plugin.postProcessor) {
+                try {
+                    result = await plugin.postProcessor(result);
+                }
+                catch (err) {
+                    console.warn(`  Warning: plugin "${plugin.name}" post-processor failed: ${err.message}`);
+                }
+            }
+        }
+    }
+    // Token telemetry
+    if (doTelemetry) {
+        const { runTelemetry } = await import("./telemetry.js");
+        const outputDir = join(root, outputDirName);
+        process.stdout.write("  Running telemetry...");
+        const report = await runTelemetry(root, result, outputDir);
+        console.log(` ${outputDirName}/telemetry.md`);
+        console.log(`\n  Telemetry Results:`);
+        for (const task of report.tasks) {
+            console.log(`    ${task.name}: ${task.reduction}x reduction (${task.tokensWithout.toLocaleString()} → ${task.tokensWith.toLocaleString()} tokens)`);
+        }
+        console.log(`    Average: ${report.summary.averageReduction}x | Tool calls saved: ${report.summary.totalToolCallsSaved}`);
+        console.log("");
+    }
     // JSON output
     if (jsonOutput) {
         console.log(JSON.stringify(result, null, 2));

package/dist/telemetry.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Token telemetry: measures real before/after token usage by simulating
+ * what an AI agent would do with and without codesight context.
+ *
+ * Approach: for each standard task (explain architecture, add route, review diff),
+ * measure the actual bytes of context that would be consumed.
+ *
+ * "Without codesight": count tokens from the files an AI would need to read
+ * to discover routes, schema, components, config, etc.
+ *
+ * "With codesight": count tokens from the CODESIGHT.md output.
+ */
+import type { ScanResult } from "./types.js";
+export interface TelemetryTask {
+    name: string;
+    description: string;
+    /** Files the AI would need to read without codesight */
+    filesRead: string[];
+    /** Tool calls the AI would make (glob, grep, read) */
+    toolCalls: number;
+    /** Tokens consumed reading those files */
+    tokensWithout: number;
+    /** Tokens consumed from codesight output */
+    tokensWith: number;
+    /** Reduction factor */
+    reduction: number;
+}
+export interface TelemetryReport {
+    project: string;
+    tasks: TelemetryTask[];
+    summary: {
+        totalTokensWithout: number;
+        totalTokensWith: number;
+        averageReduction: number;
+        totalToolCallsSaved: number;
+    };
+}
+export declare function runTelemetry(root: string, result: ScanResult, outputDir: string): Promise<TelemetryReport>;

package/dist/telemetry.js

@@ -0,0 +1,257 @@
+/**
+ * Token telemetry: measures real before/after token usage by simulating
+ * what an AI agent would do with and without codesight context.
+ *
+ * Approach: for each standard task (explain architecture, add route, review diff),
+ * measure the actual bytes of context that would be consumed.
+ *
+ * "Without codesight": count tokens from the files an AI would need to read
+ * to discover routes, schema, components, config, etc.
+ *
+ * "With codesight": count tokens from the CODESIGHT.md output.
+ */
+import { readFile } from "node:fs/promises";
+import { join, relative } from "node:path";
+function countTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+async function readFileSafe(path) {
+    try {
+        return await readFile(path, "utf-8");
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * Task 1: "Explain the architecture"
+ * Without codesight: AI reads package.json, scans dirs, reads route files,
+ * schema files, config files, middleware files — typically 15-25 file reads.
+ */
+async function measureExplainArchitecture(root, result, codesightTokens) {
+    const filesToRead = new Set();
+    // AI would read package.json first
+    filesToRead.add(join(root, "package.json"));
+    // Then scan for route files
+    for (const route of result.routes) {
+        filesToRead.add(join(root, route.file));
+    }
+    // Schema files
+    for (const _schema of result.schemas) {
+        // Find the file containing this schema from routes or libs
+        for (const lib of result.libs) {
+            if (lib.file.includes("schema") || lib.file.includes("model") || lib.file.includes("db")) {
+                filesToRead.add(join(root, lib.file));
+            }
+        }
+    }
+    // Config files
+    for (const cf of result.config.configFiles) {
+        filesToRead.add(join(root, cf));
+    }
+    // Middleware files
+    for (const mw of result.middleware) {
+        filesToRead.add(join(root, mw.file));
+    }
+    // Hot files (AI would discover these during exploration)
+    for (const hf of result.graph.hotFiles.slice(0, 10)) {
+        filesToRead.add(join(root, hf.file));
+    }
+    // Read all files and count tokens
+    let totalTokens = 0;
+    const readFiles = [];
+    for (const f of filesToRead) {
+        const content = await readFileSafe(f);
+        if (content) {
+            totalTokens += countTokens(content);
+            readFiles.push(relative(root, f));
+        }
+    }
+    // Add overhead for glob/grep tool calls (each costs ~50-100 tokens for command + results)
+    const toolCalls = Math.max(10, Math.ceil(filesToRead.size * 0.8));
+    totalTokens += toolCalls * 75; // average 75 tokens per tool call overhead
+    const reduction = totalTokens > 0 ? Math.round((totalTokens / codesightTokens) * 10) / 10 : 1;
+    return {
+        name: "Explain architecture",
+        description: "Understand project stack, routes, schema, and dependencies",
+        filesRead: readFiles,
+        toolCalls,
+        tokensWithout: totalTokens,
+        tokensWith: codesightTokens,
+        reduction,
+    };
+}
+/**
+ * Task 2: "Add a new API route"
+ * Without codesight: AI needs to find existing routes to match patterns,
+ * read schema for related models, check middleware, check config.
+ */
+async function measureAddRoute(root, result, codesightTokens) {
+    const filesToRead = new Set();
+    // AI would grep for existing route patterns — reads 3-5 route files
+    const routeFiles = [...new Set(result.routes.map((r) => r.file))];
+    for (const f of routeFiles.slice(0, 5)) {
+        filesToRead.add(join(root, f));
+    }
+    // Read schema to understand models
+    for (const lib of result.libs) {
+        if (lib.file.includes("schema") || lib.file.includes("model") || lib.file.includes("db")) {
+            filesToRead.add(join(root, lib.file));
+        }
+    }
+    // Check middleware to know what to apply
+    for (const mw of result.middleware) {
+        filesToRead.add(join(root, mw.file));
+    }
+    let totalTokens = 0;
+    const readFiles = [];
+    for (const f of filesToRead) {
+        const content = await readFileSafe(f);
+        if (content) {
+            totalTokens += countTokens(content);
+            readFiles.push(relative(root, f));
+        }
+    }
+    const toolCalls = Math.max(6, Math.ceil(filesToRead.size * 0.7));
+    totalTokens += toolCalls * 75;
+    // With codesight, AI only reads the routes + schema sections (~40% of output)
+    const withTokens = Math.ceil(codesightTokens * 0.4);
+    const reduction = totalTokens > 0 ? Math.round((totalTokens / withTokens) * 10) / 10 : 1;
+    return {
+        name: "Add new API route",
+        description: "Find route patterns, check schema, apply middleware",
+        filesRead: readFiles,
+        toolCalls,
+        tokensWithout: totalTokens,
+        tokensWith: withTokens,
+        reduction,
+    };
+}
+/**
+ * Task 3: "Review a diff / understand blast radius"
+ * Without codesight: AI needs to trace imports, find dependents, check what routes
+ * and models are affected by a file change.
+ */
+async function measureReviewDiff(root, result, codesightTokens) {
+    const filesToRead = new Set();
+    // AI would read the changed file + all its importers
+    // Simulate: pick the hottest file and trace its dependents
+    if (result.graph.hotFiles.length > 0) {
+        const hotFile = result.graph.hotFiles[0];
+        filesToRead.add(join(root, hotFile.file));
+        // Read files that import it
+        for (const edge of result.graph.edges) {
+            if (edge.to === hotFile.file) {
+                filesToRead.add(join(root, edge.from));
+            }
+        }
+    }
+    // Also read some route files to check impact
+    const routeFiles = [...new Set(result.routes.map((r) => r.file))];
+    for (const f of routeFiles.slice(0, 3)) {
+        filesToRead.add(join(root, f));
+    }
+    let totalTokens = 0;
+    const readFiles = [];
+    for (const f of filesToRead) {
+        const content = await readFileSafe(f);
+        if (content) {
+            totalTokens += countTokens(content);
+            readFiles.push(relative(root, f));
+        }
+    }
+    const toolCalls = Math.max(8, Math.ceil(filesToRead.size * 0.6));
+    totalTokens += toolCalls * 75;
+    // With codesight, AI reads graph section + routes (~50% of output)
+    const withTokens = Math.ceil(codesightTokens * 0.5);
+    const reduction = totalTokens > 0 ? Math.round((totalTokens / withTokens) * 10) / 10 : 1;
+    return {
+        name: "Review diff / blast radius",
+        description: "Trace imports, find affected routes and models",
+        filesRead: readFiles,
+        toolCalls,
+        tokensWithout: totalTokens,
+        tokensWith: withTokens,
+        reduction,
+    };
+}
+export async function runTelemetry(root, result, outputDir) {
+    // Read the codesight output to get real token count
+    const codesightContent = await readFileSafe(join(outputDir, "CODESIGHT.md"));
+    const codesightTokens = countTokens(codesightContent);
+    const tasks = await Promise.all([
+        measureExplainArchitecture(root, result, codesightTokens),
+        measureAddRoute(root, result, codesightTokens),
+        measureReviewDiff(root, result, codesightTokens),
+    ]);
+    const totalWithout = tasks.reduce((s, t) => s + t.tokensWithout, 0);
+    const totalWith = tasks.reduce((s, t) => s + t.tokensWith, 0);
+    const totalToolCalls = tasks.reduce((s, t) => s + t.toolCalls, 0);
+    const report = {
+        project: result.project.name,
+        tasks,
+        summary: {
+            totalTokensWithout: totalWithout,
+            totalTokensWith: totalWith,
+            averageReduction: totalWith > 0 ? Math.round((totalWithout / totalWith) * 10) / 10 : 1,
+            totalToolCallsSaved: totalToolCalls,
+        },
+    };
+    // Write telemetry report
+    const reportLines = [
+        `# Token Telemetry: ${result.project.name}`,
+        "",
+        `> Measured by reading the actual files an AI agent would need for each task,`,
+        `> then comparing against the codesight output (~${codesightTokens.toLocaleString()} tokens).`,
+        "",
+        "## Tasks",
+        "",
+    ];
+    for (const task of tasks) {
+        reportLines.push(`### ${task.name}`);
+        reportLines.push(`_${task.description}_`);
+        reportLines.push("");
+        reportLines.push(`| Metric | Value |`);
+        reportLines.push(`|---|---|`);
+        reportLines.push(`| Files AI would read | ${task.filesRead.length} |`);
+        reportLines.push(`| Tool calls (glob/grep/read) | ${task.toolCalls} |`);
+        reportLines.push(`| Tokens without codesight | ~${task.tokensWithout.toLocaleString()} |`);
+        reportLines.push(`| Tokens with codesight | ~${task.tokensWith.toLocaleString()} |`);
+        reportLines.push(`| **Reduction** | **${task.reduction}x** |`);
+        reportLines.push("");
+        if (task.filesRead.length > 0) {
+            reportLines.push("<details>");
+            reportLines.push(`<summary>Files read (${task.filesRead.length})</summary>`);
+            reportLines.push("");
+            for (const f of task.filesRead) {
+                reportLines.push(`- \`${f}\``);
+            }
+            reportLines.push("");
+            reportLines.push("</details>");
+            reportLines.push("");
+        }
+    }
+    reportLines.push("## Summary");
+    reportLines.push("");
+    reportLines.push(`| Metric | Value |`);
+    reportLines.push(`|---|---|`);
+    reportLines.push(`| Total tokens without codesight | ~${report.summary.totalTokensWithout.toLocaleString()} |`);
+    reportLines.push(`| Total tokens with codesight | ~${report.summary.totalTokensWith.toLocaleString()} |`);
+    reportLines.push(`| **Average reduction** | **${report.summary.averageReduction}x** |`);
+    reportLines.push(`| Tool calls saved | ${report.summary.totalToolCallsSaved} |`);
+    reportLines.push("");
+    reportLines.push("## Methodology");
+    reportLines.push("");
+    reportLines.push("Token counts are calculated by reading the actual source files an AI agent would");
+    reportLines.push("need to explore for each task, using the ~4 chars/token heuristic (standard for");
+    reportLines.push("GPT/Claude tokenizers). Tool call overhead is estimated at ~75 tokens per call");
+    reportLines.push("(command text + result formatting). The \"with codesight\" count uses the real");
+    reportLines.push("CODESIGHT.md output size, proportioned to the sections relevant to each task.");
+    reportLines.push("");
+    reportLines.push(`_Generated by codesight --telemetry_`);
+    const { writeFile: wf } = await import("node:fs/promises");
+    const { mkdir } = await import("node:fs/promises");
+    await mkdir(outputDir, { recursive: true });
+    await wf(join(outputDir, "telemetry.md"), reportLines.join("\n"));
+    return report;
+}