@backthread/extractor 0.1.0

package/dist/infra/walk.js

@@ -0,0 +1,85 @@
+// the shared bounded repo-walker for infra adapters.
+//
+// Every adapter (cloudflare, supabase, terraform, vercel, fly, render,
+// railway, aws, gcp, azure, opentofu, pulumi) used to re-implement the same
+// `SKIP_DIRS` / `MAX_DEPTH` / `listDir` / recursive `walk` machinery — twelve
+// near-identical copies (OpenTofu was a verbatim copy-paste of terraform.ts).
+// This is the one walk: a depth-bounded, skip-dir-pruned, error-tolerant
+// directory traversal that calls `onFile` for every file it reaches.
+//
+// The walk machinery is shared; the *policy* (which dirs to skip, how deep to
+// go, which files to keep) stays with each adapter as call-site options, so
+// migrating to this helper is a pure refactor with no behavior change — each
+// adapter passes the exact `skipDirs`/`maxDepth` it always used.
+import { readdirSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * The skip-set shared by the majority of adapters (cloudflare, supabase, fly,
+ * render). Adapters needing provider-specific extras (terraform → `.terraform`,
+ * vercel → `.vercel`/`out`, pulumi → `.pulumi`, railway → `.nixpacks`, the
+ * cloud adapters → `__pycache__`/`.venv`/`vendor`) pass their own `skipDirs`.
+ */
+export const DEFAULT_SKIP_DIRS = [
+    'node_modules',
+    '.git',
+    'dist',
+    '.wrangler',
+    '.next',
+    'build',
+    'coverage',
+];
+/** Default recursion bound — deep enough for monorepo nesting, cheap enough to stay bounded. */
+const DEFAULT_MAX_DEPTH = 8;
+/**
+ * Walk `repoDir` depth-first, pruning `skipDirs` and stopping past `maxDepth`,
+ * invoking `onFile(absPath, dirent)` for each file. Unreadable directories are
+ * skipped silently (a permission error on one subtree never aborts the walk).
+ */
+export function walkRepo(repoDir, opts) {
+    const skip = new Set(opts.skipDirs ?? DEFAULT_SKIP_DIRS);
+    const maxDepth = opts.maxDepth ?? DEFAULT_MAX_DEPTH;
+    const walk = (dir, depth) => {
+        if (depth > maxDepth)
+            return;
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            const abs = join(dir, e.name);
+            if (e.isDirectory()) {
+                if (!skip.has(e.name))
+                    walk(abs, depth + 1);
+            }
+            else {
+                opts.onFile(abs, e);
+            }
+        }
+    };
+    walk(repoDir, 0);
+}
+/**
+ * Convenience over {@link walkRepo} for the common "collect every file matching
+ * a predicate" case. Returns absolute paths sorted lexicographically (the same
+ * `found.sort()` every adapter applied for deterministic output).
+ *
+ * `match` takes `(absPath, dirent)` — the SAME argument order as
+ * {@link WalkRepoOptions.onFile} — so a predicate can move between the two
+ * helpers without silently rebinding its parameters.
+ */
+export function findFiles(repoDir, match, opts) {
+    const found = [];
+    walkRepo(repoDir, {
+        skipDirs: opts?.skipDirs,
+        maxDepth: opts?.maxDepth,
+        onFile: (abs, e) => {
+            if (match(abs, e))
+                found.push(abs);
+        },
+    });
+    return found.sort();
+}
+//# sourceMappingURL=walk.js.map

package/dist/infra/walk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"walk.js","sourceRoot":"","sources":["../../src/infra/walk.ts"],"names":[],"mappings":"AAAA,qDAAqD;AACrD,EAAE;AACF,uEAAuE;AACvE,4EAA4E;AAC5E,8EAA8E;AAC9E,8EAA8E;AAC9E,yEAAyE;AACzE,qEAAqE;AACrE,EAAE;AACF,8EAA8E;AAC9E,4EAA4E;AAC5E,6EAA6E;AAC7E,iEAAiE;AAEjE,OAAO,EAAE,WAAW,EAAe,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAsB;IAClD,cAAc;IACd,MAAM;IACN,MAAM;IACN,WAAW;IACX,OAAO;IACP,OAAO;IACP,UAAU;CACX,CAAC;AAEF,gGAAgG;AAChG,MAAM,iBAAiB,GAAG,CAAC,CAAC;AAW5B;;;;GAIG;AACH,MAAM,UAAU,QAAQ,CAAC,OAAe,EAAE,IAAqB;IAC7D,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,QAAQ,IAAI,iBAAiB,CAAC,CAAC;IACzD,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,iBAAiB,CAAC;IACpD,MAAM,IAAI,GAAG,CAAC,GAAW,EAAE,KAAa,EAAE,EAAE;QAC1C,IAAI,KAAK,GAAG,QAAQ;YAAE,OAAO;QAC7B,IAAI,OAAiB,CAAC;QACtB,IAAI,CAAC;YACH,OAAO,GAAG,WAAW,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;QACtD,CAAC;QAAC,MAAM,CAAC;YACP,OAAO;QACT,CAAC;QACD,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;YACxB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;YAC9B,IAAI,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC;gBACpB,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;oBAAE,IAAI,CAAC,GAAG,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;YAC9C,CAAC;iBAAM,CAAC;gBACN,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;YACtB,CAAC;QACH,CAAC;IACH,CAAC,CAAC;IACF,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;AACnB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,SAAS,CACvB,OAAe,EACf,KAAmD,EACnD,IAAyD;IAEzD,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE;QAChB,QAAQ,EAAE,IAAI,EAAE,QAAQ;QACxB,QAAQ,EAAE,IAAI,EAAE,QAAQ;QACxB,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE;YACjB,IAAI,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC;gBAAE,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACrC,CAAC;KACF,CAAC,CAAC;IACH,OAAO,KAAK,CAAC,IAAI,EAAE,CAAC;AACtB,CAAC"}

package/dist/safety.d.ts

@@ -0,0 +1,13 @@
+export interface SafetyBudget {
+    maxFileBytes: number;
+    maxTotalBytes: number;
+    maxFiles: number;
+}
+export declare const DEFAULT_BUDGET: SafetyBudget;
+/**
+ * Walk the clone, enforcing the budget. Throws on the first violation. Symlinks
+ * are never followed and any symlink resolving OUTSIDE the clone root is
+ * rejected (path-traversal guard).
+ */
+export declare function enforceSourceBudget(root: string, budget?: SafetyBudget): void;
+//# sourceMappingURL=safety.d.ts.map

package/dist/safety.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safety.d.ts","sourceRoot":"","sources":["../src/safety.ts"],"names":[],"mappings":"AAWA,MAAM,WAAW,YAAY;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,eAAO,MAAM,cAAc,EAAE,YAI5B,CAAC;AAIF;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,GAAE,YAA6B,GAAG,IAAI,CA4C7F"}

package/dist/safety.js

@@ -0,0 +1,67 @@
+// Source-tree safety budget (/370) — runs inside the ephemeral container
+// before extraction. The extractor only READS source (ts-morph, install-free —
+// it never eval/requires repo content), so the threat model is DoS/resource
+// abuse (zip-bombs, giant files, symlink escapes), not RCE. This caps that.
+//
+// CPU/mem/disk caps come from the container instance type; wall-time from the
+// exec timeout. This guard covers the content budgets the instance limits don't.
+import { readdirSync, lstatSync, realpathSync } from 'node:fs';
+import { join, resolve, sep } from 'node:path';
+export const DEFAULT_BUDGET = {
+    maxFileBytes: 8 * 1024 * 1024, // 8 MB — a source file over this is pathological
+    maxTotalBytes: 512 * 1024 * 1024, // 512 MB total scanned
+    maxFiles: 50_000,
+};
+const SKIP_DIRS = new Set(['.git', 'node_modules', 'dist', 'build', '.next', 'coverage']);
+/**
+ * Walk the clone, enforcing the budget. Throws on the first violation. Symlinks
+ * are never followed and any symlink resolving OUTSIDE the clone root is
+ * rejected (path-traversal guard).
+ */
+export function enforceSourceBudget(root, budget = DEFAULT_BUDGET) {
+    const rootReal = realpathSync(root);
+    let totalBytes = 0;
+    let fileCount = 0;
+    const walk = (dir) => {
+        for (const name of readdirSync(dir)) {
+            const p = join(dir, name);
+            const st = lstatSync(p); // lstat: do NOT follow symlinks
+            if (st.isSymbolicLink()) {
+                // Reject any symlink that escapes the clone root.
+                let target;
+                try {
+                    target = realpathSync(p);
+                }
+                catch {
+                    continue; // dangling symlink — ignore
+                }
+                // Prefix match with the explicit separator — `target.startsWith(rootReal)`
+                // alone would let `/tmp/clone-12345-evil` pass as if inside `/tmp/clone-12345`.
+                if (target !== rootReal && !target.startsWith(rootReal + sep)) {
+                    throw new Error(`safety: symlink escapes clone root: ${p}`);
+                }
+                continue; // don't traverse into symlinks
+            }
+            if (st.isDirectory()) {
+                if (SKIP_DIRS.has(name))
+                    continue;
+                walk(p);
+            }
+            else if (st.isFile()) {
+                if (st.size > budget.maxFileBytes) {
+                    throw new Error(`safety: file exceeds ${budget.maxFileBytes} bytes: ${p}`);
+                }
+                totalBytes += st.size;
+                fileCount += 1;
+                if (totalBytes > budget.maxTotalBytes) {
+                    throw new Error(`safety: tree exceeds ${budget.maxTotalBytes} bytes (zip-bomb guard)`);
+                }
+                if (fileCount > budget.maxFiles) {
+                    throw new Error(`safety: more than ${budget.maxFiles} files`);
+                }
+            }
+        }
+    };
+    walk(resolve(root));
+}
+//# sourceMappingURL=safety.js.map

