@graphpilot-oss/graphpilot 0.0.1

package/dist/parser.js

@@ -0,0 +1,128 @@
+import Parser from 'tree-sitter';
+// @ts-ignore — tree-sitter-typescript ships JS, has no types
+import TS from 'tree-sitter-typescript';
+import { readFileSync, statSync } from 'node:fs';
+import { extname } from 'node:path';
+import { MAX_FILE_BYTES } from './validation.js';
+const PARSER_CACHE = new Map();
+function getParser(lang) {
+    if (PARSER_CACHE.has(lang))
+        return PARSER_CACHE.get(lang);
+    const p = new Parser();
+    // Cast around the peer-dep type-version skew between tree-sitter and
+    // tree-sitter-typescript. Runtime is fine; only the .d.ts files disagree.
+    const langs = TS;
+    switch (lang) {
+        case 'typescript':
+            p.setLanguage(langs.typescript);
+            break;
+        case 'tsx':
+            p.setLanguage(langs.tsx);
+            break;
+        case 'javascript':
+        case 'jsx':
+            p.setLanguage(langs.typescript);
+            break;
+    }
+    PARSER_CACHE.set(lang, p);
+    return p;
+}
+export function detectLang(path) {
+    switch (extname(path).toLowerCase()) {
+        case '.ts':
+            return 'typescript';
+        case '.tsx':
+            return 'tsx';
+        case '.js':
+        case '.mjs':
+        case '.cjs':
+            return 'javascript';
+        case '.jsx':
+            return 'jsx';
+        default:
+            return null;
+    }
+}
+export function parseFile(path) {
+    const lang = detectLang(path);
+    if (!lang)
+        return null;
+    // Defence against T1 (resource exhaustion): skip oversized files rather than
+    // OOM the process. 5 MB is enough for any real source file.
+    let size;
+    try {
+        size = statSync(path).size;
+    }
+    catch {
+        return null;
+    }
+    if (size > MAX_FILE_BYTES)
+        return null;
+    const source = readFileSync(path, 'utf8');
+    return parseSource(path, source, lang);
+}
+export function parseSource(path, source, lang) {
+    const tree = getParser(lang).parse(source);
+    return { path, lang, tree, source };
+}
+/**
+ * Walk the tree and yield every node. Depth-first, pre-order.
+ *
+ * Iterative (not recursive) so a deeply-nested AST can't blow the JS stack.
+ * Tree-sitter trees on real codebases hit ~50–80 depth; pathological generated
+ * code can go much deeper. Defence against T1.
+ */
+export function* walk(node) {
+    const stack = [node];
+    while (stack.length > 0) {
+        const cur = stack.pop();
+        yield cur;
+        // Push children in reverse so they pop in original order (preserves
+        // pre-order traversal — matters for callers that rely on source ordering).
+        for (let i = cur.childCount - 1; i >= 0; i--) {
+            const child = cur.child(i);
+            if (child)
+                stack.push(child);
+        }
+    }
+}
+/**
+ * Day-2 deliverable: list every function name in a parsed file.
+ * Catches: function declarations, arrow functions assigned to consts,
+ * class methods, function expressions assigned to variables.
+ */
+export function listFunctions(parsed) {
+    const names = [];
+    for (const node of walk(parsed.tree.rootNode)) {
+        const name = functionNameOf(node);
+        if (name)
+            names.push(name);
+    }
+    return names;
+}
+function functionNameOf(node) {
+    switch (node.type) {
+        case 'function_declaration':
+        case 'generator_function_declaration':
+        case 'method_definition':
+        case 'function_signature': {
+            const nameNode = node.childForFieldName('name');
+            return nameNode?.text ?? null;
+        }
+        case 'variable_declarator': {
+            // const foo = () => ... | const foo = function() {}
+            const valueNode = node.childForFieldName('value');
+            if (valueNode &&
+                (valueNode.type === 'arrow_function' ||
+                    valueNode.type === 'function_expression' ||
+                    valueNode.type === 'function')) {
+                const nameNode = node.childForFieldName('name');
+                return nameNode?.text ?? null;
+            }
+            return null;
+        }
+        default:
+            return null;
+    }
+}
+//# sourceMappingURL=parser.js.map

package/dist/parser.js.map

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

