sourcebook 0.5.1 → 0.5.2

package/README.md

@@ -4,25 +4,27 @@
 
 # sourcebook
 
-Generate AI context files from your codebase's actual conventions. Not what agents already know — what they keep missing.
+**AI can read your code. It still doesn't know how your project works.**
+
+sourcebook captures the project knowledge your team carries in its head — conventions, patterns, traps, and where things actually go — and turns it into context your coding agent can use.
 
 ```bash
 npx sourcebook init
 ```
 
-One command. Analyzes your codebase. Outputs a `CLAUDE.md` tuned for how your project actually works.
-
 <p align="center">
   <img src="demo.svg" alt="sourcebook demo" width="820" />
 </p>
 
+> Tools like Repomix give AI your entire codebase. sourcebook gives it your project knowledge.
+
 ## Why
 
-AI coding agents spend most of their context window just orienting — reading files to build a mental model before doing real work. Developers manually write context files (`CLAUDE.md`, `.cursorrules`, `copilot-instructions.md`), but most are generic and go stale fast.
+AI coding agents spend most of their context window orienting — reading files to build a mental model before doing real work. Most context files (`CLAUDE.md`, `.cursorrules`) are generic and go stale fast.
 
-Research shows auto-generated context that restates obvious information (tech stack, directory structure) actually makes agents [worse by 2-3%](https://arxiv.org/abs/2502.09601). The only context that helps is **non-discoverable information** — things agents can't figure out by reading the code alone.
+Research shows auto-generated context that restates obvious information actually makes agents [worse by 2-3%](https://arxiv.org/abs/2502.09601). The only context that helps is **non-discoverable information** — the project knowledge agents can't figure out by reading code alone.
 
-sourcebook inverts the typical approach: instead of dumping everything, it extracts only what agents keep missing, filtered through a discoverability test.
+sourcebook extracts only what agents keep missing: the conventions, hidden dependencies, fragile areas, and dominant patterns that live in your team's heads — not in the code.
 
 ## What It Finds
 

package/dist/commands/update.js

@@ -28,6 +28,8 @@ const SOURCEBOOK_HEADERS = new Set([
     "High-Impact Files",
     "Code Conventions",
     "Constraints",
+    "Quick Reference",
+    "Dominant Patterns",
 ]);
 /**
  * Re-analyze and regenerate context files while preserving manual edits.

package/dist/scanner/frameworks.js

@@ -218,9 +218,7 @@ export async function detectFrameworks(dir, files) {
                 }
                 const paths = tsconfig?.compilerOptions?.paths;
                 if (paths) {
-                    const aliases = Object.keys(paths)
-                        .map((k) => k.replace("/*", ""))
-                        .join(", ");
+                    const aliases = [...new Set(Object.keys(paths).map((k) => k.replace("/*", "")))].join(", ");
                     findings.push({
                         category: "TypeScript imports",
                         description: `Path aliases configured: ${aliases}. Use these instead of relative imports.`,

package/dist/scanner/git.js

@@ -67,9 +67,14 @@ function detectRevertedPatterns(dir, revertedPatterns) {
     if (reverts.length >= 2) {
         // Extract what was reverted
         const revertDescriptions = [];
+        const REVERT_NOISE = [
+            /\.yml$/i, /\.yaml$/i, /scorecard/i, /dependabot/i,
+            /^update /i, /^bump /i, /^deps/i, /^ci:/i, /^build:/i,
+            /^chore\(deps\)/i, /^chore\(release\)/i,
+        ];
         for (const line of reverts.slice(0, 10)) {
             const match = line.match(/^[a-f0-9]+ Revert "(.+)"/);
-            if (match) {
+            if (match && !REVERT_NOISE.some(n => n.test(match[1]))) {
                 revertDescriptions.push(match[1]);
                 revertedPatterns.push(match[1]);
             }
@@ -103,8 +108,15 @@ function detectAntiPatterns(dir) {
                 antiPatterns.push(match[1]);
             }
         }
-        if (antiPatterns.length > 0) {
-            for (const pattern of antiPatterns.slice(0, 5)) {
+        // Filter out noise: CI config, deps, version bumps
+        const REVERT_NOISE = [
+            /\.yml$/i, /\.yaml$/i, /scorecard/i, /dependabot/i,
+            /^update /i, /^bump /i, /^deps/i, /^ci:/i, /^build:/i,
+            /^chore\(deps\)/i, /^chore\(release\)/i,
+        ];
+        const meaningful = antiPatterns.filter(p => !REVERT_NOISE.some(n => n.test(p)));
+        if (meaningful.length > 0) {
+            for (const pattern of meaningful.slice(0, 5)) {
                 findings.push({
                     category: "Anti-patterns",
                     description: `Tried and reverted: "${pattern}". This approach was explicitly rejected.`,
@@ -137,8 +149,22 @@ function detectAntiPatterns(dir) {
         if (currentFiles.length >= 3) {
             deletionBatches.push({ message: currentMessage, files: currentFiles });
         }
+        // Filter out release/changeset/version commits and revert-of-revert noise
+        const NOISE_PATTERNS = [
+            /^chore\(release\)/i,
+            /^\[ci\] release/i,
+            /^version packages/i,
+            /^changeset/i,
+            /^bump/i,
+            /^release/i,
+            /^Revert "Revert/i,
+            /^merge/i,
+            /^ci:/i,
+            /^build:/i,
+            /^Revert /i,
+        ];
         // Only report significant deletions (3+ files in one commit = abandoned feature)
-        for (const batch of deletionBatches.slice(0, 3)) {
+        for (const batch of deletionBatches.filter(b => !NOISE_PATTERNS.some(p => p.test(b.message))).slice(0, 3)) {
             if (batch.files.length >= 3) {
                 const fileList = batch.files.slice(0, 3).map((f) => path.basename(f)).join(", ");
                 findings.push({
@@ -313,9 +339,17 @@ function detectRapidReEdits(dir) {
     }
     // Find files edited 5+ times within a 7-day window
     const churnyFiles = [];
+    // Filter out non-source files that naturally churn
+    const NON_SOURCE_PATTERNS = [
+        /\.md$/i, /\.mdx$/i, /\.rst$/i, /\.txt$/i, /\.json$/i, /\.ya?ml$/i, /\.lock$/i, /\.log$/i,
+        /CHANGELOG/i, /\.env/, /\.generated\./, /\.config\./,
+        /\.github\//, /\.claude\//, /dashboard\//, /ops\//,
+    ];
     for (const [file, dates] of fileEdits) {
         if (dates.length < 5)
             continue;
+        if (NON_SOURCE_PATTERNS.some((p) => p.test(file)))
+            continue;
         // Sort dates
         dates.sort((a, b) => a.getTime() - b.getTime());
         // Sliding window: find any 7-day window with 5+ edits
@@ -377,7 +411,7 @@ function detectCommitPatterns(dir) {
             .map(([scope]) => scope);
         findings.push({
             category: "Commit conventions",
-            description: `Uses Conventional Commits (feat/fix/docs/etc). ${topScopes.length > 0 ? `Common scopes: ${topScopes.join(", ")}` : ""}. Follow this pattern for new commits.`,
+            description: `Uses Conventional Commits (feat/fix/docs/etc).${topScopes.length > 0 ? ` Common scopes: ${topScopes.join(", ")}.` : ""} Follow this pattern for new commits.`,
             confidence: "high",
             discoverable: false,
         });

package/dist/scanner/patterns.js

@@ -64,8 +64,11 @@ function sampleFiles(files, maxCount) {
         f.includes("layout.") ||
         f.includes("middleware."));
     const rest = files.filter((f) => !priority.includes(f));
-    const shuffled = rest.sort(() => Math.random() - 0.5);
-    return [...priority, ...shuffled].slice(0, maxCount);
+    // Deterministic sampling: sort by path, take evenly spaced files
+    const sorted = rest.sort();
+    const step = Math.max(1, Math.floor(sorted.length / Math.max(1, maxCount - priority.length)));
+    const sampled = sorted.filter((_, i) => i % step === 0);
+    return [...priority, ...sampled].slice(0, maxCount);
 }
 function detectBarrelExports(files, contents) {
     const indexFiles = files.filter((f) => path.basename(f).startsWith("index.") && !f.includes("node_modules"));
@@ -318,7 +321,25 @@ function detectDominantPatterns(dir, files, contents, frameworks) {
             }
         }
     }
-    const dominantI18n = i18nPatterns.filter((p) => p.count >= 3).sort((a, b) => b.count - a.count);
+    // Filter: if only t() matched, require corroborating evidence (i18n files or packages)
+    const hasI18nFiles = files.some((f) => f.includes("locale") || f.includes("i18n") || f.includes("translations") || f.includes("messages/"));
+    let hasI18nPackage = false;
+    for (const [f, c] of allContents) {
+        if (f.endsWith("package.json") && (c.includes("i18next") || c.includes("react-intl") || c.includes("next-intl") || c.includes("@lingui"))) {
+            hasI18nPackage = true;
+            break;
+        }
+    }
+    const dominantI18n = i18nPatterns
+        .filter((p) => {
+        if (p.count < 3)
+            return false;
+        // t() alone is too generic — require corroborating evidence
+        if (p.hook === 't("key")' && !hasI18nFiles && !hasI18nPackage)
+            return false;
+        return true;
+    })
+        .sort((a, b) => b.count - a.count);
     if (dominantI18n.length > 0) {
         const primary = dominantI18n[0];
         let desc = `User-facing strings use ${primary.hook} for internationalization.`;
@@ -345,10 +366,10 @@ function detectDominantPatterns(dir, files, contents, frameworks) {
     // 2. ROUTING / API PATTERNS
     // ========================================
     const routerPatterns = [
-        { pattern: "trpc\\.router|createTRPCRouter|t\\.router", name: "tRPC routers", count: 0 },
+        { pattern: "trpc\\.router|createTRPCRouter|from ['\"]@trpc", name: "tRPC routers", count: 0 },
         { pattern: "express\\.Router|router\\.get|router\\.post", name: "Express routers", count: 0 },
         { pattern: "app\\.get\\(|app\\.post\\(|app\\.put\\(", name: "Express app routes", count: 0 },
-        { pattern: "Hono|app\\.route\\(|c\\.json\\(", name: "Hono routes", count: 0 },
+        { pattern: "new Hono|from ['\"]hono['\"]", name: "Hono routes", count: 0 },
         { pattern: "FastAPI|@app\\.(get|post|put|delete)", name: "FastAPI endpoints", count: 0 },
         { pattern: "flask\\.route|@app\\.route", name: "Flask routes", count: 0 },
         { pattern: "gin\\.Engine|r\\.GET|r\\.POST", name: "Gin routes", count: 0 },
@@ -377,7 +398,7 @@ function detectDominantPatterns(dir, files, contents, frameworks) {
     // ========================================
     const schemaPatterns = [
         { pattern: "z\\.object|z\\.string|z\\.number", name: "Zod", usage: "Use Zod schemas for validation", count: 0 },
-        { pattern: "BaseModel|Field\\(", name: "Pydantic", usage: "Use Pydantic BaseModel for data classes", count: 0 },
+        { pattern: "class\\s+\\w+\\(BaseModel\\)|from pydantic", name: "Pydantic", usage: "Use Pydantic BaseModel for data classes", count: 0 },
         { pattern: "Joi\\.object|Joi\\.string", name: "Joi", usage: "Use Joi schemas for validation", count: 0 },
         { pattern: "yup\\.object|yup\\.string", name: "Yup", usage: "Use Yup schemas for validation", count: 0 },
         { pattern: "class.*Serializer.*:|serializers\\.Serializer", name: "Django serializers", usage: "Use Django REST serializers for API data", count: 0 },
@@ -433,7 +454,7 @@ function detectDominantPatterns(dir, files, contents, frameworks) {
     // 5. TESTING PATTERNS
     // ========================================
     const testPatterns = [
-        { pattern: "describe\\(|it\\(|test\\(", name: "Jest/Vitest", count: 0 },
+        { pattern: "describe\\(|it\\(|test\\(", name: "_generic_test", count: 0 },
         { pattern: "def test_|class Test|pytest", name: "pytest", count: 0 },
         { pattern: "func Test.*\\(t \\*testing\\.T\\)", name: "Go testing", count: 0 },
         { pattern: "expect\\(.*\\)\\.to", name: "Chai/expect", count: 0 },
@@ -466,7 +487,46 @@ function detectDominantPatterns(dir, files, contents, frameworks) {
     }
     const dominantTest = testPatterns.filter((p) => p.count >= 2).sort((a, b) => b.count - a.count);
     if (dominantTest.length > 0) {
-        const primary = dominantTest[0];
+        let primary = dominantTest[0];
+        // Disambiguate generic test pattern by checking package.json devDependencies
+        if (primary.name === "_generic_test") {
+            let pkgContent = allContents.get("package.json") || "";
+            if (!pkgContent) {
+                const pkgPath = safePath(dir, "package.json");
+                if (pkgPath) {
+                    try {
+                        pkgContent = fs.readFileSync(pkgPath, "utf-8");
+                    }
+                    catch { /* skip */ }
+                }
+            }
+            if (pkgContent.includes('"vitest"')) {
+                primary = { ...primary, name: "Vitest" };
+            }
+            else if (pkgContent.includes('"jest"') || pkgContent.includes('"@jest/')) {
+                primary = { ...primary, name: "Jest" };
+            }
+            else if (pkgContent.includes('"mocha"')) {
+                primary = { ...primary, name: "Mocha" };
+            }
+            else if (pkgContent.includes('"jasmine"')) {
+                primary = { ...primary, name: "Jasmine" };
+            }
+            else {
+                // Check for Deno (deno.json/deno.jsonc) or Bun (bun.lockb)
+                const hasDeno = files.some(f => f === "deno.json" || f === "deno.jsonc" || f === "deno.lock");
+                const hasBun = files.some(f => f === "bun.lockb" || f === "bunfig.toml");
+                if (hasDeno) {
+                    primary = { ...primary, name: "Deno test" };
+                }
+                else if (hasBun) {
+                    primary = { ...primary, name: "Bun test" };
+                }
+                else {
+                    primary = { ...primary, name: "Jest" }; // default for JS/TS projects
+                }
+            }
+        }
         // Also detect common test utilities/helpers
         const testHelperFiles = files.filter((f) => (f.includes("test-utils") || f.includes("testUtils") || f.includes("fixtures") || f.includes("helpers")) &&
             (f.includes("test") || f.includes("spec")));
