sourcebook 0.1.0 → 0.3.0

package/dist/generators/copilot.js

@@ -1,119 +1,104 @@
+import { hasCommands, categorizeFindings, enforceTokenBudget, } from "./shared.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 function generateCopilot(scan, budget) {
-    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 = [];
-    sections.push("# Copilot Instructions");
-    sections.push("");
-    sections.push("These instructions were generated by [sourcebook](https://github.com/maroondlabs/sourcebook). Review and edit — the best context comes from human + machine together.");
-    sections.push("");
+    sections.push({
+        key: "header",
+        content: [
+            "# Copilot Instructions",
+            "",
+            "These instructions were generated by [sourcebook](https://github.com/maroondlabs/sourcebook). Review and edit — the best context comes from human + machine together.",
+            "",
+        ].join("\n"),
+        priority: 100,
+    });
     // Commands
     if (hasCommands(scan.commands)) {
-        sections.push("## Development Commands");
-        sections.push("");
+        const lines = ["## Development Commands", ""];
         if (scan.commands.dev)
-            sections.push(`- Dev server: \`${scan.commands.dev}\``);
+            lines.push(`- Dev server: \`${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(`- Tests: \`${scan.commands.test}\``);
+            lines.push(`- Tests: \`${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 constraints
     if (critical.length > 0) {
-        sections.push("## Important Constraints");
-        sections.push("");
-        sections.push("Follow these rules when modifying this codebase:");
-        sections.push("");
+        const lines = [
+            "## Important Constraints",
+            "",
+            "Follow these rules when modifying this codebase:",
+            "",
+        ];
         for (const finding of critical) {
-            sections.push(`- ${finding.description}`);
+            lines.push(`- ${finding.description}`);
         }
-        sections.push("");
+        lines.push("");
+        sections.push({ key: "critical", content: lines.join("\n"), priority: 90 });
     }
     // Stack
     if (scan.frameworks.length > 0) {
-        sections.push("## Technology Stack");
-        sections.push("");
-        sections.push(`This project uses: ${scan.frameworks.join(", ")}.`);
-        sections.push("");
+        sections.push({
+            key: "stack",
+            content: [
+                "## Technology Stack",
+                "",
+                `This project uses: ${scan.frameworks.join(", ")}.`,
+                "",
+            ].join("\n"),
+            priority: 50,
+        });
     }
     // Core modules
     if (scan.rankedFiles && scan.rankedFiles.length > 0) {
-        const top5 = scan.rankedFiles.slice(0, 5);
-        sections.push("## High-Impact Files");
-        sections.push("");
-        sections.push("These files are imported by many others. Changes here have wide blast radius:");
-        sections.push("");
-        for (const { file } of top5) {
-            sections.push(`- \`${file}\``);
+        const lines = [
+            "## High-Impact Files",
+            "",
+            "These files are imported by many others. Changes here have wide blast radius:",
+            "",
+        ];
+        for (const { file } of scan.rankedFiles.slice(0, 5)) {
+            lines.push(`- \`${file}\``);
         }
-        sections.push("");
+        lines.push("");
+        sections.push({ key: "core_modules", content: lines.join("\n"), priority: 60 });
     }
     // Conventions
     if (important.length > 0) {
-        sections.push("## Code Conventions");
-        sections.push("");
-        sections.push("This project follows these patterns:");
-        sections.push("");
+        const lines = [
+            "## Code Conventions",
+            "",
+            "This project follows these patterns:",
+            "",
+        ];
         for (const finding of important) {
-            sections.push(`- ${finding.description}`);
+            lines.push(`- ${finding.description}`);
         }
-        sections.push("");
+        lines.push("");
+        sections.push({ key: "conventions", content: lines.join("\n"), priority: 30 });
     }
     // Additional context
     if (supplementary.length > 0) {
-        sections.push("## Additional Notes");
-        sections.push("");
+        const lines = ["## Additional Notes", ""];
         for (const finding of supplementary) {
-            sections.push(`- ${finding.description}`);
+            lines.push(`- ${finding.description}`);
         }
-        sections.push("");
+        lines.push("");
+        sections.push({ key: "supplementary", content: lines.join("\n"), priority: 20 });
     }
