@cdxgen/cdxgen 0.0.1 → 13.0.1

package/types/lib/validator/index.d.ts

@@ -0,0 +1,101 @@
+/**
+ * cdx-validate orchestrator.
+ *
+ * Combines cdxgen's existing structural validation
+ * ({@link ./bomValidator.js}) with the compliance rule packs in
+ * {@link ./complianceEngine.js} and (optionally) signature verification from
+ * {@link ../helpers/bomSigner.js}.
+ *
+ * This module exposes a single high-level function, `validateBomAdvanced`,
+ * and helpers to classify the result. It does *not* perform any I/O: the CLI
+ * wrapper (`bin/validate.js`) is responsible for reading the input BOM.
+ */
+/**
+ * Map of severity names to numeric ordering used for severity threshold
+ * comparisons.
+ *
+ * @type {Object<string, number>}
+ */
+declare const SEVERITY_ORDER: Record<string, number>;
+/**
+ * Validate a BOM.
+ *
+ * Validation is done in JavaScript. `cdxrs validate` is deliberately not used:
+ * it rejects BOMs the JS validator accepts and reports its findings on stdout
+ * rather than through the bridge, which turns a disagreement between the two
+ * implementations into an unexplained non-zero exit.
+ *
+ * **No failure mode may abort SBOM generation.**
+ *
+ * @param {object} bomJson Parsed CycloneDX BOM.
+ * @returns {Promise<{ valid: boolean, source: "js", findings: null }>}
+ */
+export declare function validateGeneratedBom(bomJson: object): Promise<{
+    valid: boolean;
+    source: "js";
+    findings: null;
+}>;
+/**
+ * Run structural + compliance validation against a parsed BOM.
+ *
+ * @param {object} bomJson Parsed CycloneDX JSON BOM.
+ * @param {object} [options]
+ * @param {boolean} [options.schema]            Run JSON-Schema validation (default true).
+ * @param {boolean} [options.deep]              Run purl/ref/metadata deep checks (default true).
+ * @param {Array<string>} [options.benchmarks]  Aliases to include in the scorecards (default: all).
+ * @param {Array<string>} [options.categories]  Restrict compliance rules to these categories.
+ * @param {string} [options.minSeverity]        Minimum severity for returned findings.
+ * @param {boolean} [options.includeManual]     Include manual-review findings (default true).
+ * @param {boolean} [options.includePass]       Include passing findings (default false).
+ * @param {string} [options.publicKey]          If set, verify the BOM signature.
+ * @returns {{
+ *   schemaValid: boolean,
+ *   deepValid: boolean,
+ *   signatureVerified: boolean | null,
+ *   signatureDetails: object | null,
+ *   findings: Array<object>,
+ *   allFindings: Array<object>,
+ *   benchmarks: Array<object>,
+ *   summary: object
+ * }}
+ */
+export declare function validateBomAdvanced(bomJson: object, options?: {
+    schema?: boolean;
+    deep?: boolean;
+    benchmarks?: Array<string>;
+    categories?: Array<string>;
+    minSeverity?: string;
+    includeManual?: boolean;
+    includePass?: boolean;
+    publicKey?: string;
+}): {
+    schemaValid: boolean;
+    deepValid: boolean;
+    signatureVerified: boolean | null;
+    signatureDetails: object | null;
+    findings: Array<object>;
+    allFindings: Array<object>;
+    benchmarks: Array<object>;
+    summary: object;
+};
+/**
+ * Decide whether a report should trigger a non-zero CLI exit.
+ *
+ * @param {object} report
+ * @param {object} opts
+ * @param {string} [opts.failSeverity] Severity level at or above which failing findings are considered a failure (default "high").
+ * @param {boolean} [opts.strict]      When true, failing on any `fail` status regardless of severity, and a failing schema/deep validation also counts.
+ * @param {boolean} [opts.requireSignature] Require a valid signature when verification was requested.
+ * @returns {{ shouldFail: boolean, reason: string | null }}
+ */
+export declare function shouldFail(report: object, opts?: {
+    failSeverity?: string;
+    strict?: boolean;
+    requireSignature?: boolean;
+}): {
+    shouldFail: boolean;
+    reason: string | null;
+};
+export { buildBenchmarkReports, evaluateAll } from "./complianceEngine.js";
+export { SEVERITY_ORDER };
+//# sourceMappingURL=index.d.ts.map

