bilt-toolkit 1.0.0

package/dist/core/scan/gitignore.js

@@ -0,0 +1,217 @@
+// ─── Gitignore Analysis ──────────────────────────────────────────────────────
+//
+// Checks whether sensitive .env files are properly covered by .gitignore.
+// Uses simple-git for accurate `git check-ignore` verification when
+// running inside a git repository.
+// ─────────────────────────────────────────────────────────────────────────────
+import { simpleGit } from "simple-git";
+import path from "node:path";
+import fs from "node:fs/promises";
+import fsSync from "node:fs";
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+let findingCounter = 0;
+function nextId(prefix) {
+    return `${prefix}-${Date.now()}-${++findingCounter}`;
+}
+/**
+ * Basename extraction that handles both `/` and `\` separators.
+ */
+function basename(filePath) {
+    return filePath.split(/[\\/]/).pop() ?? filePath;
+}
+/**
+ * File names that are intentionally tracked (they contain no real secrets).
+ */
+const TEMPLATE_NAMES = new Set([
+    ".env.example",
+    ".env.template",
+    ".env.sample",
+]);
+/**
+ * Determine if a file is a template / example that SHOULD be tracked.
+ */
+function isTemplateFile(filePath) {
+    return TEMPLATE_NAMES.has(basename(filePath).toLowerCase());
+}
+// ─── Public API ──────────────────────────────────────────────────────────────
+/**
+ * Parse a `.gitignore` file's content into a list of non-empty,
+ * non-comment patterns.
+ */
+export function parseGitignore(content) {
+    return content
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0 && !line.startsWith("#"));
+}
+/**
+ * Check whether the given env files are properly ignored by git.
+ *
+ * Strategy:
+ * 1. For each env file, skip if it's a template (should be tracked).
+ * 2. Fall back to simple pattern matching against gitignore content.
+ */
+export function checkEnvFilesIgnored(projectDir, envFiles) {
+    let gitignoreContent = "";
+    try {
+        gitignoreContent = fsSync.readFileSync(path.join(projectDir, ".gitignore"), "utf-8");
+    }
+    catch {
+        // Missing gitignore
+    }
+    const findings = [];
+    const patterns = parseGitignore(gitignoreContent);
+    for (const envFile of envFiles) {
+        // Skip template files — they should be tracked
+        if (isTemplateFile(envFile))
+            continue;
+        const name = basename(envFile);
+        const relativePath = path.relative(projectDir, envFile).replace(/\\/g, "/");
+        // Check if any gitignore pattern covers this file
+        const isCovered = patternCoversFile(patterns, name, relativePath);
+        if (!isCovered) {
+            findings.push({
+                id: nextId("gitignore-missing"),
+                severity: "critical",
+                category: "gitignore-missing",
+                message: `${name} is not ignored by git — secrets may be committed`,
+                file: envFile,
+                suggestion: `Add "${name}" or ".env*" to your .gitignore file`,
+            });
+        }
+    }
+    return findings;
+}
+/**
+ * Enhanced check using `git check-ignore` for accurate results.
+ * Falls back to pattern matching if git is not available.
+ */
+export async function checkEnvFilesIgnoredWithGit(projectDir, envFiles) {
+    const findings = [];
+    // Try to use git check-ignore for accuracy
+    let useGit = false;
+    const git = simpleGit(projectDir);
+    git.env({
+        ...process.env,
+        GIT_DIR: undefined,
+        GIT_WORK_TREE: undefined,
+    });
+    try {
+        const isRepo = await git.checkIsRepo();
+        if (isRepo)
+            useGit = true;
+    }
+    catch {
+        // Git not available or not a repo — fall back to pattern matching
+    }
+    let gitignoreContent = "";
+    try {
+        gitignoreContent = await fs.readFile(path.join(projectDir, ".gitignore"), "utf-8");
+    }
+    catch {
+        // Missing gitignore
+    }
+    for (const envFile of envFiles) {
+        if (isTemplateFile(envFile))
+            continue;
+        const name = basename(envFile);
+        let isIgnored = false;
+        if (useGit) {
+            try {
+                await git.raw(["check-ignore", "-q", envFile]);
+                // Exit code 0 means the file IS ignored
+                isIgnored = true;
+            }
+            catch {
+                // Exit code 1 means the file is NOT ignored
+                // (simple-git throws on non-zero exit)
+                isIgnored = false;
+            }
+        }
+        else {
+            // Fall back to pattern analysis
+            const patterns = parseGitignore(gitignoreContent);
+            const relativePath = path
+                .relative(projectDir, envFile)
+                .replace(/\\/g, "/");
+            isIgnored = patternCoversFile(patterns, name, relativePath);
+        }
+        if (!isIgnored) {
+            findings.push({
+                id: nextId("gitignore-missing"),
+                severity: "critical",
+                category: "gitignore-missing",
+                message: `${name} is not ignored by git — secrets may be committed`,
+                file: envFile,
+                suggestion: `Add "${name}" or ".env*" to your .gitignore file`,
+            });
+        }
+    }
+    return findings;
+}
+// ─── Pattern Matching (fallback) ─────────────────────────────────────────────
+/**
+ * Check whether a given file is covered by any of the parsed gitignore
+ * patterns.  This is a simplified matcher — for accurate results use
+ * `git check-ignore` via `checkEnvFilesIgnoredWithGit`.
+ *
+ * Supports:
+ *   • Exact name match (`.env`)
+ *   • Glob star patterns (`.env.*`, `.env*`)
+ *   • Path-relative patterns (`config/.env`)
+ *   • Negation patterns (`!.env.example`) — will un-ignore a file
+ */
+function patternCoversFile(patterns, fileName, relativePath) {
+    let covered = false;
+    for (const raw of patterns) {
+        const negated = raw.startsWith("!");
+        const pattern = negated ? raw.slice(1) : raw;
+        const matches = patternMatchesSingle(pattern, fileName, relativePath);
+        if (matches) {
+            covered = !negated;
+        }
+    }
+    return covered;
+}
+/**
+ * Simple glob-like matching for a single gitignore pattern.
+ */
+function patternMatchesSingle(pattern, fileName, relativePath) {
+    // Trim trailing slashes (directory markers) for file matching
+    const p = pattern.replace(/\/$/, "");
+    // Exact filename match
+    if (p === fileName)
+        return true;
+    // Path match
+    if (p === relativePath)
+        return true;
+    // Pattern ends with `*` — prefix match
+    if (p.endsWith("*")) {
+        const prefix = p.slice(0, -1);
+        if (fileName.startsWith(prefix))
+            return true;
+        if (relativePath.startsWith(prefix))
+            return true;
+    }
+    // Pattern contains `.*` — e.g. `.env.*` matches `.env.local`
+    if (p.includes(".*")) {
+        const re = new RegExp("^" +
+            p.replace(/\./g, "\\.").replace(/\*/g, "[^/]*").replace(/\?/g, ".") +
+            "$");
+        if (re.test(fileName) || re.test(relativePath))
+            return true;
+    }
+    // Pattern with `**` — recursive match
+    if (p.includes("**")) {
+        const re = new RegExp("^" +
+            p
+                .replace(/\./g, "\\.")
+                .replace(/\*\*/g, ".*")
+                .replace(/(?<!\.)(\*)/g, "[^/]*") +
+            "$");
+        if (re.test(relativePath))
+            return true;
+    }
+    return false;
+}
+//# sourceMappingURL=gitignore.js.map

package/dist/core/scan/gitignore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gitignore.js","sourceRoot":"","sources":["../../../src/core/scan/gitignore.ts"],"names":[],"mappings":"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"}

package/dist/core/scan/secrets.d.ts

@@ -0,0 +1,27 @@
+import type { SecretRule, ScanFinding, BiltConfig } from "../../types/index.js";
+/**
+ * Scan file content for secrets using the specified rules.
+ *
+ * Before reporting a match, the function filters out:
+ *   1. Placeholder / dummy-value heuristics
+ *   2. Entropy threshold (for the `generic-high-entropy` rule the
+ *      captured group is used; for others the full match is checked)
+ *
+ * Each surviving match is turned into a `ScanFinding` with:
+ *   • Line number within the file
+ *   • Masked preview of the matched value
+ *   • Provider info (if determinable)
+ */
+export declare function scanFileForSecrets(content: string, filePath: string, rulesOrConfig?: SecretRule[] | BiltConfig, entropyThreshold?: number): ScanFinding[];
+/**
+ * Scan the recent git history for secrets that may have been committed.
+ *
+ * Uses `simple-git` to iterate over the last `depth` commits (default
+ * 10), extract the diff for each, and run the same secret-scanning
+ * logic used for file content.
+ *
+ * Findings include the commit SHA in their `file` field so the user
+ * knows which commit to rewrite / clean.
+ */
+export declare function scanGitHistory(repoPath: string, rules: SecretRule[], entropyThreshold: number, depth?: number): Promise<ScanFinding[]>;
+//# sourceMappingURL=secrets.d.ts.map

package/dist/core/scan/secrets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secrets.d.ts","sourceRoot":"","sources":["../../../src/core/scan/secrets.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAwEhF;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,aAAa,GAAE,UAAU,EAAE,GAAG,UAAyB,EACvD,gBAAgB,GAAE,MAAY,GAC7B,WAAW,EAAE,CAkGf;AAED;;;;;;;;;GASG;AACH,wBAAsB,cAAc,CAClC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,UAAU,EAAE,EACnB,gBAAgB,EAAE,MAAM,EACxB,KAAK,SAAK,GACT,OAAO,CAAC,WAAW,EAAE,CAAC,CAqExB"}

package/dist/core/scan/secrets.js

@@ -0,0 +1,247 @@
+// ─── Secret Scanner ──────────────────────────────────────────────────────────
+//
+// Scans file content (and optionally git history) for leaked secrets by
+// running every SecretRule regex and then cross-checking with entropy
+// analysis.  Produces ScanFinding objects with masked previews, line
+// numbers, and provider information.
+// ─────────────────────────────────────────────────────────────────────────────
+import { simpleGit } from "simple-git";
+import { isHighEntropy } from "../rules/entropy.js";
+import { detectProvider } from "../rules/providers.js";
+import { SECRET_RULES } from "../rules/secret-rules.js";
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+let findingCounter = 0;
+function nextId(prefix) {
+    return `${prefix}-${Date.now()}-${++findingCounter}`;
+}
+/**
+ * Common placeholder / dummy values that should never be flagged as
+ * actual secrets.
+ */
+const PLACEHOLDER_PATTERNS = [
+    /^<.*>$/, // <YOUR_KEY>, <api-key>
+    /^your[_-]?/i, // your-api-key-here, your_key
+    /^xxx+$/i, // xxx, xxxx, etc.
+    /^change[_-]?me$/i, // CHANGE_ME, changeme
+    /^replace[_-]?me$/i, // REPLACE_ME, replaceme
+    /^todo$/i, // TODO
+    /^fixme$/i, // FIXME
+    /^placeholder$/i, // placeholder
+    /^example$/i, // example
+    /^test$/i, // test
+    /^none$/i, // none
+    /^null$/i, // null
+    /^undefined$/i, // undefined
+    /^insert[_-]?/i, // insert-your-key, insert_key_here
+    /^dummy/i, // dummy, dummy-key
+    /^\*+$/, // ***, ******, etc.
+    /^\.{3,}$/, // ..., ......
+    /^_+$/, // ___, ______
+    /^0+$/, // 000, 0000000
+];
+/**
+ * Returns true if the value looks like a placeholder rather than a
+ * real secret.
+ */
+function isPlaceholder(value) {
+    const trimmed = value.trim();
+    if (trimmed.length === 0)
+        return true;
+    return PLACEHOLDER_PATTERNS.some((re) => re.test(trimmed));
+}
+/**
+ * Mask a secret value for safe display: show first 4 and last 4 chars
+ * with stars in between.  Very short values are fully masked.
+ */
+function maskValue(value) {
+    if (value.length <= 8)
+        return "*".repeat(value.length);
+    const start = value.slice(0, 4);
+    const end = value.slice(-4);
+    return `${start}${"*".repeat(Math.min(value.length - 8, 20))}${end}`;
+}
+/**
+ * Get the 1-indexed line number within `content` for a given character
+ * offset.
+ */
+function lineNumberAt(content, offset) {
+    let line = 1;
+    for (let i = 0; i < offset && i < content.length; i++) {
+        if (content[i] === "\n")
+            line++;
+    }
+    return line;
+}
+// ─── Public API ──────────────────────────────────────────────────────────────
+/**
+ * Scan file content for secrets using the specified rules.
+ *
+ * Before reporting a match, the function filters out:
+ *   1. Placeholder / dummy-value heuristics
+ *   2. Entropy threshold (for the `generic-high-entropy` rule the
+ *      captured group is used; for others the full match is checked)
+ *
+ * Each surviving match is turned into a `ScanFinding` with:
+ *   • Line number within the file
+ *   • Masked preview of the matched value
+ *   • Provider info (if determinable)
+ */
+export function scanFileForSecrets(content, filePath, rulesOrConfig = SECRET_RULES, entropyThreshold = 4.5) {
+    let rules;
+    let threshold = entropyThreshold;
+    if (Array.isArray(rulesOrConfig)) {
+        rules = rulesOrConfig;
+    }
+    else if (rulesOrConfig && typeof rulesOrConfig === "object") {
+        // It's a BiltConfig
+        const config = rulesOrConfig;
+        rules = [...SECRET_RULES, ...(config.customRules || [])];
+        threshold = config.entropyThreshold ?? entropyThreshold;
+    }
+    else {
+        rules = SECRET_RULES;
+    }
+    const findings = [];
+    // Split content into lines for ignore-comment checks
+    const fileLines = content.split("\n");
+    // Track matches we've already reported to avoid duplicates when
+    // multiple rules match the same span.
+    const seen = new Set();
+    for (const rule of rules) {
+        // Reset the regex's lastIndex (rules use /g flag)
+        rule.pattern.lastIndex = 0;
+        let match;
+        while ((match = rule.pattern.exec(content)) !== null) {
+            // For the generic high-entropy rule, prefer the captured group
+            const matchedValue = match[1] ?? match[0];
+            // De-duplicate by position + rule
+            const dedupeKey = `${rule.id}:${match.index}`;
+            if (seen.has(dedupeKey))
+                continue;
+            seen.add(dedupeKey);
+            // Skip placeholders
+            if (isPlaceholder(matchedValue))
+                continue;
+            // For the generic high-entropy rule, require high entropy
+            if (rule.id === "generic-high-entropy") {
+                if (!isHighEntropy(matchedValue, threshold))
+                    continue;
+            }
+            // For the AWS secret key rule, require high entropy to avoid
+            // false positives from 40-char strings in code.
+            if (rule.id === "aws-secret-key") {
+                if (!isHighEntropy(matchedValue, threshold))
+                    continue;
+            }
+            const line = lineNumberAt(content, match.index);
+            // Check for known public assignments (e.g. ANON_KEY, PUBLISHABLE_KEY)
+            const matchedLine = fileLines[line - 1];
+            if (matchedLine) {
+                const isPublicAssignment = /^[a-z0-9_]*(anon_key|publishable_key|public_key|app_id)[a-z0-9_]*\s*=/i.test(matchedLine.trim());
+                if (isPublicAssignment)
+                    continue;
+            }
+            // Check for inline ignore comments (e.g. gitleaks:allow or bilt:allow)
+            const previousLine = line > 1 ? fileLines[line - 2] : undefined;
+            const isAllowed = (matchedLine &&
+                (matchedLine.includes("gitleaks:allow") ||
+                    matchedLine.includes("bilt:allow"))) ||
+                (previousLine &&
+                    (previousLine.includes("gitleaks:allow") ||
+                        previousLine.includes("bilt:allow")));
+            if (isAllowed)
+                continue;
+            const provider = detectProvider(matchedValue, rule.id) ?? undefined;
+            findings.push({
+                id: nextId("secret"),
+                severity: rule.severity,
+                category: "secret-detected",
+                message: `${rule.name} detected` +
+                    (provider ? ` (${provider.displayName})` : ""),
+                file: filePath,
+                line,
+                suggestion: provider
+                    ? `Rotate this key at ${provider.rotationUrl} and move the value to a .env file`
+                    : "Move this value to a .env file and add the file to .gitignore",
+                provider,
+                ruleId: rule.id,
+                preview: maskValue(matchedValue),
+            });
+        }
+    }
+    return findings;
+}
+/**
+ * Scan the recent git history for secrets that may have been committed.
+ *
+ * Uses `simple-git` to iterate over the last `depth` commits (default
+ * 10), extract the diff for each, and run the same secret-scanning
+ * logic used for file content.
+ *
+ * Findings include the commit SHA in their `file` field so the user
+ * knows which commit to rewrite / clean.
+ */
+export async function scanGitHistory(repoPath, rules, entropyThreshold, depth = 10) {
+    const findings = [];
+    const git = simpleGit(repoPath);
+    git.env({
+        ...process.env,
+        GIT_DIR: undefined,
+        GIT_WORK_TREE: undefined,
+    });
+    // Verify we're in a git repo
+    try {
+        const isRepo = await git.checkIsRepo();
+        if (!isRepo)
+            return findings;
+    }
+    catch {
+        return findings;
+    }
+    // Get the last N commits
+    let log;
+    try {
+        log = await git.log({ maxCount: depth });
+    }
+    catch {
+        // Repository might have no commits yet
+        return findings;
+    }
+    for (const commit of log.all) {
+        let diff;
+        try {
+            // Get the full diff for this commit
+            diff = await git.diff([`${commit.hash}~1`, commit.hash]);
+        }
+        catch {
+            // First commit has no parent — diff against empty tree
+            try {
+                diff = await git.diff([
+                    "4b825dc642cb6eb9a060e54bf899d69f82ef7b21",
+                    commit.hash,
+                ]);
+            }
+            catch {
+                continue;
+            }
+        }
+        // Extract only the added lines (lines starting with `+` in the diff,
+        // excluding the `+++` file header).
+        const addedLines = diff
+            .split("\n")
+            .filter((line) => line.startsWith("+") && !line.startsWith("+++"))
+            .map((line) => line.slice(1))
+            .join("\n");
+        if (addedLines.length === 0)
+            continue;
+        // Scan the added content
+        const commitFindings = scanFileForSecrets(addedLines, `git:${commit.hash.slice(0, 8)}`, rules, entropyThreshold);
+        // Annotate findings with commit info
+        for (const finding of commitFindings) {
+            finding.message += ` (found in commit ${commit.hash.slice(0, 8)}: ${commit.message.slice(0, 60)})`;
+            findings.push(finding);
+        }
+    }
+    return findings;
+}
+//# sourceMappingURL=secrets.js.map