-    let output = sections.join("\n");
-    // Token budget enforcement
-    const charBudget = budget * 4;
-    if (output.length > charBudget) {
-        output = output.slice(0, charBudget);
-        const lastNewline = output.lastIndexOf("\n");
-        output = output.slice(0, lastNewline) + "\n";
-    }
-    return output;
-}
-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 hasCommands(commands) {
-    return Object.values(commands).some((v) => v !== undefined);
+    const kept = enforceTokenBudget(sections, budget);
+    return kept.join("\n");
 }

package/dist/generators/cursor.d.ts

@@ -1,17 +1,11 @@
 import type { ProjectScan } from "../types.js";
 /**
  * Generate Cursor rules from scan results.
- *
- * Cursor deprecated `.cursorrules` in favor of modular `.cursor/rules/*.mdc` files.
- * Each .mdc file has YAML frontmatter (description, globs, alwaysApply) + markdown body.
- *
- * We generate a single `sourcebook.mdc` with alwaysApply: true containing
- * the same non-discoverable findings as the Claude generator, formatted for
- * Cursor's conventions (shorter, more directive).
+ * Outputs .cursor/rules/sourcebook.mdc (modular format with YAML frontmatter)
+ * and legacy .cursorrules (same content, no frontmatter).
  */
 export declare function generateCursor(scan: ProjectScan, budget: number): string;
 /**
- * Also generate the legacy .cursorrules format for backwards compatibility.
- * Same content as the .mdc but without the frontmatter.
+ * Legacy .cursorrules format — same content without YAML frontmatter.
  */
 export declare function generateCursorLegacy(scan: ProjectScan, budget: number): string;

package/dist/generators/cursor.js

@@ -1,123 +1,93 @@
+import { hasCommands, categorizeFindings, enforceTokenBudget, } from "./shared.js";
 /**
  * Generate Cursor rules from scan results.
- *
- * Cursor deprecated `.cursorrules` in favor of modular `.cursor/rules/*.mdc` files.
- * Each .mdc file has YAML frontmatter (description, globs, alwaysApply) + markdown body.
- *
- * We generate a single `sourcebook.mdc` with alwaysApply: true containing
- * the same non-discoverable findings as the Claude generator, formatted for
- * Cursor's conventions (shorter, more directive).
+ * Outputs .cursor/rules/sourcebook.mdc (modular format with YAML frontmatter)
+ * and legacy .cursorrules (same content, no frontmatter).
  */
 export function generateCursor(scan, budget) {
-    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 = [];
     // MDC frontmatter
-    sections.push("---");
-    sections.push("description: Project conventions and constraints extracted by sourcebook");
-    sections.push("alwaysApply: true");
-    sections.push("---");
-    sections.push("");
+    sections.push({
+        key: "frontmatter",
+        content: [
+            "---",
+            "description: Project conventions and constraints extracted by sourcebook",
+            "alwaysApply: true",
+            "---",
+            "",
+        ].join("\n"),
+        priority: 100,
+    });
     // Commands
     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}\``);
-        sections.push("");
+            lines.push(`- Lint: \`${scan.commands.lint}\``);
+        lines.push("");
+        sections.push({ key: "commands", content: lines.join("\n"), priority: 95 });
     }
-    // Critical constraints at the top
+    // Critical constraints
     if (critical.length > 0) {
-        sections.push("## Constraints");
-        sections.push("");
+        const lines = ["## Constraints", ""];
         for (const finding of critical) {
-            sections.push(`- ${finding.description}`);
+            lines.push(`- ${finding.description}`);
         }
-        sections.push("");
+        lines.push("");
+        sections.push({ key: "critical", content: lines.join("\n"), priority: 90 });
     }
-    // Stack (brief)
+    // Stack
     if (scan.frameworks.length > 0) {
-        sections.push("## Stack");
-        sections.push("");
-        sections.push(scan.frameworks.join(", "));
-        sections.push("");
+        sections.push({
+            key: "stack",
+            content: ["## Stack", "", scan.frameworks.join(", "), ""].join("\n"),
+            priority: 50,
+        });
     }
     // Core modules
     if (scan.rankedFiles && scan.rankedFiles.length > 0) {
-        const top5 = scan.rankedFiles.slice(0, 5);
-        sections.push("## Core Modules");
-        sections.push("");
-        for (const { file } of top5) {
-            sections.push(`- \`${file}\``);
+        const lines = ["## Core Modules", ""];
+        for (const { file } of scan.rankedFiles.slice(0, 5)) {
+            lines.push(`- \`${file}\``);
         }
-        sections.push("");
+        lines.push("");
+        sections.push({ key: "core_modules", content: lines.join("\n"), priority: 60 });
     }
     // Conventions
     if (important.length > 0) {
-        sections.push("## Conventions");
-        sections.push("");
+        const lines = ["## Conventions", ""];
         for (const finding of important) {
-            sections.push(`- ${finding.description}`);
+            lines.push(`- ${finding.description}`);
         }
-        sections.push("");
+        lines.push("");
+        sections.push({ key: "conventions", content: lines.join("\n"), priority: 30 });
     }
     // Additional context
     if (supplementary.length > 0) {
-        sections.push("## Additional Context");
-        sections.push("");
+        const lines = ["## Additional Context", ""];
         for (const finding of supplementary) {
-            sections.push(`- ${finding.description}`);
+            lines.push(`- ${finding.description}`);
         }
-        sections.push("");
+        lines.push("");
+        sections.push({ key: "supplementary", content: lines.join("\n"), priority: 20 });
     }
-    let output = sections.join("\n");
-    // Token budget enforcement
-    const charBudget = budget * 4;
-    if (output.length > charBudget) {
-        output = output.slice(0, charBudget);
-        const lastNewline = output.lastIndexOf("\n");
-        output = output.slice(0, lastNewline) + "\n";
-    }
-    return output;
+    const kept = enforceTokenBudget(sections, budget);
+    return kept.join("\n");
 }
 /**
- * Also generate the legacy .cursorrules format for backwards compatibility.
- * Same content as the .mdc but without the frontmatter.
+ * Legacy .cursorrules format — same content without YAML frontmatter.
  */
 export function generateCursorLegacy(scan, budget) {
     const mdc = generateCursor(scan, budget);
-    // Strip the YAML frontmatter
     const endOfFrontmatter = mdc.indexOf("---", 4);
     if (endOfFrontmatter !== -1) {
         return mdc.slice(endOfFrontmatter + 4).trimStart();
     }
     return mdc;
 }
-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 hasCommands(commands) {
-    return Object.values(commands).some((v) => v !== undefined);
-}

package/dist/generators/shared.d.ts

@@ -0,0 +1,34 @@
+import type { Finding } from "../types.js";
+export declare function isCritical(finding: Finding): boolean;
+export declare function groupByCategory(findings: Finding[]): Map<string, Finding[]>;
+export declare function hasCommands(commands: Record<string, string | undefined>): boolean;
+/**
+ * Estimate token count for a string (rough: 1 token ≈ 4 chars).
+ */
+export declare function estimateTokens(text: string): number;
+/**
+ * Categorize findings into priority tiers for budget enforcement.
+ */
+export declare function categorizeFindings(findings: Finding[]): {
+    critical: Finding[];
+    important: Finding[];
+    supplementary: Finding[];
+};
+/**
+ * Smart budget enforcement. Instead of truncating at a character boundary,
+ * drop lower-priority sections first (middle of context = worst retention).
+ *
+ * Priority order (highest to lowest):
+ * 1. Commands (always keep)
+ * 2. Critical constraints (always keep)
+ * 3. Core modules (keep if budget allows)
+ * 4. Stack (keep if budget allows)
+ * 5. Conventions/important findings (drop first from middle)
+ * 6. Supplementary findings (drop first)
+ * 7. Footer/manual section (always keep — end of context = high retention)
+ */
+export declare function enforceTokenBudget(sections: {
+    key: string;
+    content: string;
+    priority: number;
+}[], budget: number): string[];

package/dist/generators/shared.js

