feat: add --ignore-paths option with glob wildcard support

Adds ignore-paths input to the GitHub Action (YAML list format) and
--ignore-paths CLI flag (comma-separated) to all commands. Patterns
support * (single dir), ** (recursive), and ? (single char) wildcards.

Also adds devenv/direnv setup for local development and tests for
the ignore-paths filtering logic.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: aspala

.envrc

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+
+export DIRENV_WARN_TIMEOUT=20s
+
+eval "$(devenv direnvrc)"
+
+use devenv

.gitignore

@@ -3,3 +3,9 @@
 /doc/
 erl_crash.dump
 *.ez
+
+# devenv
+.devenv
+.devenv.flake.nix
+.devenv.local.nix
+devenv.lock

action.yml

@@ -42,6 +42,10 @@ inputs:
     description: "Path to .codeqa.yml config file"
     required: false
     default: ""
+  ignore-paths:
+    description: "YAML list of path patterns to ignore (supports wildcards, e.g. 'test/*')"
+    required: false
+    default: ""
   extra-args:
     description: "Additional CLI flags passed through to codeqa"
     required: false
@@ -78,6 +82,7 @@ runs:
         INPUT_TOP: ${{ inputs.top }}
         INPUT_FORMAT: ${{ inputs.format }}
         INPUT_CONFIG: ${{ inputs.config }}
+        INPUT_IGNORE_PATHS: ${{ inputs.ignore-paths }}
         INPUT_EXTRA_ARGS: ${{ inputs.extra-args }}
         INPUT_BASE_REF: ${{ inputs.base-ref }}
         INPUT_VERSION: ${{ inputs.version }}

devenv.nix

@@ -0,0 +1,15 @@
+{pkgs, ...}: {
+  packages = [
+    pkgs.beam.packages.erlang_27.elixir_1_19
+  ];
+
+  languages.elixir = {
+    enable = true;
+    package = pkgs.beam.packages.erlang_27.elixir_1_19;
+  };
+
+  enterShell = ''
+    elixir --version
+    mix deps.get
+  '';
+}

devenv.yaml

@@ -0,0 +1,3 @@
+inputs:
+  nixpkgs:
+    url: github:cachix/devenv-nixpkgs/rolling

lib/codeqa/cli.ex

@@ -17,7 +17,7 @@ defmodule CodeQA.CLI do
 
   defp handle_analyze(args) do
     {opts, [path], _} = OptionParser.parse(args,
-      strict: [output: :string, progress: :boolean, workers: :integer, cache: :boolean, cache_dir: :string, timeout: :integer, show_ncd: :boolean, ncd_top: :integer, ncd_paths: :string, show_files: :boolean, show_file_paths: :string, combinations: :boolean, telemetry: :boolean, experimental_stopwords: :boolean, stopwords_threshold: :float],
+      strict: [output: :string, progress: :boolean, workers: :integer, cache: :boolean, cache_dir: :string, timeout: :integer, show_ncd: :boolean, ncd_top: :integer, ncd_paths: :string, show_files: :boolean, show_file_paths: :string, combinations: :boolean, telemetry: :boolean, experimental_stopwords: :boolean, stopwords_threshold: :float, ignore_paths: :string],
       aliases: [o: :output, w: :workers, t: :timeout]
     )
 
@@ -28,7 +28,8 @@ defmodule CodeQA.CLI do
       exit({:shutdown, 1})
     end
 
-    files = CodeQA.Collector.collect_files(path)
+    ignore_patterns = parse_ignore_paths(opts[:ignore_paths])
+    files = CodeQA.Collector.collect_files(path, ignore_patterns: ignore_patterns)
     if map_size(files) == 0 do
       IO.puts(:stderr, "Warning: no source files found in '#{path}'")
       exit({:shutdown, 1})
@@ -88,7 +89,8 @@ defmodule CodeQA.CLI do
         ncd_top: :integer, ncd_paths: :string,
         combinations: :boolean, telemetry: :boolean,
         experimental_stopwords: :boolean, stopwords_threshold: :float,
-        show_files: :boolean, show_file_paths: :string
+        show_files: :boolean, show_file_paths: :string,
+        ignore_paths: :string
       ],
       aliases: [w: :workers, t: :timeout]
     )
@@ -106,6 +108,8 @@ defmodule CodeQA.CLI do
       exit({:shutdown, 1})
     end
 
+    ignore_patterns = parse_ignore_paths(opts[:ignore_paths])
+    opts = Keyword.put(opts, :ignore_patterns, ignore_patterns)
     {base_result, head_result, changes} = run_comparison(path, base_ref, head_ref, changes_only, opts)
 
     comparison =
@@ -127,7 +131,8 @@ defmodule CodeQA.CLI do
         timeout: :integer, show_ncd: :boolean,
         ncd_top: :integer, ncd_paths: :string,
         combinations: :boolean,
