Output Formats

symtrace v0.5.0 features a multi-format output engine (src/output.rs) that formats AST-based structural diff results for terminal interaction, LLM prompt generation, automated CI/CD pipelines, security scanning tools, and executive reporting.

Format Overview & Quick Matrix

The output format is selected via the --format <FMT> command-line flag or dedicated mode flags:

Format / Flag	CLI Option	Primary Use Case & Characteristics
ANSI Terminal	--format ansi (default)	High-contrast colored terminal output with adaptive granularity and $PAGER routing
Micro-Compact	--compact	Ultra-dense 1–3 line inline token changes (+85.9% Noise Suppression Ratio)
LLM Context Prompt	--format prompt	Ultra-dense context prompt for AI assistants (Gemini, Claude, GPT), saving ~80% tokens
JSON	--format json	Structured camelCase JSON detailing AST node identity, blast radius, and contracts
JSON Lines	--format jsonl	Streaming line-delimited JSON for large repo log pipelines
Markdown	--format markdown	GFM formatted report optimized for GitHub PR & GitLab MR comments
White-Mode HTML	--format html	Standalone interactive report (symtrace_report.html) with PDF print support
SARIF v2.1.0	--format sarif	Standardized security output for GitHub Code Scanning & CodeQL
Stat Summary	--stat (-s)	Tabular file-level summary of AST operation counts and impact
CI Guard	--check	Silent exit code mode (0 = clean, 1 = structural changes / violations)
Name-Only	--name-only	List of modified relative file paths, ignoring formatting-only edits

1. ANSI Terminal Output (--format ansi)

The default interactive format (--format ansi) formats AST operations with ANSI color codes, unicode status indicators, and adaptive granularity. Output is automatically piped to the system terminal pager ($PAGER, e.g., less -RFX) when running in an interactive TTY session.

Terminal Operation Symbol Cheatsheet

Symbol	Operation	Description
+ [INSERT]	Insertion	A new function, class, struct, or AST node was added
~ [MODIFY]	Modification	Internal logic of an existing code construct was altered
✎ [RENAME]	Rename	Identifier or symbol renamed across scope (e.g. process -> execute)
- [DELETE]	Deletion	An existing function, class, or code block was removed
↔ [MOVE]	Movement	A code construct moved within a file or across files without logic edits

Sample Standard Output

━━━ symtrace Semantic Diff ━━━
Repository: symtrace | Comparing: HEAD~1 → HEAD

━━━ src/handler.rs
  + [INSERT] function_item 'handle_request' inserted (L42)
  ~ [MODIFY] function_item 'parse_body' modified (L10 → L10) [75% similarity, medium]
  ✎ [RENAME] function_item renamed from 'process' to 'execute' (L5 → L5) [98% similarity, low]
  - [DELETE] function_item 'deprecated_fn' deleted (L88)
  ↔ [MOVE]   function_item 'helper' moved (L20 → L35) [100% similarity, low]

  ── Refactor Patterns ──
    ▸ 'process' renamed to 'execute' (confidence: 100%)

━━━ Summary ━━━
  Files: 1 | Moves: 1 | Renames: 1 | Inserts: 1 | Deletes: 1 | Modifies: 1

━━━ Downstream Blast Radius ━━━
  Target: fn parse_body (src/handler.rs) | Total Callers Impacted: 2 [Severity: MEDIUM]
    ▸ Depth 1: fn handle_request (src/handler.rs:L42)
    ▸ Depth 2: fn main (src/main.rs:L15)

2. Micro-Compact Mode (--compact)

Forces the high-signal, micro-compact inline token diff renderer. Ideal for small configuration changes, single-token adjustments, and micro-commits:

symtrace --compact

~ src/server.rs:L42  [MODIFY] port: 8080 -> 3000 (95%)
✎ src/models.rs:L12  [RENAME] user_id -> account_id (98%)

3. LLM Context Prompt Format (--format prompt)

Generates ultra-dense, token-optimized context representations designed specifically for AI coding assistants (Gemini, Claude, GPT). It encodes semantic structural changes, contract alerts, parameter deltas, and blast radius impact while reducing token usage by ~80% compared to standard unified diffs.

symtrace . HEAD~1 HEAD --format prompt

Sample Output

=== symtrace SEMANTIC CONTEXT ===
Repository: my-repo | Commits: HEAD~1 -> HEAD
Classification: refactor (confidence: 90%) | Intents: [EXTRACT_METHOD, TYPE_MIGRATION]
Summary: 2 files (+1 -1 ~2 ↔1 ✎1)

--- CRITICAL CONTRACT & SAFETY ALERTS ---
! [STRIPPED_LOCK_GUARD] src/state.rs:L88: Concurrency guard 'mutex.lock()' was removed, potential race condition

--- STRUCTURAL MODIFICATIONS ---
[MODIFIED] fn parse_config (src/config.rs at L10)
  ~ Control flow altered
[RENAMED] variable 'timeout' renamed to 'connection_timeout' (src/config.rs at L12)
[MOVED] struct ConfigPayload moved (src/types.rs -> src/config.rs at L4)
  * Refactor: Extract Method 'validate_keys' from 'parse_config' (confidence: 95%)

--- DOWNSTREAM BLAST RADIUS ---
* Modified 'parse_config' impacts 3 callers (Severity: MEDIUM):
  - fn init_server (src/server.rs:L24, depth 1)
  - fn main (src/main.rs:L10, depth 2)

4. JSON Output (--format json)

Generates a complete machine-readable JSON object with camelCase keys detailing file changes, AST node operations, BLAKE3 fingerprints, safety contracts, and call graph blast radius.

Sample JSON Structure

{
  "version": "0.5.0",
  "repository": "symtrace",
  "commitA": "HEAD~1",
  "commitB": "HEAD",
  "displayGranularity": "Standard",
  "summary": {
    "totalFiles": 1,
    "moves": 1,
    "renames": 1,
    "inserts": 1,
    "deletes": 1,
    "modifications": 1
  },
  "classification": {
    "primaryClass": "refactor",
    "confidenceScore": 0.85,
    "intentLabels": ["RENAME_IDENTIFIER", "EXTRACT_METHOD"]
  },
  "files": [
    {
      "filePath": "src/handler.rs",
      "oldPath": "src/handler.rs",
      "operations": [
        {
          "opType": "Move",
          "entityType": "Function",
          "oldLocation": "L20",
          "newLocation": "L35",
          "details": "function_item 'helper' moved",
          "similarity": {
            "similarityPercent": 100.0,
            "changeIntensity": "low",
            "structureSimilarity": 1.0,
            "tokenSimilarity": 1.0,
            "controlFlowChanged": false
          },
          "isLogicOp": true
        }
      ],
      "refactorPatterns": [
        {
          "patternType": "ExtractMethod",
          "description": "function 'helper' extracted",
          "confidence": 0.95
        }
      ]
    }
  ],
  "contractViolations": [],
  "blastRadius": [
    {
      "modifiedSymbol": "parse_body",
      "filePath": "src/handler.rs",
      "totalImpactedCallers": 2,
      "severity": "MEDIUM",
      "impactedCallers": [
        {
          "callerSymbol": "handle_request",
          "callerFile": "src/handler.rs",
          "callSiteLine": 42,
          "depth": 1
        }
      ]
    }
  ]
}

5. JSON Lines Output (--format jsonl)

Outputs streaming line-delimited JSON objects for high-throughput log ingestion pipelines (Elasticsearch, Datadog) and large-scale changeset indexing.

{"event":"file_start","path":"src/handler.rs","commitOld":"HEAD~1","commitNew":"HEAD"}
{"event":"operation","type":"MOVE","node":"function_item","name":"helper","fromLine":20,"toLine":35,"similarity":1.0}
{"event":"operation","type":"RENAME","node":"function_item","from":"process","to":"execute","similarity":0.98}
{"event":"file_end","path":"src/handler.rs","opsCount":2}

6. Markdown Report Format (--format markdown)

Generates structured GitHub-Flavored Markdown (GFM) reports ready for Pull Request descriptions, GitLab MR summaries, or automated CI bots.

### 🔍 symtrace Semantic PR Breakdown

**Refactor Patterns Detected:**
- ✂️ **Extract Method:** `validate_token()` extracted from `authenticate_user()` (`src/auth.rs:L42`)
- ↔️ **Cross-File Move:** `UserPayload` struct moved from `types.rs` -> `models/user.rs`

| File | Operation | Entity | Location | Similarity |
| :--- | :--- | :--- | :--- | :--- |
| `src/handler.rs` | `[MOVE]` | `function_item` | L20 -> L35 | 100% |
| `src/handler.rs` | `[RENAME]` | `function_item` | L5 -> L5 | 98% |

**0 contract violations detected. Formatting & comment noise suppressed.**

7. White-Mode HTML & PDF Export (--format html)

Generates a standalone, self-contained HTML document (symtrace_report.html) styled in a clean, professional “White-Mode” printable layout.

Features

• Print / Save PDF Button: Header action triggering the browser’s native PDF print generator.
• Collapsible File Panels: Expandable card interface with search and operation filter toggles.
• Cryptographic Audit Seal: Includes BLAKE3 checksum seal verifying the report’s audit provenance.

# Export HTML report to a file
symtrace HEAD~1 HEAD --format html > symtrace_report.html

8. SARIF Security Output (--format sarif)

Produces OASIS-compliant Static Analysis Results Interchange Format (SARIF v2.1.0) JSON for GitHub Code Scanning, GitLab Security Dashboards, and Azure DevOps security alerts.

{
  "$schema": "https://json.schemastore.org/sarif-2.1.0.json",
  "version": "2.1.0",
  "runs": [
    {
      "tool": {
        "driver": {
          "name": "symtrace",
          "semanticVersion": "0.5.0",
          "informationUri": "https://github.com/symtrace/symtrace"
        }
      },
      "results": [
        {
          "ruleId": "SYM-CONTRACT-NULL-01",
          "level": "error",
          "message": {
            "text": "Safety guard 'ptr != null' was removed, potential null-pointer dereference"
          },
          "locations": [
            {
              "physicalLocation": {
                "artifactLocation": {
                  "uri": "src/driver.c"
                },
                "region": {
                  "startLine": 12
                }
              }
            }
          ]
        }
      ]
    }
  ]
}

9. Stat Summary Mode (--stat / -s)

Outputs a high-level tabular breakdown of changed files, AST operation totals, and status:

symtrace . HEAD --stat

━━━ symtrace Diff Stat ━━━
File Path                                          | Operations   | Status
---------------------------------------------------+--------------+-----------
src/handler.rs                                     | 5            | Modified
src/auth.rs                                        | 2            | Modified
---------------------------------------------------+--------------+-----------
Total: 2 files changed (1 moves, 1 renames, 1 inserts, 1 deletes, 4 modifies)

10. CI Guard Mode (--check)

Executes silently and returns a deterministic process exit status for use in Git pre-commit hooks and CI/CD validation scripts:

# Run CI check
symtrace . HEAD --check
echo $?

• Exit Code 0: No non-trivial AST semantic changes occurred (or only whitespace/formatting tweaks were made).
• Exit Code 1: One or more structural AST modifications, inserts, deletes, renames, or contract violations were detected.

11. Name-Only Mode (--name-only)

Outputs a clean list of modified relative file paths, ignoring files that contain only formatting or comment adjustments:

symtrace . HEAD --name-only

src/handler.rs
src/auth.rs