@obfuscan/core 0.1.0

package/dist/index.js

@@ -0,0 +1,106 @@
+/**
+ * @obfuscan/core — public entry point.
+ *
+ * Stable API surface. Anything not re-exported here is internal and may
+ * change without a major version bump.
+ *
+ * ## Quick start
+ *
+ * ```ts
+ * import { scan } from "@obfuscan/core";
+ * import * as fs from "node:fs/promises";
+ *
+ * const result = await scan(
+ *   { diff: await fs.readFile("pr.diff", "utf8") },
+ *   { fileResolver: (p) => fs.readFile(p, "utf8") },
+ * );
+ *
+ * for (const f of result.findings) {
+ *   console.log(`${f.severity.toUpperCase()} ${f.file}:${f.line} ${f.reason}`);
+ * }
+ * ```
+ *
+ * ## Custom rules
+ *
+ * ```ts
+ * import { scan, loadRuleSet } from "@obfuscan/core";
+ *
+ * const rules = await loadRuleSet({
+ *   languageDir: "./my-rules/languages",
+ *   queryDir:    "./my-rules/queries",
+ * });
+ *
+ * const result = await scan({ dir: "./src" }, { fileResolver, rules });
+ * ```
+ *
+ * ## Custom detectors
+ *
+ * ```ts
+ * import { scan, defaultDetectors, Detector } from "@obfuscan/core";
+ *
+ * const myDetector: Detector = {
+ *   id: "my-org.no-fetch-in-tests",
+ *   applies: (ctx) => /\.test\./.test(ctx.path),
+ *   run: (ctx) => /* ... *\/ [],
+ * };
+ *
+ * const result = await scan(input, {
+ *   fileResolver,
+ *   detectors: [...defaultDetectors(), myDetector],
+ * });
+ * ```
+ */
+// ─── Primary entry point ───────────────────────────────────────────────────
+export { scan } from "./scan.js";
+// ─── Rule loading ──────────────────────────────────────────────────────────
+/**
+ * Load a custom rule set from disk. Use this to point obfuscan at a fork of
+ * `@obfuscan/rules` or at an internal extension. If you only need the
+ * defaults, omit `rules` from `ScanOptions` and the built-in pack is used.
+ */
+export { loadRuleSet, defaultRuleSet } from "./rules.js";
+// ─── Detectors ─────────────────────────────────────────────────────────────
+/**
+ * The shipped detector set. Use this as a base when you want to add or
+ * filter detectors:
+ *
+ * ```ts
+ * const dets = defaultDetectors().filter(d => d.id !== "obf.high-entropy-literal");
+ * ```
+ */
+export { defaultDetectors } from "./detectors/index.js";
+// ─── Allowlist helpers ─────────────────────────────────────────────────────
+/**
+ * Read/write `.obfuscan/allowlist.json`. The CLI uses these directly.
+ * Programmatic users typically pass an inline `allowlist` to `scan()`
+ * instead of touching disk.
+ */
+export { loadAllowlist, saveAllowlist, hashSnippet, matchesAllowlist, } from "./allowlist.js";
+// ─── Diff utilities ────────────────────────────────────────────────────────
+/**
+ * Parse a unified diff into the shape `scan()` consumes internally.
+ * Exposed for hosts (e.g. a Git client) that already have a structured diff
+ * representation and want to skip re-serializing.
+ */
+export { parseDiffToFiles } from "./diff.js";
+// ─── In-source suppression directives ──────────────────────────────────────
+/**
+ * Parses `// obfuscan-disable-next-line <ruleId>` and similar comment
+ * directives. Returns the set of (line, ruleId) pairs to suppress.
+ * Used internally by the aggregator; exposed for tooling that wants to
+ * surface them in a UI.
+ */
+export { extractDisableDirectives } from "./directives.js";
+// ─── Versions ──────────────────────────────────────────────────────────────
+/** SemVer of the engine. Replaced at build time via `__ENGINE_VERSION__`. */
+export { ENGINE_VERSION } from "./version.js";
+// ─── Errors ────────────────────────────────────────────────────────────────
+/**
+ * `InvalidScanInputError` — thrown when `ScanInput` is missing all of
+ * `diff`, `paths`, `dir`, or specifies more than one.
+ *
+ * `InvalidRuleSetError` — thrown when a custom rule set fails validation.
+ * Includes a `details` array describing each problem.
+ */
+export { InvalidScanInputError, InvalidRuleSetError } from "./errors.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAEH,8EAA8E;AAE9E,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AA4BjC,8EAA8E;AAE9E;;;;GAIG;AACH,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEzD,8EAA8E;AAE9E;;;;;;;GAOG;AACH,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAExD,8EAA8E;AAE9E;;;;GAIG;AACH,OAAO,EACL,aAAa,EACb,aAAa,EACb,WAAW,EACX,gBAAgB,GACjB,MAAM,gBAAgB,CAAC;AAExB,8EAA8E;AAE9E;;;;GAIG;AACH,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAG7C,8EAA8E;AAE9E;;;;;GAKG;AACH,OAAO,EAAE,wBAAwB,EAAE,MAAM,iBAAiB,CAAC;AAG3D,8EAA8E;AAE9E,6EAA6E;AAC7E,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C,8EAA8E;AAE9E;;;;;;GAMG;AACH,OAAO,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC"}

