sourcebook 0.1.0 → 0.3.0

package/README.md

@@ -1,3 +1,7 @@
+<p align="center">
+  <img src="logo.png" alt="sourcebook" width="120" />
+</p>
+
 # sourcebook
 
 Generate AI context files from your codebase's actual conventions. Not what agents already know — what they keep missing.

package/dist/cli.js

@@ -1,17 +1,33 @@
 #!/usr/bin/env node
 import { Command } from "commander";
 import { init } from "./commands/init.js";
+import { update } from "./commands/update.js";
+import { diff } from "./commands/diff.js";
 const program = new Command();
 program
     .name("sourcebook")
     .description("Extract the conventions, constraints, and architectural truths your AI coding agents keep missing.")
-    .version("0.1.0");
+    .version("0.3.0");
 program
     .command("init")
     .description("Analyze a codebase and generate agent context files")
     .option("-d, --dir <path>", "Target directory to analyze", ".")
-    .option("-f, --format <formats>", "Output formats (claude,cursor,copilot,agents,json)", "claude")
+    .option("-f, --format <formats>", "Output formats (claude,cursor,copilot,all)", "claude")
     .option("--budget <tokens>", "Max token budget for generated context", "4000")
     .option("--dry-run", "Preview findings without writing files")
     .action(init);
+program
+    .command("update")
+    .description("Re-analyze and update context files while preserving manual edits")
+    .option("-d, --dir <path>", "Target directory to analyze", ".")
+    .option("-f, --format <formats>", "Output formats (claude,cursor,copilot,all)", "claude")
+    .option("--budget <tokens>", "Max token budget for generated context", "4000")
+    .action(update);
+program
+    .command("diff")
+    .description("Show what would change if context files were regenerated")
+    .option("-d, --dir <path>", "Target directory to analyze", ".")
+    .option("-f, --format <formats>", "Output format to diff (claude,cursor,copilot)", "claude")
+    .option("--budget <tokens>", "Max token budget for generated context", "4000")
+    .action(diff);
 program.parse();

package/dist/commands/diff.d.ts

@@ -0,0 +1,12 @@
+interface DiffOptions {
+    dir: string;
+    format: string;
+    budget: string;
+}
+/**
+ * Show what would change if sourcebook regenerated the context files.
+ * Does not write any files — pure comparison.
+ * Exit code: 0 if no changes, 1 if changes found (useful for CI).
+ */
+export declare function diff(options: DiffOptions): Promise<void>;
+export {};

package/dist/commands/diff.js

