@codacy/analysis-runner 0.17.0 → 0.19.0

package/dist/index.d.ts

@@ -410,9 +410,14 @@ declare function parseAutoFilters(raw: string): {
  * The generated client (src/api/client/) is produced from the Codacy OpenAPI spec
  * and should never be edited by hand. All API interactions go through this file.
  *
- * Authentication: Codacy uses an `api-token` header (not Bearer). We set it via
- * `OpenAPI.HEADERS` before each call group. `configureApiToken()` must be called
- * before any authenticated endpoint is used.
+ * Authentication: Codacy uses an `api-token` header (account token) or a
+ * `project-token` header (repository token). `configureApiToken()`
+ * sets exactly one via `OpenAPI.HEADERS` and must be called before any
+ * authenticated endpoint is used. Most operations only accept `api-token`; a
+ * small whitelisted subset of repository-scoped reads (`getRepository`,
+ * `listRepositoryTools`, `listRepositoryToolPatterns`, `listIgnoredFiles`) also
+ * accept `project-token` — the backend rejects it everywhere else exactly as
+ * if no token had been sent.
  *
  * Pagination: all list endpoints use cursor-based pagination. `fetchAllPages()`
  * follows cursors until the response contains no next cursor.
@@ -428,12 +433,41 @@ interface IgnoredFilesResult {
     capped: boolean;
 }
 /**
- * Configures the API token used for authenticated requests.
- * Must be called before `getRepository`, `listRepositoryTools`, or
- * `listRepositoryToolPatterns`. Public endpoints (listTools, listPatterns)
- * do not require a token.
+ * Auth for API calls that accept either an account token or a repository
+ * (project) token — currently only the 4 reads `initRemoteConfig` makes. A
+ * discriminated union (same shape and naming as `UploadAuth` in `upload.ts`)
+ * so "exactly one token" is a compile-time guarantee, not a runtime check,
+ * and so there is never a "both configured" state for the backend to have to
+ * arbitrate — sending both was never useful anyway, since the backend always
+ * prefers `api-token` when both are present.
  */
-declare function configureApiToken(token: string): void;
+type RemoteAuth = {
+    kind: "account-token";
+    token: string;
+} | {
+    kind: "repository-token";
+    token: string;
+};
+/**
+ * Configures the auth header used for authenticated requests. Must be called
+ * before `getRepository`, `listRepositoryTools`, `listRepositoryToolPatterns`,
+ * or `listIgnoredFiles`. Public endpoints (listTools, listPatterns) do not
+ * require a token.
+ *
+ * Accepts a bare account-token string, for source compatibility with this
+ * function's original `(token: string)` shape — this is a published package,
+ * and embedders (a VSCode extension, an MCP server) call it directly with a
+ * bare string — or a {@link RemoteAuth} object to configure a repository
+ * token instead. Throws if given neither a non-empty string nor a valid
+ * `RemoteAuth`, rather than silently configuring no auth at all.
+ *
+ * Fully replaces any previously configured auth — it does not merge with a
+ * prior call. A process driving multiple auth contexts (e.g. an embedder
+ * juggling an account token for one repository and a project token for
+ * another) must call this again immediately before each authenticated call
+ * group, the same way `initRemoteConfig` does internally.
+ */
+declare function configureApiToken(auth: string | RemoteAuth): void;
 /**
  * Validates an API token by calling the authenticated user endpoint.
  * Returns user info on success; caller should catch errors for invalid tokens.
@@ -447,7 +481,8 @@ declare function validateApiToken(token: string): Promise<{
  * Fetches files individually ignored in Codacy Cloud for a repository.
  * Uses cursor-based pagination capped at 10 pages (1000 files max) to avoid
  * unbounded fetching for repositories with very large ignore lists.
- * Requires `configureApiToken()` to have been called.
+ * Requires `configureApiToken()` to have been called with an account token
+ * or a repository (project) token — this operation accepts either.
  */
 declare function listIgnoredFiles(provider: string, org: string, repo: string): Promise<IgnoredFilesResult>;
 
@@ -469,8 +504,31 @@ declare function listIgnoredFiles(provider: string, org: string, repo: string):
  * extensions/filenames against LANGUAGE_CONFIG. When `precomputedFiles` is
  * provided, uses that list directly instead of running `git ls-files`.
  * Returns languages sorted alphabetically for deterministic output.
+ *
+ * `exclude` (optional) drops files matching those globs before detection, so a
+ * language whose only files live in excluded paths is not reported. Every caller
+ * that turns the result into tool selection must pass the excludes `analyze`
+ * will apply — a language detected from a file `analyze` never reads produces a
+ * tool that analyzes zero files. Applied to `precomputedFiles` too (filtering is
+ * idempotent, so pre-filtered lists are safe to pass).
+ */
+declare function detectLanguages(repositoryRoot: string, precomputedFiles?: string[], exclude?: readonly string[]): Promise<Language[]>;
+/**
+ * Options shared by the init modes that derive configuration from the local
+ * repository (`local`, `default`, `auto`).
  */
-declare function detectLanguages(repositoryRoot: string, precomputedFiles?: string[]): Promise<Language[]>;
+interface InitDiscoveryOptions {
+    /**
+     * The config currently on disk, when re-generating via `update-config`.
+     *
+     * Its `exclude` (global and per-tool) is unioned with the freshly-read
+     * `.codacy.yaml` to constrain re-discovery, so excludes the user hand-wrote
+     * into `codacy.config.json` — or that arrived from Codacy Cloud's
+     * ignored-files list — don't get re-populated with tools that analyze zero
+     * files. Omit for a fresh `init`, where only `.codacy.yaml` applies.
+     */
+    existingConfig?: CodacyConfig;
+}
 /** Stats returned alongside the config from `initLocalConfig`. */
 interface InitLocalStats {
     /** Whether a .codacy.yaml file was found and its exclude paths were applied. */
@@ -482,7 +540,7 @@ interface InitLocalStats {
  * that have a local configuration file present in the repository.
  * If a .codacy.yaml file is present, its exclude paths are merged into the config.
  */
-declare function initLocalConfig(repositoryRoot: string, adapters: Readonly<ToolAdapter>[]): Promise<{
+declare function initLocalConfig(repositoryRoot: string, adapters: Readonly<ToolAdapter>[], options?: InitDiscoveryOptions): Promise<{
     config: CodacyConfig;
     stats: InitLocalStats;
 }>;
@@ -507,7 +565,7 @@ interface InitDefaultStats {
  *
  * Returns both the config and stats so the caller can report what happened.
  */
-declare function initDefaultConfig(repositoryRoot: string, adapters: Readonly<ToolAdapter>[]): Promise<{
+declare function initDefaultConfig(repositoryRoot: string, adapters: Readonly<ToolAdapter>[], options?: InitDiscoveryOptions): Promise<{
     config: CodacyConfig;
     stats: InitDefaultStats;
 }>;
@@ -534,6 +592,13 @@ interface InitRemoteStats {
  * as unsupported (cloud-only) entries (subject to the trackability filter — deprecated and
  * client-side/standalone-only tools are skipped).
  *
+ * @param auth - Account token or repository (project) token — a repository token alone
+ *   is enough for all four API calls this function makes, no login required. Also
+ *   accepts a bare account-token string, for source compatibility with callers written
+ *   against this function's original `apiToken: string` shape — this parameter used to
+ *   be exactly that, and this is a published package (embedders like a VSCode extension
+ *   or MCP server call it directly), so the old call shape must keep working unchanged.
+ *   See {@link configureApiToken} for the exact accepted shapes and validation.
  * @param onRemoteToolsFound - Optional callback invoked once after the list of enabled
  *   remote tools is fetched. Receives the total count of enabled tools and the count
  *   that have a registered local adapter. Fires before per-tool pattern fetching begins.
@@ -543,7 +608,7 @@ interface InitRemoteStats {
  * @param onIgnoredFilesFetched - Optional callback invoked after cloud-ignored files are
  *   fetched. Receives the count and whether the 1000-file cap was reached.
  */
-declare function initRemoteConfig(repositoryRoot: string, provider: string, organization: string, repositoryName: string, adapters: Readonly<ToolAdapter>[], apiToken: string, onRemoteToolsFound?: (totalEnabledTools: number, matchedAdapters: number) => void, onToolProcessed?: (displayName: string, patternCount: number, usesConfigFile: boolean) => void, onIgnoredFilesFetched?: (count: number, capped: boolean) => void): Promise<{
+declare function initRemoteConfig(repositoryRoot: string, provider: string, organization: string, repositoryName: string, adapters: Readonly<ToolAdapter>[], auth: string | RemoteAuth, onRemoteToolsFound?: (totalEnabledTools: number, matchedAdapters: number) => void, onToolProcessed?: (displayName: string, patternCount: number, usesConfigFile: boolean) => void, onIgnoredFilesFetched?: (count: number, capped: boolean) => void): Promise<{
     config: CodacyConfig;
     stats: InitRemoteStats;
 }>;
@@ -604,7 +669,7 @@ interface InitAutoStats {
  * those patterns are gated on detected frameworks exactly like supported tools;
  * tools without mappings have every committed pattern treated as universal.
  */
-declare function initAutoConfig(repositoryRoot: string, adapters: Readonly<ToolAdapter>[], descriptors: AdapterDescriptor[], filters?: AutoFilters, onDiscoveryComplete?: (result: DiscoveryResult) => void, rawFilterString?: string, loadUnsupportedPatterns?: (toolId: string) => readonly PatternEntry[]): Promise<{
+declare function initAutoConfig(repositoryRoot: string, adapters: Readonly<ToolAdapter>[], descriptors: AdapterDescriptor[], filters?: AutoFilters, onDiscoveryComplete?: (result: DiscoveryResult) => void, rawFilterString?: string, loadUnsupportedPatterns?: (toolId: string) => readonly PatternEntry[], options?: InitDiscoveryOptions): Promise<{
     config: CodacyConfig;
     stats: InitAutoStats;
 }>;
@@ -666,6 +731,41 @@ declare function resolveEngineToAdapter(engineName: string, adapters: Readonly<T
  * Returns a new config object (does not mutate the input).
  */
 declare function applyCodacyYamlExcludes(config: CodacyConfig, yamlConfig: CodacyYamlConfig, adapters: Readonly<ToolAdapter>[], logger?: Logger): CodacyConfig;
+/**
+ * The exclude patterns repository discovery must honor, resolved from every
+ * source that will also constrain `analyze`.
+ */
+interface DiscoveryExcludes {
+    /** Parsed `.codacy.yaml`, or null when the repository has none. Reused by `applyCodacyYamlExcludes` so the file is read once per init. */
+    yamlConfig: CodacyYamlConfig | null;
+    /** Global patterns — applied to every file-derived decision (languages, frameworks, tool selection). */
+    global: string[];
+    /** Per-adapter-ID patterns, applied on top of `global` when deciding whether that specific tool has files. */
+    perTool: Map<string, string[]>;
+}
+/**
+ * Resolves the exclude patterns that repository discovery must honor so that
+ * tool/language selection sees the same file set `analyze` will.
+ *
+ * Without this, discovery reads the raw `git ls-files` output while `analyze`
+ * reads that output minus `exclude` — so `init --auto` enables tools whose only
+ * evidence sits in excluded paths (e.g. language fixtures under
+ * `**\/test/fixtures/**`), and every one of them then receives zero files.
+ *
+ * Sources, unioned:
+ * - `.codacy.yaml` global `exclude_paths` → `global`
+ * - `.codacy.yaml` per-engine `exclude_paths` → `perTool` (engine names resolved
+ *   via {@link resolveEngineToAdapter}; unresolvable names are skipped)
+ * - `existingConfig.exclude` / `existingConfig.tools[].exclude` → both, for
+ *   `update-config`, so excludes the user hand-wrote into `codacy.config.json`
+ *   (or that arrived from Codacy Cloud's ignored-files list) also constrain
+ *   re-discovery
+ *
+ * `.codacy.yaml` is always re-read rather than trusted from the existing config,
+ * since it is the user-editable source of truth and may have changed since the
+ * config was generated.
+ */
+declare function resolveDiscoveryExcludes(repositoryRoot: string, adapters: Readonly<ToolAdapter>[], existingConfig?: CodacyConfig): Promise<DiscoveryExcludes>;
 
 /**
  * Computes pattern-level summary statistics for analysis results.
@@ -794,6 +894,7 @@ declare function createLogger(options?: LoggerOptions): Logger;
  *
  * All crypto uses Node.js built-in `crypto` — no external dependencies.
  */
+
 /**
  * Encrypts and saves an API token to ~/.codacy/credentials.
  * Creates the ~/.codacy/ directory if it doesn't exist.
@@ -818,6 +919,41 @@ declare function deleteCredentials(): Promise<boolean>;
  * 3. Throws with instructions if neither source has a token.
  */
 declare function resolveApiToken(): Promise<string>;
+/**
+ * Resolves auth for `init --remote` / `update-config --remote`: an explicit
+ * repository token (`repositoryToken` argument, or `CODACY_PROJECT_TOKEN`)
+ * wins outright — matching `upload`'s precedence for the same flag
+ * (`upload.ts:87-90`) — without even attempting to resolve an account token,
+ * so an explicitly-scoped run never pays the cost of loading a stored login
+ * it didn't ask for, and is never silently re-scoped to a broader token an
+ * ambient `CODACY_API_TOKEN` or prior `login` happens to leave lying around.
+ * Only when no repository token is given does this fall back to an account
+ * token, read the same way {@link resolveApiToken} does (env var, then
+ * stored credentials) — inlined here rather than calling it, so a missing
+ * account token falls through to the error below instead of throwing.
+ */
+declare function resolveRemoteAuth(repositoryToken?: string): Promise<RemoteAuth>;
+
+/**
+ * Turning a raw manifest identifier into an entity.
+ *
+ * Classification is **scoped to the ecosystem the identifier came from**, with no
+ * global fallback. A fallback is the bug this module exists to prevent: with one
+ * name-keyed catalog, the sbt artifact `requests` (com.lihaoyi) matched PyPI's
+ * Requests, and any bare gem or crate name could borrow another language's
+ * package. An artifact id is only meaningful inside its own registry, so that is
+ * the only place it is looked up.
+ */
+
+/**
+ * Display names of every entity discovery can emit.
+ *
+ * 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".
+ */
+declare function getKnownDisplayNames(): Set<string>;
 
 /**
  * Repository discovery — scans a codebase and identifies languages, file patterns,
@@ -826,14 +962,30 @@ declare function resolveApiToken(): Promise<string>;
  * The discover() function is the main entry point. It runs a 4-phase pipeline:
  * 1. File discovery (extensions, notable files)
  * 2. Language detection (reuses detectLanguages)
- * 3. Manifest parsing (dependency extraction)
- * 4. Dependency classification (framework / library / platform / tool)
+ * 3. Manifest parsing (dependency extraction, per owning ecosystem)
+ * 4. Classification (raw identifier → entity, scoped to that ecosystem)
+ *
+ * The static knowledge behind phases 3 and 4 lives in `./ecosystems/` (one module
+ * per package registry), `./signals.ts` and `./notable-files.ts`; the entity
+ * vocabulary itself is in `@codacy/tooling`.
  */
 
 /** Options for the discover function. */
 interface DiscoverOptions {
     /** Skip dependency extraction from manifests (only detect files and languages). */
     skipDependencies?: boolean;
+    /**
+     * Glob patterns to exclude from the scan, on top of `.gitignore`.
+     *
+     * Callers that feed discovery into configuration decisions **must** pass the
+     * same excludes `analyze` will apply (see `resolveDiscoveryExcludes` in
+     * `../codacy-yaml`). Otherwise discovery reports languages, frameworks, and
+     * libraries that only exist in excluded paths — e.g. a tool-orchestration
+     * monorepo whose per-language sample files all live under
+     * `**\/test/fixtures/**` looks like a 20-language polyglot repo, and every
+     * tool selected from those languages then analyzes zero files.
+     */
+    exclude?: readonly string[];
 }
 /**
  * Scans a repository and returns a structured report of languages, file patterns,
@@ -841,23 +993,6 @@ interface DiscoverOptions {
  */
 declare function discover(repositoryRoot: string, options?: DiscoverOptions): Promise<DiscoveryResult>;
 
-/**
- * Discovery catalog — static knowledge base for the discover command.
- *
- * Contains manifest file parsers, a curated dependency classification catalog,
- * and notable file detection rules. All parsers are pure functions that accept
- * raw file content and return dependency name arrays. They never throw.
- */
-
-/**
- * Every display name discovery can emit from a dependency/file/package.json signal.
- * This is the authoritative set a framework-mapping key must belong to (together
- * with detected language names) for its patterns to ever gate on. The drift-guard
- * test uses it to catch mapping keys that no signal can produce (e.g. a rename
- * like react-intl → formatjs that updates the mapping but not the catalog).
- */
-declare function getKnownDisplayNames(): Set<string>;
-
 /**
  * Git repository introspection helpers used by commands that need to know
  * *where* they are (repository root) and *what* they are looking at (the current
@@ -902,6 +1037,10 @@ declare function resolveHeadCommit(repositoryRoot: string): string;
  * Codacy patterns). We normalize either format into a flat issue list and build the
  * payload directly.
  *
+ * Issues from tools that group many findings under one pattern additionally carry
+ * `sourceId` (e.g. Trivy's CVE id), gated on the adapter descriptor's
+ * `needsSourceIdUpload` — see {@link buildPayloads}.
+ *
  * ## Where it uploads
  *
  * The **legacy v2 API** (`https://api.codacy.com/2.0`), matching the Go CLI: one
@@ -933,6 +1072,12 @@ interface NormalizedIssue {
     message: string;
     /** Codacy level string (Info/Warning/High/Error for json; Info/Warning/Error for sarif). */
     level: string;
+    /**
+     * The tool's own finding id (e.g. a CVE), when the report carries one. Only
+     * forwarded to the payload for tools whose descriptor sets
+     * `needsSourceIdUpload` — see {@link buildPayloads}.
+     */
+    sourceId?: string;
 }
 /** Authentication + routing for the upload. */
 type UploadAuth = {
@@ -995,6 +1140,8 @@ interface PayloadIssue {
             line: number;
         };
     };
+    /** Present only for tools that need it; see {@link buildPayloads}. */
+    sourceId?: string;
 }
 /**
  * Resolves the base URL for the legacy v2 results API. Defaults to Codacy SaaS;
@@ -1012,8 +1159,17 @@ declare function parseReport(fileContents: string): NormalizedIssue[];
  * Builds one v2 payload per tool, grouping issues by file. `resolveShortName` maps
  * our internal tool id to the Codacy tool short-name expected in the `tool` field
  * (which becomes an S3 key segment consumed downstream).
+ *
+ * `needsSourceId` decides, per tool, whether `sourceId` is included on each issue —
+ * mirroring the Go CLI, which gates it on the tool's `needs_source_id_upload`
+ * manifest flag. This is not cosmetic: `sourceId` is one of the four inputs to
+ * Codacy's deterministic result UUID, so sending it for a tool the cloud engine
+ * doesn't send it for would give the same finding a different UUID. Tools that
+ * don't need it omit the field entirely rather than sending an empty string.
+ * Defaults to never including it, so a caller that hasn't opted in can't change
+ * UUIDs by accident.
  */
-declare function buildPayloads(issues: NormalizedIssue[], resolveShortName: (toolId: string) => string): ToolPayload[];
+declare function buildPayloads(issues: NormalizedIssue[], resolveShortName: (toolId: string) => string, needsSourceId?: (toolId: string) => boolean): ToolPayload[];
 /**
  * Uploads an analysis report to Codacy. Reads and parses the report, resolves tool
  * short-names, POSTs one `issuesRemoteResults` per tool, then a single `resultsFinal`.
@@ -1028,4 +1184,4 @@ 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 ExecutionMode, type IgnoredFilesResult, type InitAutoStats, type InitDefaultStats, type InitLocalStats, type InitRemoteStats, type LoggerOptions, type MergeOptions, type NormalizedIssue, type PatternMetadataLookup, 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, resolveApiToken, resolveBaselinePath, resolveConfigPath, resolveEngineToAdapter, resolveHeadCommit, resolveRepositoryRoot, resolveResultsApiBaseUrl, rotateLogFiles, saveCredentials, updateConfigIncremental, uploadReport, validateApiToken, writeBaselineConfig, writeCodacyConfig, writeCodacyConfigFile };
+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, resolveApiToken, resolveBaselinePath, resolveConfigPath, resolveDiscoveryExcludes, resolveEngineToAdapter, resolveHeadCommit, resolveRemoteAuth, resolveRepositoryRoot, resolveResultsApiBaseUrl, rotateLogFiles, saveCredentials, updateConfigIncremental, uploadReport, validateApiToken, writeBaselineConfig, writeCodacyConfig, writeCodacyConfigFile };