@codacy/analysis-runner 0.12.0 → 0.14.0

package/README.md

@@ -1,7 +1,9 @@
 # @codacy/analysis-runner
 
 ## Table of Contents
+
 - [Overview](#overview)
+- [Quick start](#quick-start)
 - [API](#api)
 - [Pipeline steps](#pipeline-steps)
 - [Output formats](#output-formats)
@@ -13,17 +15,90 @@
 
 Core orchestration engine for the Codacy Analysis CLI. Discovers tools, checks capabilities, calls `analyze()` on each adapter, aggregates results, and transforms output. Usable programmatically by both the CLI and IDE integrations.
 
+## Quick start
+
+Tool adapters live in a companion preset package, **`@codacy/analysis-adapters`**. A
+consumer installs both and registers the built-in adapters **once** before running
+anything tool-related — the runner's adapter registry starts empty and nothing
+auto-populates it.
+
+```ts
+import { registerBuiltinAdapters } from "@codacy/analysis-adapters";
+import { analyze, createNullLogger } from "@codacy/analysis-runner";
+
+// Register all built-in tools + cloud-only descriptors (call once at startup).
+registerBuiltinAdapters();
+
+// Run analysis. `repositoryRoot` must be a git work tree.
+const result = await analyze({
+  repositoryRoot: "/abs/path/to/repo",
+  // files: ["src/index.ts"],   // optional: scope to specific files
+  logger: createNullLogger(), // or bring your own Logger (see below)
+});
+
+// Issue paths are repo-relative; line/column are 1-based.
+for (const issue of result.issues) {
+  console.log(
+    `${issue.filePath}:${issue.line}:${issue.column}  ${issue.patternId}  ${issue.message}`,
+  );
+}
+```
+
+To register only a subset of tools, import `builtinAdapterEntries` from the preset and
+call `registerLazyAdapter(descriptor, load)` for the ones you want.
+
+### Creating a config
+
+`analyze()` reads `.codacy/codacy.config.json`. Generate one programmatically with the
+`init*` family — they build a `CodacyConfig` from the registered adapters; `writeCodacyConfig`
+persists it:
+
+```ts
+import {
+  getRegisteredAdapters,
+  initLocalConfig, // local-config detection only (offline)
+  // initDefaultConfig / initAutoConfig / initRemoteConfig also available
+  writeCodacyConfig,
+} from "@codacy/analysis-runner";
+
+const adapters = await getRegisteredAdapters();
+const { config } = await initLocalConfig(repositoryRoot, adapters);
+await writeCodacyConfig(repositoryRoot, config);
+```
+
+`initAutoConfig` additionally takes the registered descriptors (`getRegisteredDescriptors()`)
+and the preset's `loadUnsupportedPatterns` to gate stack-specific patterns; `initRemoteConfig`
+pulls the config from Codacy Cloud (pass an API token — see credential helpers below).
+
+### Custom logging & cancellation
+
+- Pass your own `Logger` (the `@codacy/tooling` contract: `debug` / `info` / `warn` / `error`)
+  to route progress into your UI, or `createNullLogger()` for silence. Do **not** use
+  `createLogger()` in an embedder — it writes to files/stderr. Drive progress UI from the
+  `onToolStart` / `onToolComplete` / `onToolProgress` callbacks on `AnalyzeOptions`.
+- Pass `signal: AbortSignal` on `AnalyzeOptions` to cancel an in-flight run; signal-honoring
+  adapters return partial results and remaining tools are marked cancelled.
+
 ## API
 
-| Export | Purpose |
-|--------|---------|
-| `analyze(options)` | Main entry point — runs the full analysis pipeline |
-| `registerAdapter(adapter)` | Register a tool adapter |
-| `clearAdapters()` | Reset adapter registry (for tests) |
-| `getRegisteredAdapters()` | List registered adapters |
-| `formatOutput(result, format)` | Transform AnalysisResult into a formatted string |
-| `buildToolConfig()` | Assemble CodacyToolConfig from CodacyConfig + local config |
-| `readCodacyConfig()` / `writeCodacyConfig()` | Read/write `.codacy/codacy.config.json` |
+| Export                                                                                  | Purpose                                                                                                                                                      |
+| --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `analyze(options)`                                                                      | Main entry point — runs the full analysis pipeline. Options include `repositoryRoot`, `tools`, `files`, `logger`, `signal`, and `onTool*` progress callbacks |
+| `registerAdapter(adapter)` / `registerLazyAdapter(descriptor, load)`                    | Register a tool adapter (eager / lazy)                                                                                                                       |
+| `clearAdapters()`                                                                       | Reset adapter registry (for tests)                                                                                                                           |
+| `getRegisteredAdapters()` / `getRegisteredDescriptors()`                                | List registered adapters / descriptors                                                                                                                       |
+| `initLocalConfig()` / `initDefaultConfig()` / `initAutoConfig()` / `initRemoteConfig()` | Build a `CodacyConfig` (local, default, stack-aware, or Cloud-sourced)                                                                                       |
+| `readCodacyConfig()` / `writeCodacyConfig()`                                            | Read/write `.codacy/codacy.config.json`                                                                                                                      |
+| `buildToolConfig()`                                                                     | Assemble CodacyToolConfig from CodacyConfig + local config                                                                                                   |
+| `discover(path)`                                                                        | Scan a repo and report languages, frameworks, libraries, notable files                                                                                       |
+| `formatOutput(result, format)`                                                          | Transform AnalysisResult into a formatted string                                                                                                             |
+| `createLogger()` / `createNullLogger()`                                                 | File/stderr logger (CLI) / no-op logger (embedders)                                                                                                          |
+| `saveCredentials()` / `loadCredentials()` / `deleteCredentials()` / `resolveApiToken()` | Machine-stored API-token storage in `~/.codacy/credentials`                                                                                                  |
+| `validateApiToken()` / `configureApiToken()` / `listIgnoredFiles()`                     | Codacy Cloud API helpers                                                                                                                                     |
+
+> Adapter **registration** lives in the companion preset `@codacy/analysis-adapters`
+> (`registerBuiltinAdapters`, `builtinAdapterEntries`), not here — the runner stays
+> tool-agnostic.
 
 ## Pipeline steps
 
@@ -38,18 +113,18 @@ Core orchestration engine for the Codacy Analysis CLI. Discovers tools, checks c
 
 ## Output formats
 
-| Format | Description |
-|--------|-------------|
-| `json` | Pretty-printed AnalysisResult (default) |
-| `sarif` | SARIF v2.1.0 document |
-| `container` | One JSON object per line (Codacy Docker runners) |
-| `text` | Human-readable terminal summary with colors and grouping |
+| Format      | Description                                              |
+| ----------- | -------------------------------------------------------- |
+| `json`      | Pretty-printed AnalysisResult (default)                  |
+| `sarif`     | SARIF v2.1.0 document                                    |
+| `container` | One JSON object per line (Codacy Docker runners)         |
+| `text`      | Human-readable terminal summary with colors and grouping |
 
 ## Execution modes
 
-| Mode | Behavior |
-|------|----------|
-| `standard` | Skip unavailable tools, report them (default) |
-| `strict` | Fail if any configured tool is unavailable |
-| `auto-install` | Attempt to install missing tools before analysis |
-| `inspect` | Dry-run: report capability without running analysis |
+| Mode           | Behavior                                            |
+| -------------- | --------------------------------------------------- |
+| `standard`     | Skip unavailable tools, report them (default)       |
+| `strict`       | Fail if any configured tool is unavailable          |
+| `auto-install` | Attempt to install missing tools before analysis    |
+| `inspect`      | Dry-run: report capability without running analysis |

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { OutputFormat, Logger, AnalysisResult, ToolAdapter, AdapterDescriptor, CodacyConfig, ConfigurationFileCheckResult, CodacyToolConfig, IssueSeverity, IssueCategory, Language, DiscoveryResult, PatternEntry, Issue, PatternSummary, LogLevel } from '@codacy/tooling';
-export { AnalysisResult, OutputFormat } from '@codacy/tooling';
+import { OutputFormat, Logger, ProxyConfig, AnalysisResult, ToolAdapter, AdapterDescriptor, CodacyConfig, ConfigurationFileCheckResult, CodacyToolConfig, IssueSeverity, IssueCategory, Language, DiscoveryResult, PatternEntry, Issue, PatternSummary, LogLevel } from '@codacy/tooling';
+export { AnalysisResult, OutputFormat, ProxyConfig, configureProxy, resolveProxyConfig } from '@codacy/tooling';
 
 /**
  * Main analysis entry point — orchestrates the full analysis pipeline.
@@ -51,12 +51,30 @@ interface AnalyzeOptions {
     configFile?: string;
     /** Logger for pipeline progress messages (install status, etc.). Defaults to no-op. */
     logger?: Logger;
+    /**
+     * Optional caller abort signal for cancelling an in-flight analysis (e.g. an
+     * embedder like VSCode or an MCP server). When aborted, `analyze()` stops
+     * launching new tools, in-flight signal-honoring adapters return partial
+     * results, and remaining tools are marked cancelled. If the signal is already
+     * aborted when `analyze()` is called, it returns immediately without doing any
+     * work.
+     */
+    signal?: AbortSignal;
     /** Called when a tool starts executing. */
     onToolStart?: (toolId: string, displayName: string) => void;
     /** Called when a tool finishes executing. */
     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;
+    /**
+     * Optional proxy/TLS configuration for outbound HTTP (API calls and tool
+     * downloads). When provided, it is applied via `configureProxy` at the start of
+     * `analyze()`, installing a global fetch dispatcher. Library consumers that
+     * make API calls outside `analyze()` (e.g. init) should instead call
+     * `configureProxy` themselves once at startup. Omit to rely on environment
+     * variables (HTTP(S)_PROXY, NO_PROXY, SSL_CERT_FILE, CODACY_CLI_INSECURE).
+     */
+    proxy?: Partial<ProxyConfig>;
 }
 /**
  * Runs analysis on the given repository and returns the unified result.
@@ -172,6 +190,15 @@ declare function formatTextSummary(result: AnalysisResult, isInspect?: boolean):
  * (e.g. synced from Codacy Cloud) while testing a variant side-by-side.
  */
 declare function resolveConfigPath(repositoryRoot: string, configFile?: string): string;
+/**
+ * Resolves the absolute path to the config's baseline snapshot — the config the
+ * generator last produced, used by `update-config` to distinguish user-disabled
+ * patterns from default-off ones. It is a sibling of the config file
+ * (`<name>.json` → `<name>.baseline.json`), so `.codacy/codacy.config.json` maps
+ * to `.codacy/codacy.config.baseline.json`. It lives outside `.codacy/generated/`
+ * so it is committed and travels with the config.
+ */
+declare function resolveBaselinePath(repositoryRoot: string, configFile?: string): string;
 /**
  * Reads a CodacyConfig from disk.
  * Returns null if the file doesn't exist. Throws on parse/permission errors
@@ -180,6 +207,19 @@ declare function resolveConfigPath(repositoryRoot: string, configFile?: string):
  * Pass `configFile` to read from a non-default location.
  */
 declare function readCodacyConfig(repositoryRoot: string, configFile?: string): Promise<CodacyConfig | null>;
+/**
+ * Reads the config's baseline snapshot (see {@link resolveBaselinePath}).
+ * Returns null when no baseline exists (e.g. a config created before baselines
+ * were introduced), so `update-config` can fall back gracefully.
+ */
+declare function readBaselineConfig(repositoryRoot: string, configFile?: string): Promise<CodacyConfig | null>;
+/**
+ * Writes the config's baseline snapshot next to the config file (see
+ * {@link resolveBaselinePath}). No `.codacy/` side effects. Callers write this
+ * after every `init`/`update-config` so the next update diffs against the exact
+ * generator output. Returns the path written.
+ */
+declare function writeBaselineConfig(repositoryRoot: string, config: CodacyConfig, configFile?: string): Promise<string>;
 /**
  * Writes a CodacyConfig to disk at the exact resolved path, creating only the
  * parent directory. Unlike {@link writeCodacyConfig}, this has NO `.codacy/`
@@ -252,13 +292,23 @@ declare function createCodacyConfig(params?: {
 
 /** The set operation to apply between two configs. */
 type ConfigOperation = "merge" | "intersect" | "diff";
+/** Options for {@link mergeConfigs}. */
+interface MergeOptions {
+    /**
+     * When a pattern exists on both sides, keep dest's parameters instead of the
+     * default source-wins behavior. Used by the incremental update so the user's
+     * tuned parameters (dest) survive over freshly-generated defaults (source).
+     */
+    preferDestParameters?: boolean;
+}
 /**
  * Union of source and dest at the tool and pattern level.
  * Tools present on only one side are carried over as-is; tools on both sides are
- * combined (config-file rule, then per-tool pattern union with source parameters
- * winning). Never drops tools.
+ * combined (config-file rule, then per-tool pattern union). Parameters of a
+ * pattern on both sides come from source unless `options.preferDestParameters`.
+ * Never drops tools.
  */
-declare function mergeConfigs(source: CodacyConfig, dest: CodacyConfig): CodacyConfig;
+declare function mergeConfigs(source: CodacyConfig, dest: CodacyConfig, options?: MergeOptions): CodacyConfig;
 /**
  * Intersection of source and dest: only tools present in both, and per-tool only
  * the patterns present in both (config-file rule applies when either side uses a
@@ -277,6 +327,40 @@ declare function intersectConfigs(source: CodacyConfig, dest: CodacyConfig): Cod
 declare function diffConfigs(source: CodacyConfig, dest: CodacyConfig): CodacyConfig;
 /** Dispatches to the {@link mergeConfigs}, {@link intersectConfigs}, or {@link diffConfigs}. */
 declare function applyConfigOperation(op: ConfigOperation, source: CodacyConfig, dest: CodacyConfig): CodacyConfig;
+/**
+ * Returns a copy of `config` with tools that would do nothing removed — a tool
+ * with no enabled patterns and no native config file. Used after the incremental
+ * update so a tool whose every pattern was removed (e.g. its language/framework
+ * left the repo) drops out entirely. Config-file tools are always kept (they run
+ * from their own file). Does not mutate the input.
+ */
+declare function pruneEmptyTools(config: CodacyConfig): CodacyConfig;
+/**
+ * Incrementally updates a Codacy config while preserving user customizations.
+ *
+ * Three-way merge over the enabled-only config model (a disabled pattern is
+ * indistinguishable from a default-off one, so a naive re-generate + merge would
+ * resurrect patterns the user deliberately removed):
+ *
+ *   - `base`    — the config the generator last produced (pre-user-edit baseline)
+ *   - `current` — the user's live config (baseline + their edits)
+ *   - `next`    — the config the generator produces now (for the current stack)
+ *
+ *   added        = next − base       (genuinely new tools/patterns to add)
+ *   removed      = base − next       (tools/patterns whose stack element is gone)
+ *   result       = (current − removed) + added
+ *
+ * User-disabled patterns stay absent (they're in `base`, so never in `added`);
+ * user-tuned parameters and manual excludes ride along in `current` (dest wins on
+ * parameter conflicts via `preferDestParameters`). Identity/provenance metadata
+ * (`createdAt`, `source`, organization, …) come from `current`; `updatedAt` is
+ * refreshed and `metadata.languages` is refreshed from `next` (an incremental
+ * update is effectively a re-discovery, so the recorded stack must reflect the
+ * current repository, not the languages captured when the config was first
+ * written). Top-level `exclude` is reconciled with the same three-way logic, and
+ * any tool left with no patterns and no config file is pruned. Inputs are not mutated.
+ */
+declare function updateConfigIncremental(base: CodacyConfig, current: CodacyConfig, next: CodacyConfig): CodacyConfig;
 
 /**
  * auto-filters.ts — Parses and applies --auto filter syntax.
@@ -659,6 +743,15 @@ interface LoggerOptions {
      */
     onStderrMessage?: (text: string, level: LogLevel) => void;
 }
+/**
+ * Creates a no-op Logger that discards all messages.
+ *
+ * Intended for embedders (VSCode extension, MCP server, other library
+ * consumers) that call `analyze()` programmatically and do not want the
+ * pipeline writing to a log file or stderr. Passing this — or simply omitting
+ * `options.logger`, which defaults to it — keeps analysis completely silent.
+ */
+declare function createNullLogger(): Logger;
 /**
  * Removes old log files beyond the retention limit.
  *
@@ -677,6 +770,50 @@ declare function rotateLogFiles(logsDir: string, maxFiles: number): void;
  */
 declare function createLogger(options?: LoggerOptions): Logger;
 
+/**
+ * Credential storage — encrypts and persists API tokens to ~/.codacy/credentials,
+ * and resolves an API token from the environment or stored credentials.
+ *
+ * Lives in the runner so that any embedder (CLI, MCP server, IDE integration) can
+ * reuse credential storage. The interactive prompt stays in the CLI.
+ *
+ * Replicates the encryption scheme from codacy-cloud-cli — the byte format,
+ * algorithm, key derivation, and file location are SHARED, so credentials written
+ * by one tool are readable by the other. DO NOT change any of the following:
+ * - File location: ~/.codacy/credentials
+ * - Machine key: [hostname, username, homedir, platform].join("|")
+ * - Key derivation: PBKDF2 (100k iterations, SHA-512, 32-byte key)
+ * - Encryption: AES-256-GCM with random salt (32B) and IV (16B)
+ * - Storage: JSON with hex-encoded { salt, iv, authTag, encrypted }
+ * - File permissions: 0o600 (owner read/write only)
+ *
+ * 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.
+ */
+declare function saveCredentials(token: string): Promise<void>;
+/**
+ * Reads and decrypts the stored API token from ~/.codacy/credentials.
+ * Returns null if the file is missing, corrupt, or cannot be decrypted.
+ */
+declare function loadCredentials(): Promise<string | null>;
+/**
+ * Deletes the stored credentials file.
+ * Returns true if the file existed and was deleted, false otherwise.
+ */
+declare function deleteCredentials(): Promise<boolean>;
+/**
+ * Resolves a Codacy API token from the environment or stored credentials.
+ *
+ * Resolution order:
+ * 1. CODACY_API_TOKEN environment variable
+ * 2. Encrypted credentials saved via `codacy-analysis login`
+ * 3. Throws with instructions if neither source has a token.
+ */
+declare function resolveApiToken(): Promise<string>;
+
 /**
  * Repository discovery — scans a codebase and identifies languages, file patterns,
  * notable files, frameworks, and libraries.
@@ -699,4 +836,21 @@ interface DiscoverOptions {
  */
 declare function discover(repositoryRoot: string, options?: DiscoverOptions): Promise<DiscoveryResult>;
 
-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 PatternMetadataLookup, type SeverityFilter, analyze, applyCodacyYamlExcludes, applyConfigOperation, buildToolConfig, clearAdapters, computePatternSummary, configureApiToken, createCodacyConfig, createLogger, detectLanguages, diffConfigs, discover, formatOutput, formatTextSummary, getAdapter, getRegisteredAdapters, getRegisteredDescriptors, initAutoConfig, initContainerConfig, initDefaultConfig, initLocalConfig, initRemoteConfig, intersectConfigs, listDiffFiles, listIgnoredFiles, listPrFiles, listStagedFiles, mergeConfigs, parseAutoFilters, readCodacyConfig, readCodacyYaml, registerAdapter, registerLazyAdapter, registerUnsupportedTool, resolveConfigPath, resolveEngineToAdapter, rotateLogFiles, validateApiToken, writeCodacyConfig, writeCodacyConfigFile };
+/**
+ * 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>;
+
+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 PatternMetadataLookup, type SeverityFilter, analyze, applyCodacyYamlExcludes, applyConfigOperation, 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, pruneEmptyTools, readBaselineConfig, readCodacyConfig, readCodacyYaml, registerAdapter, registerLazyAdapter, registerUnsupportedTool, resolveApiToken, resolveBaselinePath, resolveConfigPath, resolveEngineToAdapter, rotateLogFiles, saveCredentials, updateConfigIncremental, validateApiToken, writeBaselineConfig, writeCodacyConfig, writeCodacyConfigFile };