@cdxgen/cdxgen 13.0.0 → 13.1.0

package/types/lib/stages/postgen/introspection/formulationEvidence.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Reader over the BOM's formulation section, the third evidence source.
+ *
+ * Formulation is two things at once, and the distinction governs every
+ * confidence decision downstream. The run-derived half — `type: "platform"`
+ * components recording the toolchain the generating run probed, and the git
+ * provenance components — is what cdxgen itself did. The config-parsed half —
+ * the commands, environment variables and task types under
+ * `formulation[].workflows[]` — is what the repo's CI declares, and a
+ * declared command was never observed to run.
+ *
+ * This module is pure: the BOM and the caller's run facts are the only
+ * inputs, nothing is read from the filesystem, and environment variable
+ * *values* are never touched — names only, because the BOM stores them and
+ * copying them into a report would republish them.
+ */
+/**
+ * Property carrying the id of the run that stamped a BOM's formulation, set
+ * on every formulation workflow by the introspection pass that reflected
+ * over the freshly generated document.
+ *
+ * @type {string}
+ */
+export declare const FORMULATION_RUN_ID_PROPERTY: string;
+/** The formulation record was produced by the run being reflected. */
+export declare const FORMULATION_ORIGIN_SAME_RUN = "same-run";
+/** The formulation record came with a BOM this run did not generate. */
+export declare const FORMULATION_ORIGIN_FOREIGN = "foreign";
+/**
+ * The BOM carries no formulation record at all, which is neither of the
+ * above: there is no evidence to weigh, so every consumer must behave as it
+ * did before formulation became a source.
+ */
+export declare const FORMULATION_ORIGIN_ABSENT = "absent";
+/**
+ * Platform component names, as the environment probes emit them, mapped to
+ * the canonical ecosystem whose row their facts can corroborate. Names not
+ * listed here have no fidelity row to join.
+ *
+ * @type {Readonly<Record<string, string>>}
+ */
+export declare const TOOL_NAME_ECOSYSTEMS: Readonly<Record<string, string>>;
+/**
+ * Resolver executables whose presence in a declared command says a build or
+ * dependency resolution was attempted, mapped to the ecosystem they drive.
+ * Keys are executable basenames, lower-cased.
+ *
+ * @type {Readonly<Record<string, string>>}
+ */
+export declare const RESOLVER_EXECUTABLES: Readonly<Record<string, string>>;
+/**
+ * Whether an `executed` value is a CI action reference such as
+ * `actions/checkout@<sha>` rather than a shell command. An action reference
+ * carries no whitespace, contains a path separator, and names a revision of
+ * the repository after the last separator; a relative-path executable such
+ * as `./mvnw` carries no revision and stays a command.
+ *
+ * @param {string|undefined} executed The executed value of a step command.
+ * @returns {boolean} True when the value names an action, not a command.
+ */
+export declare function isActionReference(executed: string | undefined): boolean;
+/**
+ * The executable a command line starts with, as a bare name.
+ *
+ * @param {string|undefined} commandLine Command line.
+ * @returns {string} Basename of the first whitespace token, or "" when absent.
+ */
+export declare function executableOf(commandLine: string | undefined): string;
+/**
+ * Read the provenance-aware formulation evidence out of a BOM.
+ *
+ * `origin` decides how the evidence may be used. `same-run` means the
+ * formulation describes this very run — its platform components are the same
+ * probes the ledger recorded as `tool.resolved`, so the evidence corroborates
+ * and must never add confidence. `foreign` means the BOM arrived without a
+ * ledger for its generation, and the formulation is the only surviving trace
+ * of what that build attempted. `absent` is neither: the BOM carries no
+ * formulation record, so there is nothing to weigh and every consumer keeps
+ * the behaviour it had before formulation became a source.
+ *
+ * Environment variable names are collected; values are never read.
+ *
+ * @param {Object} bomJson CycloneDX BOM.
+ * @param {Object} [context] Run facts the caller already knows.
+ * @param {string} [context.runId] This reflection's run id, matched against the formulation's marker.
+ * @param {number} [context.ledgerEventCount] Events the ledger holds for this BOM's generation.
+ * @returns {{
+ *   origin: "same-run"|"foreign"|"absent",
+ *   tools: {name: string|undefined, version: string|undefined, source: "probe"}[],
+ *   declaredCommands: {executable: string, commandLine: string, workflow: string|undefined, task: string|undefined, step: string|undefined, source: "ci-config"}[],
+ *   sourceTree: {commit: string|undefined, treeId: string|undefined, fileCount: number}|undefined,
+ *   environmentKeys: string[]
+ * }} The formulation evidence.
+ */
+export declare function readFormulationEvidence(bomJson: Object, context?: {
+    runId?: string;
+    ledgerEventCount?: number;
+}): {
+    origin: "same-run" | "foreign" | "absent";
+    tools: {
+        name: string | undefined;
+        version: string | undefined;
+        source: "probe";
+    }[];
+    declaredCommands: {
+        executable: string;
+        commandLine: string;
+        workflow: string | undefined;
+        task: string | undefined;
+        step: string | undefined;
+        source: "ci-config";
+    }[];
+    sourceTree: {
+        commit: string | undefined;
+        treeId: string | undefined;
+        fileCount: number;
+    } | undefined;
+    environmentKeys: string[];
+};
+/**
+ * The formulation platform entry for the runtime family this reflection runs
+ * on, when the record cannot describe the machine in use: either the
+ * recorded version of the family differs from the runtime actually running,
+ * or the record names other toolchains but no entry of this family at all. A
+ * difference proves the formulation's toolchain record describes a machine
+ * other than the one re-scanning the BOM; it says nothing about the other
+ * toolchains the record names, which no probe of this run observed.
+ *
+ * @param {Object} evidence Formulation evidence from readFormulationEvidence.
+ * @param {Object} runtime The reflection's runtime facts.
+ * @param {string} runtime.name Runtime name, such as "Node.js".
+ * @param {string} runtime.version Runtime version.
+ * @returns {{tool: string, recordedVersion: string|undefined, runtimeVersion: string}|undefined} The mismatching formulation entry, when one exists.
+ */
+export declare function findRuntimeToolMismatch(evidence: Object, runtime: {
+    name: string;
+    version: string;
+}): {
+    tool: string;
+    recordedVersion: string | undefined;
+    runtimeVersion: string;
+} | undefined;
+/**
+ * The declared CI command a formulation records for one ecosystem, if any.
+ * Commands carry no ecosystem tag, so the executable answers: the first
+ * declared command whose executable drives that ecosystem's resolver wins,
+ * in the order the formulation records them.
+ *
+ * @param {Object} evidence Formulation evidence from readFormulationEvidence.
+ * @param {string} ecosystem Canonical ecosystem name.
+ * @returns {Object|undefined} The matching declared command entry.
+ */
+export declare function declaredCommandForEcosystem(evidence: Object, ecosystem: string): Object | undefined;
+//# sourceMappingURL=formulationEvidence.d.ts.map

