sourcebook 0.1.0

package/dist/scanner/patterns.js

@@ -0,0 +1,203 @@
+import fs from "node:fs";
+import path from "node:path";
+/**
+ * Detect code patterns and conventions that are non-obvious.
+ * This is the core intelligence layer -- finding things agents miss.
+ */
+export async function detectPatterns(dir, files, frameworks) {
+    const findings = [];
+    // Only analyze source files
+    const sourceFiles = files.filter((f) => f.endsWith(".ts") ||
+        f.endsWith(".tsx") ||
+        f.endsWith(".js") ||
+        f.endsWith(".jsx"));
+    // Sample files for pattern detection (don't read everything)
+    const sampled = sampleFiles(sourceFiles, 50);
+    const fileContents = new Map();
+    for (const file of sampled) {
+        try {
+            const content = fs.readFileSync(path.join(dir, file), "utf-8");
+            fileContents.set(file, content);
+        }
+        catch {
+            // skip unreadable files
+        }
+    }
+    // --- Barrel exports detection ---
+    findings.push(...detectBarrelExports(files, fileContents));
+    // --- Import style detection ---
+    findings.push(...detectImportPatterns(fileContents));
+    // --- Environment variable patterns ---
+    findings.push(...detectEnvPatterns(dir, files, fileContents));
+    // --- Error handling patterns ---
+    findings.push(...detectErrorHandling(fileContents));
+    // --- Export patterns ---
+    findings.push(...detectExportPatterns(fileContents));
+    // Filter out discoverable findings
+    return findings.filter((f) => !f.discoverable);
+}
+function sampleFiles(files, maxCount) {
+    if (files.length <= maxCount)
+        return files;
+    // Prioritize: entry points, configs, then random sample
+    const priority = files.filter((f) => f.includes("index.") ||
+        f.includes("config.") ||
+        f.includes("app.") ||
+        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);
+}
+function detectBarrelExports(files, contents) {
+    const indexFiles = files.filter((f) => path.basename(f).startsWith("index.") && !f.includes("node_modules"));
+    if (indexFiles.length < 3)
+        return [];
+    // Check if index files are barrel exports (re-exporting)
+    let barrelCount = 0;
+    for (const indexFile of indexFiles) {
+        const content = contents.get(indexFile);
+        if (content && /export\s+\{.*\}\s+from|export\s+\*\s+from/.test(content)) {
+            barrelCount++;
+        }
+    }
+    if (barrelCount >= 3) {
+        return [
+            {
+                category: "Import conventions",
+                description: "Project uses barrel exports (index.ts files that re-export). Import from the directory, not from deep paths.",
+                evidence: `${barrelCount} barrel export files found`,
+                confidence: "high",
+                discoverable: false,
+            },
+        ];
+    }
+    return [];
+}
+function detectImportPatterns(contents) {
+    const findings = [];
+    let aliasImports = 0;
+    let relativeImports = 0;
+    let absoluteImports = 0;
+    for (const [, content] of contents) {
+        const imports = content.match(/from\s+['"]([^'"]+)['"]/g) || [];
+        for (const imp of imports) {
+            const importPath = imp.match(/['"]([^'"]+)['"]/)?.[1] || "";
+            if (importPath.startsWith("@/") || importPath.startsWith("~/")) {
+                aliasImports++;
+            }
+            else if (importPath.startsWith(".")) {
+                relativeImports++;
+            }
+            else if (!importPath.startsWith("@") && !importPath.includes("/")) {
+                absoluteImports++;
+            }
+        }
+    }
+    const total = aliasImports + relativeImports;
+    if (total > 10 && aliasImports > relativeImports * 2) {
+        findings.push({
+            category: "Import conventions",
+            description: "Project strongly prefers path alias imports (@/ or ~/) over relative imports. Use aliases for cross-directory imports.",
+            evidence: `${aliasImports} alias imports vs ${relativeImports} relative imports in sampled files`,
+            confidence: "high",
+            discoverable: false,
+        });
+    }
+    return findings;
+}
+function detectEnvPatterns(dir, files, contents) {
+    const findings = [];
+    // Check for .env.example or .env.local
+    const hasEnvExample = files.includes(".env.example") || files.includes(".env.sample");
+    const hasEnvLocal = files.includes(".env.local");
+    const hasEnv = files.includes(".env");
+    if (hasEnvExample) {
+        findings.push({
+            category: "Environment",
+            description: "Environment variables are documented in .env.example. Copy it to .env.local before running the project.",
+            confidence: "high",
+            discoverable: false,
+        });
+    }
+    // Detect which env vars are used in code
+    const envVars = new Set();
+    for (const [, content] of contents) {
+        const matches = content.matchAll(/process\.env\.(\w+)|import\.meta\.env\.(\w+)/g);
+        for (const match of matches) {
+            envVars.add(match[1] || match[2]);
+        }
+    }
+    if (envVars.size > 0) {
+        // Check for NEXT_PUBLIC_ prefix pattern
+        const publicVars = [...envVars].filter((v) => v.startsWith("NEXT_PUBLIC_") || v.startsWith("VITE_") || v.startsWith("EXPO_PUBLIC_"));
+        const privateVars = [...envVars].filter((v) => !v.startsWith("NEXT_PUBLIC_") &&
+            !v.startsWith("VITE_") &&
+            !v.startsWith("EXPO_PUBLIC_") &&
+            !v.startsWith("NODE_ENV"));
+        if (publicVars.length > 0 && privateVars.length > 0) {
+            findings.push({
+                category: "Environment",
+                description: `${envVars.size} env vars detected. Public (browser-exposed): ${publicVars.slice(0, 3).join(", ")}${publicVars.length > 3 ? "..." : ""}. Private (server-only): ${privateVars.slice(0, 3).join(", ")}${privateVars.length > 3 ? "..." : ""}.`,
+                rationale: "Agents sometimes expose private env vars to the client by using the wrong prefix.",
+                confidence: "medium",
+                discoverable: false,
+            });
+        }
+    }
+    return findings;
+}
+function detectErrorHandling(contents) {
+    const findings = [];
+    let tryCatchCount = 0;
+    let errorBoundaryCount = 0;
+    let customErrorClasses = 0;
+    for (const [, content] of contents) {
+        tryCatchCount += (content.match(/try\s*\{/g) || []).length;
+        if (content.includes("ErrorBoundary"))
+            errorBoundaryCount++;
+        if (/class\s+\w+Error\s+extends\s+(Error|BaseError)/.test(content)) {
+            customErrorClasses++;
+        }
+    }
+    if (customErrorClasses >= 2) {
+        findings.push({
+            category: "Error handling",
+            description: "Project uses custom error classes. Throw specific error types instead of generic Error.",
+            confidence: "medium",
+            discoverable: false,
+        });
+    }
+    return findings;
+}
+function detectExportPatterns(contents) {
+    const findings = [];
+    let defaultExports = 0;
+    let namedExports = 0;
+    for (const [, content] of contents) {
+        defaultExports += (content.match(/export\s+default\s/g) || []).length;
+        namedExports += (content.match(/export\s+(const|function|class|type|interface)\s/g) || []).length;
+    }
+    const total = defaultExports + namedExports;
+    if (total > 10) {
+        if (namedExports > defaultExports * 3) {
+            findings.push({
+                category: "Export conventions",
+                description: "Project strongly prefers named exports over default exports. Use `export function` / `export const`, not `export default`.",
+                evidence: `${namedExports} named vs ${defaultExports} default exports in sampled files`,
+                confidence: "high",
+                discoverable: false,
+            });
+        }
+        else if (defaultExports > namedExports * 2) {
+            findings.push({
+                category: "Export conventions",
+                description: "Project prefers default exports. Use `export default` for main module exports.",
+                evidence: `${defaultExports} default vs ${namedExports} named exports in sampled files`,
+                confidence: "medium",
+                discoverable: false,
+            });
+        }
+    }
+    return findings;
+}

package/dist/scanner/structure.d.ts

@@ -0,0 +1,2 @@
+import type { StructureAnalysis } from "../types.js";
+export declare function detectProjectStructure(dir: string, files: string[]): StructureAnalysis;

package/dist/scanner/structure.js

@@ -0,0 +1,148 @@
+import path from "node:path";
+export function detectProjectStructure(dir, files) {
+    const findings = [];
+    const directories = {};
+    const entryPoints = [];
+    // Detect top-level directory purposes
+    const topDirs = new Set();
+    for (const file of files) {
+        const parts = file.split(path.sep);
+        if (parts.length > 1)
+            topDirs.add(parts[0]);
+    }
+    // Common directory purpose detection
+    const dirPurposes = {
+        src: "Source code",
+        lib: "Library code",
+        app: "Application routes / pages",
+        pages: "Page routes",
+        components: "UI components",
+        hooks: "Custom React hooks",
+        utils: "Utility functions",
+        helpers: "Helper functions",
+        services: "Service layer / API clients",
+        api: "API routes or endpoints",
+        server: "Server-side code",
+        public: "Static assets",
+        assets: "Static assets",
+        styles: "Stylesheets",
+        types: "TypeScript type definitions",
+        config: "Configuration files",
+        scripts: "Build / utility scripts",
+        test: "Tests",
+        tests: "Tests",
+        __tests__: "Tests",
+        e2e: "End-to-end tests",
+        docs: "Documentation",
+        migrations: "Database migrations",
+        supabase: "Supabase configuration and migrations",
+        prisma: "Prisma schema and migrations",
+        context: "Context / state management",
+        store: "State store",
+        features: "Feature modules",
+        modules: "Feature modules",
+        middleware: "Middleware",
+    };
+    for (const d of topDirs) {
+        if (dirPurposes[d]) {
+            directories[d] = dirPurposes[d];
+        }
+    }
+    // Detect layout pattern
+    const hasFeatureDirs = topDirs.has("features") || topDirs.has("modules");
+    const hasLayerDirs = topDirs.has("components") &&
+        (topDirs.has("services") || topDirs.has("utils"));
+    if (hasFeatureDirs) {
+        findings.push({
+            category: "Project structure",
+            description: "Feature-based architecture. Group new code by feature, not by type (don't put components in a global components/ folder).",
+            rationale: "Agents default to layer-based grouping. Feature-based projects break when you scatter feature code across type folders.",
+            confidence: "high",
+            discoverable: false,
+        });
+    }
+    // Detect src/ vs root layout
+    const hasSrc = topDirs.has("src");
+    if (hasSrc) {
+        // Check if there's code at both root and src/ (messy)
+        const rootCode = files.some((f) => !f.includes(path.sep) &&
+            (f.endsWith(".ts") || f.endsWith(".js")) &&
+            f !== "next.config.js" &&
+            f !== "next.config.ts" &&
+            f !== "vite.config.ts" &&
+            f !== "tailwind.config.ts" &&
+            f !== "postcss.config.js" &&
+            f !== "vitest.config.ts");
+        if (rootCode) {
+            findings.push({
+                category: "Project structure",
+                description: "Source code lives in src/ but some code files exist at the root. Keep application code in src/.",
+                confidence: "medium",
+                discoverable: false,
+            });
+        }
+    }
+    // Detect entry points
+    const commonEntries = [
+        "src/index.ts",
+        "src/index.tsx",
+        "src/main.ts",
+        "src/main.tsx",
+        "src/app.ts",
+        "src/app.tsx",
+        "index.ts",
+        "index.tsx",
+        "src/cli.ts",
+        "app/layout.tsx",
+        "app/page.tsx",
+        "pages/index.tsx",
+        "pages/_app.tsx",
+        "src/server.ts",
+        "server.ts",
+    ];
+    for (const entry of commonEntries) {
+        if (files.includes(entry))
+            entryPoints.push(entry);
+    }
+    // Detect monorepo
+    const hasWorkspaces = files.includes("pnpm-workspace.yaml");
+    const hasLernaJson = files.includes("lerna.json");
+    const hasPackagesDir = topDirs.has("packages") || topDirs.has("apps");
+    if (hasWorkspaces || hasLernaJson || hasPackagesDir) {
+        findings.push({
+            category: "Project structure",
+            description: "This is a monorepo. Changes may affect multiple packages. Check workspace dependencies before modifying shared code.",
+            confidence: "high",
+            discoverable: false,
+        });
+    }
+    // Detect test co-location vs separate test dir
+    const colocatedTests = files.some((f) => f.includes(".test.") || f.includes(".spec."));
+    const separateTestDir = topDirs.has("test") || topDirs.has("tests") || topDirs.has("__tests__");
+    if (colocatedTests && !separateTestDir) {
+        findings.push({
+            category: "Testing",
+            description: "Tests are co-located with source files (*.test.ts next to *.ts). Keep this pattern -- don't create a separate test/ directory.",
+            confidence: "high",
+            discoverable: false,
+        });
+    }
+    else if (separateTestDir && !colocatedTests) {
+        findings.push({
+            category: "Testing",
+            description: "Tests live in a separate test/ directory, mirroring src/ structure. New tests go there, not next to source files.",
+            confidence: "high",
+            discoverable: false,
+        });
+    }
+    return {
+        layout: hasFeatureDirs
+            ? "feature-based"
+            : hasLayerDirs
+                ? "layer-based"
+                : undefined,
+        entryPoints,
+        directories,
+        findings,
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,51 @@
+export interface Finding {
+    /** Category of the finding */
+    category: string;
+    /** Human-readable description of the finding */
+    description: string;
+    /** Why this matters -- context an agent needs */
+    rationale?: string;
+    /** File path or pattern that evidences this finding */
+    evidence?: string;
+    /** How confident we are this is a real convention, not coincidence */
+    confidence: "high" | "medium" | "low";
+    /** Is this discoverable by an agent reading the code? If yes, we filter it out */
+    discoverable: boolean;
+}
+export interface FrameworkDetection {
+    name: string;
+    version?: string;
+    findings: Finding[];
+}
+export interface StructureAnalysis {
+    /** Detected project layout pattern (e.g., "feature-based", "layer-based") */
+    layout?: string;
+    /** Entry points */
+    entryPoints: string[];
+    /** Key directories and their purposes */
+    directories: Record<string, string>;
+    /** Findings about structure that aren't obvious */
+    findings: Finding[];
+}
+export interface BuildCommands {
+    dev?: string;
+    build?: string;
+    test?: string;
+    lint?: string;
+    start?: string;
+    [key: string]: string | undefined;
+}
+export interface ProjectScan {
+    dir: string;
+    files: string[];
+    languages: string[];
+    frameworks: string[];
+    commands: BuildCommands;
+    structure: StructureAnalysis;
+    findings: Finding[];
+    /** Files ranked by PageRank importance in the import graph */
+    rankedFiles?: {
+        file: string;
+        score: number;
+    }[];
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/output.d.ts

@@ -0,0 +1 @@
+export declare function writeOutput(dir: string, filename: string, content: string): Promise<void>;

package/dist/utils/output.js

@@ -0,0 +1,10 @@
+import fs from "node:fs";
+import path from "node:path";
+export async function writeOutput(dir, filename, content) {
+    const filePath = path.join(dir, filename);
+    const parentDir = path.dirname(filePath);
+    if (!fs.existsSync(parentDir)) {
+        fs.mkdirSync(parentDir, { recursive: true });
+    }
+    fs.writeFileSync(filePath, content, "utf-8");
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "sourcebook",
+  "version": "0.1.0",
+  "description": "Extract the conventions, constraints, and architectural truths your AI coding agents keep missing.",
+  "type": "module",
+  "bin": {
+    "sourcebook": "./dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/cli.ts",
+    "start": "node dist/cli.js",
+    "test": "vitest"
+  },
+  "keywords": [
+    "ai",
+    "claude",
+    "cursor",
+    "copilot",
+    "context",
+    "developer-tools",
+    "cli",
+    "code-analysis",
+    "llm",
+    "agents"
+  ],
+  "author": "maroond",
+  "license": "MIT",
+  "homepage": "https://sourcebook.run",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/maroondlabs/sourcebook.git"
+  },
+  "bugs": {
+    "url": "https://github.com/maroondlabs/sourcebook/issues"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "commander": "^13.0.0",
+    "glob": "^11.0.0",
+    "chalk": "^5.4.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "tsx": "^4.19.0",
+    "vitest": "^3.0.0",
+    "@types/node": "^22.0.0"
+  }
+}