swiftbutler

# SwiftButler Use `butler` to reduce Swift source into a more manageable working surface. ## Setup Install via Homebrew: ```bash brew install cocoanetics/tap/swiftbutler ``` Verify: ```bash butler --version ``` For local development from a checkout: ```bash swift build .build/debug/butler --version ``` ## Core Rules - Prefer `analyze` when an agent needs API shape, not full implementation details. - Prefer `--format yaml` or `--format json` when the result will be parsed or reused. - Prefer `check` for fast validation loops before `swift build`. - Use `reindent` to normalize indentation in place; choose exactly one of `--spaces <n>` or `--tabs`. - Use `distribute` before targeted edits when a generated file has become too large or noisy. ## Fast Command Map ### Analyze Swift APIs ```bash # Default interface-style output butler analyze Sources/MyModule # Public API only butler analyze Sources/MyModule --visibility public # Recursive YAML output for tooling butler analyze Sources --recursive --format yaml # Write structured output to a file butler analyze Sources --recursive --format yaml --output api.yaml ``` Supported formats: - `interface` - `json` - `yaml` - `markdown` ### Syntax-check Swift quickly ```bash butler check Sources --recursive butler check Sources --recursive --json butler check Sources --recursive --json --pretty butler check Sources --recursive --format markdown --show-fixits ``` ### Reindent with spaces or tabs ```bash # Default: 3 spaces butler reindent Sources --recursive # Explicit spaces butler reindent Sources --recursive --spaces 2 butler reindent Sources --recursive --spaces 4 # Tabs instead of spaces butler reindent Sources --recursive --tabs # Preview without modifying files butler reindent Sources --recursive --tabs --dry-run ``` Notes: - `--spaces <n>` accepts values from `1` to `16`. - `--tabs` and `--spaces <n>` are mutually exclusive. - Without `--tabs`, the default is `--spaces 3`. ### Distribute large files into smaller ones ```bash # Split one large generated file butler distribute Generated.swift # Preview recursive distribution butler distribute Sources/Generated --recursive --dry-run # Write distributed files to a separate directory butler distribute Sources/Generated --recursive --output SplitSources ``` ## When to Use Which Command - Use `analyze` to hand an LLM a compact view of types, functions, properties, and docs. - Use `check` inside generation or repair loops for immediate syntax feedback. - Use `reindent` after generated or patched code has inconsistent indentation. - Use `distribute` when one large Swift file should become declaration-sized files that are easier to inspect and edit.