Output Formats

Output Formats

Arxo supports multiple output formats for different use cases.

Console (Default)

Human-readable terminal output with colors and formatting.

arxo analyze

Output:

🔍 Analyzing project...
✓ Parsed 247 files
✓ Built import graph (183 nodes, 412 edges)
✓ Computed 8 metrics

📊 Results:

┌─────────────────────┬─────────┬──────────┐
│ Metric              │ Value   │ Status   │
├─────────────────────┼─────────┼──────────┤
│ scc.component_count           │ 183     │ ✓ Good   │
│ scc.max_cycle_size        │ 0       │ ✓ Good   │
│ propagation_cost.system.ratio           │ 0.12    │ ✓ Good   │
│ modularity.module.best_q  │ 0.42    │ ✓ Good   │
└─────────────────────┴─────────┴──────────┘

✅ No policy violations

Features

• Color-coded status (green/yellow/red)
• Progress indicators
• Summary tables
• Violation details with file locations

Quiet Mode

Suppress progress output:

arxo analyze --quiet

---

JSON

Machine-readable format for CI/CD and tooling integration.

arxo analyze --format json --output report.json

Structure

{
  "version": "0.1.0",
  "timestamp": "2024-01-15T10:30:00Z",
  "project_path": "/path/to/project",
  "config": {
    "metrics": ["scc", "propagation_cost"],
    "policy": { "invariants": [...] }
  },
  "results": [
    {
      "id": "scc",
      "name": "Strongly Connected Components",
      "category": "structural",
      "values": {
        "scc.component_count": 183,
        "scc.max_cycle_size": 0,
        "scc.total_nodes_in_cycles": 0
      },
      "evidence": [],
      "status": "good"
    }
  ],
  "violations": [],
  "graphs": {
    "import_graph": {
      "nodes": [...],
      "edges": [...]
    }
  },
  "timing": {
    "total_ms": 2450,
    "stages": {
      "parsing": 1200,
      "graph_building": 800,
      "metrics": 450
    }
  }
}

Key Fields

Field	Description
results	Array of metric results with values
violations	Policy violations with file locations
graphs	Graph data (nodes, edges)
evidence	Specific findings with context
timing	Performance breakdown

Usage Examples

Extract specific metric:

jq '.results[] | select(.id=="scc")' report.json

Count violations:

jq '.violations | length' report.json

Get all SCC values:

jq '.results[] | select(.id=="scc") | .values' report.json

---

HTML

Interactive web report with visualizations and drill-down capabilities.

arxo analyze --format html --output report.html

Features

• Interactive tables - Sort, filter, search
• Graph visualizations - Visual dependency graphs
• Drill-down details - Click metrics for evidence
• Responsive design - Works on mobile
• Self-contained - Single HTML file, no dependencies

Sections

1. Executive Summary - High-level metrics and status
2. Metric Details - Each metric with values and trends
3. Policy Violations - Detailed violation list with locations
4. Graph Visualizations - Interactive dependency graphs
5. Evidence - Specific findings with code context

Opening Reports

# Generate report
arxo analyze --format html --output report.html

# Open in browser
open report.html       # macOS
xdg-open report.html  # Linux
start report.html     # Windows

---

YAML (Snapshot)

Human-readable format for baseline comparisons and version control.

arxo analyze --format snapshot --output baseline.yaml

Structure

version: 0.1.0
timestamp: 2024-01-15T10:30:00Z
project_path: /path/to/project

results:
  - id: scc
    name: Strongly Connected Components
    category: structural
    values:
      scc.component_count: 183
      scc.max_cycle_size: 0
      scc.total_nodes_in_cycles: 0
    status: good

violations: []

graphs:
  import_graph:
    node_count: 183
    edge_count: 412

Use Cases

• Baseline tracking - Commit to git
• Diff comparison - Track changes over time
• Documentation - Readable metric snapshots

Example Workflow

# Create baseline
arxo analyze --format snapshot --output baseline.yaml
git add baseline.yaml
git commit -m "Add architecture baseline"

# Compare later
arxo analyze --baseline baseline.yaml

---

SARIF

Static Analysis Results Interchange Format for code scanning tools.

arxo analyze --format sarif --output results.sarif

Integration

GitHub Code Scanning:

.github/workflows/architecture.yml

- name: Run Arxo
  run: arxo analyze --format sarif --output results.sarif

- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v2
  with:
    sarif_file: results.sarif

GitLab SAST:

.gitlab-ci.yml

architecture:
  script:
    - arxo analyze --format sarif --output gl-sast-report.json
  artifacts:
    reports:
      sast: gl-sast-report.json

Structure

{
  "$schema": "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json",
  "version": "2.1.0",
  "runs": [
    {
      "tool": {
        "driver": {
          "name": "arxo",
          "version": "0.1.0"
        }
      },
      "results": [
        {
          "ruleId": "arxo/scc-max-size",
          "level": "error",
          "message": {
            "text": "Circular dependency detected (max size: 5)"
          },
          "locations": [
            {
              "physicalLocation": {
                "artifactLocation": {
                  "uri": "src/example.ts"
                },
                "region": {
                  "startLine": 1
                }
              }
            }
          ]
        }
      ]
    }
  ]
}

---

MessagePack

Efficient binary format for data processing and storage.

arxo analyze --format msgpack --output report.mpk

Use Cases

• Large projects - Smaller file size
• Data pipelines - Fast serialization
• Streaming - Efficient processing

Reading MessagePack

Python:

import msgpack

with open('report.mpk', 'rb') as f:
    data = msgpack.unpack(f)
    print(data['results'])

Rust:

use rmp_serde::decode;
use std::fs::File;

let file = File::open("report.mpk")?;
let report: Report = decode::from_read(file)?;

---

Comparison Table

Format	Size	Speed	Human-Readable	Machine-Readable	Use Case
Console	N/A	Fast	✅ Yes	❌ No	Development
JSON	Medium	Fast	⚠️ Partial	✅ Yes	CI/CD, APIs
HTML	Large	Medium	✅ Yes	❌ No	Reports, sharing
YAML	Medium	Fast	✅ Yes	✅ Yes	Baselines, docs
SARIF	Medium	Fast	⚠️ Partial	✅ Yes	Code scanning
MessagePack	Small	Very Fast	❌ No	✅ Yes	Data processing

---

Output Location

Default (stdout)

arxo analyze --format json  # Prints to terminal

File Output

arxo analyze --format json --output report.json

Multiple Formats

Generate multiple formats in one run:

#!/bin/bash

# JSON for CI
arxo analyze --format json --output report.json

# HTML for humans
arxo analyze --format html --output report.html

# YAML for baseline
arxo analyze --format snapshot --output baseline.yaml

---

Custom Processing

Extract Specific Data

Get all metric values:

arxo analyze --format json --quiet | \
  jq '.results[] | {id: .id, values: .values}'

Get violation locations:

arxo analyze --format json --quiet | \
  jq '.violations[] | {metric: .metric, file: .location.file}'

Count files by language:

arxo analyze --format json --quiet | \
  jq '.graphs.import_graph.nodes | group_by(.language) | map({language: .[0].language, count: length})'

Convert Formats

JSON to CSV:

arxo analyze --format json --quiet | \
  jq -r '.results[] | [.id, .values | to_entries[] | .value] | @csv' > metrics.csv

JSON to Markdown:

arxo analyze --format json --quiet | \
  jq -r '.results[] | "## \(.name)\n\n\(.values | to_entries[] | "- **\(.key)**: \(.value)")\n"' > report.md

---

Next Steps

• CLI Reference - Command options
• CI Integration - Use in pipelines
• Configuration Guide - Configure output