package/types/lib/validator/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../lib/validator/index.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAYH;;;;;GAKG;AACH,QAAA,MAAM,cAAc,wBAAuD,CAAC;AA4D5E;;;;;;;;;;;;GAYG;AACH,wBAAsB,oBAAoB,CAAC,OAAO,EAHvC,MAGuC,GAFrC,OAAO,CAAC;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,IAAI,CAAA;CAAE,CAAC,CAKrE;AAoCD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,mBAAmB,CAAC,OAAO,EArBtC,MAqBsC,EAAE,OAAO,AApBvD,CASA,EARA;IAA0B,MAAM,AAAhC,CACA,EADQ,OAAO,CACf;IAA0B,IAAI,AAA9B,CACA,EADQ,OAAO,CACf;IAAgC,UAAU,AAA1C,CACA,EADQ,KAAK,CAAC,MAAM,CAAC,CACrB;IAAgC,UAAU,AAA1C,CACA,EADQ,KAAK,CAAC,MAAM,CAAC,CACrB;IAAyB,WAAW,AAApC,CACA,EADQ,MAAM,CACd;IAA0B,aAAa,AAAvC,CACA,EADQ,OAAO,CACf;IAA0B,WAAW,AAArC,CACA,EADQ,OAAO,CACf;IAAyB,SAAS,AAAlC,CACA,EADQ,MAAM,CACd;CAW4D,GAXlD;IACR,WAAW,EAAE,OAAO,CAAC;IACrB,SAAS,EAAE,OAAO,CAAC;IACnB,iBAAiB,EAAE,OAAO,GAAG,IAAI,CAAC;IAClC,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,QAAQ,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACxB,WAAW,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC3B,UAAU,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAA;CAChB,CA2CH;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAPtB,MAOsB,EAAE,IAAI,GALpC;IAAsB,YAAY,AAAlC,CACA,EADQ,MAAM,CACd;IAAuB,MAAM,AAA7B,CACA,EADQ,OAAO,CACf;IAAuB,gBAAgB,AAAvC,CACA,EADQ,OAAO,CACf;CAEyC,GAF/B;IAAE,UAAU,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CA0B1D;AAED,OAAO,EAAE,qBAAqB,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAC3E,OAAO,EAAE,cAAc,EAAE,CAAC"}

package/types/lib/validator/reporters/annotations.d.ts

@@ -0,0 +1,37 @@
+/**
+ * CycloneDX annotation reporter — embeds findings as `annotations[]` entries
+ * on a copy of the input BOM. Can be reused by `bom-audit`.
+ *
+ * CycloneDX supports the annotation schema from spec version 1.5 onward.
+ */
+/**
+ * Render a set of findings into CycloneDX annotations.
+ *
+ * @param {Array<object>} findings Finding objects emitted by the validator or auditBom engine.
+ * @param {object} bomJson Full CycloneDX BOM (needed for annotator/subject wiring).
+ * @returns {Array<object>} CycloneDX annotation objects.
+ */
+export declare function buildAnnotations(findings: Array<object>, bomJson: object): Array<object>;
+/**
+ * Produce a new BOM object with findings embedded as annotations. The caller
+ * is responsible for writing the result to disk.
+ *
+ * @param {object} bomJson
+ * @param {Array<object>} findings
+ * @returns {object}
+ */
+export declare function renderBom(bomJson: object, findings: Array<object>): object;
+/**
+ * Convenience wrapper matching the signature of the other reporters. The
+ * second argument expects `{ bomJson }` because annotations are BOM-shaped,
+ * not report-shaped.
+ *
+ * @param {object} report Output of validateBomAdvanced().
+ * @param {object} options
+ * @param {object} options.bomJson The BOM to annotate.
+ * @returns {string} JSON string of the annotated BOM.
+ */
+export declare function render(report: object, options?: {
+    bomJson: object;
+}): string;
+//# sourceMappingURL=annotations.d.ts.map

