@codacy/analysis-runner 0.8.1 → 0.9.0

package/dist/index.d.ts

@@ -46,6 +46,9 @@ interface AnalyzeOptions {
     gitScope?: "staged" | {
         diff: string | true;
     } | "pr";
+    /** Custom path to the Codacy configuration file. Absolute, or relative to
+     *  `repositoryRoot`. Defaults to `.codacy/codacy.config.json`. */
+    configFile?: string;
     /** Logger for pipeline progress messages (install status, etc.). Defaults to no-op. */
     logger?: Logger;
     /** Called when a tool starts executing. */
@@ -150,14 +153,39 @@ declare function formatTextSummary(result: AnalysisResult, isInspect?: boolean):
  * 3. Default (empty patterns, no local config)
  */
 
+/**
+ * Resolves the absolute path to the Codacy configuration file.
+ *
+ * A custom `configFile` (absolute, or relative to `repositoryRoot`) overrides the
+ * default `.codacy/codacy.config.json` location. This lets callers keep one config
+ * (e.g. synced from Codacy Cloud) while testing a variant side-by-side.
+ */
+declare function resolveConfigPath(repositoryRoot: string, configFile?: string): string;
 /**
  * Reads a CodacyConfig from disk.
  * Returns null if the file doesn't exist. Throws on parse/permission errors
  * so callers can distinguish "no config" from "broken config".
+ *
+ * Pass `configFile` to read from a non-default location.
+ */
+declare function readCodacyConfig(repositoryRoot: string, configFile?: string): Promise<CodacyConfig | null>;
+/**
+ * Writes a CodacyConfig to disk at the exact resolved path, creating only the
+ * parent directory. Unlike {@link writeCodacyConfig}, this has NO `.codacy/`
+ * side effects, so it is safe to write to an arbitrary location (e.g. a scratch
+ * config a user is experimenting with).
+ *
+ * Pass `configFile` to write to a non-default location.
+ */
+declare function writeCodacyConfigFile(repositoryRoot: string, config: CodacyConfig, configFile?: string): Promise<string>;
+/**
+ * Writes a CodacyConfig to disk, creating the target directory if needed.
+ *
+ * Pass `configFile` to write to a non-default location. Regardless of where the
+ * main config lives, `.codacy/.gitignore` is always ensured so generated tool
+ * configs (which always land under `.codacy/generated/`) stay untracked.
  */
-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>;
+declare function writeCodacyConfig(repositoryRoot: string, config: CodacyConfig, configFile?: string): Promise<string>;
 /**
  * Assembles a CodacyToolConfig from the global CodacyConfig and a local config check.
  *
@@ -184,6 +212,61 @@ declare function createCodacyConfig(params?: {
     autoFilters?: string;
 }): CodacyConfig;
 
+/**
+ * Set operations on Codacy configuration files.
+ *
+ * Three operations combine the *tools* and *patterns* of two CodacyConfigs:
+ * - `merge`     — union of tools, and per-tool union of patterns
+ * - `intersect` — tools present in both, and per-tool patterns present in both
+ * - `diff`      — `dest − source`: tools/patterns in dest that are NOT in source
+ *
+ * The result is always built from `dest` (its `version`, `metadata`, and
+ * top-level `exclude`/`includeFiles` are preserved; only `tools` and
+ * `metadata.updatedAt` change), because callers write the result back to the
+ * destination file. Inputs are never mutated.
+ *
+ * Rules that span the operations:
+ * - If either side uses a tool's native config file
+ *   (`useLocalConfigurationFile === true`), the merged/intersected result for
+ *   that tool also uses a config file (patterns dropped). The path comes from
+ *   source when source uses the file, otherwise dest.
+ * - On `diff`, if the *destination* tool uses a config file and source also has
+ *   that tool (with or without a config file), the tool is removed entirely — a
+ *   config file's enabled rules are opaque, so it cannot be subtracted.
+ * - When a pattern exists on both sides during merge/intersect, its parameters
+ *   are taken from source.
+ * - On `intersect`/`diff`, a tool left with no patterns and no config file is a
+ *   no-op and is dropped from the result. `merge` always preserves its inputs.
+ */
+
+/** The set operation to apply between two configs. */
+type ConfigOperation = "merge" | "intersect" | "diff";
+/**
+ * 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.
+ */
+declare function mergeConfigs(source: CodacyConfig, dest: CodacyConfig): 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
+ * config file). Tools left empty (no patterns, no config file) are dropped.
+ */
+declare function intersectConfigs(source: CodacyConfig, dest: CodacyConfig): CodacyConfig;
+/**
+ * `dest − source`: keeps tools/patterns in dest that are not in source.
+ * - A tool only in dest is kept whole.
+ * - A dest tool that uses a config file and is also present in source is removed
+ *   entirely (its enabled rules are opaque and cannot be subtracted).
+ * - Otherwise dest's inline patterns minus source's patterns are kept (a source
+ *   tool using a config file enumerates no patterns, so all dest patterns survive).
+ * - Tools left empty after subtraction are dropped.
+ */
+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;
+
 /**
  * auto-filters.ts — Parses and applies --auto filter syntax.
  *
@@ -590,4 +673,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 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 };
+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 };

package/dist/index.js

@@ -32,6 +32,7 @@ var index_exports = {};
 __export(index_exports, {
   analyze: () => analyze,
   applyCodacyYamlExcludes: () => applyCodacyYamlExcludes,
+  applyConfigOperation: () => applyConfigOperation,
   buildToolConfig: () => buildToolConfig,
   clearAdapters: () => clearAdapters,
   computePatternSummary: () => computePatternSummary,
@@ -39,6 +40,7 @@ __export(index_exports, {
   createCodacyConfig: () => createCodacyConfig,
   createLogger: () => createLogger,
   detectLanguages: () => detectLanguages,
+  diffConfigs: () => diffConfigs,
   discover: () => discover,
   formatOutput: () => formatOutput,
   formatTextSummary: () => formatTextSummary,
@@ -50,19 +52,23 @@ __export(index_exports, {
   initDefaultConfig: () => initDefaultConfig,
   initLocalConfig: () => initLocalConfig,
   initRemoteConfig: () => initRemoteConfig,
+  intersectConfigs: () => intersectConfigs,
   listDiffFiles: () => listDiffFiles,
   listIgnoredFiles: () => listIgnoredFiles,
   listPrFiles: () => listPrFiles,
   listStagedFiles: () => listStagedFiles,
+  mergeConfigs: () => mergeConfigs,
   parseAutoFilters: () => parseAutoFilters,
   readCodacyConfig: () => readCodacyConfig,
   readCodacyYaml: () => readCodacyYaml,
   registerAdapter: () => registerAdapter,
   registerLazyAdapter: () => registerLazyAdapter,
+  resolveConfigPath: () => resolveConfigPath,
   resolveEngineToAdapter: () => resolveEngineToAdapter,
   rotateLogFiles: () => rotateLogFiles,
   validateApiToken: () => validateApiToken,
-  writeCodacyConfig: () => writeCodacyConfig
+  writeCodacyConfig: () => writeCodacyConfig,
+  writeCodacyConfigFile: () => writeCodacyConfigFile
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -127,8 +133,11 @@ var import_promises = __toESM(require("fs/promises"));
 var import_path = __toESM(require("path"));
 var CODACY_DIR = ".codacy";
 var CONFIG_FILE = "codacy.config.json";
-async function readCodacyConfig(repositoryRoot) {
-  const configPath = import_path.default.join(repositoryRoot, CODACY_DIR, CONFIG_FILE);
+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) {
+  const configPath = resolveConfigPath(repositoryRoot, configFile);
   let raw;
   try {
     raw = await import_promises.default.readFile(configPath, "utf-8");
@@ -154,13 +163,17 @@ function coerceParameterValues(config) {
     }
   }
 }
-async function writeCodacyConfig(repositoryRoot, config) {
+async function writeCodacyConfigFile(repositoryRoot, config, configFile) {
+  const configPath = resolveConfigPath(repositoryRoot, configFile);
+  await import_promises.default.mkdir(import_path.default.dirname(configPath), { recursive: true });
+  await import_promises.default.writeFile(configPath, JSON.stringify(config, null, 2) + "\n");
+  return configPath;
+}
+async function writeCodacyConfig(repositoryRoot, config, configFile) {
   const codacyDir = import_path.default.join(repositoryRoot, CODACY_DIR);
   await import_promises.default.mkdir(codacyDir, { recursive: true });
   await ensureGitignore(codacyDir);
-  const configPath = import_path.default.join(codacyDir, CONFIG_FILE);
-  await import_promises.default.writeFile(configPath, JSON.stringify(config, null, 2) + "\n");
-  return configPath;
+  return writeCodacyConfigFile(repositoryRoot, config, configFile);
 }
 async function ensureGitignore(codacyDir) {
   const gitignorePath = import_path.default.join(codacyDir, ".gitignore");
@@ -657,9 +670,10 @@ async function analyze(options) {
       []
     );
   }
+  const configLabel = options.configFile ?? ".codacy/codacy.config.json";
   let codacyConfig;
   try {
-    codacyConfig = await readCodacyConfig(options.repositoryRoot);
+    codacyConfig = await readCodacyConfig(options.repositoryRoot, options.configFile);
   } catch (err) {
     return buildResult(
       startedAt,
@@ -672,7 +686,7 @@ async function analyze(options) {
           toolId: "runner",
           phase: "toolConfig",
           kind: "InvalidConfig",
-          message: `.codacy/codacy.config.json is invalid: ${err instanceof Error ? err.message : String(err)}`,
+          message: `${configLabel} is invalid: ${err instanceof Error ? err.message : String(err)}`,
           level: "error"
         }
       ],
@@ -691,7 +705,7 @@ async function analyze(options) {
           toolId: "runner",
           phase: "toolConfig",
           kind: "MissingConfig",
-          message: "No .codacy/codacy.config.json found. Run `codacy-analysis init` to initialize the repository.",
+          message: `No ${configLabel} found. ` + (options.configFile ? `Run \`codacy-analysis init --config-file ${options.configFile}\` to initialize the repository.` : "Run `codacy-analysis init` to initialize the repository."),
           level: "error"
         }
       ],
@@ -1563,6 +1577,171 @@ function formatPatternSummary(summary) {
   return lines.join("\n");
 }
 
+// src/config-ops.ts
+function usesConfigFile(tool) {
+  return tool.useLocalConfigurationFile === true;
+}
+function isEmptyTool(tool) {
+  return !usesConfigFile(tool) && tool.patterns.length === 0;
+}
+function indexByToolId(tools) {
+  return new Map(tools.map((t) => [t.toolId, t]));
+}
+function indexByPatternId(patterns) {
+  return new Map(patterns.map((p) => [p.patternId, p]));
+}
+function unionList(dest, source) {
+  const result = [.../* @__PURE__ */ new Set([...dest ?? [], ...source ?? []])];
+  return result.length > 0 ? result : void 0;
+}
+function intersectList(dest, source) {
+  if (!dest || !source) return void 0;
+  const sourceSet = new Set(source);
+  const result = dest.filter((x) => sourceSet.has(x));
+  return result.length > 0 ? result : void 0;
+}
+function clonePattern(pattern) {
+  const result = { patternId: pattern.patternId };
+  if (pattern.parameters !== void 0) result.parameters = { ...pattern.parameters };
+  return result;
+}
+function cloneTool(tool) {
+  return structuredClone(tool);
+}
+function applyToolLevelLists(tool, source, dest, listFn) {
+  const exclude = listFn(dest.exclude, source.exclude);
+  if (exclude) tool.exclude = exclude;
+  const extraFilePatterns = listFn(dest.extraFilePatterns, source.extraFilePatterns);
+  if (extraFilePatterns) tool.extraFilePatterns = extraFilePatterns;
+}
+function buildConfigFileTool(toolId, source, dest, listFn) {
+  const localConfigurationFile = (usesConfigFile(source) ? source.localConfigurationFile : void 0) ?? dest.localConfigurationFile;
+  const tool = {
+    toolId,
+    ...localConfigurationFile !== void 0 ? { localConfigurationFile } : {},
+    useLocalConfigurationFile: true,
+    patterns: []
+  };
+  applyToolLevelLists(tool, source, dest, listFn);
+  return tool;
+}
+function mergePatterns(source, dest) {
+  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));
+    seen.add(dp.patternId);
+  }
+  for (const sp of source) {
+    if (!seen.has(sp.patternId)) result.push(clonePattern(sp));
+  }
+  return result;
+}
+function intersectPatterns(source, dest) {
+  const sourceMap = indexByPatternId(source);
+  const result = [];
+  for (const dp of dest) {
+    const sp = sourceMap.get(dp.patternId);
+    if (sp) result.push(clonePattern(sp));
+  }
+  return result;
+}
+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) {
+  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 tool = { toolId, patterns };
+  if (dest.useLocalConfigurationFile !== void 0) {
+    tool.useLocalConfigurationFile = dest.useLocalConfigurationFile;
+  } else if (source.useLocalConfigurationFile !== void 0) {
+    tool.useLocalConfigurationFile = source.useLocalConfigurationFile;
+  }
+  applyToolLevelLists(tool, source, dest, listFn);
+  return tool;
+}
+function buildResultConfig(dest, tools) {
+  const result = {
+    version: dest.version,
+    metadata: { ...structuredClone(dest.metadata), updatedAt: (/* @__PURE__ */ new Date()).toISOString() },
+    tools
+  };
+  if (dest.exclude !== void 0) result.exclude = structuredClone(dest.exclude);
+  if (dest.includeFiles !== void 0) result.includeFiles = structuredClone(dest.includeFiles);
+  return result;
+}
+function mergeConfigs(source, dest) {
+  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));
+    seen.add(d.toolId);
+  }
+  for (const s of source.tools) {
+    if (!seen.has(s.toolId)) tools.push(cloneTool(s));
+  }
+  return buildResultConfig(dest, tools);
+}
+function intersectConfigs(source, dest) {
+  const sourceMap = indexByToolId(source.tools);
+  const tools = [];
+  for (const d of dest.tools) {
+    const s = sourceMap.get(d.toolId);
+    if (!s) continue;
+    const tool = combineTool("intersect", d.toolId, s, d);
+    if (isEmptyTool(tool)) continue;
+    tools.push(tool);
+  }
+  return buildResultConfig(dest, tools);
+}
+function diffConfigs(source, dest) {
+  const sourceMap = indexByToolId(source.tools);
+  const tools = [];
+  for (const d of dest.tools) {
+    const s = sourceMap.get(d.toolId);
+    if (!s) {
+      tools.push(cloneTool(d));
+      continue;
+    }
+    if (usesConfigFile(d)) continue;
+    const tool = {
+      toolId: d.toolId,
+      patterns: diffPatterns(s.patterns, d.patterns)
+    };
+    if (d.useLocalConfigurationFile !== void 0) {
+      tool.useLocalConfigurationFile = d.useLocalConfigurationFile;
+    }
+    if (d.exclude !== void 0) tool.exclude = [...d.exclude];
+    if (d.extraFilePatterns !== void 0) tool.extraFilePatterns = [...d.extraFilePatterns];
+    if (isEmptyTool(tool)) continue;
+    tools.push(tool);
+  }
+  return buildResultConfig(dest, tools);
+}
+function applyConfigOperation(op, source, dest) {
+  switch (op) {
+    case "merge":
+      return mergeConfigs(source, dest);
+    case "intersect":
+      return intersectConfigs(source, dest);
+    case "diff":
+      return diffConfigs(source, dest);
+    default: {
+      const exhaustive = op;
+      throw new Error(`Unknown config operation: ${String(exhaustive)}`);
+    }
+  }
+}
+
 // src/init.ts
 var import_promises4 = __toESM(require("fs/promises"));
 var import_path7 = __toESM(require("path"));
@@ -6549,6 +6728,7 @@ function createLogger(options = {}) {
 0 && (module.exports = {
   analyze,
   applyCodacyYamlExcludes,
+  applyConfigOperation,
   buildToolConfig,
   clearAdapters,
   computePatternSummary,
@@ -6556,6 +6736,7 @@ function createLogger(options = {}) {
   createCodacyConfig,
   createLogger,
   detectLanguages,
+  diffConfigs,
   discover,
   formatOutput,
   formatTextSummary,
@@ -6567,17 +6748,21 @@ function createLogger(options = {}) {
   initDefaultConfig,
   initLocalConfig,
   initRemoteConfig,
+  intersectConfigs,
   listDiffFiles,
   listIgnoredFiles,
   listPrFiles,
   listStagedFiles,
+  mergeConfigs,
   parseAutoFilters,
   readCodacyConfig,
   readCodacyYaml,
   registerAdapter,
   registerLazyAdapter,
+  resolveConfigPath,
   resolveEngineToAdapter,
   rotateLogFiles,
   validateApiToken,
-  writeCodacyConfig
+  writeCodacyConfig,
+  writeCodacyConfigFile
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codacy/analysis-runner",
-  "version": "0.8.1",
+  "version": "0.9.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.8.1"
+    "@codacy/tooling": "0.9.0"
   },
   "devDependencies": {
     "@codacy/openapi-typescript-codegen": "0.0.9",
-    "@codacy/tools-dummy-1": "0.8.1"
+    "@codacy/tools-dummy-1": "0.9.0"
   },
   "license": "MIT",
   "author": "Codacy <support@codacy.com> (https://www.codacy.com)",