sview 0.1.0

Agent-friendly structure views of source and document files
Documentation

sview

sview is a small Rust CLI for producing agent-friendly structure views of files.

It is not an editor, refactoring engine, or IDE protocol client. Its first job is to help coding agents understand where the important structures are before they decide which exact ranges to read or edit.

Why

Coding agents often work with only two primitive file operations:

  1. read text;
  2. apply patch.

That is enough for small files, but it becomes expensive and fragile for large source files, Markdown documents, config files, and generated-looking artifacts. The agent has to repeatedly read broad ranges, remember where symbols or sections are, and produce large text patches without a compact structural map.

sview fills the gap before editing:

agent -> sview -> compact structure view -> targeted reads / patches

Project status

Status: 0.1.0 release candidate.

The current crate provides a working Rust CLI with Markdown, Rust, JavaScript, and TypeScript structure views. Rust and JS/TS parsing use tree-sitter grammars; Markdown parsing is still a lightweight line-oriented outline.

Installation

Install the released CLI from crates.io:

cargo install sview

Or install from the repository checkout:

cargo install --path .

Design goals

  • Agent-facing: optimize output for downstream agents, not for human IDE UI.
  • View first: inspect and summarize structure; do not mutate files.
  • Fast local CLI: start quickly, work well in shell-based agent runtimes, and produce bounded output.
  • Stable ranges: report line ranges that can guide follow-up sed, editor, patch, or tool calls.
  • Broad file coverage: support code, Markdown, configuration, scripts, and other structured text files over time.
  • Machine-readable by default: provide a stable JSON contract, with optional text formats for humans and agents.
  • Small core: avoid becoming a full LSP client, IDE backend, or rewrite framework in the first phase.

Non-goals

First versions should not implement:

  • rename symbol;
  • move symbol / move module;
  • extract function / extract module;
  • organize imports;
  • compiler or LSP diagnostics;
  • code actions;
  • automatic rewrites.

Those capabilities may later belong in a sibling tool such as sedit, or in a higher-level agent harness that combines sview with parser, LSP, compiler, or codemod backends.

CLI

The CLI is shaped around simple file-oriented calls:

sview README.md
sview README.md src/lib.rs
sview README.md --json
sview README.md src/lib.rs --json
sview src/lib.rs --json
sview src/lib.rs --depth 2
sview src/lib.rs --format text

The 0.1.x CLI supports:

  • one or more input files per invocation;
  • automatic language detection from path and content;
  • JSON output;
  • optional compact text output;
  • maximum depth / maximum nodes / maximum preview length controls.

Output model

A structure view is a tree of nodes with source ranges:

{
  "path": "src/lib.rs",
  "language": "rust",
  "nodes": [
    {
      "kind": "function",
      "name": "run_task",
      "start_line": 120,
      "end_line": 188,
      "preview": "fn run_task(...) -> ...",
      "children": []
    }
  ]
}

For Markdown, the same contract can represent headings and document regions:

{
  "path": "README.md",
  "language": "markdown",
  "nodes": [
    {
      "kind": "heading",
      "level": 2,
      "name": "Installation",
      "start_line": 20,
      "end_line": 42,
      "children": []
    }
  ]
}

The output should be deliberately boring: stable keys, predictable ranges, and enough preview text to help an agent choose the next read or edit range.

First implementation slice

A useful MVP can stay very small:

  1. Markdown outline from headings, frontmatter, code blocks, and list regions.
  2. Rust outline for modules, structs, enums, traits, impl blocks, functions, and tests.
  3. JSON output with line ranges and short previews.
  4. Compact text output for quick terminal use.
  5. Real dogfooding inside agent tasks that currently require large-file inspection.

Dogfooding

During development, use the local binary before broad file reads:

cargo run --quiet -- README.md --depth 2
cargo run --quiet -- README.md src/lib.rs --depth 1
cargo run --quiet -- src/lib.rs --depth 1 --max-nodes 40
cargo run --quiet -- tests/fixtures/typescript_sample.ts --depth 2
cargo run --quiet -- tests/fixtures/javascript_sample.js tests/fixtures/tsx_sample.tsx --json
cargo run --quiet -- src/lib.rs --json --depth 2

Text output is a compact tree outline:

src/main.rs (rust)
├─ struct Cli L8-31 — struct Cli {
├─ enum OutputFormat L34-37 — enum OutputFormat {
└─ function main L39-54 — fn main() -> Result<()> {

TypeScript output uses the same shape:

tests/fixtures/typescript_sample.ts (typescript)
├─ interface User L1-3 — export interface User {
├─ type UserId L5-5 — type UserId = string;
├─ enum Mode L7-10 — enum Mode {
└─ class Service L12-16 — export class Service {
   └─ method load L13-15 — async load(id: UserId): Promise<User> {

The intended workflow is:

  1. run sview on one or more candidate files to get stable line ranges;
  2. read only the relevant range with a focused command such as sed -n '120,180p';
  3. patch or inspect the exact range, then rerun sview or tests if structure changed.

Possible implementation approach

Rust is the preferred implementation language because sview should behave like local developer tools such as rg, bat, or ast-grep:

  • fast startup;
  • single binary distribution;
  • predictable file and range handling;
  • good parser ecosystem;
  • easy JSON output;
  • suitable for repeated agent subprocess calls.

Current implementation dependencies:

  • clap for CLI parsing;
  • serde / serde_json for output contracts;
  • tree-sitter, tree-sitter-rust, tree-sitter-javascript, and tree-sitter-typescript for code outlines.

Possible future dependencies include more tree-sitter grammars for additional languages and pulldown-cmark or another Markdown parser for richer document outlines.

Development and coverage

Run the normal verification before submitting changes:

cargo fmt -- --check
cargo test

Coverage is tracked with cargo-llvm-cov:

cargo install cargo-llvm-cov
cargo coverage

cargo coverage is a Cargo alias for cargo llvm-cov --workspace --all-targets --summary-only.

Initial coverage target: keep the core library line coverage at 70% or higher while the project is small. Parser behavior should be covered with checked-in fixtures under tests/fixtures/ for every supported language.

Release

Release readiness checks:

cargo fmt -- --check
cargo test
cargo coverage
cargo publish --dry-run

The crate is licensed under Apache-2.0. Release tags use the vMAJOR.MINOR.PATCH form, for example v0.1.0.

Relationship to other tools

sview is narrower than an IDE and higher-level than raw parser output:

agent -> sview -> tree-sitter / markdown parser / ast-grep / LSP / compiler
  • LSP can be a backend later, but the agent should not need to speak LSP directly.
  • ast-grep can be a backend for structural matching or future rewrite workflows, but sview should first expose an outline, not a grep interface.
  • IDE MCP servers and tools like Serena are closer to full code intelligence backends; sview starts as a lightweight CLI surface.

Repository layout

.
├── README.md
├── Cargo.toml
├── LICENSE
├── .github/
│   └── workflows/
│       └── ci.yml
├── src/
│   ├── analyzer.rs
│   ├── javascript.rs
│   ├── markdown.rs
│   ├── model.rs
│   ├── render.rs
│   ├── rust.rs
│   ├── util.rs
│   ├── lib.rs
│   └── main.rs
├── skills/
│   └── sview-dogfooding/
└── tests/
    └── fixtures/