package/dist/safety.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,47 @@
+export type ShortSha = string & {
+    readonly __brand: 'ShortSha';
+};
+export type ModuleId = string & {
+    readonly __brand: 'ModuleId';
+};
+export declare const ShortSha: (s: string) => ShortSha;
+export declare const ModuleId: (s: string) => ModuleId;
+export type ModuleKind = 'frontend' | 'service' | 'gateway' | 'job' | 'worker' | 'static-site' | 'queue' | 'container' | 'datastore' | 'external-api' | 'secret-store' | 'cdn' | 'external';
+export declare const INFRA_MODULE_KINDS: readonly ["worker", "static-site", "queue", "container", "datastore", "external-api", "secret-store", "cdn"];
+export type InfraModuleKind = (typeof INFRA_MODULE_KINDS)[number];
+export declare const MODULE_KINDS: readonly ["frontend", "service", "gateway", "job", "worker", "static-site", "queue", "container", "datastore", "external-api", "secret-store", "cdn"];
+/**
+ * Producer-side: returns a strict, non-deprecated ModuleKind or throws.
+ * The deprecated `external` alias is REJECTED — producers must emit
+ * `external-api`. Readers tolerate legacy `external`; producers must not
+ * regenerate it, so we fail loud at the producer boundary.
+ */
+export declare function parseModuleKind(candidate: string): ModuleKind;
+export type NodeProvenance = 'declared' | 'inferred' | 'llm-classified';
+export type PackageRole = 'app' | 'lib' | 'tooling';
+export declare const EDGE_KINDS: readonly ["calls", "reads", "writes", "publishes", "subscribes", "webhook-from", "deploys-to", "stores-in"];
+export type EdgeKind = (typeof EDGE_KINDS)[number];
+export declare const FORBIDDEN_EDGE_KINDS: readonly ["imports", "depends-on", "uses"];
+export type ForbiddenEdgeKind = (typeof FORBIDDEN_EDGE_KINDS)[number];
+/**
+ * Producer-side: returns a strict EdgeKind or throws. Use this at the extractor
+ * / enrichment / persist boundary. A throw means the classifier produced a
+ * substrate-only label that should never have left its layer — fix the
+ * classifier, not the type.
+ */
+export declare function parseEdgeKind(candidate: string): EdgeKind;
+/**
+ * Reader-side: tolerant coercion of legacy / unknown values onto the closest
+ * 8-verb equivalent so old snapshots still render. New producers must NEVER
+ * call this — they call parseEdgeKind.
+ * - 'webhook'                          → 'webhook-from'
+ * - 'imports' | 'uses' | 'depends-on'  → 'calls' (most-general structural verb)
+ * - anything else not in the 8 verbs   → 'calls'
+ */
+export declare function coerceEdgeKind(candidate: string): EdgeKind;
+export interface Edge {
+    source: ModuleId;
+    target: ModuleId;
+    kind: EdgeKind;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAeA,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAA;CAAE,CAAC;AACjE,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAA;CAAE,CAAC;AAEjE,eAAO,MAAM,QAAQ,GAAI,GAAG,MAAM,KAAG,QAAyB,CAAC;AAC/D,eAAO,MAAM,QAAQ,GAAI,GAAG,MAAM,KAAG,QAAyB,CAAC;AAkB/D,MAAM,MAAM,UAAU,GAClB,UAAU,GACV,SAAS,GACT,SAAS,GACT,KAAK,GACL,QAAQ,GACR,aAAa,GACb,OAAO,GACP,WAAW,GACX,WAAW,GACX,cAAc,GACd,cAAc,GACd,KAAK,GACL,UAAU,CAAC;AAGf,eAAO,MAAM,kBAAkB,8GASrB,CAAC;AACX,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAKlE,eAAO,MAAM,YAAY,uJAaf,CAAC;AAEX;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,UAAU,CAa7D;AAKD,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG,UAAU,GAAG,gBAAgB,CAAC;AAQxE,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,KAAK,GAAG,SAAS,CAAC;AAYpD,eAAO,MAAM,UAAU,6GASb,CAAC;AACX,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;AAGnD,eAAO,MAAM,oBAAoB,4CAA6C,CAAC;AAC/E,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEtE;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,QAAQ,CAazD;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,QAAQ,CAI1D;AAED,MAAM,WAAW,IAAI;IACnB,MAAM,EAAE,QAAQ,CAAC;IACjB,MAAM,EAAE,QAAQ,CAAC;IACjB,IAAI,EAAE,QAAQ,CAAC;CAChB"}

package/dist/types.js

@@ -0,0 +1,111 @@
+// Structural type vocabulary for the deterministic extractor.
+//
+// This is the shared type substrate the AST → cluster → framework → infra
+// pipeline enforces: the 8-verb edge taxonomy, the 4 app-role + 8 infra Module
+// kinds, and the branded primitives. The type system is law — a producer that
+// emits an out-of-enum value is a bug in the classifier, never a reason to
+// widen the enum (fail loud at the boundary instead of landing low-quality data).
+//
+// These definitions mirror the host application's domain types exactly (same
+// literals, same brand strings) so a graph produced here is structurally
+// interchangeable with one produced server-side. A drift-guard test keeps the
+// two in lockstep.
+export const ShortSha = (s) => s;
+export const ModuleId = (s) => s;
+// The 8 infra-altitude kinds, enumerated for runtime guards.
+export const INFRA_MODULE_KINDS = [
+    'worker',
+    'static-site',
+    'queue',
+    'container',
+    'datastore',
+    'external-api',
+    'secret-store',
+    'cdn',
+];
+// Every NON-deprecated kind a producer may emit — ModuleKind minus the legacy
+// `external` alias. Producer-side guard (parseModuleKind) validates against this;
+// readers stay tolerant of `external` in already-seeded blobs.
+export const MODULE_KINDS = [
+    'frontend',
+    'service',
+    'gateway',
+    'job',
+    'worker',
+    'static-site',
+    'queue',
+    'container',
+    'datastore',
+    'external-api',
+    'secret-store',
+    'cdn',
+];
+/**
+ * Producer-side: returns a strict, non-deprecated ModuleKind or throws.
+ * The deprecated `external` alias is REJECTED — producers must emit
+ * `external-api`. Readers tolerate legacy `external`; producers must not
+ * regenerate it, so we fail loud at the producer boundary.
+ */
+export function parseModuleKind(candidate) {
+    if (candidate === 'external') {
+        throw new Error(`deprecated module kind 'external' — emit 'external-api' instead. ` +
+            `Readers tolerate legacy 'external'; producers must not regenerate it.`);
+    }
+    if (!MODULE_KINDS.includes(candidate)) {
+        throw new Error(`unknown module kind '${candidate}'. Use one of: ${MODULE_KINDS.join(', ')}.`);
+    }
+    return candidate;
+}
+// --- Edge kind: the 8-verb taxonomy -----------------------------------------
+// Every edge is a verb with a direction. Substrate-only labels
+// (`imports / depends-on / uses`) are refused at the user-facing boundary.
+//
+// Producer-side discipline: `parseEdgeKind` returns an EdgeKind or throws — a
+// classifier that emits `imports` fails loudly at the persist boundary.
+// Reader-side discipline: `coerceEdgeKind` is tolerant; it maps legacy/unknown
+// values onto an 8-verb fallback so old data still renders. Producers must
+// NEVER call coerce — it exists for the renderer only.
+export const EDGE_KINDS = [
+    'calls',
+    'reads',
+    'writes',
+    'publishes',
+    'subscribes',
+    'webhook-from',
+    'deploys-to',
+    'stores-in',
+];
+// Substrate-only edge labels — refused at the user-facing boundary.
+export const FORBIDDEN_EDGE_KINDS = ['imports', 'depends-on', 'uses'];
+/**
+ * Producer-side: returns a strict EdgeKind or throws. Use this at the extractor
+ * / enrichment / persist boundary. A throw means the classifier produced a
+ * substrate-only label that should never have left its layer — fix the
+ * classifier, not the type.
+ */
+export function parseEdgeKind(candidate) {
+    if (FORBIDDEN_EDGE_KINDS.includes(candidate)) {
+        throw new Error(`forbidden edge kind '${candidate}' — substrate-only, never user-facing. ` +
+            `Use one of: ${EDGE_KINDS.join(', ')}.`);
+    }
+    if (!EDGE_KINDS.includes(candidate)) {
+        throw new Error(`unknown edge kind '${candidate}'. Use one of: ${EDGE_KINDS.join(', ')}.`);
+    }
+    return candidate;
+}
+/**
+ * Reader-side: tolerant coercion of legacy / unknown values onto the closest
+ * 8-verb equivalent so old snapshots still render. New producers must NEVER
+ * call this — they call parseEdgeKind.
+ * - 'webhook'                          → 'webhook-from'
+ * - 'imports' | 'uses' | 'depends-on'  → 'calls' (most-general structural verb)
+ * - anything else not in the 8 verbs   → 'calls'
+ */
+export function coerceEdgeKind(candidate) {
+    if (EDGE_KINDS.includes(candidate))
+        return candidate;
+    if (candidate === 'webhook')
+        return 'webhook-from';
+    return 'calls';
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,8DAA8D;AAC9D,EAAE;AACF,0EAA0E;AAC1E,+EAA+E;AAC/E,8EAA8E;AAC9E,2EAA2E;AAC3E,kFAAkF;AAClF,EAAE;AACF,6EAA6E;AAC7E,yEAAyE;AACzE,8EAA8E;AAC9E,mBAAmB;AAOnB,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,CAAS,EAAY,EAAE,CAAC,CAAa,CAAC;AAC/D,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,CAAS,EAAY,EAAE,CAAC,CAAa,CAAC;AAiC/D,6DAA6D;AAC7D,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,QAAQ;IACR,aAAa;IACb,OAAO;IACP,WAAW;IACX,WAAW;IACX,cAAc;IACd,cAAc;IACd,KAAK;CACG,CAAC;AAGX,8EAA8E;AAC9E,kFAAkF;AAClF,+DAA+D;AAC/D,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,UAAU;IACV,SAAS;IACT,SAAS;IACT,KAAK;IACL,QAAQ;IACR,aAAa;IACb,OAAO;IACP,WAAW;IACX,WAAW;IACX,cAAc;IACd,cAAc;IACd,KAAK;CACG,CAAC;AAEX;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,SAAiB;IAC/C,IAAI,SAAS,KAAK,UAAU,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CACb,mEAAmE;YACjE,uEAAuE,CAC1E,CAAC;IACJ,CAAC;IACD,IAAI,CAAE,YAAkC,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;QAC7D,MAAM,IAAI,KAAK,CACb,wBAAwB,SAAS,kBAAkB,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAC9E,CAAC;IACJ,CAAC;IACD,OAAO,SAAuB,CAAC;AACjC,CAAC;AAeD,+EAA+E;AAC/E,+DAA+D;AAC/D,2EAA2E;AAC3E,EAAE;AACF,8EAA8E;AAC9E,wEAAwE;AACxE,+EAA+E;AAC/E,2EAA2E;AAC3E,uDAAuD;AAEvD,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,OAAO;IACP,OAAO;IACP,QAAQ;IACR,WAAW;IACX,YAAY;IACZ,cAAc;IACd,YAAY;IACZ,WAAW;CACH,CAAC;AAGX,oEAAoE;AACpE,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,SAAS,EAAE,YAAY,EAAE,MAAM,CAAU,CAAC;AAG/E;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,SAAiB;IAC7C,IAAK,oBAA0C,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;QACpE,MAAM,IAAI,KAAK,CACb,wBAAwB,SAAS,yCAAyC;YACxE,eAAe,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAC1C,CAAC;IACJ,CAAC;IACD,IAAI,CAAE,UAAgC,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;QAC3D,MAAM,IAAI,KAAK,CACb,sBAAsB,SAAS,kBAAkB,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAC1E,CAAC;IACJ,CAAC;IACD,OAAO,SAAqB,CAAC;AAC/B,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAC,SAAiB;IAC9C,IAAK,UAAgC,CAAC,QAAQ,CAAC,SAAS,CAAC;QAAE,OAAO,SAAqB,CAAC;IACxF,IAAI,SAAS,KAAK,SAAS;QAAE,OAAO,cAAc,CAAC;IACnD,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+export declare const EXTRACTOR_PACKAGE_VERSION: string;
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAwCA,eAAO,MAAM,yBAAyB,EAAE,MAA6B,CAAC"}

package/dist/version.js

@@ -0,0 +1,35 @@
+// The published package version, read from package.json at runtime. This is the
+// SINGLE source of truth for the extractor version that both the CLI (local
+// structure extraction) and the hosted container stamp on their output, so a
+// version mismatch between the two — which would mean subtly different graphs —
+// is detectable (the container↔CLI version-lockstep guard).
+//
+// NOTE: distinct from `EXTRACTOR_VERSION` in graph/file-graph.ts, which is the
+// incremental-cache SCHEMA version (bumped to invalidate stale blob caches).
+// This constant is the npm package version.
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+function readPackageVersion() {
+    // Preferred: a build-time injected version (survives bundling).
+    try {
+        if (typeof __EXTRACTOR_VERSION__ === 'string' && __EXTRACTOR_VERSION__) {
+            return __EXTRACTOR_VERSION__;
+        }
+    }
+    catch {
+        /* not injected — fall through to the unbundled fs read */
+    }
+    // Fallback: read package.json (works when installed/unbundled).
+    try {
+        // dev: src/version.ts → ../package.json; built: dist/version.js → ../package.json.
+        const pkgPath = join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json');
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+        return pkg.version ?? '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+export const EXTRACTOR_PACKAGE_VERSION = readPackageVersion();
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,4EAA4E;AAC5E,6EAA6E;AAC7E,gFAAgF;AAChF,4DAA4D;AAC5D,EAAE;AACF,+EAA+E;AAC/E,6EAA6E;AAC7E,4CAA4C;AAE5C,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAQ1C,SAAS,kBAAkB;IACzB,gEAAgE;IAChE,IAAI,CAAC;QACH,IAAI,OAAO,qBAAqB,KAAK,QAAQ,IAAI,qBAAqB,EAAE,CAAC;YACvE,OAAO,qBAAqB,CAAC;QAC/B,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,0DAA0D;IAC5D,CAAC;IACD,gEAAgE;IAChE,IAAI,CAAC;QACH,mFAAmF;QACnF,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,cAAc,CAAC,CAAC;QACpF,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CAAyB,CAAC;QAC9E,OAAO,GAAG,CAAC,OAAO,IAAI,OAAO,CAAC;IAChC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,OAAO,CAAC;IACjB,CAAC;AACH,CAAC;AAED,MAAM,CAAC,MAAM,yBAAyB,GAAW,kBAAkB,EAAE,CAAC"}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@backthread/extractor",
+  "version": "0.1.0",
+  "description": "Deterministic, install-free structural extraction for TypeScript and Python codebases — AST → communities → god-nodes → framework & infra adapters, zero LLM/DB/network.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Backthread",
+  "homepage": "https://github.com/backthread/backthread/tree/main/packages/extractor#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/backthread/backthread.git",
+    "directory": "packages/extractor"
+  },
+  "bugs": "https://github.com/backthread/backthread/issues",
+  "keywords": [
+    "ast",
+    "code-graph",
+    "static-analysis",
+    "typescript",
+    "python",
+    "louvain",
+    "architecture"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22.18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "npm run clean && tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json --noEmit",
+    "test": "node --import tsx --test --test-force-exit \"src/**/*.test.ts\" && npm run build",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "@zzzen/pyright-internal": "1.2.0-dev.20251207",
+    "graphology": "^0.25.4",
+    "graphology-communities-louvain": "^2.0.2",
+    "smol-toml": "^1.7.0",
+    "ts-morph": "^23.0.0",
+    "yaml": "^2.9.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "expect": "^29.7.0",
+    "jest-mock": "^29.7.0",
+    "tsx": "^4.22.3",
+    "typescript": "^5.6.0"
+  }
+}