@codacy/analysis-runner 0.23.0 → 0.24.0

package/dist/index.d.ts

@@ -1,6 +1,222 @@
-import { OutputFormat, Logger, ProxyConfig, AnalysisResult, ToolAdapter, AdapterDescriptor, CodacyConfig, ConfigurationFileCheckResult, CodacyToolConfig, IssueSeverity, IssueCategory, Language, DiscoveryResult, PatternEntry, Issue, PatternSummary, LogLevel } from '@codacy/tooling';
+import { AdapterDescriptor, ToolAdapter, CodacyConfig, CodacyToolConfig, Logger, OutputFormat, ProxyConfig, AnalysisResult, AnalysisError, PatternEntry, ConfigurationFileCheckResult, IssueSeverity, IssueCategory, Language, DiscoveryResult, Issue, PatternSummary, LogLevel, ImageScanPkgType, ImageScanSeverity, SbomFormat } from '@codacy/tooling';
 export { AnalysisResult, OutputFormat, ProxyConfig, configureProxy, resolveProxyConfig } from '@codacy/tooling';
 
+/**
+ * `.codacyrc` — the analysis configuration Codacy's cloud runners bind-mount
+ * into a tool container at `/`.
+ *
+ * This module owns the whole ingestion path, so the production entry point
+ * (`analyze --codacyrc`) and the debugging one (`init --container`) cannot drift
+ * apart. The wire format is the one the four engine seeds implement and
+ * `codacy-plugins-api` defines — **not** our own `codacy.config.json` shape,
+ * which is what the previous implementation mistakenly parsed:
+ *
+ * ```jsonc
+ * {
+ *   "files": ["src/a.py"],                       // relative to /src
+ *   "tools": [{
+ *     "name": "ruff",                            // Codacy short-name, not our adapter id
+ *     "patterns": [{
+ *       "patternId": "S102_exec-builtin",        // unprefixed
+ *       "parameters": [{ "name": "threshold", "value": 10 }]   // array, not a map
+ *     }]
+ *   }],
+ *   "options": { }
+ * }
+ * ```
+ *
+ * See `docs/container-run.md` for how this was established and why each
+ * difference matters.
+ */
+
+/** A pattern parameter as `.codacyrc` writes it: a named value, not a map entry. */
+interface CodacyrcParameter {
+    name: string;
+    /** Any JSON scalar. `Parameter.Value` is an open trait in plugins-api. */
+    value: unknown;
+}
+/** One configured pattern. `parameters` absent means "the spec defaults". */
+interface CodacyrcPattern {
+    patternId: string;
+    parameters?: CodacyrcParameter[];
+}
+/**
+ * One tool's configuration.
+ *
+ * `patterns` **absent** is not the same as `[]` in the seeds — absent means "use
+ * your own configuration file, or your defaults". We treat both as "no Codacy
+ * patterns", which leaves the tool running only if it finds its own native
+ * config file; see {@link resolveCodacyrc}.
+ */
+interface CodacyrcTool {
+    name: string;
+    patterns?: CodacyrcPattern[];
+}
+/** The parsed `.codacyrc` document. */
+interface Codacyrc {
+    /**
+     * Tri-state. Absent ⇒ discover normally; `[]` ⇒ analyze nothing; non-empty ⇒
+     * exactly these. Never collapse the first two — they are opposites.
+     */
+    files?: string[];
+    tools?: CodacyrcTool[];
+    /** Tool-level options. Parsed so an unknown key is never fatal; unused today. */
+    options?: Record<string, unknown>;
+}
+/** How {@link resolveCodacyrc} finds adapters. Injectable so tests need no registry. */
+interface AdapterLookup {
+    descriptors: readonly AdapterDescriptor[];
+    load(toolId: string): Promise<Readonly<ToolAdapter> | undefined>;
+}
+/** The default lookup, over the process-wide adapter registry. */
+declare function registryLookup(): AdapterLookup;
+/** What {@link resolveCodacyrc} produced, and what it could not make sense of. */
+interface CodacyrcResolution {
+    /** The in-memory config to hand to `analyze()`. Never written to disk. */
+    config: CodacyConfig;
+    /** Adapter ids configured from the file, in `.codacyrc` order. */
+    matchedToolIds: string[];
+    /** `tools[].name` values that named no local adapter (cloud-only, or unknown). */
+    unmatchedToolNames: string[];
+    /** Pattern ids the adapter's catalogue does not contain. Passed through anyway. */
+    unknownPatterns: Array<{
+        toolId: string;
+        patternId: string;
+    }>;
+    /** `options`, parsed and carried so a caller can log it. Not applied. */
+    options: Record<string, unknown>;
+}
+/**
+ * Parses `.codacyrc` content.
+ *
+ * Accepts base64-encoded JSON as a fallback. No seed documents this and Codacy
+ * does not send it, but the previous implementation accepted it and it costs
+ * nothing to keep; it is not a supported part of the contract.
+ *
+ * Throws on content that is neither — a malformed configuration must fail loudly
+ * rather than silently degrade to "analyze nothing", which is indistinguishable
+ * from a clean run.
+ */
+declare function parseCodacyrc(raw: string, label?: string): Codacyrc;
+/**
+ * Reads and parses a `.codacyrc`, or returns `null` when there is none.
+ *
+ * A missing file is not an error — every seed treats it as "no configuration
+ * supplied". Any other read failure (a directory, a permission problem) is
+ * rethrown, since it means the caller pointed us somewhere wrong.
+ */
+declare function readCodacyrc(filePath: string): Promise<Codacyrc | null>;
+/**
+ * Resolves a `.codacyrc` `tools[].name` to a registered adapter.
+ *
+ * Tries exact `shortName`, then case-insensitive `shortName`, then the same on
+ * the adapter id — the id fallback is what lets a hand-written debugging
+ * `.codacyrc` name `Ruff`, and what covers an adapter with no catalog entry at
+ * all (`dummy-1`).
+ *
+ * Deliberately **not** the registry's `resolveEntry`: that matches by
+ * case-insensitive *substring*, so `"pmd"` is ambiguous between `PMD` and `PMD7`
+ * and `"eslint-8"` matches nothing. Cloud-only descriptors are skipped — they
+ * have no analyzer, so resolving to one would configure a tool that can never run.
+ */
+declare function resolveToolName(name: string, descriptors: readonly AdapterDescriptor[]): AdapterDescriptor | undefined;
+/**
+ * Turns a parsed `.codacyrc` into the `CodacyConfig` `analyze()` consumes.
+ *
+ * ## What is configured
+ *
+ * **Only tools `.codacyrc` actually names.** There is no "run with your defaults"
+ * fallback: no `tools`, or no entry this container recognizes, means nothing is
+ * configured and nothing runs. A named tool with no patterns gets an entry with
+ * an empty pattern list, which `buildToolConfig` still pairs with the tool's own
+ * native config file if the repository has one — so "run with your own config"
+ * works, while "run with a pattern set we guessed" does not. That is a deliberate
+ * deviation from the seeds, chosen because the outcome is predictable rather than
+ * depending on which patterns our committed catalogue happens to mark `enabled`.
+ *
+ * `toolIds`, when given, restricts resolution to this container's own tool(s), so
+ * a `.codacyrc` listing several tools configures only the one this image is.
+ *
+ * ## What is translated
+ *
+ * Pattern ids come in unprefixed and go out in our vocabulary; parameters come in
+ * as `[{name, value}]` and go out as a string map, with the pattern's declared
+ * defaults filled in. An id the adapter's catalogue does not contain is **passed
+ * through and reported**, never dropped — `patterns.json` is a committed snapshot
+ * and a newer tool binary can legitimately know rules it does not.
+ */
+declare function resolveCodacyrc(codacyrc: Codacyrc | null, opts?: {
+    toolIds?: string[];
+    lookup?: AdapterLookup;
+    logger?: Logger;
+}): Promise<CodacyrcResolution>;
+/**
+ * One tool's contribution to an emitted `.codacyrc`, as `analyze()` resolved it.
+ *
+ * Both halves come from the same point in the run — the routed file list and the
+ * tool config that was actually handed to the adapter — which is what makes the
+ * emitted file describe the run rather than re-derive it.
+ */
+interface CodacyrcToolInput {
+    /** The adapter that ran. `shortName` becomes `tools[].name`; the catalogue re-types parameters. */
+    adapter: Pick<ToolAdapter, "id" | "shortName" | "patternsMetadata">;
+    /** The config `buildToolConfig` produced: our prefixed pattern ids, string parameters. */
+    toolConfig: CodacyToolConfig;
+    /** What `routeFilesToTool` handed this adapter, relative to the repository root. */
+    files: readonly string[];
+}
+/**
+ * Builds the `.codacyrc` describing a run — the inverse of {@link resolveCodacyrc}.
+ *
+ * Lives beside the parser so the two halves of one wire format cannot drift; a
+ * round-trip test pins `resolveCodacyrc(parse(serialize(build(x))))` against the
+ * config `x` came from.
+ *
+ * Three things are inverted, each mirroring something the ingestion path does:
+ *
+ * - `toolId` → `tools[].name`, via the adapter's Codacy short-name. Falls back to
+ *   the adapter id (which {@link resolveToolName} also accepts) and warns, since
+ *   a name the engine does not recognize makes it silently run nothing.
+ * - Our prefixed pattern ids → the engine's vocabulary, via `toEnginePatternId`.
+ *   Conditional on the prefix, so the unprefixed tools (Brakeman, detekt, Reek,
+ *   RuboCop) pass through rather than gaining one they have never heard of.
+ * - The `Record<string, string>` parameter map → `[{name, value}]` with the
+ *   pattern's declared defaults filled in and JSON types restored. Defaults are
+ *   written out explicitly on purpose: if our catalogue and the engine image's
+ *   `docs/patterns.json` disagree about one, that shows up as a visible parameter
+ *   instead of a silent behavioural difference.
+ *
+ * `files` is the **union** of the per-tool routed lists. `.codacyrc` has one file
+ * list shared by every entry in `tools[]`, so a multi-tool emit is a superset for
+ * each of them individually — every consumer, ours included, routes within it.
+ * Emit for a single tool when the list needs to be exact.
+ *
+ * A tool running from its own native config file emits `"patterns": []`, which the
+ * contract reads as "use your own configuration file" — and that is what actually
+ * happened, so it is what the file must say. `buildToolConfig` leaves the config's
+ * `patterns` array intact when it finds a native config (`config.ts`, which spreads
+ * `existing` and then sets `useLocalConfigurationFile`), while adapters ignore those
+ * patterns entirely in that case (`eslint-9/src/adapter.ts`: `if (usingLocalConfig)
+ * … else if (codacyConfig.patterns.length > 0)`). Emitting them anyway would
+ * describe a pattern set that did not drive the run, and an engine image — which
+ * sees the same bind-mounted config file but reads `.codacyrc` first — could then
+ * legitimately analyze against the patterns while we analyzed against the file.
+ * That is precisely the divergence this flag exists to rule out.
+ *
+ * Pure: no I/O, and `options` is not emitted, since nothing carries it through a
+ * run to reproduce.
+ */
+declare function buildCodacyrc(tools: readonly CodacyrcToolInput[], opts?: {
+    logger?: Logger;
+}): Codacyrc;
+/**
+ * Serializes a `.codacyrc` for writing.
+ *
+ * Indented with a trailing newline: unlike the JSONL on stdout, this file is read
+ * by people and diffed, and it is what gets bind-mounted into an engine image.
+ */
+declare function serializeCodacyrc(codacyrc: Codacyrc): string;
+
 /**
  * Main analysis entry point — orchestrates the full analysis pipeline.
  *
@@ -31,9 +247,27 @@ interface AnalyzeOptions {
     toolTimeout?: number;
     /** Maximum number of tools to run in parallel. 1 = sequential. Defaults to 1. */
     parallelTools?: number;