package/types/lib/stages/postgen/introspection/formulationEvidence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formulationEvidence.d.ts","sourceRoot":"","sources":["../../../../../lib/stages/postgen/introspection/formulationEvidence.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B,EAF9B,MAE0D,CAAC;AAErE,sEAAsE;AACtE,eAAO,MAAM,2BAA2B,aAAa,CAAC;AAEtD,wEAAwE;AACxE,eAAO,MAAM,0BAA0B,YAAY,CAAC;AAEpD;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,WAAW,CAAC;AAElD;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,EAFvB,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAYvC,CAAC;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,EAFvB,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAkDvC,CAAC;AA6BH;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAH/B,MAAM,GAAC,SAGwB,GAF7B,OAAO,CAYnB;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,WAAW,EAH7B,MAAM,GAAC,SAGsB,GAF3B,MAAM,CAKlB;AA6ED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAZpC,MAYoC,EAAE,OAAO,AAXrD,CAGA,EAFA;IAAyB,KAAK,AAA9B,CACA,EADQ,MAAM,CACd;IAAyB,gBAAgB,AAAzC,CACA,EADQ,MAAM,CACd;CAQ0D,GARhD;IACR,MAAM,EAAE,UAAU,GAAC,SAAS,GAAC,QAAQ,CAAC;IACtC,KAAK,EAAE;QAAC,IAAI,EAAE,MAAM,GAAC,SAAS,CAAC;QAAC,OAAO,EAAE,MAAM,GAAC,SAAS,CAAC;QAAC,MAAM,EAAE,OAAO,CAAA;KAAC,EAAE,CAAC;IAC9E,gBAAgB,EAAE;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,GAAC,SAAS,CAAC;QAAC,IAAI,EAAE,MAAM,GAAC,SAAS,CAAC;QAAC,IAAI,EAAE,MAAM,GAAC,SAAS,CAAC;QAAC,MAAM,EAAE,WAAW,CAAA;KAAC,EAAE,CAAC;IAC/J,UAAU,EAAE;QAAC,MAAM,EAAE,MAAM,GAAC,SAAS,CAAC;QAAC,MAAM,EAAE,MAAM,GAAC,SAAS,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAC,GAAC,SAAS,CAAC;IAC9F,eAAe,EAAE,MAAM,EAAE,CAAA;CAC1B,CA2FH;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EANrC,MAMqC,EAAE,OAAO,EAJtD;IAAwB,IAAI,EAApB,MAAM,CACd;IAAwB,OAAO,EAAvB,MAAM,CACd;CAEsD,GAF5C;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,eAAe,EAAE,MAAM,GAAC,SAAS,CAAC;IAAC,cAAc,EAAE,MAAM,CAAA;CAAC,GAAC,SAAS,CAyB/F;AAED;;;;;;;;;GASG;AACH,wBAAgB,2BAA2B,CAAC,QAAQ,EAJzC,MAIyC,EAAE,SAAS,EAHpD,MAGoD,GAFlD,MAAM,GAAC,SAAS,CAW5B"}

