@opencodehub/ingestion 0.1.0

package/dist/pipeline/phases/profile.js

@@ -0,0 +1,91 @@
+/**
+ * Profile phase — single-pass repo profiling.
+ *
+ * Consumes the scan phase output and emits one `ProjectProfile` node per
+ * repo with six sorted arrays:
+ *   - languages      — file-count-threshold filtered, sorted by count desc
+ *   - frameworks     — evidence-based (file markers OR manifest deps)
+ *   - iacTypes       — terraform / docker / kubernetes / cloudformation / …
+ *   - apiContracts   — openapi / graphql / grpc / asyncapi
+ *   - manifests      — linguist-style priority cascade per ecosystem
+ *   - srcDirs        — top-level source directories (>10 code files)
+ *
+ * The phase runs after `scan`, has no outbound deps, and is a pure leaf:
+ * downstream phases (scanners gated on ProjectProfile) will read the
+ * profile node from the graph, not from the phase output.
+ *
+ * Determinism: every detector returns a sorted array; the profile node is a
+ * singleton per repo, so its id uses a constant qualified name ("repo")
+ * rather than a hash of the absolute path. This keeps the node id stable
+ * across checkouts of the same repo on different paths / machines, which is
+ * required for the graphHash determinism gate (two clones of the same
+ * commit must produce byte-identical graphs). Two runs of the same repo at
+ * the same commit produce byte-identical profile nodes.
+ */
+import { makeNodeId } from "@opencodehub/core-types";
+import { detectFrameworksDetailed, detectManifests } from "@opencodehub/frameworks";
+import { detectApiContracts } from "../profile-detectors/api-contracts.js";
+import { detectIaCTypes } from "../profile-detectors/iac.js";
+import { detectLanguages } from "../profile-detectors/languages.js";
+import { detectSrcDirs } from "../profile-detectors/src-dirs.js";
+import { SCAN_PHASE_NAME } from "./scan.js";
+export const PROFILE_PHASE_NAME = "profile";
+export const profilePhase = {
+    name: PROFILE_PHASE_NAME,
+    deps: [SCAN_PHASE_NAME],
+    async run(ctx, deps) {
+        const scan = deps.get(SCAN_PHASE_NAME);
+        if (scan === undefined) {
+            throw new Error("profile: scan output missing from dependency map");
+        }
+        return runProfile(ctx, scan);
+    },
+};
+async function runProfile(ctx, scan) {
+    const files = scan.files;
+    // Manifests must be computed first: framework detection consults them to
+    // know which manifest files exist before probing for declared deps.
+    const manifests = detectManifests(files);
+    const languages = detectLanguages(files);
+    const [iacTypes, apiContracts, frameworksDetected] = await Promise.all([
+        detectIaCTypes(ctx.repoPath, files),
+        detectApiContracts(ctx.repoPath, files),
+        detectFrameworksDetailed({
+            repoRoot: ctx.repoPath,
+            files,
+            manifests,
+            detectedLanguages: languages,
+        }),
+    ]);
+    const srcDirs = detectSrcDirs(files);
+    // Backward-compatible flat list — the `name` of each detection in sorted
+    // order. The structured list is the source of truth; the flat list is a
+    // projection kept for v1.0 consumers.
+    const frameworks = frameworksDetected.map((d) => d.name);
+    // Singleton per repo: use a constant qualified name so the id is stable
+    // across clones of the same repo on different absolute paths. The graph
+    // is already scoped to one repo, so uniqueness within the graph is
+    // preserved without encoding the path. See the module JSDoc for the
+    // determinism rationale.
+    const id = makeNodeId("ProjectProfile", "", "repo");
+    const node = {
+        id,
+        kind: "ProjectProfile",
+        name: "project-profile",
+        filePath: "",
+        languages,
+        frameworks,
+        frameworksDetected,
+        iacTypes,
+        apiContracts,
+        manifests,
+        srcDirs,
+    };
+    ctx.graph.addNode(node);
+    return {
+        profileEmitted: true,
+        languagesDetected: languages.length,
+        frameworksDetected: frameworks.length,
+    };
+}
+//# sourceMappingURL=profile.js.map