-    /** Target execution environment. "local" = developer machine, "container" = Codacy Docker runner.
-     *  Phase 9 implements the actual container path; this field is accepted but currently ignored. */
+    /**
+     * Target execution environment. `"local"` = developer machine, `"container"` =
+     * Codacy Docker runner.
+     *
+     * Under `"container"` the runner refuses to install anything, keeps its
+     * generated tool configs out of the (read-only, bind-mounted) source directory,
+     * and skips managed-install repair — an image ships its tools pinned and must
+     * not reach the network mid-analysis.
+     */
     runner?: "local" | "container";
+    /**
+     * Pre-resolved configuration, used **instead of** reading one from disk. When
+     * set, `configFile` is ignored and nothing under `.codacy/` is read.
+     *
+     * This is how `analyze --codacyrc` runs without writing into the mounted source
+     * directory. The caller owns validation: unlike `readCodacyConfig`, no shape
+     * assertion, parameter coercion or `localConfigurationFile` resolution is
+     * applied — `resolveCodacyrc` already produces strings and absolute paths are
+     * filled in later by `buildToolConfig`.
+     */
+    config?: CodacyConfig;
     /**
      * Git-aware file scope. Mutually exclusive options:
      * - `"staged"` — analyze only files in the git staging area
@@ -66,6 +300,20 @@ interface AnalyzeOptions {
     onToolComplete?: (toolId: string, displayName: string, issueCount: number, durationMs: number) => void;
     /** Called when a tool reports mid-execution progress (e.g. "Linting 50/200 files"). */
     onToolProgress?: (toolId: string, displayName: string, message: string) => void;
