feat(#20): --@swell.<attr> comment hints on analyzed-single-truth

[wokalski]

Summary

Closes #20 on top of #32 (analyzed-single-truth).

A clean reimplementation of #23 using the new internals — the AST-driven Analyzed pipeline + pg_util helpers already had everything we needed.

How it works

pg_query::scan returns every -- / /* */ as a token with byte positions; pg_query::parse exposes ResTarget.location per target-list entry. A comment attaches to the column whose ResTarget.location is the largest one less-or-equal to the comment's start. String literals + dollar-quoted bodies are naturally excluded by the scanner.

Attributes

• nullable — force nullable: true
• nonnullable / nonnull / notnull — force nullable: false
• type=T or type: T — verbatim TS type

Multiple comments stack on the same column. Works on SELECT target lists and DML RETURNING lists. The existing alias-suffix form (col! / col?) still parses for back-compat; comment hints take precedence.

Wired in

When any hint applies the analyzer drops the base-column table_ref for that column, so the override surfaces verbatim in the emitted .d.ts instead of being masked by an indexed-access (Table[\"col\"]) lookup.

SELECT email --@swell.nullable
FROM billing.users WHERE id = \$1;
-- → { email: string | null }   (instead of BillingUsers[\"email\"] | null)

SELECT metadata /*@swell.type=UserMeta*/ AS meta
FROM billing.users WHERE id = \$1;
-- → { meta: UserMeta }

Test plan

• 11 unit tests in comment_hints.rs covering line/block forms, the type= and type: separators, stacked + comma-separated attrs, attribution to the preceding column, RETURNING lists, parse-failure tolerance, and string-literal isolation.
• 7 corpus tests in billing.md exercising the same matrix end-to-end against live Postgres.

🤖 Generated with Claude Code