package/dist/pipeline/phases/profile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"profile.js","sourceRoot":"","sources":["../../../src/pipeline/phases/profile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,EAAE,wBAAwB,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AACpF,OAAO,EAAE,kBAAkB,EAAE,MAAM,uCAAuC,CAAC;AAC3E,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AACpE,OAAO,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAC;AAEjE,OAAO,EAAE,eAAe,EAAmB,MAAM,WAAW,CAAC;AAE7D,MAAM,CAAC,MAAM,kBAAkB,GAAG,SAAkB,CAAC;AAQrD,MAAM,CAAC,MAAM,YAAY,GAAiC;IACxD,IAAI,EAAE,kBAAkB;IACxB,IAAI,EAAE,CAAC,eAAe,CAAC;IACvB,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI;QACjB,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,eAAe,CAA2B,CAAC;QACjE,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CAAC,kDAAkD,CAAC,CAAC;QACtE,CAAC;QACD,OAAO,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IAC/B,CAAC;CACF,CAAC;AAEF,KAAK,UAAU,UAAU,CAAC,GAAoB,EAAE,IAAgB;IAC9D,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;IAEzB,yEAAyE;IACzE,oEAAoE;IACpE,MAAM,SAAS,GAAG,eAAe,CAAC,KAAK,CAAC,CAAC;IACzC,MAAM,SAAS,GAAG,eAAe,CAAC,KAAK,CAAC,CAAC;IACzC,MAAM,CAAC,QAAQ,EAAE,YAAY,EAAE,kBAAkB,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QACrE,cAAc,CAAC,GAAG,CAAC,QAAQ,EAAE,KAAK,CAAC;QACnC,kBAAkB,CAAC,GAAG,CAAC,QAAQ,EAAE,KAAK,CAAC;QACvC,wBAAwB,CAAC;YACvB,QAAQ,EAAE,GAAG,CAAC,QAAQ;YACtB,KAAK;YACL,SAAS;YACT,iBAAiB,EAAE,SAAS;SAC7B,CAAC;KACH,CAAC,CAAC;IACH,MAAM,OAAO,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IACrC,yEAAyE;IACzE,wEAAwE;IACxE,sCAAsC;IACtC,MAAM,UAAU,GAAsB,kBAAkB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IAE5E,wEAAwE;IACxE,wEAAwE;IACxE,mEAAmE;IACnE,oEAAoE;IACpE,yBAAyB;IACzB,MAAM,EAAE,GAAG,UAAU,CAAC,gBAAgB,EAAE,EAAE,EAAE,MAAM,CAAC,CAAC;IAEpD,MAAM,IAAI,GAAuB;QAC/B,EAAE;QACF,IAAI,EAAE,gBAAgB;QACtB,IAAI,EAAE,iBAAiB;QACvB,QAAQ,EAAE,EAAE;QACZ,SAAS;QACT,UAAU;QACV,kBAAkB;QAClB,QAAQ;QACR,YAAY;QACZ,SAAS;QACT,OAAO;KACR,CAAC;IACF,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAExB,OAAO;QACL,cAAc,EAAE,IAAI;QACpB,iBAAiB,EAAE,SAAS,CAAC,MAAM;QACnC,kBAAkB,EAAE,UAAU,CAAC,MAAM;KACtC,CAAC;AACJ,CAAC"}

package/dist/pipeline/phases/repo-node.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Repo-node phase — emits one first-class `RepoNode` per graph.
+ *
+ * Runs after the `profile` phase so we can inherit `ProjectProfileNode.languages`
+ * when deriving `languageStats`. Probes three git endpoints via
+ * `git -C <path> ...` on the repository root:
+ *   - `config --get remote.origin.url` → `originUrl` + `repoUri`
+ *   - `symbolic-ref --short refs/remotes/origin/HEAD` → `defaultBranch`
+ *   - `rev-parse HEAD` → `commitSha`
+ *
+ * All probes fail-safe: when git is absent, the repo is not a git working
+ * tree, or the command exits non-zero, the phase returns a deterministic
+ * `local:<sha256(abs-path)[:12]>` handle. The phase never throws on git
+ * failures — it downgrades to the local-only shape.
+ *
+ * `indexTime` is populated inside this phase but is explicitly kept out of
+ * graphHash determinism inputs — graphHash hashes the node verbatim, so
+ * callers that need fixture-stable hashes must freeze `indexTime` at the
+ * fixture level or omit the phase from the determinism gate.
+ */
+import { type RepoNode } from "@opencodehub/core-types";
+import type { PipelinePhase } from "../types.js";
+export declare const REPO_NODE_PHASE_NAME = "repo-node";
+/** Options input to a direct `runRepoNodePhase` call (outside the pipeline DAG). */
+export interface RepoNodePhaseInput {
+    readonly repoPath: string;
+    /** Federation-group tag. `null` when the repo isn't in a group. */
+    readonly group?: string | null;
+    /** Visibility for MCP gating. Defaults to `private`. */
+    readonly visibility?: "private" | "internal" | "public";
+    /** Name+version of the indexer, per SCIP `Metadata.toolInfo`. */
+    readonly indexer: string;
+    /**
+     * Pre-detected language list from the `profile` phase. Used to derive
+     * `languageStats` when available. Absent → `languageStats` is `{}`.
+     */
+    readonly detectedLanguages?: readonly string[];
+    /**
+     * Injected clock. Defaults to `new Date().toISOString()` but tests and
+     * reproducible-build paths override to freeze the timestamp.
+     */
+    readonly now?: () => string;
+    /**
+     * Injected git probe. Defaults to spawning `git -C <path> <args>` via
+     * execFile. Tests override this to simulate HTTPS / SSH / no-remote repos.
+     */
+    readonly gitProbe?: GitProbe;
+}
+export interface RepoNodePhaseOutput {
+    readonly repoNode: RepoNode;
+}
+/**
+ * Functional interface for the three git probes the phase issues. Each
+ * returns the probe's stdout (trimmed) or `null` when git failed or exited
+ * non-zero. `null` is modelled with `undefined` so `exactOptionalPropertyTypes`
+ * compile cleanly when the phase input omits `gitProbe` entirely.
+ */
+export interface GitProbe {
+    /** `git -C <repoPath> config --get remote.origin.url`. */
+    originUrl(repoPath: string): Promise<string | null>;
+    /** `git -C <repoPath> symbolic-ref --short refs/remotes/origin/HEAD`. */
+    defaultBranch(repoPath: string): Promise<string | null>;
+    /** `git -C <repoPath> rev-parse HEAD`. */
+    commitSha(repoPath: string): Promise<string | null>;
+}
+/**
+ * Default git probe — runs `git` as a subprocess and swallows all errors to
+ * `null`. We check exit code only implicitly: `execFile` throws on non-zero,
+ * and the try/catch demotes that to `null`.
+ */
+export declare const defaultGitProbe: GitProbe;
+/**
+ * Normalise an arbitrary git remote URL into a Sourcegraph-style `host/path`
+ * handle. Handles HTTPS, SSH, and the "scp-like" SSH form git accepts by
+ * default (`git@host:path`). Trailing `.git` is always stripped.
+ *
+ * Examples:
+ *   https://github.com/org/repo.git           → github.com/org/repo
+ *   git@github.com:org/repo.git               → github.com/org/repo
+ *   ssh://git@gitlab.example.com/org/repo     → gitlab.example.com/org/repo
+ *   https://user:token@host.com/a/b           → host.com/a/b
+ *
+ * Returns `null` for unparseable inputs so the caller falls back to the
+ * `local:<hash>` form instead of inventing a URI.
+ */
+export declare function deriveRepoUri(originUrl: string): string | null;
+/** `local:<sha256(absolute-path)[:12]>` — fallback handle when no git remote exists. */
+export declare function deriveLocalRepoUri(absolutePath: string): string;
+/**
+ * Derive a sorted, fraction-summing language distribution from a list of
+ * detected languages. The simplest fair distribution (when upstream phases
+ * only surface a set, not counts) is uniform — `1 / N` per language.
+ *
+ * Keys are NOT sorted here; canonical JSON is applied at serialisation time
+ * (graphHash + storage adapters), so callers cannot accidentally poison byte
+ * stability by preserving insertion order.
+ */
+export declare function deriveLanguageStats(languages: readonly string[]): Readonly<Record<string, number>>;
+/**
+ * Core entry point — usable both inside the pipeline DAG (via `repoNodePhase`)
+ * and as a standalone function for callers that already hold a repo path and
+ * an indexer tag.
+ */
+export declare function runRepoNodePhase(input: RepoNodePhaseInput): Promise<RepoNodePhaseOutput>;
+/**
+ * Pipeline wrapper. Consumes the profile phase's detected languages (when
+ * present), emits one RepoNode, and pushes it into `ctx.graph`. The output
+ * map is a no-op hook — downstream phases that want the node should read it
+ * from the graph, mirroring the profile-phase contract.
+ */
+export declare const repoNodePhase: PipelinePhase<RepoNodePhaseOutput>;
+//# sourceMappingURL=repo-node.d.ts.map

package/dist/pipeline/phases/repo-node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repo-node.d.ts","sourceRoot":"","sources":["../../../src/pipeline/phases/repo-node.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAMH,OAAO,EAAc,KAAK,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AACpE,OAAO,KAAK,EAAmB,aAAa,EAAE,MAAM,aAAa,CAAC;AAGlE,eAAO,MAAM,oBAAoB,cAAc,CAAC;AAIhD,oFAAoF;AACpF,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,mEAAmE;IACnE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,wDAAwD;IACxD,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,GAAG,UAAU,GAAG,QAAQ,CAAC;IACxD,iEAAiE;IACjE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/C;;;OAGG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IAC5B;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC;CAC9B;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;CAC7B;AAED;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACvB,0DAA0D;IAC1D,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACpD,yEAAyE;IACzE,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACxD,0CAA0C;IAC1C,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CACrD;AAED;;;;GAIG;AACH,eAAO,MAAM,eAAe,EAAE,QAe7B,CAAC;AA2CF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CA4B9D;AAYD,wFAAwF;AACxF,wBAAgB,kBAAkB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAG/D;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,SAAS,MAAM,EAAE,GAC3B,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAMlC;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CA2C9F;AAED;;;;;GAKG;AACH,eAAO,MAAM,aAAa,EAAE,aAAa,CAAC,mBAAmB,CAwB5D,CAAC"}

package/dist/pipeline/phases/repo-node.js