@@ -527,9 +587,9 @@ function detectDominantPatterns(dir, files, contents, frameworks) {
     // 7. STYLING CONVENTIONS
     // ========================================
     const stylePatterns = [
-        { pattern: "className=|class=.*tw-", name: "Tailwind CSS", desc: "Styling uses Tailwind CSS utility classes", count: 0 },
-        { pattern: "styled\\.|styled\\(|css`", name: "styled-components/Emotion", desc: "Styling uses CSS-in-JS (styled-components or Emotion)", count: 0 },
-        { pattern: "styles\\.\\w+|from.*\\.module\\.(css|scss)", name: "CSS Modules", desc: "Styling uses CSS Modules (*.module.css)", count: 0 },
+        { pattern: "class=.*tw-|className=[\"'](?:flex |grid |p-|m-|text-|bg-|border-|rounded-|shadow-|w-|h-)", name: "Tailwind CSS", desc: "Styling uses Tailwind CSS utility classes", count: 0 },
+        { pattern: "from ['\"]styled-components|from ['\"]@emotion|styled\\.|styled\\(", name: "styled-components/Emotion", desc: "Styling uses CSS-in-JS (styled-components or Emotion)", count: 0 },
+        { pattern: "from.*\\.module\\.(css|scss)", name: "CSS Modules", desc: "Styling uses CSS Modules (*.module.css)", count: 0 },
     ];
     for (const [f, content] of allContents) {
         for (const p of stylePatterns) {
@@ -645,13 +705,15 @@ function detectDominantPatterns(dir, files, contents, frameworks) {
     if (dominantRouter.length > 0) {
         const routeDirs = files
             .filter((f) => (f.includes("routes") || f.includes("routers") || f.includes("api/") || f.includes("app/api/")) &&
-            !f.includes("node_modules") && !f.includes(".test.") &&
+            !f.includes("node_modules") && !f.includes(".test.") && !f.includes(".spec.") &&
+            !f.includes("test/") && !f.includes("tests/") && !f.includes("__test") &&
+            !f.includes("fixture") && !f.includes("mock") &&
             (f.endsWith(".ts") || f.endsWith(".js") || f.endsWith(".py") || f.endsWith(".go")))
             .map((f) => {
             const parts = f.split("/");
-            // Get the directory containing route files
             return parts.slice(0, -1).join("/");
         })
+            .filter((v) => v && v !== "." && v.length > 0) // filter empty/root paths
             .filter((v, i, a) => a.indexOf(v) === i)
             .slice(0, 3);
         if (routeDirs.length > 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sourcebook",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "description": "Extract the conventions, constraints, and architectural truths your AI coding agents keep missing.",
   "type": "module",
   "bin": {