package/dist/provenance.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Provenance / evidence anchors for tool responses.
+ *
+ * Why this exists: agents hallucinate. The most common Cursor / Claude
+ * Code failure pattern is "the model called a function that doesn't
+ * exist" — and the user has no quick way to verify a tool's claim
+ * before acting on it.
+ *
+ * Solution: every result we return carries an evidence anchor — a
+ * structured `{file, line, sha, excerpt}` reference that the agent
+ * can include verbatim in its reply. The user (or the agent itself)
+ * can then jump to the file/line and confirm the cited code matches
+ * the claim. If we ever fabricate, the anchor exposes us instantly.
+ *
+ * Format design:
+ *   - Path is relative to the indexed root (portable).
+ *   - Line is 1-indexed (matches editor convention).
+ *   - SHA is optional — null when the indexed repo isn't a git repo.
+ *     When present, it's the 7-char short SHA of the index time.
+ *   - Excerpt is optional and short (~200 chars) — for symbol records
+ *     it's the signature line. For edges it's the call expression.
+ *
+ * Per the differentiation research, this is the SINGLE feature no
+ * competitor in the 15+ landscape has shipped. See
+ * .notes/differentiation-research-2026-05-21.md §1.3.
+ */
+import type { SymbolRecord } from './symbols.js';
+import type { CallEdge } from './edges.js';
+/** A single evidence anchor pointing at a specific location in the repo. */
+export interface Provenance {
+    /** Relative path from the indexed repo root, e.g. "src/auth.ts". */
+    file: string;
+    /** 1-indexed line number. */
+    line: number;
+    /** Optional 1-indexed column. */
+    column?: number;
+    /** End line, when the entity spans multiple lines. */
+    endLine?: number;
+    /** Short git SHA (7 chars) at index time. Null if not a git repo. */
+    sha?: string | null;
+    /** Short text excerpt — symbol signature, call expression, etc. */
+    excerpt?: string;
+}
+/**
+ * Make provenance for a symbol. Excerpt is the symbol's stored
+ * signature (already secret-redacted by T3).
+ */
+export declare function symbolProvenance(s: SymbolRecord, sha: string | null): Provenance;
+/**
+ * Make provenance for a call edge. Points at the CALL SITE (where the
+ * call happens), not the callee's definition. The callee's own
+ * provenance is available via `symbolProvenance(idx.findById(edge.toId))`
+ * when toId is non-null.
+ */
+export declare function edgeProvenance(e: CallEdge, sha: string | null): Provenance;
+/**
+ * Format a Provenance as a single-line human/agent-readable string.
+ * Used inline in tool text responses.
+ *
+ * Examples:
+ *   src/auth.ts:42                    (no sha — not a git repo)
+ *   src/auth.ts:42 @ ab12cd3          (with sha)
+ *   src/auth.ts:42:5 @ ab12cd3        (with column)
+ */
+export declare function formatProvenance(p: Provenance): string;
+/**
+ * Format a Provenance as a verifiable evidence tag the agent can
+ * include in its reply. The agent's user (or a downstream tool) can
+ * paste this directly into a search.
+ *
+ * Example:
+ *   [evidence: src/auth.ts:42 @ ab12cd3]
+ */
+export declare function formatEvidenceTag(p: Provenance): string;

package/dist/provenance.js

@@ -0,0 +1,95 @@
+/**
+ * Provenance / evidence anchors for tool responses.
+ *
+ * Why this exists: agents hallucinate. The most common Cursor / Claude
+ * Code failure pattern is "the model called a function that doesn't
+ * exist" — and the user has no quick way to verify a tool's claim
+ * before acting on it.
+ *
+ * Solution: every result we return carries an evidence anchor — a
+ * structured `{file, line, sha, excerpt}` reference that the agent
+ * can include verbatim in its reply. The user (or the agent itself)
+ * can then jump to the file/line and confirm the cited code matches
+ * the claim. If we ever fabricate, the anchor exposes us instantly.
+ *
+ * Format design:
+ *   - Path is relative to the indexed root (portable).
+ *   - Line is 1-indexed (matches editor convention).
+ *   - SHA is optional — null when the indexed repo isn't a git repo.
+ *     When present, it's the 7-char short SHA of the index time.
+ *   - Excerpt is optional and short (~200 chars) — for symbol records
+ *     it's the signature line. For edges it's the call expression.
+ *
+ * Per the differentiation research, this is the SINGLE feature no
+ * competitor in the 15+ landscape has shipped. See
+ * .notes/differentiation-research-2026-05-21.md §1.3.
+ */
+const MAX_EXCERPT_LEN = 200;
+function clipExcerpt(s) {
+    if (!s)
+        return undefined;
+    const trimmed = s.trim();
+    if (trimmed.length === 0)
+        return undefined;
+    return trimmed.length > MAX_EXCERPT_LEN ? trimmed.slice(0, MAX_EXCERPT_LEN - 1) + '…' : trimmed;
+}
+/**
+ * Make provenance for a symbol. Excerpt is the symbol's stored
+ * signature (already secret-redacted by T3).
+ */
+export function symbolProvenance(s, sha) {
+    return {
+        file: s.file,
+        line: s.line,
+        column: s.column,
+        endLine: s.endLine,
+        sha: sha ?? null,
+        excerpt: clipExcerpt(s.signature),
+    };
+}
+/**
+ * Make provenance for a call edge. Points at the CALL SITE (where the
+ * call happens), not the callee's definition. The callee's own
+ * provenance is available via `symbolProvenance(idx.findById(edge.toId))`
+ * when toId is non-null.
+ */
+export function edgeProvenance(e, sha) {
+    return {
+        file: e.file,
+        line: e.line,
+        column: e.column,
+        sha: sha ?? null,
+        // No excerpt for edges — we don't store the call line text.
+        // (Future v0.2: capture the call line at index time so the agent
+        // sees the actual call expression.)
+    };
+}
+/**
+ * Format a Provenance as a single-line human/agent-readable string.
+ * Used inline in tool text responses.
+ *
+ * Examples:
+ *   src/auth.ts:42                    (no sha — not a git repo)
+ *   src/auth.ts:42 @ ab12cd3          (with sha)
+ *   src/auth.ts:42:5 @ ab12cd3        (with column)
+ */
+export function formatProvenance(p) {
+    let out = p.file + ':' + p.line;
+    if (p.column !== undefined)
+        out += ':' + p.column;
+    if (p.sha)
+        out += ' @ ' + p.sha;
+    return out;
+}
+/**
+ * Format a Provenance as a verifiable evidence tag the agent can
+ * include in its reply. The agent's user (or a downstream tool) can
+ * paste this directly into a search.
+ *
+ * Example:
+ *   [evidence: src/auth.ts:42 @ ab12cd3]
+ */
+export function formatEvidenceTag(p) {
+    return `[evidence: ${formatProvenance(p)}]`;
+}
+//# sourceMappingURL=provenance.js.map

package/dist/provenance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provenance.js","sourceRoot":"","sources":["../src/provenance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAqBH,MAAM,eAAe,GAAG,GAAG,CAAC;AAE5B,SAAS,WAAW,CAAC,CAAqB;IACxC,IAAI,CAAC,CAAC;QAAE,OAAO,SAAS,CAAC;IACzB,MAAM,OAAO,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IACzB,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAC3C,OAAO,OAAO,CAAC,MAAM,GAAG,eAAe,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,eAAe,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC;AAClG,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,CAAe,EAAE,GAAkB;IAClE,OAAO;QACL,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,MAAM,EAAE,CAAC,CAAC,MAAM;QAChB,OAAO,EAAE,CAAC,CAAC,OAAO;QAClB,GAAG,EAAE,GAAG,IAAI,IAAI;QAChB,OAAO,EAAE,WAAW,CAAC,CAAC,CAAC,SAAS,CAAC;KAClC,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,CAAW,EAAE,GAAkB;IAC5D,OAAO;QACL,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,MAAM,EAAE,CAAC,CAAC,MAAM;QAChB,GAAG,EAAE,GAAG,IAAI,IAAI;QAChB,4DAA4D;QAC5D,iEAAiE;QACjE,oCAAoC;KACrC,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,gBAAgB,CAAC,CAAa;IAC5C,IAAI,GAAG,GAAG,CAAC,CAAC,IAAI,GAAG,GAAG,GAAG,CAAC,CAAC,IAAI,CAAC;IAChC,IAAI,CAAC,CAAC,MAAM,KAAK,SAAS;QAAE,GAAG,IAAI,GAAG,GAAG,CAAC,CAAC,MAAM,CAAC;IAClD,IAAI,CAAC,CAAC,GAAG;QAAE,GAAG,IAAI,KAAK,GAAG,CAAC,CAAC,GAAG,CAAC;IAChC,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAAC,CAAa;IAC7C,OAAO,cAAc,gBAAgB,CAAC,CAAC,CAAC,GAAG,CAAC;AAC9C,CAAC"}

package/dist/query.d.ts

@@ -0,0 +1,68 @@
+import type { Graph } from './storage.js';
+import type { SymbolRecord } from './symbols.js';
+import type { CallEdge } from './edges.js';
+export interface RecallOptions {
+    /** Max results. Default 10. Capped at 100. */
+    limit?: number;
+    /**
+     * If true, match if the query is a substring of the symbol name.
+     * If false (default), require exact case-insensitive match.
+     */
+    substring?: boolean;
+}
+export interface EdgeQueryOptions {
+    /** Max edges to return. Default 50. Capped at 500. */
+    limit?: number;
+    /**
+     * If true, include edges where the callee is unresolved (toId === null).
+     * Default true — agents usually want to see those too.
+     */
+    includeUnresolved?: boolean;
+}
+/**
+ * Pre-computed lookup tables over a Graph. Build once after loading; every
+ * query is then O(1) or O(k) (k = result count).
+ *
+ * The whole index is built in one pass on construction. For graphpilot's own
+ * code (50 symbols, 155 edges) build time is <1ms. For a 50k-symbol repo
+ * we'd expect ~20ms — still negligible compared to a Claude Code round trip.
+ */
+export declare class GraphIndex {
+    readonly graph: Graph;
+    private readonly byNameLower;
+    private readonly byId;
+    /** Edges keyed by callee id — answers "who calls X?". */
+    private readonly callersOf;
+    /** Edges keyed by caller id — answers "what does X call?". */
+    private readonly calleesOf;
+    constructor(graph: Graph);
+    /**
+     * Find symbols by name. Default behaviour is exact case-insensitive match;
+     * pass `substring: true` to enable substring search.
+     *
+     * Returns ranked roughly by "best first" — exact case match before
+     * case-folded matches.
+     */
+    findByName(query: string, opts?: RecallOptions): SymbolRecord[];
+    /** Look up a symbol by its id. Returns null if not found. */
+    findById(id: string): SymbolRecord | null;
+    /**
+     * Resolve a name (or id) to a unique symbol. Used by tools that take a
+     * "symbol" argument — accepts either a bare name or a full id.
+     *
+     * Ambiguity policy: if more than one symbol matches the name, returns the
+     * first one (same heuristic as the resolver). Caller can disambiguate by
+     * passing the full id.
+     */
+    resolveSymbol(nameOrId: string): SymbolRecord | null;
+    /** Edges where this symbol is the target — "who calls X?". */
+    callers(symbolId: string, opts?: EdgeQueryOptions): CallEdge[];
+    /** Edges where this symbol is the source — "what does X call?". */
+    callees(symbolId: string, opts?: EdgeQueryOptions): CallEdge[];
+    /** Convenience: how many symbols / edges are indexed. */
+    get stats(): {
+        symbols: number;
+        edges: number;
+        resolvedEdges: number;
+    };
+}

package/dist/query.js