+    /**
+     * Called once with the `.codacyrc` describing this run — after file routing and
+     * pattern resolution, before any tool executes.
+     *
+     * A callback rather than a path so the runner performs no write of its own: a
+     * container run must not touch the bind-mounted `/src`, and where the file goes
+     * is the caller's policy. Awaited, and a throw propagates: nothing has run yet,
+     * so failing loudly is cheaper than handing back a file that silently was not
+     * written.
+     *
+     * Not called when the run returns before routing (`inspect` mode, an unavailable
+     * tool under `strict`, a fatal config error) or when no tool has anything to run.
+     */
+    onCodacyrc?: (codacyrc: Codacyrc) => void | Promise<void>;
     /**
      * Optional proxy/TLS configuration for outbound HTTP (API calls and tool
      * downloads). When provided, it is applied via `configureProxy` at the start of
@@ -165,6 +413,25 @@ declare function clearAdapters(): void;
  * This function never throws — format errors are returned as descriptive strings.
  */
 declare function formatOutput(result: AnalysisResult, format: OutputFormat): string;
+/**
+ * Splits errors into the ones `container` output can carry and the ones it
+ * cannot.
+ *
+ * `fileErrors` are the errors that mean *this file was not analysed*
+ * ({@link AnalysisError.fileNotAnalyzed}) — the only ones that may become a
+ * `FileError` line. Presence of a `filePath` alone is deliberately not enough:
+ * markdownlint and stylelint attach one to a finding whose rule they could not
+ * name, and promoting those would tell Codacy a perfectly healthy file is
+ * unanalysed, discarding the findings we did report for it.
+ *
+ * `otherErrors` have nowhere to go in this format. The CLI logs them to stderr;
+ * dropping them silently is what this split exists to prevent. Exported because
+ * `formatOutput` is pure and has no logger.
+ */
+declare function partitionContainerErrors(errors: readonly AnalysisError[]): {
+    fileErrors: AnalysisError[];
+    otherErrors: AnalysisError[];
+};
 /**
  * Builds the summary portion of the text output: header line, tools table,
  * and install hints. Exported separately so the CLI can print it to stdout
@@ -172,6 +439,78 @@ declare function formatOutput(result: AnalysisResult, format: OutputFormat): str
  */
 declare function formatTextSummary(result: AnalysisResult, isInspect?: boolean): string;
 
