@codacy/analysis-runner 0.13.0 → 0.14.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-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';
+import { OutputFormat, Logger, ProxyConfig, AnalysisResult, ToolAdapter, AdapterDescriptor, CodacyConfig, ConfigurationFileCheckResult, CodacyToolConfig, IssueSeverity, IssueCategory, Language, DiscoveryResult, PatternEntry, Issue, PatternSummary, LogLevel } from '@codacy/tooling';
+export { AnalysisResult, OutputFormat, ProxyConfig, configureProxy, resolveProxyConfig } from '@codacy/tooling';
 
 /**
  * Main analysis entry point — orchestrates the full analysis pipeline.
@@ -66,6 +66,15 @@ interface AnalyzeOptions {
     onToolComplete?: (toolId: string, displayName: string, issueCount: number, durationMs: number) => void;
     /** Called when a tool reports mid-execution progress (e.g. "Linting 50/200 files"). */
     onToolProgress?: (toolId: string, displayName: string, message: string) => void;
+    /**
+     * Optional proxy/TLS configuration for outbound HTTP (API calls and tool
+     * downloads). When provided, it is applied via `configureProxy` at the start of
+     * `analyze()`, installing a global fetch dispatcher. Library consumers that
+     * make API calls outside `analyze()` (e.g. init) should instead call
+     * `configureProxy` themselves once at startup. Omit to rely on environment
+     * variables (HTTP(S)_PROXY, NO_PROXY, SSL_CERT_FILE, CODACY_CLI_INSECURE).
+     */
+    proxy?: Partial<ProxyConfig>;
 }
 /**
  * Runs analysis on the given repository and returns the unified result.
@@ -181,6 +190,15 @@ declare function formatTextSummary(result: AnalysisResult, isInspect?: boolean):
  * (e.g. synced from Codacy Cloud) while testing a variant side-by-side.
  */
 declare function resolveConfigPath(repositoryRoot: string, configFile?: string): string;
+/**
+ * Resolves the absolute path to the config's baseline snapshot — the config the
+ * generator last produced, used by `update-config` to distinguish user-disabled
+ * patterns from default-off ones. It is a sibling of the config file
+ * (`<name>.json` → `<name>.baseline.json`), so `.codacy/codacy.config.json` maps
+ * to `.codacy/codacy.config.baseline.json`. It lives outside `.codacy/generated/`
+ * so it is committed and travels with the config.
+ */
+declare function resolveBaselinePath(repositoryRoot: string, configFile?: string): string;
 /**
  * Reads a CodacyConfig from disk.
  * Returns null if the file doesn't exist. Throws on parse/permission errors
@@ -189,6 +207,19 @@ declare function resolveConfigPath(repositoryRoot: string, configFile?: string):
  * Pass `configFile` to read from a non-default location.
  */
 declare function readCodacyConfig(repositoryRoot: string, configFile?: string): Promise<CodacyConfig | null>;
+/**
+ * Reads the config's baseline snapshot (see {@link resolveBaselinePath}).
+ * Returns null when no baseline exists (e.g. a config created before baselines
+ * were introduced), so `update-config` can fall back gracefully.
+ */
+declare function readBaselineConfig(repositoryRoot: string, configFile?: string): Promise<CodacyConfig | null>;
+/**
+ * Writes the config's baseline snapshot next to the config file (see
+ * {@link resolveBaselinePath}). No `.codacy/` side effects. Callers write this
+ * after every `init`/`update-config` so the next update diffs against the exact
+ * generator output. Returns the path written.
+ */
+declare function writeBaselineConfig(repositoryRoot: string, config: CodacyConfig, configFile?: string): Promise<string>;
 /**
  * Writes a CodacyConfig to disk at the exact resolved path, creating only the
  * parent directory. Unlike {@link writeCodacyConfig}, this has NO `.codacy/`
@@ -261,13 +292,23 @@ declare function createCodacyConfig(params?: {
 
 /** The set operation to apply between two configs. */
 type ConfigOperation = "merge" | "intersect" | "diff";
+/** Options for {@link mergeConfigs}. */
+interface MergeOptions {
+    /**
+     * When a pattern exists on both sides, keep dest's parameters instead of the
+     * default source-wins behavior. Used by the incremental update so the user's
+     * tuned parameters (dest) survive over freshly-generated defaults (source).
+     */
+    preferDestParameters?: boolean;
+}
 /**
  * Union of source and dest at the tool and pattern level.
  * Tools present on only one side are carried over as-is; tools on both sides are
- * combined (config-file rule, then per-tool pattern union with source parameters
- * winning). Never drops tools.
+ * combined (config-file rule, then per-tool pattern union). Parameters of a
+ * pattern on both sides come from source unless `options.preferDestParameters`.
+ * Never drops tools.
  */
-declare function mergeConfigs(source: CodacyConfig, dest: CodacyConfig): CodacyConfig;
+declare function mergeConfigs(source: CodacyConfig, dest: CodacyConfig, options?: MergeOptions): CodacyConfig;
 /**
  * Intersection of source and dest: only tools present in both, and per-tool only
  * the patterns present in both (config-file rule applies when either side uses a
@@ -286,6 +327,40 @@ declare function intersectConfigs(source: CodacyConfig, dest: CodacyConfig): Cod
 declare function diffConfigs(source: CodacyConfig, dest: CodacyConfig): CodacyConfig;
 /** Dispatches to the {@link mergeConfigs}, {@link intersectConfigs}, or {@link diffConfigs}. */
 declare function applyConfigOperation(op: ConfigOperation, source: CodacyConfig, dest: CodacyConfig): CodacyConfig;
+/**
+ * Returns a copy of `config` with tools that would do nothing removed — a tool
+ * with no enabled patterns and no native config file. Used after the incremental
+ * update so a tool whose every pattern was removed (e.g. its language/framework
+ * left the repo) drops out entirely. Config-file tools are always kept (they run
+ * from their own file). Does not mutate the input.
+ */
+declare function pruneEmptyTools(config: CodacyConfig): CodacyConfig;
+/**
+ * Incrementally updates a Codacy config while preserving user customizations.
+ *
+ * Three-way merge over the enabled-only config model (a disabled pattern is
+ * indistinguishable from a default-off one, so a naive re-generate + merge would
+ * resurrect patterns the user deliberately removed):
+ *
+ *   - `base`    — the config the generator last produced (pre-user-edit baseline)
+ *   - `current` — the user's live config (baseline + their edits)
+ *   - `next`    — the config the generator produces now (for the current stack)
+ *
+ *   added        = next − base       (genuinely new tools/patterns to add)
+ *   removed      = base − next       (tools/patterns whose stack element is gone)
+ *   result       = (current − removed) + added
+ *
+ * User-disabled patterns stay absent (they're in `base`, so never in `added`);
+ * user-tuned parameters and manual excludes ride along in `current` (dest wins on
+ * parameter conflicts via `preferDestParameters`). Identity/provenance metadata
+ * (`createdAt`, `source`, organization, …) come from `current`; `updatedAt` is
+ * refreshed and `metadata.languages` is refreshed from `next` (an incremental
+ * update is effectively a re-discovery, so the recorded stack must reflect the
+ * current repository, not the languages captured when the config was first
+ * written). Top-level `exclude` is reconciled with the same three-way logic, and
+ * any tool left with no patterns and no config file is pruned. Inputs are not mutated.
+ */
+declare function updateConfigIncremental(base: CodacyConfig, current: CodacyConfig, next: CodacyConfig): CodacyConfig;
 
 /**
  * auto-filters.ts — Parses and applies --auto filter syntax.
@@ -778,4 +853,4 @@ declare function discover(repositoryRoot: string, options?: DiscoverOptions): Pr
  */
 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 };
+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 MergeOptions, 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, pruneEmptyTools, readBaselineConfig, readCodacyConfig, readCodacyYaml, registerAdapter, registerLazyAdapter, registerUnsupportedTool, resolveApiToken, resolveBaselinePath, resolveConfigPath, resolveEngineToAdapter, rotateLogFiles, saveCredentials, updateConfigIncremental, validateApiToken, writeBaselineConfig, writeCodacyConfig, writeCodacyConfigFile };

package/dist/index.js