package/dist/internal/patterns.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Pattern-building helpers shared by detectors.
+ *
+ * The bundled detectors are intentionally regex-driven rather than parse-tree
+ * driven — that keeps the engine dependency-free and runnable in any Node
+ * environment. The regexes are built dynamically from `LanguageConfig` so the
+ * same detector covers every supported language.
+ *
+ * Tradeoff: regex matching is approximate (no full scope analysis). False
+ * positives are mitigated by:
+ *   - Severity ceilings + allowlist
+ *   - The shape of the patterns (e.g. requiring an *immediate* call wrap)
+ *   - The aggregator's `disabledDetectors` and in-source directives
+ *
+ * For airtight semantic analysis, hosts can override `defaultDetectors()`
+ * with tree-sitter-backed implementations.
+ */
+/**
+ * Escape a string for use as a literal inside a regex.
+ * Handles the dotted/qualified names that appear in language configs
+ * (e.g. `base64.b64decode`, `Buffer.from`, `[Convert]::FromBase64String`).
+ */
+export declare function escapeRegex(s: string): string;
+/**
+ * Build a regex source matching any of the configured names as a function
+ * call. Accepts qualified names — for `base64.b64decode` the regex matches
+ * either the bare `b64decode(...)` or fully-qualified `base64.b64decode(...)`.
+ *
+ * The boundary on the left tolerates common JS/TS/Py prefixes (`.`, `(`,
+ * `=`, `,`, whitespace, start-of-line) so we don't miss expression contexts.
+ *
+ * Returns an inner alternation suitable for inclusion in a larger pattern.
+ */
+export declare function namedCallAlternation(names: readonly string[]): string;
+/**
+ * 1-based line number for a 0-based character offset.
+ * Used by every detector to report source positions.
+ */
+export declare function lineAtOffset(source: string, offset: number): number;
+/**
+ * 1-based end line of a span starting at `start` and consuming `length` chars.
+ */
+export declare function lineAtEnd(source: string, start: number, length: number): number;
+/** Cap on how many findings any single detector emits per file. */
+export declare const MAX_FINDINGS_PER_DETECTOR = 50;
+/** Cap on file size before detectors short-circuit. */
+export declare const MAX_SOURCE_BYTES = 2000000;
+//# sourceMappingURL=patterns.d.ts.map

package/dist/internal/patterns.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"patterns.d.ts","sourceRoot":"","sources":["../../src/internal/patterns.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE7C;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAkCrE;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAOnE;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAE/E;AAED,mEAAmE;AACnE,eAAO,MAAM,yBAAyB,KAAK,CAAC;AAE5C,uDAAuD;AACvD,eAAO,MAAM,gBAAgB,UAAY,CAAC"}

package/dist/internal/patterns.js

