feat(capabilities): pin public capability surface to a tracked manifest

[nao1215]

Summary

Make sqlode's public capability claims traceable to a single source of truth, so future CHANGELOG / README / doc edits cannot silently drift from what the code actually supports. Introduces a tiny capabilities module, a tracked doc/capabilities.md snapshot, a Gleam test that pins the two against each other, and fixes the CHANGELOG entry that overclaimed :batchone / :batchmany / :batchexec / :copyfrom as shipped features. Closes #365.

Changes

• src/sqlode/capabilities.gleam (new): exports the supported engine, runtime, type-mapping, macro, and placeholder-style lists, plus a split between fully-supported query annotations and the ones parsed for sqlc compatibility but currently rejected by generate.validate_unsupported_annotations. Each list uses model / runtime values so a capability cannot be emitted without the enum variant existing; manifest_markdown/0 renders them into a stable Markdown manifest.
• doc/capabilities.md (new, tracked): the committed snapshot.
• test/capabilities_test.gleam (new): asserts capabilities.manifest_markdown() == doc/capabilities.md contents and prints the expected output on failure so regenerating is a copy/paste. Also pins that every advertised section is present in the render and that no capability list goes empty.
• CHANGELOG.md: replace the line that claimed all ten query annotations were "added" with wording that mirrors generate.gleam and the README's "Planned annotations" section — six are fully supported, four are parsed-but-rejected.

Design Decisions

• Lists live in code, prose lives in Markdown. The capabilities module is not a documentation file; it is plain Gleam that the rest of the compiler could also consume if it wanted to. The Markdown render exists to give humans one place to eyeball the current surface, pinned by the test.
• Snapshot test prints the expected content on failure. Regenerating the file is always "copy everything between the --- expected --- markers into doc/capabilities.md". No external script or separate just capabilities recipe to get out of sync.
• Fully-supported vs. parsed-but-rejected is explicit. sqlc parses :batchone / :batchmany / :batchexec / :copyfrom, and so does sqlode's parser, but generation currently refuses them. Listing both groups with distinct headings matches the README's "Planned annotations" section and makes the gap visible to anyone reading the manifest.
• doc/reference/ stays gitignored. The Issue explicitly flagged it as research material that should be disposable. The tracked public surface now lives at the new doc/capabilities.md instead, so users reading the repo do not see the stale drift.

Limitations

• The manifest only covers claims that are easy to enumerate: engines, runtimes, type mappings, query annotations, macros, placeholder styles. README tables about configuration fields and SQL dialect coverage still rely on hand-written prose; they are unchanged by this PR but can be driven by the same module once we also enumerate them there.
• The test pins exact Markdown output, which means any cosmetic tweak to manifest_markdown forces a doc update. That is intentional — the point of the snapshot is to catch unreviewed changes to the public surface — but it does mean the manifest's wording is part of the test contract.
• doc/reference/specs/sqlc-compatibility.md and doc/reference/design/sqlode-architecture.md are not touched here because doc/reference/ is gitignored. They can still drift locally; the Issue's "treat as disposable" position stands.

Summary by CodeRabbit

Documentation

• Added comprehensive capabilities documentation detailing supported databases (PostgreSQL, MySQL, SQLite), runtimes, type mappings, query annotations, and SQL macros.
• Updated CHANGELOG to clarify which query annotations are fully supported versus planned for future implementation.

[coderabbitai]

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Free

Run ID: e0e5bf59-a12f-4467-b521-e6338fee2b5c

📥 Commits

Reviewing files that changed from the base of the PR and between 7cd7908 and d7343bf.

📒 Files selected for processing (4)

• CHANGELOG.md
• doc/capabilities.md
• src/sqlode/capabilities.gleam
• test/capabilities_test.gleam

---

📝 Walkthrough

Walkthrough

This PR introduces a new capabilities module (src/sqlode/capabilities.gleam) that centralizes sqlode's supported features including databases, runtimes, type mappings, query annotations, macros, and placeholder styles. A generated documentation file enumerates these capabilities, alongside tests that verify consistency and completeness. The CHANGELOG was updated to clarify supported vs. parsed-only query annotations.

Changes

Cohort / File(s)	Summary
Documentation Updates CHANGELOG.md, doc/capabilities.md	Updated changelog to clarify supported query annotations (:one, :many, :exec, :execresult, :execrows, :execlastid fully supported; :batchone, :batchmany, :batchexec, :copyfrom parsed but rejected during generation). Added new generated capabilities manifest documenting supported engines, runtimes, type mappings, macros, and placeholder styles.
Capabilities Module src/sqlode/capabilities.gleam	New module centralizing publicly advertised capabilities with functions to list supported engines, runtimes, type mappings, query commands, macros, and placeholder styles. Includes manifest_markdown() function that renders a deterministic Markdown capability manifest with helper functions for consistent formatting.
Capabilities Tests test/capabilities_test.gleam	Added three tests: verification that generated capabilities manifest matches tracked file, validation that all capability categories return non-empty lists, and structural checks ensuring manifest contains required Markdown section headings.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Poem

🐰 A warren of features, now catalogued with care,
Capabilities listed and documented fair,
From engines to placeholders, all rendered in Markdown's embrace,
Tests verify truth keeps our manifest in place,
Let the world know what sqlode can grace! 🎉

---

Note

🎁 Summarized by CodeRabbit Free

Your organization is on the Free plan. CodeRabbit will generate a high-level summary and a walkthrough for each pull request. For a comprehensive line-by-line review, please upgrade your subscription to CodeRabbit Pro by visiting https://app.coderabbit.ai/login.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}