package/types/lib/stages/postgen/introspection/markers.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Ecosystem marker detection for the build-introspection reflection step.
+ *
+ * A marker is a manifest or lockfile whose presence on disk proves an
+ * ecosystem was part of the scanned project. Markers drive two verdicts:
+ * an ecosystem with markers but zero components in the BOM is `absent`, and
+ * an ecosystem that has markers but no cdxgen project type at all is a
+ * coverage gap (`unsupported`), which is cdxgen's backlog rather than the
+ * user's problem.
+ *
+ * Detection is deliberately bounded: the scanned directory itself plus one
+ * level of immediate subdirectories. postProcess runs after generation, so a
+ * second full tree walk would be a measurable cost on large repos; markers
+ * deeper than one directory level are simply not seen, which is acceptable
+ * because tier assignment never relies on markers alone when the BOM already
+ * carries the ecosystem's components.
+ */
+/**
+ * Marker table: ecosystem → manifest and lockfile names that indicate the
+ * ecosystem is part of the project. Entries are either exact file names or
+ * `{ suffix }` matchers for extension-driven ecosystems. Ecosystems cdxgen
+ * cannot parse (elm, crystal, nim, perl, r) are included so the reflection
+ * can report them as coverage gaps instead of silently ignoring them.
+ *
+ * @type {Readonly<Record<string, {names: string[], suffixes: string[]}>>}
+ */
+export declare const ECOSYSTEM_MARKERS: Readonly<Record<string, {
+    names: string[];
+    suffixes: string[];
+}>>;
+/** Marker file name → ecosystems claiming it, and marker suffix → claiming
+ * ecosystems, both built once from the table. The name index is exported so
+ * the reflection can recognize marker paths carried in ledger events without
+ * rescanning the filesystem. */
+export declare const MARKERS_BY_NAME: Map<any, any>;
+/**
+ * Detect ecosystem markers under a project directory without walking the full
+ * tree: the directory itself is inspected, then up to
+ * {@link MAX_SUBDIRS_SCANNED} immediate subdirectories in sorted order. Paths
+ * are built with `node:path`, so `markersOnDisk` carries platform-correct
+ * separators.
+ *
+ * @param {string} projectPath Directory that was scanned, when known.
+ * @param {Object} [hooks] Test hooks.
+ * @param {(dirPath: string) => {name: string, directory: boolean}[]} [hooks.listDir] Directory lister override.
+ * @returns {{markersByEcosystem: Map<string, string[]>, scannedDirectories: number}} Marker paths per ecosystem and the number of directories inspected.
+ */
+export declare function detectEcosystemMarkers(projectPath: string, hooks?: {
+    listDir?: (dirPath: string) => {
+        name: string;
+        directory: boolean;
+    }[];
+}): {
+    markersByEcosystem: Map<string, string[]>;
+    scannedDirectories: number;
+};
+//# sourceMappingURL=markers.d.ts.map

package/types/lib/stages/postgen/introspection/markers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markers.d.ts","sourceRoot":"","sources":["../../../../../lib/stages/postgen/introspection/markers.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAUH;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,EAFpB,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE;IAAC,KAAK,EAAE,MAAM,EAAE,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAC,CAAC,CAoFtE,CAAC;AAEH;;;gCAGgC;AAChC,eAAO,MAAM,eAAe,eAAY,CAAC;AAyDzC;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CAAC,WAAW,EALvC,MAKuC,EAAE,KAAK,AAJtD,CAEA,EADA;IAA0E,OAAO,AAAjF,CACA,EADQ,CAAC,OAAO,EAAE,MAAM,KAAK;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,OAAO,CAAA;KAAC,EAAE,CACjE;CAE2D,GAFjD;IAAC,kBAAkB,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAAC,kBAAkB,EAAE,MAAM,CAAA;CAAC,CAoCnF"}

package/types/lib/stages/postgen/introspection/reflect.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Reflection: join what cdxgen did (the build ledger) with what it produced
+ * (the BOM, through the build-fidelity rule pack) and commit to a per-
+ * ecosystem fidelity verdict.
+ *
+ * The two evidence sources are kept independent on purpose. A finding backed
+ * by both the ledger and a BOM-side rule is high confidence; either alone is
+ * lower confidence. A ledger event with no BOM-side corroboration is reported
+ * as an observation, never as a defect: an event says the run degraded
+ * somewhere, but only the BOM shows whether the output paid for it. The
+ * rule-only path is a first-class path — reflecting over a foreign BOM with
+ * no ledger at all still produces a complete verdict.
+ *
+ * Every ecosystem present in the scan is assigned exactly one tier from the
+ * ladder `resolved > lockfile > manifest > heuristic > absent`, or excluded
+ * from scoring entirely as `unsupported` when its markers name an ecosystem
+ * cdxgen has no project type for. Ties break toward the worse tier: a report
+ * that overstates fidelity stops the remediation loop early, while one that
+ * understates it merely costs an extra iteration.
+ */
+/**
+ * The fidelity tier ladder, from healthiest to worst.
+ *
+ * @type {string[]}
+ */
+export declare const FIDELITY_TIERS: string[];
+/**
+ * Ecosystem states. `graded` rows carry a tier below their ceiling and are
+ * the remediation loop's business; `at-ceiling` rows already parse as
+ * completely as their ecosystem permits; `absent` rows produced zero
+ * components for a supported ecosystem and are real failures; `unsupported`
+ * rows are coverage gaps in cdxgen itself, excluded from the score.
+ *
+ * @type {string[]}
+ */
+export declare const ECOSYSTEM_STATES: string[];
+/**
+ * Ecosystems whose best achievable tier is below `resolved`, because the
+ * ecosystem has no resolved graph for cdxgen to read. Any ecosystem not
+ * listed here defaults to a ceiling of `resolved`, so a newly supported
+ * ecosystem fails safe by demanding the most. Every entry below is backed by
+ * a measurement recorded in the deliverable handoff; none is added from
+ * reading a table.
+ *
+ * @type {Readonly<Record<string, string>>}
+ */
+export declare const ECOSYSTEM_CEILINGS: Readonly<Record<string, string>>;
+/**
+ * True when introspection is enabled for a run: the CLI option is set or the
+ * documented environment opt-in is present. Everything in this module sits
+ * behind this check, so a disabled run pays one boolean test.
+ *
+ * @param {Object} options CLI options.
+ * @returns {boolean} True when the reflection should run.
+ */
+export { isIntrospectionEnabled } from "../../../core/buildLedger.js";
+/**
+ * Review a completed run and produce a per-ecosystem fidelity assessment.
+ *
+ * @param {Object} bomJson Generated CycloneDX BOM.
+ * @param {Object} options CLI options.
+ * @param {Object} [context] Overrides for testing.
+ * @param {Object[]} [context.ledgerEvents] Events, defaulting to the sidecar or in-memory ledger.
+ * @param {string} [context.ledgerSource] Force the reported ledger source.
+ * @param {boolean} [context.ledgerComplete] Force the reported ledger completeness.
+ * @param {string} [context.projectPath] Directory scanned, for marker detection.
+ * @param {Object} [context.markerHooks] Directory-lister overrides for marker detection tests.
+ * @returns {Promise<Object>} The reflection document.
+ */
+export declare function reflectOnRun(bomJson: Object, options?: Object, context?: {
+    ledgerEvents?: Object[];
+    ledgerSource?: string;
+    ledgerComplete?: boolean;
+    projectPath?: string;
+    markerHooks?: Object;
+}): Promise<Object>;
+//# sourceMappingURL=reflect.d.ts.map

package/types/lib/stages/postgen/introspection/reflect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reflect.d.ts","sourceRoot":"","sources":["../../../../../lib/stages/postgen/introspection/reflect.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AA6BH;;;;GAIG;AACH,eAAO,MAAM,cAAc,EAFjB,MAAM,EAQf,CAAC;AAWF;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,EAFnB,MAAM,EAOf,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,EAFrB,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CA6BvC,CAAC;AAqIH;;;;;;;GAOG;AACH,OAAO,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AAusBtE;;;;;;;;;;;;GAYG;AACH,wBAAsB,YAAY,CAAC,OAAO,EAV/B,MAU+B,EAAE,OAAO,GATxC,MAS6C,EAAE,OAAO,AAR9D,CAMA,EALA;IAA2B,YAAY,AAAvC,CACA,EADQ,MAAM,EAAE,CAChB;IAAyB,YAAY,AAArC,CACA,EADQ,MAAM,CACd;IAA0B,cAAc,AAAxC,CACA,EADQ,OAAO,CACf;IAAyB,WAAW,AAApC,CACA,EADQ,MAAM,CACd;IAAyB,WAAW,AAApC,CACA,EADQ,MAAM,CACd;CAEmE,GAFzD,OAAO,CAAC,MAAM,CAAC,CAmO3B"}

