Skip to content

RSS-USAGE-GUIDE.md

Latest commit

 

History

History
481 lines (337 loc) · 12.2 KB

RSS-USAGE-GUIDE.md

File metadata and controls

481 lines (337 loc) · 12.2 KB

RSS - Runtime State Slicing Usage Guide (CLI)

Authority: E-ADR-004 (RSS CLI Implementation for Developer-Invoked Graph Traversal)
Audience: Human developers
Version: 1.0.0

For AI Coding Assistants

This document covers the CLI interface for human developers.

If you are an AI coding assistant (Cursor, Copilot, etc.), use the programmatic TypeScript API instead of the CLI. The programmatic API provides:

  • Structured data (typed objects, not parsed terminal output)
  • Faster execution (no process spawning)
  • Better integration with tooling

See RSS-PROGRAMMATIC-API.md for the machine interface.

What is RSS?

RSS (Runtime State Slicing) provides semantic graph traversal over AI-DOC state generated by RECON. RSS is a graph traversal protocol for deterministic context assembly that starts at entry points and traverses explicit references with depth bounds. Instead of grep-searching raw source code, RSS lets you query a pre-indexed semantic graph of:

  • Modules - Source files with exports, imports, and relationships
  • Functions - Callable units with signatures and dependencies
  • Classes - Type definitions with methods and properties
  • API Endpoints - REST/GraphQL endpoints with handlers
  • Data Entities - Database tables, schemas, models
  • Infrastructure - CloudFormation resources, parameters, outputs
  • Frontend Components - Angular/React components, services, routes
  • Design Tokens - CSS variables, breakpoints, animations

Key Insight: RSS trades grep's O(n) full-codebase search for O(1) semantic lookups with relationship traversal.

Quick Start

Prerequisites

  1. Run RECON first to generate semantic state:

    cd ste-runtime
npm run recon:full

  2. Verify state exists:

    node dist/cli/rss-cli.js stats

Basic Commands

# From ste-runtime directory:
node dist/cli/rss-cli.js <command> [args] [options]

# Or with npm script:
npm run rss -- <command> [args]

Command Reference

stats - Understand the Graph

Purpose: Get an overview of what's in the semantic graph before querying.

node dist/cli/rss-cli.js stats

Output:

Graph Statistics
================
Total nodes: 850
  graph/module: 120
  graph/function: 380
  graph/class: 45
  api/endpoint: 32
  data/entity: 15
  infrastructure/resource: 180
  infrastructure/template: 8
  frontend/component: 40
  frontend/service: 18
  ...

Total edges: 920
Tags: 1,150

When to use: Start here to understand the codebase structure and what domains are populated.

search - Entry Point Discovery

Purpose: Find relevant nodes using natural language. This is your starting point for exploration.

node dist/cli/rss-cli.js search "user authentication"
node dist/cli/rss-cli.js search "order processing"
node dist/cli/rss-cli.js search "DynamoDB table"

Options:

  • --max=N - Limit results (default: 50)

Output: Ranked list of nodes matching the query, with relevance scores.

When to use: When you don't know the exact component name but know the concept.

lookup - Direct Retrieval

Purpose: Get full details of a specific node by key or domain/id.

# By full key
node dist/cli/rss-cli.js lookup graph/function/src-services-auth.ts-validateToken

# By domain and ID
node dist/cli/rss-cli.js lookup graph/function validateToken

Output: Complete node data including:

  • Semantic metadata (domain, type, tags)
  • Source attribution (file, lines, checksum)
  • Relationships (imports, dependencies)
  • Full extracted content

When to use: When you know the exact component and need its details.

dependencies - Forward Traversal

Purpose: What does this component depend on? (Outgoing edges)

node dist/cli/rss-cli.js dependencies graph/module/src-services-user-service.ts
node dist/cli/rss-cli.js dependencies graph/function/createOrder --depth=3

