sourcebook 0.1.0 → 0.3.0

package/dist/scanner/frameworks.js

@@ -226,5 +226,146 @@ export async function detectFrameworks(dir, files) {
             findings,
         });
     }
+    // --- Python ---
+    const hasPyproject = fs.existsSync(path.join(dir, "pyproject.toml"));
+    const hasRequirements = fs.existsSync(path.join(dir, "requirements.txt"));
+    const hasSetupPy = fs.existsSync(path.join(dir, "setup.py"));
+    if (hasPyproject || hasRequirements || hasSetupPy) {
+        const findings = [];
+        let pyDeps = "";
+        if (hasPyproject) {
+            try {
+                pyDeps = fs.readFileSync(path.join(dir, "pyproject.toml"), "utf-8");
+            }
+            catch { }
+        }
+        else if (hasRequirements) {
+            try {
+                pyDeps = fs.readFileSync(path.join(dir, "requirements.txt"), "utf-8");
+            }
+            catch { }
+        }
+        const pyDepsLower = pyDeps.toLowerCase();
+        // Django
+        if (pyDepsLower.includes("django")) {
+            const hasManagePy = files.includes("manage.py");
+            const settingsFile = files.find((f) => f.endsWith("settings.py") || f.includes("settings/"));
+            findings.push({
+                category: "Django",
+                description: `Django project${settingsFile ? ` (settings: ${settingsFile})` : ""}. Use \`python manage.py\` for management commands.`,
+                confidence: "high",
+                discoverable: false,
+            });
+            if (files.some((f) => f.endsWith("models.py"))) {
+                findings.push({
+                    category: "Django",
+                    description: "After modifying models, run `python manage.py makemigrations && python manage.py migrate`.",
+                    rationale: "Agents forget to create migrations after model changes, causing runtime errors.",
+                    confidence: "high",
+                    discoverable: false,
+                });
+            }
+            detected.push({ name: "Django", findings });
+        }
+        // FastAPI
+        else if (pyDepsLower.includes("fastapi")) {
+            findings.push({
+                category: "FastAPI",
+                description: "FastAPI project. Use Pydantic models for request/response schemas, not raw dicts.",
+                confidence: "high",
+                discoverable: false,
+            });
+            if (pyDepsLower.includes("sqlalchemy") || pyDepsLower.includes("sqlmodel")) {
+                findings.push({
+                    category: "FastAPI",
+                    description: "Uses SQLAlchemy/SQLModel for ORM. Database sessions must be properly closed (use dependency injection).",
+                    confidence: "high",
+                    discoverable: false,
+                });
+            }
+            detected.push({ name: "FastAPI", findings });
+        }
+        // Flask
+        else if (pyDepsLower.includes("flask")) {
+            detected.push({ name: "Flask", findings: [] });
+        }
+        // Generic Python
+        else {
+            detected.push({ name: "Python", findings: [] });
+        }
+        // pytest detection
+        if (pyDepsLower.includes("pytest")) {
+            findings.push({
+                category: "Testing",
+                description: "Uses pytest. Test files should be named `test_*.py` or `*_test.py`.",
+                confidence: "high",
+                discoverable: false,
+            });
+        }
+        // Virtual environment detection
+        const hasVenv = files.some((f) => f.startsWith(".venv/") || f.startsWith("venv/"));
+        if (hasVenv) {
+            findings.push({
+                category: "Python environment",
+                description: "Virtual environment detected. Activate with `source .venv/bin/activate` before running commands.",
+                confidence: "medium",
+                discoverable: false,
+            });
+        }
+    }
+    // --- Go ---
+    const hasGoMod = fs.existsSync(path.join(dir, "go.mod"));
+    if (hasGoMod) {
+        const findings = [];
+        try {
+            const goMod = fs.readFileSync(path.join(dir, "go.mod"), "utf-8");
+            const moduleMatch = goMod.match(/^module\s+(.+)$/m);
+            if (moduleMatch) {
+                findings.push({
+                    category: "Go module",
+                    description: `Module path: ${moduleMatch[1]}. Use this as the import prefix for all internal packages.`,
+                    confidence: "high",
+                    discoverable: false,
+                });
+            }
+            // Detect web frameworks
+            if (goMod.includes("github.com/gin-gonic/gin")) {
+                detected.push({ name: "Go + Gin", findings });
+            }
+            else if (goMod.includes("github.com/labstack/echo")) {
+                detected.push({ name: "Go + Echo", findings });
+            }
+            else if (goMod.includes("github.com/gofiber/fiber")) {
+                detected.push({ name: "Go + Fiber", findings });
+            }
+            else {
+                detected.push({ name: "Go", findings });
+            }
+        }
+        catch {
+            detected.push({ name: "Go", findings: [] });
+        }
+        // cmd/ vs pkg/ layout
+        const hasCmdDir = files.some((f) => f.startsWith("cmd/"));
+        const hasPkgDir = files.some((f) => f.startsWith("pkg/"));
+        const hasInternalDir = files.some((f) => f.startsWith("internal/"));
+        if (hasCmdDir) {
+            findings.push({
+                category: "Go layout",
+                description: `Standard Go project layout: ${hasCmdDir ? "cmd/" : ""}${hasPkgDir ? " pkg/" : ""}${hasInternalDir ? " internal/" : ""}. Entry points are in cmd/ subdirectories.`,
+                confidence: "high",
+                discoverable: false,
+            });
+        }
+        if (hasInternalDir) {
+            findings.push({
+                category: "Go visibility",
+                description: "internal/ packages cannot be imported by external modules. Keep private code here.",
+                rationale: "Go enforces this at the compiler level. Agents may try to import internal packages from external code.",
+                confidence: "high",
+                discoverable: false,
+            });
+        }
+    }
     return detected;
 }

