@vertekum/schema-builder 0.1.4 → 0.1.5

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @vertekum/schema-builder
 
+## 0.1.5
+
+### Patch Changes
+
+- [`ecb2e95`](https://github.com/moros-oxus/vertekum/commit/ecb2e95fa860fa1aed780b29222aa69d474d68fe) Thanks [@tschemmer](https://github.com/tschemmer)! - Adds `vertekum schema lint`: validate `.dfn` modules — fragments and unused productions included — with findings collected and positioned per file. Grammar errors now point at the offending source (file, line, column) instead of `1:1`, and a misplaced `*` explains where the open-set mark belongs.
+
 ## 0.1.4
 
 ### Patch Changes

package/README.md

@@ -18,13 +18,13 @@ import { defineConfig } from '@vertekum/core';
 import { schemaBuilderExtension } from '@vertekum/schema-builder';
 
 export default defineConfig({
-  collection: './tokens',
   extensions: [schemaBuilderExtension],
-  schemas: [{ from: './schemas', domain: 'vocabulary', use: { 'house.json': '*.json' } }],
+  // the BUILT schema (step 3) validating a token set from the collection
+  schemas: [{ from: './schemas', use: { 'color-schema.json': 'core-tokens.json' } }],
 });
 ```
 
-2. Declare the vocabulary — `schemas/house.dfn`:
+2. Declare the vocabulary — `schemas/color-schema.dfn`:
 
 ```dfn
 emphasis = subtle | bold
@@ -35,96 +35,44 @@ root = color.text.[neutral | brand | success].<emphasis>
 3. Build it, then check as usual:
 
 ```bash
-npx vertekum schema build          # writes schemas/house.json beside the module
+npx vertekum schema build          # writes schemas/color-schema.json beside the module
 npx vertekum check                 # the built schema now governs your token names
 ```
 
-`schema build` accepts a single module argument, defaults to every `.dfn` under
-`./schemas`, and supports `--dry-run` (list without writing), `--json`, and `--check`
-(verify built files are current; exit 1 when stale — the CI guard). Only modules with a
-`root` build: the sweep skips fragment modules (denotation files that exist to be `use`d),
-while naming one explicitly is an error.
-
-## The definition language
-
-A module is line-oriented: `#` comments, pragmas, `use` imports, and productions. An
-indented line continues the statement above it.
-
-### Statements
-
-| statement | meaning |
-| --- | --- |
-| `name = expression` | a **production**: a named fragment (a denotation, a branch, a whole subtree) |
-| `root = expression` | the reserved production `build` materializes; one per module |
-| `use "./other.dfn"` | import a module (relative path or package specifier) |
-| `use "./other.dfn" as x` | alias the import: `<@x>` is its root, `<@x/name>` qualifies into it — the resolver when two imports share a basename |
-| `id "…"` `title "…"` `description "…"` | pragmas: the built schema's `$id`, `title`, `description` |
-| `scope "branch"` | the schema governs only its named top-level branches — the document root stays unsealed so sibling vocabularies can bind over the same files (default: `"document"`, which seals it) |
-
-### Expressions
-
-| syntax | meaning |
-| --- | --- |
-| `a.b.c` | nesting — one name-tree level per step |
-| `a \| b` | alternation — the set of permitted names |
-| `[ … ]` | grouping; groups may hold full sub-paths (branches) |
-| `<name>` | reference a local production |
-| `<@name>` | reference an imported production; an imported module's *root* goes by its basename |
-| `<@module/name>` | qualified: that import's production alone — the resolver when two imports share a name |
-| `<name [a, b]>` | **pick** — only the listed members of the set |
-| `<name ![a, b]>` | **omit** — the set minus the listed members |
-| `<name*>` / `[a \| b *]` | **open set** — additions beyond the listed names are permitted, and every member (listed or added) takes the same tail |
-| `step?` | **optional slot** — the step may be skipped: `<role>.<emphasis>?.<state>?` grants `role`, `role.<emphasis>`, `role.<state>`, and the full path |
-| `100-900/100` | an additive scale, inclusive both ends, enumerated at build; a leading zero on a written endpoint (`025-100/25`) zero-pads every emitted name |
-| `16-64*1.25~4` | a geometric scale: `min-max*factor` (fractional ok), `~quantum` rounding each step to the nearest multiple; steps that collide onto an earlier name are a build error |
-
-Pick and omit validate every listed name against the set's members — a typo is a build
-error, and a modified set is a new set. Naming one derives a narrowed denotation:
+The grammar reads the way a design system talks: nesting is `.`, choice is `|`,
+denotations are named productions referenced as `<emphasis>`, scales are enumerated
+expressions (`100-900/100`, `16-64*1.25~4`), and `?` marks a slot as optional. One
+expression grants a whole syntagm:
 
 ```dfn
-use "./colors.dfn"
-
-limited-accents = <@accent-color [red, blue]>
-```
-
-### Style: the root reads as the syntagm
-
-State the high-level shape in the root and let unused slots collapse; give forks their own
-named productions instead of nesting:
-
-```dfn
-property = background | text | icon | border
-role = brand | danger | neutral | success | warning
-emphasis = subtle | bold
-state = hovered | pressed
-
-root = color.[
-    <property>.<role>?.<emphasis>?.<state>?
-  | <code>
-  ]
-
-code = text.code.[comments | keywords | strings]
-```
-
-## Built artifacts and ownership
-
-A built file lands beside its module (`house.dfn` → `house.json`) and carries a `$comment`
-stamp naming its source. The stamp is the ownership contract: `schema build` regenerates
-stamped files and **never overwrites a file whose stamp was removed** — hand-edit the JSON
-and delete the stamp to take ownership, and the builder leaves it alone from then on.
-
-## Ejecting grammar
-
-`vertekum schema eject` copies any resolvable file verbatim — including `.dfn` modules
-from packages that ship them:
-
-```bash
-npx vertekum schema eject @vertekum/schema-atlassian/color.dfn ./schemas/color.dfn
-npx vertekum schema build
+root = color.<property>.<role>?.<emphasis>?.<state>?
 ```
 
-Ejecting the grammar (rather than the built JSON) means your edits stay one-line grammar
-edits with a rebuild, instead of surgery on generated schema. Two notes: an ejected module
-that `use`s relative imports needs them ejected alongside it; and the config hint `eject`
-prints applies to schemas you bind directly — an ejected `.dfn` is not bound, its *built*
-`.json` is.
+## Documentation
+
+- [The module](./docs/language.md) — statements, pragmas (`id`, `title`, `description`,
+  `scope`), comments and continuation, `root` and fragments.
+- [Expressions](./docs/expressions.md) — nesting, alternation, groups, references,
+  pick/omit, open sets, optional slots; the style that keeps a root readable.
+- [Scales](./docs/scales.md) — additive and geometric ranges, zero-padding,
+  quantization, the locked semantics.
+- [Modules and composition](./docs/modules.md) — `use` and aliasing, fragments,
+  aggregate roots, nested directories, shipping and ejecting grammar.
+- [`schema build`](./docs/build.md) — the command, the sweep, the ownership stamp, the
+  `--check` CI gate, programmatic use.
+- [`schema lint`](./docs/lint.md) — validate the `.dfn` sources themselves: fragments
+  included, every production, findings collected with positions.
+- [What a build emits](./docs/emission.md) — the names-and-order schema shape, open
+  positions, `$defs`, scope; a complete dfn→JSON example.
+
+## Ownership in one paragraph
+
+A built file lands beside its module (`color.dfn` → `color.json`) and carries a
+`$comment` stamp naming its source. `schema build` regenerates stamped files and
+**never overwrites a file whose stamp was removed** — deleting the stamp line is how
+you take ownership of the JSON and part ways with the grammar. Until then, the `.dfn`
+is the source of truth and `--check` keeps CI honest about rebuilds.
+
+## License
+
+Apache-2.0

package/docs/build.md

@@ -0,0 +1,81 @@
+# `vertekum schema build`
+
+Build `.dfn` modules into the JSON Schema files the `schemas` config binds. The command
+is contributed by this extension — it exists once `schemaBuilderExtension` is in the
+project's config, and appears in `vertekum --help` and `vertekum describe` from then on.
+
+```bash
+# vertekum schema build [module] [--check] [--dry-run] [--json] [--cwd <dir>]
+vertekum schema build                       # every module under ./schemas
+vertekum schema build schemas/color.dfn     # one module
+vertekum schema build --check               # CI: verify nothing is stale
+```
+
+| Argument / flag | What it does                                                                 |
+| --------------- | ----------------------------------------------------------------------------- |
+| `[module]`      | A `.dfn` file, relative to the working directory. Default: the sweep (below). |
+| `--check`       | Verify the built files on disk are current; write nothing.                    |
+| `--dry-run`     | Report what would be written without writing — owned by the runner, like every contributed command (see `@vertekum/cli`'s documentation). |
+| `--json`        | Machine-readable result (`files`, plus `skipped` and `fragments` under `data`). |
+| `--cwd <dir>`   | Project discovery starts here.                                                |
+
+## The sweep
+
+With no argument, every `.dfn` under the project's `schemas/` directory builds —
+recursively, so nested module directories are included (`node_modules` is not).
+Modules without a `root` are **fragments**: the sweep skips them with a notice, while
+naming one explicitly is an error — see [modules](./modules.md#fragments).
+
+## Artifacts
+
+Each module builds to `<module-name>.json` **beside its own file** —
+`schemas/color.dfn` → `schemas/color.json`, `schemas/palette/color.dfn` →
+`schemas/palette/color.json`. What the file contains is [emission](./emission.md).
+
+Writing goes through the CLI runner: `--dry-run` lists the same files and writes
+nothing, and an artifact path can never escape the working directory.
+
+## Ownership: the stamp
+
+Every built file carries a `$comment` stamp naming its source module:
+
+```
+built by @vertekum/schema-builder from schemas/color.dfn — do not hand-edit; remove this comment to take ownership
+```
+
+The stamp is the contract:
+
+- A **stamped** file is the builder's — regenerated on every build.
+- A **stampless** file at a build target has been taken over: hand-edit the JSON and
+  delete the stamp line, and the builder skips it from then on — reported
+  (`… has local edits (no stamp) — left as is`), never overwritten silently.
+
+## `--check`: the staleness gate
+
+`--check` rebuilds in memory and compares against disk, writing nothing. Any
+difference is an error (exit `1`) naming the stale files:
+
+```
+stale built schemas: schemas/color.json — run `vertekum schema build`
+```
+
+This is the CI guard: run it wherever the built schemas are committed, and a grammar
+edit that forgot its rebuild cannot land.
+
+`--check` asks "are the artifacts **current**?" — the complementary question, "is the
+grammar **sound**?" (including fragments a build never reaches), belongs to
+[`schema lint`](./lint.md); CI wants both.
+
+## Programmatic use
+
+The pipeline is importable from `@vertekum/schema-builder/api` for tooling that wants
+the pieces directly:
+
+| Export                     | Does                                                             |
+| -------------------------- | ----------------------------------------------------------------- |
+| `parse(source)`            | `.dfn` text → the module AST.                                     |
+| `resolveModule(path)`      | Parse a file and, recursively, everything it `use`s.              |
+| `build(resolved)`          | Expand a resolved module's root into its name tree.               |
+| `emit(tree, options)`      | Name tree → the JSON Schema document text.                        |
+| `buildModule(path, label?)`| The whole pipeline: path in, `{ target, content }` out.           |
+| `isStamped(content)` / `stamp(moduleFile)` | The ownership-stamp helpers.                      |

package/docs/emission.md

@@ -0,0 +1,129 @@
+# What a build emits
+
+A built schema is ordinary JSON Schema (2020-12), in the **names-and-order** shape
+hand-written vocabulary schemas use — so a generated file and a hand-written one are
+interchangeable, and taking ownership of a generated file (removing the stamp) leaves
+you with idiomatic schema, not machine soup.
+
+## The position shape
+
+Every position in the name tree becomes:
+
+```json
+{
+  "type": "object",
+  "properties": { "…declared children…": {} },
+  "patternProperties": { "^\\$": true },
+  "unevaluatedProperties": false
+}
+```
+
+- `properties` holds the granted names, one position schema each.
+- `patternProperties: { "^\\$": true }` lets DTCG's structural members (`$value`,
+  `$type`, `$description`, …) pass at every level — the vocabulary governs **names**,
+  not the token format (the format schemas do that separately).
+- `unevaluatedProperties: false` is the closure: a name outside the grant is a
+  violation, which is the entire point of a vocabulary schema.
+
+## Open positions
+
+A position whose set is [open](./expressions.md#open-sets) (`*`) replaces the closure
+with a route for additions:
+
+```json
+{
+  "type": "object",
+  "properties": { "…the listed members…": {} },
+  "patternProperties": { "^\\$": true },
+  "additionalProperties": { "…the members' shared tail…": {} }
+}
+```
+
+Additions join the set: they take the same tail every listed member has (which is
+well-defined precisely because `*` is restricted to name-only sets).
+
+## Denotations become `$defs`
+
+A terminal denotation referenced from **two or more** positions is emitted once under
+`$defs` and `$ref`'d — matching how a hand author avoids repeating themselves. A
+single-use denotation is inlined. A [picked or omitted](./expressions.md#pick-and-omit)
+set never shares the source's `$def`: a modified set is a different set.
+
+## Document keys
+
+| Key                     | From                                                             |
+| ----------------------- | ----------------------------------------------------------------- |
+| `$schema`               | always `https://json-schema.org/draft/2020-12/schema`             |
+| `$id`                   | the [`id` pragma](./language.md#pragmas), when declared           |
+| `$comment`              | the provenance stamp — the [ownership contract](./build.md#ownership-the-stamp) |
+| `title`, `description`  | their pragmas, when declared                                      |
+| `$defs`                 | shared denotations, when any                                      |
+| the root position       | `type`, `properties`, `patternProperties`, and the seal           |
+
+## Scope
+
+The [`scope` pragma](./language.md#pragmas) decides the **root** seal only:
+
+- `"document"` (default): the root carries `unevaluatedProperties: false` — nothing
+  beyond the granted top-level names may exist in a bound file.
+- `"branch"`: the root omits it — the schema governs its own branches and ignores
+  siblings, so several per-aspect schemas can bind over one collection. Every level
+  *below* the root stays sealed either way.
+
+## A complete example
+
+`schemas/color.dfn`:
+
+```dfn
+emphasis = subtle | bold
+
+root = color.[text | icon].<emphasis>
+```
+
+builds to `schemas/color.json`:
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$comment": "built by @vertekum/schema-builder from schemas/color.dfn — do not hand-edit; remove this comment to take ownership",
+  "$defs": {
+    "emphasis": {
+      "type": "object",
+      "properties": {
+        "subtle": {
+          "type": "object",
+          "properties": {},
+          "patternProperties": { "^\\$": true },
+          "unevaluatedProperties": false
+        },
+        "bold": {
+          "type": "object",
+          "properties": {},
+          "patternProperties": { "^\\$": true },
+          "unevaluatedProperties": false
+        }
+      },
+      "patternProperties": { "^\\$": true },
+      "unevaluatedProperties": false
+    }
+  },
+  "type": "object",
+  "properties": {
+    "color": {
+      "type": "object",
+      "properties": {
+        "text": { "$ref": "#/$defs/emphasis" },
+        "icon": { "$ref": "#/$defs/emphasis" }
+      },
+      "patternProperties": { "^\\$": true },
+      "unevaluatedProperties": false
+    }
+  },
+  "patternProperties": { "^\\$": true },
+  "unevaluatedProperties": false
+}
+```
+
+`<emphasis>` sits at two terminal positions (`color.text`, `color.icon`), so it became
+a shared `$def`. A token file bound to this schema may hold `color.text.subtle` with
+any `$`-members along the way — and nothing named outside the grant.

package/docs/expressions.md

@@ -0,0 +1,150 @@
+# Expressions
+
+An expression describes a **name tree**: which token names may exist beneath a
+position, and in what order the nesting proceeds. Everything to the right of a
+production's `=` is one of these forms, freely composed.
+
+| Syntax                  | Form                                                            |
+| ----------------------- | ---------------------------------------------------------------- |
+| [`a.b.c`](#nesting)     | nesting — one tree level per step                                |
+| [`a \| b`](#alternation) | alternation — the set of permitted names                        |
+| [`[ … ]`](#groups)      | grouping; groups may hold full sub-paths                         |
+| [`<name>`](#references) | reference a local production                                     |
+| [`<@name>`, `<@module/name>`](#references) | reference an imported production              |
+| [`<name [a, b]>`](#pick-and-omit)  | **pick** — only the listed members                    |
+| [`<name ![a, b]>`](#pick-and-omit) | **omit** — the set minus the listed members           |
+| [`<name*>`, `[a \| b *]`](#open-sets) | **open set** — additions are permitted             |
+| [`step?`](#optional-slots) | **optional slot** — the step may be skipped                   |
+| [`100-900/100`, `16-64*1.25~4`](./scales.md) | a numeric scale, enumerated at build — see [scales](./scales.md) |
+
+## Nesting
+
+`a.b.c` — each `.` step is one level of the name tree: the token path `a.b.c` and
+nothing beside it.
+
+```dfn
+root = color.text.base
+```
+
+grants exactly one path: `color.text.base`.
+
+## Alternation
+
+`a | b | c` — the union: this position permits these names.
+
+```dfn
+role = brand | danger | neutral | success | warning
+```
+
+## Groups
+
+`[ … ]` groups an expression, usually to alternate inside a path:
+
+```dfn
+root = color.[text | icon].base
+```
+
+grants `color.text.base` and `color.icon.base`.
+
+A group's options may be full **sub-paths**, which is how one root states branches with
+different shapes:
+
+```dfn
+root = color.[
+    <property>.<role>
+  | text.code.[comments | keywords | strings]
+  ]
+```
+
+## References
+
+| Form                | Resolves to                                                                    |
+| ------------------- | ------------------------------------------------------------------------------ |
+| `<name>`            | the local production `name`.                                                    |
+| `<@name>`           | an imported production: searched across every import; an imported module's **root** goes by the module's key (its basename, or its `use … as` alias). |
+| `<@module/name>`    | qualified — that import's production alone.                                     |
+
+An unqualified `<@name>` that two imports could satisfy is an error naming the fix:
+qualify it as `<@module/name>`. The import model — keys, aliasing, fragments — is
+[modules](./modules.md).
+
+## Pick and omit
+
+A reference may narrow the set it names: `[a, b]` **picks** only the listed members,
+`![a, b]` **omits** them. Every listed member is validated against the set — a typo is
+a build error (`'<scale>' has no member '600' to omit`), and numbers are valid members:
+
+```dfn
+use "./space.dfn"
+
+root = space.[<scale> | negative.<scale ![0, 1000]>]
+```
+
+A modified set is a **new** set: it never shares the source denotation's `$def` in the
+built schema — narrowing a set and changing the set are the same act. Naming the
+narrowed form derives a new denotation:
+
+```dfn
+limited-accents = <@accent-color [red, blue]>
+```
+
+## Open sets
+
+`*` marks a position's set as **open**: names beyond the listed ones are permitted, and
+every member — listed or added — takes the same tail.
+
+```dfn
+root = color.<color-role*>.value
+```
+
+grants `color.<any color-role, or any addition>.value`. The trailing `*` also works
+inside a group: `[small | medium | large *]`.
+
+`*` opens a set of **names**: the production (or group) it marks must be name-only —
+names, scales, and alternations of them. Opening a set of sub-paths is a build error,
+because an addition would have no well-defined shape to take. The shared tail is
+exactly what makes additions meaningful; the emitted schema routes them accordingly
+([emission](./emission.md#open-positions)).
+
+## Optional slots
+
+`?` marks a path step as skippable. The grant is the **slot-collapse lattice** — every
+combination of present and skipped optional steps:
+
+```dfn
+root = <role>.<emphasis>?.<state>?
+```
+
+grants four shapes:
+
+- `<role>`
+- `<role>.<emphasis>`
+- `<role>.<state>`
+- `<role>.<emphasis>.<state>`
+
+Order is preserved — `<state>` always follows `<emphasis>` when both appear; skipping
+is the only freedom. This is how a vocabulary states "emphasis and state are optional
+refinements" in one line instead of enumerating the lattice.
+
+## Style: the root reads as the syntagm
+
+State the high-level shape in the root and let unused slots collapse; give forks their
+own named productions instead of nesting them inline:
+
+```dfn
+property = background | text | icon | border
+role = brand | danger | neutral | success | warning
+emphasis = subtle | bold
+state = hovered | pressed
+
+root = color.[
+    <property>.<role>?.<emphasis>?.<state>?
+  | <code>
+  ]
+
+code = text.code.[comments | keywords | strings]
+```
+
+The root is the sentence — a reader sees the whole grammar of the vocabulary at the top
+of the file; the productions below are its glossary. Deep inline nesting states the
+same tree while hiding its shape.

package/docs/language.md

@@ -0,0 +1,95 @@
+# The module
+
+A `.dfn` file is a **module**: a line-oriented text file declaring a vocabulary. This
+page is the module's structure — statements, pragmas, and imports; the expression forms
+that appear to the right of `=` are [expressions](./expressions.md).
+
+```dfn
+# color.dfn — the colour vocabulary this project enforces
+title "Colour vocabulary"
+
+use "./denotations/emphasis.dfn"
+
+role = neutral | brand | success
+
+root = color.[text | icon].<role>.<@emphasis>
+```
+
+## Lexical rules
+
+- **Statements are lines.** One statement per line; a line that starts with whitespace
+  **continues** the statement above it, so a long expression wraps without any
+  continuation character:
+
+  ```dfn
+  root = color.[
+      <property>.<role>?.<emphasis>?
+    | <code>
+    ]
+  ```
+
+- **`#` starts a comment**, running to the end of the line.
+- **Identifiers** are `[A-Za-z][A-Za-z0-9-]*` — letters, digits, hyphens
+  (`color-role`). A term that starts with a digit is numeric: a bare number (`950`) or
+  a [scale expression](./scales.md) (`100-300/50`) — which is why hyphens inside names
+  never collide with range syntax.
+- **Strings** (pragma and `use` arguments) are double-quoted.
+
+## Statements
+
+| Statement                | What it is                                                       |
+| ------------------------ | ----------------------------------------------------------------- |
+| [`name = expression`](#productions) | A **production**: a named fragment of the vocabulary.  |
+| [`root = expression`](#root)        | The reserved production a build materializes.          |
+| [`use "…" [as name]`](#use)         | Import another module.                                 |
+| [`id` / `title` / `description` / `scope` `"…"`](#pragmas) | Document metadata pragmas.      |
+
+### Productions
+
+`name = expression` binds a name to an expression — a denotation (a set of names), a
+branch, or a whole subtree. Productions exist to be referenced (`<name>`) from other
+productions or the root; an unreferenced production builds nothing on its own. A
+production may not expand through itself — a reference cycle is a build error.
+
+### `root`
+
+`root = expression` is the reserved production the build materializes: the module's
+whole name tree grows from it. One per module.
+
+A module **without** a root is a **fragment** — a library of productions that exists to
+be `use`d by other modules. The build sweep skips fragments (with a notice); naming one
+explicitly as the build argument is an error, so a typo'd `root` cannot pass silently.
+See [modules](./modules.md#fragments).
+
+### `use`
+
+`use "<specifier>"` imports another module; `as <name>` renames the import. Specifier
+forms, import accessors, and collision handling are [modules](./modules.md).
+
+### Pragmas
+
+A pragma is an identifier followed by a string, each usable at most once per module:
+
+| Pragma        | Value                        | Lands in the built schema as              |
+| ------------- | ---------------------------- | ----------------------------------------- |
+| `id`          | any string (usually a URI)   | `$id`                                     |
+| `title`       | any string                   | `title`                                   |
+| `description` | any string                   | `description`                             |
+| `scope`       | `"document"` \| `"branch"`   | whether the document root is sealed       |
+
+`scope` is the one with semantics, and exactly two values:
+
+| Value        | Meaning                                                                                       |
+| ------------ | ---------------------------------------------------------------------------------------------- |
+| `"document"` | Default. The schema **seals** the document root: nothing beyond the granted names may exist.   |
+| `"branch"`   | The schema governs only the top-level branches it names — the root stays **unsealed**, so sibling vocabularies (a colour module, a spacing module) can each bind over the same token files without rejecting each other's branches. |
+
+A single whole-vocabulary schema wants the default; per-aspect schemas that co-validate
+one collection want `"branch"`. The exact effect on the emitted JSON is
+[emission](./emission.md#scope).
+
+## Editor support
+
+The package ships a TextMate grammar and language configuration for `.dfn` under
+`grammar/` — editors and tooling that consume TextMate grammars can pick them up from
+there.

package/docs/lint.md

@@ -0,0 +1,59 @@
+# `vertekum schema lint`
+
+Validate the `.dfn` sources themselves — fragments included, every production evaluated —
+without building anything.
+
+```bash
+# vertekum schema lint [module] [--json] [--cwd <dir>]
+vertekum schema lint                        # every module under ./schemas
+vertekum schema lint schemas/color.dfn      # one module — fragment or rooted
+```
+
+| Argument / flag | What it does                                                                 |
+| --------------- | ----------------------------------------------------------------------------- |
+| `[module]`      | A `.dfn` file, relative to the working directory. Default: every module under `./schemas`, recursively — **fragments included**. |
+| `--json`        | Machine-readable result.                                                       |
+| `--cwd <dir>`   | Project discovery starts here.                                                 |
+
+Exit `0` when the grammar is sound, `1` with findings — one per line, positioned:
+
+```
+2 problem(s) in the .dfn modules:
+  schemas/emphasis.dfn:1:21 unknown production '<missing>'
+  schemas/scale.dfn:1:14 '*' marks a set open and sits inside the reference or group it opens — <name*> or [a | b *]
+```
+
+## What lint checks that a build does not
+
+A build expands from `root`, so its validation reaches exactly what a root reaches.
+Lint's contract is the source:
+
+- **Fragments** — a module with no `root` never builds, but lint evaluates its
+  productions, so a broken denotation is caught in the file that declares it, not
+  months later in the first module that imports it.
+- **Unused productions** — a rooted module's production that nothing references yet is
+  still checked.
+- **Everything a build would refuse** — unknown or ambiguous references, pick/omit
+  members that don't exist, scale collisions, `*` on a non-name set, reference cycles —
+  reported the same way, at the same positions.
+
+Findings **collect**: one broken production does not hide the next, so a module with
+three mistakes is one lint run, not three.
+
+## Sound vs. current
+
+`lint` and [`build --check`](./build.md#--check-the-staleness-gate) answer different
+questions:
+
+| Verb            | Question                    | Covers                                    |
+| --------------- | --------------------------- | ------------------------------------------ |
+| `schema lint`   | Is the grammar sound?       | Every `.dfn`, fragments and all; no artifacts touched. |
+| `schema build --check` | Are the artifacts current? | Rooted modules' built `.json` vs. disk.  |
+
+CI wants both — lint fails a broken fragment the staleness gate cannot see, and the
+staleness gate fails a sound grammar whose rebuild was forgotten.
+
+## Programmatic use
+
+`lintModule(path)` (from `@vertekum/schema-builder/api`) returns the findings as
+`{ file, line, column, message }` records — an empty array means sound.