Nimblesite / Nimblesite/Basilisk

Docs: document the opt-in `strict-annotations` switch (and other opt-in rule toggles) in configuration reference

Open
#276 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

high-priority
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-E0001E0005, 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, default false) — what rule codes it enables.
  • [tool.basilisk.uv] dependency-diagnostics and stub-suggestions (both boolean, default false).

Plus:

  • A callout: "if basilisk check reports no issues on code you expected flagged for missing annotations, this is why."
  • Add strict-annotations = true to 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.