Options:

  • --depth=N - How many hops to traverse (default: 2)

Output: Tree of dependencies showing what the target imports/calls/uses.

When to use: Understanding what a component needs to function.

dependents - Backward Traversal

Purpose: What depends on this component? (Incoming edges)

node dist/cli/rss-cli.js dependents data/entity/UsersTable
node dist/cli/rss-cli.js dependents graph/function/validateToken --depth=2

Options:

  • --depth=N - How many hops to traverse (default: 2)

Output: Tree of dependents showing what uses/imports/calls the target.

When to use: Understanding impact - "if I change this, what else is affected?"

blast-radius - Bidirectional Impact

Purpose: Full impact surface - both what this depends on AND what depends on it.

node dist/cli/rss-cli.js blast-radius data/entity/OrdersTable
node dist/cli/rss-cli.js blast-radius graph/module/src-api-users.py --depth=3

Options:

  • --depth=N - How many hops in each direction (default: 2)

Output: Combined tree showing complete impact surface.

When to use: Planning changes - understand the full ripple effect before modifying.

by-tag - Cross-Domain Query

Purpose: Find all nodes with a specific tag, regardless of domain.

node dist/cli/rss-cli.js by-tag "backend:api"
node dist/cli/rss-cli.js by-tag "dynamodb"
node dist/cli/rss-cli.js by-tag "frontend:component"
node dist/cli/rss-cli.js by-tag "angular"

Common tags:

  • backend:api, backend:lambda, backend:handler
  • frontend:component, frontend:service, frontend:guard
  • infrastructure:dynamodb, infrastructure:lambda, infrastructure:apigateway
  • python, typescript, cloudformation, angular

When to use: Discovering all components of a certain type across the codebase.

context - Full Context Assembly

Purpose: Natural language query that assembles a complete context bundle for a task.

node dist/cli/rss-cli.js context "implement user authentication"
node dist/cli/rss-cli.js context "add order status tracking"
node dist/cli/rss-cli.js context "create new API endpoint for notifications"

Output: Assembled bundle containing:

  • Relevant modules and functions
  • Data entities involved
  • API endpoints related
  • Infrastructure resources
  • Suggested entry points for implementation

When to use: Starting a new feature - get everything you need in one query.

Output Formats

Table (Default)

Human-readable tabular output with colors:

node dist/cli/rss-cli.js search "users" --format=table

JSON

Machine-readable JSON for scripting or AI consumption:

node dist/cli/rss-cli.js search "users" --json

Compact

Abbreviated output for quick scanning:

node dist/cli/rss-cli.js search "users" --compact

Workflows

Workflow 1: Exploring a New Codebase

# 1. Understand the shape of the codebase
node dist/cli/rss-cli.js stats

# 2. Find the main domains
node dist/cli/rss-cli.js by-tag "backend:api"
node dist/cli/rss-cli.js by-tag "frontend:component"

# 3. Search for key concepts
node dist/cli/rss-cli.js search "authentication"
node dist/cli/rss-cli.js search "dashboard"

# 4. Drill into specific components
node dist/cli/rss-cli.js lookup graph/module/src-services-auth-service.ts

Workflow 2: Planning a Feature

# 1. Get context for the feature
node dist/cli/rss-cli.js context "add email notifications for orders"

# 2. Find existing related components
node dist/cli/rss-cli.js search "notification"
node dist/cli/rss-cli.js search "email"

# 3. Understand the data model
node dist/cli/rss-cli.js by-tag "data:entity"
node dist/cli/rss-cli.js lookup data/entity/OrdersTable

# 4. Find API endpoints to extend
node dist/cli/rss-cli.js by-tag "api:endpoint"

# 5. Check blast radius of changes
node dist/cli/rss-cli.js blast-radius data/entity/OrdersTable

Workflow 3: Understanding Impact Before Refactoring

# 1. Find the component to refactor
node dist/cli/rss-cli.js search "processOrder"