@@ -37,6 +37,7 @@ __export(index_exports, {
   clearAdapters: () => clearAdapters,
   computePatternSummary: () => computePatternSummary,
   configureApiToken: () => configureApiToken,
+  configureProxy: () => import_tooling6.configureProxy,
   createCodacyConfig: () => createCodacyConfig,
   createLogger: () => createLogger,
   createNullLogger: () => createNullLogger,
@@ -63,17 +64,23 @@ __export(index_exports, {
   loadCredentials: () => loadCredentials,
   mergeConfigs: () => mergeConfigs,
   parseAutoFilters: () => parseAutoFilters,
+  pruneEmptyTools: () => pruneEmptyTools,
+  readBaselineConfig: () => readBaselineConfig,
   readCodacyConfig: () => readCodacyConfig,
   readCodacyYaml: () => readCodacyYaml,
   registerAdapter: () => registerAdapter,
   registerLazyAdapter: () => registerLazyAdapter,
   registerUnsupportedTool: () => registerUnsupportedTool,
   resolveApiToken: () => resolveApiToken,
+  resolveBaselinePath: () => resolveBaselinePath,
   resolveConfigPath: () => resolveConfigPath,
   resolveEngineToAdapter: () => resolveEngineToAdapter,
+  resolveProxyConfig: () => import_tooling6.resolveProxyConfig,
   rotateLogFiles: () => rotateLogFiles,
   saveCredentials: () => saveCredentials,
+  updateConfigIncremental: () => updateConfigIncremental,
   validateApiToken: () => validateApiToken,
+  writeBaselineConfig: () => writeBaselineConfig,
   writeCodacyConfig: () => writeCodacyConfig,
   writeCodacyConfigFile: () => writeCodacyConfigFile
 });
@@ -154,8 +161,14 @@ var CONFIG_FILE = "codacy.config.json";
 function resolveConfigPath(repositoryRoot, configFile) {
   return configFile ? import_path.default.resolve(repositoryRoot, configFile) : import_path.default.join(repositoryRoot, CODACY_DIR, CONFIG_FILE);
 }
-async function readCodacyConfig(repositoryRoot, configFile) {
+function resolveBaselinePath(repositoryRoot, configFile) {
   const configPath = resolveConfigPath(repositoryRoot, configFile);
+  const dir = import_path.default.dirname(configPath);
+  const ext = import_path.default.extname(configPath);
+  const stem = import_path.default.basename(configPath, ext);
+  return import_path.default.join(dir, `${stem}.baseline${ext}`);
+}
+async function readConfigAtPath(configPath) {
   let raw;
   try {
     raw = await import_promises.default.readFile(configPath, "utf-8");
@@ -165,10 +178,26 @@ async function readCodacyConfig(repositoryRoot, configFile) {
     }
     throw err;
   }
-  const config = JSON.parse(raw);
+  const parsed = JSON.parse(raw);
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new Error(`Invalid config at ${configPath}: expected a JSON object`);
+  }
+  const config = parsed;
   coerceParameterValues(config);
   return config;
 }
+async function readCodacyConfig(repositoryRoot, configFile) {
+  return readConfigAtPath(resolveConfigPath(repositoryRoot, configFile));
+}
+async function readBaselineConfig(repositoryRoot, configFile) {
+  return readConfigAtPath(resolveBaselinePath(repositoryRoot, configFile));
+}
+async function writeBaselineConfig(repositoryRoot, config, configFile) {
+  const baselinePath = resolveBaselinePath(repositoryRoot, configFile);
+  await import_promises.default.mkdir(import_path.default.dirname(baselinePath), { recursive: true });
+  await import_promises.default.writeFile(baselinePath, JSON.stringify(config, null, 2) + "\n");
+  return baselinePath;
+}
 function coerceParameterValues(config) {
   for (const tool of config.tools) {
     for (const pattern of tool.patterns) {
@@ -987,6 +1016,7 @@ async function mapWithConcurrency(items, concurrency, task) {
 }
 async function analyze(options) {
   const startedAt = /* @__PURE__ */ new Date();
+  if (options.proxy) (0, import_tooling3.configureProxy)(options.proxy);
   const mode = options.mode || "standard";
   const toolTimeout = options.toolTimeout || 9e5;
   const parallelTools = options.parallelTools || 1;
@@ -2110,13 +2140,13 @@ function buildConfigFileTool(toolId, source, dest, listFn) {
   applyToolLevelLists(tool, source, dest, listFn);
   return tool;
 }
-function mergePatterns(source, dest) {
+function mergePatterns(source, dest, preferDest = false) {
   const sourceMap = indexByPatternId(source);
   const seen = /* @__PURE__ */ new Set();
   const result = [];
   for (const dp of dest) {
     const sp = sourceMap.get(dp.patternId);
-    result.push(clonePattern(sp ?? dp));
+    result.push(clonePattern(preferDest ? dp : sp ?? dp));
     seen.add(dp.patternId);
   }
   for (const sp of source) {
@@ -2137,12 +2167,12 @@ function diffPatterns(source, dest) {
   const sourceIds = new Set(source.map((p) => p.patternId));
   return dest.filter((dp) => !sourceIds.has(dp.patternId)).map(clonePattern);
 }
-function combineTool(op, toolId, source, dest) {
+function combineTool(op, toolId, source, dest, preferDest = false) {
   const listFn = op === "merge" ? unionList : intersectList;
   if (usesConfigFile(source) || usesConfigFile(dest)) {
     return buildConfigFileTool(toolId, source, dest, listFn);
   }
-  const patterns = op === "merge" ? mergePatterns(source.patterns, dest.patterns) : intersectPatterns(source.patterns, dest.patterns);
+  const patterns = op === "merge" ? mergePatterns(source.patterns, dest.patterns, preferDest) : intersectPatterns(source.patterns, dest.patterns);
   const tool = { toolId, patterns };
   if (dest.useLocalConfigurationFile !== void 0) {
     tool.useLocalConfigurationFile = dest.useLocalConfigurationFile;
@@ -2162,13 +2192,14 @@ function buildResultConfig(dest, tools) {
   if (dest.includeFiles !== void 0) result.includeFiles = structuredClone(dest.includeFiles);
   return result;
 }
-function mergeConfigs(source, dest) {
+function mergeConfigs(source, dest, options = {}) {
+  const preferDest = options.preferDestParameters === true;
   const sourceMap = indexByToolId(source.tools);
   const seen = /* @__PURE__ */ new Set();
   const tools = [];
   for (const d of dest.tools) {
     const s = sourceMap.get(d.toolId);
-    tools.push(s ? combineTool("merge", d.toolId, s, d) : cloneTool(d));
+    tools.push(s ? combineTool("merge", d.toolId, s, d, preferDest) : cloneTool(d));
     seen.add(d.toolId);
   }
   for (const s of source.tools) {
@@ -2226,6 +2257,39 @@ function applyConfigOperation(op, source, dest) {
     }
   }
 }
+function pruneEmptyTools(config) {
+  const tools = config.tools.filter((t) => !isEmptyTool(t));
+  if (tools.length === config.tools.length) return config;
+  return { ...config, tools };
+}
+function threeWayList(base = [], current = [], next = []) {
+  const baseSet = new Set(base);
+  const nextSet = new Set(next);
+  const removed = new Set(base.filter((x) => !nextSet.has(x)));
+  const added = next.filter((x) => !baseSet.has(x));
+  const kept = current.filter((x) => !removed.has(x));
+  const seen = /* @__PURE__ */ new Set();
+  const result = [];
+  for (const x of [...kept, ...added]) {
+    if (!seen.has(x)) {
+      seen.add(x);
+      result.push(x);
+    }
+  }
+  return result;
+}
+function updateConfigIncremental(base, current, next) {
+  const added = diffConfigs(base, next);
+  const removed = diffConfigs(next, base);
+  const afterRemoval = diffConfigs(removed, current);
+  const merged = mergeConfigs(added, afterRemoval, { preferDestParameters: true });
+  const exclude = threeWayList(base.exclude, current.exclude, next.exclude);
+  const result = { ...merged };
+  if (exclude.length > 0) result.exclude = exclude;
+  else delete result.exclude;
+  result.metadata = { ...merged.metadata, languages: [...next.metadata.languages] };
+  return pruneEmptyTools(result);
+}
 
 // src/init.ts
 var import_promises4 = __toESM(require("fs/promises"));
@@ -7410,6 +7474,9 @@ function parseAutoFilters(raw) {
   return { filters: { severities, categories }, unknown };
 }
 
+// src/index.ts
+var import_tooling6 = require("@codacy/tooling");
+
 // src/credentials.ts
 var import_crypto = __toESM(require("crypto"));
 var import_promises5 = __toESM(require("fs/promises"));
@@ -7482,6 +7549,7 @@ async function resolveApiToken() {
   clearAdapters,
   computePatternSummary,
   configureApiToken,
+  configureProxy,
   createCodacyConfig,
   createLogger,
   createNullLogger,
@@ -7508,17 +7576,23 @@ async function resolveApiToken() {
   loadCredentials,
   mergeConfigs,
   parseAutoFilters,
+  pruneEmptyTools,
+  readBaselineConfig,
   readCodacyConfig,
   readCodacyYaml,
   registerAdapter,
   registerLazyAdapter,
   registerUnsupportedTool,
   resolveApiToken,
+  resolveBaselinePath,
   resolveConfigPath,
   resolveEngineToAdapter,
+  resolveProxyConfig,
   rotateLogFiles,
   saveCredentials,
+  updateConfigIncremental,
   validateApiToken,
+  writeBaselineConfig,
   writeCodacyConfig,
   writeCodacyConfigFile
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codacy/analysis-runner",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Core orchestration engine for Codacy analysis",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -12,11 +12,11 @@
     "cli-table3": "^0.6",
     "minimatch": "10.2.4",
     "yaml": "^2.6.0",
-    "@codacy/tooling": "0.13.0"
+    "@codacy/tooling": "0.14.0"
   },
   "devDependencies": {
     "@codacy/openapi-typescript-codegen": "0.0.9",
-    "@codacy/tools-dummy-1": "0.13.0"
+    "@codacy/tools-dummy-1": "0.14.0"
   },
   "license": "MIT",
   "author": "Codacy <support@codacy.com> (https://www.codacy.com)",