@codacy/analysis-runner 0.10.1 → 0.12.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { OutputFormat, Logger, AnalysisResult, ToolAdapter, AdapterDescriptor, CodacyConfig, ConfigurationFileCheckResult, CodacyToolConfig, IssueSeverity, IssueCategory, Language, DiscoveryResult, Issue, PatternSummary, LogLevel } from '@codacy/tooling';
+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';
 
 /**
@@ -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;
@@ -94,6 +94,17 @@ declare function registerAdapter(adapter: Readonly<ToolAdapter>): void;
  * and inspect-mode metadata display without loading the full module.
  */
 declare function registerLazyAdapter(descriptor: AdapterDescriptor, factory: AdapterFactory): void;
+/**
+ * Register an unsupported (cloud-only) tool by descriptor alone.
+ *
+ * These tools exist on Codacy Cloud but have no local analyzer in this CLI. They are
+ * registered so that `getRegisteredDescriptors()` (and therefore `info`, `init --auto`,
+ * and config generation) can see them, but they are intentionally excluded from
+ * `getRegisteredAdapters()`/`getAdapter()` since there is nothing to execute.
+ *
+ * The descriptor should have `unsupported: true`.
+ */
+declare function registerUnsupportedTool(descriptor: AdapterDescriptor): void;
 /**
  * Returns all registered adapters, optionally filtered by tool ID list.
  *
@@ -309,6 +320,53 @@ declare function parseAutoFilters(raw: string): {
     unknown: string[];
 };
 
+/**
+ * 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.
+ */
+
+/** Result of fetching cloud-ignored files, with pagination cap. */
+interface IgnoredFilesResult {
+    /** File paths ignored in Codacy Cloud. */
+    files: string[];
+    /** Total number of files fetched (same as files.length). */
+    totalFetched: number;
+    /** Whether the fetch was stopped because it hit the 1000-file cap. */
+    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.
+ */
+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;
+}>;
+/**
+ * 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.
+ */
+declare function listIgnoredFiles(provider: string, org: string, repo: string): Promise<IgnoredFilesResult>;
+
 /**
  * Init mode logic — builds a CodacyConfig from five distinct sources:
  *
@@ -348,8 +406,10 @@ declare function initLocalConfig(repositoryRoot: string, adapters: Readonly<Tool
 interface InitDefaultStats {
     /** Total number of tools listed by the Codacy API. */
     totalApiTools: number;
-    /** Number of tool entries added to the config from API defaults. */
+    /** Number of supported (local-adapter) tool entries added from API defaults. */
     addedTools: number;
+    /** Number of unsupported (cloud-only) tool entries added from API defaults. */
+    addedUnsupported: number;
     /** Whether a .codacy.yaml file was found and its exclude paths were applied. */
     codacyYamlApplied: boolean;
 }
@@ -373,6 +433,8 @@ interface InitRemoteStats {
     totalRemoteTools: number;
     /** Number of those tools that have a registered local adapter. */
     matchedAdapters: number;
+    /** Number of those tools included as unsupported (cloud-only) entries. */
+    unsupportedTools: number;
     /** Whether a .codacy.yaml file was found and its exclude paths were applied. */
     codacyYamlApplied: boolean;
     /** Number of cloud-ignored files fetched from the Codacy API. */
@@ -383,8 +445,10 @@ interface InitRemoteStats {
 /**
  * `--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.
+ * The remote config is treated as the source of truth: tools with a registered adapter
+ * are included as supported tools, and enabled tools without a local adapter are tracked
+ * as unsupported (cloud-only) entries (subject to the trackability filter — deprecated and
+ * client-side/standalone-only tools are skipped).
  *
  * @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
@@ -418,8 +482,10 @@ interface InitAutoStats {
     detectedFrameworks: number;
     /** Number of libraries detected by discover. */
     detectedLibraries: number;
-    /** Number of tool entries added to the config. */
+    /** Number of tool entries added to the config (supported + unsupported). */
     selectedTools: number;
+    /** Number of those entries that are unsupported (cloud-only) tools. */
+    selectedUnsupported: number;
     /** Whether a .codacy.yaml file was found and its exclude paths were applied. */
     codacyYamlApplied: boolean;
 }
@@ -440,8 +506,16 @@ interface InitAutoStats {
  * ESLint core rules and their `@typescript-eslint` equivalents may both be
  * enabled, potentially causing duplicate findings. This will be addressed in v2
  * via conflict-resolution metadata in the mapping files.
+ *
+ * Unsupported (cloud-only) tools — descriptors with `unsupported: true` — are
+ * also filled when their languages overlap the detected stack. Their patterns are
+ * loaded lazily via `loadUnsupportedPatterns`; when it is not provided they are
+ * skipped. Tools that ship framework-specific patterns (e.g. PHPCS, dartanalyzer,
+ * SonarCSharp, CodeNarc) carry curated `frameworkMappings` on their descriptor, so
+ * 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): Promise<{
+declare function initAutoConfig(repositoryRoot: string, adapters: Readonly<ToolAdapter>[], descriptors: AdapterDescriptor[], filters?: AutoFilters, onDiscoveryComplete?: (result: DiscoveryResult) => void, rawFilterString?: string, loadUnsupportedPatterns?: (toolId: string) => readonly PatternEntry[]): Promise<{
     config: CodacyConfig;
     stats: InitAutoStats;
 }>;
@@ -527,11 +601,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.
@@ -552,53 +625,6 @@ declare function listDiffFiles(repositoryRoot: string, base?: string): string[];
  */
 declare function listPrFiles(repositoryRoot: string): string[];
 
-/**
- * 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.
- */
-
-/** Result of fetching cloud-ignored files, with pagination cap. */
-interface IgnoredFilesResult {
-    /** File paths ignored in Codacy Cloud. */
-    files: string[];
-    /** Total number of files fetched (same as files.length). */
-    totalFetched: number;
-    /** Whether the fetch was stopped because it hit the 1000-file cap. */
-    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.
- */
-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;
-}>;
-/**
- * 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.
- */
-declare function listIgnoredFiles(provider: string, org: string, repo: string): Promise<IgnoredFilesResult>;
-
 /**
  * Structured file + stderr logger for the analysis pipeline.
  *
@@ -673,4 +699,4 @@ 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, resolveConfigPath, resolveEngineToAdapter, rotateLogFiles, validateApiToken, writeCodacyConfig, writeCodacyConfigFile };
+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 };