+/**
+ * Pattern-ID translation between our vocabulary and the Codacy engine's.
+ *
+ * Codacy's cloud runners speak the vocabulary of the per-tool Docker images:
+ * `docs/patterns.json` inside a container lists **unprefixed** rule ids
+ * (`S102_exec-builtin`). Our own `patterns.json` files come from the v3 API,
+ * which returns them **tool-prefixed** (`Ruff_S102_exec-builtin`). The two
+ * container seams — `.codacyrc` ingestion and `container` output — are the only
+ * places that translation happens; adapters keep speaking prefixed ids and
+ * nothing else in the CLI changes.
+ *
+ * Both directions live here so they cannot drift apart.
+ *
+ * ## Not every tool is prefixed
+ *
+ * A tool with no `prefix` in the Codacy API (detekt, Reek, Brakeman, RuboCop)
+ * ships **bare** rule ids in our `patterns.json` too — `Attribute`, not
+ * `Reek_Attribute`. So translation is conditional, never a blind strip or
+ * prepend. Verified across all 33 committed catalogues (17 871 patterns):
+ * adoption is all-or-nothing per tool — 29 fully prefixed, 4 fully unprefixed,
+ * none mixed, and no unprefixed id starts with its own tool id even
+ * case-insensitively. `packages/runner/test/pattern-id.test.ts` pins that
+ * invariant, which is what licenses the cheap `startsWith` test below.
+ */
+
+/**
+ * Our prefixed pattern id → the engine's unprefixed one.
+ *
+ * Needs no data beyond the tool id, which every `Issue` already carries, so the
+ * `container` formatter can translate without loading any adapter.
+ *
+ * Strips **exactly once**: `Checkov_Checkov_FOO` → `Checkov_FOO`, because the
+ * trailing half is a real rule name. Never use a global regex, `replaceAll`, or
+ * a loop here.
+ */
+declare function toEnginePatternId(patternId: string, toolId: string): string;
+/** Translates the engine's pattern ids into ours for one tool. */
+interface PatternIdTranslator {
+    readonly toolId: string;
+    /**
+     * The engine's id → ours. Always answers: an id the catalogue does not contain
+     * is translated by the tool's own naming convention rather than rejected, so
+     * catalog lag cannot turn into lost findings. Use {@link isKnown} to decide
+     * whether that is worth reporting.
+     */
+    toInternal(enginePatternId: string): string;
+    /**
+     * Whether the catalogue actually contains this id. Always `true` when the
+     * adapter ships no catalogue — with nothing to check against, an unmatched id
+     * is not evidence of anything.
+     */
+    isKnown(enginePatternId: string): boolean;
+    /** Whether this tool ships a pattern catalogue at all. */
+    readonly hasCatalogue: boolean;
+}
+/**
+ * Builds the engine → ours direction for one tool.
+ *
+ * Driven by the adapter's own `patternsMetadata` when it has one: that is a
+ * lookup table rather than a guess, so it is exact for prefixed and unprefixed
+ * tools alike, and it also accepts an id already written in our vocabulary — a
+ * hand-written debugging `.codacyrc` carrying `Ruff_S102_exec-builtin` still
+ * resolves.
+ *
+ * For an id the catalogue lacks — and for adapters with no catalogue at all, like
+ * the `dummy-1` reference tool — it falls back to the tool's observed convention:
+ * prepend `{toolId}_` only if the tool's own patterns are prefixed. Prepending
+ * for an unprefixed tool would invent `Reek_Attribute`, a pattern Reek has never
+ * heard of.
+ */
+declare function buildPatternTranslator(toolId: string, patternsMetadata?: readonly PatternEntry[]): PatternIdTranslator;
+
 /**
  * Configuration resolution — manages the .codacy/ directory structure and
  * assembles per-tool CodacyToolConfig from config + local config checks.
@@ -653,16 +992,18 @@ declare function initRemoteConfig(repositoryRoot: string, provider: string, orga
     stats: InitRemoteStats;
 }>;
 /**
- * `--container` mode.
- * Reads `.codacyrc` from the repository root (the container run input file).
- * Parses the `files` list into `includeFiles` and maps `tools` entries to adapters.
+ * `--container` mode — the debugging counterpart of `analyze --codacyrc`.
  *
- * `.codacyrc` format (from codacy-engine-typescript-seed):
- * ```json
- * { "tools": [...], "files": ["src/main.rs", "src/lib.rs"], "options": {...} }
- * ```
+ * Materializes the configuration a container *would* run with, so it can be
+ * inspected before analysis. The production path never calls this: it builds the
+ * same config in memory and never writes into the mounted source directory.
+ *
+ * Both go through {@link resolveCodacyrc}, so the two cannot drift apart.
+ *
+ * A missing `.codacyrc` yields a config with no tools rather than an error —
+ * every seed treats an absent file as "no configuration supplied".
  */
