@codacy/analysis-runner 0.11.0 → 0.13.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

@@ -27,7 +27,7 @@ interface AnalyzeOptions {
     outputFormat?: OutputFormat;
     /** Execution mode. Defaults to "standard". */
     mode?: ExecutionMode;
-    /** Maximum time in ms for each tool invocation. Defaults to 600000 (10 minutes). */
+    /** Maximum time in ms for each tool invocation. Defaults to 900000 (15 minutes). */
     toolTimeout?: number;
     /** Maximum number of tools to run in parallel. 1 = sequential. Defaults to 1. */
     parallelTools?: number;
@@ -51,6 +51,15 @@ 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. */
@@ -601,11 +610,10 @@ interface PatternMetadataLookup {
 declare function computePatternSummary(issues: readonly Issue[], lookup: ReadonlyMap<string, PatternMetadataLookup>): PatternSummary;
 
 /**
- * File discovery and routing — finds files in a repository, applies exclusion
- * layers (.gitignore, global exclude, per-tool exclude), and routes files to
- * the appropriate tool adapters based on file patterns.
+ * Git-scope file resolution — resolves the set of files implied by the
+ * `--staged`, `--diff`, and `--pr` flags. Each helper returns paths relative
+ * to the repository root, excluding deleted files, sorted for stable output.
  */
-
 /**
  * Returns files changed in the git staging area (index), excluding deleted files.
  * Used by `--staged` to analyze only what's about to be committed.
@@ -660,6 +668,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.
  *
@@ -678,6 +695,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.
@@ -700,4 +761,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 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, readCodacyConfig, readCodacyYaml, registerAdapter, registerLazyAdapter, registerUnsupportedTool, resolveApiToken, resolveConfigPath, resolveEngineToAdapter, rotateLogFiles, saveCredentials, validateApiToken, writeCodacyConfig, writeCodacyConfigFile };