[psteinroe]

Stacked on #899.

A few section marker mistakes went unreported, and some leftovers from #862/#863 remained. With section markers configured, both of these passed without a diagnostic:

create table users (id bigint);   -- before the first marker: dbmate and goose reject the file
-- migrate:up
...
-- Migrate:Down                   -- dbmate's markers are case-sensitive: this is a plain comment

What changed

• A new migrations/sectionMarkers diagnostic (warning) for:

  • statements before the first marker. dbmate fails with "dbmate does not support statements preceding the '-- migrate:up' block" (migration.go), and goose with "must start with '-- +goose Up' annotation";
  • lines that are markers once trimmed or lowercased, but not as written: dbmate's -- Migrate:Up or an indented -- migrate:up, and goose's -- +Goose Down. The tools read these as plain comments, so the file silently has fewer sections. goose matches the annotation itself case-insensitively, but not +goose. An indented -- +goose annotation is different: goose rejects it, and the message says so.

  Both are reported only when sectionMarkers is set. The statement ranges come from a Document::statement_ranges accessor, the same one fix(workspace): put the suppression comment above the statement #910 adds, so whichever merges second has an identical hunk. A marker inside a dollar-quoted body is still not reported: dbmate splits there too, so our sections match what the tool runs.

• plpgsql_check: a query position that isn't a number no longer panics (expect on parse). The diagnostic falls back to the statement's span like other unlocatable issues.

• TypecheckDiagnosticsMapper no longer computes the SQL function signature, which fix(workspace): do not typecheck SQL function bodies with EXPLAIN #863 left in place unused.

• Docs (F15): the rules index marks rules with a fix with 🔧. The linting docs' example of a safe fix now uses requireConcurrentReindex, which is in the recommended preset, instead of CREATE INDEX, which needs a rule that isn't. They also say how to enable the other fixable rules and that 🛠 rules only run in migrationsDir. The migrations guide mentions the new diagnostics.

Tests

Unit tests for the new diagnostics: a statement before the first marker for dbmate and goose, wrong-case and indented dbmate markers, goose +Goose, and no diagnostics without markers. A workspace test checks that they're reported through pull_file_diagnostics. A plpgsql_check unit test covers a non-numeric query position. The mapper tests are updated.

Not covered

• goose ENVSUB (F19).
• Single-quoted SQL function bodies with '' still can't be located (F20). That needs a different way to find the body in the source than find.

Follow-ups: goose ENVSUB is handled by #949. Single-quoted bodies with '' are located by scanner token in #918 and #941 (on the #888 stack).