@cdxgen/cdxgen 0.0.1 → 13.0.0

package/types/lib/inventory/purl.d.ts

@@ -0,0 +1,313 @@
+/**
+ * The set of purl types that carry validation rules in cdx-purl.
+ *
+ * cdx-purl's `build()` is permissive: it accepts *any* type string (even an
+ * unregistered one like `pkg:nix/...`) without throwing, because the "type"
+ * segment of a Package URL is not restricted by the spec. What distinguishes a
+ * *registered* type is that cdx-purl ships a rule table for it
+ * (`TYPE_RULES_SOURCE`, exposed as `TypedPurls`) — namespace requirements,
+ * permitted qualifiers, and so on. A purl built with an unregistered type
+ * round-trips but gets no type-specific normalization, and more importantly it
+ * identifies a package in a namespace no vulnerability database or advisory
+ * feed recognises.
+ *
+ * Ecosystems cdxgen supports that have no registered type (nix, zig, mojo, and
+ * gleam when it is not published via hex) must therefore emit `pkg:generic/...`
+ * with a `cdx:purl:proposedType` property instead of squatting a type. This set
+ * is the single source of truth for that decision, sourced directly from
+ * cdx-purl so it updates automatically when a type is registered upstream.
+ */
+export declare const REGISTERED_PURL_TYPES: Set<string>;
+/**
+ * Report whether a purl type is registered in cdx-purl's rule table.
+ *
+ * @param {string} type Purl type (the segment after `pkg:`)
+ * @returns {boolean} `true` when the type carries validation rules upstream
+ */
+export declare function purlTypeIsRegistered(type: string): boolean;
+/**
+ * Report whether a purl string uses a type that cdx-purl has registered rules
+ * for. Purls that fail to parse are treated as unregistered rather than
+ * throwing, because the caller is vetting untrusted output.
+ *
+ * @param {string} purlString Purl string to vet
+ * @returns {boolean} `true` when the purl's type is registered upstream
+ */
+export declare function purlTypeIsRegisteredString(purlString: string): boolean;
+/**
+ * Encode a string for safe inclusion in a PackageURL, percent-encoding special characters
+ * while preserving already-encoded `%40` sequences and keeping `:` and `/` unencoded.
+ *
+ * @param {string} s String to encode
+ * @returns {string} Encoded string suitable for use in a PackageURL component
+ */
+export declare function encodeForPurl(s: string): string;
+/**
+ * Build a purl string, returning `null` instead of throwing when the parts do
+ * not form a valid purl.
+ *
+ * cdx-purl is strict: it rejects a maven purl without a groupId, a swift or
+ * golang purl without a namespace, a vscode-extension without a publisher, and
+ * so on. Those rejections are correct and must not be papered over — but they
+ * also must not crash a scan of an otherwise fine project. This helper is the
+ * one sanctioned place to turn a `PurlError` into an absent purl.
+ *
+ * Only `PurlError` is swallowed. Anything else (a `TypeError` from a bad call,
+ * for instance) is a defect in the caller and is rethrown.
+ *
+ * @param {object} parts Purl parts accepted by cdx-purl's `build()`
+ * @returns {string|null} Canonical purl string, or `null` if it is not valid
+ */
+export declare function tryBuildPurl(parts: object): string | null;
+/**
+ * Build a canonical npm purl from a package name and version.
+ *
+ * Prefer this over hand-assembling `pkg:npm/...` strings. Manual assembly has
+ * to re-implement percent-encoding and gets it wrong in ways cdx-purl then
+ * rejects: an unencoded `+` in a semver build-metadata version
+ * (`1.0.0+build.1`) throws `E_INVALID_CHARACTER`, and the scope separator has
+ * to survive encoding. `build()` handles both, so callers pass raw values.
+ *
+ * @param {string} pkgName Package name, optionally scoped (`@scope/name`)
+ * @param {string} [version] Package version, raw and unencoded
+ * @returns {string} Canonical npm purl string
+ */
+export declare function npmPurl(pkgName: string, version?: string): string;
+/**
+ * Detect whether a version string is a concrete version or an MSBuild
+ * expression / NuGet range that names no single version.
+ *
+ * NuGet project files express versions in a small language of their own:
+ * `$(TargetFSharpCoreVersion)` is an MSBuild property that only a build
+ * evaluates, `1.0-*` is a floating range, and `[1.0,2.0)` is an interval.
+ * None of them is a version, so none can be encoded into a purl — the result
+ * would parse but identify no package.
+ *
+ * Callers resolve such a version from a manifest that pins one (paket.lock,
+ * packages.lock.json, project.assets.json, Directory.Packages.props). This
+ * function is the last-resort guard for when no manifest pins it: the purl is
+ * then emitted without a version rather than with a meaningless one.
+ *
+ * It encodes NuGet's syntax specifically, so it belongs to the NuGet helpers
+ * and not to purl construction in general — an ecosystem that allows brackets
+ * or commas in a legitimate version must not have it applied.
+ *
+ * @param {string} version Candidate version
+ * @returns {string|null} The version when concrete, or null to omit it
+ */
+export declare function concreteVersion(version: string): string | null;
+/**
+ * Build a canonical NuGet purl from a package name and version.
+ *
+ * The version is expected to have been resolved from a manifest that pins one.
+ * An MSBuild expression or NuGet range that reaches here unresolved is dropped
+ * by {@link concreteVersion}, leaving a versionless purl that identifies the
+ * package rather than a version-shaped purl that identifies nothing.
+ *
+ * @param {string} name Package name
+ * @param {string} [version] Package version (may be non-concrete)
+ * @returns {string|null} Canonical purl, or null when the name is empty
+ */
+export declare function nugetPurl(name: string, version?: string): string | null;
+/**
+ * Build a canonical PyPI purl from a package name and version.
+ *
+ * PyPI normalises underscores to hyphens in the name component.
+ *
+ * @param {string} name Package name (underscores will be normalised)
+ * @param {string} [version] Package version
+ * @returns {string|null} Canonical purl, or null when invalid
+ */
+export declare function pypiPurl(name: string, version?: string): string | null;
+/**
+ * Identifier a dependency graph uses to reference a PyPI component.
+ *
+ * PyPI names are case-insensitive and treat `_` and `-` as equivalent, so
+ * cdx-purl folds both when it builds the purl. A reference assembled by hand
+ * from the raw name does not, and then names out of the same distribution
+ * disagree: a `zope_interface` requirement points at nothing while the
+ * component is `pkg:pypi/zope-interface`. Deriving the reference from the purl
+ * keeps the graph attached to the components.
+ *
+ * @param {string} name Package name
+ * @param {string} [version] Package version
+ * @returns {string} bom-ref for the component
+ */
+export declare function pypiBomRef(name: string, version?: string): string;
+/**
+ * Build a canonical Maven purl from group, name, and version.
+ *
+ * @param {string} group Group ID (required for Maven)
+ * @param {string} name Artifact ID
+ * @param {string} [version] Version
+ * @param {object} [qualifiers] Optional qualifiers (e.g. `{type: "jar"}`)
+ * @returns {string|null} Canonical purl, or null when invalid
+ */
+export declare function mavenPurl(group: string, name: string, version?: string, qualifiers?: object): string | null;
+/**
+ * Build a purl for a Nix flake input using the registered `generic` type.
+ *
+ * `nix` is not a registered purl type in cdx-purl, so emitting `pkg:nix/...`
+ * would squat a namespace no vulnerability database recognises. Nix inputs are
+ * therefore identified as generic packages, disambiguated by a `vcs_url`
+ * qualifier built from the flake lock, and tagged with a
+ * `cdx:purl:proposedType=nix` property on the component so the intended type is
+ * recoverable. If `nix` is ever registered upstream, callers can switch over
+ * without touching the property scheme.
+ *
+ * Callers pass the already-encoded qualifier values they derived from the lock
+ * node; this helper only owns purl construction.
+ *
+ * @param {string} name Package name
+ * @param {string} [version] Package version (typically the short revision)
+ * @param {object} [qualifiers] Optional qualifiers such as `{ vcs_url }`
+ * @returns {string|null} Canonical purl, or null when invalid
+ */
+export declare function nixGenericPurl(name: string, version?: string, qualifiers?: object): string | null;
+/**
+ * Identifier for a Nix flake project, whose version is not pinned by the flake
+ * itself.
+ *
+ * A flake project is named after its directory. The bom-ref deliberately uses
+ * the `application:name:version` shape (matching `fallbackBomRef`) rather than a
+ * `pkg:` string, because `nix` is not a registered purl type and a bom-ref that
+ * looks like a purl but is not valid would mislead downstream tooling.
+ *
+ * @param {string} name Project name
+ * @returns {string} bom-ref for the component
+ */
+export declare function nixBomRef(name: string): string;
+/**
+ * Build a canonical generic purl from a name.
+ *
+ * @param {string} name Package name
+ * @returns {string|null} Canonical purl, or null when invalid
+ */
+export declare function genericPurl(name: string): string | null;
+/**
+ * Report whether a string is a valid purl according to cdx-purl.
+ *
+ * Use this before writing anything into a CycloneDX `purl` field that did not
+ * come from `build()` — notably when recovering a purl from a `bom-ref`, which
+ * is an opaque identifier and frequently is not a purl at all.
+ *
+ * @param {string} candidate String to test
+ * @returns {boolean} true when cdx-purl parses it
+ */
+export declare function isValidPurl(candidate: string): boolean;
+/**
+ * Parse a purl string, returning `null` instead of throwing when it is invalid.
+ *
+ * The parse-side counterpart of {@link tryBuildPurl}, for callers that have
+ * already assembled a purl string. Only `PurlError` is swallowed.
+ *
+ * @param {string} purlString Candidate purl
+ * @returns {string|null} Canonical purl string, or `null` if it is not valid
+ */
+export declare function tryParsePurl(purlString: string): string | null;
+/**
+ * Build a `bom-ref` for a component that has no valid purl.
+ *
+ * `bom-ref` must be **unique within the document** — CycloneDX uses it as the
+ * key for the dependency graph, so two components sharing one silently merge
+ * their edges. The bare component name is therefore not usable: the syft go
+ * module graph contains eight versions of `go.opencensus.io`, none of which can
+ * carry a golang purl (cdx-purl requires a namespace), and naming them all
+ * `go.opencensus.io` collapsed eight distinct modules into one ref.
+ *
+ * The `type:group/name:version` shape matches the convention already used for
+ * root components (`application:swift-smoke:latest`) and for the dedupe key in
+ * `lib/stages/postgen/ruleEngine.js`.
+ *
+ * @param {object} component Component with `type`, `group`, `name`, `version`
+ * @returns {string} A document-unique, deterministic bom-ref
+ */
+export declare function fallbackBomRef(component: object): string;
+/**
+ * Attach a purl and `bom-ref` to a component, never emitting an invalid purl.
+ *
+ * CycloneDX requires `component.purl` to be a valid Package URL when present,
+ * so a component we cannot build a purl for must omit the field entirely — it
+ * must *not* fall back to the bare name, which is what produced
+ * `"purl": "swift-smoke"` in the swift golden.
+ *
+ * `bom-ref` has no syntax constraint but does have a uniqueness constraint, so
+ * the fallback goes through {@link fallbackBomRef} rather than using the name.
+ *
+ * Any pre-existing `purl` is deleted when the new one is invalid, so a
+ * component cannot retain a stale purl from an earlier enrichment pass.
+ *
+ * @param {object} component Component to mutate
+ * @param {string|null} purlString Canonical purl string, or `null`/`undefined`
+ * @param {string} [fallbackRef] Explicit `bom-ref` override for when there is no purl
+ * @returns {object} The same component, for chaining
+ */
+export declare function applyPurl(component: object, purlString: string | null, fallbackRef?: string): object;
+/**
+ * Sanitize a purl that cdxgen did not author.
+ *
+ * cdxgen ingests components from places it does not control — caxa binary
+ * metadata, existing SBOMs supplied as input, converter output. Those purls can
+ * be invalid (`@cdxgen/caxa` emitted `pkg:generic/...?arch=…&platform=…`, and
+ * `arch`/`platform` are not qualifiers the `generic` type allows), and cdxgen
+ * must neither emit an invalid purl it merely read nor hard-fail on third-party
+ * data.
+ *
+ * Order of preference:
+ *   1. Keep the purl when it is already valid.
+ *   2. Rebuild a canonical purl from the component's own type/group/name/version.
+ *   3. Drop the purl and assign a unique fallback `bom-ref`.
+ *
+ * The original string is preserved in a property whenever it is discarded, so the
+ * provenance of the change is visible in the output rather than silent.
+ *
+ * @param {object} component Component to sanitize in place
+ * @param {string} [purlType] purl type to use when rebuilding (default `generic`)
+ * @returns {object} The same component, for chaining
+ */
+export declare function sanitizeIngestedPurl(component: object, purlType?: string): object;
+/**
+ * Build an `oci` purl from a Docker/OCI repository digest.
+ *
+ * The `oci` type **prohibits** a namespace, so the registry-qualified repository
+ * cannot go in the purl path: `pkg:oci/docker.io/library/alpine@sha256:…` is
+ * invalid. Per the purl spec the name is the repository's last segment, the
+ * version is the digest, and the full repository travels in `repository_url`.
+ *
+ * @param {string} repoDigest e.g. `docker.io/library/alpine@sha256:abc…`
+ * @param {string} [tag] Optional image tag, emitted as the `tag` qualifier
+ * @returns {string|null} Canonical purl, or `null` when one cannot be built
+ */
+export declare function ociPurl(repoDigest: string, tag?: string): string | null;
+/**
+ * Create a PackageURL object from a repository URL string, package type, and version.
+ *
+ * Supports HTTPS URLs, SSH `git@` URLs, Bitbucket SSH URLs, and local paths.
+ * Extracts the namespace (host + path prefix) and repository name from the URL.
+ *
+ * @param {string} type PackageURL type (e.g. `"swift"`, `"generic"`)
+ * @param {string} repoUrl Repository URL string
+ * @param {string} version Package version
+ * @returns {PackageURL|undefined} PackageURL object, or undefined for unsupported URL formats
+ */
+export declare function purlFromUrlString(type: string, repoUrl: string, version: string): PackageURL | undefined;
+/**
+ * NOT IMPLEMENTED YET.
+ * A future method to locate a generic package given some name and properties
+ *
+ * @param {object} apkg Package to locate
+ * @returns Located project with precise purl or the original unmodified input.
+ */
+export declare function locateGenericPackage(apkg: object): object;
+/**
+ * Parse a Conan package reference into purl coordinates.
+ *
+ * Accepts references such as `name/version@user/channel#recipe_revision` and
+ * returns a `[purl, name, version]` tuple, or `[null, null, null]` when the
+ * reference cannot be parsed.
+ *
+ * @param {string} conanPkgRef Conan package reference
+ * @returns {(string|null)[]} Tuple of purl string, package name, and version
+ */
+export declare function mapConanPkgRefToPurlStringAndNameAndVersion(conanPkgRef: string): (string | null)[];
+//# sourceMappingURL=purl.d.ts.map

package/types/lib/inventory/purl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"purl.d.ts","sourceRoot":"","sources":["../../../lib/inventory/purl.js"],"names":[],"mappings":"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"}

package/types/lib/inventory/rustFormulationParser.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Parser for Rust/Cargo and Pixi maturin formulation components.
+ *
+ * Matches `Cargo.toml` and `pyproject.toml` files and converts them into
+ * formulation components carrying build-tool, build-script capability, native
+ * build dependency, and maturin metadata properties.
+ *
+ * @type {{id: string, patterns: string[], parse(files: string[]): {components: Object[]}}}
+ */
+export declare const rustFormulationParser: {
+    id: string;
+    patterns: string[];
+    parse(files: string[]): {
+        components: Object[];
+    };
+};
+//# sourceMappingURL=rustFormulationParser.d.ts.map

package/types/lib/inventory/rustFormulationParser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rustFormulationParser.d.ts","sourceRoot":"","sources":["../../../lib/inventory/rustFormulationParser.js"],"names":[],"mappings":"AAmTA;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB,EAFxB;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAC;IAAC,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG;QAAC,UAAU,EAAE,MAAM,EAAE,CAAA;KAAC,CAAA;CAwBxF,CAAC"}

package/types/lib/inventory/sbomDocument.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Maximum size in bytes (5 MiB) of a third-party SBOM document accepted for parsing.
+ *
+ * @type {number}
+ */
+export declare const MAX_SBOM_DOCUMENT_BYTES: number;
+/**
+ * Parse a third-party SBOM document into components and dependencies.
+ *
+ * Returns null — never throws — when the document is too large, is not JSON, is
+ * not a recognised SBOM shape, or carries nothing worth merging. Every rejection
+ * is reported once, naming the source, so a skipped document is visible rather
+ * than silent.
+ *
+ * @param {string} text Raw document text
+ * @param {Object} [input] Parse inputs
+ * @param {string} [input.source] Provenance label used in warnings (path, entry name or URL)
+ * @param {number} [input.maxBytes] Size bound. Defaults to `MAX_SBOM_DOCUMENT_BYTES`
+ * @returns {{components: Object[], dependencies: Object[], format: string, rootRef: (string|undefined)}|null}
+ */
+export declare function parseSbomDocument(text: string, { source, maxBytes }?: {
+    source?: string;
+    maxBytes?: number;
+}): {
+    components: Object[];
+    dependencies: Object[];
+    format: string;
+    rootRef: (string | undefined);
+} | null;
+/**
+ * Repair the purl of a component read from a third-party document.
+ *
+ * Producers write a `download_url` as a bare URL, but a purl qualifier value is
+ * percent-encoded, so an unescaped `://` makes the whole purl unparseable. A
+ * `file:` URL is dropped instead of escaped: it names a path on the machine
+ * that built the document, so it identifies nothing for a reader of the BOM.
+ * Versions are escaped for build metadata in either case.
+ *
+ * A purl that is still unparseable afterwards is split on its separators and
+ * rebuilt, which escapes any remaining reserved character wherever it sits —
+ * a shared-library name such as `libstdc++.so.6`, for instance.
+ *
+ * @param {object} component Component whose purl is rewritten in place
+ */
+export declare function repairPurl(component: object): void;
+/**
+ * Attach provenance properties to every component of a parsed document. The
+ * caller owns the property names so each provenance channel stays
+ * distinguishable in the merged BOM.
+ *
+ * @param {Object[]} components Components from `parseSbomDocument`
+ * @param {Array<{name: string, value: string}>} properties Properties to add
+ * @returns {Object[]} The same array, with properties attached
+ */
+export declare function tagSbomComponents(components: Object[], properties: Array<{
+    name: string;
+    value: string;
+}>): Object[];
+//# sourceMappingURL=sbomDocument.d.ts.map

