model2data 1.8.0__tar.gz → 1.10.0__tar.gz

{model2data-1.8.0/model2data.egg-info → model2data-1.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: model2data
-Version: 1.8.0
+Version: 1.10.0
 Summary: Generate analytics-ready datasets from DBML models
 Author: JB Analytica
 License-Expression: MIT
@@ -132,7 +132,7 @@ access required.
 ## The model file
 
 A model is one YAML document, `<name>.model2data.yml` — or the same document as JSON. Its format
-is [spec 0.2.0](https://github.com/JB-Analytica/model2data/blob/main/model2data/spec/README.md), with a JSON Schema your editor can autocomplete and
+is [spec 0.3.0](https://github.com/JB-Analytica/model2data/blob/main/model2data/spec/README.md), with a JSON Schema your editor can autocomplete and
 check against:
 
 ```yaml
@@ -177,6 +177,12 @@ run:
 CLI option overrides the one it names. `model2data validate FILE` checks a model and prints every
 issue with its path in the document.
 
+**Validate models in CI.** `model2data validate a.model2data.yml b.model2data.yml` (or
+`--glob "**/*.model2data.yml"`, `--format github` for inline pull request annotations) exits 1
+when any model has an error. A GitHub Action (`uses: JB-Analytica/model2data@v1`), a pre-commit
+hook (`model2data-validate`) and a GitLab CI snippet are in the
+[README](https://github.com/JB-Analytica/model2data#validate-models-in-ci).
+
 **DBML is supported input.** `--file` also takes a `.dbml` file, converted to the same model
 before generating; a JSON note on a column (`[note: '{"min": 1}']`) becomes its `generate`, any
 other note its description. `model2data convert schema.dbml -o schema.model2data.yml` writes the
@@ -330,6 +336,55 @@ days[3].tables["orders"].updated    # rows day 3 changed, with their new values
 days[3].tables["orders"].state      # the table after day 3
 ```
 
+### Break the data on purpose
+
+A dbt test you have never seen fail is a test you hope works. `--defects` puts deliberate,
+counted defects in the generated data, so `dbt build` fails exactly the tests it should — for
+teaching dbt, or for proving a project's tests fire:
+
+```bash
+model2data --file examples/ecommerce.model2data.yml --seed 42 --defects training
+cd dbt_ecommerce && dbt build    # fails unique, not_null, relationships, accepted_values once each
+```
+
+`training` breaks each kind of standard dbt test once; `messy` puts a small share of every defect
+on every table; `clean` (the default) is the data as it always was, byte for byte; `none` also
+ignores the defects a model's tables list, for the clean data of a training model. A table can
+also list its own defects in the model (spec 0.3.0):
+
+```yaml
+orders:
+  defects:
+    - {type: duplicate_keys, count: 3}                               # fails unique
+    - {type: orphan_foreign_keys, column: customer_id, share: 0.02}  # fails relationships
+    - {type: nulls, column: order_date, count: 5}                    # fails not_null
+```
+
+The types are `duplicate_keys`, `orphan_foreign_keys`, `nulls`, `invalid_values` (fails
+`accepted_values`), `messy_text` (whitespace and casing to clean in staging), and, with `--days`,
+`late_arriving` (rows an incremental model filtering on `updated_at > max(updated_at)` skips) and
+`late_updates` (versions a `strategy: timestamp` snapshot misses) and `overlapping_history` (see
+below). Every run with defects writes
+`defects_report.json` (each defect, the rows it broke, the tests it breaks) and
+`EXPECTED_FAILURES.md` into the project, so a test that does not fire is visible. Defects are applied
+after the clean data, from their own random stream: the same seed gives the same bytes, and a
+defect on one table moves nothing in another. From Python, `model2data.defects.planned_defects`
+says what a run will break, `model2data.output.finish_run` applies it (and builds the histories)
+after `generate_days`, and `write_defects_report` / `write_expected_failures` write the two files.
+
+### A source that keeps its history
+
+`history: true` in a table's `incremental` (spec 0.3.0) also writes `<table>_history`: every
+version of every row over the generated days, with `valid_from`, `valid_to` (null for the current
+version) and `is_current` — an SCD type 2 source to build snapshots and point-in-time joins
+against. The project tests it with two package-free tests, one current row per key and no
+overlapping versions; the `overlapping_history` defect breaks the second.
+
+```yaml
+orders:
+  incremental: {new_per_day: 20, update_rate: 0.1, updated_at: updated_at, history: true}
+```
+
 ## Generated dbt project structure
 
 The generated dbt project includes:

{model2data-1.8.0 → model2data-1.10.0}/README.md

@@ -123,7 +123,7 @@ flowchart LR
 ## The model file
 
 A model is one YAML document, `<name>.model2data.yml` — or the same document as JSON. Its
-format is [spec 0.2.0](model2data/spec/README.md), with a JSON Schema
+format is [spec 0.3.0](model2data/spec/README.md), with a JSON Schema
 ([`model.schema.json`](model2data/spec/model.schema.json)) your editor can autocomplete and check
 against:
 
@@ -199,6 +199,54 @@ unquoted non-ASCII names — can't be read yet, and are refused with the line an
 
 ---
 
+## Validate models in CI
+
+Teams that keep `*.model2data.yml` models in git can fail a pull request that breaks one.
+`model2data validate` takes several files and `--glob` patterns, prefixes each issue with its
+file, exits 1 if any model has an error, and with `--format github` prints annotations that show
+inline on the pull request's Files tab. `--require-files` fails when nothing matched.
+
+**GitHub Actions**
+
+```yaml
+name: model2data
+on:
+  pull_request:
+    paths: ["**/*.model2data.yml"]
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: JB-Analytica/model2data@v1
+```
+
+Inputs: `files` (glob, default `**/*.model2data.yml`), `version` (default: the release the tag
+points at, e.g. `1.10.0`; a specifier such as `>=1.10,<2` also works), `python-version` (3.12).
+
+**pre-commit**
+
+```yaml
+repos:
+  - repo: https://github.com/JB-Analytica/model2data
+    rev: v1.10.0
+    hooks:
+      - id: model2data-validate
+```
+
+**GitLab CI**
+
+```yaml
+model2data:
+  image: python:3.12-slim
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+      changes: ["**/*.model2data.yml"]
+  script:
+    - pip install model2data==1.10.0
+    - model2data validate --glob "**/*.model2data.yml"
+```
+
 ## model2data studio — the same engine, in the browser
 
 [**model2data studio**](https://studio.jbanalytica.com) puts everything on this page behind a
@@ -473,6 +521,55 @@ they describe intent and should not break a first `dbt build` on real data); the
 same YAML as before. To call the mapping from Python, `model2data.dbt.hint_tests.hint_tests_for(model)`
 returns the tests as data.
 
+### Break the data on purpose
+
+A dbt test you have never seen fail is a test you hope works. `--defects` puts deliberate,
+counted defects in the generated data, so `dbt build` fails exactly the tests it should — for
+teaching dbt, or for proving a project's tests fire:
+
+```bash
+model2data --file examples/ecommerce.model2data.yml --seed 42 --defects training
+cd dbt_ecommerce && dbt build    # fails unique, not_null, relationships, accepted_values once each
+```
+
+`training` breaks each kind of standard dbt test once; `messy` puts a small share of every defect
+on every table; `clean` (the default) is the data as it always was, byte for byte; `none` also
+ignores the defects a model's tables list, for the clean data of a training model. A table can
+also list its own defects in the model (spec 0.3.0):
+
+```yaml
+orders:
+  defects:
+    - {type: duplicate_keys, count: 3}                               # fails unique
+    - {type: orphan_foreign_keys, column: customer_id, share: 0.02}  # fails relationships
+    - {type: nulls, column: order_date, count: 5}                    # fails not_null
+```
+
+The types are `duplicate_keys`, `orphan_foreign_keys`, `nulls`, `invalid_values` (fails
+`accepted_values`), `messy_text` (whitespace and casing to clean in staging), and, with `--days`,
+`late_arriving` (rows an incremental model filtering on `updated_at > max(updated_at)` skips) and
+`late_updates` (versions a `strategy: timestamp` snapshot misses) and `overlapping_history` (see
+below). Every run with defects writes
+`defects_report.json` (each defect, the rows it broke, the tests it breaks) and
+`EXPECTED_FAILURES.md` into the project, so a test that does not fire is visible. Defects are applied
+after the clean data, from their own random stream: the same seed gives the same bytes, and a
+defect on one table moves nothing in another. From Python, `model2data.defects.planned_defects`
+says what a run will break, `model2data.output.finish_run` applies it (and builds the histories)
+after `generate_days`, and `write_defects_report` / `write_expected_failures` write the two files.
+
+### A source that keeps its history
+
+`history: true` in a table's `incremental` (spec 0.3.0) also writes `<table>_history`: every
+version of every row over the generated days, with `valid_from`, `valid_to` (null for the current
+version) and `is_current` — an SCD type 2 source to build snapshots and point-in-time joins
+against. The project tests it with two package-free tests, one current row per key and no
+overlapping versions; the `overlapping_history` defect breaks the second.
+
+```yaml
+orders:
+  incremental: {new_per_day: 20, update_rate: 0.1, updated_at: updated_at, history: true}
+```
+
 ---
 
 ## Generated dbt project structure

{model2data-1.8.0 → model2data-1.10.0}/README_PYPI.md

@@ -85,7 +85,7 @@ access required.
 ## The model file
 
 A model is one YAML document, `<name>.model2data.yml` — or the same document as JSON. Its format
-is [spec 0.2.0](https://github.com/JB-Analytica/model2data/blob/main/model2data/spec/README.md), with a JSON Schema your editor can autocomplete and
+is [spec 0.3.0](https://github.com/JB-Analytica/model2data/blob/main/model2data/spec/README.md), with a JSON Schema your editor can autocomplete and
 check against:
 
 ```yaml
@@ -130,6 +130,12 @@ run:
 CLI option overrides the one it names. `model2data validate FILE` checks a model and prints every
 issue with its path in the document.
 
+**Validate models in CI.** `model2data validate a.model2data.yml b.model2data.yml` (or
+`--glob "**/*.model2data.yml"`, `--format github` for inline pull request annotations) exits 1
+when any model has an error. A GitHub Action (`uses: JB-Analytica/model2data@v1`), a pre-commit
+hook (`model2data-validate`) and a GitLab CI snippet are in the
+[README](https://github.com/JB-Analytica/model2data#validate-models-in-ci).
+
 **DBML is supported input.** `--file` also takes a `.dbml` file, converted to the same model
 before generating; a JSON note on a column (`[note: '{"min": 1}']`) becomes its `generate`, any
 other note its description. `model2data convert schema.dbml -o schema.model2data.yml` writes the
@@ -283,6 +289,55 @@ days[3].tables["orders"].updated    # rows day 3 changed, with their new values
 days[3].tables["orders"].state      # the table after day 3
 ```
 
+### Break the data on purpose
+
+A dbt test you have never seen fail is a test you hope works. `--defects` puts deliberate,
+counted defects in the generated data, so `dbt build` fails exactly the tests it should — for
+teaching dbt, or for proving a project's tests fire:
+
+```bash
+model2data --file examples/ecommerce.model2data.yml --seed 42 --defects training
+cd dbt_ecommerce && dbt build    # fails unique, not_null, relationships, accepted_values once each
+```
+
+`training` breaks each kind of standard dbt test once; `messy` puts a small share of every defect
+on every table; `clean` (the default) is the data as it always was, byte for byte; `none` also
+ignores the defects a model's tables list, for the clean data of a training model. A table can
+also list its own defects in the model (spec 0.3.0):
+
+```yaml
+orders:
+  defects:
+    - {type: duplicate_keys, count: 3}                               # fails unique
+    - {type: orphan_foreign_keys, column: customer_id, share: 0.02}  # fails relationships
+    - {type: nulls, column: order_date, count: 5}                    # fails not_null
+```
+
+The types are `duplicate_keys`, `orphan_foreign_keys`, `nulls`, `invalid_values` (fails
+`accepted_values`), `messy_text` (whitespace and casing to clean in staging), and, with `--days`,
+`late_arriving` (rows an incremental model filtering on `updated_at > max(updated_at)` skips) and
+`late_updates` (versions a `strategy: timestamp` snapshot misses) and `overlapping_history` (see
+below). Every run with defects writes
+`defects_report.json` (each defect, the rows it broke, the tests it breaks) and
+`EXPECTED_FAILURES.md` into the project, so a test that does not fire is visible. Defects are applied
+after the clean data, from their own random stream: the same seed gives the same bytes, and a
+defect on one table moves nothing in another. From Python, `model2data.defects.planned_defects`
+says what a run will break, `model2data.output.finish_run` applies it (and builds the histories)
+after `generate_days`, and `write_defects_report` / `write_expected_failures` write the two files.
+
+### A source that keeps its history
+
+`history: true` in a table's `incremental` (spec 0.3.0) also writes `<table>_history`: every
+version of every row over the generated days, with `valid_from`, `valid_to` (null for the current
+version) and `is_current` — an SCD type 2 source to build snapshots and point-in-time joins
+against. The project tests it with two package-free tests, one current row per key and no
+overlapping versions; the `overlapping_history` defect breaks the second.
+
+```yaml
+orders:
+  incremental: {new_per_day: 20, update_rate: 0.1, updated_at: updated_at, history: true}
+```
+
 ## Generated dbt project structure
 
 The generated dbt project includes:

{model2data-1.8.0 → model2data-1.10.0}/model2data/cli.py

@@ -1,7 +1,6 @@
 import random
-import re
 import shutil
-from dataclasses import replace
+from collections.abc import Iterable
 from datetime import date, datetime
 from pathlib import Path
 from typing import Any, Optional
@@ -13,12 +12,19 @@ from typer.core import TyperGroup
 from typer.models import ParameterInfo
 
 from model2data.dbt.hint_tests import DEFAULT_TOLERANCE, SEVERITIES
+from model2data.dbt.naming import dbt_names, for_dbt
 from model2data.dbt.project import (
     create_profiles_yml,
     create_project_scaffold,
     create_staging_models,
 )
 from model2data.dbt.tests import generate_dbt_yml, generate_unit_tests
+from model2data.defects import (
+    DefectsReport,
+    planned_defects,
+    write_defects_report,
+    write_expected_failures,
+)
 from model2data.generate.core import (
     generate_data_from_dbml,
     get_cyclic_tables,
@@ -36,8 +42,10 @@ from model2data.generate.faker import (
     get_unmapped_columns,
     reset_stats,
 )
+from model2data.generate.history import history_tables
 from model2data.generate.options import TimeProfile
 from model2data.model import (
+    DEFECT_PRESETS,
     Issue,
     Model,
     ModelError,
@@ -47,7 +55,7 @@ from model2data.model import (
     to_engine,
     validate,
 )
-from model2data.parse.dbml import TableDef
+from model2data.output import finish_run
 from model2data.utils import normalize_identifier
 
 SUPPORTED_ADAPTERS = ("duckdb", "postgres")
@@ -155,7 +163,7 @@ app = typer.Typer(
     cls=_GenerateByDefault,
     help=(
         "model2data: Generate analytics-ready datasets from a data model.\n\n"
-        "Given a model -- a .model2data.yml document (spec 0.2.0), the same as JSON,\n"
+        "Given a model -- a .model2data.yml document (spec 0.3.0), the same as JSON,\n"
         "or a DBML file -- this tool produces:\n"
         "• Synthetic but realistic data\n"
         "• A runnable dbt project scaffold\n"
@@ -188,15 +196,16 @@ def _read_model(file: Path) -> Model:
     return model
 
 
-def _print_issues(file: Path, issues: list[Issue]) -> None:
+def _print_issues(file: Path, issues: list[Issue], label: Optional[str] = None) -> None:
     """Errors, then warnings, each with its document path."""
+    label = label or file.name
     errors = [issue for issue in issues if issue.is_error]
     warnings = [issue for issue in issues if not issue.is_error]
     for marker, group, word in (("❌", errors, "error"), ("⚠️ ", warnings, "warning")):
         if not group:
             continue
         count = f"1 {word}" if len(group) == 1 else f"{len(group)} {word}s"
-        typer.echo(f"{marker} {file.name}: {count}")
+        typer.echo(f"{marker} {label}: {count}")
         for issue in group:
             text = str(issue).removeprefix("warning: ").replace("\n", "\n      ")
             typer.echo(f"  - {text}")
@@ -211,37 +220,13 @@ def _model_stem(file: Path) -> str:
     return file.stem
 
 
-def _dbt_identifier(key: str) -> str:
-    """A table key as the seed and model name it gets in the dbt project.
-
-    Spec 0.2.0 leaves a name as written (`user accounts`, `raw.orders`) and has
-    a consumer normalise it where it reaches a file or a dbt identifier, to
-    `[a-z0-9_]`. Underscores are kept as they are, so `_dlt_loads` and
-    `stories__kids` stay what they were.
-    """
-    cleaned = re.sub(r"[^0-9a-z_]+", "_", key.lower())
-    if cleaned.strip("_") == "":
-        cleaned = "table"
-    elif cleaned[0].isdigit():
-        cleaned = f"t_{cleaned}"
-    return cleaned
-
-
-def _dbt_names(tables: dict[str, TableDef]) -> dict[str, str]:
+def _dbt_names(tables: Iterable[str]) -> dict[str, str]:
     """Each table key's dbt identifier, refusing two keys that normalise alike."""
-    names: dict[str, str] = {}
-    owners: dict[str, str] = {}
-    for key in tables:
-        name = _dbt_identifier(key)
-        if name in owners:
-            typer.echo(
-                f"❌ Tables {owners[name]!r} and {key!r} would both be the dbt seed {name!r}. "
-                "Rename one of them."
-            )
-            raise typer.Exit(1)
-        owners[name] = key
-        names[key] = name
-    return names
+    try:
+        return dbt_names(tables)
+    except ValueError as exc:
+        typer.echo(f"❌ {exc}")
+        raise typer.Exit(1) from None
 
 
 @app.command(
@@ -420,6 +405,18 @@ def main(
         "--next",
         help="Shorthand for --days 1.",
     ),
+    defects_preset: Optional[str] = typer.Option(
+        None,
+        "--defects",
+        metavar="PRESET",
+        help=(
+            "Break the data on purpose: 'clean' (no preset, the default), 'messy' (a mix on\n"
+            "every table) or 'training' (each kind of dbt test fails once); a table's own\n"
+            "`defects` still apply. 'none' ignores every defect, the tables' own too.\n"
+            "Overrides the model's run.defects. Writes defects_report.json and\n"
+            "EXPECTED_FAILURES.md into the project."
+        ),
+    ),
     days_format: str = typer.Option(
         "batches",
         "--days-format",
@@ -463,6 +460,14 @@ def main(
     tolerance = _given(test_tolerance)
     tolerance = DEFAULT_TOLERANCE if tolerance is None else float(tolerance)
 
+    preset = _given(defects_preset)
+    if preset is not None:
+        preset = preset.lower()
+        if preset not in DEFECT_PRESETS:
+            raise typer.BadParameter(
+                f"Choose one of: {', '.join(DEFECT_PRESETS)}.", param_hint="--defects"
+            )
+
     # -------------------------
     # Read the model (names untouched)
     # -------------------------
@@ -537,7 +542,11 @@ def main(
     if table_seeds:
         rolled = ", ".join(f"{key}={value}" for key, value in sorted(table_seeds.items()))
         typer.echo(f"🎲 Re-rolling with a table seed of its own: {rolled}")
-    dbt_names = _dbt_names(tables)
+    names = _dbt_names([*tables, *history_tables(inputs)])
+    plan = planned_defects(model, preset, days=days or 0)
+    preset = preset or (run.defects if run.defects is not None else None)
+    if preset in ("messy", "training") and not plan:
+        typer.echo(f"ℹ️  The {preset} preset finds nothing to break in this model: no defects.")
 
     project_name = normalize_identifier(_given(name) or model.name or _model_stem(file))
     dest = Path.cwd() / f"dbt_{project_name}"
@@ -596,22 +605,33 @@ def main(
         typer.echo(f"❌ {exc}")
         raise typer.Exit(1) from None
 
+    # -------------------------
+    # Defects: broken on purpose, after the clean data, and reported
+    # -------------------------
+    if plan:
+        typer.echo("🧨 Breaking the data on purpose (defects)...")
+    out = finish_run(
+        inputs,
+        day_results or generated_tables,
+        plan,
+        seed=seed,
+        preset=preset,
+        as_of=anchor,
+        hint_tests=hint_tests,
+        test_tolerance=tolerance,
+        names=names,
+    )
+    report = out.report
+    generated_tables = out.frames
+    if day_results:
+        day_results = out.days
+
     # -------------------------
     # dbt names: a table key becomes a [a-z0-9_] seed and model name here,
     # once, so the CSV's stem, `stg_<name>` and every `ref()` agree.
     # -------------------------
-    dbt_tables = {
-        dbt_names[key]: replace(table, name=dbt_names[key]) for key, table in tables.items()
-    }
-    dbt_refs = [
-        {
-            **ref,
-            "source_table": dbt_names.get(ref["source_table"], ref["source_table"]),
-            "target_table": dbt_names.get(ref["target_table"], ref["target_table"]),
-        }
-        for ref in refs
-    ]
-    dbt_frames = {dbt_names.get(key, key): df for key, df in generated_tables.items()}
+    dbt_tables, dbt_refs = for_dbt(out.tables, refs, names)
+    dbt_frames = {names.get(key, key): df for key, df in generated_tables.items()}
 
     # -------------------------
     # Write dbt seeds (normalized names)
@@ -623,7 +643,7 @@ def main(
 
     if day_results and days_format != "final":
         write = write_batches if days_format == "batches" else write_changelog
-        write(dest, day_results, dbt_names)
+        write(dest, day_results, names)
 
     # -------------------------
     # Build dbt assets
@@ -651,6 +671,10 @@ def main(
     # Keep the original model file for reference
     shutil.copy(file, dest / file.name)
 
+    if report is not None:
+        write_defects_report(report, dest)
+        write_expected_failures(report, dest)
+
     # -------------------------
     # Summary
     # -------------------------
@@ -698,6 +722,9 @@ def main(
         for label in duplicate_unique:
             typer.echo(f"    - {label}")
 
+    if report is not None:
+        _print_defects(report)
+
     # -------------------------
     # Done
     # -------------------------
@@ -707,26 +734,121 @@ def main(
     typer.echo("  dbt build   # loads the seeds, builds the models, runs every test")
 
 
+def _spec_of(file: Path) -> str:
+    """The spec a conforming model is written against: 0.3.0, or 0.2.0 (DBML included)."""
+    return "0.3.0" if str(load(file).version).startswith("0.3") else "0.2.0"
+
+
+def _print_defects(report: DefectsReport) -> None:
+    typer.echo("\n🧨 Defects (defects_report.json, EXPECTED_FAILURES.md)")
+    for defect in report.defects:
+        column = defect.column if not isinstance(defect.column, list) else ", ".join(defect.column)
+        on = f".{column}" if column else ""
+        typer.echo(
+            f"  {defect.table}{on}: {defect.defect}, {defect.applied} "
+            f"row{'' if defect.applied == 1 else 's'}"
+        )
+        if defect.note and not defect.applied:
+            typer.echo(f"    ⚠️  {defect.note}")
+    count = len(report.expected_failures)
+    typer.echo(f"  dbt build should fail {count} test{'' if count == 1 else 's'}:")
+    for failure in report.expected_failures:
+        warn = " (warn)" if failure.severity == "warn" else ""
+        typer.echo(f"    - {failure.test}{warn}")
+
+
+_SKIPPED_DIRS = {".git", ".venv", "node_modules"}
+
+
+def _expand_globs(patterns: list[str]) -> list[Path]:
+    """Files matching recursive glob patterns relative to the cwd, sorted, without duplicates."""
+    found: dict[Path, None] = {}
+    for pattern in patterns:
+        for match in sorted(Path.cwd().glob(pattern)):
+            relative = match.relative_to(Path.cwd())
+            if match.is_file() and not _SKIPPED_DIRS.intersection(relative.parts):
+                found[relative] = None
+    return list(found)
+
+
+def _github_escape(text: str, *, prop: bool = False) -> str:
+    """Escape a workflow-command message (or property value) the way GitHub expects."""
+    text = text.replace("%", "%25").replace("\r", "%0D").replace("\n", "%0A")
+    return text.replace(":", "%3A").replace(",", "%2C") if prop else text
+
+
+def _print_github_issues(file: Path, issues: list[Issue]) -> None:
+    """One `::error` / `::warning` annotation per issue, shown inline on a pull request."""
+    for issue in issues:
+        level = "error" if issue.is_error else "warning"
+        where = f"file={_github_escape(file.as_posix(), prop=True)}"
+        if issue.line:
+            where += f",line={issue.line}"
+        text = f"{issue.path}: {issue.message}" if issue.path else issue.message
+        typer.echo(f"::{level} {where}::{_github_escape(text)}")
+
+
 @app.command("validate")
 def validate_command(
-    file: Path = typer.Argument(  # noqa: B008
-        ...,
+    files: Optional[list[Path]] = typer.Argument(  # noqa: B008
+        None,
         exists=True,
         file_okay=True,
         dir_okay=False,
         readable=True,
-        help="The model: a .model2data.yml / .yaml / .json document, or a .dbml file.",
+        help="The models: .model2data.yml / .yaml / .json documents, or .dbml files.",
+    ),
+    glob: Optional[list[str]] = typer.Option(  # noqa: B008
+        None,
+        "--glob",
+        help=(
+            "A recursive glob relative to the current directory, e.g. '**/*.model2data.yml'. "
+            "Repeatable; expands without the shell, so CI needs no globstar."
+        ),
+    ),
+    output_format: str = typer.Option(
+        "text",
+        "--format",
+        help="'text' (default) or 'github' for ::error / ::warning annotations on a pull request.",
+    ),
+    require_files: bool = typer.Option(
+        False, "--require-files", help="Exit 1 when no model file was given or matched."
     ),
 ):
-    """Check that a model conforms to spec 0.2.0, printing every issue with its path.
+    """Check that models conform to spec 0.3.0 (or 0.2.x), printing every issue with its path.
 
-    Exits 1 when there is an error; warnings are printed, and the model conforms.
+    Takes one or more files and/or --glob patterns. Exits 1 when any file has an error;
+    warnings are printed, and the model conforms.
     """
-    issues = validate(file)
-    _print_issues(file, issues)
-    if any(issue.is_error for issue in issues):
+    if output_format not in ("text", "github"):
+        raise typer.BadParameter("must be 'text' or 'github'", param_hint="--format")
+    targets = list(files or [])
+    if glob:
+        targets += [path for path in _expand_globs(glob) if path not in targets]
+    if not targets:
+        typer.echo("no model files matched")
+        raise typer.Exit(1 if require_files else 0)
+
+    failed = 0
+    for file in targets:
+        issues = validate(file)
+        if output_format == "github":
+            _print_github_issues(file, issues)
+        else:
+            _print_issues(file, issues, label=str(file) if len(targets) > 1 else file.name)
+        if any(issue.is_error for issue in issues):
+            failed += 1
+        elif output_format == "text":
+            typer.echo(
+                f"✅ {file if len(targets) > 1 else file.name} conforms to spec {_spec_of(file)}."
+            )
+    if len(targets) > 1 or output_format == "github":
+        checked = f"{len(targets)} model file{'s' if len(targets) != 1 else ''}"
+        typer.echo(
+            f"❌ {failed} of {checked} do not conform." if failed else f"✅ {checked} conform."
+        )
+    if failed:
         raise typer.Exit(1)
-    typer.echo(f"✅ {file.name} conforms to spec 0.2.0.")
 
 
 @app.command("convert")
@@ -748,7 +870,8 @@ def convert_command(
     ),
     force: bool = typer.Option(False, "--force", help="Overwrite the output file if it exists."),
 ):
-    """Convert a model -- DBML, typically -- to a spec 0.2.0 .model2data.yml document."""
+    """Convert a model -- DBML, typically -- to a .model2data.yml document (spec 0.2.0, or
+    0.3.0 when it has defects)."""
     try:
         model = load(file)
     except ModelError as error: