Nimblesite / Nimblesite/Basilisk
Docs: document the opt-in `strict-annotations` switch (and other opt-in rule toggles) in configuration reference
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 54
- Forks
- 3
- PR merge metrics
- No merged PRs in 30d
Description
Problem
The configuration reference (website/src/docs/configuration.md) tells users that stricter-than-spec rules are opt-in and to "enable them when you want stricter-than-spec checking" — but it never documents the key that actually enables them. There is no mention of strict-annotations (or the [tool.basilisk.uv] toggles) anywhere on the website.
grep -r "strict-annotations" website/ returns nothing; the term only appears in internal docs/specs / docs/plans.
Why this bites users
By default Basilisk runs pure PEP conformance only. The opinionated annotation rules (BSK-E0001–E0005, BSK-E0025, BSK-W0014, BSK-W0050) are gated behind strict-annotations (off by default).
So a user who writes a deliberately "bad", fully-unannotated file and runs basilisk check bad.py gets "All checked. No issues found." and concludes the tool is broken — when in fact the annotation checks are simply off. There's no on-ramp in the public docs pointing them to the switch.
Repro:
```python
bad.py
def process(data):
return data.upper()
```
- Default: `basilisk check bad.py` → "No issues found."
- With `[tool.basilisk]\nstrict-annotations = true`: reports `BSK-E0001` / `BSK-E0002`.
Note: setting `[tool.basilisk.rules] "BSK-E0001" = "error"` does not enable it — that only sets severity. Opt-in gating happens before severity resolution and is keyed on the rule's tag via `strict-annotations`. The docs should make this distinction explicit so users don't reach for the wrong knob.
Proposed fix
Add an "Opt-in Basilisk rules" section to website/src/docs/configuration.md documenting:
strict-annotations(boolean, defaultfalse) — what rule codes it enables.[tool.basilisk.uv]dependency-diagnosticsandstub-suggestions(both boolean, defaultfalse).
Plus:
- A callout: "if
basilisk checkreports no issues on code you expected flagged for missing annotations, this is why." - Add
strict-annotations = trueto the full-config example. - Add a pointer on the Missing Annotations rule page (
website/src/docs/rules/missing-annotations.md) noting these rules are opt-in and how to enable them.
Source of truth for keys/defaults: crates/basilisk-config/src/parse.rs (strict_annotations, uv_dependency_diagnostics, uv_stub_suggestions).
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with website/src/docs/configuration.md and website/src/docs/rules/missing-annotations.md, then check crates/basilisk-config/src/parse.rs for the documented keys and defaults. Document strict-annotations and the two [tool.basilisk.uv] toggles, update the full-config example and callout, and link the missing-annotations rules to their opt-in configuration.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python, rust
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 78/100