# 2. Get its full details
node dist/cli/rss-cli.js lookup graph/function/processOrder

# 3. See what depends on it
node dist/cli/rss-cli.js dependents graph/function/processOrder --depth=3

# 4. See what it depends on
node dist/cli/rss-cli.js dependencies graph/function/processOrder --depth=2

# 5. Full blast radius
node dist/cli/rss-cli.js blast-radius graph/function/processOrder --depth=3

Workflow 4: Discovering Components by Type

# All API endpoints
node dist/cli/rss-cli.js by-tag "api:endpoint"

# All DynamoDB tables
node dist/cli/rss-cli.js by-tag "infrastructure:dynamodb"

# All Angular components
node dist/cli/rss-cli.js by-tag "frontend:component"

# All Angular services
node dist/cli/rss-cli.js by-tag "frontend:service"

# All Lambda handlers
node dist/cli/rss-cli.js by-tag "backend:handler"

For AI Coding Assistants

Recommended Exploration Pattern

When exploring a codebase to complete a task:

  1. Start with stats - Understand graph shape and available domains
  2. Use search or context - Find entry points for the task
  3. Use by-tag - Find all components of a type
  4. Use lookup - Get details of specific components
  5. Use blast-radius - Understand impact before proposing changes
  6. Use dependencies/dependents - Trace relationships

Key Advantages Over Grep

Grep RSS
Searches raw text Searches semantic meaning
Returns line matches Returns structured entities
No relationship awareness Full dependency graph
O(n) scan of all files O(1) indexed lookup
Results need interpretation Results are pre-parsed

Example: "Add a new API endpoint"

With RSS:

# Find existing endpoints as examples
node dist/cli/rss-cli.js by-tag "api:endpoint" --max=5

# See how an endpoint connects to handlers
node dist/cli/rss-cli.js dependencies api/endpoint/GET-/users

# Find the infrastructure template
node dist/cli/rss-cli.js search "API Gateway"

# Get the data model
node dist/cli/rss-cli.js by-tag "data:entity"

Without RSS (grep):

# Many grep calls needed
grep -r "def get_" backend/
grep -r "AWS::ApiGateway" infrastructure/
grep -r "Type.*Table" infrastructure/
# ...must read each file to understand relationships

Reading Slice Files

If you need raw slice data, read from .ste/state/:

.ste/state/
├── graph/
│   ├── modules/     # Module-level slices
│   ├── functions/   # Function-level slices
│   └── classes/     # Class-level slices
├── api/
│   └── endpoints/   # API endpoint slices
├── data/
│   └── entities/    # Data model slices
├── infrastructure/
│   ├── resources/   # CloudFormation resources
│   ├── templates/   # Template metadata
│   ├── parameters/  # Stack parameters
│   └── outputs/     # Stack outputs
└── frontend/
    ├── component/   # Angular/React components
    ├── service/     # Services
    └── styles/      # CSS/design tokens

Slice files are YAML with consistent structure:

_slice:
  id: "function:path/to/file.py:function_name"
  domain: "backend"
  type: "function"
  tags: ["backend:lambda", "python", "handler"]
_source:
  files: ["path/to/file.py"]
  line_start: 42
  line_end: 95
  checksum: "abc123..."
# ... semantic content ...

Troubleshooting

"State directory not found"

Run RECON first:

cd ste-runtime
npm run recon:full

"No results found"

  1. Check if RECON completed successfully
  2. Verify the state directory has content: ls .ste/state/
  3. Try broader search terms
  4. Use stats to see what's indexed

Graph seems incomplete

  1. Check ste.config.json includes all source directories
  2. Verify languages are configured correctly
  3. Re-run RECON with --mode=full

Integration with RECON

RSS operates on the semantic state generated by RECON:

Source Code → [RECON] → .ste/state/ → [RSS] → Query Results

Keep state fresh: Re-run RECON after significant code changes:

npm run recon

See Also