@@ -0,0 +1,87 @@
+/**
+ * Shared helpers for all generators.
+ * Extracted to avoid duplicating criticality logic and budget enforcement.
+ */
+const CRITICAL_CATEGORIES = new Set([
+    "Hidden dependencies",
+    "Circular dependencies",
+    "Core modules",
+    "Fragile code",
+    "Git history",
+    "Commit conventions",
+    "Anti-patterns",
+]);
+const CRITICAL_KEYWORDS = [
+    "breaking", "blast radius", "deprecated", "don't", "must",
+    "never", "revert", "fragile", "hidden", "invisible", "coupling",
+];
+export function isCritical(finding) {
+    if (CRITICAL_CATEGORIES.has(finding.category))
+        return true;
+    const desc = finding.description.toLowerCase();
+    return CRITICAL_KEYWORDS.some((kw) => desc.includes(kw));
+}
+export 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;
+}
+export function hasCommands(commands) {
+    return Object.values(commands).some((v) => v !== undefined);
+}
+/**
+ * Estimate token count for a string (rough: 1 token ≈ 4 chars).
+ */
+export function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+/**
+ * Categorize findings into priority tiers for budget enforcement.
+ */
+export function categorizeFindings(findings) {
+    return {
+        critical: findings.filter((f) => f.confidence === "high" && isCritical(f)),
+        important: findings.filter((f) => f.confidence === "high" && !isCritical(f)),
+        supplementary: findings.filter((f) => f.confidence === "medium"),
+    };
+}
+/**
+ * Smart budget enforcement. Instead of truncating at a character boundary,
+ * drop lower-priority sections first (middle of context = worst retention).
+ *
+ * Priority order (highest to lowest):
+ * 1. Commands (always keep)
+ * 2. Critical constraints (always keep)
+ * 3. Core modules (keep if budget allows)
+ * 4. Stack (keep if budget allows)
+ * 5. Conventions/important findings (drop first from middle)
+ * 6. Supplementary findings (drop first)
+ * 7. Footer/manual section (always keep — end of context = high retention)
+ */
+export function enforceTokenBudget(sections, budget) {
+    // Sort by priority descending (highest priority = keep)
+    const sorted = [...sections].sort((a, b) => b.priority - a.priority);
+    let totalTokens = sorted.reduce((sum, s) => sum + estimateTokens(s.content), 0);
+    if (totalTokens <= budget) {
+        // Everything fits — return in original order
+        return sections.map((s) => s.content);
+    }
+    // Drop lowest-priority sections until we fit
+    const dropped = new Set();
+    const byPriority = [...sections].sort((a, b) => a.priority - b.priority);
+    for (const section of byPriority) {
+        if (totalTokens <= budget)
+            break;
+        if (section.priority >= 90)
+            continue; // Never drop critical sections
+        totalTokens -= estimateTokens(section.content);
+        dropped.add(section.key);
+    }
+    return sections
+        .filter((s) => !dropped.has(s.key))
+        .map((s) => s.content);
+}

package/dist/scanner/build.js

@@ -52,5 +52,33 @@ export async function detectBuildCommands(dir) {
             // can't read
         }
     }
+    // Check for go.mod
+    const goModPath = path.join(dir, "go.mod");
+    if (fs.existsSync(goModPath)) {
+        if (!commands.build)
+            commands.build = "go build ./...";
+        if (!commands.test)
+            commands.test = "go test ./...";
+        // Check for cmd/ entry points
+        const cmdDir = path.join(dir, "cmd");
+        if (fs.existsSync(cmdDir)) {
+            try {
+                const entries = fs.readdirSync(cmdDir);
+                if (entries.length === 1) {
+                    commands.dev = `go run ./cmd/${entries[0]}`;
+                }
+            }
+            catch { }
+        }
+        else {
+            if (!commands.dev)
+                commands.dev = "go run .";
+        }
+    }
+    // Check for requirements.txt / pyproject.toml Python commands
+    const hasRequirements = fs.existsSync(path.join(dir, "requirements.txt"));
+    if (hasRequirements && !commands.test) {
+        commands.test = "pytest";
+    }
     return commands;
 }