From 0b2468265501858ae59949b8d882398288205909 Mon Sep 17 00:00:00 2001 From: Sergei Zharinov Date: Sun, 4 Jan 2026 12:58:02 -0300 Subject: [PATCH] chore: minor doc formatting --- AGENTS.md | 37 +++++++++++++++++++++++++++++-------- docs/cli.md | 39 ++++++++++++++++++++------------------- 2 files changed, 49 insertions(+), 27 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 32424a24..82c74b83 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,6 @@ # Ethos -- `AGENTS.md` is our constitution. Propose useful amendments. +- `AGENTS.md` is our constitution. When you notice systematic gaps (repeated retries, patterns discovered through trial-and-error), propose amendments at the end of the session. - Resilient parser with user-friendly error messages called "diagnostics" (see `diagnostics/`) - Stability via invariants: `panic!`/`assert!`/`.expect()` for simple cases, `invariants.rs` otherwise @@ -227,6 +227,7 @@ Options: `--verbose-nodes`, `--no-node-type`, `--no-export`, `-o ` Execute a query against source code and output JSON. **Usage variants:** + ``` exec # two positional files exec -q # inline query + source file @@ -246,6 +247,7 @@ Options: `--compact`, `--verbose-nodes`, `--check`, `--entry ` Trace query execution for debugging. **Usage variants:** + ``` trace # two positional files trace -q # inline query + source file @@ -276,13 +278,13 @@ cargo run -p plotnik-cli -- langs ## Lifetime Conventions -| Lifetime | Meaning | -| -------- | ------------------------------------------------ | -| `'q` | Query source string (`.ptk` file content) | -| `'d` | Diagnostics reference | -| `'s` | Source code string (tree-sitter input) | -| `'t` | Parsed tree-sitter tree | -| `'a` | Any other (generic borrows, bytecode views) | +| Lifetime | Meaning | +| -------- | ------------------------------------------- | +| `'q` | Query source string (`.ptk` file content) | +| `'d` | Diagnostics reference | +| `'s` | Source code string (tree-sitter input) | +| `'t` | Parsed tree-sitter tree | +| `'a` | Any other (generic borrows, bytecode views) | # Testing Rules @@ -318,3 +320,22 @@ fn valid_query() { Coverage: `make coverage-lines | grep recursion` `invariants.rs`: `ensure_*()` functions for unreachable code exclusion from coverage. + +# PR Body Format + +``` +## Summary +<1-3 bullets: what this PR does> + +## Why +<1-2 sentences: motivation, problem solved, or link to relevant docs> + +## Notes (optional) + +``` + +- **Summary**: Quick scan; becomes squash-merge commit body +- **Why**: Captures context that code/diff doesn't convey +- **Notes**: Escape hatch for edge cases + +**Omit**: How (diff shows this), Testing (CI covers it). diff --git a/docs/cli.md b/docs/cli.md index eef12974..4c74039f 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -170,15 +170,15 @@ plotnik exec query.ptk app.js --entry FunctionDef **Flags:** -| Flag | Purpose | -| ----------------- | ------------------------------------- | -| `-q, --query` | Inline query text | -| `-s, --source` | Inline source text | -| `-l, --lang` | Language (inferred from file ext) | -| `--compact` | Output compact JSON | -| `--verbose-nodes` | Include line/column in nodes | -| `--check` | Validate output against inferred types| -| `--entry NAME` | Start from specific definition | +| Flag | Purpose | +| ----------------- | -------------------------------------- | +| `-q, --query` | Inline query text | +| `-s, --source` | Inline source text | +| `-l, --lang` | Language (inferred from file ext) | +| `--compact` | Output compact JSON | +| `--verbose-nodes` | Include line/column in nodes | +| `--check` | Validate output against inferred types | +| `--entry NAME` | Start from specific definition | --- @@ -221,6 +221,7 @@ plotnik trace query.ptk app.js -vv # very verbose ### Query-Only Commands (tree, check, dump, infer) These commands take a single input. Use either: + - **Positional**: `plotnik tree app.ts` or `plotnik dump query.ptk` - **Flag**: `plotnik tree -s 'let x' -l js` or `plotnik dump -q 'Q = ...'` @@ -228,21 +229,21 @@ These commands take a single input. Use either: These commands take two inputs. Use any combination: -| Pattern | Query from | Source from | -| ------------------------------- | ------------- | -------------- | -| `exec QUERY SOURCE` | 1st positional| 2nd positional | -| `exec -q '...' SOURCE` | `-q` flag | positional | -| `exec -s '...' QUERY -l lang` | positional | `-s` flag | -| `exec -q '...' -s '...' -l lang`| `-q` flag | `-s` flag | +| Pattern | Query from | Source from | +| -------------------------------- | -------------- | -------------- | +| `exec QUERY SOURCE` | 1st positional | 2nd positional | +| `exec -q '...' SOURCE` | `-q` flag | positional | +| `exec -s '...' QUERY -l lang` | positional | `-s` flag | +| `exec -q '...' -s '...' -l lang` | `-q` flag | `-s` flag | **Key rule**: When `-q` is provided with one positional, it becomes SOURCE. ### Language Detection -| Input type | Language | -| ------------ | -------------------- | -| File | Inferred from `.ext` | -| Inline (`-s`)| Requires `-l` | +| Input type | Language | +| ------------- | -------------------- | +| File | Inferred from `.ext` | +| Inline (`-s`) | Requires `-l` | ---