# AST_GREP_COMMANDS

Purpose: keep discovery lightweight by using repeatable `ast-grep` queries instead of storing very large file maps in `agent-state/index.json`.

Scope:
- Run from workspace root.
- Prefer targeted paths (`ace-mcp-server/src`, `engineering-state/src`) over `.` when possible.
- Treat this as command playbook for orchestrator/research/spec workflows.

## 1) Profile the codebase quickly

```bash
# Languages present (source files only)
find . -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.py" -o -name "*.rs" -o -name "*.go" \) \
  | grep -v "\.git\|node_modules\|dist\|target\|__pycache__" \
  | sed 's/.*\.//' | sort | uniq -c | sort -rn

# Entry-point candidates
find . \( -name "index.ts" -o -name "main.py" -o -name "main.rs" -o -name "server.ts" -o -name "app.py" \) \
  | grep -v "\.git\|node_modules\|dist\|target" | head -20
```

## 2) TypeScript/JavaScript API surface

```bash
# Exported functions (TS)
ast-grep --pattern 'export function $NAME($$$ARGS): $RET { $$$BODY }' --lang ts ace-mcp-server/src --color never \
  | grep -oE 'export function [A-Za-z0-9_]+' | awk '{print $3}' | sort -u

# Exported classes (TS)
ast-grep --pattern 'export class $NAME { $$$BODY }' --lang ts ace-mcp-server/src --color never \
  | grep -oE 'export class [A-Za-z0-9_]+' | awk '{print $3}' | sort -u

# Async functions (TS)
ast-grep --pattern 'async function $NAME($$$ARGS)' --lang ts ace-mcp-server/src --color never
```

## 3) Python API surface

```bash
# Top-level function definitions
ast-grep --pattern 'def $NAME($$$ARGS):' --lang python engineering-state/src --color never

# Class definitions
ast-grep --pattern 'class $NAME:' --lang python engineering-state/src --color never
```

## 4) Rust API surface

```bash
# Public functions
ast-grep --pattern 'pub fn $NAME($$$ARGS)' --lang rust engineering-state/src --color never

# Public structs
ast-grep --pattern 'pub struct $NAME' --lang rust engineering-state/src --color never
```

## 5) Test and quality signals

```bash
# TS test blocks
ast-grep --pattern "it('$DESC', $$$BODY)" --lang ts ace-mcp-server/src --color never
ast-grep --pattern 'test("$DESC", $$$BODY)' --lang ts ace-mcp-server/src --color never

# Python tests
ast-grep --pattern 'def test_$NAME($$$ARGS):' --lang python engineering-state/src --color never

# TODO/FIXME/HACK density
grep -rn "TODO\|FIXME\|HACK\|XXX" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.py" --include="*.rs" . \
  | grep -v "\.git\|node_modules\|dist\|target"
```

## 6) Contract and handoff checks (ACE-specific)

```bash
# Find handoff schema references
ast-grep --pattern '$X("SWARM_HANDOFF.$Y")' --lang ts ace-mcp-server/src --color never

# Find route selection logic
grep -rn "route_task\|routingMap\|ace-orchestrator" ace-mcp-server/src

# Find index usage
grep -rn "agent-state/index.json\|scanWorkspaceDelta" ace-mcp-server/src
```

## 7) `rep_astgrep.cxml` corpus mining (reference pack)

Use when `rep_astgrep.cxml` exists and you need a structural map from the imported ast-grep reference corpus without loading the full XML into context.

```bash
# Source path inventory inside corpus
rg -o "<source>[^<]+</source>" rep_astgrep.cxml \
  | sed -E 's#</?source>##g' | sort | uniq > /tmp/rep_astgrep_sources.txt

# Top-level directory distribution
awk -F/ '{print $1}' /tmp/rep_astgrep_sources.txt | sort | uniq -c | sort -rn | head -30

# Language distribution from referenced source paths
sed -nE 's#.*\.([a-zA-Z0-9]+)$#\1#p' /tmp/rep_astgrep_sources.txt | sort | uniq -c | sort -rn

# High-signal AST/CLI docs inside corpus
rg -n "ast-grep|sg |playground|pattern|rewrite|rule|yaml|napi|pyo3|Cargo.toml" rep_astgrep.cxml | head -120
```

## 8) Output capture template

When a scan is materially important, persist to `agent-state/EVIDENCE_LOG.md`:

```bash
{
  date -u +"[%Y-%m-%dT%H:%M:%SZ] ast-grep scan: exported TS functions";
  ast-grep --pattern 'export function $NAME($$$ARGS): $RET { $$$BODY }' --lang ts ace-mcp-server/src --color never \
    | grep -oE 'export function [A-Za-z0-9_]+' | awk '{print $3}' | sort -u;
} >> agent-state/EVIDENCE_LOG.md
```

## 9) Usage guidance

- Use `agent-state/index.json` for lightweight map metadata (counts, directories, extensions, sampled entries).
- Use this command pack for deep inspection and role-specific discovery.
- Prefer narrow path scopes for speed and reduced noise.