sourcebook 0.1.0

package/dist/generators/cursor.js

@@ -0,0 +1,123 @@
+/**
+ * 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).
+ */
+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 sections = [];
+    // MDC frontmatter
+    sections.push("---");
+    sections.push("description: Project conventions and constraints extracted by sourcebook");
+    sections.push("alwaysApply: true");
+    sections.push("---");
+    sections.push("");
+    // Commands
+    if (hasCommands(scan.commands)) {
+        sections.push("## Commands");
+        sections.push("");
+        if (scan.commands.dev)
+            sections.push(`- Dev: \`${scan.commands.dev}\``);
+        if (scan.commands.build)
+            sections.push(`- Build: \`${scan.commands.build}\``);
+        if (scan.commands.test)
+            sections.push(`- Test: \`${scan.commands.test}\``);
+        if (scan.commands.lint)
+            sections.push(`- Lint: \`${scan.commands.lint}\``);
+        sections.push("");
+    }
+    // Critical constraints at the top
+    if (critical.length > 0) {
+        sections.push("## Constraints");
+        sections.push("");
+        for (const finding of critical) {
+            sections.push(`- ${finding.description}`);
+        }
+        sections.push("");
+    }
+    // Stack (brief)
+    if (scan.frameworks.length > 0) {
+        sections.push("## Stack");
+        sections.push("");
+        sections.push(scan.frameworks.join(", "));
+        sections.push("");
+    }
+    // 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}\``);
+        }
+        sections.push("");
+    }
+    // Conventions
+    if (important.length > 0) {
+        sections.push("## Conventions");
+        sections.push("");
+        for (const finding of important) {
+            sections.push(`- ${finding.description}`);
+        }
+        sections.push("");
+    }
+    // Additional context
+    if (supplementary.length > 0) {
+        sections.push("## Additional Context");
+        sections.push("");
+        for (const finding of supplementary) {
+            sections.push(`- ${finding.description}`);
+        }
+        sections.push("");
+    }
+    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;
+}
+/**
+ * Also generate the legacy .cursorrules format for backwards compatibility.
+ * Same content as the .mdc but without the 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/scanner/build.d.ts

@@ -0,0 +1,2 @@
+import type { BuildCommands } from "../types.js";
+export declare function detectBuildCommands(dir: string): Promise<BuildCommands>;

package/dist/scanner/build.js

@@ -0,0 +1,56 @@
+import fs from "node:fs";
+import path from "node:path";
+export async function detectBuildCommands(dir) {
+    const commands = {};
+    // Check package.json scripts
+    const pkgPath = path.join(dir, "package.json");
+    if (fs.existsSync(pkgPath)) {
+        try {
+            const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+            const scripts = pkg.scripts || {};
+            commands.dev = scripts.dev;
+            commands.build = scripts.build;
+            commands.test = scripts.test;
+            commands.lint = scripts.lint;
+            commands.start = scripts.start;
+            // Detect non-standard but important scripts
+            for (const [name, script] of Object.entries(scripts)) {
+                if (typeof script === "string" &&
+                    !commands[name] &&
+                    (name.includes("migrate") ||
+                        name.includes("seed") ||
+                        name.includes("deploy") ||
+                        name.includes("typecheck") ||
+                        name.includes("generate"))) {
+                    commands[name] = script;
+                }
+            }
+        }
+        catch {
+            // malformed package.json
+        }
+    }
+    // Check for Makefile
+    const makefilePath = path.join(dir, "Makefile");
+    if (fs.existsSync(makefilePath) && !commands.build) {
+        commands.build = "make";
+    }
+    // Check for pyproject.toml
+    const pyprojectPath = path.join(dir, "pyproject.toml");
+    if (fs.existsSync(pyprojectPath)) {
+        try {
+            const content = fs.readFileSync(pyprojectPath, "utf-8");
+            if (content.includes("[tool.poetry.scripts]")) {
+                // Poetry project
+                if (!commands.dev)
+                    commands.dev = "poetry run dev";
+                if (!commands.test)
+                    commands.test = "poetry run pytest";
+            }
+        }
+        catch {
+            // can't read
+        }
+    }
+    return commands;
+}

package/dist/scanner/frameworks.d.ts

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

package/dist/scanner/frameworks.js

@@ -0,0 +1,230 @@
+import fs from "node:fs";
+import path from "node:path";
+export async function detectFrameworks(dir, files) {
+    const detected = [];
+    // Read all package.json files (root + workspaces/sub-packages)
+    const pkgFiles = files.filter((f) => f.endsWith("package.json") && !f.includes("node_modules"));
+    if (pkgFiles.length === 0)
+        pkgFiles.push("package.json");
+    const allDeps = {};
+    for (const pkgFile of pkgFiles) {
+        const pkgPath = path.join(dir, pkgFile);
+        if (fs.existsSync(pkgPath)) {
+            try {
+                const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+                Object.assign(allDeps, pkg.dependencies || {}, pkg.devDependencies || {});
+            }
+            catch {
+                // malformed package.json
+            }
+        }
+    }
+    // --- Next.js ---
+    if (allDeps["next"]) {
+        const findings = [];
+        const hasAppDir = files.some((f) => f.startsWith("app/") || f.startsWith("src/app/"));
+        const hasPagesDir = files.some((f) => f.startsWith("pages/") || f.startsWith("src/pages/"));
+        if (hasAppDir && hasPagesDir) {
+            findings.push({
+                category: "Next.js routing",
+                description: "Project uses BOTH App Router and Pages Router. New routes should go in the app/ directory unless there's a specific reason for pages/.",
+                rationale: "Mixed routing is a common migration state. Agents default to pages/ because training data has more examples of it.",
+                confidence: "high",
+                discoverable: false,
+            });
+        }
+        else if (hasAppDir) {
+            findings.push({
+                category: "Next.js routing",
+                description: "Project uses App Router (app/ directory). Use server components by default.",
+                confidence: "high",
+                discoverable: true,
+            });
+        }
+        // Check for next.config
+        const nextConfig = files.find((f) => /^next\.config\.(js|mjs|ts)$/.test(f));
+        if (nextConfig) {
+            try {
+                const configContent = fs.readFileSync(path.join(dir, nextConfig), "utf-8");
+                if (configContent.includes("output:") && configContent.includes("standalone")) {
+                    findings.push({
+                        category: "Next.js deployment",
+                        description: "Standalone output mode is enabled. Build produces a self-contained server in .next/standalone.",
+                        confidence: "high",
+                        discoverable: false,
+                    });
+                }
+                if (configContent.includes("images") && configContent.includes("remotePatterns")) {
+                    findings.push({
+                        category: "Next.js images",
+                        description: "Remote image patterns are configured. New image domains must be added to next.config before use.",
+                        rationale: "Agents will try to use next/image with arbitrary URLs and get 400 errors without this config.",
+                        confidence: "high",
+                        discoverable: false,
+                    });
+                }
+            }
+            catch {
+                // can't read config
+            }
+        }
+        detected.push({
+            name: "Next.js",
+            version: allDeps["next"],
+            findings: findings.filter((f) => !f.discoverable),
+        });
+    }
+    // --- Expo / React Native ---
+    if (allDeps["expo"]) {
+        const findings = [];
+        const hasExpoRouter = !!allDeps["expo-router"];
+        if (hasExpoRouter) {
+            findings.push({
+                category: "Expo routing",
+                description: "Uses Expo Router (file-based routing in app/ directory). Follows Next.js-like conventions.",
+                confidence: "high",
+                discoverable: true,
+            });
+        }
+        // Check for EAS config
+        if (files.includes("eas.json")) {
+            findings.push({
+                category: "Expo builds",
+                description: "EAS Build is configured. Use `eas build` for device builds, not `expo build`.",
+                rationale: "expo build is deprecated. Agents trained on older docs will suggest it.",
+                confidence: "high",
+                discoverable: false,
+            });
+        }
+        // Check app.json for scheme
+        const appJsonPath = path.join(dir, "app.json");
+        if (fs.existsSync(appJsonPath)) {
+            try {
+                const appJson = JSON.parse(fs.readFileSync(appJsonPath, "utf-8"));
+                if (appJson?.expo?.scheme) {
+                    findings.push({
+                        category: "Expo deep linking",
+                        description: `Deep link scheme is "${appJson.expo.scheme}://". Use this for universal links and navigation.`,
+                        confidence: "high",
+                        discoverable: false,
+                    });
+                }
+            }
+            catch {
+                // malformed app.json
+            }
+        }
+        detected.push({
+            name: "Expo",
+            version: allDeps["expo"],
+            findings: findings.filter((f) => !f.discoverable),
+        });
+    }
+    // --- React (standalone, not Next/Expo) ---
+    if (allDeps["react"] && !allDeps["next"] && !allDeps["expo"]) {
+        const findings = [];
+        const hasVite = !!allDeps["vite"];
+        if (hasVite) {
+            detected.push({ name: "Vite + React", version: allDeps["vite"], findings });
+        }
+        else {
+            detected.push({ name: "React", version: allDeps["react"], findings });
+        }
+    }
+    // --- Supabase ---
+    if (allDeps["@supabase/supabase-js"]) {
+        const findings = [];
+        // Check for RLS awareness
+        const hasSupabaseDir = files.some((f) => f.startsWith("supabase/"));
+        if (hasSupabaseDir) {
+            findings.push({
+                category: "Supabase",
+                description: "Local Supabase setup detected (supabase/ directory). Use `supabase db push` for migrations, not the dashboard.",
+                confidence: "high",
+                discoverable: false,
+            });
+        }
+        detected.push({
+            name: "Supabase",
+            version: allDeps["@supabase/supabase-js"],
+            findings,
+        });
+    }
+    // --- Tailwind CSS ---
+    if (allDeps["tailwindcss"]) {
+        const findings = [];
+        const hasTwConfig = files.some((f) => /^tailwind\.config\.(js|ts|mjs|cjs)$/.test(f));
+        if (hasTwConfig) {
+            try {
+                const configPath = files.find((f) => /^tailwind\.config\.(js|ts|mjs|cjs)$/.test(f));
+                const content = fs.readFileSync(path.join(dir, configPath), "utf-8");
+                if (content.includes("extend") && content.includes("colors")) {
+                    findings.push({
+                        category: "Tailwind",
+                        description: "Custom color tokens are defined in tailwind.config. Use these instead of arbitrary color values.",
+                        rationale: "Agents default to Tailwind's built-in palette. Using custom tokens keeps the design system consistent.",
+                        confidence: "medium",
+                        discoverable: false,
+                    });
+                }
+            }
+            catch {
+                // can't read config
+            }
+        }
+        detected.push({
+            name: "Tailwind CSS",
+            version: allDeps["tailwindcss"],
+            findings,
+        });
+    }
+    // --- Express ---
+    if (allDeps["express"]) {
+        detected.push({
+            name: "Express",
+            version: allDeps["express"],
+            findings: [],
+        });
+    }
+    // --- TypeScript ---
+    if (allDeps["typescript"]) {
+        const findings = [];
+        const tsconfigPath = path.join(dir, "tsconfig.json");
+        if (fs.existsSync(tsconfigPath)) {
+            try {
+                const tsconfig = JSON.parse(fs.readFileSync(tsconfigPath, "utf-8"));
+                const strict = tsconfig?.compilerOptions?.strict;
+                if (strict === false) {
+                    findings.push({
+                        category: "TypeScript",
+                        description: "Strict mode is OFF. Don't add strict type annotations that would break existing patterns.",
+                        confidence: "high",
+                        discoverable: false,
+                    });
+                }
+                const paths = tsconfig?.compilerOptions?.paths;
+                if (paths) {
+                    const aliases = Object.keys(paths)
+                        .map((k) => k.replace("/*", ""))
+                        .join(", ");
+                    findings.push({
+                        category: "TypeScript imports",
+                        description: `Path aliases configured: ${aliases}. Use these instead of relative imports.`,
+                        rationale: "Agents default to relative imports. Path aliases keep imports clean.",
+                        confidence: "high",
+                        discoverable: false,
+                    });
+                }
+            }
+            catch {
+                // malformed tsconfig
+            }
+        }
+        detected.push({
+            name: "TypeScript",
+            version: allDeps["typescript"],
+            findings,
+        });
+    }
+    return detected;
+}

package/dist/scanner/git.d.ts

@@ -0,0 +1,17 @@
+import type { Finding } from "../types.js";
+interface GitAnalysis {
+    findings: Finding[];
+    activeAreas: string[];
+    revertedPatterns: string[];
+    coChangeClusters: [string, string, number][];
+}
+/**
+ * Mine git history for non-obvious context:
+ * - Reverted commits (literal "don't do this" signals)
+ * - Co-change coupling (invisible dependencies)
+ * - Recently active areas
+ * - Commit message patterns (module structure)
+ * - Rapid re-edits (code that was hard to get right)
+ */
+export declare function analyzeGitHistory(dir: string): Promise<GitAnalysis>;
+export {};