@@ -0,0 +1,95 @@
+/**
+ * Pattern-building helpers shared by detectors.
+ *
+ * The bundled detectors are intentionally regex-driven rather than parse-tree
+ * driven — that keeps the engine dependency-free and runnable in any Node
+ * environment. The regexes are built dynamically from `LanguageConfig` so the
+ * same detector covers every supported language.
+ *
+ * Tradeoff: regex matching is approximate (no full scope analysis). False
+ * positives are mitigated by:
+ *   - Severity ceilings + allowlist
+ *   - The shape of the patterns (e.g. requiring an *immediate* call wrap)
+ *   - The aggregator's `disabledDetectors` and in-source directives
+ *
+ * For airtight semantic analysis, hosts can override `defaultDetectors()`
+ * with tree-sitter-backed implementations.
+ */
+/**
+ * Escape a string for use as a literal inside a regex.
+ * Handles the dotted/qualified names that appear in language configs
+ * (e.g. `base64.b64decode`, `Buffer.from`, `[Convert]::FromBase64String`).
+ */
+export function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Build a regex source matching any of the configured names as a function
+ * call. Accepts qualified names — for `base64.b64decode` the regex matches
+ * either the bare `b64decode(...)` or fully-qualified `base64.b64decode(...)`.
+ *
+ * The boundary on the left tolerates common JS/TS/Py prefixes (`.`, `(`,
+ * `=`, `,`, whitespace, start-of-line) so we don't miss expression contexts.
+ *
+ * Returns an inner alternation suitable for inclusion in a larger pattern.
+ */
+export function namedCallAlternation(names) {
+    const alts = [];
+    for (const raw of names) {
+        if (!raw)
+            continue;
+        // Special-case PowerShell's `[Type]::Member` form
+        if (/^\[.+\]::/.test(raw)) {
+            alts.push(escapeRegex(raw));
+            continue;
+        }
+        // Special-case Bash pipelines like `base64 -d` or `base64 --decode`
+        if (/\s/.test(raw)) {
+            alts.push(escapeRegex(raw));
+            continue;
+        }
+        // Split on either `.` (Python/JS) or `::` (Perl/Ruby/Rust/C++) to find
+        // the bare tail. We accept both because configs mix conventions across
+        // languages (e.g. `MIME::Base64::decode_base64`, `base64.b64decode`).
+        const parts = raw.split(/\.|::/);
+        const tail = parts[parts.length - 1] ?? raw;
+        alts.push(escapeRegex(raw));
+        if (parts.length > 1 && tail !== raw && tail.length > 0) {
+            alts.push(escapeRegex(tail));
+        }
+    }
+    // Deduplicate while preserving order
+    const seen = new Set();
+    const unique = [];
+    for (const a of alts) {
+        if (!seen.has(a)) {
+            seen.add(a);
+            unique.push(a);
+        }
+    }
+    return unique.join("|");
+}
+/**
+ * 1-based line number for a 0-based character offset.
+ * Used by every detector to report source positions.
+ */
+export function lineAtOffset(source, offset) {
+    let line = 1;
+    const cap = Math.min(offset, source.length);
+    for (let i = 0; i < cap; i++) {
+        if (source.charCodeAt(i) === 10 /* \n */)
+            line++;
+    }
+    return line;
+}
+/**
+ * 1-based end line of a span starting at `start` and consuming `length` chars.
+ */
+export function lineAtEnd(source, start, length) {
+    return lineAtOffset(source, start + length);
+}
+/** Cap on how many findings any single detector emits per file. */
+export const MAX_FINDINGS_PER_DETECTOR = 50;
+/** Cap on file size before detectors short-circuit. */
+export const MAX_SOURCE_BYTES = 2_000_000;
+//# sourceMappingURL=patterns.js.map

package/dist/internal/patterns.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"patterns.js","sourceRoot":"","sources":["../../src/internal/patterns.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,CAAS;IACnC,OAAO,CAAC,CAAC,OAAO,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAC;AAClD,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAwB;IAC3D,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,KAAK,MAAM,GAAG,IAAI,KAAK,EAAE,CAAC;QACxB,IAAI,CAAC,GAAG;YAAE,SAAS;QACnB,kDAAkD;QAClD,IAAI,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YAC1B,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC;YAC5B,SAAS;QACX,CAAC;QACD,oEAAoE;QACpE,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YACnB,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC;YAC5B,SAAS;QACX,CAAC;QACD,uEAAuE;QACvE,uEAAuE;QACvE,sEAAsE;QACtE,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACjC,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI,GAAG,CAAC;QAC5C,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC;QAC5B,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,IAAI,KAAK,GAAG,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACxD,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC;QAC/B,CAAC;IACH,CAAC;IACD,qCAAqC;IACrC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;QACrB,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;YACjB,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YACZ,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACjB,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC1B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,MAAc,EAAE,MAAc;IACzD,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;IAC5C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC;QAC7B,IAAI,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,QAAQ;YAAE,IAAI,EAAE,CAAC;IACnD,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,SAAS,CAAC,MAAc,EAAE,KAAa,EAAE,MAAc;IACrE,OAAO,YAAY,CAAC,MAAM,EAAE,KAAK,GAAG,MAAM,CAAC,CAAC;AAC9C,CAAC;AAED,mEAAmE;AACnE,MAAM,CAAC,MAAM,yBAAyB,GAAG,EAAE,CAAC;AAE5C,uDAAuD;AACvD,MAAM,CAAC,MAAM,gBAAgB,GAAG,SAAS,CAAC"}

