Docs Phase 2: structured reference for formats, engines, and data types

[BorisTyshkevich]

Parent: #60
Depends on: #313

Goal

Extend version-exact reference documentation to structured non-function entities:

• output formats;
• table engines;
• database engines;
• data type families.

Add pure SQL-context routing, CM6 hover/F1 integration, completion details, and explicit schema-surface actions. Broad system.documentation Markdown coverage remains #315.

Version and capability policy

Do not use a fixed 26.6 gate for any Phase 2 source. These tables and their documentation columns vary independently across ClickHouse releases and builds.

For each source, actual table/column availability is authoritative:

• inspect system.columns once per connection or perform one silent best-effort probe;
• build the SELECT list only from confirmed columns;
• degrade optional fields independently;
• cache missing table, denied access, or incompatible required shape as unavailable for the connection;
• keep transient auth/network failures retryable;
• do not infer full support merely because the server is 26.6+;
• do not skip a usable source merely because the server is older than 26.6.

The hard pre-26.6 short-circuit applies only to system.documentation in #315.

Entity contract

Extend the shared types from #313:

type DocKind =
  | 'function'
  | 'aggregate-function'
  | 'format'
  | 'table-engine'
  | 'database-engine'
  | 'data-type';

Every loader uses the shared found | missing | unavailable contract and generation-safe kind:name cache. Unknown fields are ignored safely; UI consumes normalized entries only.

Structured sources

Kind	Source	Fields when available
format	system.formats	description, examples, introduced_in, related, capability flags
table-engine	system.table_engines	supported documentation fields exposed by the server
database-engine	system.database_engines	supported documentation fields exposed by the server
data-type	system.data_type_families	supported documentation fields exposed by the server

system.formats has no syntax column. Never probe, query, or fabricate it.

Do not hard-code row counts or fixed field sets.

Normalization

Add source-specific pure normalizers. Preserve canonical casing, examples, introduced version, and related values. Represent absent fields as absent. Convert resolvable related names to targets and retain unresolved names as text chips. Never expose raw rows to CM6 or DOM code.

Pure SQL-context classifier

Extend src/core/doc-context.ts. It receives SQL, caret position, and optional precomputed lexical/syntax information; it returns ranked targets and issues no SQL.

Required contexts:

• top-level FORMAT Name, including either FORMAT/SETTINGS order, without confusing format();
• table ENGINE = Name and parameterized engines;
• database ENGINE = Name in database DDL;
• strong type positions: column definitions, CAST(... AS Type), x::Type, and {name:Type};
• nested types resolve the innermost type token under the caret.

Ignore strings, comments, quoted identifiers, nested false positives, and weak arbitrary identifiers.

CM6 integration

Reuse #313 hover, completion info, F1 command, stale async guards, and the same openDocEntry() action.

• Hover remains compact.
• F1 uses the strongest classifier result.
• Format completion info can open format docs.
• No metadata query runs during ordinary typing; load only when tooltip/info is materialized or pane is explicitly opened.
• Function documentation must not regress.

Schema-surface actions

Add keyboard-accessible documentation actions where engine names and column types are displayed.

• Open engine reference for table/database engine surfaces.
• Open type reference for schema tree/detail type surfaces.
• Preserve existing single-click, double-click, and Shift-click behavior.
• Opening docs must not mutate editor text or close the schema graph.
• Unavailable docs hide or disable the action without a toast.
• Restore initiating focus where possible.

Pane rendering

Extend the #313 pane with kind badge, canonical name, description, actual syntax only when exposed, examples, introduced version, related actions, and useful format capability facts.

Do not fabricate format syntax. Related navigation replaces content in place and uses a bounded session-local back stack cleared on pane close or connection change.

Cache and lifecycle

Reuse kind/name keys, request deduplication, connection generations, and invalidation from #313. Capability state is independent per source. A denied source is not re-probed per entity. Missing entries are cacheable; transient failures remain retryable.

Accessibility

All actions have explicit accessible names and visible focus. Hover is never the sole access path. Related actions are keyboard reachable. F1 remains documented in the shortcuts dialog.

Tests

Cover:

• capability detection and dynamic SELECT lists for each source;
• pre-26.6 sources that are usable;
• 26.6+ sources with missing optional columns;
• unavailable version string with successful probes;
• denied access without visible errors or probe storms;
• system.formats never requesting syntax;
• normalizers and unknown-field tolerance;
• all strong SQL contexts and negative literal/nested/malformed cases;
• hover, completion, F1, and schema actions sharing one target path;
• related history and reconnect stale suppression;
• no request on ordinary keystrokes;
• Phase 1 regression coverage.

Acceptance criteria

• Phase 2 sources are capability-gated by actual tables/columns, not a 26.6 check.
• Usable pre-26.6 sources are used.
• Missing optional columns degrade field-by-field.
• Formats, engines, and data types render version-exact structured docs when supported.
• system.formats never queries or displays a fabricated syntax field.
• CM6 hover/F1 use a pure strong-context classifier.
• Schema actions preserve existing gestures.
• Related entries navigate in the non-modal pane.
• Unsupported/denied sources degrade silently and are probed at most once per connection.
• No metadata SQL runs per keystroke.
• Unit, CM6, integration, and browser accessibility tests pass.

Non-goals

• settings, table functions, codecs, metrics, system tables, or other broad kinds;
• system.documentation Markdown rendering;
• weak-context guessing;
• changing schema insertion gestures;
• public-site fetching;
• persisted pane history;
• a general Markdown dependency.