package/types/lib/validator/reporters/annotations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"annotations.d.ts","sourceRoot":"","sources":["../../../../lib/validator/reporters/annotations.js"],"names":[],"mappings":"AAAA;;;;;GAKG;AAyBH;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAJ9B,KAAK,CAAC,MAAM,CAIkB,EAAE,OAAO,EAHvC,MAGuC,GAFrC,KAAK,CAAC,MAAM,CAAC,CAwEzB;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAJtB,MAIsB,EAAE,QAAQ,EAHhC,KAAK,CAAC,MAAM,CAGoB,GAF9B,MAAM,CAUlB;AAED;;;;;;;;;GASG;AACH,wBAAgB,MAAM,CAAC,MAAM,EALlB,MAKkB,EAAE,OAAO,GAHnC;IAAwB,OAAO,EAAvB,MAAM,CACd;CAEwC,GAF9B,MAAM,CAMlB"}

package/types/lib/validator/reporters/console.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Console reporter — renders findings and benchmark scorecards as tables.
+ * Uses cdxgen's internal table helper for lightweight rendering.
+ */
+/**
+ * Produce a human-readable summary of findings.
+ *
+ * @param {Array<object>} findings
+ * @param {object} [options]
+ * @returns {string}
+ */
+export declare function formatFindings(findings: Array<object>, options?: object): string;
+/**
+ * Produce a scorecard table for benchmark reports.
+ *
+ * @param {Array<object>} reports
+ * @returns {string}
+ */
+export declare function formatBenchmarks(reports: Array<object>): string;
+/**
+ * Produce a compact one-line summary for CI logs.
+ *
+ * @param {object} summary
+ * @returns {string}
+ */
+export declare function formatSummary(summary: object): string;
+/**
+ * Render the full report as a single string.
+ *
+ * @param {object} report Output of validateBomAdvanced().
+ * @returns {string}
+ */
+export declare function render(report: object): string;
+//# sourceMappingURL=console.d.ts.map

package/types/lib/validator/reporters/console.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"console.d.ts","sourceRoot":"","sources":["../../../../lib/validator/reporters/console.js"],"names":[],"mappings":"AAAA;;;GAGG;AAoBH;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAJ5B,KAAK,CAAC,MAAM,CAIgB,EAAE,OAAO,AAH7C,CACA,EADQ,MAG0C,GAFxC,MAAM,CAiClB;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAH7B,KAAK,CAAC,MAAM,CAGiB,GAF3B,MAAM,CAmClB;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAH1B,MAG0B,GAFxB,MAAM,CAWlB;AAED;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,MAAM,EAHlB,MAGkB,GAFhB,MAAM,CAkClB"}

package/types/lib/validator/reporters/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Reporter registry — dispatches to the requested reporter.
+ *
+ * Reporters are intentionally kept as independent modules so they can also be
+ * consumed by the BOM audit engine or future validators.
+ */
+import * as annotations from "./annotations.js";
+import * as consoleReporter from "./console.js";
+import * as json from "./json.js";
+import * as sarif from "./sarif.js";
+/**
+ * Map of reporter name → module.
+ */
+export declare const reporters: {
+    console: typeof consoleReporter;
+    json: typeof json;
+    sarif: typeof sarif;
+    annotations: typeof annotations;
+};
+/**
+ * Render a validation report using the named reporter.
+ *
+ * @param {string} name   Reporter identifier.
+ * @param {object} report Output of validateBomAdvanced().
+ * @param {object} [opts] Reporter-specific options.
+ * @returns {string}
+ */
+export declare function render(name: string, report: object, opts?: object): string;
+export { annotations, consoleReporter as console, json, sarif };
+//# sourceMappingURL=index.d.ts.map

