Skip to content

gate(docs): data-formation is read by the engine but structurally invisible to check:docs #1170

Description

@zachshallbetter

Found while writing the Phase 5 cookbook (#1169), and verified against main.

The gap

data-formation is a real declarative surface. The engine queries it directly:

packages/core/src/engine/field.ts:3018
  host.root.querySelectorAll('[data-formation]').forEach((node) => {

It appears in no attribute table, and apps/site/src/lib/docs-api.ts has zero entries for it.

check:docs does not catch this, and cannot, because of where it looks. From scripts/check-docs.mjs:

 *   5. body attrs            (engine: core/scanner.ts        · docs: ATTRS[])
const scannerSrc = read('packages/core/src/engine/scanner.ts');

The gate extracts the authoritative attribute list from scanner.ts. data-formation is not handled there — it is handled in field.ts — so it is not in the set the gate compares against the docs, and an undocumented attribute reads as full coverage. The gate currently reports 258/258 at 100% with this surface missing entirely.

Why this matters beyond one attribute

This is the same class as #1090 and #1158: a surface the gate structurally cannot see, so the gap stays invisible rather than failing a check. The parity matrix answered that class for render modes by adding a dimension that reads what the host actually paints. The docs gate needs the equivalent — its body-attribute source needs to cover every place an attribute is consumed, not one file that happens to hold most of them.

Worth asking while fixing: is scanner.ts the only extraction point that has drifted from where the engine really reads things? A gate whose source of truth is one file among several will keep finding this out one attribute at a time.

Suggested shape

  1. Document data-formation with its docs-api.ts row, so the immediate gap closes.
  2. Widen the gate's extraction so an attribute consumed anywhere in the engine counts. docs(refactor): Phase 5 — the task-shaped cookbook, with examples that execute (#1000) #1169's author notes this needs generator work — a matching declarative-body concept id — which is why it was flagged here rather than folded into a docs PR.
  3. Consider a cheaper backstop in the meantime: a check that greps the engine for [data-*] selectors and asserts each has a docs row. Crude, but it would have caught this.

Note that #1169 documents the attribute on the cookbook page, so the user-facing gap is closed by that PR. This issue is about the gate, which is the part that lets it recur.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't working

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions