cassis-cli 0.3.0__tar.gz → 0.4.0__tar.gz

{cassis_cli-0.3.0 → cassis_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cassis-cli
-Version: 0.3.0
+Version: 0.4.0
 Summary: Cassis CLI — run Cassis actions (ontology validation, upload and publish) from your CI pipelines
 License: Proprietary
 Keywords: cassis,ontology,ci,text-to-sql
@@ -23,6 +23,7 @@ Description-Content-Type: text/markdown
 Run Cassis actions from your CI pipelines:
 
 - `cassis ontology check` validates the ontology files in your repository with the exact same checks as the Cassis GitHub PR check (YAML parsing, round-trip, import validation) — so you can gate merges in any CI system, not just GitHub.
+- `cassis ontology fmt` rewrites the ontology files in canonical form (think `black`/`gofmt` for the ontology), so hand or agent edits pass the round-trip check.
 - `cassis ontology upload` uploads the ontology files to a Cassis project (full replace) and, by default, publishes them immediately as a new version — so a merge to your main branch can go live in one CI step.
 - `cassis ontology pull` downloads the project's unpublished ontology into your repository checkout (full sync — stale local YAML files are pruned), so you can start editing from the current state, or bootstrap a repo that isn't git-synced (e.g. Bitbucket).
 - `cassis eval run` runs the project's eval suite against your local ontology files (scored in-memory — nothing is pushed to Cassis) and prints per-question results, so you can test the changes on your git branch before merging.
@@ -95,6 +96,20 @@ and Ctrl-C cancels the run (exit 130). It prints a deep link to the run's page
 in the Evals UI; `--app-url` / `CASSIS_APP_URL` overrides the link's base URL
 when the webapp is not served from the API host (defaults to `--api-url`).
 
+### Formatting
+
+```bash
+# Rewrite the ontology files in canonical form (in place)
+cassis ontology fmt
+
+# CI mode: fail (exit 1) if any file is not canonical, write nothing
+cassis ontology fmt --check
+```
+
+`fmt` uses the exact serializer the validation round-trip compares against, so a formatted tree cannot fail that stage. Formatting does not run import validation — `check` remains the pass/fail gate for semantic problems (dangling references, incomplete metrics).
+
+**Review the diff before committing**: canonical form keeps exactly the fields Cassis understands. Unknown fields (typos) are dropped — the rewrite makes them visible in `git diff` instead of losing them silently at sync time. Files with duplicate YAML keys are rejected (fix them by hand: the formatter can't know which value you meant).
+
 ### Exit codes
 
 | Code | Meaning                                                                        |

{cassis_cli-0.3.0 → cassis_cli-0.4.0}/README.md

@@ -3,6 +3,7 @@
 Run Cassis actions from your CI pipelines:
 
 - `cassis ontology check` validates the ontology files in your repository with the exact same checks as the Cassis GitHub PR check (YAML parsing, round-trip, import validation) — so you can gate merges in any CI system, not just GitHub.
+- `cassis ontology fmt` rewrites the ontology files in canonical form (think `black`/`gofmt` for the ontology), so hand or agent edits pass the round-trip check.
 - `cassis ontology upload` uploads the ontology files to a Cassis project (full replace) and, by default, publishes them immediately as a new version — so a merge to your main branch can go live in one CI step.
 - `cassis ontology pull` downloads the project's unpublished ontology into your repository checkout (full sync — stale local YAML files are pruned), so you can start editing from the current state, or bootstrap a repo that isn't git-synced (e.g. Bitbucket).
 - `cassis eval run` runs the project's eval suite against your local ontology files (scored in-memory — nothing is pushed to Cassis) and prints per-question results, so you can test the changes on your git branch before merging.
@@ -75,6 +76,20 @@ and Ctrl-C cancels the run (exit 130). It prints a deep link to the run's page
 in the Evals UI; `--app-url` / `CASSIS_APP_URL` overrides the link's base URL
 when the webapp is not served from the API host (defaults to `--api-url`).
 
+### Formatting
+
+```bash
+# Rewrite the ontology files in canonical form (in place)
+cassis ontology fmt
+
+# CI mode: fail (exit 1) if any file is not canonical, write nothing
+cassis ontology fmt --check
+```
+
+`fmt` uses the exact serializer the validation round-trip compares against, so a formatted tree cannot fail that stage. Formatting does not run import validation — `check` remains the pass/fail gate for semantic problems (dangling references, incomplete metrics).
+
+**Review the diff before committing**: canonical form keeps exactly the fields Cassis understands. Unknown fields (typos) are dropped — the rewrite makes them visible in `git diff` instead of losing them silently at sync time. Files with duplicate YAML keys are rejected (fix them by hand: the formatter can't know which value you meant).
+
 ### Exit codes
 
 | Code | Meaning                                                                        |

{cassis_cli-0.3.0 → cassis_cli-0.4.0}/cassis_cli/__init__.py

@@ -1,3 +1,3 @@
 """Cassis CLI — run Cassis actions from your CI pipelines."""
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"

{cassis_cli-0.3.0 → cassis_cli-0.4.0}/cassis_cli/api.py

@@ -284,3 +284,39 @@ def post_eval_run_cancel(
         raise _project_scope_error(response)
     if response.status_code >= 400:
         raise ApiError(f"Cassis API returned HTTP {response.status_code}: {response.text[:500]}")
+
+
+def post_ontology_fmt(
+    *,
+    api_url: str,
+    api_key: str,
+    files: dict[str, str],
+    transport: Optional[httpx.BaseTransport] = None,
+) -> dict[str, Any]:
+    """POST the ontology tree to /api/ci/ontology-fmt and return the response body."""
+    url = api_url.rstrip("/") + "/api/ci/ontology-fmt"
+    try:
+        with httpx.Client(timeout=TIMEOUT_SECONDS, transport=transport) as client:
+            response = client.post(
+                url,
+                json={"files": files},
+                headers={"Authorization": f"Bearer {api_key}"},
+            )
+    except httpx.HTTPError as exc:
+        raise ApiError(f"Could not reach the Cassis API at {url}: {exc}") from exc
+
+    if response.status_code == 401:
+        raise AuthError("The Cassis API rejected the API key (invalid or expired).")
+    if response.status_code >= 400:
+        raise ApiError(f"Cassis API returned HTTP {response.status_code}: {response.text[:500]}")
+    result = _parse_json_response(response, url)
+    if (
+        not isinstance(result, dict)
+        or "ok" not in result
+        or not isinstance(result.get("findings"), list)
+        or not isinstance(result.get("changed_paths"), list)
+        or not isinstance(result.get("removed_paths"), list)
+        or (result["ok"] and not isinstance(result.get("files"), dict))
+    ):
+        raise ApiError(f"Unexpected response shape from the Cassis API at {url}.")
+    return result

{cassis_cli-0.3.0 → cassis_cli-0.4.0}/cassis_cli/ontology.py

@@ -15,6 +15,7 @@ from cassis_cli.api import (
     UploadValidationError,
     get_ontology_export,
     post_ontology_check,
+    post_ontology_fmt,
     post_ontology_import,
 )
 from cassis_cli.common import (
@@ -281,3 +282,93 @@ def upload(
                 fg=typer.colors.GREEN,
             )
     raise typer.Exit(EXIT_OK)
+
+
+@app.command()
+def fmt(
+    path: Path = typer.Argument(
+        Path("."),
+        help="Repository checkout root (the directory containing the ontology export path).",
+    ),
+    api_key: Optional[str] = typer.Option(
+        None,
+        "--api-key",
+        envvar="CASSIS_API_KEY",
+        help="Cassis API key (sk-k6-...). Create one in Organization settings -> API keys.",
+    ),
+    api_url: str = typer.Option(
+        DEFAULT_API_URL,
+        "--api-url",
+        envvar="CASSIS_API_URL",
+        help="Cassis API base URL.",
+    ),
+    base_path: str = typer.Option(
+        DEFAULT_BASE_PATH,
+        "--base-path",
+        envvar="CASSIS_BASE_PATH",
+        help="Repository directory the ontology is exported under (the project's git-sync Path setting).",
+    ),
+    check_only: bool = typer.Option(
+        False,
+        "--check",
+        help="Do not write anything; exit 1 if any file would change.",
+    ),
+) -> None:
+    """Rewrite the ontology files in canonical form (think `black` for the ontology).
+
+    Uses the exact serializer the validation round-trip compares against, so a
+    formatted tree cannot fail that stage of `cassis ontology check` or the
+    GitHub PR check. Unknown fields are dropped by canonicalization — review
+    the diff before committing; duplicate YAML keys are rejected (the
+    formatter cannot know which value was intended). Exits 0 on success
+    (1 with --check when changes are needed), 1 when the tree cannot be
+    parsed, 2 on usage errors, 3 on transport/API errors.
+    """
+    api_key = _require_api_key(api_key)
+    files, base_path = _collect_tree(path, base_path)
+    ontology_dir = path / Path(base_path)
+
+    try:
+        result = post_ontology_fmt(api_url=api_url, api_key=api_key, files=files)
+    except AuthError as exc:
+        typer.secho(str(exc), fg=typer.colors.RED, err=True)
+        raise typer.Exit(EXIT_TRANSPORT) from exc
+    except ApiError as exc:
+        typer.secho(str(exc), fg=typer.colors.RED, err=True)
+        raise typer.Exit(EXIT_TRANSPORT) from exc
+
+    if not result["ok"]:
+        typer.secho("Cannot format: the tree does not parse.", fg=typer.colors.RED, bold=True, err=True)
+        for finding in result["findings"]:
+            location = f"{base_path}/{finding.get('path')}: " if finding.get("path") else ""
+            typer.echo(f"  {location}{finding.get('message', '')}", err=True)
+        raise typer.Exit(EXIT_VALIDATION_FAILED)
+
+    changed = result["changed_paths"]
+    removed = result["removed_paths"]
+    if not changed and not removed:
+        typer.secho(f"✓ {len(files)} file(s) already canonical.", fg=typer.colors.GREEN)
+        raise typer.Exit(EXIT_OK)
+
+    if check_only:
+        for p in changed:
+            typer.echo(f"would rewrite {base_path}/{p}")
+        for p in removed:
+            typer.echo(f"would remove {base_path}/{p}")
+        raise typer.Exit(EXIT_VALIDATION_FAILED)
+
+    for p in changed:
+        target = ontology_dir / p
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(result["files"][p], encoding="utf-8")
+        typer.echo(f"rewrote {base_path}/{p}")
+    for p in removed:
+        (ontology_dir / p).unlink(missing_ok=True)
+        typer.echo(f"removed {base_path}/{p}")
+    typer.secho(
+        f"Formatted {len(changed)} file(s)"
+        + (f", removed {len(removed)}" if removed else "")
+        + ". Review the diff: fields Cassis does not recognize are dropped.",
+        fg=typer.colors.YELLOW,
+    )
+    raise typer.Exit(EXIT_OK)

{cassis_cli-0.3.0 → cassis_cli-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "cassis-cli"
-version = "0.3.0"
+version = "0.4.0"
 description = "Cassis CLI — run Cassis actions (ontology validation, upload and publish) from your CI pipelines"
 readme = "README.md"
 license = { text = "Proprietary" }