package/types/lib/validator/reporters/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../lib/validator/reporters/index.js"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,WAAW,MAAM,kBAAkB,CAAC;AAChD,OAAO,KAAK,eAAe,MAAM,cAAc,CAAC;AAChD,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,KAAK,KAAK,MAAM,YAAY,CAAC;AAEpC;;GAEG;AACH,eAAO,MAAM,SAAS;;;;;CAKrB,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,MAAM,CAAC,IAAI,EALhB,MAKgB,EAAE,MAAM,EAJxB,MAIwB,EAAE,IAAI,AAHtC,CACA,EADQ,MAG8B,GAF5B,MAAM,CAUlB;AAED,OAAO,EAAE,WAAW,EAAE,eAAe,IAAI,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC"}

package/types/lib/validator/reporters/json.d.ts

@@ -0,0 +1,11 @@
+/**
+ * JSON reporter — emits a stable, documented structure for programmatic use.
+ * No dependencies.
+ */
+/**
+ * @param {object} report Output of validateBomAdvanced().
+ * @param {object} [_options] Unused
+ * @returns {string}
+ */
+export declare function render(report: object, _options?: object): string;
+//# sourceMappingURL=json.d.ts.map

package/types/lib/validator/reporters/json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.d.ts","sourceRoot":"","sources":["../../../../lib/validator/reporters/json.js"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,MAAM,EAJlB,MAIkB,EAAE,QAAQ,AAHpC,CACA,EADQ,MAGiC,GAF/B,MAAM,CA4BlB"}

package/types/lib/validator/reporters/sarif.d.ts

@@ -0,0 +1,22 @@
+/**
+ * SARIF 2.1.0 reporter — renders findings as a SARIF log suitable for upload
+ * to GitHub code scanning or any other SARIF-aware consumer.
+ *
+ * No external dependencies. Spec: https://docs.oasis-open.org/sarif/sarif/v2.1.0/
+ */
+/**
+ * Render a validation report as SARIF.
+ *
+ * @param {object} report Output of validateBomAdvanced().
+ * @param {object} [options]
+ * @param {string} [options.toolName]    Override driver name.
+ * @param {string} [options.toolVersion] Driver version to embed.
+ * @param {boolean} [options.includeManual] Include manual-review findings (default false).
+ * @returns {string}
+ */
+export declare function render(report: object, options?: {
+    toolName?: string;
+    toolVersion?: string;
+    includeManual?: boolean;
+}): string;
+//# sourceMappingURL=sarif.d.ts.map

package/types/lib/validator/reporters/sarif.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sarif.d.ts","sourceRoot":"","sources":["../../../../lib/validator/reporters/sarif.js"],"names":[],"mappings":"AAAA;;;;;GAKG;AAgIH;;;;;;;;;GASG;AACH,wBAAgB,MAAM,CAAC,MAAM,EAPlB,MAOkB,EAAE,OAAO,AANnC,CAIA,EAHA;IAAyB,QAAQ,AAAjC,CACA,EADQ,MAAM,CACd;IAAyB,WAAW,AAApC,CACA,EADQ,MAAM,CACd;IAA0B,aAAa,AAAvC,CACA,EADQ,OAAO,CACf;CAEwC,GAF9B,MAAM,CA0ClB"}

package/mod.d.ts

@@ -1,7 +0,0 @@
-/**
- * Name placeholder for cdxgen v13.
- *
- * @returns A message naming the package to install instead
- */
-export declare function placeholderNotice(): string;
-export default placeholderNotice;

package/mod.js

@@ -1,22 +0,0 @@
-/**
- * Name placeholder for cdxgen v13.
- *
- * This package exists so that the `@cdxgen/cdxgen` name is registered on npm
- * and JSR, which is a precondition for configuring trusted publishing (OIDC)
- * on either registry: a trusted publisher is attached to an existing package,
- * so the package has to be created before the real release can use it.
- *
- * It deliberately ships no CLI. cdxgen's binary is called `cdxgen`, and a
- * placeholder that installs an executable of that name would shadow the real
- * tool for anyone who installed this by mistake.
- *
- * @returns {string} A message naming the package to install instead
- */
-export function placeholderNotice() {
-  return (
-    "@cdxgen/cdxgen is a name placeholder. cdxgen v13 has not been released " +
-    "under this name yet — install @cyclonedx/cdxgen instead."
-  );
-}
-
-export default placeholderNotice;