Skip to content

Output Formats

axm-ast offers multiple output formats optimized for different consumers.

Detail Levels (describe)

Detailed (default)

Adds docstrings, parameter types, return types, and visibility indicators (🔓 public, 🔒 private). This is the default detail level.

axm-ast describe src/mylib

Summary

Quick orientation. Shows module names, public function signatures, and class names.

axm-ast describe src/mylib --detail summary

Full

Everything: imports, variables, private symbols, decorators. Useful for complete documentation generation.

axm-ast describe src/mylib --detail full

Compressed

AI-optimized format designed to fit large codebases into LLM context windows.

axm-ast describe src/mylib --compress

Includes:

  • Module docstrings (first line only)
  • __all__ exports
  • Public function signatures with first docstring line
  • Class stubs with methods
  • Relative imports (dependencies)
  • Module-level constants

Excludes:

  • Function bodies
  • Absolute imports (e.g., from pathlib import Path)
  • Private symbols not in __all__
  • Multi-line docstrings

TOC (table of contents)

Ultra-lightweight overview returning only module names and symbol counts — no individual function or class details.

axm-ast describe src/mylib --detail toc

Includes:

  • Module dotted name
  • Module docstring (first sentence)
  • Function count, class count, total symbol count

Excludes:

  • Individual function/class details
  • Signatures, parameters, imports, variables

Combine with --modules to filter:

axm-ast describe src/mylib --detail toc --modules core

Detail Levels (docs)

The docs command also supports progressive disclosure via --detail:

Full (default)

Returns complete content for README, mkdocs.yml, and all doc pages. Same as the original behavior.

axm-ast docs .

TOC

Heading tree + line count per page (~500 tokens). Use this to decide which pages to drill into.

axm-ast docs . --detail toc

Summary

Headings + first sentence per section. A budget-friendly overview with enough context to identify stale sections.

axm-ast docs . --detail summary

Page filter

Combine any detail level with --pages to narrow the scope:

axm-ast docs . --detail summary --pages architecture,howto

Flow Detail Levels (flows)

The flows command supports two detail levels via --detail:

Trace (default)

BFS traversal returning FlowStep objects with symbol name, module, depth, and call chain.

axm-ast flows src/mylib --entry main

Source

Adds function source text to each FlowStep. Useful for full code-level tracing.

axm-ast flows src/mylib --entry main --detail source

When --cross-module is enabled, the BFS also resolves imported symbols across package boundaries. See Cross-Module Resolution for the algorithm details.

Graph Formats

Text (default)

axm-ast graph src/mylib

Mermaid

Paste directly into GitHub markdown or MkDocs:

axm-ast graph src/mylib --format mermaid

```mermaid
graph TD
    cli["cli"]
    core_analyzer["core.analyzer"]
    cli --> core_analyzer
```

JSON

axm-ast graph src/mylib --json

JSON Output

Every command supports --json for machine-readable output. JSON output follows consistent conventions:

  • Describe: Full module/function/class trees
  • Graph: Adjacency list {module: [dependencies]}
  • Context: Structured project metadata
  • Impact: Callers, affected modules, tests, score
  • Search/Callers: Symbol lists with location info

Piping to jq

axm-ast describe src/mylib --json | jq '.modules[].name'
axm-ast impact src/mylib --symbol foo --json | jq '.score'