sourcebook 0.3.0 → 0.5.0

package/dist/generators/claude.js

@@ -1,4 +1,4 @@
-import { groupByCategory, hasCommands, categorizeFindings, enforceTokenBudget, } from "./shared.js";
+import { groupByCategory, hasCommands, categorizeFindings, enforceTokenBudget, buildQuickReference, getModePriorities, } from "./shared.js";
 /**
  * Generate a CLAUDE.md file from scan results.
  *
@@ -10,6 +10,7 @@ import { groupByCategory, hasCommands, categorizeFindings, enforceTokenBudget, }
  */
 export function generateClaude(scan, budget) {
     const { critical, important, supplementary } = categorizeFindings(scan.findings);
+    const priorities = getModePriorities(scan.repoMode);
     const sections = [];
     // ============================================
     // BEGINNING: Most critical info goes here
@@ -23,7 +24,12 @@ export function generateClaude(scan, budget) {
         "",
     ].join("\n");
     sections.push({ key: "header", content: header, priority: 100 });
-    // Commands first -- most immediately actionable
+    // Quick Reference — the "30-second handoff" (highest priority in app mode)
+    const quickRef = buildQuickReference(scan.findings);
+    if (quickRef) {
+        sections.push({ key: "quick_reference", content: quickRef, priority: priorities.quick_reference });
+    }
+    // Commands — most immediately actionable
     if (hasCommands(scan.commands)) {
         const lines = ["## Commands", ""];
         if (scan.commands.dev)
@@ -49,7 +55,7 @@ export function generateClaude(scan, budget) {
             lines.push(`- **${finding.category}:** ${finding.description}`);
         }
         lines.push("");
-        sections.push({ key: "critical", content: lines.join("\n"), priority: 90 });
+        sections.push({ key: "critical", content: lines.join("\n"), priority: priorities.critical });
     }
     // ============================================
     // MIDDLE: Less critical but useful info
@@ -58,7 +64,7 @@ export function generateClaude(scan, budget) {
     // Stack (brief)
     if (scan.frameworks.length > 0) {
         const content = ["## Stack", "", scan.frameworks.join(", "), ""].join("\n");
-        sections.push({ key: "stack", content, priority: 50 });
+        sections.push({ key: "stack", content, priority: priorities.stack });
     }
     // Key directories (only non-obvious ones)
     if (Object.keys(scan.structure.directories).length > 0) {
@@ -69,7 +75,7 @@ export function generateClaude(scan, budget) {
                 lines.push(`- \`${dir}/\` — ${purpose}`);
             }
             lines.push("");
-            sections.push({ key: "structure", content: lines.join("\n"), priority: 40 });
+            sections.push({ key: "structure", content: lines.join("\n"), priority: priorities.structure });
         }
     }
     // Core modules (from PageRank)
@@ -80,7 +86,7 @@ export function generateClaude(scan, budget) {
             lines.push(`- \`${file}\``);
         }
         lines.push("");
-        sections.push({ key: "core_modules", content: lines.join("\n"), priority: 60 });
+        sections.push({ key: "core_modules", content: lines.join("\n"), priority: priorities.core_modules });
     }
     // Important findings (high confidence, non-critical)
     if (important.length > 0) {
@@ -98,7 +104,7 @@ export function generateClaude(scan, budget) {
             }
         }
         lines.push("");
-        sections.push({ key: "conventions", content: lines.join("\n"), priority: 30 });
+        sections.push({ key: "conventions", content: lines.join("\n"), priority: priorities.conventions });
     }
     // Supplementary findings (medium confidence)
     if (supplementary.length > 0) {
@@ -116,7 +122,7 @@ export function generateClaude(scan, budget) {
             }
         }
         lines.push("");
-        sections.push({ key: "supplementary", content: lines.join("\n"), priority: 20 });
+        sections.push({ key: "supplementary", content: lines.join("\n"), priority: priorities.supplementary });
     }
     // ============================================
     // END: Important reminders go here

package/dist/generators/shared.d.ts

