@opencodehub/cli 0.1.0

package/dist/commands/ingest-sarif.js

@@ -0,0 +1,381 @@
+/**
+ * `codehub ingest-sarif <sarif-file>` — import a SARIF v2.1.0 log into
+ * the code graph as `Finding` nodes + `FOUND_IN` edges.
+ *
+ * Flow:
+ *   1. Read + parse + validate the SARIF file via `@opencodehub/sarif`.
+ *   2. Resolve the target repo (either `--repo <name>` or CWD).
+ *   3. Open the DuckDB store and pull a per-file, line-sorted symbol
+ *      index over the SARIF's referenced URIs (used to resolve Finding
+ *      → Symbol edges).
+ *   4. For every Result across every Run, build a Finding node keyed by
+ *      `Finding:<scannerId>:<ruleId>:<uri>:<startLine>`. Emit FOUND_IN
+ *      edges to the target File node (matched by `artifactLocation.uri`
+ *      against `file_path`) plus a second FOUND_IN edge to the tightest
+ *      enclosing symbol at `(uri, startLine)` when the graph contains
+ *      one. A scanner-provided `opencodehub.symbolId` hint wins over the
+ *      enclosing lookup when set.
+ *   5. UPSERT into DuckDB via `store.bulkLoad({ mode: "upsert" })`.
+ *
+ * The command is idempotent — re-running with the same SARIF produces
+ * the same nodes and edges. Results without a parsable location (no
+ * physicalLocation.artifactLocation.uri) are skipped with a warning.
+ */
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { KnowledgeGraph, makeNodeId } from "@opencodehub/core-types";
+import { applyBaselineState, enrichWithFingerprints, SarifLogSchema, } from "@opencodehub/sarif";
+import { openStore, resolveDbPath, resolveRepoMetaDir, } from "@opencodehub/storage";
+import { readRegistry } from "../registry.js";
+import { ENCLOSING_SYMBOL_KINDS, findEnclosingSymbolId, indexNodesByFile, } from "./find-enclosing-symbol.js";
+export async function runIngestSarif(sarifFile, opts = {}) {
+    const sarifPath = resolve(sarifFile);
+    const raw = await readFile(sarifPath, "utf8");
+    const parsed = JSON.parse(raw);
+    const validation = SarifLogSchema.safeParse(parsed);
+    if (!validation.success) {
+        throw new Error(`codehub ingest-sarif: ${sarifPath} is not a valid SARIF 2.1.0 log: ${validation.error.message}`);
+    }
+    let log = validation.data;
+    const repoPath = await resolveRepoPath(opts);
+    // Stamp `opencodehub/v1` + `primaryLocationLineHash` partial fingerprints
+    // onto every result. The call is idempotent: an already-enriched input
+    // produces the same fingerprints, so re-ingesting a SARIF file leaves the
+    // column stable.
+    log = enrichWithFingerprints(log);
+    // Optional baseline overlay. When `<repo>/.codehub/baseline.sarif` exists
+    // we tag every result with SARIF 2.1.0 `baselineState` so the
+    // `baseline_state` column is populated; missing baseline leaves it NULL
+    // (consumers treat NULL as "new" by convention).
+    const baselineLog = await loadRepoBaseline(repoPath);
+    if (baselineLog !== undefined) {
+        log = applyBaselineState(log, baselineLog);
+    }
+    const dbPath = resolveDbPath(repoPath);
+    const composed = await openStore({ path: dbPath, backend: "auto" });
+    let graph;
+    let summary;
+    try {
+        await composed.graph.open();
+        await composed.graph.createSchema();
+        // Pull the per-file symbol index out of the store once so every
+        // SARIF result can resolve its enclosing symbol without a round
+        // trip. Restricts to URIs that actually appear in the SARIF log
+        // and to the code-kind allow set shared with `buildFindingsGraph`.
+        const nodesByFile = await loadNodesByFileForSarif(composed.graph, log.runs);
+        ({ graph, summary } = buildFindingsGraph(log.runs, nodesByFile));
+        await composed.graph.bulkLoad(graph, { mode: "upsert" });
+    }
+    finally {
+        await composed.close();
+    }
+    const out = {
+        sarifFile: sarifPath,
+        repoPath,
+        findingsEmitted: summary.findingsEmitted,
+        edgesEmitted: summary.edgesEmitted,
+        resultsSkipped: summary.resultsSkipped,
+        warnings: summary.warnings,
+    };
+    for (const w of summary.warnings) {
+        console.warn(`codehub ingest-sarif: ${w}`);
+    }
+    console.warn(`codehub ingest-sarif: ${out.findingsEmitted} findings, ${out.edgesEmitted} edges from ${sarifPath} → ${repoPath}`);
+    return out;
+}
+/**
+ * Pure builder over SARIF runs. Exposed for unit tests so we can exercise
+ * the node/edge emission logic without touching DuckDB.
+ *
+ * `nodesByFile` is the per-file, line-sorted symbol index (produced by
+ * {@link indexNodesByFile}) used to resolve each SARIF result back to the
+ * tightest-enclosing code symbol when the scanner did not populate
+ * `result.properties["opencodehub.symbolId"]` itself. Callers that only
+ * want the File-level edge (e.g. unit tests) can omit it — an empty map
+ * means every symbol lookup misses and only the File edge is emitted.
+ */
+export function buildFindingsGraph(runs, nodesByFile = new Map()) {
+    const graph = new KnowledgeGraph();
+    const warnings = [];
+    let findingsEmitted = 0;
+    let edgesEmitted = 0;
+    let resultsSkipped = 0;
+    for (const run of runs) {
+        const scannerId = run.tool.driver.name;
+        const results = run.results ?? [];
+        for (const result of results) {
+            const finding = buildFindingNode(scannerId, result);
+            if (!finding) {
+                resultsSkipped += 1;
+                continue;
+            }
+            graph.addNode(finding.node);
+            findingsEmitted += 1;
+            // FOUND_IN edge Finding → File (matched by URI). We always emit
+            // this edge — if the target File node does not exist in the graph
+            // (ingest-sarif runs independently of analyze), the relation is
+            // still recorded; downstream queries can left-join.
+            const fileId = makeNodeId("File", finding.uri, finding.uri);
+            graph.addEdge({
+                from: finding.node.id,
+                to: fileId,
+                type: "FOUND_IN",
+                confidence: 1,
+                reason: finding.reason,
+            });
+            edgesEmitted += 1;
+            // Resolve the Finding → Symbol edge. Priority order:
+            //   1. `opencodehub.symbolId` in the result properties bag — the
+            //      explicit scanner-provided hint wins (e.g. semgrep rules that
+            //      resolve to a specific function already).
+            //   2. Tightest-enclosing symbol at (uri, startLine) from the graph
+            //      index. This is the common path for third-party SARIF tools
+            //      that emit raw file+line locations.
+            // If neither resolves we keep the File-only edge.
+            const hintedSymbolId = extractSymbolId(result);
+            const symbolId = hintedSymbolId !== undefined
+                ? hintedSymbolId
+                : findEnclosingSymbolId(nodesByFile, finding.uri, finding.node.startLine ?? 1);
+            if (symbolId !== undefined) {
+                graph.addEdge({
+                    from: finding.node.id,
+                    to: symbolId,
+                    type: "FOUND_IN",
+                    confidence: 1,
+                    reason: finding.reason,
+                    step: 1,
+                });
+                edgesEmitted += 1;
+            }
+        }
+    }
+    return {
+        graph,
+        summary: { findingsEmitted, edgesEmitted, resultsSkipped, warnings },
+    };
+}
+/**
+ * Convert a single SARIF Result into a FindingNode. Returns `undefined`
+ * when the result is missing a location we can key on — we need
+ * (ruleId, uri, startLine) to produce a stable id.
+ */
+function buildFindingNode(scannerId, result) {
+    const ruleId = result.ruleId;
+    if (typeof ruleId !== "string" || ruleId.length === 0)
+        return undefined;
+    const loc = result.locations?.[0]?.physicalLocation;
+    const uri = loc?.artifactLocation?.uri;
+    if (typeof uri !== "string" || uri.length === 0)
+        return undefined;
+    const region = loc?.region;
+    const startLine = region?.startLine ?? 1;
+    const endLine = region?.endLine;
+    // Severity: map SARIF level → Finding.severity. Default "note" when
+    // the scanner omits `level` (GHAS treats missing level as "warning",
+    // but we stay conservative).
+    const severity = mapSeverity(result.level);
+    const message = result.message?.text ?? "";
+    const id = makeNodeId("Finding", uri, `${scannerId}:${ruleId}:${startLine}`);
+    const propertiesBag = {};
+    if (result.properties) {
+        for (const [k, v] of Object.entries(result.properties)) {
+            propertiesBag[k] = v;
+        }
+    }
+    const suppressedJson = extractSuppressedJson(result);
+    const partialFingerprint = extractOpenCodeHubFingerprint(result);
+    const baselineState = extractBaselineState(result);
+    const node = {
+        id,
+        kind: "Finding",
+        name: `${scannerId}:${ruleId}`,
+        filePath: uri,
+        ruleId,
+        severity,
+        scannerId,
+        message,
+        propertiesBag,
+        startLine,
+        ...(endLine !== undefined ? { endLine } : {}),
+        ...(suppressedJson !== undefined ? { suppressedJson } : {}),
+        ...(partialFingerprint !== undefined ? { partialFingerprint } : {}),
+        ...(baselineState !== undefined ? { baselineState } : {}),
+    };
+    const reason = endLine !== undefined ? `startLine=${startLine};endLine=${endLine}` : `startLine=${startLine}`;
+    return { node, uri, reason };
+}
+function mapSeverity(level) {
+    switch (level) {
+        case "error":
+        case "warning":
+        case "note":
+        case "none":
+            return level;
+        default:
+            return "note";
+    }
+}
+/**
+ * Persist SARIF `suppressions[]` into the FindingNode's `suppressedJson`
+ * column. We keep every entry (external + inSource) so
+ * downstream consumers can distinguish waiver provenance; missing or
+ * empty arrays resolve to undefined so the column stays null and verdict
+ * treats the finding as un-suppressed.
+ */
+function extractSuppressedJson(result) {
+    const arr = result.suppressions;
+    if (!Array.isArray(arr) || arr.length === 0)
+        return undefined;
+    const entries = [];
+    for (const entry of arr) {
+        if (entry === null || typeof entry !== "object")
+            continue;
+        const record = entry;
+        const kind = record["kind"];
+        const justification = record["justification"];
+        if (typeof kind !== "string" || typeof justification !== "string")
+            continue;
+        const expiresAt = record["expiresAt"];
+        const out = {
+            kind,
+            justification,
+        };
+        if (typeof expiresAt === "string" && expiresAt.length > 0)
+            out.expiresAt = expiresAt;
+        entries.push(out);
+    }
+    return entries.length > 0 ? JSON.stringify(entries) : undefined;
+}
+function extractSymbolId(result) {
+    const props = result.properties;
+    if (!props || typeof props !== "object")
+        return undefined;
+    const record = props;
+    // Primary key scanners put inside their result properties bag.
+    const v = record["opencodehub.symbolId"];
+    if (typeof v === "string" && v.length > 0)
+        return v;
+    return undefined;
+}
+/**
+ * Pull the `opencodehub/v1` entry out of `result.partialFingerprints` and
+ * persist it on the FindingNode. Enrichment runs before ingest so this
+ * lookup always succeeds for well-formed inputs — if it doesn't, the
+ * column stays NULL (e.g. SARIF files that predate enrichment).
+ */
+function extractOpenCodeHubFingerprint(result) {
+    const pf = result.partialFingerprints;
+    if (pf === null || pf === undefined || typeof pf !== "object")
+        return undefined;
+    const v = pf["opencodehub/v1"];
+    return typeof v === "string" && v.length > 0 ? v : undefined;
+}
+/**
+ * Read `result.baselineState` as a typed literal. `applyBaselineState`
+ * only writes `"new" | "unchanged" | "updated"` (baseline-only findings
+ * stay outside the current log); `"absent"` can arrive via third-party
+ * tooling so we accept it for completeness.
+ */
+function extractBaselineState(result) {
+    const v = result.baselineState;
+    if (v === "new" || v === "unchanged" || v === "updated" || v === "absent") {
+        return v;
+    }
+    return undefined;
+}
+/**
+ * Load `<repo>/.codehub/baseline.sarif` if present. Missing file resolves
+ * to undefined; malformed file raises so the caller can surface the
+ * validation error instead of silently dropping baselineState.
+ */
+async function loadRepoBaseline(repoPath) {
+    const candidate = resolve(`${resolveRepoMetaDir(repoPath)}/baseline.sarif`);
+    let raw;
+    try {
+        raw = await readFile(candidate, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return undefined;
+        throw err;
+    }
+    const parsed = JSON.parse(raw);
+    const result = SarifLogSchema.safeParse(parsed);
+    if (!result.success) {
+        throw new Error(`codehub ingest-sarif: baseline at ${candidate} is not a valid SARIF 2.1.0 log: ${result.error.message}`);
+    }
+    return result.data;
+}
+/**
+ * Collect every distinct `artifactLocation.uri` across every Result in
+ * every Run. Results without a parsable URI (or with an empty one) are
+ * silently skipped — downstream emission logic already discards them.
+ */
+function collectSarifUris(runs) {
+    const seen = new Set();
+    for (const run of runs) {
+        for (const result of run.results ?? []) {
+            const uri = result.locations?.[0]?.physicalLocation?.artifactLocation?.uri;
+            if (typeof uri === "string" && uri.length > 0)
+                seen.add(uri);
+        }
+    }
+    return [...seen];
+}
+/**
+ * Query the graph store for every code-kind node whose `file_path`
+ * matches a URI that appears in the SARIF log, then build the per-file,
+ * line-sorted symbol index used by {@link findEnclosingSymbolId}.
+ *
+ * Scoping by the SARIF URIs keeps the query bounded even on large
+ * repos: a SARIF log typically references a few hundred files, not the
+ * whole codebase. Empty URI list short-circuits to an empty index — the
+ * caller will emit only File-level edges, which matches the v0 behavior
+ * before symbol-level linkage existed.
+ */
+async function loadNodesByFileForSarif(graph, runs) {
+    const uris = collectSarifUris(runs);
+    if (uris.length === 0)
+        return new Map();
+    // Fan one round-trip per code kind in the allow-set, narrowed by
+    // `filePath` set. `listNodesByKind` returns the typed node shape
+    // (`NodeOfKind<K>`) — the row projection only needs id / filePath /
+    // startLine / endLine / kind, all of which are present on every
+    // ENCLOSING_SYMBOL_KINDS member (LocatedNode subset).
+    const uriSet = new Set(uris);
+    const projected = [];
+    for (const kind of ENCLOSING_SYMBOL_KINDS) {
+        const nodes = await graph.listNodesByKind(kind);
+        for (const n of nodes) {
+            if (!uriSet.has(n.filePath))
+                continue;
+            const startLine = n.startLine;
+            const endLine = n.endLine;
+            if (typeof startLine !== "number" || !Number.isFinite(startLine))
+                continue;
+            if (typeof endLine !== "number" || !Number.isFinite(endLine))
+                continue;
+            projected.push({
+                id: n.id,
+                filePath: n.filePath,
+                startLine,
+                endLine,
+                kind: n.kind,
+            });
+        }
+    }
+    return indexNodesByFile(projected);
+}
+async function resolveRepoPath(opts) {
+    if (opts.repo !== undefined) {
+        const registryOpts = opts.home !== undefined ? { home: opts.home } : {};
+        const registry = await readRegistry(registryOpts);
+        const hit = registry[opts.repo];
+        if (hit)
+            return resolve(hit.path);
+        // Treat as raw path fallback for ergonomics (same convention as query CLI).
+        return resolve(opts.repo);
+    }
+    return resolve(process.cwd());
+}
+//# sourceMappingURL=ingest-sarif.js.map

package/dist/commands/ingest-sarif.js.map

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

package/dist/commands/init.d.ts

@@ -0,0 +1,75 @@
+/**
+ * `codehub init` — bootstrap a repository for OpenCodeHub in one command.
+ *
+ * Project-scope installer. Copies plugin assets (skills/agents/commands/hooks)
+ * into `<repo>/.claude/`, writes `.mcp.json` so Claude Code launches the
+ * `codehub` MCP server, appends `.codehub/` to `.gitignore`, and seeds a
+ * starter `opencodehub.policy.yaml` (commented out; rules ship in spec 002).
+ *
+ * Why project scope:
+ *   - Checking `.claude/` into git means every teammate's Claude Code
+ *     auto-discovers the plugin on clone. No per-machine install.
+ *   - Keeps the plugin pinned to the repo's graph schema; upgrades are
+ *     explicit (`codehub init --upgrade`) rather than ambient.
+ *
+ * Hook rewrite note:
+ *   The plugin's `hooks.json` uses `${CLAUDE_PLUGIN_ROOT}` which is only
+ *   bound for user-scope plugins. Project-scope hooks must use
+ *   `${CLAUDE_PROJECT_DIR}/.claude` for Claude Code to find the shell
+ *   scripts. We rewrite the token at install time and write the result
+ *   to `.claude/settings.json` (the project-scope equivalent of
+ *   `hooks.json`).
+ *
+ * Idempotence: re-running with identical args produces byte-identical
+ * output. Re-running against an existing `.claude/` refuses unless
+ * `--force` is set, and the error lists every conflicting file.
+ *
+ * Filesystem access goes through the same `FsApi` seam used by
+ * `commands/setup.ts` so tests run against an in-memory implementation.
+ */
+import { type FsApi, type SetupResult } from "./setup.js";
+export interface InitOptions {
+    /** Target repo. Defaults to `process.cwd()`. */
+    readonly repo?: string;
+    /** Plugin source dir. Defaults to the bundled `dist/plugin-assets/`. */
+    readonly sourceDir?: string;
+    /**
+     * Overwrite `.claude/` on re-run. Without `--force`, conflicting files cause
+     * a refusal listing each one.
+     */
+    readonly force?: boolean;
+    /**
+     * Skip the `.mcp.json` edit. Useful for teams that manage MCP config
+     * elsewhere (e.g., via Claude Code user-scope config).
+     */
+    readonly skipMcp?: boolean;
+    /**
+     * Skip seeding `opencodehub.policy.yaml`. The starter file is commented out
+     * and purely informational; some repos may prefer to author their own.
+     */
+    readonly skipPolicy?: boolean;
+    /** FS seam. Defaults to real filesystem. */
+    readonly fs?: FsApi;
+    /** Structured logger. Defaults to `console.warn`. */
+    readonly log?: (message: string) => void;
+    readonly warn?: (message: string) => void;
+    /** Override home dir (forwarded to `runSetup` for claude-code MCP write). */
+    readonly home?: string;
+}
+export interface InitResult {
+    readonly repoRoot: string;
+    readonly sourceDir: string;
+    readonly claudeDir: string;
+    readonly filesCopied: number;
+    readonly hooksWrittenTo: string | null;
+    readonly mcpResult: SetupResult | null;
+    readonly gitignoreUpdated: boolean;
+    readonly policySeeded: boolean;
+}
+/**
+ * Entry point for `codehub init`. Returns a structured result; throws on
+ * unrecoverable error (e.g., plugin source missing, conflicts without
+ * `--force`).
+ */
+export declare function runInit(opts?: InitOptions): Promise<InitResult>;
+//# sourceMappingURL=init.d.ts.map

package/dist/commands/init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAgBH,OAAO,EAAE,KAAK,KAAK,EAA+B,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AA0CvF,MAAM,WAAW,WAAW;IAC1B,gDAAgD;IAChD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,wEAAwE;IACxE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;IAC9B,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,CAAC,EAAE,KAAK,CAAC;IACpB,qDAAqD;IACrD,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACzC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAC1C,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IACvC,QAAQ,CAAC,SAAS,EAAE,WAAW,GAAG,IAAI,CAAC;IACvC,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;CAChC;AAED;;;;GAIG;AACH,wBAAsB,OAAO,CAAC,IAAI,GAAE,WAAgB,GAAG,OAAO,CAAC,UAAU,CAAC,CA6EzE"}