@codacy/analysis-runner 0.6.1 → 0.8.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { OutputFormat, Logger, AnalysisResult, ToolAdapter, AdapterDescriptor, CodacyConfig, ConfigurationFileCheckResult, CodacyToolConfig, Language, LogLevel } from '@codacy/tooling';
+import { OutputFormat, Logger, AnalysisResult, ToolAdapter, AdapterDescriptor, CodacyConfig, ConfigurationFileCheckResult, CodacyToolConfig, IssueSeverity, IssueCategory, Language, DiscoveryResult, Issue, PatternSummary, LogLevel } from '@codacy/tooling';
 export { AnalysisResult, OutputFormat } from '@codacy/tooling';
 
 /**
@@ -179,26 +179,71 @@ declare function createCodacyConfig(params?: {
     repositoryId?: string | null;
     repositoryName?: string | null;
     includeFiles?: string[];
+    autoFilters?: string;
 }): CodacyConfig;
 
 /**
- * Init mode logic — builds a CodacyConfig from four distinct sources:
+ * auto-filters.ts — Parses and applies --auto filter syntax.
+ *
+ * Filter syntax: comma-separated list of severity and category names.
+ * - Severity names: Info/Minor, Warning/Medium, High, Error/Critical (both accepted)
+ * - Category names: Security, ErrorProne, CodeStyle, etc.
+ * - `All` prefix on any token removes the `enabled: true` filter for that value.
+ *   e.g. `AllCritical` includes ALL Critical patterns, not just default ones.
+ *
+ * Dimensions are ANDed (severity AND category). Values within a dimension are ORed.
+ * Omitting a dimension means "no restriction" for that dimension.
+ */
+
+/** A single severity filter with its All-prefix status. */
+interface SeverityFilter {
+    level: IssueSeverity;
+    all: boolean;
+}
+/** A single category filter with its All-prefix status. */
+interface CategoryFilter {
+    category: IssueCategory;
+    all: boolean;
+}
+/** Parsed result of the --auto filter string. */
+interface AutoFilters {
+    severities: SeverityFilter[];
+    categories: CategoryFilter[];
+}
+/**
+ * Parses a comma-separated auto-filter string into structured filters.
+ *
+ * Each token is classified as a severity or category by name lookup.
+ * The `All` prefix (case-insensitive) on a token removes the `enabled: true`
+ * constraint for that specific severity or category.
+ *
+ * Unrecognized tokens are collected and returned in the `unknown` array.
+ */
+declare function parseAutoFilters(raw: string): {
+    filters: AutoFilters;
+    unknown: string[];
+};
+
+/**
+ * Init mode logic — builds a CodacyConfig from five distinct sources:
  *
  * - `initLocalConfig`    — detect languages + tools with a local config file
+ * - `initAutoConfig`     — discover stack, then select tools/patterns by framework match
  * - `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`.
+ * All five 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.
+ * Detects programming languages present in the repository by matching file
+ * extensions/filenames against LANGUAGE_CONFIG. When `precomputedFiles` is
+ * provided, uses that list directly instead of running `git ls-files`.
  * Returns languages sorted alphabetically for deterministic output.
  */
