deepbom 2.0.0 → 2.1.0

package/package.json

@@ -1,15 +1,25 @@
 {
   "name": "deepbom",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "mcpName": "io.github.JunHwan-Kwon/deepbom",
   "description": "Local multi-format deployment-artifact analysis for on-device AI models",
   "type": "module",
+  "main": "./sdk/index.mjs",
+  "types": "./sdk/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./sdk/index.d.mts",
+      "import": "./sdk/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
   "bin": {
     "deepbom": "bin/deepbom.mjs"
   },
   "files": [
     "bin/",
     "pkg/",
+    "sdk/",
     "skills/deepbom/",
     "README.md",
     "LICENSE"

package/pkg/release-manifest.json

@@ -1,14 +1,14 @@
 {
   "schema": "deepbom.npm_release.v1",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "source": {
-    "git_commit": "520695232ab30a9eb3712388212542ea78d185e6",
+    "git_commit": "b161cd4c383e1133e97200a04c8459935f4c7d97",
     "git_state": "clean",
     "distribution": "public_channel"
   },
   "runtime": {
     "node": ">=20",
-    "tflite_wasm_sha256": "352c71ffcd1ef4bd3918f0dbbff967cb1ec2cbc0293f8148d2804be56ce30cc8",
+    "tflite_wasm_sha256": "7a562be6d5daa3df1b8f5dd4d15fd2c05eae715eb805f9c99b2287294fc352ee",
     "self_test": {
       "file": "bin/deepbom-self-test.onnx",
       "sha256": "82a2feef00eb6ab03d82f2b30cd17f4d826e2d8307cb059eccd6a0f3120059b2"

package/sdk/index.d.mts

@@ -0,0 +1,62 @@
+/** Stable SDK entry point; native documents retain their own schema versions. */
+export type JsonDocument = Record<string, unknown>;
+export interface Limits { timeoutMs?: number; maxOutputBytes?: number; }
+export interface InspectOptions extends Limits {
+  scan?: "auto" | "structure" | "integrity" | "full";
+  expectedSha256?: string;
+  gate?: "defects";
+  policy?: "engineering" | "regulatory";
+}
+export interface AuditOptions extends InspectOptions {
+  output?: "analysis" | "envelope" | "cyclonedx" | "sarif";
+  sections?: string[];
+}
+export interface Finding extends JsonDocument {
+  id: string; title: string; severity: string; evidence_class: string;
+  source_pointers: string[]; recommendation: string | null;
+}
+export interface ReviewSummary extends JsonDocument {
+  schema: "deepbom.review_summary.v1";
+  artifact: { filename: string | null; format: string | null; sha256: string; byte_length: number | null; artifact_ir_sha256: string };
+  verdict: { status: "artifact_defects_observed" | "no_artifact_defect_observed"; artifact_defect_count: number; caution_count: number; evidence_needed_count: number; scope: string };
+  findings: { artifact_defects: Finding[]; cautions: Finding[]; evidence_needed: Finding[] };
+  coverage: { assessed: number; partial: number; unavailable: number; /** @deprecated Alias for unavailable; does not mean all missing capabilities require external evidence. */ needs_external_evidence: number; declared: number; applicability: Record<string, number> };
+  graph: { operator_count: number | null; tensor_count: number | null; total_macs: number | null; mac_confidence: "exact" | "partial" | "symbolic" | "not_applicable"; mac_assessment_status: string | null };
+  storage: JsonDocument | null;
+  quantization: { classification: string | null; max_risk: string; max_risk_op_index: number | null; max_risk_op_name: string | null; max_risk_detail: string | null };
+  target: { id: string | null; label: string | null; binding_source: string | null };
+  rulepack: { version: string | null; sha256: string | null };
+  reproduction: { schema: "deepbom.reproduction_command.v1"; executable: string; argv: string[]; package_version: string; artifact_filename: string; expected_sha256: string; shell_command: string; boundary: string };
+  applicability: Record<string, JsonDocument>;
+  next_actions: { action: string; command_hint: string }[];
+  evidence_envelope_sha256: string;
+}
+export interface EvidenceEnvelope extends JsonDocument {
+  schema: "deepbom.artifact_evidence_envelope.v1";
+  identity: { filename: string; format: string; sha256: string; hash_basis: string; byte_length: number | null; schema_or_opset: string | null };
+  capabilities: { schema: string; format: string; declared_capabilities: string[]; assessed: string[]; partial: string[]; unavailable: string[]; conservation: { declared: number; classified: number; valid: boolean } };
+  findings: (JsonDocument & { id: string; finding_kind: "artifact_defect" | "caution" | "evidence_gap"; severity: string })[];
+  provenance: JsonDocument & { analyzer: string; version: string; command: string };
+  evidence_boundary: string;
+  envelope_sha256: string;
+}
+export class DeepBomError extends Error {
+  constructor(message: string, options?: { exitCode?: number | null; document?: JsonDocument | null; cause?: unknown });
+  readonly code: string;
+  readonly exitCode: number | null;
+  document: JsonDocument | null;
+}
+export class DeepBomInvocationError extends DeepBomError {}
+export class DeepBomPolicyBlocked extends DeepBomError {}
+export class DeepBomIncompleteBinding extends DeepBomError {}
+export class DeepBomIdentityMismatch extends DeepBomError {}
+export class DeepBomTimeout extends DeepBomError {}
+export class DeepBomOutputTooLarge extends DeepBomError {}
+export function capabilities(options?: Limits): Promise<JsonDocument>;
+export function inspect(artifact: string, options?: InspectOptions): Promise<ReviewSummary>;
+export function audit(artifact: string, options?: InspectOptions & { output?: "envelope"; sections?: never }): Promise<EvidenceEnvelope>;
+export function audit(artifact: string, options: AuditOptions): Promise<JsonDocument>;
+export function diff(baseline: string, candidate: string, options?: Limits & { tensorsOnly?: boolean }): Promise<JsonDocument>;
+export function captureContract(artifact: string, options?: Limits): Promise<JsonDocument>;
+export function verifyContract(artifact: string, contract: string, options?: Limits): Promise<JsonDocument>;
+export function verifyBom(artifact: string, bom: string, options?: Limits & { componentRef?: string }): Promise<JsonDocument>;

package/sdk/index.mjs

@@ -0,0 +1,172 @@
+/** Public Node SDK. All analysis and policy evaluation run in the packaged CLI. */
+import { spawn } from "node:child_process";
+import { mkdtemp, readFile, rm, stat } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const cli = fileURLToPath(new URL("../bin/deepbom.mjs", import.meta.url));
+const defaults = { timeoutMs: 300_000, maxOutputBytes: 64 * 1024 * 1024 };
+const limitKeys = Object.keys(defaults);
+const auditKeys = [...limitKeys, "scan", "output", "sections", "gate", "policy", "expectedSha256"];
+
+export class DeepBomError extends Error {
+  constructor(message, { exitCode = null, document = null, cause } = {}) {
+    super(message, { cause });
+    this.name = this.constructor.name;
+    this.code = this.constructor.code;
+    this.exitCode = exitCode;
+    this.document = document;
+  }
+  static code = "DEEPBOM_ERROR";
+}
+export class DeepBomInvocationError extends DeepBomError { static code = "INVOCATION_FAILED"; }
+export class DeepBomPolicyBlocked extends DeepBomError { static code = "POLICY_BLOCKED"; }
+export class DeepBomIncompleteBinding extends DeepBomError { static code = "INCOMPLETE_BINDING"; }
+export class DeepBomIdentityMismatch extends DeepBomError { static code = "IDENTITY_MISMATCH"; }
+export class DeepBomTimeout extends DeepBomError { static code = "TIMEOUT"; }
+export class DeepBomOutputTooLarge extends DeepBomError { static code = "OUTPUT_TOO_LARGE"; }
+
+export async function capabilities(options = {}) {
+  checkOptions(options, limitKeys);
+  return invoke(["capabilities", "--compact"], options);
+}
+
+export async function audit(artifact, options = {}) {
+  checkOptions(options, auditKeys);
+  const sections = names(options.sections);
+  const output = choice(options.output ?? (sections.length ? "analysis" : "envelope"), "output", ["analysis", "envelope", "cyclonedx", "sarif"]);
+  if (sections.length && output !== "analysis") throw new TypeError("sections require output='analysis'");
+  if (options.gate != null && options.policy != null) throw new TypeError("gate and policy are mutually exclusive");
+  const argv = ["audit", localPath(artifact), "--scan", choice(options.scan ?? "auto", "scan", ["auto", "structure", "integrity", "full"])];
+  if (sections.length) argv.push("--section", sections.join(","));
+  if (output !== "analysis") argv.push("--output-format", output);
+  argv.push("--compact");
+  if (options.gate != null) argv.push("--gate", choice(options.gate, "gate", ["defects"]));
+  if (options.policy != null) argv.push("--policy", choice(options.policy, "policy", ["engineering", "regulatory"]));
+  if (options.expectedSha256 != null) {
+    if (typeof options.expectedSha256 !== "string" || !/^[0-9a-f]{64}$/i.test(options.expectedSha256)) throw new TypeError("expectedSha256 must contain 64 hexadecimal characters");
+    argv.push("--expected-sha256", options.expectedSha256.toLowerCase());
+  }
+  return invoke(argv, options);
+}
+
+export async function inspect(artifact, options = {}) {
+  checkOptions(options, auditKeys.filter(key => !["output", "sections"].includes(key)));
+  try {
+    return summaryFrom(await audit(artifact, { ...options, sections: ["summary"] }));
+  } catch (error) {
+    // A policy rejection still contains the same summary shape as a success.
+    if (error instanceof DeepBomPolicyBlocked && error.document) error.document = summaryFrom(error.document);
+    throw error;
+  }
+}
+
+export async function diff(baseline, candidate, options = {}) {
+  checkOptions(options, [...limitKeys, "tensorsOnly"]);
+  if (options.tensorsOnly != null && typeof options.tensorsOnly !== "boolean") throw new TypeError("tensorsOnly must be boolean");
+  return invoke(["diff", localPath(baseline), localPath(candidate), "--compact", ...(options.tensorsOnly ? ["--tensors"] : [])], options);
+}
+
+export async function captureContract(artifact, options = {}) {
+  checkOptions(options, limitKeys);
+  return invoke(["contract", "capture", localPath(artifact), "--compact"], options);
+}
+
+export async function verifyContract(artifact, contract, options = {}) {
+  checkOptions(options, limitKeys);
+  return invoke(["verify", localPath(artifact), "--contract", localPath(contract), "--compact"], options);
+}
+
+export async function verifyBom(artifact, bom, options = {}) {
+  checkOptions(options, [...limitKeys, "componentRef"]);
+  const argv = ["verify", localPath(artifact), "--bom", localPath(bom), "--compact"];
+  if (options.componentRef != null) {
+    if (typeof options.componentRef !== "string" || !options.componentRef.trim() || options.componentRef.includes("\0")) throw new TypeError("componentRef must be a non-empty bom-ref");
+    argv.push("--component-ref", options.componentRef.trim());
+  }
+  return invoke(argv, options);
+}
+
+function summaryFrom(selection) {
+  const summary = selection.sections?.summary;
+  if (selection.schema !== "deepbom.analysis_selection.v1" || summary?.schema !== "deepbom.review_summary.v1") {
+    throw new DeepBomInvocationError("The engine returned an incompatible review summary.");
+  }
+  return summary;
+}
+
+function localPath(value) {
+  if (typeof value !== "string" || !value || value.includes("\0") || /^[a-z][a-z0-9+.-]*:\/\//i.test(value)) throw new TypeError("SDK paths must be non-empty local filesystem paths");
+  return path.resolve(value);
+}
+function checkOptions(options, allowed) {
+  if (!options || typeof options !== "object" || ![Object.prototype, null].includes(Object.getPrototypeOf(options))) throw new TypeError("options must be a plain object with own properties");
+  for (const key of Reflect.ownKeys(options)) {
+    if (typeof key !== "string" || !allowed.includes(key)) throw new TypeError(`Unsupported SDK option: ${String(key)}`);
+    if (!Object.getOwnPropertyDescriptor(options, key).enumerable) throw new TypeError(`SDK option must be enumerable: ${key}`);
+  }
+}
+function choice(value, field, allowed) {
+  if (!allowed.includes(value)) throw new TypeError(`${field} must be one of: ${allowed.join(", ")}`);
+  return value;
+}
+function names(values) {
+  if (values == null) return [];
+  if (!Array.isArray(values) || values.some(value => typeof value !== "string" || !/^[a-z0-9_.-]+$/i.test(value))) throw new TypeError("sections must be an array of section names");
+  return [...new Set(values)];
+}
+
+async function invoke(argv, options) {
+  const timeoutMs = options.timeoutMs ?? defaults.timeoutMs;
+  const maxOutputBytes = options.maxOutputBytes ?? defaults.maxOutputBytes;
+  for (const [key, value] of Object.entries({ timeoutMs, maxOutputBytes })) {
+    if (!Number.isSafeInteger(value) || value <= 0 || (key === "timeoutMs" && value > 2_147_483_647)) throw new TypeError(`${key} must be a positive bounded integer`);
+  }
+  let directory;
+  let failure;
+  try {
+    directory = await mkdtemp(path.join(tmpdir(), "deepbom-sdk-"));
+    const output = path.join(directory, "result.json");
+    const { exitCode, diagnostic } = await new Promise((resolve, reject) => {
+      const child = spawn(process.execPath, [cli, ...argv, "--output", output], { shell: false, windowsHide: true, stdio: ["ignore", "ignore", "pipe"] });
+      let diagnostic = Buffer.alloc(0);
+      let timedOut = false;
+      let spawnError;
+      const timer = setTimeout(() => { timedOut = true; child.kill("SIGKILL"); }, timeoutMs);
+      child.stderr.on("data", chunk => { diagnostic = Buffer.concat([diagnostic, chunk]).subarray(-16_384); });
+      child.on("error", error => { spawnError = error; });
+      child.on("close", (exitCode, signal) => {
+        clearTimeout(timer);
+        if (timedOut) reject(new DeepBomTimeout(`DEEPBOM exceeded timeoutMs=${timeoutMs}.`));
+        else if (spawnError) reject(new DeepBomInvocationError("Could not start the packaged DEEPBOM engine.", { cause: spawnError }));
+        else if (signal) reject(new DeepBomInvocationError(`DEEPBOM was terminated by ${signal}.`));
+        else resolve({ exitCode, diagnostic: diagnostic.toString("utf8").trim() });
+      });
+    });
+    let document = null;
+    const info = await stat(output).catch(error => { if (error.code === "ENOENT") return null; throw error; });
+    if (info) {
+      if (info.size > maxOutputBytes) throw new DeepBomOutputTooLarge(`DEEPBOM result is ${info.size} bytes; maxOutputBytes is ${maxOutputBytes}.`, { exitCode });
+      try {
+        document = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(await readFile(output)), (_key, value) => {
+          if (typeof value === "number" && !Number.isFinite(value)) throw new Error("JSON number exceeds the finite floating-point range");
+          return value;
+        });
+      }
+      catch (cause) { throw new DeepBomInvocationError("DEEPBOM returned invalid JSON.", { exitCode, cause }); }
+      if (!document || typeof document !== "object" || Array.isArray(document)) throw new DeepBomInvocationError("DEEPBOM JSON result must be an object.", { exitCode });
+    }
+    if (exitCode === 0 && document) return document;
+    const Failure = { 2: DeepBomPolicyBlocked, 3: DeepBomIncompleteBinding, 4: DeepBomIdentityMismatch }[exitCode] || DeepBomInvocationError;
+    throw new Failure(diagnostic || `DEEPBOM exited ${exitCode} without a usable result.`, { exitCode, document });
+  } catch (error) {
+    failure = error instanceof DeepBomError ? error : new DeepBomInvocationError("Could not invoke or read the packaged DEEPBOM engine.", { cause: error });
+    throw failure;
+  } finally {
+    if (directory) {
+      try { await rm(directory, { recursive: true, force: true }); }
+      catch (cause) { if (!failure) throw new DeepBomInvocationError("Could not clean up DEEPBOM temporary output.", { cause }); }
+    }
+  }
+}