package/types/lib/inventory/sbomDocument.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sbomDocument.d.ts","sourceRoot":"","sources":["../../../lib/inventory/sbomDocument.js"],"names":[],"mappings":"AAqBA;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,EAF1B,MAE4C,CAAC;AAsBvD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAPK,MAOL,EACJ,EAAE,MAAkB,EAAE,QAAkC,EAAE,AAPzD,CAGA,EAFA;IAAuB,MAAM,AAA7B,CACA,EADQ,MAAM,CACd;IAAuB,QAAQ,AAA/B,CACA,EADQ,MAAM,CACd;CAI8D,GAJpD;IAAC,UAAU,EAAE,MAAM,EAAE,CAAC;IAAC,YAAY,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,CAAC,MAAM,GAAC,SAAS,CAAC,CAAA;CAAC,GAAC,IAAI,CAoE5G;AA6FD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,UAAU,CAAC,SAAS,EAFzB,MAEyB,QAsBnC;AAsDD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAJjC,MAAM,EAI2B,EAAE,UAAU,EAH7C,KAAK,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAC,CAGU,GAF3C,MAAM,EAAE,CAoBpB"}

package/types/lib/inventory/source.d.ts

@@ -0,0 +1,163 @@
+/** Warning emitted for repository URLs resolved from untrusted package registry metadata. */
+export declare const PURL_REGISTRY_LOOKUP_WARNING = "Resolved repository URL from package registry metadata. This source can be inaccurate or malicious; review before trusting results.";
+/** Purl types supported for source repository resolution. */
+export declare const SUPPORTED_PURL_SOURCE_TYPES: string[];
+/**
+ * Validate git ref names used as branch/tag values.
+ *
+ * @param {string|undefined} refName branch or tag name
+ * @returns {boolean} true if safe
+ */
+export declare function isSafeGitRefName(refName: string | undefined): boolean;
+/**
+ * Execute git with hardened defaults.
+ *
+ * @param {string[]} args git arguments
+ * @param {Object} options command options
+ * @param {string|undefined} options.cwd working directory
+ * @returns {Object} spawn result
+ */
+export declare function hardenedGitCommand(args: string[], options?: {
+    cwd: string | undefined;
+}): Object;
+/**
+ * Build CycloneDX release notes from git tags and commits.
+ *
+ * @param {string|undefined} repoPath local repository path
+ * @param {Object} options options carrying release notes hints
+ * @returns {Object|undefined} releaseNotes object
+ */
+export declare function buildReleaseNotesFromGit(repoPath: string | undefined, options?: Object): Object | undefined;
+/**
+ * Return git allow protocol string from the environment variables.
+ *
+ * @returns {string} git allow protocol string
+ */
+export declare function getGitAllowProtocol(): string;
+/**
+ * Checks the given hostname against the allowed list.
+ *
+ * @param {string} hostname Host name to check
+ * @returns {boolean} true if the hostname in its entirety is allowed. false otherwise.
+ */
+export declare function isAllowedHost(hostname: string): boolean;
+/**
+ * Checks the given path string to belong to a drive in Windows.
+ *
+ * @param {string} p Path string to check
+ * @returns {boolean} true if the windows path belongs to a drive. false otherwise (device names)
+ */
+export declare function isAllowedWinPath(p: string): boolean;
+/**
+ * Checks the given path against the allowed list.
+ *
+ * @param {string} p Path string to check
+ * @returns {boolean} true if the path is present in the allowed paths. false otherwise.
+ */
+export declare function isAllowedPath(p: string): boolean;
+/**
+ * Determine if the path could be a package URL.
+ *
+ * @param {string} filePath Path or URL
+ * @returns {boolean} true if the file path looks like a purl
+ */
+export declare function maybePurlSource(filePath: string): boolean;
+/**
+ * Determine if the file path could be a remote URL.
+ *
+ * @param {string} filePath The Git URL or local path
+ * @returns {boolean} true if the file path is a remote URL. false otherwise.
+ */
+export declare function maybeRemotePath(filePath: string): boolean;
+/**
+ * Validates a given Git URL/Path against dangerous protocols and allowed hosts.
+ *
+ * @param {string} filePath The Git URL or local path
+ * @returns {Object|null} Error object if invalid, or null if valid
+ */
+export declare function validateAndRejectGitSource(filePath: string): Object | null;
+/**
+ * Clone a git repository into a temporary directory.
+ *
+ * @param {string} repoUrl Repository URL
+ * @param {string|string[]|null} branch Branch name
+ * @returns {string} cloned directory path
+ */
+export declare function gitClone(repoUrl: string, branch?: string | string[] | null): string;
+/**
+ * Sanitize remote URL for logging.
+ *
+ * @param {string|undefined} remoteUrl Repository URL
+ * @returns {string|undefined} sanitized URL
+ */
+export declare function sanitizeRemoteUrlForLogs(remoteUrl: string | undefined): string | undefined;
+/**
+ * Find a matching git ref for a package version.
+ *
+ * @param {string} repoUrl Repository URL
+ * @param {Object|undefined} purlResolution purl resolution metadata
+ * @returns {string|undefined} matching tag or branch reference
+ */
+export declare function findGitRefForPurlVersion(repoUrl: string, purlResolution: Object | undefined): string | undefined;
+/**
+ * Find the best source directory for purl-based npm monorepo scans.
+ *
+ * @param {string} srcDir cloned source directory
+ * @param {Object|undefined} purlResolution purl resolution metadata
+ * @returns {string|undefined} preferred source directory
+ */
+export declare function resolvePurlSourceDirectory(srcDir: string, purlResolution: Object | undefined): string | undefined;
+/**
+ * Validate package URL source input and return an error object when invalid.
+ *
+ * @param {string} purlString package URL string
+ * @returns {{status:number,error:string,details:string}|null} validation error or null
+ */
+export declare function validatePurlSource(purlString: string): {
+    status: number;
+    error: string;
+    details: string;
+} | null;
+/**
+ * Discard prefetched registry documents. Tests only.
+ */
+export declare function resetGitUrlSourcePrefetch(): void;
+/**
+ * Prefetch the registry documents a list of purls will be resolved from.
+ *
+ * `resolveGitUrlFromPurl` takes a single purl, so on its own it can only ever
+ * make one request at a time. Callers that know the whole list up front — the
+ * predictive audit knows every target before it starts — can hand it over here
+ * and have the documents fetched in one round instead.
+ *
+ * @param {Array<string>} purlStrings Purls about to be resolved. Duplicates,
+ *   empties and unparseable entries are fine.
+ * @returns {Promise<void>}
+ */
+export declare function prefetchGitUrlSources(purlStrings: Array<string>): Promise<void>;
+/**
+ * Resolve source repository details for a package from its purl.
+ *
+ * Queries the package registry (or constructs the URL directly for VCS-hosted
+ * purl types) and normalizes the repository or homepage URL found in registry
+ * metadata. Network and lookup failures are logged and yield `undefined`.
+ *
+ * @param {string} purlString Package URL string
+ * @param {Object} [helpers={}] Injected registry helpers (e.g. `fetchPomXmlAsJson` required for maven)
+ * @returns {Promise<{type: string, registry: string, repoUrl: string, version: string, namespace: string, name: string}|undefined>} Resolved source details, or `undefined` when no remote repository URL could be resolved
+ */
+export declare function resolveGitUrlFromPurl(purlString: string, helpers?: Object): Promise<{
+    type: string;
+    registry: string;
+    repoUrl: string;
+    version: string;
+    namespace: string;
+    name: string;
+} | undefined>;
+/**
+ * Clean up cloned source directories.
+ *
+ * @param {string} srcDir directory path to remove
+ */
+export declare function cleanupSourceDir(srcDir: string): void;
+//# sourceMappingURL=source.d.ts.map

