feat(engine): near-duplicate-blocks engine and layered architecture

.codeqa.yml

@@ -4,4 +4,32 @@
 # Patterns here are merged with any --ignore-paths passed on the command line.
 
 ignore_paths:
-  - priv/combined_metrics/samples/**
+  - priv/**
+  - tools/**
+  - scripts/**
+  - docs/**
+  - plans/**
+  - test/**
+  - devenv*
+  - direnv*
+  - README.md
+  - action.yml
+
+# Impact weights for overall score calculation.
+# Combined metric categories default to 1 (can be overridden here).
+impact:
+  complexity: 5
+  file_structure: 4
+  function_design: 4
+  code_smells: 3
+  naming_conventions: 2
+  error_handling: 2
+  consistency: 2
+  documentation: 1
+  testing: 1
+  # combined categories override example:
+  # variable_naming: 2
+
+combined_top: 5 # worst offender files per combined-metric behavior
+
+cosine_significance_threshold: 0.25 # threshold for cosine similarity calculation in behavior categories

.dialyzer_ignore.exs

@@ -0,0 +1,14 @@
+[
+  # Dialyzer specializes analyze/2 for the codebase call-site where include_pairs
+  # is always true, making the false branch appear unreachable. Both branches are
+  # valid and reachable at runtime from the file-level and codebase callers.
+  {"lib/codeqa/metrics/file/near_duplicate_blocks.ex", :pattern_match},
+  # Mix module type information is not available in the PLT; these are valid
+  # Mix.Task callbacks and standard Mix module calls.
+  {"lib/mix/tasks/codeqa/sample_report.ex", :callback_info_missing},
+  {"lib/mix/tasks/codeqa/signal_debug.ex", :callback_info_missing},
+  {"lib/mix/tasks/codeqa/sample_report.ex", :unknown_function},
+  {"lib/mix/tasks/codeqa/signal_debug.ex", :unknown_function},
+  # CodeQA.Engine.Registry.t/0 is defined via a macro; type is available at runtime.
+  {"lib/codeqa/analysis/file_metrics_server.ex", :unknown_type}
+]

.github/workflows/bootstrap-labels.yml

@@ -10,7 +10,7 @@ jobs:
   bootstrap:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Bootstrap labels
         uses: actions/github-script@v7

.github/workflows/compare.yml

@@ -12,10 +12,19 @@ jobs:
   compare:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0
 
+      - name: Cache Mix deps and build
+        uses: actions/cache@v4
+        with:
+          path: |
+            deps
+            _build
+          key: ${{ runner.os }}-mix-1.19-27.3-${{ hashFiles('mix.lock', 'mix.exs') }}
+          restore-keys: ${{ runner.os }}-mix-1.19-27.3-
+
       - name: Get fork point
         id: fork-point
         run: |

.github/workflows/dialyzer.yml

@@ -25,7 +25,7 @@ jobs:
 
     steps:
       - name: Checkout PR
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Set up Elixir
         uses: erlef/setup-beam@v1
@@ -45,9 +45,9 @@ jobs:
         uses: actions/cache@v4
         with:
           path: _build
-          key: build-${{ env.ELIXIR_VERSION }}-${{ env.OTP_VERSION }}-${{ hashFiles('mix.lock') }}
+          key: build-${{ env.MIX_ENV }}-${{ env.ELIXIR_VERSION }}-${{ env.OTP_VERSION }}-${{ hashFiles('mix.lock') }}
           restore-keys: |
-            build-${{ env.ELIXIR_VERSION }}-${{ env.OTP_VERSION }}-
+            build-${{ env.MIX_ENV }}-${{ env.ELIXIR_VERSION }}-${{ env.OTP_VERSION }}-
 
       - name: Cache PLT
         uses: actions/cache@v4

.github/workflows/health-report.yml

@@ -12,7 +12,17 @@ jobs:
   health-report:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
+
+      - name: Cache Mix deps and build
+        uses: actions/cache@v4
+        with:
+          path: |
+            deps
+            _build
+          key: ${{ runner.os }}-mix-1.19-27.3-${{ hashFiles('mix.lock', 'mix.exs') }}
+          restore-keys: ${{ runner.os }}-mix-1.19-27.3-
+
       - uses: ./
         with:
           command: health-report

.github/workflows/release.yml

@@ -17,15 +17,33 @@ jobs:
   build:
     runs-on: ubuntu-latest
 
+    env:
+      ELIXIR_VERSION: "1.19"
+      OTP_VERSION: "27.3"
+
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Set up Elixir
         uses: erlef/setup-beam@v1
         with:
-          otp-version: "27.3"
-          elixir-version: "1.19"
+          otp-version: ${{ env.OTP_VERSION }}
+          elixir-version: ${{ env.ELIXIR_VERSION }}
+
+      - name: Cache deps
+        uses: actions/cache@v4
+        with:
+          path: deps
+          key: deps-${{ env.ELIXIR_VERSION }}-${{ env.OTP_VERSION }}-${{ hashFiles('mix.lock', 'mix.exs') }}
+          restore-keys: deps-${{ env.ELIXIR_VERSION }}-${{ env.OTP_VERSION }}-
+
+      - name: Cache build
+        uses: actions/cache@v4
+        with:
+          path: _build
+          key: build-${{ env.ELIXIR_VERSION }}-${{ env.OTP_VERSION }}-${{ hashFiles('mix.lock', 'mix.exs') }}
+          restore-keys: build-${{ env.ELIXIR_VERSION }}-${{ env.OTP_VERSION }}-
 
       - name: Build escript
         run: |

.github/workflows/sync-behavior-coverage.yml

@@ -0,0 +1,65 @@
+name: Sync Behavior Coverage
+
+on:
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: write
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    if: github.event.pull_request.head.repo.full_name == github.repository
+
+    steps:
+      - name: Checkout PR branch
+        uses: actions/checkout@v6
+        with:
+          ref: ${{ github.head_ref }}
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Set up Elixir
+        uses: erlef/setup-beam@v1
+        with:
+          otp-version: "27.3"
+          elixir-version: "1.19"
+
+      - name: Cache deps
+        uses: actions/cache@v4
+        with:
+          path: |
+            deps
+            _build
+          key: ${{ runner.os }}-mix-dev-otp27.3-elixir1.19-${{ hashFiles('mix.lock', 'mix.exs') }}
+          restore-keys: ${{ runner.os }}-mix-dev-otp27.3-elixir1.19-
+
+      - name: Install dependencies
+        run: mix deps.get
+
+      - name: Compile
+        run: mix compile --warnings-as-errors
+
+      - name: Regenerate language coverage
+        run: mix codeqa.sample_report --apply-languages
+
+      - name: Regenerate scalar vectors
+        run: mix codeqa.sample_report --apply-scalars
+
+      - name: Check for YAML drift
+        id: diff
+        run: |
+          if git diff --quiet priv/combined_metrics/; then
+            echo "changed=false" >> $GITHUB_OUTPUT
+          else
+            echo "changed=true" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Commit and push updated YAMLs
+        if: steps.diff.outputs.changed == 'true'
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add priv/combined_metrics/*.yml
+          git commit -m "chore(combined-metrics): sync language coverage and scalar vectors [skip ci]"
+          git push

.github/workflows/test.yml

@@ -10,24 +10,27 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Set up Elixir
+        id: beam
         uses: erlef/setup-beam@v1
         with:
           otp-version: "27.3"
           elixir-version: "1.19"
 
       - name: Cache deps
+        id: mix-cache
         uses: actions/cache@v4
         with:
           path: |
             deps
             _build
-          key: ${{ runner.os }}-mix-${{ hashFiles('mix.lock') }}
-          restore-keys: ${{ runner.os }}-mix-
+          key: ${{ runner.os }}-mix-${{ steps.beam.outputs.otp-version }}-${{ steps.beam.outputs.elixir-version }}-${{ hashFiles('mix.lock', 'mix.exs') }}
+          restore-keys: ${{ runner.os }}-mix-${{ steps.beam.outputs.otp-version }}-${{ steps.beam.outputs.elixir-version }}-
 
       - name: Install dependencies
+        if: steps.mix-cache.outputs.cache-hit != 'true'
         run: mix deps.get
 
       - name: Compile

.github/workflows/validate-issue-links.yml

@@ -12,7 +12,7 @@ jobs:
   validate:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Validate issue template links
         run: |

.gitignore

@@ -18,3 +18,10 @@ devenv.lock
 
 # Git worktrees
 .worktrees/
+docs/plans/
+docs/superpowers/
+plans/
+scripts/*.exs
+
+# Claude Code
+.claude/

.pre-commit-config.yaml

@@ -0,0 +1,8 @@
+repos:
+- repo: local
+  hooks:
+  - id: mix-precommit
+    name: Mix precommit
+    entry: devenv shell precommit
+    language: system
+    pass_filenames: false