Skip to content

Add outline CLI command#2738

Merged
HerringtonDarkholme merged 1 commit into
mainfrom
outline-cli-command
Jun 19, 2026
Merged

Add outline CLI command#2738
HerringtonDarkholme merged 1 commit into
mainfrom
outline-cli-command

Conversation

@HerringtonDarkholme

@HerringtonDarkholme HerringtonDarkholme commented Jun 19, 2026

Copy link
Copy Markdown
Member

Summary

  • add the outline subcommand and text/JSON output paths
  • compile and cache outline extractors per language for file workers
  • include Rust built-in outline rules and final CLI module organization

Test

  • cargo fmt --check
  • cargo test -p ast-grep-outline
  • cargo check -p ast-grep

Summary by CodeRabbit

Release Notes

  • New Features

    • The outline command is now fully functional with extraction from files and stdin.
    • Added --outline-rules option to load custom outline rule files.
    • Added --no-default-outline-rules flag to skip bundled default rules.
    • Outline output supports JSON and multiple formatted text views.
    • Includes bundled Rust outline rules for common symbol types.
  • Tests

    • Added comprehensive test suite for outline rendering across all output formats and styles.

@coderabbitai

coderabbitai Bot commented Jun 19, 2026

Copy link
Copy Markdown
Contributor

Review Change Stack

📝 Walkthrough

Walkthrough

This PR implements the sg outline CLI command end-to-end. It activates bundled Rust YAML outline rules (DEFAULT_OUTLINE_RULES), adds an extraction pipeline (OutlineExtractors, load_outline_rules, extract_stdin, stream_paths), derives OutlineTextOptions from CLI args, and introduces OutlineEmitter for text and JSON output across four view modes.

Changes

sg outline end-to-end implementation

Layer / File(s) Summary
Bundled Rust outline rules and crate export
crates/outline/src/default_rule.rs, crates/outline/src/lib.rs
Replaces the legacy commented prototype with an active DEFAULT_OUTLINE_RULES YAML constant covering all Rust symbol types, exports it from the crate root, and adds three integration tests that compile and assert extraction results for functions, structs, enums, impls, traits, visibility, and generic shapes.
CLI wiring and extraction pipeline
crates/cli/Cargo.toml, crates/cli/src/outline.rs, crates/cli/src/outline/extract.rs
Adds ast-grep-outline as a workspace dependency, replaces the run_outline stub with real logic that loads rules, constructs OutlineExtractors, resolves options, and drives OutlineEmitter. extract.rs provides OutlineFile, the extractor cache, load_outline_rules, extract_stdin, parallel stream_paths, path/language helpers, and 'static ownership converters.
OutlineTextOptions filtering
crates/cli/src/outline/options.rs
Defines OutlineTextOptions and try_from_arg: resolves Auto item/view modes from input shape, parses comma-separated SymbolType filters, compiles an optional name/signature regex, and exposes matches_item_filters as a composed predicate.
OutlineEmitter and text/JSON rendering
crates/cli/src/outline/output.rs
Implements OutlineEmitter with JSON (pretty/compact/stream) and text dispatch; per-view renderers for Names, Signatures, Digest, and Expanded; line-number alignment; grouped name/member builders; item_line/member_line formatters; SymbolType→label/ANSI-color mapping; and OutlineTextStyle with emphasis logic for imports and exports.
Emitter and CLI outline tests
crates/cli/src/outline/output/tests.rs, crates/cli/src/lib.rs
Adds fixture builders and tests covering all four view modes, line-number padding, empty-file output, multi-file spacing, JSON Lines and compact JSON modes, per-SymbolType ANSI color assertions, and redundant-style suppression. Updates CLI test assertions so --outline-rules and --no-default-outline-rules are valid.

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant run_outline
  participant load_outline_rules
  participant OutlineExtractors
  participant OutlineTextOptions
  participant OutlineEmitter
  participant stream_paths

  User->>run_outline: sg outline [--outline-rules F] [--no-default-outline-rules] [paths]
  run_outline->>load_outline_rules: include_default=!flag, extra paths
  load_outline_rules-->>run_outline: Vec<SerializableOutlineRule>
  run_outline->>OutlineExtractors: new(rules)
  run_outline->>OutlineTextOptions: try_from_arg(arg)
  run_outline->>OutlineEmitter: new(stdout, json_style, options)
  alt stdin
    run_outline->>stream_paths: extract_stdin(arg, extractors, options)
    stream_paths-->>OutlineEmitter: emit(OutlineFile)
  else file/dir paths
    run_outline->>stream_paths: stream_paths(arg, extractors, options, emit)
    stream_paths-->>OutlineEmitter: emit(OutlineFile) per file
  end
  run_outline->>OutlineEmitter: finish()
  OutlineEmitter-->>User: text / JSON output
Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

  • ast-grep/ast-grep#2685: Introduced the sg outline CLI command and OutlineArg struct that this PR builds upon with full extraction/emission implementation.
  • ast-grep/ast-grep#2702: Rewrote the outline core model (Entry/Item/Member schema) that extract.rs, options.rs, and output.rs in this PR directly consume for filtering and rendering.
  • ast-grep/ast-grep#2710: Introduced SerializableOutlineRule and rule serde infrastructure that load_outline_rules and OutlineExtractors in this PR depend on for rule loading and compilation.

Poem

🐇 Hop, hop! The outline bursts to life,
Rules in YAML, carved clean and precise.
Through AST forests the extractor bounds,
JSON or text — the emitter resounds.
No more todo!(), no stub left to hide,
The rabbit has shipped the whole outline ride! 🌿

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 30.36% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title 'Add outline CLI command' accurately summarizes the main change: implementing a new outline subcommand for the ast-grep CLI tool.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch outline-cli-command

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

Base automatically changed from outline-cursor-traversal to main June 19, 2026 15:36
@codecov

codecov Bot commented Jun 19, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 60.31915% with 373 lines in your changes missing coverage. Please review.
✅ Project coverage is 85.85%. Comparing base (ca14c11) to head (2a96e6f).

Files with missing lines Patch % Lines
crates/cli/src/outline/extract.rs 0.00% 194 Missing ⚠️
crates/cli/src/outline/options.rs 0.00% 96 Missing ⚠️
crates/cli/src/outline/output.rs 83.29% 73 Missing ⚠️
crates/cli/src/outline.rs 0.00% 10 Missing ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##             main    #2738      +/-   ##
==========================================
- Coverage   86.93%   85.85%   -1.09%     
==========================================
  Files         121      125       +4     
  Lines       21010    21945     +935     
==========================================
+ Hits        18266    18841     +575     
- Misses       2744     3104     +360     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@crates/cli/src/outline/extract.rs`:
- Around line 140-170: Replace the unbounded mpsc::channel() call on line 140
with a bounded channel by using mpsc::channel(capacity) instead, where capacity
is an appropriate limit for the maximum number of OutlineFile items that should
be queued. This will apply backpressure to the producer thread when the queue
reaches capacity, preventing memory spikes when parallel walks generate files
faster than the sequential processing loop can consume them. The rest of the
producer and consumer logic using tx.send() and rx.recv() will automatically
handle the bounded behavior.

In `@crates/outline/src/default_rule.rs`:
- Around line 7-726: Add new pattern-based rules to the DEFAULT_OUTLINE_RULES
constant to handle async functions that are currently missing from extraction.
Create rules for async function variants (pub async fn, async fn) that mirror
the existing synchronous function rules such as rust-function-public,
rust-function, rust-function-public-return, rust-function-return,
rust-function-public-generic, rust-function-generic, and their variants with
return types and where clauses. Each async rule should have a unique id prefixed
with rust-async- and patterns that include the async keyword before fn, for
example pub async fn $NAME($$$ARGS) { $$$BODY } and async fn $NAME($$$ARGS) {
$$$BODY }, along with corresponding variants for generic parameters, return
types, and where clauses to match the coverage provided by existing non-async
rules.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: f4084b29-85b2-467a-b9d8-e1e21417e6c1

📥 Commits

Reviewing files that changed from the base of the PR and between ca14c11 and 2a96e6f.

⛔ Files ignored due to path filters (1)
  • Cargo.lock is excluded by !**/*.lock
📒 Files selected for processing (9)
  • crates/cli/Cargo.toml
  • crates/cli/src/lib.rs
  • crates/cli/src/outline.rs
  • crates/cli/src/outline/extract.rs
  • crates/cli/src/outline/options.rs
  • crates/cli/src/outline/output.rs
  • crates/cli/src/outline/output/tests.rs
  • crates/outline/src/default_rule.rs
  • crates/outline/src/lib.rs

Comment thread crates/cli/src/outline/extract.rs
Comment thread crates/outline/src/default_rule.rs
@HerringtonDarkholme

Copy link
Copy Markdown
Member Author

this is still awful, but it's okay to merge now and iterate later

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant