claw
787ac3b736
- Add safety note on Strict() decoder not expanding aliases recursively, since alias resolution uses the pre-validated AST (finding #1) - Document that ast.Node map keys rely on pointer identity, which holds because all goccy/go-yaml AST types are pointer receivers (finding #2) - Clarify AnchorNode comment: effective depth budget is reduced for anchor+alias pairs, not literally halved (finding #3) - Improve test depth trace comment for accuracy (finding #4) - Add HTML comment in CONVENTIONS.md referencing #91 for the two-step process deviation (finding #5)
53 lines
1.6 KiB
Markdown
53 lines
1.6 KiB
Markdown
# Conventions
|
|
|
|
## Language & Dependencies
|
|
|
|
- Target the latest stable Go release.
|
|
- **STRICT ALLOWLIST:** Only packages listed below may be imported. No exceptions.
|
|
|
|
### Approved Third-Party Packages
|
|
|
|
| Package | Use Case | Scope |
|
|
|---------|----------|-------|
|
|
| `github.com/goccy/go-yaml` | YAML parsing (persona files, config) | production |
|
|
| `github.com/google/go-cmp` | Test comparisons (`cmp.Diff`) | test only |
|
|
|
|
**Any import not in this table or the Go standard library is forbidden.**
|
|
|
|
Transitive dependencies of approved packages are automatically allowed.
|
|
|
|
To request a new dependency:
|
|
1. Open a PR that ONLY updates this table
|
|
2. Requires explicit approval from Aaron
|
|
3. After merge, a separate PR may use the package
|
|
|
|
<!-- Deviation from step 1+3 for go-yaml migration: see #91 for rationale. -->
|
|
|
|
*Enforcement: `scripts/check-deps.sh` parses this table — update only here.*
|
|
|
|
## Error Handling
|
|
|
|
- Return errors; never panic.
|
|
- Wrap errors with context using `fmt.Errorf("context: %w", err)`.
|
|
- Check all error returns.
|
|
|
|
## Testing
|
|
|
|
- Test every exported function.
|
|
- Use `net/http/httptest` for HTTP mocking.
|
|
- Table-driven tests where multiple inputs share the same assertion logic.
|
|
- Integration tests use build tags (`//go:build integration`).
|
|
|
|
## Style
|
|
|
|
- Keep functions short and focused.
|
|
- Prefer early returns over deep nesting.
|
|
- Meaningful variable names — no single-letter names outside loop indices.
|
|
- Comments explain *why*, not *what*.
|
|
|
|
## Process
|
|
|
|
- `go test ./...` must pass before commit.
|
|
- `go vet ./...` must pass before commit.
|
|
- Keep commits atomic and well-described.
|