@@ -0,0 +1,97 @@
+import fs from "node:fs";
+import path from "node:path";
+import chalk from "chalk";
+import { scanProject } from "../scanner/index.js";
+import { generateClaude } from "../generators/claude.js";
+import { generateCursor } from "../generators/cursor.js";
+import { generateCopilot } from "../generators/copilot.js";
+/**
+ * Show what would change if sourcebook regenerated the context files.
+ * Does not write any files — pure comparison.
+ * Exit code: 0 if no changes, 1 if changes found (useful for CI).
+ */
+export async function diff(options) {
+    const targetDir = path.resolve(options.dir);
+    const format = options.format.split(",")[0].trim(); // diff one format at a time
+    const budget = parseInt(options.budget, 10);
+    console.log(chalk.bold("\nsourcebook diff"));
+    console.log(chalk.dim("Comparing current context with fresh analysis...\n"));
+    const scan = await scanProject(targetDir);
+    const formatMap = {
+        claude: {
+            generator: () => generateClaude(scan, budget),
+            file: "CLAUDE.md",
+        },
+        cursor: {
+            generator: () => generateCursor(scan, budget),
+            file: ".cursor/rules/sourcebook.mdc",
+        },
+        copilot: {
+            generator: () => generateCopilot(scan, budget),
+            file: ".github/copilot-instructions.md",
+        },
+    };
+    const config = formatMap[format];
+    if (!config) {
+        console.log(chalk.yellow(`⚠ Format "${format}" not supported for diff`));
+        process.exit(1);
+    }
+    const filePath = path.join(targetDir, config.file);
+    let existing;
+    try {
+        existing = fs.readFileSync(filePath, "utf-8");
+    }
+    catch {
+        console.log(chalk.yellow(`⚠ ${config.file} does not exist yet. Run \`sourcebook init\` first.`));
+        process.exit(1);
+    }
+    const fresh = config.generator();
+    if (existing.trim() === fresh.trim()) {
+        console.log(chalk.green("✓") + ` ${config.file} is up to date. No changes needed.\n`);
+        process.exit(0);
+    }
+    // Line-by-line diff
+    const existingLines = existing.split("\n");
+    const freshLines = fresh.split("\n");
+    let hasChanges = false;
+    console.log(chalk.bold(`  ${config.file}\n`));
+    // Simple diff: show removed and added lines
+    const maxLen = Math.max(existingLines.length, freshLines.length);
+    // Build sets for quick lookup
+    const existingSet = new Set(existingLines.map((l) => l.trim()).filter(Boolean));
+    const freshSet = new Set(freshLines.map((l) => l.trim()).filter(Boolean));
+    // Lines only in existing (removed)
+    const removed = existingLines.filter((l) => l.trim() && !freshSet.has(l.trim()));
+    // Lines only in fresh (added)
+    const added = freshLines.filter((l) => l.trim() && !existingSet.has(l.trim()));
+    if (removed.length > 0) {
+        hasChanges = true;
+        console.log(chalk.red("  Removed:"));
+        for (const line of removed.slice(0, 20)) {
+            console.log(chalk.red(`  - ${line}`));
+        }
+        if (removed.length > 20) {
+            console.log(chalk.dim(`  ... and ${removed.length - 20} more`));
+        }
+        console.log("");
+    }
+    if (added.length > 0) {
+        hasChanges = true;
+        console.log(chalk.green("  Added:"));
+        for (const line of added.slice(0, 20)) {
+            console.log(chalk.green(`  + ${line}`));
+        }
+        if (added.length > 20) {
+            console.log(chalk.dim(`  ... and ${added.length - 20} more`));
+        }
+        console.log("");
+    }
+    if (hasChanges) {
+        console.log(chalk.dim("  Run `sourcebook update` to apply these changes while preserving your edits.\n"));
+        process.exit(1);
+    }
+    else {
+        console.log(chalk.green("✓") + " No meaningful changes detected.\n");
+        process.exit(0);
+    }
+}

package/dist/commands/update.d.ts

@@ -0,0 +1,17 @@
+interface UpdateOptions {
+    dir: string;
+    format: string;
+    budget: string;
+}
+/**
+ * Re-analyze and regenerate context files while preserving manual edits.
+ *
+ * Strategy:
+ * 1. Read existing output file
+ * 2. Parse into sections (split on ## headers)
+ * 3. Identify manual sections (headers not in SOURCEBOOK_HEADERS)
+ * 4. Re-run scan and generate fresh content
+ * 5. Replace sourcebook sections, keep manual sections in their original positions
+ */
+export declare function update(options: UpdateOptions): Promise<void>;
+export {};

package/dist/commands/update.js

@@ -0,0 +1,177 @@
+import fs from "node:fs";
+import path from "node:path";
+import chalk from "chalk";
+import { scanProject } from "../scanner/index.js";
+import { generateClaude } from "../generators/claude.js";
+import { generateCursor, generateCursorLegacy } from "../generators/cursor.js";
+import { generateCopilot } from "../generators/copilot.js";
+import { writeOutput } from "../utils/output.js";
+// Headers that sourcebook generates — anything else is user-added
+const SOURCEBOOK_HEADERS = new Set([
+    "CLAUDE.md",
+    "Commands",
+    "Critical Constraints",
+    "Stack",
+    "Project Structure",
+    "Core Modules (by structural importance)",
+    "Core Modules",
+    "Conventions & Patterns",
+    "Conventions",
+    "Additional Context",
+    "Additional Notes",
+    "What to Add Manually",
+    "Copilot Instructions",
+    "Development Commands",
+    "Important Constraints",
+    "Technology Stack",
+    "High-Impact Files",
+    "Code Conventions",
+    "Constraints",
+]);
+/**
+ * Re-analyze and regenerate context files while preserving manual edits.
+ *
+ * Strategy:
+ * 1. Read existing output file
+ * 2. Parse into sections (split on ## headers)
+ * 3. Identify manual sections (headers not in SOURCEBOOK_HEADERS)
+ * 4. Re-run scan and generate fresh content
+ * 5. Replace sourcebook sections, keep manual sections in their original positions
+ */
+export async function update(options) {
+    const targetDir = path.resolve(options.dir);
+    const formats = options.format.split(",").map((f) => f.trim());
+    const budget = parseInt(options.budget, 10);
+    console.log(chalk.bold("\nsourcebook update"));
+    console.log(chalk.dim("Re-analyzing while preserving your edits...\n"));
+    const scan = await scanProject(targetDir);
+    console.log(chalk.green("✓") + " Scanned project structure");
+    console.log(chalk.dim(`  ${scan.files.length} files, ${scan.frameworks.length} frameworks detected`));
+    console.log(chalk.green("✓") + ` Extracted ${scan.findings.length} findings\n`);
+    for (const format of formats) {
+        switch (format) {
+            case "claude": {
+                const fresh = generateClaude(scan, budget);
+                const existing = readExisting(targetDir, "CLAUDE.md");
+                const merged = existing ? mergeContent(existing, fresh) : fresh;
+                await writeOutput(targetDir, "CLAUDE.md", merged);
+                const preserved = existing ? countManualSections(existing) : 0;
+                console.log(chalk.green("✓") +
+                    ` Updated CLAUDE.md` +
+                    (preserved > 0 ? chalk.dim(` (${preserved} manual section${preserved > 1 ? "s" : ""} preserved)`) : ""));
+                break;
+            }
+            case "cursor": {
+                const fresh = generateCursor(scan, budget);
+                await writeOutput(targetDir, ".cursor/rules/sourcebook.mdc", fresh);
+                const legacyFresh = generateCursorLegacy(scan, budget);
+                await writeOutput(targetDir, ".cursorrules", legacyFresh);
+                console.log(chalk.green("✓") + " Updated .cursor/rules/sourcebook.mdc");
+                break;
+            }
+            case "copilot": {
+                const fresh = generateCopilot(scan, budget);
+                const existing = readExisting(targetDir, ".github/copilot-instructions.md");
+                const merged = existing ? mergeContent(existing, fresh) : fresh;
+                await writeOutput(targetDir, ".github/copilot-instructions.md", merged);
+                const preserved = existing ? countManualSections(existing) : 0;
+                console.log(chalk.green("✓") +
+                    ` Updated .github/copilot-instructions.md` +
+                    (preserved > 0 ? chalk.dim(` (${preserved} manual section${preserved > 1 ? "s" : ""} preserved)`) : ""));
+                break;
+            }
+            case "all": {
+                // Recurse for each format
+                for (const f of ["claude", "cursor", "copilot"]) {
+                    await update({ ...options, format: f });
+                }
+                return;
+            }
+            default:
+                console.log(chalk.yellow(`⚠ Format "${format}" not yet supported`));
+        }
+    }
+    console.log(chalk.dim("\nDone. Your manual sections were preserved.\n"));
+}
+function readExisting(dir, filename) {
+    const filePath = path.join(dir, filename);
+    try {
+        return fs.readFileSync(filePath, "utf-8");
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Parse markdown into sections split by ## headers.
+ */
+function parseSections(content) {
+    const sections = [];
+    const lines = content.split("\n");
+    let currentHeader = "";
+    let currentBody = [];
+    for (const line of lines) {
+        const headerMatch = line.match(/^##\s+(.+)/);
+        if (headerMatch) {
+            if (currentHeader || currentBody.length > 0) {
+                sections.push({ header: currentHeader, body: currentBody.join("\n") });
+            }
+            currentHeader = headerMatch[1].trim();
+            currentBody = [];
+        }
+        else {
+            currentBody.push(line);
+        }
+    }
+    if (currentHeader || currentBody.length > 0) {
+        sections.push({ header: currentHeader, body: currentBody.join("\n") });
+    }
+    return sections;
+}
+function isSourcebookSection(header) {
+    return SOURCEBOOK_HEADERS.has(header) || header === "";
+}
+function countManualSections(content) {
+    const sections = parseSections(content);
+    return sections.filter((s) => s.header && !isSourcebookSection(s.header)).length;
+}
+/**
+ * Merge fresh sourcebook output with existing content,
+ * preserving any manually added sections.
+ */
+function mergeContent(existing, fresh) {
+    const existingSections = parseSections(existing);
+    const freshSections = parseSections(fresh);
+    // Extract manual sections from existing content
+    const manualSections = existingSections.filter((s) => s.header && !isSourcebookSection(s.header));
+    if (manualSections.length === 0) {
+        // No manual sections — just use the fresh content
+        return fresh;
+    }
+    // Find where "What to Add Manually" or last section is in fresh content
+    // Insert manual sections before the footer
+    const result = [];
+    let insertedManual = false;
+    for (const section of freshSections) {
+        // Insert manual sections before the "What to Add Manually" footer
+        if (section.header === "What to Add Manually" && !insertedManual) {
+            for (const manual of manualSections) {
+                result.push(`## ${manual.header}`);
+                result.push(manual.body);
+            }
+            insertedManual = true;
+        }
+        if (section.header) {
+            result.push(`## ${section.header}`);
+        }
+        result.push(section.body);
+    }
+    // If we never found the footer, append manual sections at the end
+    if (!insertedManual) {
+        for (const manual of manualSections) {
+            result.push(`## ${manual.header}`);
+            result.push(manual.body);
+        }
+    }
+    return result.join("\n");
+}

package/dist/generators/claude.js

@@ -1,3 +1,4 @@
+import { groupByCategory, hasCommands, categorizeFindings, enforceTokenBudget, } from "./shared.js";
 /**
  * Generate a CLAUDE.md file from scan results.
  *
@@ -8,47 +9,47 @@
  * 3. Karpathy's program.md pattern: constraints, gotchas, and autonomy boundaries
  */
 export function generateClaude(scan, budget) {
-    // Separate findings by importance for context-rot-aware placement
-    const critical = scan.findings.filter((f) => f.confidence === "high" && isCritical(f));
-    const important = scan.findings.filter((f) => f.confidence === "high" && !isCritical(f));
-    const supplementary = scan.findings.filter((f) => f.confidence === "medium");
+    const { critical, important, supplementary } = categorizeFindings(scan.findings);
     const sections = [];
     // ============================================
     // BEGINNING: Most critical info goes here
     // (LLMs retain start of context best)
     // ============================================
-    sections.push("# CLAUDE.md");
-    sections.push("");
-    sections.push("This file provides guidance to Claude Code when working with this codebase.");
-    sections.push("Generated by [sourcebook](https://github.com/maroondlabs/sourcebook). Review and edit — the best context comes from human + machine together.");
-    sections.push("");
+    const header = [
+        "# CLAUDE.md",
+        "",
+        "This file provides guidance to Claude Code when working with this codebase.",
+        "Generated by [sourcebook](https://github.com/maroondlabs/sourcebook). Review and edit — the best context comes from human + machine together.",
+        "",
+    ].join("\n");
+    sections.push({ key: "header", content: header, priority: 100 });
     // Commands first -- most immediately actionable
     if (hasCommands(scan.commands)) {
-        sections.push("## Commands");
-        sections.push("");
+        const lines = ["## Commands", ""];
         if (scan.commands.dev)
-            sections.push(`- **Dev:** \`${scan.commands.dev}\``);
+            lines.push(`- **Dev:** \`${scan.commands.dev}\``);
         if (scan.commands.build)
-            sections.push(`- **Build:** \`${scan.commands.build}\``);
+            lines.push(`- **Build:** \`${scan.commands.build}\``);
         if (scan.commands.test)
-            sections.push(`- **Test:** \`${scan.commands.test}\``);
+            lines.push(`- **Test:** \`${scan.commands.test}\``);
         if (scan.commands.lint)
-            sections.push(`- **Lint:** \`${scan.commands.lint}\``);
+            lines.push(`- **Lint:** \`${scan.commands.lint}\``);
         for (const [name, cmd] of Object.entries(scan.commands)) {
             if (cmd && !["dev", "build", "test", "lint", "start"].includes(name)) {
-                sections.push(`- **${name}:** \`${cmd}\``);
+                lines.push(`- **${name}:** \`${cmd}\``);
             }
         }
-        sections.push("");
+        lines.push("");
+        sections.push({ key: "commands", content: lines.join("\n"), priority: 95 });
     }
-    // Critical warnings/constraints near the top (danger zone, fragile code, hidden deps)
+    // Critical warnings/constraints near the top
     if (critical.length > 0) {
-        sections.push("## Critical Constraints");
-        sections.push("");
+        const lines = ["## Critical Constraints", ""];
         for (const finding of critical) {
-            sections.push(`- **${finding.category}:** ${finding.description}`);
+            lines.push(`- **${finding.category}:** ${finding.description}`);
         }
-        sections.push("");
+        lines.push("");
+        sections.push({ key: "critical", content: lines.join("\n"), priority: 90 });
     }
     // ============================================
     // MIDDLE: Less critical but useful info
@@ -56,136 +57,85 @@ export function generateClaude(scan, budget) {
     // ============================================
     // Stack (brief)
     if (scan.frameworks.length > 0) {
-        sections.push("## Stack");
-        sections.push("");
-        sections.push(scan.frameworks.join(", "));
-        sections.push("");
+        const content = ["## Stack", "", scan.frameworks.join(", "), ""].join("\n");
+        sections.push({ key: "stack", content, priority: 50 });
     }
     // Key directories (only non-obvious ones)
     if (Object.keys(scan.structure.directories).length > 0) {
         const nonObvious = Object.entries(scan.structure.directories).filter(([dir]) => !["src", "public", "node_modules", "dist", "build"].includes(dir));
         if (nonObvious.length > 0) {
-            sections.push("## Project Structure");
-            sections.push("");
+            const lines = ["## Project Structure", ""];
             for (const [dir, purpose] of nonObvious) {
-                sections.push(`- \`${dir}/\` — ${purpose}`);
+                lines.push(`- \`${dir}/\` — ${purpose}`);
             }
-            sections.push("");
+            lines.push("");
+            sections.push({ key: "structure", content: lines.join("\n"), priority: 40 });
         }
     }
     // Core modules (from PageRank)
     if (scan.rankedFiles && scan.rankedFiles.length > 0) {
         const top5 = scan.rankedFiles.slice(0, 5);
-        sections.push("## Core Modules (by structural importance)");
-        sections.push("");
+        const lines = ["## Core Modules (by structural importance)", ""];
         for (const { file } of top5) {
-            sections.push(`- \`${file}\``);
+            lines.push(`- \`${file}\``);
         }
-        sections.push("");
+        lines.push("");
+        sections.push({ key: "core_modules", content: lines.join("\n"), priority: 60 });
     }
     // Important findings (high confidence, non-critical)
     if (important.length > 0) {
-        sections.push("## Conventions & Patterns");
-        sections.push("");
+        const lines = ["## Conventions & Patterns", ""];
         const grouped = groupByCategory(important);
         for (const [category, findings] of grouped) {
             if (findings.length === 1) {
-                sections.push(`- **${category}:** ${findings[0].description}`);
+                lines.push(`- **${category}:** ${findings[0].description}`);
             }
             else {
-                sections.push(`- **${category}:**`);
+                lines.push(`- **${category}:**`);
                 for (const f of findings) {
-                    sections.push(`  - ${f.description}`);
+                    lines.push(`  - ${f.description}`);
                 }
             }
         }
-        sections.push("");
+        lines.push("");
+        sections.push({ key: "conventions", content: lines.join("\n"), priority: 30 });
     }
     // Supplementary findings (medium confidence)
     if (supplementary.length > 0) {
-        sections.push("## Additional Context");
-        sections.push("");
+        const lines = ["## Additional Context", ""];
         const grouped = groupByCategory(supplementary);
         for (const [category, findings] of grouped) {
             if (findings.length === 1) {
-                sections.push(`- **${category}:** ${findings[0].description}`);
+                lines.push(`- **${category}:** ${findings[0].description}`);
             }
             else {
-                sections.push(`- **${category}:**`);
+                lines.push(`- **${category}:**`);
                 for (const f of findings) {
-                    sections.push(`  - ${f.description}`);
+                    lines.push(`  - ${f.description}`);
                 }
             }
         }
-        sections.push("");
+        lines.push("");
+        sections.push({ key: "supplementary", content: lines.join("\n"), priority: 20 });
     }
     // ============================================
     // END: Important reminders go here
     // (LLMs retain end of context second-best)
     // ============================================
-    // "What to add" section -- prompts human to add non-discoverable context
-    sections.push("## What to Add Manually");
-    sections.push("");
-    sections.push("The most valuable context is what only you know. Add:");
-    sections.push("");
-    sections.push("- Architectural decisions and why they were made");
-    sections.push("- Past incidents that shaped current conventions");
-    sections.push("- Deprecated patterns to avoid in new code");
-    sections.push("- Domain-specific rules or terminology");
-    sections.push("- Environment setup beyond what .env.example shows");
-    sections.push("");
-    let output = sections.join("\n");
-    // Token budget enforcement (rough: 1 token ≈ 4 chars)
-    const charBudget = budget * 4;
-    if (output.length > charBudget) {
-        output = output.slice(0, charBudget);
-        const lastNewline = output.lastIndexOf("\n");
-        output =
-            output.slice(0, lastNewline) +
-                "\n\n<!-- truncated to fit token budget -->\n";
-    }
-    return output;
-}
-/**
- * Determine if a finding is "critical" -- things that can cause real damage
- * if an agent gets them wrong. These go at the TOP of the file.
- */
-function isCritical(finding) {
-    const criticalCategories = new Set([
-        "Hidden dependencies",
-        "Circular dependencies",
-        "Core modules",
-        "Fragile code",
-        "Git history",
-        "Commit conventions",
-    ]);
-    const criticalKeywords = [
-        "breaking",
-        "blast radius",
-        "deprecated",
-        "don't",
-        "must",
-        "never",
-        "revert",
-        "fragile",
-        "hidden",
-        "invisible",
-        "coupling",
-    ];
-    if (criticalCategories.has(finding.category))
-        return true;
-    const desc = finding.description.toLowerCase();
-    return criticalKeywords.some((kw) => desc.includes(kw));
-}
-function groupByCategory(findings) {
-    const grouped = new Map();
-    for (const finding of findings) {
-        const existing = grouped.get(finding.category) || [];
-        existing.push(finding);
-        grouped.set(finding.category, existing);
-    }
-    return grouped;
-}
-function hasCommands(commands) {
-    return Object.values(commands).some((v) => v !== undefined);
+    const footer = [
+        "## What to Add Manually",
+        "",
+        "The most valuable context is what only you know. Add:",
+        "",
+        "- Architectural decisions and why they were made",
+        "- Past incidents that shaped current conventions",
+        "- Deprecated patterns to avoid in new code",
+        "- Domain-specific rules or terminology",
+        "- Environment setup beyond what .env.example shows",
+        "",
+    ].join("\n");
+    sections.push({ key: "footer", content: footer, priority: 90 });
+    // Apply smart budget enforcement
+    const kept = enforceTokenBudget(sections, budget);
+    return kept.join("\n");
 }

package/dist/generators/copilot.d.ts

@@ -1,12 +1,6 @@
 import type { ProjectScan } from "../types.js";
 /**
  * Generate GitHub Copilot instructions from scan results.
- *
- * Copilot supports:
- * - `.github/copilot-instructions.md` — repo-level instructions (always loaded)
- * - `.instructions.md` — per-directory instructions (loaded when files in that dir are referenced)
- *
- * We generate the repo-level file. Copilot's format is plain markdown with
- * natural language instructions — more conversational than Cursor's directive style.
+ * Outputs .github/copilot-instructions.md — conversational style.
  */
 export declare function generateCopilot(scan: ProjectScan, budget: number): string;