@codacy/analysis-runner 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Codacy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,55 @@
+# @codacy/analysis-runner
+
+## Table of Contents
+- [Overview](#overview)
+- [API](#api)
+- [Pipeline steps](#pipeline-steps)
+- [Output formats](#output-formats)
+- [Execution modes](#execution-modes)
+
+---
+
+## Overview
+
+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.
+
+## 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` |
+
+## Pipeline steps
+
+1. Discover registered adapters (filtered by `options.tools` if set)
+2. Check availability → build CapabilityReport
+3. Apply execution mode rules (standard/strict/auto-install/inspect)
+4. Discover files via git, apply exclusion layers, route to tools
+5. Check local config + build CodacyToolConfig per tool
+6. Execute `adapter.analyze()` with timeout and concurrency control
+7. Aggregate results into AnalysisResult
+8. Format output
+
+## 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 |
+
+## 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 |

package/dist/index.d.ts

@@ -0,0 +1,364 @@
+import { OutputFormat, Logger, AnalysisResult, ToolAdapter, CodacyConfig, ConfigurationFileCheckResult, CodacyToolConfig, Language, LogLevel } from '@codacy/tooling';
+export { AnalysisResult, OutputFormat } from '@codacy/tooling';
+
+/**
+ * Main analysis entry point — orchestrates the full analysis pipeline.
+ *
+ * Pipeline steps:
+ * 1. Discover registered adapters (filtered by options.tools if set)
+ * 2. Check availability of each adapter → CapabilityReport
+ * 3. Apply execution mode rules (standard/strict/auto-install/inspect)
+ * 4. Discover files, apply exclusions, route to tools
+ * 5. Check local config + build CodacyToolConfig per tool
+ * 6. Execute tools (sequential or parallel)
+ * 7. Aggregate results into AnalysisResult
+ */
+
+/** Execution mode controls how the runner handles unavailable tools. */
+type ExecutionMode = "standard" | "strict" | "auto-install" | "inspect";
+interface AnalyzeOptions {
+    /** Absolute path to the repository to analyze. */
+    repositoryRoot: string;
+    /** Restrict analysis to these tool IDs. If empty/undefined, all registered tools run. */
+    tools?: string[];
+    /** Specific files to analyze (relative to repositoryRoot). If empty, all files. */
+    files?: string[];
+    /** Output format for the analysis results. Defaults to "json". */
+    outputFormat?: OutputFormat;
+    /** Execution mode. Defaults to "standard". */
+    mode?: ExecutionMode;
+    /** Maximum time in ms for each tool invocation. Defaults to 300000 (5 minutes). */
+    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. */
+    runner?: "local" | "container";
+    /** Logger for pipeline progress messages (install status, etc.). Defaults to no-op. */
+    logger?: Logger;
+    /** 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;
+}
+/**
+ * Runs analysis on the given repository and returns the unified result.
+ * This is the main entry point used by both the CLI and IDE integrations.
+ */
+declare function analyze(options: AnalyzeOptions): Promise<AnalysisResult>;
+
+/**
+ * Tool adapter registry — stores registered adapters for discovery by the runner.
+ *
+ * Adapters must be registered before calling analyze(). The registry is a simple
+ * in-memory map keyed by adapter ID. clearAdapters() is provided for testing.
+ */
+
+/** Register a tool adapter so the runner can discover and invoke it. */
+declare function registerAdapter(adapter: Readonly<ToolAdapter>): void;
+/** Returns all registered adapters, optionally filtered by tool ID list. */
+declare function getRegisteredAdapters(toolIds?: string[]): Readonly<ToolAdapter>[];
+/** Remove all registered adapters. Used in tests to reset state between runs. */
+declare function clearAdapters(): void;
+
+/**
+ * Output format transformations — converts AnalysisResult into the requested
+ * output format string.
+ *
+ * This is the single place where output transformation happens, so that both
+ * CLI and IDE consumers share the same formatting logic.
+ *
+ * Supported formats:
+ * - json:      AnalysisResult as pretty-printed JSON (default)
+ * - sarif:     SARIF v2.1.0 document
+ * - container: one JSON object per line on stdout (Codacy Docker runners)
+ * - text:      human-readable summary with colors and grouping
+ */
+
+/**
+ * Transforms an AnalysisResult into the specified output format string.
+ * This function never throws — format errors are returned as descriptive strings.
+ */
+declare function formatOutput(result: AnalysisResult, format: OutputFormat): string;
+/**
+ * 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
+ * even when the full output is written to a file via `-o`.
+ */
+declare function formatTextSummary(result: AnalysisResult, isInspect?: boolean): string;
+
+/**
+ * Configuration resolution — manages the .codacy/ directory structure and
+ * assembles per-tool CodacyToolConfig from config + local config checks.
+ *
+ * Precedence order:
+ * 1. Explicit CodacyConfig entry for the tool
+ * 2. Local native config file detected by the adapter
+ * 3. Default (empty patterns, no local config)
+ */
+
+/** Reads a CodacyConfig from disk. Returns null if the file doesn't exist. */
+declare function readCodacyConfig(repositoryRoot: string): Promise<CodacyConfig | null>;
+/** Writes a CodacyConfig to disk, creating the .codacy/ directory if needed. */
+declare function writeCodacyConfig(repositoryRoot: string, config: CodacyConfig): Promise<string>;
+/**
+ * Assembles a CodacyToolConfig from the global CodacyConfig and a local config check.
+ *
+ * Logic:
+ * - If `codacyConfig` has an entry for this tool, start with it
+ * - If no entry, create a default (empty patterns, no local config)
+ * - If `configCheck.found` and the existing config doesn't explicitly disable
+ *   local config, set `localConfigurationFile` and `useLocalConfigurationFile`
+ */
+declare function buildToolConfig(codacyConfig: CodacyConfig | null, adapter: Readonly<ToolAdapter>, configCheck: ConfigurationFileCheckResult): CodacyToolConfig;
+/**
+ * Creates a new CodacyConfig.
+ * Used by the init functions to build configs for all init modes.
+ */
+declare function createCodacyConfig(params?: {
+    source?: CodacyConfig["metadata"]["source"];
+    provider?: string | null;
+    organization?: string | null;
+    languages?: string[];
+    tools?: CodacyToolConfig[];
+    repositoryId?: string | null;
+    repositoryName?: string | null;
+    includeFiles?: string[];
+}): CodacyConfig;
+
+/**
+ * Init mode logic — builds a CodacyConfig from four distinct sources:
+ *
+ * - `initLocalConfig`    — detect languages + tools with a local config file
+ * - `initDefaultConfig`  — same as local, enriched with API-sourced pattern defaults
+ * - `initRemoteConfig`   — fetch the full tool/pattern config from a remote Codacy repository
+ * - `initContainerConfig`— read .codacyrc file (container run input) and extract file list
+ *
+ * All four functions return a `CodacyConfig` ready to be written by `writeCodacyConfig`.
+ * None of them write to disk — that is the caller's responsibility.
+ */
+
+/**
+ * Detects programming languages present in the repository by listing git-tracked
+ * files and matching their extensions/filenames against LANGUAGE_CONFIG.
+ * Returns languages sorted alphabetically for deterministic output.
+ */
+declare function detectLanguages(repositoryRoot: string): Promise<Language[]>;
+/** Stats returned alongside the config from `initLocalConfig`. */
+interface InitLocalStats {
+    /** Whether a .codacy.yaml file was found and its exclude paths were applied. */
+    codacyYamlApplied: boolean;
+}
+/**
+ * Default init mode (no options).
+ * Detects languages from git-tracked files and adds tool entries only for adapters
+ * 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<{
+    config: CodacyConfig;
+    stats: InitLocalStats;
+}>;
+/** Stats returned alongside the config from `initDefaultConfig`. */
+interface InitDefaultStats {
+    /** Total number of tools listed by the Codacy API. */
+    totalApiTools: number;
+    /** Number of tool entries added to the config from API defaults. */
+    addedTools: number;
+    /** Whether a .codacy.yaml file was found and its exclude paths were applied. */
+    codacyYamlApplied: boolean;
+}
+/**
+ * `--default` mode.
+ * Runs local detection first, then enriches the config with API-sourced default
+ * patterns for every registered adapter. Tools that already have a local config
+ * file are left as-is (local config takes precedence).
+ *
+ * Uses only public Codacy API endpoints — no API token required.
+ *
+ * Returns both the config and stats so the caller can report what happened.
+ */
+declare function initDefaultConfig(repositoryRoot: string, adapters: Readonly<ToolAdapter>[]): Promise<{
+    config: CodacyConfig;
+    stats: InitDefaultStats;
+}>;
+/** Stats returned alongside the config from `initRemoteConfig`. */
+interface InitRemoteStats {
+    /** Number of enabled tools returned by the remote repository's configuration. */
+    totalRemoteTools: number;
+    /** Number of those tools that have a registered local adapter. */
+    matchedAdapters: number;
+    /** Whether a .codacy.yaml file was found and its exclude paths were applied. */
+    codacyYamlApplied: boolean;
+}
+/**
+ * `--remote <provider> <org> <repo>` mode.
+ * Fetches the full tool/pattern configuration from the repository's Codacy settings.
+ * The remote config is treated as the source of truth — only tools with a registered
+ * adapter are included.
+ *
+ * @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.
+ * @param onToolProcessed - Optional callback invoked after each tool's patterns are
+ *   fetched. Receives the adapter's display name, the number of patterns configured, and
+ *   whether the tool uses a local configuration file. Useful for real-time CLI progress.
+ */
+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): Promise<{
+    config: CodacyConfig;
+    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.
+ *
+ * `.codacyrc` format (from codacy-engine-typescript-seed):
+ * ```json
+ * { "tools": [...], "files": ["src/main.rs", "src/lib.rs"], "options": {...} }
+ * ```
+ */
+declare function initContainerConfig(repositoryRoot: string, adapters: Readonly<ToolAdapter>[]): Promise<CodacyConfig>;
+
+/**
+ * .codacy.yaml ingestion — reads the standard Codacy configuration file from
+ * the repository root and extracts exclude paths for use during init.
+ *
+ * The .codacy.yaml file is the user-facing configuration file documented at
+ * https://docs.codacy.com/repositories-configure/codacy-configuration-file/
+ *
+ * During init, this module:
+ * - Reads global `exclude_paths` → maps to `CodacyConfig.exclude`
+ * - Reads per-engine `exclude_paths` → maps to `CodacyToolConfig.exclude`
+ * - Parses but defers `include_paths` (no support yet in CodacyConfig)
+ */
+
+/** Per-engine configuration extracted from .codacy.yaml. */
+interface CodacyYamlEngineConfig {
+    excludePaths: string[];
+    includePaths: string[];
+}
+/**
+ * Parsed representation of a .codacy.yaml file, containing only the fields
+ * relevant to the analysis CLI. Unknown fields are silently ignored.
+ */
+interface CodacyYamlConfig {
+    /** Global exclude paths (glob patterns). */
+    excludePaths: string[];
+    /** Global include paths (glob patterns). Reserved for future use. */
+    includePaths: string[];
+    /** Per-engine overrides keyed by engine name as it appears in .codacy.yaml. */
+    engines: Map<string, CodacyYamlEngineConfig>;
+}
+/**
+ * Reads and parses a .codacy.yaml (or .codacy.yml) file from the repository root.
+ * Returns null if neither file exists. Throws on malformed YAML.
+ */
+declare function readCodacyYaml(repositoryRoot: string): Promise<CodacyYamlConfig | null>;
+/**
+ * Resolves a .codacy.yaml engine name to a registered adapter ID using fuzzy matching.
+ *
+ * Resolution order (same as registry.ts:resolveAdapter):
+ * 1. Exact match on adapter ID
+ * 2. Case-insensitive substring match on adapter ID or displayName
+ *    — only resolves if exactly one adapter matches (ambiguous = no match)
+ *
+ * Returns the adapter ID or undefined if no unique match is found.
+ */
+declare function resolveEngineToAdapter(engineName: string, adapters: Readonly<ToolAdapter>[]): string | undefined;
+/**
+ * Applies parsed .codacy.yaml excludes to a CodacyConfig.
+ *
+ * - Global `exclude_paths` are appended to `config.exclude` (deduplicated)
+ * - Per-engine `exclude_paths` are appended to the matching tool's `exclude` (deduplicated)
+ * - Per-engine excludes only apply to tools already present in the config
+ * - Logs warnings for unresolved engine names and unsupported include_paths
+ *
+ * Returns a new config object (does not mutate the input).
+ */
+declare function applyCodacyYamlExcludes(config: CodacyConfig, yamlConfig: CodacyYamlConfig, adapters: Readonly<ToolAdapter>[], logger?: Logger): CodacyConfig;
+
+/**
+ * Codacy API client — thin wrappers around the generated OpenAPI client.
+ *
+ * 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.
+ *
+ * Pagination: all list endpoints use cursor-based pagination. `fetchAllPages()`
+ * follows cursors until the response contains no next cursor.
+ */
+
+/**
+ * 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.
+ */
+declare function configureApiToken(token: string): void;
+/**
+ * Validates an API token by calling the authenticated user endpoint.
+ * Returns user info on success; caller should catch errors for invalid tokens.
+ */
+declare function validateApiToken(token: string): Promise<{
+    valid: boolean;
+    name?: string;
+    email?: string;
+}>;
+
+/**
+ * Structured file + stderr logger for the analysis pipeline.
+ *
+ * Creates a Logger (as defined in @codacy/tooling) that writes:
+ *   1. JSON lines to a log file at `~/.codacy/logs/analysis-<timestamp>.log`
+ *   2. Human-readable messages to stderr
+ *
+ * Both outputs share a single level threshold controlled by `--log-level`.
+ * Log rotation deletes the oldest files beyond the configured retention count.
+ */
+
+/** Configuration for the logger factory. */
+interface LoggerOptions {
+    /** Minimum level for both stderr and file output. Defaults to "info". */
+    level?: LogLevel;
+    /** Whether to write to a log file. Defaults to true. */
+    fileEnabled?: boolean;
+    /** Directory for log files. Defaults to `~/.codacy/logs/`. */
+    logsDir?: string;
+    /** Maximum log file size in bytes before mid-run rotation. Defaults to 10 MB. */
+    maxFileSize?: number;
+    /** Number of rotated log files to keep. Defaults to 5. */
+    maxFiles?: number;
+    /**
+     * Optional callback invoked instead of writing to stderr.
+     *
+     * When set, the logger calls this with the enriched human-readable message
+     * (message + key fields) instead of writing to stderr directly. This allows
+     * the CLI to integrate log messages with the spinner without interleaving.
+     *
+     * When not set, the logger writes to stderr as before.
+     */
+    onStderrMessage?: (text: string, level: LogLevel) => void;
+}
+/**
+ * Removes old log files beyond the retention limit.
+ *
+ * Keeps the most recent `maxFiles` log files sorted by filename (which embeds
+ * an ISO timestamp, giving natural chronological order). Called at logger
+ * creation and after mid-run size rotation.
+ */
+declare function rotateLogFiles(logsDir: string, maxFiles: number): void;
+/**
+ * Creates a Logger that writes structured JSON lines to a file and
+ * human-readable messages to stderr (or to a callback), both filtered
+ * by a single log level.
+ *
+ * The returned logger conforms to the Logger interface from @codacy/tooling,
+ * so it can be passed directly into `analyze()` options and through ToolContext.
+ */
+declare function createLogger(options?: LoggerOptions): Logger;
+
+export { type AnalyzeOptions, type CodacyYamlConfig, type CodacyYamlEngineConfig, type ExecutionMode, type InitDefaultStats, type InitLocalStats, type InitRemoteStats, type LoggerOptions, analyze, applyCodacyYamlExcludes, buildToolConfig, clearAdapters, configureApiToken, createCodacyConfig, createLogger, detectLanguages, formatOutput, formatTextSummary, getRegisteredAdapters, initContainerConfig, initDefaultConfig, initLocalConfig, initRemoteConfig, readCodacyConfig, readCodacyYaml, registerAdapter, resolveEngineToAdapter, rotateLogFiles, validateApiToken, writeCodacyConfig };