package/types/lib/stages/postgen/introspection/report.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Renderers over a completed reflection document and its scoring document.
+ *
+ * Every function here is pure: the reflection and scoring documents are the
+ * only evidence inputs, nothing reads the filesystem, the ledger, or the BOM
+ * again, and nothing writes a file. The caller owns serialization and printing,
+ * which is what makes these renderable against a committed fixture without a
+ * temporary directory.
+ *
+ * The markdown report is written for a human reading it in a terminal pager, a
+ * CI log, or a pull-request comment: plain GitHub-flavoured markdown, no HTML,
+ * no emoji, and a verdict line that carries the right impression on its own.
+ * The JSON report is written for the remediation loop: a versioned contract
+ * with stable key order and no content that churns between identical runs, so
+ * an agent can diff consecutive reports to detect progress. Free text is
+ * redacted again here even though the ledger already sanitized it, because
+ * this report is the artifact most likely to be pasted into a chat window.
+ */
+/**
+ * Version of the JSON report contract. Additive fields bump the minor version;
+ * removals or semantic changes bump the major version.
+ *
+ * @type {string}
+ */
+export declare const INTROSPECTION_REPORT_SCHEMA_VERSION: string;
+/**
+ * Derive the overall tier and confidence labels from the scored rows.
+ *
+ * The scoring document publishes a number only. Both labels the reports
+ * publish are the *worst* among the scored rows: one unhealthy ecosystem must
+ * not disappear behind a healthy average, and no report may claim more
+ * confidence than its least-corroborated row. A reflection with no scored
+ * rows carries no verdict at all, so both labels are null.
+ *
+ * @param {Object} scored Scoring document from scoreReflection.
+ * @returns {{tier: string|null, confidence: string|null}} Worst tier and confidence among the scored rows.
+ */
+export declare function overallAssessment(scored: Object): {
+    tier: string | null;
+    confidence: string | null;
+};
+/**
+ * Build the JSON report document, the remediation loop's contract.
+ *
+ * @param {Object} reflection Reflection document from reflectOnRun.
+ * @param {Object} scored Scoring document from scoreReflection.
+ * @param {Object} [options] CLI options that name the run's outputs.
+ * @param {string} [options.output] Path the BOM was written to.
+ * @param {number} [options.introspectFailBelow] CI gate threshold, when configured.
+ * @returns {Object} The report document; serializing it is the caller's job.
+ */
+export declare function buildIntrospectionJson(reflection: Object, scored: Object, options?: {
+    output?: string;
+    introspectFailBelow?: number;
+}): Object;
+/**
+ * Render the markdown report.
+ *
+ * @param {Object} reflection Reflection document from reflectOnRun.
+ * @param {Object} scored Scoring document from scoreReflection.
+ * @param {Object} [options] CLI options that name the run's outputs.
+ * @param {string} [options.output] Path the BOM was written to.
+ * @param {boolean} [options.installDeps] Whether the run installs dependencies.
+ * @returns {string} The complete markdown report.
+ */
+export declare function renderIntrospectionMarkdown(reflection: Object, scored: Object, options?: {
+    output?: string;
+    installDeps?: boolean;
+}): string;
+/**
+ * Render the console summary: a handful of diagnostic lines carrying the
+ * verdict, the remediation counts, and the paths the reports were written
+ * to. The full report never goes to the console.
+ *
+ * @param {Object} scored Scoring document from scoreReflection.
+ * @param {Object} [options] CLI options naming the report outputs.
+ * @param {string} [options.introspectReport] Path of the markdown report.
+ * @param {string} [options.introspectJson] Path of the JSON report.
+ * @returns {string} Newline-terminated lines for the diagnostic stream.
+ */
+export declare function renderIntrospectionConsole(scored: Object, options?: {
+    introspectReport?: string;
+    introspectJson?: string;
+}): string;
+//# sourceMappingURL=report.d.ts.map

package/types/lib/stages/postgen/introspection/report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.d.ts","sourceRoot":"","sources":["../../../../../lib/stages/postgen/introspection/report.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAMH;;;;;GAKG;AACH,eAAO,MAAM,mCAAmC,EAFtC,MAE8C,CAAC;AAwGzD;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAH7B,MAG6B,GAF3B;IAAC,IAAI,EAAE,MAAM,GAAC,IAAI,CAAC;IAAC,UAAU,EAAE,MAAM,GAAC,IAAI,CAAA;CAAC,CAuBxD;AA0XD;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,UAAU,EAPtC,MAOsC,EAAE,MAAM,EAN9C,MAM8C,EAAE,OAAO,AAL/D,CAGA,EAFA;IAAyB,MAAM,AAA/B,CACA,EADQ,MAAM,CACd;IAAyB,mBAAmB,AAA5C,CACA,EADQ,MAAM,CACd;CAEoE,GAF1D,MAAM,CA4ElB;AAoXD;;;;;;;;;GASG;AACH,wBAAgB,2BAA2B,CAAC,UAAU,EAP3C,MAO2C,EAAE,MAAM,EANnD,MAMmD,EAAE,OAAO,AALpE,CAGA,EAFA;IAAyB,MAAM,AAA/B,CACA,EADQ,MAAM,CACd;IAA0B,WAAW,AAArC,CACA,EADQ,OAAO,CACf;CAEyE,GAF/D,MAAM,CA2JlB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EANtC,MAMsC,EAAE,OAAO,AALvD,CAGA,EAFA;IAAyB,gBAAgB,AAAzC,CACA,EADQ,MAAM,CACd;IAAyB,cAAc,AAAvC,CACA,EADQ,MAAM,CACd;CAE4D,GAFlD,MAAM,CAiClB"}