package/dist/core/scan/secrets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"secrets.js","sourceRoot":"","sources":["../../../src/core/scan/secrets.ts"],"names":[],"mappings":"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"}

package/dist/core/score/health.d.ts

@@ -0,0 +1,29 @@
+import type { ScanFinding } from "../../types/index.js";
+export interface CategoryBreakdown {
+    category: string;
+    points: number;
+    count: number;
+}
+export interface HealthReport {
+    /** Numeric score from 0 (worst) to 100 (perfect). */
+    score: number;
+    /** Letter grade (A+ through F). */
+    grade: string;
+    /** Per-category breakdown showing point deductions and finding counts. */
+    breakdown: CategoryBreakdown[];
+}
+/**
+ * Calculate a health score from an array of `ScanFinding`s.
+ *
+ * Scoring:
+ *   • Start at **100**.
+ *   • Each `critical` finding: **−15 points**.
+ *   • Each `warning` finding: **−5 points**.
+ *   • Each `info` finding: **−1 point**.
+ *   • Floor at **0** (score never goes negative).
+ *
+ * The `breakdown` array lists every finding category that contributed
+ * to the score loss, sorted by point deduction (largest first).
+ */
+export declare function calculateHealthScore(findings: ScanFinding[]): HealthReport;
+//# sourceMappingURL=health.d.ts.map