package/dist/internal/text.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Internal text helpers shared across detectors.
+ *
+ * Anything in `src/internal/` is NOT part of the public API and may change
+ * without a major version bump. Detectors are allowed to import from here.
+ * External consumers must not.
+ */
+/**
+ * Truncate a snippet to `Finding.snippet`'s documented 200-char ceiling.
+ * The engine also enforces this defensively, but doing it in the detector
+ * keeps `Finding.evidence` payloads consistent with what the user sees.
+ */
+export declare function truncateSnippet(s: string): string;
+//# sourceMappingURL=text.d.ts.map

package/dist/internal/text.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"text.d.ts","sourceRoot":"","sources":["../../src/internal/text.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAGjD"}

package/dist/internal/text.js

@@ -0,0 +1,20 @@
+/**
+ * Internal text helpers shared across detectors.
+ *
+ * Anything in `src/internal/` is NOT part of the public API and may change
+ * without a major version bump. Detectors are allowed to import from here.
+ * External consumers must not.
+ */
+const MAX_SNIPPET_LEN = 200;
+const ELLIPSIS = "...";
+/**
+ * Truncate a snippet to `Finding.snippet`'s documented 200-char ceiling.
+ * The engine also enforces this defensively, but doing it in the detector
+ * keeps `Finding.evidence` payloads consistent with what the user sees.
+ */
+export function truncateSnippet(s) {
+    if (s.length <= MAX_SNIPPET_LEN)
+        return s;
+    return s.slice(0, MAX_SNIPPET_LEN - ELLIPSIS.length) + ELLIPSIS;
+}
+//# sourceMappingURL=text.js.map

package/dist/internal/text.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"text.js","sourceRoot":"","sources":["../../src/internal/text.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,eAAe,GAAG,GAAG,CAAC;AAC5B,MAAM,QAAQ,GAAG,KAAK,CAAC;AAEvB;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,CAAS;IACvC,IAAI,CAAC,CAAC,MAAM,IAAI,eAAe;QAAE,OAAO,CAAC,CAAC;IAC1C,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,eAAe,GAAG,QAAQ,CAAC,MAAM,CAAC,GAAG,QAAQ,CAAC;AAClE,CAAC"}

package/dist/rules.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Rule pack loader.
+ *
+ * Loads `LanguageConfig` JSON files from a directory (or from the bundled
+ * @obfuscan/rules package) and exposes a `RuleSet` interface used by the
+ * scan loop.
+ *
+ * No tree-sitter grammars are loaded eagerly — `loadGrammar()` is a stub that
+ * returns a sentinel handle. The bundled detectors operate on raw source via
+ * regex/AST-lite techniques and don't require a live parser. Hosts that want
+ * full tree-sitter parsing can implement their own `RuleSet` and pass it via
+ * `ScanOptions.rules`.
+ */
+import type { RuleSet } from "./types.js";
+interface LoadOptions {
+    /** Directory containing per-language *.json configs. */
+    languageDir: string;
+    /** Optional directory of .scm queries. Currently informational; reserved for future use. */
+    queryDir?: string;
+}
+/** Build a RuleSet by scanning a directory of language configs. */
+export declare function loadRuleSet(opts: LoadOptions): Promise<RuleSet>;
+export declare function defaultRuleSet(): Promise<RuleSet>;
+export {};
+//# sourceMappingURL=rules.d.ts.map

package/dist/rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rules.d.ts","sourceRoot":"","sources":["../src/rules.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,OAAO,KAAK,EAAiC,OAAO,EAAE,MAAM,YAAY,CAAC;AAGzE,UAAU,WAAW;IACnB,wDAAwD;IACxD,WAAW,EAAE,MAAM,CAAC;IACpB,4FAA4F;IAC5F,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,mEAAmE;AACnE,wBAAsB,WAAW,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,CAsFrE;AA0CD,wBAAsB,cAAc,IAAI,OAAO,CAAC,OAAO,CAAC,CAkBvD"}

package/dist/rules.js

