feat: schema-aware semantic diagnostics (unknown tables/columns, ambiguous columns) (#163)

## Summary

Linting was syntax-only, even though the extension already accepts a
full `SQLNamespace` schema (used by hover). This adds
**`sqlSemanticLinter`**, a schema-aware linter that reports the
highest-value SQL diagnostics:

- **Unknown table** — `FROM`/`JOIN` references and DML targets
(`INSERT`/`UPDATE`/`DELETE`) resolved against the namespace.
Case-insensitive; qualified paths like `mydb.users` traverse nested
namespaces; CTE names and DDL targets (`CREATE TABLE x` defines `x`) are
skipped.
- **Unknown column** — qualified refs (`u.name`, `users.name`) resolved
through a per-scope alias map; unqualified refs checked only when the
statement reads exactly one known table.
- **Ambiguous column** — unqualified refs that exist in 2+ referenced
tables (suppressed for `USING`/`NATURAL` joins).

Severities are configurable per check (`"error" | "warning" | "off"`,
default `"warning"`), and semantic diagnostics carry `source:
"sql-schema"` vs. `"sql-parser"` for syntax errors.

## False positives are fatal to trust

The analyzer builds proper query scopes from the AST and skips anything
not confidently resolvable, preferring under-reporting:

- checks only run on statements that parse cleanly (no semantic noise on
top of syntax errors)
- CTE outputs, FROM-subquery results, and table functions are opaque —
their columns are never guessed
- unqualified columns are never checked inside correlated subqueries
(they may legally resolve to the outer scope)
- SELECT-list aliases referenced in `ORDER BY`/`GROUP BY` are skipped
- unresolved qualifiers (possible outer-scope aliases) are skipped
- under-qualified names match tables nested deeper in the schema, so
`FROM users` with schema `{mydb: {users}}` never flags
- without a schema (or with an empty placeholder while it lazily loads
upstream) the linter is fully inert — zero parser calls

## Shared schema facet

Also introduces **`sqlSchemaFacet`** so the schema is defined once for
hover + semantic linting (and future completion) instead of per
sub-extension. `sqlExtension` gains top-level `schema`,
`enableSemanticLinting` (default true; inert without a schema), and
`semanticLinterConfig`. Per-extension `schema` config still overrides
for back-compat.

## Implementation note on positions

The plan called for `parseOptions: { includeLocations: true }`, but
node-sql-parser does not attach `loc` to `column_ref`/table nodes even
with it enabled (verified empirically; only some expression wrappers get
it). Diagnostics are instead positioned by word-bounded,
case-insensitive text search within the statement's document range —
searching the original doc text keeps positions exact even around inline
comments (covered by a test).

## Testing

- 24 new tests in `src/sql/__tests__/semantic-diagnostics.test.ts`
covering all checks, CTE/alias/subquery/correlation scoping, nested
namespaces, `self/children` namespaces, Completion-object columns,
severity overrides, facet fallback/precedence, inertness gating, and
diagnostic positioning
- `pnpm test`: 334 passed | 1 expected fail (pre-existing)
- `pnpm run typecheck` and `pnpm exec oxlint`: clean (also fixed the one
pre-existing oxlint warning in `extension.ts`)
- demo updated to exercise semantic linting (`pnpm run demo` builds)

<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Add schema-aware SQL linting that flags unknown tables/columns and
ambiguous columns, shared with hover via a new schema facet. Introduces
`sqlSemanticLinter` and `sqlSchemaFacet`, and adds top-level `schema`
and `enableSemanticLinting` options to `sqlExtension`; also refines
parser/analyzer inheritance to avoid dialect mismatches.

- **New Features**
- `sqlSemanticLinter`: reports unknown tables, unknown columns, and
ambiguous unqualified columns; per-check severity (`error` | `warning` |
`off`, default `warning`); diagnostics use `source: "sql-schema"`; skips
unresolvable cases to avoid false positives.
- `sqlSchemaFacet`: shared schema for hover and semantic lint; supports
function sources; per-feature `schema` still overrides; exported
`resolveSqlSchema`.
- `sqlExtension`: new `schema`, `enableSemanticLinting` (default true;
inert without a schema), and `semanticLinterConfig`; hover falls back to
the shared schema; semantic linter reuses `linterConfig.parser` and
inherits `linterConfig.structureAnalyzer` only when the linter parser is
inherited, preventing analyzer/dialect mismatches.

- **Migration**
- If you already pass a schema to hover, move it to `sqlExtension({
schema })` to share across features.
- To enable semantic linting, supply a schema and optionally set
severities via `semanticLinterConfig.severity`.
  - To disable, set `enableSemanticLinting: false`.

<sup>Written for commit fb7ca9e.
Summary will update on new commits.</sup>

<a
href="https://cubic.dev/pr/marimo-team/codemirror-sql/pull/163?utm_source=github"
target="_blank" rel="noopener noreferrer"
data-no-image-dialog="true"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"><source
media="(prefers-color-scheme: light)"
srcset="https://www.cubic.dev/buttons/review-in-cubic-light.svg"><img
alt="Review in cubic"
src="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"></picture></a>

<!-- End of auto-generated description by cubic. -->

Author: mscolnick

README.md

@@ -5,6 +5,7 @@ A CodeMirror extension for SQL linting and visual gutter indicators. Built by an
 ## Features
 
 - ⚡ **Real-time validation** - Per-statement SQL syntax checking as you type, with detailed error messages for every broken statement
+- 🧠 **Schema-aware linting** - Warns about unknown tables, unknown columns, and ambiguous column references based on your schema
 - 🎨 **Visual gutter** - Color-coded statement indicators and error highlighting
 - 💡 **Hover tooltips** - Schema info, keywords, and column details on hover
 - 🔮 **CTE autocomplete** - Auto-complete support for CTEs
@@ -47,6 +48,8 @@ const editor = new EditorView({
       autocomplete: cteCompletionSource,
     }),
     sqlExtension({
+      // Shared by hover tooltips and semantic linting
+      schema: schema,
       linterConfig: {
         delay: 250, // Validation delay in ms
       },
@@ -57,7 +60,6 @@ const editor = new EditorView({
       },
       enableHover: true,
       hoverConfig: {
-        schema: schema,
         hoverTime: 300,
         enableKeywords: true,
         enableTables: true,
@@ -69,6 +71,40 @@ const editor = new EditorView({
 });
 ```
 
+### Schema-aware semantic linting
+
+When a schema is provided (via the top-level `schema` option, the
+`sqlSchemaFacet`, or `semanticLinterConfig.schema`), queries are validated
+against it: unknown tables, unknown columns, and ambiguous column references
+are reported as warnings (configurable per check). Without a schema the
+semantic linter is inert.
+
+```ts
+import { EditorView } from "codemirror";
+import { sqlSemanticLinter } from "@marimo-team/codemirror-sql";
+
+const editor = new EditorView({
+  extensions: [
+    sqlSemanticLinter({
+      schema: { users: ["id", "name"], posts: ["id", "user_id"] },
+      severity: {
+        unknownTable: "error", // "error" | "warning" | "off" (default: "warning")
+        unknownColumn: "warning",
+        ambiguousColumn: "warning",
+      },
+    }),
+  ],
+  parent: document.querySelector("#editor"),
+});
+```
+
+Checks only run on statements that parse cleanly, and skip anything that
+can't be confidently resolved (CTE outputs, subquery results, aliases from
+outer scopes), preferring under-reporting over false positives. Semantic
+diagnostics carry `source: "sql-schema"`; syntax diagnostics use
+`source: "sql-parser"`. If the schema is provided as a function, it is called
+on every lint pass and should be cheap/memoized.
+
 ## Additional Dialects
 
 This extension adds support for additional dialects:

_typos.toml

@@ -7,4 +7,6 @@ extend-exclude = [
   "src/data/duckdb-keywords.json",
   # Contains intentionally misspelled SQL (e.g. SELCT) to trigger parse errors
   "src/sql/__tests__/diagnostics.test.ts",
+  # Contains intentionally misspelled identifiers (e.g. usres) to trigger schema diagnostics
+  "src/sql/__tests__/semantic-diagnostics.test.ts",
 ]

demo/index.ts

@@ -134,11 +134,18 @@ function initializeEditor() {
     databaseField,
     baseSqlCompartment.of(baseSqlExtension(defaultDialect)),
     sqlExtension({
+      // Shared schema for hover tooltips and schema-aware linting
+      schema: schema,
       // Linter extension configuration
       linterConfig: {
         delay: 250, // Delay before running validation
         parser,
       },
+      // Schema-aware linting (unknown tables/columns, ambiguous columns)
+      semanticLinterConfig: {
+        delay: 250,
+        parser,
+      },
 
       // Gutter extension configuration
       gutterConfig: {

src/__tests__/index.test.ts

@@ -14,9 +14,12 @@ describe("index.ts exports", () => {
         "SqlStructureAnalyzer",
         "cteCompletionSource",
         "defaultSqlHoverTheme",
+        "resolveSqlSchema",
         "sqlExtension",
         "sqlHover",
         "sqlLinter",
+        "sqlSchemaFacet",
+        "sqlSemanticLinter",
         "sqlStructureGutter",
       ]
     `);

src/index.ts

@@ -1,6 +1,6 @@
 export { cteCompletionSource } from "./sql/cte-completion-source.js";
 export { type SqlLinterConfig, sqlLinter } from "./sql/diagnostics.js";
-export { sqlExtension } from "./sql/extension.js";
+export { type SqlExtensionConfig, sqlExtension } from "./sql/extension.js";
 export type {
   KeywordTooltipData,
   NamespaceTooltipData,
@@ -15,6 +15,12 @@ export {
   type ParserOption,
   type SupportedDialects,
 } from "./sql/parser.js";
+export { resolveSqlSchema, type SqlSchemaSource, sqlSchemaFacet } from "./sql/schema-facet.js";
+export {
+  type SemanticSeverity,
+  type SqlSemanticLinterConfig,
+  sqlSemanticLinter,
+} from "./sql/semantic-diagnostics.js";
 export type { SqlStatement } from "./sql/structure-analyzer.js";
 export { SqlStructureAnalyzer } from "./sql/structure-analyzer.js";
 export type { SqlGutterConfig } from "./sql/structure-extension.js";

src/sql/__tests__/extension.test.ts

@@ -1,5 +1,7 @@
+import { EditorState } from "@codemirror/state";
 import { describe, expect, it } from "vitest";
 import { sqlExtension } from "../extension.js";
+import { sqlSchemaFacet } from "../schema-facet.js";
 
 describe("sqlExtension", () => {
   it("should return an array of extensions with default config", () => {
@@ -35,12 +37,37 @@ describe("sqlExtension", () => {
   it("should handle all features disabled", () => {
     const extensions = sqlExtension({
       enableLinting: false,
+      enableSemanticLinting: false,
       enableGutterMarkers: false,
       enableHover: false,
     });
     expect(extensions).toEqual([]);
   });
 
+  it("should register the shared schema facet when a schema is provided", () => {
+    const schema = { users: ["id"] };
+    const withSchema = sqlExtension({
+      schema,
+      enableLinting: false,
+      enableSemanticLinting: false,
+      enableGutterMarkers: false,
+      enableHover: false,
+    });
+    expect(withSchema).toHaveLength(1);
+
+    const state = EditorState.create({ extensions: withSchema });
+    expect(state.facet(sqlSchemaFacet)).toBe(schema);
+
+    const withoutSchema = sqlExtension({
+      enableLinting: false,
+      enableSemanticLinting: false,
+      enableGutterMarkers: false,
+      enableHover: false,
+    });
+    const emptyState = EditorState.create({ extensions: withoutSchema });
+    expect(emptyState.facet(sqlSchemaFacet)).toBeNull();
+  });
+
   it("should pass config objects to individual extensions", () => {
     const linterConfig = { delay: 500 };
     const gutterConfig = { backgroundColor: "#ff0000" };