@@ -0,0 +1,127 @@
+const HARD_RESULT_CAP = 100;
+const HARD_EDGE_CAP = 500;
+/**
+ * Pre-computed lookup tables over a Graph. Build once after loading; every
+ * query is then O(1) or O(k) (k = result count).
+ *
+ * The whole index is built in one pass on construction. For graphpilot's own
+ * code (50 symbols, 155 edges) build time is <1ms. For a 50k-symbol repo
+ * we'd expect ~20ms — still negligible compared to a Claude Code round trip.
+ */
+export class GraphIndex {
+    graph;
+    byNameLower = new Map();
+    byId = new Map();
+    /** Edges keyed by callee id — answers "who calls X?". */
+    callersOf = new Map();
+    /** Edges keyed by caller id — answers "what does X call?". */
+    calleesOf = new Map();
+    constructor(graph) {
+        this.graph = graph;
+        for (const s of graph.symbols) {
+            this.byId.set(s.id, s);
+            const key = s.name.toLowerCase();
+            const list = this.byNameLower.get(key);
+            if (list)
+                list.push(s);
+            else
+                this.byNameLower.set(key, [s]);
+        }
+        for (const e of graph.edges) {
+            // callers index — only resolved edges have a toId
+            if (e.toId) {
+                const list = this.callersOf.get(e.toId);
+                if (list)
+                    list.push(e);
+                else
+                    this.callersOf.set(e.toId, [e]);
+            }
+            // callees index — every edge has a fromId
+            const list = this.calleesOf.get(e.fromId);
+            if (list)
+                list.push(e);
+            else
+                this.calleesOf.set(e.fromId, [e]);
+        }
+    }
+    /**
+     * Find symbols by name. Default behaviour is exact case-insensitive match;
+     * pass `substring: true` to enable substring search.
+     *
+     * Returns ranked roughly by "best first" — exact case match before
+     * case-folded matches.
+     */
+    findByName(query, opts = {}) {
+        const limit = Math.min(opts.limit ?? 10, HARD_RESULT_CAP);
+        if (!query)
+            return [];
+        if (opts.substring) {
+            const q = query.toLowerCase();
+            const results = [];
+            for (const [name, syms] of this.byNameLower) {
+                if (!name.includes(q))
+                    continue;
+                for (const s of syms) {
+                    results.push(s);
+                    if (results.length >= limit)
+                        return results;
+                }
+            }
+            return results;
+        }
+        // Exact case-insensitive — fast path through the map.
+        const candidates = this.byNameLower.get(query.toLowerCase()) ?? [];
+        if (candidates.length === 0)
+            return [];
+        // Prefer exact case match first, then the rest.
+        const exact = candidates.filter((s) => s.name === query);
+        const rest = candidates.filter((s) => s.name !== query);
+        return [...exact, ...rest].slice(0, limit);
+    }
+    /** Look up a symbol by its id. Returns null if not found. */
+    findById(id) {
+        return this.byId.get(id) ?? null;
+    }
+    /**
+     * Resolve a name (or id) to a unique symbol. Used by tools that take a
+     * "symbol" argument — accepts either a bare name or a full id.
+     *
+     * Ambiguity policy: if more than one symbol matches the name, returns the
+     * first one (same heuristic as the resolver). Caller can disambiguate by
+     * passing the full id.
+     */
+    resolveSymbol(nameOrId) {
+        if (nameOrId.includes('#') && nameOrId.includes('@')) {
+            return this.findById(nameOrId);
+        }
+        const matches = this.findByName(nameOrId);
+        return matches[0] ?? null;
+    }
+    /** Edges where this symbol is the target — "who calls X?". */
+    callers(symbolId, opts = {}) {
+        const limit = Math.min(opts.limit ?? 50, HARD_EDGE_CAP);
+        return (this.callersOf.get(symbolId) ?? []).slice(0, limit);
+    }
+    /** Edges where this symbol is the source — "what does X call?". */
+    callees(symbolId, opts = {}) {
+        const limit = Math.min(opts.limit ?? 50, HARD_EDGE_CAP);
+        const all = this.calleesOf.get(symbolId) ?? [];
+        if (opts.includeUnresolved === false) {
+            return all.filter((e) => e.toId !== null).slice(0, limit);
+        }
+        return all.slice(0, limit);
+    }
+    /** Convenience: how many symbols / edges are indexed. */
+    get stats() {
+        let resolved = 0;
+        for (const e of this.graph.edges)
+            if (e.toId)
+                resolved++;
+        return {
+            symbols: this.graph.symbols.length,
+            edges: this.graph.edges.length,
+            resolvedEdges: resolved,
+        };
+    }
+}
+//# sourceMappingURL=query.js.map

package/dist/query.js.map

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

package/dist/redact.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Secret-pattern redaction for symbol signatures before they're stored.
+ *
+ * Code occasionally contains literal secrets — `const API_KEY = "sk-..."`,
+ * embedded JWTs, AWS access keys, GitHub tokens. When we extract a symbol's
+ * signature line into graph.json, those literals come with it. We redact
+ * them here so:
+ *   1. The on-disk graph.json doesn't carry plaintext secrets
+ *   2. The MCP tool output sent to the agent doesn't expose them either
+ *
+ * This is NOT a full secret scanner — it covers well-known fixed-prefix
+ * formats. Determined leakage (custom-format secrets) will still escape,
+ * but the common ones are covered.
+ *
+ * Pattern coverage and replacement tokens are intentionally short so a
+ * signature stays readable after redaction.
+ */
+/**
+ * Run every secret pattern over the input string. Returns the redacted text.
+ * Safe for any input length: regex operations are linear in input size.
+ *
+ * Order matters — more specific patterns run first so a JWT doesn't get
+ * eaten by the generic long-token catch-all.
+ */
+export declare function redactSecrets(text: string): string;
+/**
+ * Test helper / introspection: which patterns matched in this input?
+ * Useful for diagnostics; not on a hot path.
+ */
+export declare function detectSecrets(text: string): string[];