package/types/lib/stages/postgen/introspection/score.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Scoring and remediation ranking over a completed reflection document.
+ *
+ * Every function here is pure: the reflection produced by `reflect.js` is the
+ * only evidence input, the remediation catalog is a static lookup passed in by
+ * the caller, and nothing reads the ledger, the BOM, or the filesystem. The
+ * same reflection therefore always yields the same score, on every runtime.
+ *
+ * The score is the gradient and the tier is the verdict: an ecosystem at its
+ * ceiling scores 100 and emits nothing (a manifest-tier helm chart is a
+ * success, not a nagging opportunity), an unsupported ecosystem is excluded
+ * from the mean entirely (a missing Elm parser is a coverage gap, not a
+ * project defect), and everything else starts from its tier base and loses
+ * points for each tool fact and corroborated degradation the reflection
+ * recorded. Deductions are floored at the tier base minus 15 so a single
+ * ecosystem can never fall out of its tier's band.
+ */
+/**
+ * Base score per fidelity tier, from healthiest to worst.
+ *
+ * @type {Readonly<Record<string, number>>}
+ */
+export declare const TIER_BASE_SCORES: Readonly<Record<string, number>>;
+/**
+ * The fidelity ladder, healthiest first, shared by the rank arithmetic and the
+ * rule-derived target selection.
+ *
+ * @type {Readonly<string[]>}
+ */
+export declare const TIER_LADDER: Readonly<string[]>;
+/**
+ * Closed vocabulary for catalog action kinds. `container` proposes running
+ * cdxgen inside the official image for toolchains that are impractical to
+ * provision on the host.
+ *
+ * @type {Readonly<string[]>}
+ */
+export declare const REMEDIATION_ACTION_KINDS: Readonly<string[]>;
+/**
+ * Action kinds that need outbound network access, and are therefore blocked
+ * when the run was offline or under a command-execution policy.
+ *
+ * @type {ReadonlySet<string>}
+ */
+export declare const NETWORK_ACTION_KINDS: ReadonlySet<string>;
+/**
+ * Provisioners a catalog action can depend on. An action whose `via` names one
+ * of these is blocked when the run recorded the provisioner as unavailable.
+ *
+ * @type {ReadonlySet<string>}
+ */
+export declare const PROVISIONER_TOOLS: ReadonlySet<string>;
+/**
+ * Confidence that the row's verdict reflects reality, derived from the
+ * corroboration between the ledger and the rule pack. `high` needs both
+ * sources on the row, `low` covers an absent or incomplete ledger and
+ * disk-marker-only verdicts, and everything else is `medium`.
+ *
+ * A foreign BOM's formulation is the asymmetric case. It substitutes for the
+ * absent ledger events as primary evidence, which lifts the verdict off the
+ * marker-only floor; because the run was never observed, `medium` is a cap
+ * it can never exceed, and a formulation without a toolchain record leaves
+ * the row at `low`. On a same-run scan the formulation is the ledger's own
+ * evidence reported twice, so it moves nothing in either direction.
+ *
+ * @param {Object} row Ecosystem row.
+ * @param {Object} reflection Reflection document.
+ * @returns {"high"|"medium"|"low"} Confidence label.
+ */
+export declare function confidenceFor(row: Object, reflection: Object): "high" | "medium" | "low";
+/**
+ * Total score deduction for a row: one amount per missing or mismatched tool,
+ * plus one impact-keyed amount per distinct corroborated remediation id. The
+ * catalog supplies the kind behind each id, so a `command.failed` event keeps
+ * its own extra deduction even though the reflection stores degradations by
+ * id.
+ *
+ * @param {Object} row Ecosystem row.
+ * @param {Object|null} catalog Remediation catalog keyed by id.
+ * @returns {{total: number, byRemediationId: Map<string, number>}} Total deduction and the per-remediation split.
+ */
+export declare function deductionsFor(row: Object, catalog: Object | null): {
+    total: number;
+    byRemediationId: Map<string, number>;
+};
+/**
+ * Score one ecosystem row. At-ceiling rows score 100 whatever their tier and
+ * unsupported rows score nothing at all — they sit outside the mean.
+ *
+ * @param {Object} row Ecosystem row.
+ * @param {Object|null} catalog Remediation catalog keyed by id.
+ * @returns {{score: number, base: number, deduction: number, weight: number}|null} Score facts, or null for unsupported rows.
+ */
+export declare function scoreEcosystemRow(row: Object, catalog: Object | null): {
+    score: number;
+    base: number;
+    deduction: number;
+    weight: number;
+} | null;
+export type ResolvedActionVersion = {
+    /**
+     * Declared version, when a source answered.
+     */
+    version: string | undefined;
+    /**
+     * Cascade band that answered.
+     */
+    versionFrom: "mismatch" | "pin" | "expected" | "unresolved";
+    /**
+     * Where the version came from.
+     */
+    versionSource: string | undefined;
+    /**
+     * True when no source answered.
+     */
+    versionSourceMissing: boolean | undefined;
+};
+/**
+ * Order remediations for the loop: the largest expected gain first, then the
+ * largest per-ecosystem recovery, then the most confident evidence, then the
+ * id — a total order, so the sequence is identical no matter how the input
+ * findings were ordered. The per-ecosystem recovery separates entries whose
+ * weighted gains round to the same hundredth.
+ *
+ * @param {Object[]} entries Remediation entries.
+ * @returns {Object[]} Ranked copy of the entries.
+ */
+export declare function rankRemediations(entries: Object[]): Object[];
+/**
+ * Score a completed reflection and rank everything an agent could do next.
+ *
+ * @param {Object} reflection Reflection document from reflectOnRun.
+ * @param {Object|null} catalog Remediation catalog keyed by id (data/remediations.json).
+ * @param {Object} [runContext] Run facts the reflection cannot carry.
+ * @param {boolean} [runContext.secureMode] The run executed under secure mode or a command policy.
+ * @param {boolean} [runContext.inContainer] The run executed inside a container.
+ * @param {boolean} [runContext.offline] Overrides the offline fact derived from the ledger observations.
+ * @param {string[]} [runContext.unavailableProvisioners] Overrides the provisioners derived from the reflection.
+ * @param {Object} [runContext.commandFacts] Project facts the command variables (`{{mvn}}`, `{{gradle}}`, `{{pythonManager}}`, `{{npmClient}}`) resolve from; without them the variables fall back to the plain executables.
+ * @returns {Object} Scoring document with the overall score, per-ecosystem scores, coverage gaps and the ranked remediation list.
+ */
+export declare function scoreReflection(reflection: Object, catalog: Object | null, runContext?: {
+    secureMode?: boolean;
+    inContainer?: boolean;
+    offline?: boolean;
+    unavailableProvisioners?: string[];
+    commandFacts?: Object;
+}): Object;
+//# sourceMappingURL=score.d.ts.map