package/types/lib/inventory/source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source.d.ts","sourceRoot":"","sources":["../../../lib/inventory/source.js"],"names":[],"mappings":"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"}

package/types/lib/inventory/spdx.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Parsed list of SPDX license identifiers loaded from `data/spdx-licenses.json`.
+ *
+ * @type {string[]}
+ */
+export declare const spdxLicenses: string[];
+/**
+ * Method to determine if a license is a valid SPDX license expression
+ *
+ * @param {string} license License string
+ * @returns {boolean} true if the license is a valid SPDX license expression
+ * @see https://spdx.dev/learn/handling-license-info/
+ **/
+export declare function isSpdxLicenseExpression(license: string): boolean;
+/**
+ * Convert the array of licenses to a CycloneDX 1.5 compliant license array.
+ * This should return an array containing:
+ * - one or more SPDX license if no expression is present
+ * - the license of the expression if one expression is present
+ * - a unified conditional 'OR' license expression if more than one expression is present
+ *
+ * @param {Array} licenses Array of licenses
+ * @returns {Array} CycloneDX 1.5 compliant license array
+ */
+export declare function adjustLicenseInformation(licenses: any[]): any[];
+/**
+ * Performs a lookup + validation of the license specified in the
+ * package. If the license is a valid SPDX license ID, set the 'id'
+ * and url of the license object, otherwise, set the 'name' of the license
+ * object.
+ */
+export declare function getLicenses(pkg: any): any[] | undefined;
+/**
+ * Method to retrieve known license by known-licenses.json
+ *
+ * @param {String} licenseUrl Repository url
+ * @param {String} pkg Bom ref
+ * @return {Object} Objetct with SPDX license id or license name
+ */
+export declare function getKnownLicense(licenseUrl: string, pkg: string): Object;
+/**
+ * Tries to find a file containing the license text based on commonly
+ * used naming and content types. If a candidate file is found, add
+ * the text to the license text object and stop.
+ */
+export declare function addLicenseText(pkg: any, l: any, licenseContent: any): void;
+/**
+ * Read the file from the given path to the license text object and includes
+ * content-type attribute, if not default. Returns the license text object.
+ */
+export declare function readLicenseText(licenseFilepath: any, licenseContentType: any): {
+    content: any;
+} | null;
+/**
+ * Method to find the spdx license id from name
+ *
+ * @param {string} name License full name
+ */
+export declare function findLicenseId(name: string): any;
+/**
+ * Method to guess the spdx license id from license contents
+ *
+ * @param {string} content License file contents
+ */
+export declare function guessLicenseId(content: string): any;
+//# sourceMappingURL=spdx.d.ts.map

package/types/lib/inventory/spdx.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spdx.d.ts","sourceRoot":"","sources":["../../../lib/inventory/spdx.js"],"names":[],"mappings":"AAeA;;;;GAIG;AACH,eAAO,MAAM,YAAY,EAFf,MAAM,EAIf,CAAC;AAMF;;;;;;IAMI;AACJ,wBAAgB,uBAAuB,CAAC,OAAO,EAJpC,MAIoC,GAHlC,OAAO,CA0BnB;AAED;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,OAAA,SA2BhD;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,GAAG,KAAA,qBAqG9B;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,UAAU,QAAA,EAAE,GAAG,QAAA,GAFnC,MAAM,CAoDjB;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,GAAG,KAAA,EAAE,CAAC,KAAA,EAAE,cAAc,KAAA,QAoCpD;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,eAAe,KAAA,EAAE,kBAAkB,KAAA;;SAUlE;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAFvB,MAEuB,OAYjC;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAF3B,MAE2B,OAUrC"}