package/dist/redact.js

@@ -0,0 +1,117 @@
+/**
+ * Secret-pattern redaction for symbol signatures before they're stored.
+ *
+ * Code occasionally contains literal secrets — `const API_KEY = "sk-..."`,
+ * embedded JWTs, AWS access keys, GitHub tokens. When we extract a symbol's
+ * signature line into graph.json, those literals come with it. We redact
+ * them here so:
+ *   1. The on-disk graph.json doesn't carry plaintext secrets
+ *   2. The MCP tool output sent to the agent doesn't expose them either
+ *
+ * This is NOT a full secret scanner — it covers well-known fixed-prefix
+ * formats. Determined leakage (custom-format secrets) will still escape,
+ * but the common ones are covered.
+ *
+ * Pattern coverage and replacement tokens are intentionally short so a
+ * signature stays readable after redaction.
+ */
+const SECRET_PATTERNS = [
+    // PEM private-key headers — match the BEGIN line before generic long-token
+    // catches it, so we get the precise label.
+    {
+        pattern: /-----BEGIN [A-Z ]*PRIVATE KEY-----/g,
+        replacement: '-----BEGIN ***REDACTED*** PRIVATE KEY-----',
+        label: 'pem-private-key',
+    },
+    // JSON Web Tokens: three base64url segments separated by dots.
+    {
+        pattern: /eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/g,
+        replacement: '***JWT-REDACTED***',
+        label: 'jwt',
+    },
+    // OpenAI / Anthropic style API keys: `sk-` then 20+ alphanumerics.
+    // Also covers `sk-ant-...`, `sk-proj-...` etc.
+    {
+        pattern: /\bsk-[A-Za-z0-9_-]{20,}\b/g,
+        replacement: 'sk-***REDACTED***',
+        label: 'sk-token',
+    },
+    // GitHub personal access tokens.
+    { pattern: /\bghp_[A-Za-z0-9]{30,}\b/g, replacement: 'ghp_***REDACTED***', label: 'github-pat' },
+    // GitHub server tokens.
+    {
+        pattern: /\bghs_[A-Za-z0-9]{30,}\b/g,
+        replacement: 'ghs_***REDACTED***',
+        label: 'github-server',
+    },
+    // GitHub user / OAuth tokens.
+    {
+        pattern: /\bgho_[A-Za-z0-9]{30,}\b/g,
+        replacement: 'gho_***REDACTED***',
+        label: 'github-oauth',
+    },
+    // GitHub refresh tokens.
+    {
+        pattern: /\bghr_[A-Za-z0-9]{30,}\b/g,
+        replacement: 'ghr_***REDACTED***',
+        label: 'github-refresh',
+    },
+    // AWS access key IDs.
+    { pattern: /\bAKIA[0-9A-Z]{16}\b/g, replacement: 'AKIA***REDACTED***', label: 'aws-akia' },
+    // AWS short-term session tokens (less specific, but the leading prefix is unique).
+    { pattern: /\bASIA[0-9A-Z]{16}\b/g, replacement: 'ASIA***REDACTED***', label: 'aws-asia' },
+    // Slack tokens.
+    {
+        pattern: /\bxox[abprs]-[A-Za-z0-9-]{10,}\b/g,
+        replacement: 'xox*-***REDACTED***',
+        label: 'slack',
+    },
+    // Stripe live secret keys.
+    {
+        pattern: /\bsk_live_[A-Za-z0-9]{20,}\b/g,
+        replacement: 'sk_live_***REDACTED***',
+        label: 'stripe-live',
+    },
+    // Generic long high-entropy token inside a string literal.
+    // Heuristic: 32+ chars of alphanumeric / underscore / hyphen / equals,
+    // immediately surrounded by matching quotes. Keeps false positives down
+    // because random function names rarely live inside quotes.
+    {
+        pattern: /(["'])([A-Za-z0-9_+/=-]{40,})\1/g,
+        replacement: '$1***REDACTED-LONG-TOKEN***$1',
+        label: 'long-token-in-string',
+    },
+];
+/**
+ * Run every secret pattern over the input string. Returns the redacted text.
+ * Safe for any input length: regex operations are linear in input size.
+ *
+ * Order matters — more specific patterns run first so a JWT doesn't get
+ * eaten by the generic long-token catch-all.
+ */
+export function redactSecrets(text) {
+    if (!text)
+        return text;
+    let out = text;
+    for (const { pattern, replacement } of SECRET_PATTERNS) {
+        out = out.replace(pattern, replacement);
+    }
+    return out;
+}
+/**
+ * Test helper / introspection: which patterns matched in this input?
+ * Useful for diagnostics; not on a hot path.
+ */
+export function detectSecrets(text) {
+    if (!text)
+        return [];
+    const hits = [];
+    for (const { pattern, label } of SECRET_PATTERNS) {
+        // Build a fresh regex from the source to avoid lastIndex state on /g.
+        const fresh = new RegExp(pattern.source, pattern.flags);
+        if (fresh.test(text))
+            hits.push(label);
+    }
+    return hits;
+}
+//# sourceMappingURL=redact.js.map

package/dist/redact.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redact.js","sourceRoot":"","sources":["../src/redact.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAQH,MAAM,eAAe,GAA6B;IAChD,2EAA2E;IAC3E,2CAA2C;IAC3C;QACE,OAAO,EAAE,qCAAqC;QAC9C,WAAW,EAAE,4CAA4C;QACzD,KAAK,EAAE,iBAAiB;KACzB;IACD,+DAA+D;IAC/D;QACE,OAAO,EAAE,6DAA6D;QACtE,WAAW,EAAE,oBAAoB;QACjC,KAAK,EAAE,KAAK;KACb;IACD,mEAAmE;IACnE,+CAA+C;IAC/C;QACE,OAAO,EAAE,4BAA4B;QACrC,WAAW,EAAE,mBAAmB;QAChC,KAAK,EAAE,UAAU;KAClB;IACD,iCAAiC;IACjC,EAAE,OAAO,EAAE,2BAA2B,EAAE,WAAW,EAAE,oBAAoB,EAAE,KAAK,EAAE,YAAY,EAAE;IAChG,wBAAwB;IACxB;QACE,OAAO,EAAE,2BAA2B;QACpC,WAAW,EAAE,oBAAoB;QACjC,KAAK,EAAE,eAAe;KACvB;IACD,8BAA8B;IAC9B;QACE,OAAO,EAAE,2BAA2B;QACpC,WAAW,EAAE,oBAAoB;QACjC,KAAK,EAAE,cAAc;KACtB;IACD,yBAAyB;IACzB;QACE,OAAO,EAAE,2BAA2B;QACpC,WAAW,EAAE,oBAAoB;QACjC,KAAK,EAAE,gBAAgB;KACxB;IACD,sBAAsB;IACtB,EAAE,OAAO,EAAE,uBAAuB,EAAE,WAAW,EAAE,oBAAoB,EAAE,KAAK,EAAE,UAAU,EAAE;IAC1F,mFAAmF;IACnF,EAAE,OAAO,EAAE,uBAAuB,EAAE,WAAW,EAAE,oBAAoB,EAAE,KAAK,EAAE,UAAU,EAAE;IAC1F,gBAAgB;IAChB;QACE,OAAO,EAAE,mCAAmC;QAC5C,WAAW,EAAE,qBAAqB;QAClC,KAAK,EAAE,OAAO;KACf;IACD,2BAA2B;IAC3B;QACE,OAAO,EAAE,+BAA+B;QACxC,WAAW,EAAE,wBAAwB;QACrC,KAAK,EAAE,aAAa;KACrB;IACD,2DAA2D;IAC3D,uEAAuE;IACvE,wEAAwE;IACxE,2DAA2D;IAC3D;QACE,OAAO,EAAE,kCAAkC;QAC3C,WAAW,EAAE,+BAA+B;QAC5C,KAAK,EAAE,sBAAsB;KAC9B;CACF,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IACvB,IAAI,GAAG,GAAG,IAAI,CAAC;IACf,KAAK,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,IAAI,eAAe,EAAE,CAAC;QACvD,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;IAC1C,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,IAAI,CAAC,IAAI;QAAE,OAAO,EAAE,CAAC;IACrB,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,KAAK,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,eAAe,EAAE,CAAC;QACjD,sEAAsE;QACtE,MAAM,KAAK,GAAG,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;QACxD,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC;YAAE,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACzC,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}