Skip to content

fix: give first-run errors working advice - #88

Merged
kvlonge merged 3 commits into
mainfrom
fix/first-run-diagnostics
Nov 6, 2026
Merged

kvlonge merged 3 commits into
mainfrom
fix/first-run-diagnostics

Conversation

@kvlonge

@kvlonge kvlonge commented Nov 5, 2026

Copy link
Copy Markdown
Contributor

Why

These are the first errors a new user hits after launch. Some of them gave advice that doesn't work, or leaked parser internals:

  • SQ0008 help didn't name the divergence and suggested fixes that can't apply.
  • --builtin-policy refused the TIMEZONE=UTC and result-neutral --session parameters that the policy docs say it takes.
  • A misspelt divergence id gave serde's "missing field" message.
  • Schema shape errors said "data did not match any variant of untagged enum".

Changes

  • SQ0008 help names the refused divergence and lists only the fixes that work for this caller's flags, policy and session: a confirmation flag, dropping --strict or --loud-divergences-only, a policy edit, or a UTC session. Refusal::divergence() exposes the id. The registry help and the diagnostics reference are updated.
  • --builtin-policy accepts TIMEZONE and the result-neutral session parameters. It refuses any other parameter by name and points to --policy.
  • Policy parse errors suggest the nearest divergence id ("did you mean") for a misspelling, or name the missing fields of a partial entry.
  • The --help exit-status footer covers check, convert and function, and says census and index exit 0 on refused files and 2 when they can't run.
  • Schema shape errors name the key, relation or column at fault. Syntax errors keep JSON's own location.

Verification

  • New tests: CLI SQ0008 help cases, builtin-session convert cases, schema-shape cases, and policy parse cases for a misspelt id and a partial entry.
  • cargo test passes for sqlquack-core, -policy, -rules, -semantics and sqlquack.
  • make check-ci and fensu check (0 faults) pass. The hygiene scan is clean.

SQ0008 help names the refused divergence and lists only the fixes that
apply to the caller's flags, policy and session. --builtin-policy takes
TIMEZONE and the result-neutral session parameters. Policy errors suggest
the nearest divergence id or name a partial entry's missing fields.
Schema shape errors name the key, relation or column at fault, and the
--help footer documents every command's exit status.
The playground shares the command line's session handling, so the built-in
default now converts under TIMEZONE=UTC and still refuses WEEK_START with
SQ0007.
…tics

# Conflicts:
#	crates/sqlquack-policy/src/policy/constants.rs
#	crates/sqlquack/src/cli/_helpers/evidence.rs

kvlonge commented Nov 6, 2026

Copy link
Copy Markdown
Contributor Author

Gate for landing at exactly 4f52a5bf54d1d2e3930dc69022422ba3fbdad953 (merges main 019bd185; fast-forward):

  • make check-merge RECORDER=0: exit 0
  • make verify-recorded: exit 0. 8,468 cases: 6,778 passed, 994 diverged as expected, 660 refused, 36 typed, 0 pending, 0 unproven, 0 failed; 220 of 220 equivalences and rules verified. Against main: 0 regressions, 0 other changes.
  • Hosted CI (Website) green on this head.
  • Public-repository hygiene scan over the full tree: clean.

@kvlonge
kvlonge merged commit 4f52a5b into main Nov 6, 2026
1 check passed
@kvlonge
kvlonge deleted the fix/first-run-diagnostics branch November 9, 2026 21:31
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.

1 participant