evaluate_policy

evaluate_policy

Evaluate architectural policies defined in your arxo.yaml configuration (or provided inline) and return any violations. This tool enables architecture governance by checking if current metrics meet your defined standards.

Tip

Use this in CI pipelines to fail builds when architectural invariants are violated (e.g., cycle count > 0, propagation cost > 10%).

Parameters

Parameter	Type	Required	Description
project_path	string	Yes	Absolute or relative path to the project root directory
policy_yaml	string	No	Inline policy YAML content (optional — uses arxo.yaml if not provided)

Response

Returns a JSON summary with policy violations and current metric values.

Response Schema

{
  "violations": [
    {
      "metric": "string",          // Metric key (e.g., "scc.max_cycle_size")
      "expected": "number",         // Expected numeric threshold
      "actual": "number",           // Actual value from analysis
      "operator": "string"          // Comparison operator
    }
  ],
  "violations_count": "number",
  "metrics_summary": [              // Current metric payloads from analysis
    {
      "id": "string",
      "data": [ { "key": "string", "value": { "kind": "number", "v": 0.0 } } ]
    }
  ]
}

Policy YAML Format

Define policies in arxo.yaml:

policy:
  invariants:
    - metric: scc.max_cycle_size
      op: '<='
      value: 0
      message: 'No circular dependencies allowed'
    - metric: propagation_cost.system.ratio
      op: '<='
      value: 0.10
      message: 'System propagation cost must stay under 10%'
    - metric: smells.hubs.count
      op: '=='
      value: 0
      message: 'No hub modules allowed'

Supported Operators

Operator	Description
==	Equal to
!=	Not equal to
<	Less than
<=	Less than or equal to
>	Greater than
>=	Greater than or equal to

Examples

No violations (passing policy)

Request:

{
  "project_path": "."
}

Response:

{
  "violations": [],
  "violations_count": 0,
  "metrics_summary": [
    {
      "id": "scc",
      "data": [
        { "key": "scc.max_cycle_size", "value": { "kind": "number", "v": 0 } },
        { "key": "scc.cycle_count", "value": { "kind": "number", "v": 0 } }
      ]
    },
    {
      "id": "smells",
      "data": [
        { "key": "smells.hubs.count", "value": { "kind": "number", "v": 0 } },
        { "key": "smells.god_components.count", "value": { "kind": "number", "v": 0 } }
      ]
    }
  ]
}

Violations detected

Request:

{
  "project_path": "/path/to/project"
}

Response:

{
  "violations": [
    {
      "metric": "scc.max_cycle_size",
      "expected": 0,
      "actual": 5,
      "operator": "<="
    },
    {
      "metric": "propagation_cost.system.ratio",
      "expected": 0.10,
      "actual": 0.23,
      "operator": "<="
    }
  ],
  "violations_count": 2,
  "metrics_summary": [
    {
      "id": "scc",
      "data": [
        { "key": "scc.max_cycle_size", "value": { "kind": "number", "v": 5 } },
        { "key": "scc.cycle_count", "value": { "kind": "number", "v": 2 } }
      ]
    },
    {
      "id": "propagation_cost",
      "data": [
        { "key": "propagation_cost.system.ratio", "value": { "kind": "number", "v": 0.23 } }
      ]
    }
  ]
}

Inline policy (no config file)

Request:

{
  "project_path": ".",
  "policy_yaml": "policy:\n  invariants:\n    - metric: scc.max_cycle_size\n      op: '<='\n      value: 0\n      message: 'No cycles allowed'\n    - metric: centrality.module.betweenness_max\n      op: '<'\n      value: 0.5\n      message: 'No modules with betweenness >= 0.5'"
}

Response:

{
  "violations": [
    {
      "metric": "centrality.module.betweenness_max",
      "expected": 0.5,
      "actual": 0.62,
      "operator": "<"
    }
  ],
  "violations_count": 1,
  "metrics_summary": [
    {
      "id": "scc",
      "data": [
        { "key": "scc.max_cycle_size", "value": { "kind": "number", "v": 0 } }
      ]
    },
    {
      "id": "centrality",
      "data": [
        { "key": "centrality.module.betweenness_max", "value": { "kind": "number", "v": 0.62 } }
      ]
    }
  ]
}

Common Policies

Zero circular dependencies

policy:
  invariants:
    - metric: scc.max_cycle_size
      op: '<='
      value: 0
      message: 'No circular dependencies allowed'

Propagation cost ceiling

policy:
  invariants:
    - metric: propagation_cost.system.ratio
      op: '<='
      value: 0.15
      message: 'System propagation cost must not exceed 15%'

No architectural smells

policy:
  invariants:
    - metric: smells.hubs.count
      op: '=='
      value: 0
      message: 'No hub modules allowed'
    - metric: smells.god_components.count
      op: '=='
      value: 0
      message: 'No god classes allowed'

Layer violation enforcement

policy:
  invariants:
    - metric: layer_violations.violations_count
      op: '=='
      value: 0
      message: 'No layer violations allowed'

Security policy

policy:
  invariants:
    - metric: sensitive_data_flow.pii_leaks
      op: '=='
      value: 0
      message: 'No PII leakage to external services'
    - metric: security.high_severity_cves
      op: '=='
      value: 0
      message: 'No high-severity CVEs in dependencies'

Workflow

Use this tool in a CI/CD pipeline:

1. evaluate_policy → check for violations
2. If violations_count > 0:
   a. Fail the build
   b. Comment on PR with violations
   c. Link to get_hotspots or suggest_refactors for guidance
3. Else: proceed with merge

See Workflows: Policy enforcement for a full example.

Error Cases

Error	Cause	Solution
missing required parameter: project_path	project_path not provided	Include project_path in request
Failed to parse policy YAML	Invalid YAML syntax	Check YAML formatting (indentation, quotes)
Unknown metric: xyz	Policy references non-existent metric	Use list_presets to see available metrics
Invalid operator: xyz	Policy uses unsupported operator	Use ==, !=, <, <=, >, >=

Performance

• Speed: 5-15 seconds (uses ci preset internally)
• Caching: Does not use cache (always fresh evaluation)
• Preset used: ci preset (includes scc, smells, layer_violations, architecture_budgeting)

Note

The tool currently uses the ci preset. If your policy references metrics outside this preset, consider using analyze_architecture with a custom preset instead.

Best Practices

Start with lenient policies

Begin with loose thresholds and tighten over time:

# Phase 1: Establish baseline
policy:
  invariants:
    - metric: scc.max_cycle_size
      op: '<='
      value: 10  # Allow some cycles initially
      message: 'Reduce cycle size'

# Phase 2: Tighten after refactoring
policy:
  invariants:
    - metric: scc.max_cycle_size
      op: '<='
      value: 3
      message: 'Cycles must be small'

# Phase 3: Enforce zero cycles
policy:
  invariants:
    - metric: scc.max_cycle_size
      op: '<='
      value: 0
      message: 'No cycles allowed'

Use clear, actionable messages

Good:

message: 'Circular dependency detected. Run `arxo cycles` to identify modules.'

Bad:

message: 'Policy violation'

Combine with architectural budgets

Use architecture_budgeting for incremental improvement:

policy:
  invariants:
    - metric: architecture_budgeting.violations
      op: '=='
      value: 0
      message: 'Architecture budget exceeded'

Related Tools

• analyze_architecture — Run full analysis with policies in config
• get_hotspots — Find modules causing violations
• check_cycles — Fast cycle check for SCC policies

Related Resources

• policy://violations/<path> — Read cached policy violations

Related Guides

• Policy Examples — Sample policies for common scenarios
• CI Integration — Using policies in CI/CD

CLI Equivalent

# Evaluate policy from arxo.yaml
arxo analyze --preset ci

# Check if violations exist (exit code non-zero if violations)
arxo analyze --preset ci --fail-on-violations