sourcebook 0.1.0

package/dist/scanner/git.js

@@ -0,0 +1,317 @@
+import { execSync } from "node:child_process";
+import path from "node:path";
+/**
+ * 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 async function analyzeGitHistory(dir) {
+    const findings = [];
+    const activeAreas = [];
+    const revertedPatterns = [];
+    const coChangeClusters = [];
+    // Check if this is a git repo
+    if (!isGitRepo(dir)) {
+        return { findings, activeAreas, revertedPatterns, coChangeClusters };
+    }
+    // 1. Reverted commits -- "don't do this" signals
+    findings.push(...detectRevertedPatterns(dir, revertedPatterns));
+    // 2. Recently active areas
+    findings.push(...detectActiveAreas(dir, activeAreas));
+    // 3. Co-change coupling -- invisible dependencies
+    findings.push(...detectCoChangeCoupling(dir, coChangeClusters));
+    // 4. Rapid re-edits -- code that was hard to get right
+    findings.push(...detectRapidReEdits(dir));
+    // 5. Commit message patterns -- development focus
+    findings.push(...detectCommitPatterns(dir));
+    return { findings, activeAreas, revertedPatterns, coChangeClusters };
+}
+function isGitRepo(dir) {
+    try {
+        execSync("git rev-parse --is-inside-work-tree", {
+            cwd: dir,
+            stdio: "pipe",
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function git(dir, args) {
+    try {
+        return execSync(`git ${args}`, {
+            cwd: dir,
+            stdio: "pipe",
+            maxBuffer: 10 * 1024 * 1024,
+        }).toString();
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * Find reverted commits -- these are explicit "we tried this and it didn't work" signals.
+ */
+function detectRevertedPatterns(dir, revertedPatterns) {
+    const findings = [];
+    const revertLog = git(dir, 'log --grep="^Revert" --oneline --since="1 year ago" -50');
+    if (!revertLog.trim())
+        return findings;
+    const reverts = revertLog.trim().split("\n").filter(Boolean);
+    if (reverts.length >= 2) {
+        // Extract what was reverted
+        const revertDescriptions = [];
+        for (const line of reverts.slice(0, 10)) {
+            const match = line.match(/^[a-f0-9]+ Revert "(.+)"/);
+            if (match) {
+                revertDescriptions.push(match[1]);
+                revertedPatterns.push(match[1]);
+            }
+        }
+        if (revertDescriptions.length > 0) {
+            findings.push({
+                category: "Git history",
+                description: `${reverts.length} reverted commits in the last year. Previously attempted and rolled back: ${revertDescriptions.slice(0, 3).join("; ")}${revertDescriptions.length > 3 ? "; ..." : ""}`,
+                rationale: "Reverted commits are explicit signals of approaches that were tried and failed. Agents should avoid re-attempting these patterns.",
+                confidence: "high",
+                discoverable: false,
+            });
+        }
+    }
+    return findings;
+}
+/**
+ * Find recently active areas -- where development is concentrated.
+ */
+function detectActiveAreas(dir, activeAreas) {
+    const findings = [];
+    // Get files changed in the last 30 days, count changes per directory
+    const recentChanges = git(dir, 'log --since="30 days ago" --name-only --pretty=format: --diff-filter=AMRC');
+    if (!recentChanges.trim())
+        return findings;
+    const dirCounts = new Map();
+    for (const file of recentChanges.trim().split("\n").filter(Boolean)) {
+        const dir = path.dirname(file);
+        const topDir = dir.split(path.sep)[0] || dir;
+        if (topDir === "." || topDir === "node_modules")
+            continue;
+        dirCounts.set(topDir, (dirCounts.get(topDir) || 0) + 1);
+    }
+    // Sort by activity
+    const sorted = [...dirCounts.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 5);
+    if (sorted.length >= 2) {
+        const topAreas = sorted
+            .filter(([, count]) => count >= 3)
+            .map(([dir, count]) => `${dir}/ (${count} changes)`);
+        if (topAreas.length > 0) {
+            activeAreas.push(...sorted.map(([dir]) => dir));
+            findings.push({
+                category: "Active development",
+                description: `Most active areas in the last 30 days: ${topAreas.join(", ")}. Expect ongoing changes here.`,
+                rationale: "Active areas may have in-progress refactoring. Check recent commits before making large changes.",
+                confidence: "medium",
+                discoverable: false,
+            });
+        }
+    }
+    return findings;
+}
+/**
+ * Detect co-change coupling -- files that are always committed together
+ * but have no import relationship. These are invisible dependencies.
+ */
+function detectCoChangeCoupling(dir, clusters) {
+    const findings = [];
+    // Get the last 200 commits with their changed files
+    const log = git(dir, 'log --name-only --pretty=format:"COMMIT" --since="6 months ago" -200');
+    if (!log.trim())
+        return findings;
+    // Parse commits into file groups
+    const commits = [];
+    let current = [];
+    for (const line of log.split("\n")) {
+        if (line.trim() === '"COMMIT"' || line.trim() === "COMMIT") {
+            if (current.length > 0)
+                commits.push(current);
+            current = [];
+        }
+        else if (line.trim() && !line.includes("node_modules")) {
+            current.push(line.trim());
+        }
+    }
+    if (current.length > 0)
+        commits.push(current);
+    // Build co-occurrence matrix (only for source files)
+    const sourceExts = new Set([
+        ".ts",
+        ".tsx",
+        ".js",
+        ".jsx",
+        ".py",
+        ".go",
+        ".rs",
+    ]);
+    const pairCounts = new Map();
+    const fileCounts = new Map();
+    for (const commit of commits) {
+        const sourceFiles = commit.filter((f) => sourceExts.has(path.extname(f).toLowerCase()));
+        // Skip mega-commits (likely merges or bulk changes)
+        if (sourceFiles.length > 20 || sourceFiles.length < 2)
+            continue;
+        for (const file of sourceFiles) {
+            fileCounts.set(file, (fileCounts.get(file) || 0) + 1);
+        }
+        // Count pairs
+        for (let i = 0; i < sourceFiles.length; i++) {
+            for (let j = i + 1; j < sourceFiles.length; j++) {
+                const pair = [sourceFiles[i], sourceFiles[j]].sort().join("|||");
+                pairCounts.set(pair, (pairCounts.get(pair) || 0) + 1);
+            }
+        }
+    }
+    // Find statistically significant co-changes
+    // (files committed together more than expected by chance)
+    const significantPairs = [];
+    for (const [pairKey, count] of pairCounts) {
+        if (count < 4)
+            continue; // Need at least 4 co-occurrences
+        const [fileA, fileB] = pairKey.split("|||");
+        const countA = fileCounts.get(fileA) || 0;
+        const countB = fileCounts.get(fileB) || 0;
+        // Skip files in the same directory (obvious coupling)
+        if (path.dirname(fileA) === path.dirname(fileB))
+            continue;
+        // Jaccard-like strength: co-changes / union of changes
+        const strength = count / (countA + countB - count);
+        if (strength > 0.3) {
+            significantPairs.push({
+                files: [fileA, fileB],
+                count,
+                strength,
+            });
+        }
+    }
+    // Sort by strength
+    significantPairs.sort((a, b) => b.strength - a.strength);
+    if (significantPairs.length > 0) {
+        const topPairs = significantPairs.slice(0, 5);
+        for (const pair of topPairs) {
+            clusters.push([pair.files[0], pair.files[1], pair.count]);
+        }
+        const pairDescriptions = topPairs
+            .slice(0, 3)
+            .map((p) => `${path.basename(p.files[0])} ↔ ${path.basename(p.files[1])} (${p.count} co-commits)`);
+        findings.push({
+            category: "Hidden dependencies",
+            description: `Files that change together across directories (invisible coupling): ${pairDescriptions.join("; ")}`,
+            rationale: "These files have no import relationship but are always modified together. Changing one without the other likely introduces bugs.",
+            confidence: "high",
+            discoverable: false,
+        });
+    }
+    return findings;
+}
+/**
+ * Detect files that were edited many times in quick succession --
+ * code that was hard to get right.
+ */
+function detectRapidReEdits(dir) {
+    const findings = [];
+    // Get files with high commit frequency in short windows
+    const log = git(dir, 'log --format="%H %aI" --name-only --since="3 months ago" -300');
+    if (!log.trim())
+        return findings;
+    // Track edits per file with timestamps
+    const fileEdits = new Map();
+    let currentDate = null;
+    for (const line of log.split("\n")) {
+        const commitMatch = line.match(/^[a-f0-9]{40} (\d{4}-\d{2}-\d{2})/);
+        if (commitMatch) {
+            currentDate = new Date(commitMatch[1]);
+        }
+        else if (line.trim() && currentDate && !line.includes("node_modules")) {
+            const file = line.trim();
+            if (!fileEdits.has(file))
+                fileEdits.set(file, []);
+            fileEdits.get(file).push(currentDate);
+        }
+    }
+    // Find files edited 5+ times within a 7-day window
+    const churnyFiles = [];
+    for (const [file, dates] of fileEdits) {
+        if (dates.length < 5)
+            continue;
+        // Sort dates
+        dates.sort((a, b) => a.getTime() - b.getTime());
+        // Sliding window: find any 7-day window with 5+ edits
+        for (let i = 0; i <= dates.length - 5; i++) {
+            const windowStart = dates[i];
+            const windowEnd = new Date(windowStart.getTime() + 7 * 24 * 60 * 60 * 1000);
+            const editsInWindow = dates.filter((d) => d >= windowStart && d <= windowEnd).length;
+            if (editsInWindow >= 5) {
+                churnyFiles.push({
+                    file,
+                    edits: editsInWindow,
+                    window: `${windowStart.toISOString().split("T")[0]}`,
+                });
+                break; // One detection per file is enough
+            }
+        }
+    }
+    // Sort by edit count
+    churnyFiles.sort((a, b) => b.edits - a.edits);
+    if (churnyFiles.length > 0) {
+        const topFiles = churnyFiles
+            .slice(0, 3)
+            .map((f) => `${f.file} (${f.edits} edits in one week)`);
+        findings.push({
+            category: "Fragile code",
+            description: `Files that required many rapid edits (hard to get right): ${topFiles.join("; ")}`,
+            rationale: "High churn in short windows indicates tricky logic. Take extra care when modifying these files.",
+            confidence: "medium",
+            discoverable: false,
+        });
+    }
+    return findings;
+}
+/**
+ * Detect commit message patterns -- reveals development focus and conventions.
+ */
+function detectCommitPatterns(dir) {
+    const findings = [];
+    const log = git(dir, 'log --oneline --since="6 months ago" -200');
+    if (!log.trim())
+        return findings;
+    const messages = log.trim().split("\n").filter(Boolean);
+    // Detect conventional commits usage
+    const conventionalPattern = /^[a-f0-9]+ (feat|fix|docs|refactor|test|chore|style|perf|ci|build)(\(.+?\))?[!:]?\s*:/;
+    const conventionalCount = messages.filter((m) => conventionalPattern.test(m)).length;
+    if (conventionalCount > messages.length * 0.5) {
+        // Extract scope patterns
+        const scopes = new Map();
+        for (const msg of messages) {
+            const match = msg.match(conventionalPattern);
+            if (match?.[2]) {
+                const scope = match[2].replace(/[()]/g, "");
+                scopes.set(scope, (scopes.get(scope) || 0) + 1);
+            }
+        }
+        const topScopes = [...scopes.entries()]
+            .sort((a, b) => b[1] - a[1])
+            .slice(0, 5)
+            .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.`,
+            confidence: "high",
+            discoverable: false,
+        });
+    }
+    return findings;
+}

package/dist/scanner/graph.d.ts

@@ -0,0 +1,17 @@
+import type { Finding } from "../types.js";
+interface GraphAnalysis {
+    /** Files ranked by importance (PageRank) */
+    rankedFiles: {
+        file: string;
+        score: number;
+    }[];
+    /** Findings about architecture from the graph */
+    findings: Finding[];
+}
+/**
+ * Build an import/dependency graph and run PageRank to identify
+ * the most structurally important files. Conventions found in
+ * high-PageRank files are likely canonical.
+ */
+export declare function analyzeImportGraph(dir: string, files: string[]): Promise<GraphAnalysis>;
+export {};

package/dist/scanner/graph.js

@@ -0,0 +1,251 @@
+import fs from "node:fs";
+import path from "node:path";
+/**
+ * Build an import/dependency graph and run PageRank to identify
+ * the most structurally important files. Conventions found in
+ * high-PageRank files are likely canonical.
+ */
+export async function analyzeImportGraph(dir, files) {
+    const findings = [];
+    // Only analyze source files
+    const sourceFiles = files.filter((f) => /\.(ts|tsx|js|jsx)$/.test(f));
+    if (sourceFiles.length < 5) {
+        return { rankedFiles: [], findings };
+    }
+    // Extract imports from each file
+    const edges = [];
+    const fileSet = new Set(sourceFiles);
+    for (const file of sourceFiles) {
+        const filePath = path.join(dir, file);
+        let content;
+        try {
+            content = fs.readFileSync(filePath, "utf-8");
+        }
+        catch {
+            continue;
+        }
+        const imports = extractImports(content);
+        for (const imp of imports) {
+            const resolved = resolveImport(imp, file, fileSet, dir);
+            if (resolved) {
+                edges.push({ from: file, to: resolved });
+            }
+        }
+    }
+    if (edges.length < 5) {
+        return { rankedFiles: [], findings };
+    }
+    // Run PageRank
+    const scores = pageRank(sourceFiles, edges, 20, 0.85);
+    // Sort by score descending
+    const rankedFiles = [...scores.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .map(([file, score]) => ({ file, score }));
+    // Find hub files (high fan-in -- many files import them)
+    const fanIn = new Map();
+    for (const edge of edges) {
+        fanIn.set(edge.to, (fanIn.get(edge.to) || 0) + 1);
+    }
+    const hubs = [...fanIn.entries()]
+        .filter(([, count]) => count >= 5)
+        .sort((a, b) => b[1] - a[1]);
+    if (hubs.length > 0) {
+        const hubList = hubs
+            .slice(0, 5)
+            .map(([file, count]) => `${file} (imported by ${count} files)`);
+        findings.push({
+            category: "Core modules",
+            description: `Hub files (most depended on): ${hubList.join("; ")}. Changes here have the widest blast radius.`,
+            rationale: "These are the most imported files in the project. Modifying them affects many consumers. Test thoroughly after changes.",
+            confidence: "high",
+            discoverable: false,
+        });
+    }
+    // Detect potential circular dependencies
+    const cycles = detectCycles(edges, sourceFiles);
+    if (cycles.length > 0) {
+        const cycleDescriptions = cycles
+            .slice(0, 3)
+            .map((c) => c.map((f) => path.basename(f)).join(" → "));
+        findings.push({
+            category: "Circular dependencies",
+            description: `Circular import chains detected: ${cycleDescriptions.join("; ")}. Avoid adding to these cycles.`,
+            rationale: "Circular dependencies cause subtle bugs (undefined imports, initialization order issues). Agents may unknowingly create new cycles.",
+            confidence: "high",
+            discoverable: false,
+        });
+    }
+    // Detect orphan files (no imports, not imported)
+    const connectedFiles = new Set();
+    for (const edge of edges) {
+        connectedFiles.add(edge.from);
+        connectedFiles.add(edge.to);
+    }
+    const orphans = sourceFiles.filter((f) => !connectedFiles.has(f) &&
+        !f.includes("test") &&
+        !f.includes("spec") &&
+        !f.includes(".config") &&
+        !f.endsWith(".d.ts"));
+    if (orphans.length >= 3 && orphans.length < sourceFiles.length * 0.3) {
+        findings.push({
+            category: "Dead code candidates",
+            description: `${orphans.length} source files have no import connections (potential dead code): ${orphans.slice(0, 5).join(", ")}${orphans.length > 5 ? ", ..." : ""}`,
+            confidence: "low",
+            discoverable: false,
+        });
+    }
+    return { rankedFiles, findings };
+}
+/**
+ * Extract import paths from a source file using regex.
+ * Not as robust as Tree-sitter but fast and sufficient for graph building.
+ */
+function extractImports(content) {
+    const imports = [];
+    // ES imports: import ... from "path"
+    const esImports = content.matchAll(/(?:import|export)\s+.*?\s+from\s+['"]([^'"]+)['"]/g);
+    for (const match of esImports) {
+        imports.push(match[1]);
+    }
+    // Dynamic imports: import("path")
+    const dynamicImports = content.matchAll(/import\s*\(\s*['"]([^'"]+)['"]\s*\)/g);
+    for (const match of dynamicImports) {
+        imports.push(match[1]);
+    }
+    // require: require("path")
+    const requires = content.matchAll(/require\s*\(\s*['"]([^'"]+)['"]\s*\)/g);
+    for (const match of requires) {
+        imports.push(match[1]);
+    }
+    // Only return relative imports (not packages)
+    return imports.filter((p) => p.startsWith(".") || p.startsWith("@/") || p.startsWith("~/"));
+}
+/**
+ * Resolve an import path to an actual file in the project.
+ */
+function resolveImport(importPath, fromFile, fileSet, dir) {
+    let resolved;
+    if (importPath.startsWith("@/") || importPath.startsWith("~/")) {
+        // Path alias -- resolve from root
+        resolved = importPath.replace(/^[@~]\//, "src/");
+    }
+    else {
+        // Relative import
+        resolved = path.normalize(path.join(path.dirname(fromFile), importPath));
+    }
+    // Try exact match, then with extensions, then as directory index
+    const candidates = [
+        resolved,
+        `${resolved}.ts`,
+        `${resolved}.tsx`,
+        `${resolved}.js`,
+        `${resolved}.jsx`,
+        `${resolved}/index.ts`,
+        `${resolved}/index.tsx`,
+        `${resolved}/index.js`,
+        `${resolved}/index.jsx`,
+    ];
+    for (const candidate of candidates) {
+        // Normalize to remove leading ./
+        const normalized = candidate.replace(/^\.\//, "");
+        if (fileSet.has(normalized))
+            return normalized;
+    }
+    return null;
+}
+/**
+ * Simple PageRank implementation.
+ * No external dependencies needed.
+ */
+function pageRank(nodes, edges, iterations, damping) {
+    const n = nodes.length;
+    const scores = new Map();
+    const outDegree = new Map();
+    // Initialize
+    for (const node of nodes) {
+        scores.set(node, 1 / n);
+        outDegree.set(node, 0);
+    }
+    // Count outgoing edges
+    for (const edge of edges) {
+        outDegree.set(edge.from, (outDegree.get(edge.from) || 0) + 1);
+    }
+    // Build adjacency (incoming edges)
+    const incoming = new Map();
+    for (const node of nodes) {
+        incoming.set(node, []);
+    }
+    for (const edge of edges) {
+        if (incoming.has(edge.to)) {
+            incoming.get(edge.to).push(edge.from);
+        }
+    }
+    // Iterate
+    for (let iter = 0; iter < iterations; iter++) {
+        const newScores = new Map();
+        for (const node of nodes) {
+            let sum = 0;
+            for (const inNode of incoming.get(node) || []) {
+                const out = outDegree.get(inNode) || 1;
+                sum += (scores.get(inNode) || 0) / out;
+            }
+            newScores.set(node, (1 - damping) / n + damping * sum);
+        }
+        // Update
+        for (const [node, score] of newScores) {
+            scores.set(node, score);
+        }
+    }
+    return scores;
+}
+/**
+ * Detect circular dependencies using DFS.
+ * Returns up to 5 short cycles.
+ */
+function detectCycles(edges, files) {
+    const adj = new Map();
+    for (const file of files)
+        adj.set(file, []);
+    for (const edge of edges) {
+        if (adj.has(edge.from)) {
+            adj.get(edge.from).push(edge.to);
+        }
+    }
+    const cycles = [];
+    const visited = new Set();
+    const stack = new Set();
+    const path = [];
+    function dfs(node) {
+        if (cycles.length >= 5)
+            return;
+        if (stack.has(node)) {
+            // Found a cycle
+            const cycleStart = path.indexOf(node);
+            if (cycleStart !== -1) {
+                const cycle = [...path.slice(cycleStart), node];
+                if (cycle.length <= 5) {
+                    // Only report short cycles
+                    cycles.push(cycle);
+                }
+            }
+            return;
+        }
+        if (visited.has(node))
+            return;
+        visited.add(node);
+        stack.add(node);
+        path.push(node);
+        for (const neighbor of adj.get(node) || []) {
+            dfs(neighbor);
+        }
+        stack.delete(node);
+        path.pop();
+    }
+    for (const file of files) {
+        if (!visited.has(file))
+            dfs(file);
+        if (cycles.length >= 5)
+            break;
+    }
+    return cycles;
+}

package/dist/scanner/index.d.ts

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

package/dist/scanner/index.js

@@ -0,0 +1,87 @@
+import path from "node:path";
+import { globSync } from "glob";
+import { detectFrameworks } from "./frameworks.js";
+import { detectBuildCommands } from "./build.js";
+import { detectPatterns } from "./patterns.js";
+import { detectProjectStructure } from "./structure.js";
+import { analyzeGitHistory } from "./git.js";
+import { analyzeImportGraph } from "./graph.js";
+const IGNORE_PATTERNS = [
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/.git/**",
+    "**/.next/**",
+    "**/coverage/**",
+    "**/.expo/**",
+    "**/android/**",
+    "**/ios/**",
+    "**/*.lock",
+    "**/package-lock.json",
+];
+export async function scanProject(dir) {
+    // Collect all files
+    const files = globSync("**/*", {
+        cwd: dir,
+        nodir: true,
+        ignore: IGNORE_PATTERNS,
+        dot: true,
+    });
+    // Detect languages from file extensions
+    const languages = detectLanguages(files);
+    // Detect frameworks from package.json, config files, etc.
+    const frameworks = await detectFrameworks(dir, files);
+    // Detect build/test/dev commands
+    const commands = await detectBuildCommands(dir);
+    // Detect project structure patterns
+    const structure = detectProjectStructure(dir, files);
+    // Detect code patterns and conventions (the non-obvious stuff)
+    const patterns = await detectPatterns(dir, files, frameworks.map((fw) => fw.name));
+    // Analyze git history for decision shadows and hidden dependencies
+    const gitAnalysis = await analyzeGitHistory(dir);
+    // Build import graph and run PageRank for structural importance
+    const graphAnalysis = await analyzeImportGraph(dir, files);
+    // Compile findings -- things an agent wouldn't figure out on its own
+    const findings = [
+        ...frameworks.map((fw) => fw.findings).flat(),
+        ...structure.findings,
+        ...patterns,
+        ...gitAnalysis.findings,
+        ...graphAnalysis.findings,
+    ];
+    return {
+        dir,
+        files,
+        languages,
+        frameworks: frameworks.map((f) => f.name),
+        commands,
+        structure,
+        findings,
+        rankedFiles: graphAnalysis.rankedFiles,
+    };
+}
+function detectLanguages(files) {
+    const extMap = {
+        ".ts": "TypeScript",
+        ".tsx": "TypeScript",
+        ".js": "JavaScript",
+        ".jsx": "JavaScript",
+        ".py": "Python",
+        ".go": "Go",
+        ".rs": "Rust",
+        ".rb": "Ruby",
+        ".java": "Java",
+        ".swift": "Swift",
+        ".kt": "Kotlin",
+        ".css": "CSS",
+        ".scss": "SCSS",
+        ".html": "HTML",
+    };
+    const found = new Set();
+    for (const file of files) {
+        const ext = path.extname(file).toLowerCase();
+        if (extMap[ext])
+            found.add(extMap[ext]);
+    }
+    return [...found];
+}

package/dist/scanner/patterns.d.ts

@@ -0,0 +1,6 @@
+import type { Finding } from "../types.js";
+/**
+ * Detect code patterns and conventions that are non-obvious.
+ * This is the core intelligence layer -- finding things agents miss.
+ */
+export declare function detectPatterns(dir: string, files: string[], frameworks: string[]): Promise<Finding[]>;