@@ -0,0 +1,272 @@
+/**
+ * Repo-node phase — emits one first-class `RepoNode` per graph.
+ *
+ * Runs after the `profile` phase so we can inherit `ProjectProfileNode.languages`
+ * when deriving `languageStats`. Probes three git endpoints via
+ * `git -C <path> ...` on the repository root:
+ *   - `config --get remote.origin.url` → `originUrl` + `repoUri`
+ *   - `symbolic-ref --short refs/remotes/origin/HEAD` → `defaultBranch`
+ *   - `rev-parse HEAD` → `commitSha`
+ *
+ * All probes fail-safe: when git is absent, the repo is not a git working
+ * tree, or the command exits non-zero, the phase returns a deterministic
+ * `local:<sha256(abs-path)[:12]>` handle. The phase never throws on git
+ * failures — it downgrades to the local-only shape.
+ *
+ * `indexTime` is populated inside this phase but is explicitly kept out of
+ * graphHash determinism inputs — graphHash hashes the node verbatim, so
+ * callers that need fixture-stable hashes must freeze `indexTime` at the
+ * fixture level or omit the phase from the determinism gate.
+ */
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import { resolve } from "node:path";
+import { promisify } from "node:util";
+import { makeNodeId } from "@opencodehub/core-types";
+import { PROFILE_PHASE_NAME } from "./profile.js";
+export const REPO_NODE_PHASE_NAME = "repo-node";
+const execFileAsync = promisify(execFile);
+/**
+ * Default git probe — runs `git` as a subprocess and swallows all errors to
+ * `null`. We check exit code only implicitly: `execFile` throws on non-zero,
+ * and the try/catch demotes that to `null`.
+ */
+export const defaultGitProbe = {
+    async originUrl(repoPath) {
+        return tryGit(repoPath, ["config", "--get", "remote.origin.url"]);
+    },
+    async defaultBranch(repoPath) {
+        const ref = await tryGit(repoPath, ["symbolic-ref", "--short", "refs/remotes/origin/HEAD"]);
+        if (ref === null)
+            return null;
+        // refs/remotes/origin/HEAD dereferences to "origin/main" etc. Strip the
+        // leading remote prefix so callers get "main", "master", "trunk".
+        const slash = ref.indexOf("/");
+        return slash === -1 ? ref : ref.slice(slash + 1);
+    },
+    async commitSha(repoPath) {
+        return tryGit(repoPath, ["rev-parse", "HEAD"]);
+    },
+};
+/**
+ * Fixed sentinel used when we can't resolve a deterministic per-commit
+ * timestamp. Anchored to the Unix epoch so it clearly signals "unknown" and
+ * carries NO run-to-run variance — this preserves graphHash determinism when
+ * the phase runs outside a git working tree.
+ */
+const UNKNOWN_INDEX_TIME = "1970-01-01T00:00:00Z";
+/**
+ * Resolve `indexTime` deterministically from the repo's HEAD commit
+ * timestamp via `git show -s --format=%cI HEAD`. The %cI formatter emits
+ * ISO 8601 strict UTC. Falls back to the unknown sentinel when git is
+ * unavailable or the repo is not a git working tree.
+ *
+ * graphHash determinism requires this: `new Date().toISOString()` would
+ * inject wall-clock noise into every node, breaking determinism on any
+ * pipeline run where the repo-node phase is active. Pinning to the HEAD
+ * commit time gives us "stable per commit" without excluding the field
+ * from graphHash.
+ */
+async function probeCommitTime(repoPath) {
+    const out = await tryGit(repoPath, ["show", "-s", "--format=%cI", "HEAD"]);
+    if (out === null)
+        return UNKNOWN_INDEX_TIME;
+    return out;
+}
+async function tryGit(repoPath, args) {
+    try {
+        const { stdout } = await execFileAsync("git", ["-C", repoPath, ...args], {
+            // Prevent a stuck git from wedging the pipeline — 5s is generous for
+            // the three metadata probes we issue.
+            timeout: 5000,
+            windowsHide: true,
+        });
+        const trimmed = stdout.trim();
+        return trimmed.length > 0 ? trimmed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Normalise an arbitrary git remote URL into a Sourcegraph-style `host/path`
+ * handle. Handles HTTPS, SSH, and the "scp-like" SSH form git accepts by
+ * default (`git@host:path`). Trailing `.git` is always stripped.
+ *
+ * Examples:
+ *   https://github.com/org/repo.git           → github.com/org/repo
+ *   git@github.com:org/repo.git               → github.com/org/repo
+ *   ssh://git@gitlab.example.com/org/repo     → gitlab.example.com/org/repo
+ *   https://user:token@host.com/a/b           → host.com/a/b
+ *
+ * Returns `null` for unparseable inputs so the caller falls back to the
+ * `local:<hash>` form instead of inventing a URI.
+ */
+export function deriveRepoUri(originUrl) {
+    const remaining = originUrl.trim();
+    if (remaining.length === 0)
+        return null;
+    // scp-like SSH: `[user@]host:path`. The `:` must not be preceded by a
+    // scheme separator (`://`) and the path must not start with `/`.
+    const schemeMatch = /^[a-zA-Z][a-zA-Z0-9+\-.]*:\/\//.exec(remaining);
+    if (schemeMatch === null) {
+        const colonIdx = remaining.indexOf(":");
+        const slashIdx = remaining.indexOf("/");
+        if (colonIdx !== -1 && (slashIdx === -1 || colonIdx < slashIdx)) {
+            const userHost = remaining.slice(0, colonIdx);
+            const path = remaining.slice(colonIdx + 1);
+            const atIdx = userHost.lastIndexOf("@");
+            const host = atIdx === -1 ? userHost : userHost.slice(atIdx + 1);
+            return finalizeRepoUri(host, path);
+        }
+        return null;
+    }
+    // URL-parseable form. Node's URL supports ssh://, https://, git://, etc.
+    try {
+        const u = new URL(remaining);
+        // u.pathname starts with "/", strip it.
+        return finalizeRepoUri(u.host, u.pathname.replace(/^\/+/, ""));
+    }
+    catch {
+        return null;
+    }
+}
+function finalizeRepoUri(host, path) {
+    const cleanHost = host.trim().toLowerCase();
+    if (cleanHost.length === 0)
+        return null;
+    let cleanPath = path.trim().replace(/^\/+/, "");
+    if (cleanPath.endsWith(".git"))
+        cleanPath = cleanPath.slice(0, -4);
+    cleanPath = cleanPath.replace(/\/+$/, "");
+    if (cleanPath.length === 0)
+        return null;
+    return `${cleanHost}/${cleanPath}`;
+}
+/** `local:<sha256(absolute-path)[:12]>` — fallback handle when no git remote exists. */
+export function deriveLocalRepoUri(absolutePath) {
+    const digest = createHash("sha256").update(absolutePath, "utf8").digest("hex");
+    return `local:${digest.slice(0, 12)}`;
+}
+/**
+ * Derive a sorted, fraction-summing language distribution from a list of
+ * detected languages. The simplest fair distribution (when upstream phases
+ * only surface a set, not counts) is uniform — `1 / N` per language.
+ *
+ * Keys are NOT sorted here; canonical JSON is applied at serialisation time
+ * (graphHash + storage adapters), so callers cannot accidentally poison byte
+ * stability by preserving insertion order.
+ */
+export function deriveLanguageStats(languages) {
+    if (languages.length === 0)
+        return {};
+    const share = 1 / languages.length;
+    const out = {};
+    for (const lang of languages)
+        out[lang] = share;
+    return out;
+}
+/**
+ * Core entry point — usable both inside the pipeline DAG (via `repoNodePhase`)
+ * and as a standalone function for callers that already hold a repo path and
+ * an indexer tag.
+ */
+export async function runRepoNodePhase(input) {
+    const probe = input.gitProbe ?? defaultGitProbe;
+    const absolutePath = resolve(input.repoPath);
+    const [originUrl, defaultBranch, commitSha] = await Promise.all([
+        probe.originUrl(absolutePath),
+        probe.defaultBranch(absolutePath),
+        probe.commitSha(absolutePath),
+    ]);
+    const derivedUri = originUrl !== null ? deriveRepoUri(originUrl) : null;
+    const repoUri = derivedUri ?? deriveLocalRepoUri(absolutePath);
+    const name = repoUri;
+    const id = makeNodeId("Repo", "", "repo");
+    // `indexTime` must be deterministic per commit — `new Date().toISOString()`
+    // would poison graphHash with wall-clock noise, breaking determinism. The
+    // injected `now` override wins when the caller wants a fixture-stable
+    // value (tests); otherwise we read the HEAD commit timestamp so two runs
+    // at the same commit produce byte-identical RepoNodes.
+    const indexTime = input.now !== undefined ? input.now() : await probeCommitTime(absolutePath);
+    const repoNode = {
+        id,
+        kind: "Repo",
+        name,
+        filePath: "",
+        originUrl,
+        repoUri,
+        defaultBranch,
+        // When HEAD can't be resolved the repo is effectively un-indexed; emit
+        // the null-commit sentinel as an empty SHA string so downstream tooling
+        // can detect the degenerate case without a branch. This is still a
+        // valid RepoNode — the interface declares `commitSha: string`, so we
+        // satisfy the type with an explicit empty string rather than `null`.
+        commitSha: commitSha ?? "",
+        indexTime,
+        group: input.group ?? null,
+        visibility: input.visibility ?? "private",
+        indexer: input.indexer,
+        languageStats: deriveLanguageStats(input.detectedLanguages ?? []),
+    };
+    return { repoNode };
+}
+/**
+ * Pipeline wrapper. Consumes the profile phase's detected languages (when
+ * present), emits one RepoNode, and pushes it into `ctx.graph`. The output
+ * map is a no-op hook — downstream phases that want the node should read it
+ * from the graph, mirroring the profile-phase contract.
+ */
+export const repoNodePhase = {
+    name: REPO_NODE_PHASE_NAME,
+    // Declaring `profile` as a dep (not `scan`) makes the phase run AFTER
+    // ProjectProfileNode is on the graph, which guarantees `languageStats`
+    // is populated from the same source-of-truth detector.
+    deps: [PROFILE_PHASE_NAME],
+    async run(ctx, deps) {
+        const profile = deps.get(PROFILE_PHASE_NAME);
+        if (profile === undefined) {
+            throw new Error("repo-node: profile output missing from dependency map");
+        }
+        const detectedLanguages = readDetectedLanguages(ctx);
+        const out = await runRepoNodePhase({
+            repoPath: ctx.repoPath,
+            // The pipeline does not yet thread group / visibility / indexer through
+            // PipelineOptions — that wiring lands in a later iteration. For now we
+            // surface deterministic defaults that match the RepoNode interface
+            // contract.
+            indexer: `opencodehub@${resolveIndexerVersion()}`,
+            detectedLanguages,
+        });
+        ctx.graph.addNode(out.repoNode);
+        return out;
+    },
+};
+function readDetectedLanguages(ctx) {
+    for (const n of ctx.graph.nodes()) {
+        if (n.kind === "ProjectProfile") {
+            return n.languages;
+        }
+    }
+    return [];
+}
+/**
+ * Best-effort read of the ingestion package version so `indexer` carries a
+ * concrete `opencodehub@<version>` tag. Resolves via `package.json` import
+ * only when available; falls back to `"unknown"` so the phase never throws
+ * on a missing / unreadable manifest.
+ */
+function resolveIndexerVersion() {
+    try {
+        // dist layout: phases/ -> pipeline/ -> src/ -> package root / package.json
+        // (under packages/ingestion/). We do NOT import the file directly — an
+        // ESM import of package.json requires an import assertion that most
+        // Node versions gate behind a flag. Instead, fall back to the static
+        // package name when the version isn't trivially discoverable.
+        return "0.1.0";
+    }
+    catch {
+        return "unknown";
+    }
+}
+//# sourceMappingURL=repo-node.js.map

package/dist/pipeline/phases/repo-node.js.map

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

package/dist/pipeline/phases/risk-snapshot.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Risk-snapshot phase.
+ *
+ * Persists a per-community risk snapshot to
+ * `.codehub/history/risk_<ISOTS>.json` after `annotate` has finalised the
+ * community + finding counts. The snapshot captures the state of the graph
+ * for trend analysis across successive analyze runs.
+ *
+ * Dependencies: `[annotate]` — we want the finished community + finding
+ * node set.
+ *
+ * Determinism: snapshot filenames are derived from the run's wall-clock
+ * timestamp; callers that want byte-stable output should inject a clock via
+ * `options.riskSnapshotNow`. The snapshot itself is deterministic given a
+ * pinned timestamp because both `perCommunityRisk` and the histogram keys
+ * are sorted before serialisation.
+ */
+import type { PipelinePhase } from "../types.js";
+export declare const RISK_SNAPSHOT_PHASE_NAME: "risk-snapshot";
+export interface RiskSnapshotOptions {
+    /** When true, do not persist the snapshot. Default false (persist). */
+    readonly riskSnapshotSkipPersist?: boolean;
+    /** Override the timestamp used for the filename + snapshot field. */
+    readonly riskSnapshotNow?: string;
+}
+export interface RiskSnapshotOutput {
+    readonly filePath: string | null;
+    readonly communityCount: number;
+    readonly totalNodeCount: number;
+    readonly totalEdgeCount: number;
+    readonly persisted: boolean;
+}
+export declare const riskSnapshotPhase: PipelinePhase<RiskSnapshotOutput>;
+//# sourceMappingURL=risk-snapshot.d.ts.map

package/dist/pipeline/phases/risk-snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"risk-snapshot.d.ts","sourceRoot":"","sources":["../../../src/pipeline/phases/risk-snapshot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,KAAK,EAAmB,aAAa,EAAE,MAAM,aAAa,CAAC;AAGlE,eAAO,MAAM,wBAAwB,EAAG,eAAwB,CAAC;AAEjE,MAAM,WAAW,mBAAmB;IAClC,uEAAuE;IACvE,QAAQ,CAAC,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAC3C,qEAAqE;IACrE,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;CACnC;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED,eAAO,MAAM,iBAAiB,EAAE,aAAa,CAAC,kBAAkB,CAM/D,CAAC"}

package/dist/pipeline/phases/risk-snapshot.js

@@ -0,0 +1,63 @@
+/**
+ * Risk-snapshot phase.
+ *
+ * Persists a per-community risk snapshot to
+ * `.codehub/history/risk_<ISOTS>.json` after `annotate` has finalised the
+ * community + finding counts. The snapshot captures the state of the graph
+ * for trend analysis across successive analyze runs.
+ *
+ * Dependencies: `[annotate]` — we want the finished community + finding
+ * node set.
+ *
+ * Determinism: snapshot filenames are derived from the run's wall-clock
+ * timestamp; callers that want byte-stable output should inject a clock via
+ * `options.riskSnapshotNow`. The snapshot itself is deterministic given a
+ * pinned timestamp because both `perCommunityRisk` and the histogram keys
+ * are sorted before serialisation.
+ */
+import { buildRiskSnapshotFromGraph, persistRiskSnapshot } from "@opencodehub/analysis";
+import { ANNOTATE_PHASE_NAME } from "./annotate.js";
+export const RISK_SNAPSHOT_PHASE_NAME = "risk-snapshot";
+export const riskSnapshotPhase = {
+    name: RISK_SNAPSHOT_PHASE_NAME,
+    deps: [ANNOTATE_PHASE_NAME],
+    async run(ctx, deps) {
+        return runRiskSnapshot(ctx, deps);
+    },
+};
+async function runRiskSnapshot(ctx, deps) {
+    const annotate = deps.get(ANNOTATE_PHASE_NAME);
+    const options = ctx.options;
+    const nowIso = options.riskSnapshotNow ?? new Date().toISOString();
+    const commit = annotate?.currentCommit ?? "unknown";
+    const snapshot = buildRiskSnapshotFromGraph(ctx.graph, commit, nowIso);
+    const communityCount = Object.keys(snapshot.perCommunityRisk).length;
+    if (options.riskSnapshotSkipPersist === true) {
+        return {
+            filePath: null,
+            communityCount,
+            totalNodeCount: snapshot.totalNodeCount,
+            totalEdgeCount: snapshot.totalEdgeCount,
+            persisted: false,
+        };
+    }
+    let filePath = null;
+    try {
+        filePath = await persistRiskSnapshot(ctx.repoPath, snapshot);
+    }
+    catch (err) {
+        ctx.onProgress?.({
+            phase: RISK_SNAPSHOT_PHASE_NAME,
+            kind: "warn",
+            message: `risk-snapshot: persist failed (${err.message})`,
+        });
+    }
+    return {
+        filePath,
+        communityCount,
+        totalNodeCount: snapshot.totalNodeCount,
+        totalEdgeCount: snapshot.totalEdgeCount,
+        persisted: filePath !== null,
+    };
+}
+//# sourceMappingURL=risk-snapshot.js.map

package/dist/pipeline/phases/risk-snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"risk-snapshot.js","sourceRoot":"","sources":["../../../src/pipeline/phases/risk-snapshot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,0BAA0B,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAExF,OAAO,EAAE,mBAAmB,EAAuB,MAAM,eAAe,CAAC;AAEzE,MAAM,CAAC,MAAM,wBAAwB,GAAG,eAAwB,CAAC;AAiBjE,MAAM,CAAC,MAAM,iBAAiB,GAAsC;IAClE,IAAI,EAAE,wBAAwB;IAC9B,IAAI,EAAE,CAAC,mBAAmB,CAAC;IAC3B,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI;QACjB,OAAO,eAAe,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IACpC,CAAC;CACF,CAAC;AAEF,KAAK,UAAU,eAAe,CAC5B,GAAoB,EACpB,IAAkC;IAElC,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,mBAAmB,CAA+B,CAAC;IAC7E,MAAM,OAAO,GAAG,GAAG,CAAC,OAAwD,CAAC;IAC7E,MAAM,MAAM,GAAG,OAAO,CAAC,eAAe,IAAI,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACnE,MAAM,MAAM,GAAG,QAAQ,EAAE,aAAa,IAAI,SAAS,CAAC;IACpD,MAAM,QAAQ,GAAG,0BAA0B,CAAC,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAEvE,MAAM,cAAc,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAAC,MAAM,CAAC;IACrE,IAAI,OAAO,CAAC,uBAAuB,KAAK,IAAI,EAAE,CAAC;QAC7C,OAAO;YACL,QAAQ,EAAE,IAAI;YACd,cAAc;YACd,cAAc,EAAE,QAAQ,CAAC,cAAc;YACvC,cAAc,EAAE,QAAQ,CAAC,cAAc;YACvC,SAAS,EAAE,KAAK;SACjB,CAAC;IACJ,CAAC;IAED,IAAI,QAAQ,GAAkB,IAAI,CAAC;IACnC,IAAI,CAAC;QACH,QAAQ,GAAG,MAAM,mBAAmB,CAAC,GAAG,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAC/D,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,GAAG,CAAC,UAAU,EAAE,CAAC;YACf,KAAK,EAAE,wBAAwB;YAC/B,IAAI,EAAE,MAAM;YACZ,OAAO,EAAE,kCAAmC,GAAa,CAAC,OAAO,GAAG;SACrE,CAAC,CAAC;IACL,CAAC;IAED,OAAO;QACL,QAAQ;QACR,cAAc;QACd,cAAc,EAAE,QAAQ,CAAC,cAAc;QACvC,cAAc,EAAE,QAAQ,CAAC,cAAc;QACvC,SAAS,EAAE,QAAQ,KAAK,IAAI;KAC7B,CAAC;AACJ,CAAC"}

package/dist/pipeline/phases/routes.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Routes phase — materialises HTTP route metadata emitted by the static
+ * detectors (Next.js, Express, FastAPI, NestJS, Spring MVC, Rails) as
+ * graph nodes and edges.
+ *
+ * The phase:
+ *   1. Feeds the scanned files through every detector that matches the
+ *      active {@link ProjectProfileNode.frameworks} list. Next.js +
+ *      Express always run when TS/JS files are present. FastAPI runs on
+ *      `fastapi`, NestJS on `nestjs`, Spring on any `spring-*` variant,
+ *      Rails on `rails`.
+ *   2. Creates one `Route` node per unique `(url, method)` pair, keyed
+ *      by the handler file so two frameworks declaring the same URL on
+ *      the same file reuse the node.
+ *   3. Emits `HANDLES_ROUTE` edges from the declaring File node to the
+ *      Route node with a fixed confidence of 0.9.
+ *   4. Detects cross-file duplicates for the same `(url, method)` and
+ *      surfaces them as warnings via the progress callback — but keeps
+ *      one edge per handler file (the route *is* re-declared).
+ *
+ * Depends on `parse` to order the DAG; the profile node is read from
+ * the in-memory graph.
+ */
+import type { PipelinePhase } from "../types.js";
+export interface RoutesOutput {
+    readonly routeCount: number;
+    readonly duplicateCount: number;
+}
+export declare const ROUTES_PHASE_NAME = "routes";
+export declare const routesPhase: PipelinePhase<RoutesOutput>;
+//# sourceMappingURL=routes.d.ts.map

package/dist/pipeline/phases/routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../../src/pipeline/phases/routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAgBH,OAAO,KAAK,EAAmB,aAAa,EAAE,MAAM,aAAa,CAAC;AAsBlE,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED,eAAO,MAAM,iBAAiB,WAAW,CAAC;AAE1C,eAAO,MAAM,WAAW,EAAE,aAAa,CAAC,YAAY,CAgBnD,CAAC"}