Skip to content

fix: surface .lashignore and explain the linter's own codes (#58) - #59

Merged
fohara merged 2 commits into
mainfrom
fix/58-lashignore-explain-discoverability
Aug 13, 2026
Merged

fix: surface .lashignore and explain the linter's own codes (#58)#59
fohara merged 2 commits into
mainfrom
fix/58-lashignore-explain-discoverability

Conversation

@fohara

@fohara fohara commented Aug 13, 2026

Copy link
Copy Markdown
Contributor

Closes #58.

Two discoverability failures from the report, both ending at the same place: the user is looking at a diagnostic and the thing that resolves it is documented somewhere they are not.

.lashignore

It already worked — honoured by both walkers, tested, used by this repo — and was reachable from nothing a user reads when a content/ directory starts reporting W_INDEX_ORPHAN once per file.

  • The warning message names it: ... is not referenced in the root index (add it to .lashignore if it is not a task file). The pointer is in the message rather than only the help field because help surfaces only under -v, and one warning per file is exactly when the escape hatch has to be on screen.
  • lash lint --help and the top-level lash --help describe file discovery (.gitignore + .lashignore).
  • README, docs/user-guide.md and docs/error-codes.md each document it.

lash explain

lash explain W_INDEX_ORPHAN and lash explain E_LINK_NOT_FOUND answered "Unknown error code" — the linter's per-rule codes were never connected to the explanation table (the E_LINT_* entries predate them).

  • All 29 missing codes now have entries, including E_SEM_DESC_TOO_LONG and E_NOTE_EXCESSIVE_LENGTH, which only appear at a different severity and so are invisible to a rule's code(). Also added generic E_PARSE, which lint emits directly.
  • A registry test walks register_default_rules and fails if any rule's code has no explanation, so a new rule cannot reintroduce the gap.
  • explain --list was silently dropping every code its if-else prefix chain did not match — all W_ and I_ codes. Replaced with a prefix table plus an explicit "Other Codes" fallback. Order matters: E_INDEX_FILE_MISSING is a cross-file rule, not a database error.
  • Warnings and info codes are labelled Warning: / Info: instead of Error:.
  • Lint's summary now names one of the codes it reported and the lash explain invocation for it — picking a code explain actually knows, so the hint can't create the dead end it exists to prevent.

error_explanations.rs was split into a module directory (parse / syntax / semantic / crossfile / runtime / creation, mirroring the --list grouping); it was already past the repo's 500-line guideline and this change nearly doubled it.

Verification

Reproduced the report end to end: content/a-post.md warns with the .lashignore pointer, printf 'content/\n' > .lashignore clears it, and lash explain W_INDEX_ORPHAN now answers. Full suite, doctests, clippy -D warnings and cargo fmt --check pass; lint/agent-prompt snapshots updated for the new message and footer.

fohara added 2 commits August 13, 2026 09:27
The W_INDEX_ORPHAN message, both --help surfaces and the docs now name
.lashignore, and `lash explain` knows every code lint emits.
rustdoc -D warnings rejects a public doc linking to a private method.
@fohara
fohara merged commit 9fb3cf2 into main Aug 13, 2026
21 checks passed
@fohara
fohara deleted the fix/58-lashignore-explain-discoverability branch August 13, 2026 17:42
@fohara fohara mentioned this pull request Aug 15, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

.lashignore is undiscoverable: not in --help, config, or the W_INDEX_ORPHAN message

1 participant