-        show_files: :boolean, show_file_paths: :string
+        show_files: :boolean, show_file_paths: :string,
+        ignore_paths: :string
       ],
       aliases: [n: :commits, o: :output_dir, w: :workers, t: :timeout]
     )
@@ -154,6 +159,7 @@ defmodule CodeQA.CLI do
     IO.puts(:stderr, "Found #{length(commits)} commits to analyze.")
 
     analyze_opts = build_analyze_opts(opts)
+    ignore_patterns = parse_ignore_paths(opts[:ignore_paths])
 
     commits
     |> Enum.with_index(1)
@@ -164,6 +170,7 @@ defmodule CodeQA.CLI do
       current_opts = if opts[:progress], do: [{:on_progress, fn c, t, p, _tt -> progress_callback(c, t, p, start_time_progress) end} | analyze_opts], else: analyze_opts
 
       files = CodeQA.Git.collect_files_at_ref(path, commit)
+      files = CodeQA.Collector.reject_ignored_map(files, ignore_patterns)
 
       if map_size(files) == 0 do
         IO.puts(:stderr, "Warning: no source files found at commit #{commit}")
@@ -410,7 +417,9 @@ defmodule CodeQA.CLI do
   end
 
   defp run_comparison(path, base_ref, head_ref, changes_only, opts) do
+    ignore_patterns = opts[:ignore_patterns] || []
     changes = CodeQA.Git.changed_files(path, base_ref, head_ref)
+    changes = CodeQA.Collector.reject_ignored(changes, ignore_patterns, & &1.path)
 
     file_paths = if changes_only do
       IO.puts(:stderr, "Comparing #{length(changes)} changed files...")
@@ -422,6 +431,8 @@ defmodule CodeQA.CLI do
 
     base_files = CodeQA.Git.collect_files_at_ref(path, base_ref, file_paths)
     head_files = CodeQA.Git.collect_files_at_ref(path, head_ref, file_paths)
+    base_files = CodeQA.Collector.reject_ignored_map(base_files, ignore_patterns)
+    head_files = CodeQA.Collector.reject_ignored_map(head_files, ignore_patterns)
 
     if map_size(base_files) == 0 and map_size(head_files) == 0 do
       IO.puts(:stderr, "Warning: no source files found at either ref")
@@ -538,7 +549,7 @@ defmodule CodeQA.CLI do
 
   defp handle_stopwords(args) do
     {opts, [path], _} = OptionParser.parse(args,
-      strict: [workers: :integer, stopwords_threshold: :float, progress: :boolean],
+      strict: [workers: :integer, stopwords_threshold: :float, progress: :boolean, ignore_paths: :string],
       aliases: [w: :workers]
     )
 
@@ -547,7 +558,8 @@ defmodule CodeQA.CLI do
       exit({:shutdown, 1})
     end
 
-    files = CodeQA.Collector.collect_files(path)
+    ignore_patterns = parse_ignore_paths(opts[:ignore_paths])
+    files = CodeQA.Collector.collect_files(path, ignore_patterns: ignore_patterns)
     if map_size(files) == 0 do
       IO.puts(:stderr, "Warning: no source files found in '#{path}'")
       exit({:shutdown, 1})
@@ -589,7 +601,8 @@ defmodule CodeQA.CLI do
         timeout: :integer, show_ncd: :boolean,
         ncd_top: :integer, ncd_paths: :string,
         combinations: :boolean, telemetry: :boolean,
-        experimental_stopwords: :boolean, stopwords_threshold: :float
+        experimental_stopwords: :boolean, stopwords_threshold: :float,
+        ignore_paths: :string
       ],
       aliases: [o: :output, w: :workers, t: :timeout]
     )
@@ -601,7 +614,8 @@ defmodule CodeQA.CLI do
       exit({:shutdown, 1})
     end
 
-    files = CodeQA.Collector.collect_files(path)
+    ignore_patterns = parse_ignore_paths(opts[:ignore_paths])
+    files = CodeQA.Collector.collect_files(path, ignore_patterns: ignore_patterns)
     if map_size(files) == 0 do
       IO.puts(:stderr, "Warning: no source files found in '#{path}'")
       exit({:shutdown, 1})
@@ -680,6 +694,13 @@ defmodule CodeQA.CLI do
   # credo:disable-for-next-line Credo.Check.Warning.OperationOnSameValues
   defp nan?(x), do: x != x
 
+  defp parse_ignore_paths(nil), do: []
+  defp parse_ignore_paths(paths_string) do
+    paths_string
+    |> String.split(",", trim: true)
+    |> Enum.map(&String.trim/1)
+  end
+
   defp print_usage do
     IO.puts("""
     Usage: codeqa <command> [options]
@@ -704,6 +725,7 @@ defmodule CodeQA.CLI do
       --ncd-paths PATHS     Comma-separated list of paths to compute NCD for
       --show-files          Include individual file metrics in the output
       --show-file-paths P   Comma-separated list of paths to include in the output
+      --ignore-paths PATHS  Comma-separated list of path patterns to ignore (supports wildcards, e.g. "test/*,docs/*")
 
     Options for compare:
       --base-ref REF        Base git ref to compare from (required)
@@ -722,6 +744,7 @@ defmodule CodeQA.CLI do
       --ncd-paths PATHS     Comma-separated list of paths to compute NCD for
       --show-files          Include individual file metrics in the output
       --show-file-paths P   Comma-separated list of paths to include in the output
+      --ignore-paths PATHS  Comma-separated list of path patterns to ignore (supports wildcards, e.g. "test/*,docs/*")
 
     Options for history:
       -n, --commits N       Number of recent commits to analyze
@@ -737,6 +760,7 @@ defmodule CodeQA.CLI do
       --ncd-paths PATHS     Comma-separated list of paths to compute NCD for
       --show-files          Include individual file metrics in the output
       --show-file-paths P   Comma-separated list of paths to include in the output
+      --ignore-paths PATHS  Comma-separated list of path patterns to ignore (supports wildcards, e.g. "test/*,docs/*")
 
     Options for correlate:
       -t, --top N           Number of top correlations to show (default: 20)
@@ -757,6 +781,7 @@ defmodule CodeQA.CLI do
       --cache               Enable caching file metrics
       --cache-dir DIR       Directory to store cache (default: .codeqa_cache)
       -t, --timeout MS      Timeout for similarity analysis (default: 5000)
+      --ignore-paths PATHS  Comma-separated list of path patterns to ignore (supports wildcards, e.g. "test/*,docs/*")
     """)
   end
 end

lib/codeqa/collector.ex

@@ -13,9 +13,10 @@ defmodule CodeQA.Collector do
     .next coverage
   ])
 
-  @spec collect_files(String.t()) :: %{String.t() => String.t()}
-  def collect_files(root) do
+  @spec collect_files(String.t(), keyword()) :: %{String.t() => String.t()}
+  def collect_files(root, opts \\ []) do
     root_path = Path.expand(root)
+    ignore_patterns = Keyword.get(opts, :ignore_patterns, [])
 
     unless File.dir?(root_path) do
       raise File.Error, reason: :enoent, path: root, action: "find directory"
@@ -27,10 +28,49 @@ defmodule CodeQA.Collector do
       rel = Path.relative_to(path, root_path)
       {rel, File.read!(path)}
     end)
+    |> reject_ignored_map(ignore_patterns)
   end
 
   def source_extensions, do: @source_extensions
 
+  @doc false
+  def ignored?(path, patterns) do
+    Enum.any?(patterns, fn pattern ->
+      match_pattern?(path, pattern)
+    end)
+  end
+
+  @doc false
+  def reject_ignored_map(files_map, []), do: files_map
+  def reject_ignored_map(files_map, patterns) do
+    Map.reject(files_map, fn {path, _} -> ignored?(path, patterns) end)
+  end
+
+  @doc false
+  def reject_ignored(list, [], _key_fn), do: list
+  def reject_ignored(list, patterns, key_fn) do
+    Enum.reject(list, fn item -> ignored?(key_fn.(item), patterns) end)
+  end
+
+  defp match_pattern?(path, pattern) do
+    # Convert glob pattern to regex:
+    # - ** matches any number of directories
+    # - * matches anything except /
+    # - ? matches a single character except /
+    regex_str =
+      pattern
+      |> String.replace(".", "\\.")
+      |> String.replace("**", "\0GLOBSTAR\0")
+      |> String.replace("*", "[^/]*")
+      |> String.replace("?", "[^/]")
+      |> String.replace("\0GLOBSTAR\0", ".*")
+
+    case Regex.compile("^#{regex_str}$") do
+      {:ok, regex} -> Regex.match?(regex, path)
+      _ -> false
+    end
+  end
+
   defp walk_directory(dir) do
     dir
     |> File.ls!()

scripts/run.sh

@@ -70,6 +70,25 @@ case "$INPUT_COMMAND" in
     ;;
 esac
 
+# Parse ignore-paths YAML list into --ignore-paths flag
+if [[ -n "$INPUT_IGNORE_PATHS" ]]; then
+  IGNORE_CSV=""
+  while IFS= read -r line; do
+    # Strip YAML list prefix "- " and surrounding whitespace
+    pattern=$(echo "$line" | sed 's/^[[:space:]]*-[[:space:]]*//' | sed 's/[[:space:]]*$//')
+    if [[ -n "$pattern" ]]; then
+      if [[ -n "$IGNORE_CSV" ]]; then
+        IGNORE_CSV="${IGNORE_CSV},${pattern}"
+      else
+        IGNORE_CSV="$pattern"
+      fi
+    fi
+  done <<< "$INPUT_IGNORE_PATHS"
+  if [[ -n "$IGNORE_CSV" ]]; then
+    ARGS+=("--ignore-paths" "$IGNORE_CSV")
+  fi
+fi
+
 # Append extra args (word-split intentionally)
 if [[ -n "$INPUT_EXTRA_ARGS" ]]; then
   # shellcheck disable=SC2206