@codacy/analysis-runner

Table of Contents

• Overview
• Quick start
• API
• Pipeline steps
• Output formats
• 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.

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.

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:

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. 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

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 |