@typecad/framework-zephyr 1.0.0-alpha.16 → 1.0.0-alpha.19

package/dist/sbom.d.ts

@@ -0,0 +1,181 @@
+import { type ReadFile, type ReadDir } from '@typecad/cuttlefish/api/shared';
+export type SbomFormat = 'cyclonedx' | 'spdx';
+/** Options accepted by `runSbomPresenter` (the parsed `typecad-hal sbom`
+ *  command options are structurally compatible). */
+export interface SbomPresenterOptions {
+    format?: SbomFormat;
+    /** Scope to every west manifest module (default: only linked modules). */
+    all?: boolean;
+    /** Exit non-zero on integrity warnings (floating revisions, missing SHAs). */
+    strict?: boolean;
+    /** Verify the recorded CycloneDX SBOM against the current build. */
+    check?: boolean;
+    /** Print the JSON to stdout instead of writing a file. */
+    stdout?: boolean;
+    /** Output path (default: <buildDir>/sbom.cdx.json, or ./sbom.cdx.json). */
+    output?: string;
+    /** Compare two SBOM files instead of generating. */
+    diff?: [string, string];
+}
+/** One `west list` project with its immutable identity. */
+export interface WestModuleRef {
+    name: string;
+    abspath: string;
+    /** Manifest revision (SHA, tag, or branch — see floating-revision warning). */
+    revision?: string;
+    /** Checked-out commit SHA (what the build actually compiled). */
+    sha?: string;
+    url?: string;
+}
+export type SbomWarningKind = 'floating-revision' | 'missing-sha' | 'no-build' | 'unknown-license' | 'west-list-limited';
+export interface SbomWarning {
+    kind: SbomWarningKind;
+    component: string;
+    detail?: string;
+}
+export interface SbomModule {
+    name: string;
+    isKernel: boolean;
+    /** Identity: the checked-out SHA (kernel: friendly version, e.g. 4.3.0). */
+    version: string;
+    sha?: string;
+    revision?: string;
+    url?: string;
+    /** Resolved SPDX license id (absent when undeterminable). */
+    spdx?: string;
+    kernelVersion?: string;
+}
+export interface SbomInventoryMeta {
+    projectName?: string;
+    projectVersion?: string;
+    boardTarget?: string;
+}
+export type SbomInventory = {
+    ok: true;
+    scope: 'linked' | 'all';
+    projectName: string;
+    projectVersion: string;
+    boardTarget?: string;
+    buildDir?: string;
+    artifact?: {
+        path: string;
+        fileName: string;
+        sha256: string;
+        sizeBytes: number;
+    };
+    modules: SbomModule[];
+    tools: {
+        cuttlefish?: string;
+        frameworkZephyr?: string;
+        /** @typecad/hal as installed in THIS project — the API surface the
+         *  firmware source compiled against (part of the generator ladder,
+         *  never a linked runtime component). */
+        hal?: string;
+        sdk?: string;
+    };
+    warnings: SbomWarning[];
+    needsBuild: boolean;
+} | {
+    ok: false;
+    reason: 'no-workspace';
+    message: string;
+};
+/**
+ * Injected seams so the inventory + presenters are unit-testable without
+ * spawning west or touching disk. The production runner (defaultSbomRunner)
+ * wires these to discoverWest + westSpawn + fs + crypto.
+ */
+export interface SbomRunner {
+    /** Directory the project lives in (project name fallback, build search). */
+    cwd?: string;
+    /** Discovered $ZEPHYR_BASE (absolute), or undefined. */
+    zephyrBase?: string;
+    /** west manifest projects with identity fields, or null when west failed. */
+    listModules: () => WestModuleRef[] | null;
+    /** The last build's compile_commands.json path, or undefined. */
+    compileCommandsPath?: () => string | undefined;
+    readFile: ReadFile;
+    readdir: ReadDir;
+    statMtimeMs?: (p: string) => number | null;
+    sha256?: (p: string) => string | null;
+    fileSize?: (p: string) => number | null;
+    /** $ZEPHYR_BASE/VERSION text (kernel friendly version), or undefined. */
+    zephyrVersionText?: () => string | undefined;
+    /** Project package.json text, or undefined. */
+    projectPackageJson?: () => string | undefined;
+    /** Toolchain versions for the formulation block. */
+    toolVersions?: () => {
+        cuttlefish?: string;
+        frameworkZephyr?: string;
+        sdk?: string;
+    };
+}
+/** Parse a Zephyr VERSION file ("VERSION_MAJOR = 4\n...") into "4.3.0". */
+export declare function parseZephyrVersion(text: string | undefined): string | undefined;
+/**
+ * Collect the as-built inventory: kernel + west modules (linked-only by
+ * default), each one's immutable identity + resolved SPDX license, the hashed
+ * firmware artifact, the project identity, and the toolchain versions.
+ * Never throws.
+ */
+export declare function collectSbomInventory(runner: SbomRunner, allModules?: boolean, meta?: SbomInventoryMeta): SbomInventory;
+/**
+ * Deterministic serial number: the same build (same component identities +
+ * artifact hash) always produces the same urn:uuid, so `sbom --check` can
+ * regenerate and compare without false drift from random UUIDs.
+ */
+export declare function sbomSerialNumber(inv: Extract<SbomInventory, {
+    ok: true;
+}>): string;
+export interface SbomBuildOpts {
+    toolVersion: string;
+    /** RFC3339 UTC timestamp (reused verbatim by --check comparisons). */
+    timestamp: string;
+}
+export declare function buildCycloneDXBom(inv: Extract<SbomInventory, {
+    ok: true;
+}>, opts: SbomBuildOpts): Record<string, unknown>;
+export declare function buildSpdxDocument(inv: Extract<SbomInventory, {
+    ok: true;
+}>, opts: SbomBuildOpts): Record<string, unknown>;
+/** Stable stringify: object keys sorted, so regenerated docs compare equal. */
+export declare function canonicalJson(value: unknown): string;
+export interface SbomDiffEntry {
+    /** Stable component identity (`type:name` — NOT the bom-ref, which embeds
+     *  the version and would turn every update into remove+add). */
+    component: string;
+    field: 'version' | 'license' | 'hash';
+    from: string;
+    to: string;
+}
+export interface SbomDiffResult {
+    added: string[];
+    removed: string[];
+    changed: SbomDiffEntry[];
+}
+/** Compare two CycloneDX documents' component sets (added/removed/changed),
+ *  keyed by type:name so a version bump reads as a change, not churn. */
+export declare function diffCycloneDxDocs(a: Record<string, unknown>, b: Record<string, unknown>): SbomDiffResult;
+/**
+ * Parse `west list --format` TSV output into module refs. Empty columns and
+ * west's "N/A" placeholder (e.g. the sha/url of the manifest-imported zephyr
+ * project) become undefined; lines without a name+abspath pair are skipped.
+ * Exported for unit tests.
+ */
+export declare function parseWestListOutput(out: string): WestModuleRef[];
+/**
+ * Write `<buildDir>/sbom.cdx.json` after a successful west build. Best-effort:
+ * any failure returns undefined silently — a missing SBOM never blocks the
+ * build. `runner` is a test seam; production leaves it unset.
+ */
+export declare function stampBuildSbom(args: {
+    buildDir: string;
+    board?: string;
+    projectRoot?: string;
+}, runner?: SbomRunner | null): string | undefined;
+/** @internal Test-only override of the default runner. Pass null to simulate west-not-found. */
+export declare function __setSbomRunnerForTest(runner: SbomRunner | null | undefined): void;
+/** `typecad-hal sbom` presenter: generate (default), --check, or --diff.
+ *  `--stdout` (generate mode) prints ONLY the JSON document — the banner,
+ *  summary, and warnings are suppressed so it is a clean CI pipe. */
+export declare function runSbomPresenter(options: SbomPresenterOptions): void;