package/dist/core/score/health.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.d.ts","sourceRoot":"","sources":["../../../src/core/score/health.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACV,WAAW,EAGZ,MAAM,sBAAsB,CAAC;AA6B9B,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,YAAY;IAC3B,qDAAqD;IACrD,KAAK,EAAE,MAAM,CAAC;IACd,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,0EAA0E;IAC1E,SAAS,EAAE,iBAAiB,EAAE,CAAC;CAChC;AAID;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,WAAW,EAAE,GAAG,YAAY,CAwC1E"}

package/dist/core/score/health.js

@@ -0,0 +1,73 @@
+// ─── Health Score Calculator ─────────────────────────────────────────────────
+//
+// Computes a 0-100 health score from scan findings, with a letter-grade
+// and per-category breakdown.  Pure function — no side effects.
+// ─────────────────────────────────────────────────────────────────────────────
+// ─── Point Deductions ────────────────────────────────────────────────────────
+const SEVERITY_COST = {
+    critical: 15,
+    warning: 5,
+    info: 1,
+};
+// ─── Grade Thresholds ────────────────────────────────────────────────────────
+// Ordered from highest to lowest so the first match wins.
+const GRADE_THRESHOLDS = [
+    { min: 97, grade: "A+" },
+    { min: 93, grade: "A" },
+    { min: 90, grade: "A-" },
+    { min: 87, grade: "B+" },
+    { min: 83, grade: "B" },
+    { min: 80, grade: "B-" },
+    { min: 77, grade: "C+" },
+    { min: 73, grade: "C" },
+    { min: 70, grade: "C-" },
+    { min: 60, grade: "D" },
+    { min: 0, grade: "F" },
+];
+// ─── Public API ──────────────────────────────────────────────────────────────
+/**
+ * Calculate a health score from an array of `ScanFinding`s.
+ *
+ * Scoring:
+ *   • Start at **100**.
+ *   • Each `critical` finding: **−15 points**.
+ *   • Each `warning` finding: **−5 points**.
+ *   • Each `info` finding: **−1 point**.
+ *   • Floor at **0** (score never goes negative).
+ *
+ * The `breakdown` array lists every finding category that contributed
+ * to the score loss, sorted by point deduction (largest first).
+ */
+export function calculateHealthScore(findings) {
+    // Accumulate deductions per category
+    const categoryMap = new Map();
+    for (const finding of findings) {
+        const cost = SEVERITY_COST[finding.severity];
+        const existing = categoryMap.get(finding.category);
+        if (existing) {
+            existing.points += cost;
+            existing.count += 1;
+        }
+        else {
+            categoryMap.set(finding.category, { points: cost, count: 1 });
+        }
+    }
+    // Total deduction
+    let totalDeduction = 0;
+    for (const { points } of categoryMap.values()) {
+        totalDeduction += points;
+    }
+    const score = Math.max(0, 100 - totalDeduction);
+    // Determine grade
+    const grade = GRADE_THRESHOLDS.find((t) => score >= t.min)?.grade ?? "F";
+    // Build sorted breakdown
+    const breakdown = [...categoryMap.entries()]
+        .map(([category, data]) => ({
+        category,
+        points: data.points,
+        count: data.count,
+    }))
+        .sort((a, b) => b.points - a.points);
+    return { score, grade, breakdown };
+}
+//# sourceMappingURL=health.js.map

