model2data 1.9.0__tar.gz → 1.10.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: model2data
-Version: 1.9.0
+Version: 1.10.0
 Summary: Generate analytics-ready datasets from DBML models
 Author: JB Analytica
 License-Expression: MIT
@@ -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

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

@@ -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

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

@@ -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

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

@@ -196,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}")
@@ -756,26 +757,98 @@ def _print_defects(report: DefectsReport) -> None:
         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.3.0 (or 0.2.x), 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 {_spec_of(file)}.")
 
 
 @app.command("convert")

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: model2data
-Version: 1.9.0
+Version: 1.10.0
 Summary: Generate analytics-ready datasets from DBML models
 Author: JB Analytica
 License-Expression: MIT
@@ -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

{model2data-1.9.0 → model2data-1.10.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "model2data"
-version = "1.9.0"
+version = "1.10.0"
 description = "Generate analytics-ready datasets from DBML models"
 readme = "README_PYPI.md"
 requires-python = ">=3.10"

{model2data-1.9.0 → model2data-1.10.0}/tests/test_cli_model.py

@@ -246,3 +246,95 @@ def test_help_lists_the_commands():
     assert result.exit_code == 0
     for command in ("generate", "validate", "convert"):
         assert command in result.output
+
+
+# ---------------------------------------------------------------------------
+# validate: several files, --glob, --format github, and the CI integration files
+# ---------------------------------------------------------------------------
+def _broken(tmp_path, name="bad.model2data.yml"):
+    return _write(tmp_path, name, MODEL.replace("rows: 12", "rows: 0"))
+
+
+def test_validate_several_files_all_valid(tmp_path):
+    a = _write(tmp_path, "a.model2data.yml", MODEL)
+    b = _write(tmp_path, "b.model2data.yml", MODEL)
+    result = runner.invoke(app, ["validate", str(a), str(b)])
+    assert result.exit_code == 0, result.output
+    assert f"✅ {a} conforms to spec 0.2.0." in result.output
+    assert "✅ 2 model files conform." in result.output
+
+
+def test_validate_several_files_one_invalid_exits_1_with_path_prefixed_issues(tmp_path):
+    good = _write(tmp_path, "good.model2data.yml", MODEL)
+    bad = _broken(tmp_path)
+    result = runner.invoke(app, ["validate", str(good), str(bad)])
+    assert result.exit_code == 1
+    assert f"❌ {bad}: 1 error" in result.output
+    assert "  - run.rows: must be 1 or more (got 0)" in result.output
+    assert "❌ 1 of 2 model files do not conform." in result.output
+
+
+def test_validate_glob_matches_nested_files(tmp_path, monkeypatch):
+    (tmp_path / "deep" / "er").mkdir(parents=True)
+    _write(tmp_path, "top.model2data.yml", MODEL)
+    _write(tmp_path / "deep" / "er", "nested.model2data.yml", MODEL)
+    (tmp_path / "node_modules").mkdir()
+    _write(tmp_path / "node_modules", "skipped.model2data.yml", MODEL)
+    monkeypatch.chdir(tmp_path)
+    result = runner.invoke(app, ["validate", "--glob", "**/*.model2data.yml"])
+    assert result.exit_code == 0, result.output
+    assert "top.model2data.yml" in result.output
+    assert "nested.model2data.yml" in result.output
+    assert "skipped" not in result.output
+    assert "2 model files conform" in result.output
+
+
+def test_validate_glob_with_no_match_is_a_note_unless_files_are_required(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    result = runner.invoke(app, ["validate", "--glob", "**/*.model2data.yml"])
+    assert result.exit_code == 0
+    assert "no model files matched" in result.output
+    required = runner.invoke(app, ["validate", "--glob", "**/*.model2data.yml", "--require-files"])
+    assert required.exit_code == 1
+    assert "no model files matched" in required.output
+
+
+def test_validate_format_github_prints_annotations(tmp_path, monkeypatch):
+    _broken(tmp_path)
+    monkeypatch.chdir(tmp_path)
+    result = runner.invoke(app, ["validate", "bad.model2data.yml", "--format", "github"])
+    assert result.exit_code == 1
+    assert "::error file=bad.model2data.yml::run.rows: must be 1 or more (got 0)" in result.output
+    yaml_error = _write(tmp_path, "dup.model2data.yml", MODEL + "name: again\n")
+    result = runner.invoke(app, ["validate", yaml_error.name, "--format", "github"])
+    assert "::error file=dup.model2data.yml,line=25::" in result.output
+
+
+def test_validate_format_github_prints_warnings_and_exits_0():
+    result = runner.invoke(
+        app, ["validate", str(EXAMPLES / "hackernews.dbml"), "--format", "github"]
+    )
+    assert result.exit_code == 0
+    assert "::warning file=" in result.output
+
+
+def test_validate_rejects_an_unknown_format(tmp_path):
+    model = _write(tmp_path, "m.model2data.yml", MODEL)
+    assert runner.invoke(app, ["validate", str(model), "--format", "xml"]).exit_code != 0
+
+
+def test_ci_integration_files_run_the_validate_command():
+    import yaml
+
+    root = Path(__file__).resolve().parent.parent
+    action = yaml.safe_load((root / "action.yml").read_text())
+    assert action["runs"]["using"] == "composite"
+    assert set(action["inputs"]) == {"files", "version", "python-version"}
+    steps = " ".join(str(step.get("run", "")) for step in action["runs"]["steps"])
+    assert "model2data validate --glob" in steps
+    assert "--format github" in steps
+    hooks = yaml.safe_load((root / ".pre-commit-hooks.yaml").read_text())
+    assert hooks[0]["id"] == "model2data-validate"
+    assert hooks[0]["entry"] == "model2data validate"
+    assert hooks[0]["language"] == "python"
+    assert hooks[0]["pass_filenames"] is True