npm package: @plunderstruck/repo-ctx
Description: Agent-first JavaScript and TypeScript code navigation CLI.
Latest version: 0.3.0

# ctx Tool

`ctx` is an agent-first JavaScript and TypeScript code navigation CLI.

The tool builds a compact structural model of a codebase so an agent can work
from indexed symbols, call graphs, data flow, and compact reports instead of
repeatedly reading raw files into context.

Examples below use `ctx` as the installed command name.
In this repo checkout, run `node tools/ctx/ctx ...` from the repo root.
Use `ctx --root /path/to/repo ...` when you want to target a repo other than
the current working directory.

## Why Use It

- Find exported, private, and nested symbols without grepping files by hand.
- Follow call relationships and data flow from real AST-based analysis.
- See impact and blast radius from one CLI surface.
- Prefer compact outputs when they help an agent stay precise with fewer tokens.

## Quick Start

Install globally:

```bash
npm install -g @plunderstruck/repo-ctx
ctx --help
```

Or use the repo-local checkout:

```bash
npm install
node tools/ctx/ctx --help
```

Initialize `ctx` for an existing repo:

```bash
ctx init
```

That writes both `ctx/config.json` and a starter `ctx/arch.json` when the repo
does not already have an architecture config.

Preview the generated config first:

```bash
ctx init --dry-run
```

Build the index:

```bash
ctx index
```

Use the indexed surfaces:

```bash
ctx find runRegen
ctx about runRegen
ctx context buildIndexedFileEntry --callers
ctx file tools/ctx/lib/index/regen.js
```

When in doubt, start with live help:

```bash
ctx help
ctx help context
```

## Core Workflow

1. Run `ctx init` once per repo.
2. Run `ctx index` after source changes.
3. Use `find`, `file`, `about`, `context`, `code`, `dataflow`, and `slice` to
   navigate the codebase.
4. Use `affected`, `cycles`, and `similar` for change and hygiene views.

### Command Chooser

- `find` searches for symbols by name or keyword.
- `file` shows one file's indexed symbols.
- `about` is the symbol card: signature and direct callers/callees.
- `context` is the local call-graph view around one symbol.
- `code` returns a bounded source snippet for one symbol.

## Output Defaults

`ctx` does not force one renderer for every command.

- `find` defaults to TOON because exact symbol identity matters more than
  prose when names collide.
- `file`, `about`, `context`, `code`, `impact`,
  `complexity`, `dataflow`, and `slice` stay human-first because their structured forms
  are materially larger on real code and often repeat identity context
  across distinct results.
- `map tree` stays markdown-first.
- `map stats` is best as a human summary, with TOON useful when another tool
  needs explicit fields.

Use `--toon`, `--json`, or `--human` when a command supports them. Use
`ctx help <command>` for the live contract.

## Symbol Coverage

A symbol in `ctx` is a named code unit the agent can identify and relate.
The current JS/TS parser covers:

- function declarations
- function-valued const bindings
- property-assigned functions such as `store.reset = () => {}`
- class declarations and class expressions assigned to bindings
- object-literal methods and accessors under named bindings
- methods, accessors, class properties, constructors, and constructor
  parameter properties
- private class members
- nested local helpers
- destructured bindings
- default exports, CommonJS export assignments, and named/namespace re-exports

The parser intentionally excludes throwaway anonymous callbacks that do not
help navigation.

## Key Commands

Use `ctx help <command>` or append `--help` for live usage.

### Indexing

- `ctx init [--dry-run] [--force] [--json]`
- `ctx index [--force]`

### Discovery

- `ctx find "<query>" [filters]`
- `ctx file <path>`
- `ctx about <symbol>`
- `ctx context <symbol> [--depth=N] [--callers] [--budget=N]`
- `ctx code <symbol> [--context=<n>]`

### Analysis

- `ctx impact <symbol> [--depth=N]`
- `ctx complexity <symbol>`
- `ctx dataflow <symbol>`
- `ctx slice <symbol> <variable> [--forward|--backward] [--line=N]`

### Navigation

- `ctx map tree [--human|--toon|--json]`
- `ctx map stats [--human|--json|--toon] [--files] [--full]`
- `ctx config <key> [value]`

### Change And Hygiene

- `ctx affected [ref] [--tests-only] [--verbose|-v] [--since=REF]`
- `ctx cycles`
- `ctx similar [--to=<symbol>] [--min-savings=N] [--path=<dir>] [--threshold=<0-1>]`

### Choosing The Right Symbol Command

- `about` is the symbol card. Use it for identity and direct callers/callees.
- `context` is the local call-graph view. Use it to walk outward through callees or inspect direct callers around one symbol.
- `impact` is the reverse blast-radius view. Use it to trace caller chains back to entry points.

## Repo And Package Surface

The named CLI entrypoint is `tools/ctx/cli.js`.
The extensionless `tools/ctx/ctx` file is now only a tiny shim so existing
repo-local workflows keep working.

Useful package scripts:

```bash
npm test
npm run check:self-host
npm run self:index
npm run self:help
```

## Generated Files

Do not edit these by hand:

- `ctx/config.json`
- `ctx/manifest.json`
- `ctx/index.top.md`
- `ctx/files/**`