-declare function detectLanguages(repositoryRoot: string): Promise<Language[]>;
+declare function detectLanguages(repositoryRoot: string, precomputedFiles?: 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. */
@@ -280,6 +325,41 @@ declare function initRemoteConfig(repositoryRoot: string, provider: string, orga
  * ```
  */
 declare function initContainerConfig(repositoryRoot: string, adapters: Readonly<ToolAdapter>[]): Promise<CodacyConfig>;
+/** Stats returned alongside the config from `initAutoConfig`. */
+interface InitAutoStats {
+    /** Number of languages detected by discover. */
+    detectedLanguages: number;
+    /** Number of frameworks detected by discover. */
+    detectedFrameworks: number;
+    /** Number of libraries detected by discover. */
+    detectedLibraries: number;
+    /** Number of tool entries added to the config. */
+    selectedTools: number;
+    /** Whether a .codacy.yaml file was found and its exclude paths were applied. */
+    codacyYamlApplied: boolean;
+}
+/**
+ * `--auto [filters]` mode.
+ *
+ * Runs `discover()` to detect the repository's tech stack, then selects tools
+ * by language overlap and filters patterns using per-tool framework mappings.
+ *
+ * Framework-specific patterns (those matching a mapping entry) are included only
+ * if the corresponding dependency was detected — and they bypass the `enabled`
+ * filter. Universal patterns (not in any mapping) are included only if
+ * `enabled: true`, unless an `All`-prefixed filter widens the gate.
+ *
+ * Severity and category filters are ANDed across dimensions, ORed within.
+ *
+ * **Known limitation (v1):** When both TypeScript and JavaScript are detected,
+ * 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.
+ */
+declare function initAutoConfig(repositoryRoot: string, adapters: Readonly<ToolAdapter>[], descriptors: AdapterDescriptor[], filters?: AutoFilters, onDiscoveryComplete?: (result: DiscoveryResult) => void, rawFilterString?: string): Promise<{
+    config: CodacyConfig;
+    stats: InitAutoStats;
+}>;
 
 /**
  * .codacy.yaml ingestion — reads the standard Codacy configuration file from
@@ -339,6 +419,28 @@ declare function resolveEngineToAdapter(engineName: string, adapters: Readonly<T
  */
 declare function applyCodacyYamlExcludes(config: CodacyConfig, yamlConfig: CodacyYamlConfig, adapters: Readonly<ToolAdapter>[], logger?: Logger): CodacyConfig;
 
+/**
+ * Computes pattern-level summary statistics for analysis results.
+ *
+ * Groups issues by Severity → Category → Pattern, producing a PatternSummary
+ * that formatters can render. Called inside analyze() where adapter metadata
+ * (pattern titles, tool display names) is available.
+ */
+
+/** Resolved metadata for a pattern, built from adapter.patternsMetadata. */
+interface PatternMetadataLookup {
+    title: string;
+    toolDisplayName: string;
+}
+/**
+ * Computes a PatternSummary from issues and a pattern metadata lookup.
+ *
+ * The lookup maps patternId → { title, toolDisplayName } and should be built
+ * from adapter.patternsMetadata before calling this function. Patterns not
+ * in the lookup fall back to patternId as the title and toolId as display name.
+ */
+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
@@ -464,4 +566,26 @@ declare function rotateLogFiles(logsDir: string, maxFiles: number): void;
  */
 declare function createLogger(options?: LoggerOptions): Logger;
 
-export { type AdapterFactory, type AnalyzeOptions, type CodacyYamlConfig, type CodacyYamlEngineConfig, type ExecutionMode, type IgnoredFilesResult, type InitDefaultStats, type InitLocalStats, type InitRemoteStats, type LoggerOptions, analyze, applyCodacyYamlExcludes, buildToolConfig, clearAdapters, configureApiToken, createCodacyConfig, createLogger, detectLanguages, formatOutput, formatTextSummary, getAdapter, getRegisteredAdapters, getRegisteredDescriptors, initContainerConfig, initDefaultConfig, initLocalConfig, initRemoteConfig, listDiffFiles, listIgnoredFiles, listPrFiles, listStagedFiles, readCodacyConfig, readCodacyYaml, registerAdapter, registerLazyAdapter, resolveEngineToAdapter, rotateLogFiles, validateApiToken, writeCodacyConfig };
+/**
+ * Repository discovery — scans a codebase and identifies languages, file patterns,
+ * notable files, frameworks, and libraries.
+ *
+ * The discover() function is the main entry point. It runs a 4-phase pipeline:
+ * 1. File discovery (extensions, notable files)
+ * 2. Language detection (reuses detectLanguages)
+ * 3. Manifest parsing (dependency extraction)
+ * 4. Dependency classification (framework / library / platform / tool)
+ */
+
+/** Options for the discover function. */
+interface DiscoverOptions {
+    /** Skip dependency extraction from manifests (only detect files and languages). */
+    skipDependencies?: boolean;
+}
+/**
+ * Scans a repository and returns a structured report of languages, file patterns,
+ * notable files, frameworks, and libraries.
+ */
+declare function discover(repositoryRoot: string, options?: DiscoverOptions): Promise<DiscoveryResult>;
+
+export { type AdapterFactory, type AnalyzeOptions, type AutoFilters, type CategoryFilter, type CodacyYamlConfig, type CodacyYamlEngineConfig, type DiscoverOptions, type ExecutionMode, type IgnoredFilesResult, type InitAutoStats, type InitDefaultStats, type InitLocalStats, type InitRemoteStats, type LoggerOptions, type PatternMetadataLookup, type SeverityFilter, analyze, applyCodacyYamlExcludes, buildToolConfig, clearAdapters, computePatternSummary, configureApiToken, createCodacyConfig, createLogger, detectLanguages, discover, formatOutput, formatTextSummary, getAdapter, getRegisteredAdapters, getRegisteredDescriptors, initAutoConfig, initContainerConfig, initDefaultConfig, initLocalConfig, initRemoteConfig, listDiffFiles, listIgnoredFiles, listPrFiles, listStagedFiles, parseAutoFilters, readCodacyConfig, readCodacyYaml, registerAdapter, registerLazyAdapter, resolveEngineToAdapter, rotateLogFiles, validateApiToken, writeCodacyConfig };