package/dist/core/score/health.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.js","sourceRoot":"","sources":["../../../src/core/score/health.ts"],"names":[],"mappings":"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"}

package/dist/core/watch/watcher.d.ts

@@ -0,0 +1,29 @@
+import type { BiltConfig, WatchEvent } from "../../types/index.js";
+export interface WatcherHandle {
+    close: () => Promise<void>;
+}
+/**
+ * Start watching a project directory for file changes.
+ *
+ * On each change:
+ *   1. Read the modified file.
+ *   2. Run secret-detection rules against its content.
+ *   3. Invoke the `onEvent` callback with the resulting findings.
+ *
+ * The watcher ignores `node_modules`, `.git`, `.bilt`, `dist`, `build`,
+ * and binary files.  Changes are debounced (default 300ms) to avoid
+ * flooding the callback during bulk operations like `npm install`.
+ *
+ * @param projectDir Root directory to watch.
+ * @param config     Bilt configuration (used for entropy threshold & ignore patterns).
+ * @param onEvent    Callback invoked with watch events.
+ * @returns A handle with a `close()` method to stop watching.
+ */
+export declare function startWatcher(projectDir: string, config: BiltConfig, onEvent: (event: WatchEvent) => void): WatcherHandle;
+/**
+ * Stop a running watcher.
+ *
+ * @param watcher The watcher handle returned by `startWatcher`.
+ */
+export declare function stopWatcher(watcher: WatcherHandle): Promise<void>;
+//# sourceMappingURL=watcher.d.ts.map