package/types/lib/stages/postgen/introspection/score.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"score.d.ts","sourceRoot":"","sources":["../../../../../lib/stages/postgen/introspection/score.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAMH;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,EAFnB,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAQvC,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,WAAW,EAFd,QAAQ,CAAC,MAAM,EAAE,CAQzB,CAAC;AAwBH;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,EAF3B,QAAQ,CAAC,MAAM,EAAE,CASzB,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,EAFvB,WAAW,CAAC,MAAM,CAEkD,CAAC;AAE/E;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,EAFpB,WAAW,CAAC,MAAM,CAQ1B,CAAC;AAiEH;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAJtB,MAIsB,EAAE,UAAU,EAHlC,MAGkC,GAFhC,MAAM,GAAC,QAAQ,GAAC,KAAK,CAwCjC;AAgED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAJtB,MAIsB,EAAE,OAAO,EAH/B,MAAM,GAAC,IAGwB,GAF7B;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAC,CAsBjE;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAJ1B,MAI0B,EAAE,OAAO,EAHnC,MAAM,GAAC,IAG4B,GAFjC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAC,GAAC,IAAI,CAgBjF;AAkFE,YAAkB,qBAAqB,GACvC;;;;IAA6B,OAAO,EAAzB,MAAM,GAAC,SAAS,CAC3B;;;;IAAqD,WAAW,EAArD,UAAU,GAAC,KAAK,GAAC,UAAU,GAAC,YAAY,CACnD;;;;IAA6B,aAAa,EAA/B,MAAM,GAAC,SAAS,CAC3B;;;;IAA8B,oBAAoB,EAAvC,OAAO,GAAC,SAAS,CAC9B;CAAA,CAAA;AA+fD;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAH7B,MAAM,EAGuB,GAF3B,MAAM,EAAE,CAWpB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAV/B,MAU+B,EAAE,OAAO,EATxC,MAAM,GAAC,IASiC,EAAE,UAAU,AAR5D,CAMA,EALA;IAA6B,UAAU,AAAvC,CACA,EADQ,OAAO,CACf;IAA6B,WAAW,AAAxC,CACA,EADQ,OAAO,CACf;IAA6B,OAAO,AAApC,CACA,EADQ,OAAO,CACf;IAA8B,uBAAuB,AAArD,CACA,EADQ,MAAM,EAAE,CAChB;IAA4B,YAAY,AAAxC,CACA,EADQ,MAAM,CACd;CAEiE,GAFvD,MAAM,CA0FlB"}

package/types/lib/stages/postgen/introspection/shapeCommand.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Command shaping for remediation actions.
+ *
+ * The remediation catalog authors commands with template variables where the
+ * right value depends on the scanned project: which maven or gradle
+ * executable the repo wraps, which Python manager owns its lock files, which
+ * client npm itself should use. This module substitutes those variables from
+ * a facts object the caller gathered earlier, and names on every shaped
+ * command the detection it relied on, so a reviewer can tell a correct
+ * detection from a lucky default.
+ *
+ * Every function here is pure: the facts object is the only input beyond the
+ * template string, nothing reads the filesystem, and the same facts always
+ * yield the same command. The filesystem reads live in the collector
+ * (`commandFacts.js`).
+ */
+/**
+ * Template variables this module substitutes, beside the `{{version}}` and
+ * `{{major}}` placeholders the version cascade fills.
+ *
+ * @type {Readonly<string[]>}
+ */
+export declare const SHAPE_VARIABLES: Readonly<string[]>;
+/**
+ * Python managers a command can name, with the lock command each catalog
+ * entry pairs the variable with.
+ *
+ * @type {Readonly<string[]>}
+ */
+export declare const PYTHON_MANAGERS: Readonly<string[]>;
+export type CommandFacts = {
+    /**
+     * Directory the facts were gathered from.
+     */
+    projectRoot?: string;
+    /**
+     * Platform the command targets; defaults to posix.
+     */
+    platform?: "posix" | "windows";
+    /**
+     * Wrapper presence facts, executable-bit included for the platform's script.
+     */
+    wrappers?: {
+        mvnw?: boolean;
+        mvnwInexecutable?: boolean;
+        mvnwCmd?: boolean;
+        gradlew?: boolean;
+        gradlewInexecutable?: boolean;
+        gradlewBat?: boolean;
+        composerPhar?: boolean;
+    };
+    /**
+     * The Python manager in play.
+     */
+    pythonManager?: string | undefined;
+    /**
+     * Every manager detected, when two or more compete.
+     */
+    pythonManagerCandidates?: string[];
+    /**
+     * The npm client the project names or locks.
+     */
+    npmClient?: string;
+};
+/**
+ * Shape one command string: substitute the template variables the catalog
+ * authors into it and report which detection drove the result. A command
+ * without any `{{` marker is returned byte-identical and unshaped.
+ *
+ * @param {string} templateCommand Catalog command template.
+ * @param {CommandFacts} [facts] Facts gathered for the scanned project.
+ * @returns {{command: string, shapedBy: string|undefined, shapedNote: string|undefined}} The shaped command, the detection behind it, and the question to surface when shaping could not answer.
+ */
+export declare function shapeCommand(templateCommand: string, facts?: CommandFacts): {
+    command: string;
+    shapedBy: string | undefined;
+    shapedNote: string | undefined;
+};
+//# sourceMappingURL=shapeCommand.d.ts.map

package/types/lib/stages/postgen/introspection/shapeCommand.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shapeCommand.d.ts","sourceRoot":"","sources":["../../../../../lib/stages/postgen/introspection/shapeCommand.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,eAAe,EAFlB,QAAQ,CAAC,MAAM,EAAE,CAazB,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,eAAe,EAFlB,QAAQ,CAAC,MAAM,EAAE,CAEoD,CAAC;AAO7E,YAAkB,YAAY,GAC9B;;;;IAAoB,WAAW,AAA/B,CACA,EADW,MAAM,CACjB;;;;IAA+B,QAAQ,AAAvC,CACA,EADW,OAAO,GAAC,SAAS,CAC5B;;;;IAAoB,QAAQ,AAA5B,CAQA,EAPA;QAA8B,IAAI,AAAlC,CACA,EADW,OAAO,CAClB;QAA8B,gBAAgB,AAA9C,CACA,EADW,OAAO,CAClB;QAA8B,OAAO,AAArC,CACA,EADW,OAAO,CAClB;QAA8B,OAAO,AAArC,CACA,EADW,OAAO,CAClB;QAA8B,mBAAmB,AAAjD,CACA,EADW,OAAO,CAClB;QAA8B,UAAU,AAAxC,CACA,EADW,OAAO,CAClB;QAA8B,YAAY,AAA1C,CACA,EADW,OAAO,CAClB;KAAA,CAAA;;;;IAA8B,aAAa,AAA3C,CACA,EADW,MAAM,GAAC,SAAS,CAC3B;;;;IAAsB,uBAAuB,AAA7C,CACA,EADW,MAAM,EAAE,CACnB;;;;IAAoB,SAAS,AAA7B,CACF,EADa,MAAM,CACnB;CAAA,CAAA;AA2MD;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,eAAe,EAJjC,MAIiC,EAAE,KAAK,AAHhD,CACA,EADQ,YAG6C,GAF3C;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,GAAC,SAAS,CAAC;IAAC,UAAU,EAAE,MAAM,GAAC,SAAS,CAAA;CAAC,CA8BvF"}