analyze_with_baseline

analyze_with_baseline

Compare current architecture metrics against a baseline git reference (e.g., main branch or a previous commit) to detect regressions and improvements.

Caution

Status: This tool is currently a placeholder and requires the full arxo binary with git worktree support. The MCP server cannot perform baseline comparisons.

Use the CLI instead: arxo analyze --baseline <ref>

Parameters

Parameter	Type	Required	Description
project_path	string	Yes	Absolute or relative path to the project root directory
baseline_ref	string	Yes	Git ref to use as baseline (e.g., main, HEAD~1, commit SHA)

Expected Response (when implemented)

{
  "diff": [
    {
      "metric": "string",
      "baseline": "number",
      "current": "number",
      "delta": "number"
    }
  ],
  "baseline_violations_count": "number",
  "current_violations_count": "number"
}

Interpreting Delta

• Positive delta — Metric increased (may be regression or improvement depending on metric)
• Negative delta — Metric decreased
• Zero delta — No change

Metric	Positive Delta	Negative Delta
scc.max_cycle_size	🚨 Regression (cycles grew)	✅ Improvement (cycles reduced)
propagation_cost.system.ratio	🚨 Regression (coupling increased)	✅ Improvement (coupling reduced)
centrality.module.betweenness_max	🚨 Regression (more centralized)	✅ Improvement (less centralized)
modularity.module.best_q	✅ Improvement (better separation)	🚨 Regression (worse separation)

Error Response (current behavior)

Request:

{
  "project_path": ".",
  "baseline_ref": "main"
}

Response:

ToolError: Baseline comparison requires full arxo (git checkout). Use arxo binary: arxo analyze --baseline <ref>

Why This Limitation Exists

The MCP server uses arxo-loader (engine-only library) which doesn’t include git operations. Baseline comparison requires:

1. Checking out the baseline ref in a git worktree
2. Running analysis on the baseline version
3. Running analysis on the current version
4. Computing the diff

These operations require filesystem manipulation and git commands not available in the MCP server.

Workaround: Use CLI

Compare against main branch

arxo analyze --baseline main --format json > baseline-comparison.json

Compare against previous commit

arxo analyze --baseline HEAD~1 --format json

Compare against specific commit

arxo analyze --baseline a3f7c8d --format json

CI workflow example

.github/workflows/architecture-check.yml

name: Architecture Check
on: [pull_request]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0  # Needed for baseline comparison

      - name: Install Arxo
        run: |
          curl -sL "https://github.com/arxohq/arxo/releases/latest/download/arxo-linux-x86_64.tar.gz" | tar xz
          chmod +x arxo && sudo mv arxo /usr/local/bin/

      - name: Compare against main
        run: |
          arxo analyze --baseline origin/main --format json > comparison.json

          # Fail if cycles increased
          DELTA=$(jq '.diff[] | select(.metric=="scc.max_cycle_size") | .delta' comparison.json)
          if [ "$DELTA" -gt 0 ]; then
            echo "Error: Circular dependencies increased!"
            exit 1
          fi

Expected Usage (when implemented)

Detect cycle regressions

{
  "project_path": ".",
  "baseline_ref": "main"
}

Expected response:

{
  "diff": [
    {
      "metric": "scc.max_cycle_size",
      "baseline": 3,
      "current": 5,
      "delta": 2
    },
    {
      "metric": "propagation_cost.system.ratio",
      "baseline": 0.08,
      "current": 0.07,
      "delta": -0.01
    }
  ],
  "baseline_violations_count": 1,
  "current_violations_count": 2
}

Interpretation:

• scc.max_cycle_size increased by 2 (regression — cycles grew)
• propagation_cost.system.ratio decreased by 0.01 (improvement — coupling reduced)
• Violations increased from 1 to 2

Compare performance across commits

{
  "project_path": ".",
  "baseline_ref": "v1.0.0"
}

Track architectural evolution between releases.

Workflow (when implemented)

Use in CI to prevent regressions:

1. analyze_with_baseline → compare current vs main
2. For each metric with positive delta (regression):
   a. Check if delta exceeds threshold
   b. If yes, fail the build
   c. Comment on PR with regression details
3. For metrics with negative delta (improvement):
   a. Comment on PR celebrating the improvement

Related Tools

• analyze_architecture — Run analysis on current state
• evaluate_policy — Check absolute thresholds (not deltas)

Related Guides

• CI Integration — Using arxo in CI/CD pipelines
• Baseline Analysis — In-depth guide (if exists)

Future Implementation

To implement this tool in the MCP server, we would need to:

1. Add git operations to arxo-loader or expose them via a separate interface
2. Create temporary worktrees for baseline analysis
3. Cache baseline results by git ref SHA
4. Compute metric deltas in the server

Alternatively, the tool could invoke the CLI binary as a subprocess, but this adds complexity and external dependencies.

CLI Equivalent (current solution)

# This is the only way to do baseline comparison currently
arxo analyze --baseline main --format json