package/dist/scanner/git.js

@@ -19,6 +19,8 @@ export async function analyzeGitHistory(dir) {
     }
     // 1. Reverted commits -- "don't do this" signals
     findings.push(...detectRevertedPatterns(dir, revertedPatterns));
+    // 1b. Anti-patterns from reverts and deleted approaches
+    findings.push(...detectAntiPatterns(dir));
     // 2. Recently active areas
     findings.push(...detectActiveAreas(dir, activeAreas));
     // 3. Co-change coupling -- invisible dependencies
@@ -84,6 +86,73 @@ function detectRevertedPatterns(dir, revertedPatterns) {
     }
     return findings;
 }
+/**
+ * Detect anti-patterns from reverted commits and deleted files.
+ * Reverts contain the original commit message — extract the approach that failed.
+ * Deleted files may indicate abandoned approaches.
+ */
+function detectAntiPatterns(dir) {
+    const findings = [];
+    // Extract detailed info from reverted commits
+    const revertLog = git(dir, 'log --grep="^Revert" --format="%s" --since="1 year ago" -20');
+    if (revertLog.trim()) {
+        const antiPatterns = [];
+        for (const line of revertLog.trim().split("\n").filter(Boolean)) {
+            const match = line.match(/^Revert "(.+)"/);
+            if (match) {
+                antiPatterns.push(match[1]);
+            }
+        }
+        if (antiPatterns.length > 0) {
+            for (const pattern of antiPatterns.slice(0, 5)) {
+                findings.push({
+                    category: "Anti-patterns",
+                    description: `Tried and reverted: "${pattern}". This approach was explicitly rejected.`,
+                    rationale: "This commit was made and then reverted. The approach failed for a reason. Do not re-attempt without understanding why it was rolled back.",
+                    confidence: "high",
+                    discoverable: false,
+                });
+            }
+        }
+    }
+    // Detect files deleted in bulk (abandoned features/approaches)
+    const deletedLog = git(dir, 'log --diff-filter=D --name-only --pretty=format:"COMMIT %s" --since="6 months ago" -50');
+    if (deletedLog.trim()) {
+        const deletionBatches = [];
+        let currentMessage = "";
+        let currentFiles = [];
+        for (const line of deletedLog.split("\n")) {
+            const commitMatch = line.match(/^"?COMMIT (.+)"?$/);
+            if (commitMatch) {
+                if (currentFiles.length >= 3) {
+                    deletionBatches.push({ message: currentMessage, files: currentFiles });
+                }
+                currentMessage = commitMatch[1];
+                currentFiles = [];
+            }
+            else if (line.trim() && !line.includes("node_modules")) {
+                currentFiles.push(line.trim());
+            }
+        }
+        if (currentFiles.length >= 3) {
+            deletionBatches.push({ message: currentMessage, files: currentFiles });
+        }
+        // Only report significant deletions (3+ files in one commit = abandoned feature)
+        for (const batch of deletionBatches.slice(0, 3)) {
+            if (batch.files.length >= 3) {
+                const fileList = batch.files.slice(0, 3).map((f) => path.basename(f)).join(", ");
+                findings.push({
+                    category: "Anti-patterns",
+                    description: `Abandoned: "${batch.message}" (${batch.files.length} files deleted including ${fileList})`,
+                    rationale: "A batch of files was deleted in a single commit, suggesting an abandoned approach or feature removal.",
+                    confidence: "medium",
+                    discoverable: false,
+                });
+            }
+        }
+    }
+    return findings;
+}
 /**
  * Find recently active areas -- where development is concentrated.
  */

package/dist/scanner/index.js

@@ -18,6 +18,8 @@ const IGNORE_PATTERNS = [
     "**/ios/**",
     "**/*.lock",
     "**/package-lock.json",
+    "**/.claude/worktrees/**",
+    "**/.claude/**",
 ];
 export async function scanProject(dir) {
     // Collect all files

package/dist/scanner/patterns.js

@@ -6,11 +6,13 @@ import path from "node:path";
  */
 export async function detectPatterns(dir, files, frameworks) {
     const findings = [];
-    // Only analyze source files
+    // Analyze source files (JS/TS + Python + Go)
     const sourceFiles = files.filter((f) => f.endsWith(".ts") ||
         f.endsWith(".tsx") ||
         f.endsWith(".js") ||
-        f.endsWith(".jsx"));
+        f.endsWith(".jsx") ||
+        f.endsWith(".py") ||
+        f.endsWith(".go"));
     // Sample files for pattern detection (don't read everything)
     const sampled = sampleFiles(sourceFiles, 50);
     const fileContents = new Map();
@@ -33,6 +35,10 @@ export async function detectPatterns(dir, files, frameworks) {
     findings.push(...detectErrorHandling(fileContents));
     // --- Export patterns ---
     findings.push(...detectExportPatterns(fileContents));
+    // --- Python conventions ---
+    findings.push(...detectPythonConventions(files, fileContents));
+    // --- Go conventions ---
+    findings.push(...detectGoConventions(files, fileContents));
     // Filter out discoverable findings
     return findings.filter((f) => !f.discoverable);
 }
@@ -170,6 +176,85 @@ function detectErrorHandling(contents) {
     }
     return findings;
 }
+function detectPythonConventions(files, contents) {
+    const findings = [];
+    const pyFiles = [...contents.entries()].filter(([f]) => f.endsWith(".py"));
+    if (pyFiles.length < 3)
+        return findings;
+    // Detect __init__.py barrel pattern
+    const initFiles = files.filter((f) => f.endsWith("__init__.py"));
+    const nonEmptyInits = initFiles.filter((f) => {
+        const content = contents.get(f);
+        return content && content.trim().length > 10;
+    });
+    if (nonEmptyInits.length >= 3) {
+        findings.push({
+            category: "Python conventions",
+            description: "Uses __init__.py as barrel exports. Import from the package, not from internal modules.",
+            evidence: `${nonEmptyInits.length} non-empty __init__.py files`,
+            confidence: "high",
+            discoverable: false,
+        });
+    }
+    // Detect type hint usage
+    let typeHintCount = 0;
+    let noHintCount = 0;
+    for (const [, content] of pyFiles) {
+        const funcDefs = content.match(/def\s+\w+\s*\([^)]*\)/g) || [];
+        for (const def of funcDefs) {
+            if (def.includes(":") && def.includes("->"))
+                typeHintCount++;
+            else
+                noHintCount++;
+        }
+    }
+    if (typeHintCount + noHintCount > 10 && typeHintCount > noHintCount * 2) {
+        findings.push({
+            category: "Python conventions",
+            description: "Project uses type hints extensively. Add type annotations to all new functions.",
+            evidence: `${typeHintCount} typed vs ${noHintCount} untyped function signatures`,
+            confidence: "high",
+            discoverable: false,
+        });
+    }
+    return findings;
+}
+function detectGoConventions(files, contents) {
+    const findings = [];
+    const goFiles = [...contents.entries()].filter(([f]) => f.endsWith(".go"));
+    if (goFiles.length < 3)
+        return findings;
+    // Detect error handling style
+    let errNilCount = 0;
+    let errWrapCount = 0;
+    for (const [, content] of goFiles) {
+        errNilCount += (content.match(/if\s+err\s*!=\s*nil/g) || []).length;
+        errWrapCount += (content.match(/fmt\.Errorf\(.*%w/g) || []).length;
+    }
+    if (errWrapCount > 5 && errWrapCount > errNilCount * 0.3) {
+        findings.push({
+            category: "Go conventions",
+            description: "Project wraps errors with fmt.Errorf(%w). Use error wrapping, not bare returns.",
+            evidence: `${errWrapCount} wrapped errors found`,
+            confidence: "high",
+            discoverable: false,
+        });
+    }
+    // Detect interface-first design
+    let interfaceCount = 0;
+    for (const [, content] of goFiles) {
+        interfaceCount += (content.match(/type\s+\w+\s+interface\s*\{/g) || []).length;
+    }
+    if (interfaceCount >= 5) {
+        findings.push({
+            category: "Go conventions",
+            description: `Project uses interface-first design (${interfaceCount} interfaces). Define interfaces at the consumer, not the producer.`,
+            confidence: "medium",
+            discoverable: false,
+        });
+    }
+    return findings;
+}
 function detectExportPatterns(contents) {
     const findings = [];
     let defaultExports = 0;

package/package.json

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