@@ -27,6 +27,18 @@ export declare function categorizeFindings(findings: Finding[]): {
  * 6. Supplementary findings (drop first)
  * 7. Footer/manual section (always keep — end of context = high retention)
  */
+/**
+ * Build a Quick Reference section from dominant pattern findings.
+ * This is the "30-second senior engineer handoff" — the single most
+ * actionable section in the output.
+ */
+export declare function buildQuickReference(findings: Finding[]): string | null;
+/**
+ * Get priority adjustments based on repo mode.
+ * App repos: boost dominant patterns, demote structural.
+ * Library repos: boost structural, demote patterns.
+ */
+export declare function getModePriorities(repoMode?: "app" | "library" | "monorepo"): Record<string, number>;
 export declare function enforceTokenBudget(sections: {
     key: string;
     content: string;

package/dist/generators/shared.js

@@ -10,6 +10,7 @@ const CRITICAL_CATEGORIES = new Set([
     "Git history",
     "Commit conventions",
     "Anti-patterns",
+    "Critical constraints",
 ]);
 const CRITICAL_KEYWORDS = [
     "breaking", "blast radius", "deprecated", "don't", "must",
@@ -62,6 +63,113 @@ export function categorizeFindings(findings) {
  * 6. Supplementary findings (drop first)
  * 7. Footer/manual section (always keep — end of context = high retention)
  */
+/**
+ * Build a Quick Reference section from dominant pattern findings.
+ * This is the "30-second senior engineer handoff" — the single most
+ * actionable section in the output.
+ */
+export function buildQuickReference(findings) {
+    const patterns = findings.filter((f) => f.category === "Dominant patterns");
+    if (patterns.length < 2)
+        return null;
+    const lines = ["## Quick Reference", ""];
+    for (const p of patterns) {
+        // Extract a short label from the description
+        const desc = p.description;
+        let label = "";
+        let value = desc;
+        if (desc.includes("internationalization") || desc.includes("i18n") || desc.includes("translation")) {
+            label = "i18n";
+        }
+        else if (desc.includes("route") || desc.includes("endpoint") || desc.includes("API")) {
+            label = "routing";
+        }
+        else if (desc.includes("validation") || desc.includes("schema") || desc.includes("Zod") || desc.includes("Pydantic")) {
+            label = "validation";
+        }
+        else if ((desc.includes("auth") || desc.includes("Auth") || desc.includes("session")) && !desc.includes("integration")) {
+            label = "auth";
+        }
+        else if (desc.includes("Test") || desc.includes("test")) {
+            label = "testing";
+        }
+        else if (desc.includes("Tailwind") || desc.includes("styled") || desc.includes("CSS")) {
+            label = "styling";
+        }
+        else if (desc.includes("database") || desc.includes("Database") || desc.includes("Prisma") || desc.includes("ORM")) {
+            label = "database";
+        }
+        else if (desc.includes("fetching") || desc.includes("Query") || desc.includes("SWR")) {
+            label = "data fetching";
+        }
+        else if (desc.includes("Route definitions") || desc.includes("Add new endpoints")) {
+            label = "routes";
+        }
+        else if (desc.includes("integration") || desc.includes("Third-party")) {
+            label = "integrations";
+        }
+        else if (desc.includes("components") || desc.includes("UI")) {
+            label = "components";
+        }
+        else if (desc.includes("Generated") || desc.includes("generated") || desc.includes("DO NOT")) {
+            label = "generated";
+        }
+        else {
+            continue; // Skip findings we can't label cleanly
+        }
+        // Compress the description to a short actionable line
+        const short = desc
+            .replace(/\. Follow this pattern.*$/, "")
+            .replace(/\. This is the project's standard.*$/, "")
+            .replace(/\. Each integration has.*$/, "");
+        lines.push(`- **${label}:** ${short}`);
+    }
+    if (lines.length <= 2)
+        return null; // Nothing useful
+    // Deduplicate by label — keep only first occurrence of each
+    const seen = new Set();
+    const deduped = [lines[0], lines[1]]; // Keep header
+    for (let i = 2; i < lines.length; i++) {
+        const labelMatch = lines[i].match(/^\- \*\*(\w[\w\s]*)\:\*\*/);
+        if (labelMatch) {
+            const lbl = labelMatch[1];
+            if (seen.has(lbl))
+                continue;
+            seen.add(lbl);
+        }
+        deduped.push(lines[i]);
+    }
+    deduped.push("");
+    return deduped.join("\n");
+}
+/**
+ * Get priority adjustments based on repo mode.
+ * App repos: boost dominant patterns, demote structural.
+ * Library repos: boost structural, demote patterns.
+ */
+export function getModePriorities(repoMode) {
+    if (repoMode === "library") {
+        return {
+            quick_reference: 85,
+            critical: 92,
+            core_modules: 90,
+            conventions: 80,
+            stack: 50,
+            structure: 40,
+            supplementary: 25,
+        };
+    }
+    // Default: app mode (boost patterns, Quick Reference highest)
+    return {
+        quick_reference: 96,
+        critical: 92,
+        core_modules: 50,
+        conventions: 85,
+        stack: 45,
+        structure: 60,
+        supplementary: 20,
+    };
+}
 export function enforceTokenBudget(sections, budget) {
     // Sort by priority descending (highest priority = keep)
     const sorted = [...sections].sort((a, b) => b.priority - a.priority);

package/dist/scanner/index.js

@@ -51,6 +51,8 @@ export async function scanProject(dir) {
         ...gitAnalysis.findings,
         ...graphAnalysis.findings,
     ];
+    // Detect repo mode for prioritization
+    const repoMode = detectRepoMode(dir, files, frameworks.map((f) => f.name));
     return {
         dir,
         files,
@@ -60,8 +62,29 @@ export async function scanProject(dir) {
         structure,
         findings,
         rankedFiles: graphAnalysis.rankedFiles,
+        repoMode,
     };
 }
+function detectRepoMode(dir, files, frameworks) {
+    // Monorepo detection
+    const hasWorkspaces = files.some((f) => f === "pnpm-workspace.yaml" || f === "lerna.json" || f === "nx.json");
+    if (hasWorkspaces)
+        return "monorepo";
+    // Library detection
+    const hasPublishConfig = files.some((f) => f === "setup.py" || f === "pyproject.toml" || f === "setup.cfg");
+    const hasSrcLib = files.some((f) => f.startsWith("src/lib/") || f.startsWith("lib/"));
+    const hasExportsField = false; // would need to read package.json, but frameworks already detected
+    const isLibraryFramework = frameworks.some((f) => ["FastAPI", "Flask", "Django", "Hono", "Express"].includes(f));
+    // If it has a setup.py/pyproject.toml AND no app/ or pages/ → library
+    const hasAppDirs = files.some((f) => f.startsWith("app/") || f.startsWith("pages/") || f.startsWith("src/app/") || f.startsWith("src/pages/"));
+    const hasComponents = files.some((f) => f.includes("/components/"));
+    if (hasPublishConfig && !hasAppDirs && !hasComponents)
+        return "library";
+    if (hasSrcLib && !hasAppDirs && !hasComponents && !isLibraryFramework)
+        return "library";
+    // Default: app
+    return "app";
+}
 function detectLanguages(files) {
     const extMap = {
         ".ts": "TypeScript",