feat: unqualified column completion inferred from the FROM clause (#165)

## Summary

Typing a bare identifier prefix now completes columns of the tables
referenced in the current statement's `FROM`/`JOIN` clauses — even when
the schema defines many tables:

```sql
SELECT id, name, email
FROM users
WHERE active = true
ORDER BY created_at DESC;
```

`SELECT e` → `email`, `ORDER BY cre` → `created_at`, because `FROM
users` is in the statement.

Previously unqualified column completion was delegated entirely to
`@codemirror/lang-sql`'s `schemaCompletionSource`, which only offers
top-level columns when a single `defaultTable` is configured —
impossible with 2+ tables/schemas.

## Changes

- **New `unqualifiedColumnCompletionSource({ schema?, parser?,
contextAnalyzer? })`** (`src/sql/column-completion-source.ts`):
- Matches bare identifier prefixes; skips qualified paths (after a dot —
the alias source's territory) and table-name positions (right after
`FROM`/`JOIN`/`INTO`/`UPDATE`/`TABLE`)
- Scopes to the statement under the cursor; reuses
`QueryContextAnalyzer` (AST walk + regex fallback, so it works mid-edit
on unparsable SQL)
- Offers the union of all FROM/JOIN tables' columns with `detail:
"column of <table>"`; duplicate names across joins appear once
- CTEs in FROM resolve to their declared/inferred columns;
under-qualified tables that are ambiguous across schemas yield nothing
rather than wrong columns
- Empty prefix completes only on explicit (Ctrl-Space) requests; columns
get a small boost to rank just above keywords
- **`src/sql/completion-utils.ts`**: `resolveSchema` /
`findTableColumns` / `toCompletion` lifted unchanged from the alias
source and shared by both (no behavior change to
`aliasColumnCompletionSource`)
- Exported from `src/index.ts`, registered in the demo (sharing one
`QueryContextAnalyzer` across completion sources), documented in README

## Test plan

- 18 new tests in `src/sql/__tests__/column-completion-source.test.ts`:
the motivating multi-table scenario, ORDER BY, joins + per-table
details, dedup, dot/table-position guards, empty prefix, mid-edit SQL,
multi-statement scoping, aliased/quoted/nested tables, ambiguity, CTEs,
facet fallback, boosts
- `pnpm test` (412 passed), `pnpm run typecheck`, `pnpm exec oxlint`,
`pnpm run demo` all clean

<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Adds FROM-aware autocomplete for bare column prefixes. Typing
unqualified text like SELECT e now suggests columns from tables in the
current statement, including joins and CTEs, with better multi‑schema
support than `@codemirror/lang-sql`.

- **New Features**
- Add `unqualifiedColumnCompletionSource({ schema?, parser?,
contextAnalyzer? })`.
- Completes in SELECT/WHERE/ORDER BY; skips after a dot and in
table-name positions; empty prefix only on explicit request.
- Unions columns from FROM/JOIN tables; de-dupes; shows "column of
<table>"; supports CTE columns; small boost over keywords; falls back to
`sqlSchemaFacet`; preserves schema-provided boosts.

- **Bug Fixes**
  - No suggestions inside string literals or comments.
- Skip in comma-continued FROM table lists; still completes after commas
in SELECT/GROUP BY.
- Correctly resolves quoted table names containing dots (e.g.
"my.table").

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

<a
href="https://cubic.dev/pr/marimo-team/codemirror-sql/pull/165?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

@@ -10,6 +10,7 @@ A CodeMirror extension for SQL linting and visual gutter indicators. Built by an
 - 💡 **Hover tooltips** - Schema info, keywords, and column details on hover
 - 🔮 **CTE autocomplete** - Statement-scoped completion of CTE names and their output columns
 - 🏷️ **Alias resolution** - Hover and completion understand table aliases (`SELECT u.name FROM users u`)
+- 📇 **FROM-aware column completion** - Unqualified prefixes complete the columns of the tables in the statement's FROM clause (`SELECT e` -> `email` with `FROM users`), even with many tables in the schema
 - 🧭 **Navigation** - Go-to-definition, reference highlighting, and rename for CTEs and aliases
 - 🎯 **Query-aware resolution** - Context-sensitive schema and column suggestions
 - 🔍 **Additional dialects** - DuckDB, BigQuery, Dremio
@@ -30,7 +31,7 @@ pnpm add @marimo-team/codemirror-sql
 ```ts
 import { sql, StandardSQL } from "@codemirror/lang-sql";
 import { basicSetup, EditorView } from "codemirror";
-import { sqlExtension, cteCompletionSource, aliasColumnCompletionSource } from "@marimo-team/codemirror-sql";
+import { sqlExtension, cteCompletionSource, aliasColumnCompletionSource, unqualifiedColumnCompletionSource } from "@marimo-team/codemirror-sql";
 
 const schema = {
   users: ["id", "name", "email", "active"],
@@ -53,6 +54,10 @@ const editor = new EditorView({
       // Complete `u.` -> columns of `users` in `SELECT ... FROM users u`
       autocomplete: aliasColumnCompletionSource({ schema }),
     }),
+    StandardSQL.language.data.of({
+      // Complete `SELECT e` -> `email` because `FROM users` is in the statement
+      autocomplete: unqualifiedColumnCompletionSource({ schema }),
+    }),
     sqlExtension({
       // Shared by hover tooltips and semantic linting
       schema: schema,

demo/index.ts

@@ -9,8 +9,10 @@ import {
   DefaultSqlTooltipRenders,
   defaultSqlHoverTheme,
   NodeSqlParser,
+  QueryContextAnalyzer,
   type SupportedDialects,
   sqlExtension,
+  unqualifiedColumnCompletionSource,
 } from "../src/index.js";
 import { tableTooltipRenderer } from "./custom-renderers.js";
 import { defaultSqlDoc, schema } from "./data.js";
@@ -127,6 +129,8 @@ function initializeEditor() {
       };
     },
   });
+  // Shared between the completion sources so each edit is analyzed once
+  const contextAnalyzer = new QueryContextAnalyzer(parser);
 
   const extensions = [
     basicSetup,
@@ -187,7 +191,11 @@ function initializeEditor() {
     }),
     defaultDialect.language.data.of({
       // Complete `u.` -> columns of `users` in `SELECT ... FROM users u`
-      autocomplete: aliasColumnCompletionSource({ schema, parser }),
+      autocomplete: aliasColumnCompletionSource({ schema, parser, contextAnalyzer }),
+    }),
+    defaultDialect.language.data.of({
+      // Complete `SELECT e` -> `email` because `FROM users` is in the statement
+      autocomplete: unqualifiedColumnCompletionSource({ schema, parser, contextAnalyzer }),
     }),
     // Custom theme for better SQL editing
     EditorView.theme({

src/__tests__/index.test.ts

@@ -33,6 +33,7 @@ describe("index.ts exports", () => {
         "sqlSchemaFacet",
         "sqlSemanticLinter",
         "sqlStructureGutter",
+        "unqualifiedColumnCompletionSource",
       ]
     `);
   });

src/index.ts

@@ -2,6 +2,10 @@ export {
   type AliasCompletionConfig,
   aliasColumnCompletionSource,
 } from "./sql/alias-completion-source.js";
+export {
+  type ColumnCompletionConfig,
+  unqualifiedColumnCompletionSource,
+} from "./sql/column-completion-source.js";
 export {
   createCteCompletionSource,
   type CteCompletionConfig,

src/sql/__tests__/column-completion-source.test.ts

@@ -0,0 +1,256 @@
+import { CompletionContext, type CompletionResult } from "@codemirror/autocomplete";
+import type { SQLNamespace } from "@codemirror/lang-sql";
+import { EditorState } from "@codemirror/state";
+import { describe, expect, it } from "vitest";
+import { unqualifiedColumnCompletionSource } from "../column-completion-source.js";
+import { sqlSchemaFacet } from "../schema-facet.js";
+
+const schema: SQLNamespace = {
+  users: ["id", "username", "email"],
+  orders: [
+    { label: "order_id", detail: "Order ID", type: "property" },
+    "total",
+  ],
+};
+
+const nestedSchema: SQLNamespace = {
+  mydb: {
+    users: ["id", "username"],
+  },
+};
+
+async function complete(
+  doc: string,
+  opts: {
+    schema?: SQLNamespace;
+    pos?: number;
+    explicit?: boolean;
+    facetSchema?: SQLNamespace;
+  } = {},
+): Promise<CompletionResult | null> {
+  const source = unqualifiedColumnCompletionSource(
+    opts.schema === undefined && opts.facetSchema !== undefined ? {} : { schema: opts.schema },
+  );
+  const state = EditorState.create({
+    doc,
+    extensions: opts.facetSchema !== undefined ? [sqlSchemaFacet.of(opts.facetSchema)] : [],
+  });
+  const pos = opts.pos ?? doc.length;
+  const context = new CompletionContext(state, pos, opts.explicit ?? false);
+  return (await source(context)) as CompletionResult | null;
+}
+
+function labels(result: CompletionResult | null): string[] {
+  return (result?.options ?? []).map((option) => option.label);
+}
+
+describe("unqualifiedColumnCompletionSource", () => {
+  it("offers the FROM table's columns for a bare prefix", async () => {
+    const result = await complete("SELECT e FROM users", {
+      schema,
+      pos: "SELECT e".length,
+    });
+    expect(labels(result)).toEqual(["id", "username", "email"]);
+    expect(result?.from).toBe("SELECT ".length);
+    expect(result?.options.every((option) => option.type === "property")).toBe(true);
+  });
+
+  it("completes in ORDER BY position", async () => {
+    const doc = "SELECT id FROM users ORDER BY user";
+    const result = await complete(doc, { schema, pos: doc.length });
+    expect(labels(result)).toContain("username");
+    expect(result?.from).toBe(doc.indexOf("user", doc.indexOf("ORDER BY")));
+  });
+
+  it("only offers columns of the referenced table when the schema has many", async () => {
+    const result = await complete("SELECT e FROM users", {
+      schema,
+      pos: "SELECT e".length,
+    });
+    expect(labels(result)).not.toContain("total");
+    expect(labels(result)).not.toContain("order_id");
+  });
+
+  it("offers the union of all joined tables' columns with per-table details", async () => {
+    const doc = "SELECT  FROM users u JOIN orders o ON u.id = o.user_id";
+    const result = await complete(doc, {
+      schema,
+      pos: "SELECT ".length,
+      explicit: true,
+    });
+    expect(labels(result)).toEqual(["id", "username", "email", "order_id", "total"]);
+    expect(result?.options.find((option) => option.label === "email")?.detail).toBe(
+      "column of users",
+    );
+    expect(result?.options.find((option) => option.label === "total")?.detail).toBe(
+      "column of orders",
+    );
+    // Schema-provided details are preserved
+    expect(result?.options.find((option) => option.label === "order_id")?.detail).toBe(
+      "Order ID",
+    );
+  });
+
+  it("offers a duplicate column name once, from the first table", async () => {
+    const dupSchema: SQLNamespace = { a: ["id", "x"], b: ["id", "y"] };
+    const doc = "SELECT  FROM a JOIN b ON a.id = b.id";
+    const result = await complete(doc, { schema: dupSchema, pos: "SELECT ".length, explicit: true });
+    expect(labels(result)).toEqual(["id", "x", "y"]);
+    expect(result?.options.find((option) => option.label === "id")?.detail).toBe("column of a");
+  });
+
+  it("returns null after a dot", async () => {
+    const result = await complete("SELECT u. FROM users u", {
+      schema,
+      pos: "SELECT u.".length,
+      explicit: true,
+    });
+    expect(result).toBeNull();
+  });
+
+  it("returns null in table-name position", async () => {
+    expect(await complete("SELECT id FROM use", { schema, pos: "SELECT id FROM use".length })).toBeNull();
+    const doc = "SELECT id FROM users JOIN ord";
+    expect(await complete(doc, { schema, pos: doc.length })).toBeNull();
+  });
+
+  it("returns null in a comma-continued FROM table list", async () => {
+    expect(await complete("SELECT id FROM users, ord", { schema })).toBeNull();
+    expect(await complete("SELECT id FROM users u, ord", { schema })).toBeNull();
+    expect(await complete("SELECT id FROM users AS u, orders o, ord", { schema })).toBeNull();
+  });
+
+  it("still completes after commas in non-FROM clauses", async () => {
+    const groupBy = "SELECT id FROM users GROUP BY id, user";
+    expect(labels(await complete(groupBy, { schema }))).toContain("username");
+    const selectList = "SELECT id, e FROM users";
+    expect(labels(await complete(selectList, { schema, pos: "SELECT id, e".length }))).toContain(
+      "email",
+    );
+  });
+
+  it("returns null inside string literals and comments", async () => {
+    const inString = "SELECT id FROM users WHERE name = 'em";
+    expect(await complete(inString, { schema })).toBeNull();
+    const inLineComment = "SELECT id FROM users -- em";
+    expect(await complete(inLineComment, { schema })).toBeNull();
+    const inBlockComment = "SELECT id FROM users /* em";
+    expect(await complete(inBlockComment, { schema })).toBeNull();
+  });
+
+  it("requires a prefix unless the request is explicit", async () => {
+    const doc = "SELECT  FROM users";
+    expect(await complete(doc, { schema, pos: "SELECT ".length })).toBeNull();
+    expect(labels(await complete(doc, { schema, pos: "SELECT ".length, explicit: true }))).toEqual([
+      "id",
+      "username",
+      "email",
+    ]);
+  });
+
+  it("returns null when the statement has no FROM clause yet", async () => {
+    const result = await complete("SELECT em", { schema, pos: "SELECT em".length });
+    expect(result).toBeNull();
+  });
+
+  it("still completes while the statement is mid-edit (unparsable)", async () => {
+    const result = await complete("SELECT em FROM users WHERE", {
+      schema,
+      pos: "SELECT em".length,
+    });
+    expect(labels(result)).toEqual(["id", "username", "email"]);
+  });
+
+  it("scopes tables to the statement containing the cursor", async () => {
+    const doc = "SELECT id FROM users; SELECT t FROM orders";
+    const result = await complete(doc, { schema, pos: doc.indexOf("t FROM orders") + 1 });
+    expect(labels(result)).toEqual(["order_id", "total"]);
+  });
+
+  it("completes columns of an aliased table", async () => {
+    const result = await complete("SELECT e FROM users u", {
+      schema,
+      pos: "SELECT e".length,
+    });
+    expect(labels(result)).toEqual(["id", "username", "email"]);
+  });
+
+  it("resolves tables nested in the schema", async () => {
+    const qualified = await complete("SELECT user FROM mydb.users", {
+      schema: nestedSchema,
+      pos: "SELECT user".length,
+    });
+    expect(labels(qualified)).toEqual(["id", "username"]);
+
+    const underQualified = await complete("SELECT user FROM users", {
+      schema: nestedSchema,
+      pos: "SELECT user".length,
+    });
+    expect(labels(underQualified)).toEqual(["id", "username"]);
+  });
+
+  it("returns null when an under-qualified table is ambiguous across schemas", async () => {
+    const ambiguousSchema: SQLNamespace = {
+      db1: { users: ["id"] },
+      db2: { users: ["email"] },
+    };
+    const result = await complete("SELECT i FROM users", {
+      schema: ambiguousSchema,
+      pos: "SELECT i".length,
+    });
+    expect(result).toBeNull();
+  });
+
+  it("offers CTE columns when the FROM table is a CTE", async () => {
+    const doc = "WITH recent AS (SELECT x, y FROM logs) SELECT x FROM recent";
+    const result = await complete(doc, { schema, pos: doc.indexOf("x FROM recent") + 1 });
+    const resultLabels = labels(result);
+    expect(resultLabels).toContain("x");
+    expect(resultLabels).toContain("y");
+    expect(result?.options.find((option) => option.label === "x")?.detail).toBe(
+      "column of recent",
+    );
+  });
+
+  it("completes columns of a quoted table name", async () => {
+    const quotedSchema: SQLNamespace = { "User Table": ["id", "full_name"] };
+    const doc = 'SELECT full FROM "User Table"';
+    const result = await complete(doc, { schema: quotedSchema, pos: "SELECT full".length });
+    expect(labels(result)).toEqual(["id", "full_name"]);
+  });
+
+  it("completes columns of a quoted table name containing a dot", async () => {
+    const dottedSchema: SQLNamespace = { "my.table": ["id", "email"] };
+    const doc = 'SELECT e FROM "my.table"';
+    const result = await complete(doc, { schema: dottedSchema, pos: "SELECT e".length });
+    expect(labels(result)).toEqual(["id", "email"]);
+  });
+
+  it("falls back to the sqlSchemaFacet when no schema is configured", async () => {
+    const result = await complete("SELECT e FROM users", {
+      facetSchema: schema,
+      pos: "SELECT e".length,
+    });
+    expect(labels(result)).toEqual(["id", "username", "email"]);
+  });
+
+  it("returns null when the table is not in the schema", async () => {
+    const result = await complete("SELECT x FROM missing", {
+      schema,
+      pos: "SELECT x".length,
+    });
+    expect(result).toBeNull();
+  });
+
+  it("boosts columns while preserving schema-provided boosts", async () => {
+    const boostedSchema: SQLNamespace = {
+      users: ["id", { label: "email", boost: 5 }],
+    };
+    const result = await complete("SELECT e FROM users", {
+      schema: boostedSchema,
+      pos: "SELECT e".length,
+    });
+    expect(result?.options.find((option) => option.label === "id")?.boost).toBe(1);
+    expect(result?.options.find((option) => option.label === "email")?.boost).toBe(5);
+  });
+});