-declare function initContainerConfig(repositoryRoot: string, adapters: Readonly<ToolAdapter>[]): Promise<CodacyConfig>;
+declare function initContainerConfig(repositoryRoot: string, adapters: Readonly<ToolAdapter>[], codacyrcPath?: string): Promise<CodacyConfig>;
 /** Stats returned alongside the config from `initAutoConfig`. */
 interface InitAutoStats {
     /** Number of languages detected by discover. */
@@ -986,12 +1327,12 @@ declare function resolveRemoteAuth(repositoryToken?: string): Promise<RemoteAuth
  */
 
 /**
- * Display names of every entity discovery can emit.
+ * Display names of every entity in the catalog.
  *
- * Kept for consumers that report on the catalog. Note it is **not** the set of
- * gating keys — those are entity keys ({@link getEntityProviders}) — precisely
- * because display names are not unique: Angular 2+, AngularJS and AngularDart all
- * display as "Angular".
+ * For consumers that label or report on the vocabulary. Names are unique, so the
+ * set has one member per entity — but it is still **not** the set of gating keys
+ * ({@link getEntityProviders}): a label is copy and can be reworded, so anything
+ * that has to keep matching a `pattern-mappings.json` file keys on the entity key.
  */
 declare function getKnownDisplayNames(): Set<string>;
 
@@ -1224,4 +1565,84 @@ declare function buildPayloads(issues: NormalizedIssue[], resolveShortName: (too
  */
 declare function uploadReport(options: UploadOptions): Promise<UploadResult>;
 
-export { type AdapterFactory, type AnalyzeOptions, type AutoFilters, type CategoryFilter, type CodacyYamlConfig, type CodacyYamlEngineConfig, type ConfigOperation, type DiscoverOptions, type DiscoveryExcludes, type ExecutionMode, type IgnoredFilesResult, type InitAutoStats, type InitDefaultStats, type InitDiscoveryOptions, type InitLocalStats, type InitRemoteStats, type LoggerOptions, type MergeOptions, type NormalizedIssue, type PatternMetadataLookup, type RemoteAuth, type SeverityFilter, type UploadAuth, type UploadOptions, type UploadResult, analyze, applyCodacyYamlExcludes, applyConfigOperation, buildPayloads, buildToolConfig, clearAdapters, computePatternSummary, configureApiToken, createCodacyConfig, createLogger, createNullLogger, deleteCredentials, detectLanguages, diffConfigs, discover, formatOutput, formatTextSummary, getAdapter, getKnownDisplayNames, getRegisteredAdapters, getRegisteredDescriptors, initAutoConfig, initContainerConfig, initDefaultConfig, initLocalConfig, initRemoteConfig, intersectConfigs, listDiffFiles, listIgnoredFiles, listPrFiles, listStagedFiles, loadCredentials, mergeConfigs, parseAutoFilters, parseReport, pruneEmptyTools, readBaselineConfig, readCodacyConfig, readCodacyYaml, registerAdapter, registerLazyAdapter, registerUnsupportedTool, relativizeLocalConfigPaths, resolveApiToken, resolveBaselinePath, resolveConfigPath, resolveDiscoveryExcludes, resolveEngineToAdapter, resolveHeadCommit, resolveLocalConfigPaths, resolveRemoteAuth, resolveRepositoryRoot, resolveResultsApiBaseUrl, rotateLogFiles, saveCredentials, updateConfigIncremental, uploadReport, validateApiToken, writeBaselineConfig, writeCodacyConfig, writeCodacyConfigFile };
+/**
+ * Container-image operations: vulnerability scanning (`container-scan`) and
+ * SBOM generation + upload (`upload-sbom`), the two cli-v2 commands that work
+ * on an image rather than a repository working tree.
+ *
+ * The runner stays tool-agnostic here as everywhere else: it looks for a
+ * registered adapter whose descriptor declares `scansContainerImages` (today,
+ * Trivy) and drives it through `ToolAdapter.containerImage`. Validation of every
+ * user-supplied value happens **before** any tool is installed or spawned.
+ */
+
+/** cli-v2's defaults, kept so migrated CI pipelines report exactly what they did. */
+declare const DEFAULT_IMAGE_SCAN_SEVERITIES: readonly ImageScanSeverity[];
+/** cli-v2's default: OS packages only. */
+declare const DEFAULT_IMAGE_SCAN_PKG_TYPES: readonly ImageScanPkgType[];
+/** Options for {@link scanContainerImage}. */
+interface ScanContainerImageOptions {
+    /** Image reference, e.g. `nginx:1.25`, `ghcr.io/org/app:v1`, `app@sha256:…`. */
+    image: string;
+    /** Severities to report. Defaults to {@link DEFAULT_IMAGE_SCAN_SEVERITIES}. */
+    severities?: readonly string[];
+    /** Package classes to inspect. Defaults to {@link DEFAULT_IMAGE_SCAN_PKG_TYPES}. */
+    pkgTypes?: readonly string[];
+    /** Skip vulnerabilities with no released fix. Defaults to `true`, as in cli-v2. */
+    ignoreUnfixed?: boolean;
+    logger?: Logger;
+    signal?: AbortSignal;
+}
+/**
+ * Scans a container image for vulnerabilities and returns an ordinary
+ * {@link AnalysisResult}, so `formatOutput` renders it in every format and
+ * `localExitCode` maps it to 0 (clean) / 1 (findings) / 2 (failure).
+ *
+ * Throws — before installing or spawning anything — for an invalid image
+ * reference or an unknown severity / package type, and when no image-capable
+ * adapter is registered (`registerBuiltinAdapters()` not called). Everything
+ * after that, including a failed install or a failed scan, is reported inside
+ * the result rather than thrown — as is caller cancellation through `signal`,
+ * which yields a `Cancelled` error exactly like `analyze()`.
+ */
+declare function scanContainerImage(options: ScanContainerImageOptions): Promise<AnalysisResult>;
+/** Options for {@link uploadImageSbom}. */
+interface UploadImageSbomOptions {
+    /** Image reference. A digest reference cannot be combined with `tag`. */
+    image: string;
+    /** Tag to record; defaults to the reference's own tag, then `latest`. */
+    tag?: string;
+    /** SBOM document format. Defaults to `cyclonedx` (smaller output). */
+    format?: string;
+    /** Git provider: `gh`, `gl` or `bb`. */
+    provider: string;
+    organization: string;
+    /** Codacy repository to associate the image with. */
+    repositoryName?: string;
+    /** Where the image is deployed, e.g. `production`. */
+    environment?: string;
+    /** Account API token. The endpoint has no repository-token mode. */
+    apiToken: string;
+    logger?: Logger;
+    signal?: AbortSignal;
+    /** Progress lines for the caller to display (e.g. on stderr). */
+    onProgress?: (message: string) => void;
+}
+/** What {@link uploadImageSbom} uploaded. */
+interface UploadImageSbomResult {
+    imageName: string;
+    tag: string;
+    format: SbomFormat;
+}
+/**
+ * Generates an SBOM for a container image and uploads it to the organization's
+ * image-SBOM endpoint — one step, as cli-v2's `upload-sbom` was.
+ *
+ * Every input is validated before anything is installed or spawned. The SBOM
+ * is written to a private temp directory that is removed on success and on
+ * every failure path. Throws on any failure, with a message naming the stage
+ * (validation, install, generation or upload) that failed.
+ */
+declare function uploadImageSbom(options: UploadImageSbomOptions): Promise<UploadImageSbomResult>;
+
+export { type AdapterFactory, type AdapterLookup, type AnalyzeOptions, type AutoFilters, type CategoryFilter, type CodacyYamlConfig, type CodacyYamlEngineConfig, type Codacyrc, type CodacyrcParameter, type CodacyrcPattern, type CodacyrcResolution, type CodacyrcTool, type CodacyrcToolInput, type ConfigOperation, DEFAULT_IMAGE_SCAN_PKG_TYPES, DEFAULT_IMAGE_SCAN_SEVERITIES, type DiscoverOptions, type DiscoveryExcludes, type ExecutionMode, type IgnoredFilesResult, type InitAutoStats, type InitDefaultStats, type InitDiscoveryOptions, type InitLocalStats, type InitRemoteStats, type LoggerOptions, type MergeOptions, type NormalizedIssue, type PatternIdTranslator, type PatternMetadataLookup, type RemoteAuth, type ScanContainerImageOptions, type SeverityFilter, type UploadAuth, type UploadImageSbomOptions, type UploadImageSbomResult, type UploadOptions, type UploadResult, analyze, applyCodacyYamlExcludes, applyConfigOperation, buildCodacyrc, buildPatternTranslator, buildPayloads, buildToolConfig, clearAdapters, computePatternSummary, configureApiToken, createCodacyConfig, createLogger, createNullLogger, deleteCredentials, detectLanguages, diffConfigs, discover, formatOutput, formatTextSummary, getAdapter, getKnownDisplayNames, getRegisteredAdapters, getRegisteredDescriptors, initAutoConfig, initContainerConfig, initDefaultConfig, initLocalConfig, initRemoteConfig, intersectConfigs, listDiffFiles, listIgnoredFiles, listPrFiles, listStagedFiles, loadCredentials, mergeConfigs, parseAutoFilters, parseCodacyrc, parseReport, partitionContainerErrors, pruneEmptyTools, readBaselineConfig, readCodacyConfig, readCodacyYaml, readCodacyrc, registerAdapter, registerLazyAdapter, registerUnsupportedTool, registryLookup, relativizeLocalConfigPaths, resolveApiToken, resolveBaselinePath, resolveCodacyrc, resolveConfigPath, resolveDiscoveryExcludes, resolveEngineToAdapter, resolveHeadCommit, resolveLocalConfigPaths, resolveRemoteAuth, resolveRepositoryRoot, resolveResultsApiBaseUrl, resolveToolName, rotateLogFiles, saveCredentials, scanContainerImage, serializeCodacyrc, toEnginePatternId, updateConfigIncremental, uploadImageSbom, uploadReport, validateApiToken, writeBaselineConfig, writeCodacyConfig, writeCodacyConfigFile };