@@ -0,0 +1,195 @@
+/**
+ * Rule pack loader.
+ *
+ * Loads `LanguageConfig` JSON files from a directory (or from the bundled
+ * @obfuscan/rules package) and exposes a `RuleSet` interface used by the
+ * scan loop.
+ *
+ * No tree-sitter grammars are loaded eagerly — `loadGrammar()` is a stub that
+ * returns a sentinel handle. The bundled detectors operate on raw source via
+ * regex/AST-lite techniques and don't require a live parser. Hosts that want
+ * full tree-sitter parsing can implement their own `RuleSet` and pass it via
+ * `ScanOptions.rules`.
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { InvalidRuleSetError } from "./errors.js";
+/** Build a RuleSet by scanning a directory of language configs. */
+export async function loadRuleSet(opts) {
+    const { languageDir } = opts;
+    const entries = await fs.readdir(languageDir).catch((e) => {
+        throw new InvalidRuleSetError(`failed to read language directory: ${languageDir}`, [{ file: languageDir, problem: String(e) }]);
+    });
+    const configs = new Map();
+    const aliasIndex = new Map();
+    const extIndex = new Map();
+    const filenameIndex = new Map();
+    const problems = [];
+    for (const file of entries) {
+        if (!file.endsWith(".json"))
+            continue;
+        if (file.startsWith("_"))
+            continue; // skip _schema.json, _template.json
+        const full = path.join(languageDir, file);
+        let raw;
+        try {
+            raw = await fs.readFile(full, "utf8");
+        }
+        catch (e) {
+            problems.push({ file, problem: `read failed: ${String(e)}` });
+            continue;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch (e) {
+            problems.push({ file, problem: `invalid JSON: ${String(e)}` });
+            continue;
+        }
+        const cfg = parsed;
+        if (typeof cfg.id !== "string") {
+            problems.push({ file, problem: "missing string field: id" });
+            continue;
+        }
+        if (!Array.isArray(cfg.extensions)) {
+            problems.push({ file, problem: "missing array field: extensions" });
+            continue;
+        }
+        if (!Array.isArray(cfg.dynamic_exec_sinks)) {
+            problems.push({ file, problem: "missing array field: dynamic_exec_sinks" });
+            continue;
+        }
+        if (!Array.isArray(cfg.decoders)) {
+            problems.push({ file, problem: "missing array field: decoders" });
+            continue;
+        }
+        const config = cfg;
+        configs.set(config.id, config);
+        aliasIndex.set(config.id, config.id);
+        for (const alias of config.aliases ?? []) {
+            aliasIndex.set(alias, config.id);
+        }
+        for (const ext of config.extensions) {
+            extIndex.set(ext.toLowerCase(), config.id);
+        }
+        for (const fname of config.filenames ?? []) {
+            filenameIndex.set(fname, config.id);
+        }
+    }
+    if (problems.length > 0 && configs.size === 0) {
+        throw new InvalidRuleSetError(`no valid language configs in ${languageDir}`, problems);
+    }
+    return {
+        languages: () => Array.from(configs.keys()).sort(),
+        configFor: (id) => configs.get(aliasIndex.get(id) ?? id) ?? null,
+        detectLanguage: (p) => detectLanguage(p, extIndex, filenameIndex),
+        loadGrammar: async (id) => {
+            // Stub: detectors that depend on a live parser would override this via
+            // a host-supplied RuleSet. The bundled detectors don't need it.
+            return Object.freeze({ id, _internal: null });
+        },
+        version: () => "0.0.0-source", // placeholder; defaultRuleSet() supplies real CalVer
+    };
+}
+function detectLanguage(filePath, extIndex, filenameIndex) {
+    const norm = filePath.replace(/\\/g, "/");
+    const base = norm.slice(norm.lastIndexOf("/") + 1);
+    // Filename match first (Dockerfile, build.rs, package.json, setup.py, …)
+    const exact = filenameIndex.get(base);
+    if (exact)
+        return exact;
+    // Common manifests by basename when no language config claims them
+    if (base === "package.json")
+        return "json";
+    if (base === "Dockerfile" || base.startsWith("Dockerfile."))
+        return "dockerfile";
+    if (norm.includes("/.github/workflows/") && (base.endsWith(".yml") || base.endsWith(".yaml"))) {
+        return "yaml";
+    }
+    // Extension match
+    const lastDot = base.lastIndexOf(".");
+    if (lastDot >= 0) {
+        const ext = base.slice(lastDot).toLowerCase();
+        const id = extIndex.get(ext);
+        if (id)
+            return id;
+    }
+    return null;
+}
+// ─── Default rule set ──────────────────────────────────────────────────────
+//
+// The bundled @obfuscan/rules package is resolved via Node's module resolver.
+// We try several candidate locations in order so this works whether
+// @obfuscan/rules is installed via npm, linked, or bundled in a workspace.
+const RULES_VERSION_FALLBACK = "2026.04.0";
+const here = path.dirname(fileURLToPath(import.meta.url));
+let cachedDefault = null;
+export async function defaultRuleSet() {
+    if (cachedDefault)
+        return cachedDefault;
+    const candidates = await locateBundledRules();
+    for (const dir of candidates) {
+        try {
+            const rs = await loadRuleSet({ languageDir: dir });
+            const version = await readPackageVersion(path.dirname(dir)) ?? RULES_VERSION_FALLBACK;
+            cachedDefault = wrapWithVersion(rs, version);
+            return cachedDefault;
+        }
+        catch {
+            // try next candidate
+        }
+    }
+    // Last resort: an empty rule set so the engine still runs.
+    cachedDefault = emptyRuleSet();
+    return cachedDefault;
+}
+async function locateBundledRules() {
+    const candidates = [];
+    // 1. Sibling workspace package: ../rules/languages
+    candidates.push(path.resolve(here, "..", "..", "rules", "languages"));
+    // 2. Installed via npm: node_modules/@obfuscan/rules/languages
+    try {
+        const req = (await import("node:module")).createRequire(import.meta.url);
+        const pkgPath = req.resolve("@obfuscan/rules/package.json");
+        candidates.push(path.join(path.dirname(pkgPath), "languages"));
+    }
+    catch {
+        // not resolvable; skip
+    }
+    // 3. Env override
+    const envDir = process.env["OBFUSCAN_RULES_DIR"];
+    if (envDir)
+        candidates.unshift(envDir);
+    return candidates;
+}
+async function readPackageVersion(dir) {
+    try {
+        const raw = await fs.readFile(path.join(dir, "package.json"), "utf8");
+        const pkg = JSON.parse(raw);
+        return typeof pkg.version === "string" ? pkg.version : null;
+    }
+    catch {
+        return null;
+    }
+}
+function wrapWithVersion(rs, version) {
+    return {
+        languages: () => rs.languages(),
+        configFor: id => rs.configFor(id),
+        detectLanguage: p => rs.detectLanguage(p),
+        loadGrammar: id => rs.loadGrammar(id),
+        version: () => version,
+    };
+}
+function emptyRuleSet() {
+    return {
+        languages: () => [],
+        configFor: () => null,
+        detectLanguage: () => null,
+        loadGrammar: async (id) => Object.freeze({ id, _internal: null }),
+        version: () => RULES_VERSION_FALLBACK,
+    };
+}
+//# sourceMappingURL=rules.js.map

package/dist/rules.js.map

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

package/dist/scan.d.ts

@@ -0,0 +1,26 @@
+/**
+ * scan() — the orchestrator.
+ *
+ * Pipeline:
+ *   1. Validate ScanInput (exactly one of diff/paths/dir).
+ *   2. Resolve target file list:
+ *        diff   → parseDiffToFiles → addedRanges per file
+ *        paths  → use as-is, no addedRanges
+ *        dir    → host enumerates; we just respect the resolver's nulls
+ *   3. For each file (concurrency-limited):
+ *        a. Resolve content via fileResolver (catch errors; log+skip)
+ *        b. Build FileContext (path, source, languageId, config, addedRanges)
+ *        c. For each enabled detector where applies(ctx) is true:
+ *             - run() with per-file timeout + try/catch
+ *             - collect findings
+ *        d. Apply diff-range filter (drop findings outside addedRanges)
+ *        e. Apply in-source disable directives
+ *        f. Apply allowlist (paths + snippets)
+ *        g. Apply minSeverity
+ *        h. Truncate snippets to 200 chars defensively
+ *   4. Sort findings by (severity desc, score desc, file asc, line asc).
+ *   5. Return ScanResult.
+ */
+import type { ScanInput, ScanOptions, ScanResult } from "./types.js";
+export declare function scan(input: ScanInput, options: ScanOptions): Promise<ScanResult>;
+//# sourceMappingURL=scan.d.ts.map

package/dist/scan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan.d.ts","sourceRoot":"","sources":["../src/scan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAIV,SAAS,EACT,WAAW,EAEX,UAAU,EAIX,MAAM,YAAY,CAAC;AAoBpB,wBAAsB,IAAI,CACxB,KAAK,EAAE,SAAS,EAChB,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC,UAAU,CAAC,CA4KrB"}