Rodin
bd9790caa1
5 steps: Quantify → Extract one → Decision tree → Cross-refs → Hyperlinks. Delegation strategy (per-entry, not per-file). Discovery greps for Go, Elixir, Rust, Python. Hyperlink scripts per language.
290 lines
10 KiB
Markdown
290 lines
10 KiB
Markdown
# Commands Reference
|
|
|
|
Shell patterns for each phase. Load only when you need the exact
|
|
syntax — the SKILL.md tells you WHAT to look for; this tells you HOW.
|
|
|
|
---
|
|
|
|
## Phase 1: Shape
|
|
|
|
```bash
|
|
# Clone (always full — never --depth 1)
|
|
cd $CLONE_DIR && git clone <url>
|
|
|
|
# Dimensions
|
|
du -sh <repo>
|
|
find . -name "*.go" | grep -v vendor | wc -l # Go files
|
|
git log --oneline | wc -l # commits
|
|
git log --format="%an" | sort -u | wc -l # contributors
|
|
ls -d */ # top-level dirs
|
|
```
|
|
|
|
## Phase 2: Import Hierarchy
|
|
|
|
```bash
|
|
# Go: most-imported internal packages
|
|
grep -rh '"<module>/' --include="*.go" \
|
|
| sed 's/.*"<module>\///' | sed 's/".*//' \
|
|
| cut -d/ -f1 | sort | uniq -c | sort -rn | head -15
|
|
|
|
# Elixir: most-aliased modules
|
|
grep -rh "alias " --include="*.ex" \
|
|
| sed 's/.*alias //' | cut -d. -f1-2 \
|
|
| sort | uniq -c | sort -rn | head -15
|
|
```
|
|
|
|
## Phase 3: Interfaces
|
|
|
|
```bash
|
|
# Go interfaces (skip test/mock/generated)
|
|
grep -rn "type.*interface {" --include="*.go" \
|
|
| grep -v test | grep -v mock | grep -v _gen.go
|
|
|
|
# Elixir behaviours/protocols
|
|
grep -rn "@callback\|@behaviour\|defprotocol" --include="*.ex"
|
|
```
|
|
|
|
## Phase 4: Quality Markers
|
|
|
|
```bash
|
|
# TODOs (non-test, note format)
|
|
grep -rn "TODO" --include="*.go" | grep -v test | wc -l
|
|
grep -rh "// TODO" --include="*.go" | head -5 # check format
|
|
|
|
# Other markers
|
|
grep -rn "FIXME\|HACK" --include="*.go" | grep -v test | wc -l
|
|
|
|
# Test ratio
|
|
find . -name "*_test.go" | wc -l # test files
|
|
find . -name "*mock*" | wc -l # mock files
|
|
```
|
|
|
|
## Phase 6: Git Archaeology
|
|
|
|
```bash
|
|
# When was a file/pattern introduced?
|
|
git log --all --oneline --diff-filter=A -- path/to/file
|
|
|
|
# Who wrote it and why?
|
|
git log --format="%an%n%ad%n%s%n%b" <commit> -1
|
|
|
|
# When was a string added/removed (pickaxe search)?
|
|
git log -p -S "pattern_string" -- relevant/path/
|
|
|
|
# TODOs added with context
|
|
git log --all -p -S "TODO" -- lib/ \
|
|
| grep "^commit\|^+.*TODO\|^-.*TODO" | head -20
|
|
|
|
# Find if full clone or shallow
|
|
git rev-parse --is-shallow-repository
|
|
# Unshallow if needed
|
|
git fetch --unshallow
|
|
```
|
|
|
|
## Phase 7: PR Lookup
|
|
|
|
```bash
|
|
# Find PR by title/content
|
|
gh api "search/issues?q=repo:<org>/<repo>+<keywords>+type:pr" \
|
|
--jq '.items[] | {number: .number, title: .title}'
|
|
|
|
# Read PR metadata
|
|
gh api repos/<org>/<repo>/pulls/<num> \
|
|
--jq '{title, body: (.body | split("\n") | .[0:30] | join("\n")), comments, review_comments, created_at, merged_at}'
|
|
|
|
# Read review comments (the debate)
|
|
gh api "repos/<org>/<repo>/pulls/<num>/comments?per_page=30" \
|
|
--jq '.[] | select(.body | length > 50) | {user: .user.login, body: (.body | split("\n") | .[0:5] | join("\n"))}'
|
|
|
|
# Read issue comments
|
|
gh api repos/<org>/<repo>/issues/<num>/comments \
|
|
--jq '.[] | {user: .user.login, body: (.body | split("\n") | .[0:6] | join("\n"))}'
|
|
```
|
|
|
|
## Output: Repo Creation & Push
|
|
|
|
Adapt to your git remote:
|
|
|
|
```bash
|
|
# Create repo via API (example — adapt auth and endpoint to your forge)
|
|
TOKEN=$(cat $GIT_TOKEN_PATH)
|
|
curl -s -X POST "$GIT_REMOTE/api/v1/user/repos" \
|
|
-H "Authorization: token $TOKEN" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"name": "<project>-conventions", "auto_init": true, "default_branch": "master", "license": "MIT"}'
|
|
|
|
# Or use your forge's CLI:
|
|
# gh repo create $GIT_ORG/<project>-conventions --public --clone
|
|
# glab project create <project>-conventions
|
|
|
|
# Clone, add content, push
|
|
cd <project>-conventions
|
|
git config user.name "<your-name>"
|
|
git config user.email "<your-email>"
|
|
# ... add files ...
|
|
git add -A && git commit -m "docs: initial conventions from <org>/<project>" && git push
|
|
```
|
|
|
|
## Patterns Mode: Step 1 Discovery Greps
|
|
|
|
Run these per topic to get pattern names + counts. Adapt to your
|
|
language. The goal is a numbered list of patterns to write entries for.
|
|
|
|
### Go
|
|
|
|
```bash
|
|
# Error handling
|
|
grep -rn "^var Err" --include="*.go" | grep -v test | grep -v vendor | grep -v internal | grep -v cmd | wc -l
|
|
grep -rn "fmt.Errorf.*%w" --include="*.go" | grep -v test | grep -v vendor | wc -l
|
|
grep -rn "errors\.Is\|errors\.As" --include="*.go" | grep -v test | grep -v vendor | wc -l
|
|
grep -rn "errors\.Join" --include="*.go" | grep -v test | grep -v vendor | wc -l
|
|
grep -rn "func.*Error() string" --include="*.go" | grep -v test | grep -v vendor | grep -v internal | wc -l
|
|
|
|
# Interfaces
|
|
grep -rn "type.*interface {" --include="*.go" | grep -v test | grep -v vendor | grep -v internal | grep -v cmd | wc -l
|
|
grep -rn "var _.*=" --include="*.go" | grep -v test | grep -v vendor | wc -l
|
|
|
|
# Testing
|
|
grep -rn "t\.Run(" --include="*.go" | grep -v vendor | wc -l
|
|
grep -rn "t\.Helper()" --include="*.go" | grep -v vendor | wc -l
|
|
grep -rn "func Example" --include="*.go" | grep -v vendor | wc -l
|
|
grep -rn "func TestMain" --include="*.go" | grep -v vendor | wc -l
|
|
grep -rn "func Benchmark" --include="*.go" | grep -v vendor | wc -l
|
|
find . -name "testdata" -type d | grep -v vendor | wc -l
|
|
grep -rn "func Fuzz" --include="*.go" | grep -v vendor | wc -l
|
|
|
|
# Concurrency
|
|
grep -rn "sync\.Mutex\|sync\.RWMutex" --include="*.go" | grep -v test | grep -v vendor | grep -v internal | wc -l
|
|
grep -rn "sync\.Once" --include="*.go" | grep -v test | grep -v vendor | grep -v internal | wc -l
|
|
grep -rn "sync\.Pool" --include="*.go" | grep -v test | grep -v vendor | grep -v internal | wc -l
|
|
grep -rn "context\.Context" --include="*.go" | grep -v test | grep -v vendor | grep -v internal | wc -l
|
|
grep -rn "sync\.WaitGroup" --include="*.go" | grep -v test | grep -v vendor | grep -v internal | wc -l
|
|
|
|
# Naming/Style
|
|
grep -rn "^func New" --include="*.go" | grep -v test | grep -v vendor | grep -v internal | grep -v cmd | wc -l
|
|
grep -rn "func.*) Get[A-Z]" --include="*.go" | grep -v test | grep -v vendor | grep -v internal | wc -l
|
|
find . -name "doc.go" | grep -v vendor | grep -v internal | wc -l
|
|
grep -rn "Deprecated:" --include="*.go" | grep -v test | grep -v vendor | wc -l
|
|
|
|
# Configuration
|
|
grep -rn "^func With" --include="*.go" | grep -v test | grep -v vendor | grep -v internal | grep -v cmd | wc -l
|
|
grep -rn "type.*Config struct\|type.*Options struct" --include="*.go" | grep -v test | grep -v vendor | wc -l
|
|
grep -rn "^var Default\|^func Default" --include="*.go" | grep -v test | grep -v vendor | grep -v internal | wc -l
|
|
grep -rn "^func Register" --include="*.go" | grep -v test | grep -v vendor | grep -v internal | wc -l
|
|
|
|
# Performance
|
|
grep -rn "sync\.Pool" --include="*.go" | grep -v test | grep -v vendor | grep -v internal | wc -l
|
|
grep -rn "func.*Append[A-Z]" --include="*.go" | grep -v test | grep -v vendor | grep -v internal | wc -l
|
|
grep -rn "make(\[\].*,.*," --include="*.go" | grep -v test | grep -v vendor | grep -v internal | wc -l
|
|
```
|
|
|
|
### Elixir
|
|
|
|
```bash
|
|
# Error handling
|
|
grep -rn "defexception" --include="*.ex" | wc -l
|
|
grep -rn "{:ok,\|{:error," --include="*.ex" | grep -v test | wc -l
|
|
grep -rn "raise\|reraise" --include="*.ex" | grep -v test | wc -l
|
|
grep -rn "rescue" --include="*.ex" | grep -v test | wc -l
|
|
|
|
# Protocols/Behaviours
|
|
grep -rn "defprotocol" --include="*.ex" | wc -l
|
|
grep -rn "@callback" --include="*.ex" | wc -l
|
|
grep -rn "@behaviour" --include="*.ex" | wc -l
|
|
grep -rn "defimpl" --include="*.ex" | wc -l
|
|
|
|
# Testing
|
|
grep -rn "describe\|test " --include="*.exs" | wc -l
|
|
grep -rn "assert\|refute" --include="*.exs" | wc -l
|
|
grep -rn "setup\|setup_all" --include="*.exs" | wc -l
|
|
grep -rn "ExUnit.CaseTemplate" --include="*.ex" | wc -l
|
|
grep -rn "doctest" --include="*.exs" | wc -l
|
|
|
|
# Process/OTP
|
|
grep -rn "use GenServer\|use Agent\|use Supervisor" --include="*.ex" | wc -l
|
|
grep -rn "GenServer.call\|GenServer.cast" --include="*.ex" | grep -v test | wc -l
|
|
grep -rn "DynamicSupervisor\|Registry" --include="*.ex" | grep -v test | wc -l
|
|
|
|
# Documentation/Types
|
|
grep -rn "@moduledoc" --include="*.ex" | wc -l
|
|
grep -rn "@doc" --include="*.ex" | wc -l
|
|
grep -rn "@spec" --include="*.ex" | wc -l
|
|
grep -rn "@type\|@typep\|@opaque" --include="*.ex" | wc -l
|
|
grep -rn "defguard" --include="*.ex" | wc -l
|
|
|
|
# Macros/Metaprogramming
|
|
grep -rn "defmacro" --include="*.ex" | wc -l
|
|
grep -rn "quote do" --include="*.ex" | wc -l
|
|
grep -rn "__using__\|__before_compile__" --include="*.ex" | wc -l
|
|
```
|
|
|
|
### Rust
|
|
|
|
```bash
|
|
# Error handling
|
|
grep -rn "Result<" --include="*.rs" | grep -v test | wc -l
|
|
grep -rn "impl.*Error" --include="*.rs" | grep -v test | wc -l
|
|
grep -rn "#\[derive.*thiserror" --include="*.rs" | wc -l
|
|
grep -rn "anyhow\|eyre" --include="*.rs" | wc -l
|
|
|
|
# Traits
|
|
grep -rn "pub trait" --include="*.rs" | grep -v test | wc -l
|
|
grep -rn "impl.*for" --include="*.rs" | grep -v test | wc -l
|
|
|
|
# Testing
|
|
grep -rn "#\[test\]" --include="*.rs" | wc -l
|
|
grep -rn "#\[cfg(test)\]" --include="*.rs" | wc -l
|
|
grep -rn "proptest\|quickcheck" --include="*.rs" | wc -l
|
|
|
|
# Async
|
|
grep -rn "async fn" --include="*.rs" | grep -v test | wc -l
|
|
grep -rn "\.await" --include="*.rs" | grep -v test | wc -l
|
|
grep -rn "tokio\|async-std" --include="*.rs" | wc -l
|
|
```
|
|
|
|
### Python
|
|
|
|
```bash
|
|
# Error handling
|
|
grep -rn "raise " --include="*.py" | grep -v test | wc -l
|
|
grep -rn "class.*Exception\|class.*Error" --include="*.py" | wc -l
|
|
grep -rn "except " --include="*.py" | grep -v test | wc -l
|
|
|
|
# Types
|
|
grep -rn "def.*->" --include="*.py" | grep -v test | wc -l
|
|
grep -rn "@dataclass\|@attrs" --include="*.py" | wc -l
|
|
grep -rn "Protocol\|ABC" --include="*.py" | wc -l
|
|
|
|
# Testing
|
|
grep -rn "def test_" --include="*.py" | wc -l
|
|
grep -rn "@pytest.fixture" --include="*.py" | wc -l
|
|
grep -rn "@pytest.mark.parametrize" --include="*.py" | wc -l
|
|
```
|
|
|
|
## Patterns Mode: Step 5 Hyperlink Script
|
|
|
|
```bash
|
|
# Generic hyperlink conversion script
|
|
# Adapt OWNER, REPO, HEAD, and source path format to your language
|
|
|
|
HEAD=$(git rev-parse HEAD)
|
|
BASE="https://github.com/OWNER/REPO/blob/${HEAD}"
|
|
|
|
# Go: `src/path/file.go:NN` or `src/path/file.go` lines NN
|
|
for f in patterns/*.md; do
|
|
sed -i -E "s|\`src/([^:\`]+):([0-9]+)(-[0-9]+)?\`|[src/\\1#L\\2](${BASE}/src/\\1#L\\2)|g" "$f"
|
|
sed -i -E "s|\`src/([^\`]+)\` lines? ([0-9]+)[\x{2013}-]([0-9]+)|[src/\\1#L\\2](${BASE}/src/\\1#L\\2)|g" "$f"
|
|
done
|
|
|
|
# Elixir: `lib/elixir/lib/something.ex` lines NN
|
|
for f in patterns/*.md; do
|
|
sed -i -E "s|\`(lib/[^:\`]+\\.ex[s]?):([0-9]+)(-[0-9]+)?\`|[\\1#L\\2](${BASE}/\\1#L\\2)|g" "$f"
|
|
sed -i -E "s|\`(lib/[^\`]+\\.ex[s]?)\` lines? ([0-9]+)|[\\1#L\\2](${BASE}/\\1#L\\2)|g" "$f"
|
|
done
|
|
|
|
# Rust: `src/path/file.rs:NN`
|
|
for f in patterns/*.md; do
|
|
sed -i -E "s|\`(src/[^:\`]+\\.rs):([0-9]+)(-[0-9]+)?\`|[\\1#L\\2](${BASE}/\\1#L\\2)|g" "$f"
|
|
done
|
|
```
|