cassis-cli 2.1.0__tar.gz → 2.2.0__tar.gz

{cassis_cli-2.1.0 → cassis_cli-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cassis-cli
-Version: 2.1.0
+Version: 2.2.0
 Summary: Validate, test and evaluate your Cassis ontology from your terminal, then publish it
 License: Apache-2.0
 License-File: LICENSE
@@ -35,10 +35,10 @@ Validate, test and evaluate your ontology from your terminal, then publish it. T
 - `cassis ontology test` runs individual questions through the text-to-SQL agent using your local ontology files, so you can check that a change actually works (e.g. a new column gets picked) — where `eval run` only checks for regressions on existing eval cases.
 - `cassis eval add-case` adds a gold question/SQL case to the project's eval suite — after fixing an ontology issue, add the question users were failing on so `eval run` guards it from regressing.
 - `cassis eval list-cases` and `cassis eval delete-case` maintain the suite: list the current cases with their ids, and prune one that is stale or wrong (e.g. its gold SQL encodes a definition the ontology has since changed).
-- `cassis schema plan <ddl>` (or `--warehouse` on a project connected to a warehouse) previews what a schema update would change before anything is applied: the source schema diff, the ontology changes Cassis will make (every change on a table placed in the ontology, with everything a drop takes with it) and warnings, terraform-style. `cassis schema apply <ddl>` (or `--plan <id>`) writes the resulting ontology files into the local checkout, app untouched, for review with `git diff`. `cassis schema push <ddl> [--publish]` pushes the new schema and the local ontology to the app (`--yes` in CI). The file speaks only for the schemas it contains — pass `--complete` when it is the project's complete source schema so schemas absent from it are treated as dropped. With `--warehouse` the server introspects the connected warehouse instead of parsing a file; the plan is always whole-source.
+- `cassis schema plan <ddl>` (or `--warehouse` on a project connected to a warehouse) previews what a schema update would change before anything is applied: the source schema diff, the ontology changes Cassis will make (every change on a table placed in the ontology, with everything a drop takes with it) and warnings, terraform-style. `cassis schema apply <ddl>` (or `--plan <id>`) writes the resulting ontology files into the local checkout, app untouched, for review with `git diff`. `cassis schema push <ddl> [--publish]` pushes the new schema and the local ontology to the app (`--yes` in CI). The file speaks only for the schemas it contains — pass `--complete` when it is the project's complete source schema so schemas absent from it are treated as dropped. With `--warehouse` the server introspects the connected warehouse instead of parsing a file; the plan is always whole-source. `cassis schema plan <ddl> --dry-run` is the prepare-ahead variant: the plan is computed synchronously and nothing is kept in Cassis (no plan to apply or resume, the current plan untouched), so a dbt model or migration still in a PR can be planned against safely; `--write-checkout` writes the ontology files it would produce into the checkout, to commit alongside the schema change.
 - `cassis projects list` lists the projects your API key can reach — id (what `--project` and `CASSIS_PROJECT_ID` take), name, published ontology version, and data-source dialect — so a pipeline or agent can discover the project id from the terminal instead of fishing it out of a webapp URL.
 - `cassis status` shows the project's published version (number, label, git commit), whether unpublished changes await publication, the git-sync binding, a schema plan waiting to be applied, and how your local git HEAD relates to the published commit (in sync / N commits ahead / diverged). `cassis status --watch` polls until the published commit matches your local HEAD — e.g. right after merging a PR whose CI publishes the ontology — instead of watching the GitHub Actions tab.
-- `cassis issues` triages the issues Cassis raised on the project — what it found wrong while answering questions (an ontology gap, missing data) — without leaving the checkout: `issues list` (filterable by status, impact and cause), `issues show <id>` for the diagnosis, suggested action and the occurrences behind it, `issues evidence <id> <occurrence-id>` for what the agent actually saw, and `issues resolve` / `dismiss` / `reopen` once you've acted on it.
+- `cassis issues` triages the issues Cassis raised on the project — what it found wrong while answering questions (an ontology gap, missing data) — without leaving the checkout: `issues list` (filterable by status, impact, cause and ontology domain, and showing each issue's domain so you can work through one domain at a time), `issues show <id>` for the diagnosis, suggested action and the occurrences behind it, `issues evidence <id> <occurrence-id>` for what the agent actually saw, and `issues resolve` / `dismiss` / `reopen` once you've acted on it.
 - `cassis verify` runs the full local gate in one verb — `ontology fmt --check`, `ontology check`, `eval run` — stopping at the first failure. One command in a checkout ("is this change safe to merge?"), one job in CI. `--no-eval` skips the eval suite.
 
 ## Install
@@ -140,6 +140,7 @@ cassis schema plan schema.sql --complete
 cassis schema apply schema.sql --complete      # writes cassis/ locally
 cassis schema push schema.sql --complete --yes  # schema + ontology to the app
 cassis schema plan --warehouse                   # warehouse-connected projects: introspect instead
+cassis schema plan future.sql --dry-run --write-checkout  # plan a not-yet-deployed DDL, keep nothing server-side
 
 # List the projects the API key can reach (id, name, published version, dialect):
 cassis projects list
@@ -153,6 +154,9 @@ cassis issues analyze
 cassis issues list --status open
 cassis issues show 019f0000-0000-7000-8000-0000000000e1
 
+# Work one ontology domain at a time (nested domains included):
+cassis issues list --domain sales
+
 # Read what the agent saw for one occurrence (ids from `issues show`):
 cassis issues evidence 019f0000-0000-7000-8000-0000000000e1 019f0000-0000-7000-8000-0000000000c1
 

{cassis_cli-2.1.0 → cassis_cli-2.2.0}/README.md

@@ -13,10 +13,10 @@ Validate, test and evaluate your ontology from your terminal, then publish it. T
 - `cassis ontology test` runs individual questions through the text-to-SQL agent using your local ontology files, so you can check that a change actually works (e.g. a new column gets picked) — where `eval run` only checks for regressions on existing eval cases.
 - `cassis eval add-case` adds a gold question/SQL case to the project's eval suite — after fixing an ontology issue, add the question users were failing on so `eval run` guards it from regressing.
 - `cassis eval list-cases` and `cassis eval delete-case` maintain the suite: list the current cases with their ids, and prune one that is stale or wrong (e.g. its gold SQL encodes a definition the ontology has since changed).
-- `cassis schema plan <ddl>` (or `--warehouse` on a project connected to a warehouse) previews what a schema update would change before anything is applied: the source schema diff, the ontology changes Cassis will make (every change on a table placed in the ontology, with everything a drop takes with it) and warnings, terraform-style. `cassis schema apply <ddl>` (or `--plan <id>`) writes the resulting ontology files into the local checkout, app untouched, for review with `git diff`. `cassis schema push <ddl> [--publish]` pushes the new schema and the local ontology to the app (`--yes` in CI). The file speaks only for the schemas it contains — pass `--complete` when it is the project's complete source schema so schemas absent from it are treated as dropped. With `--warehouse` the server introspects the connected warehouse instead of parsing a file; the plan is always whole-source.
+- `cassis schema plan <ddl>` (or `--warehouse` on a project connected to a warehouse) previews what a schema update would change before anything is applied: the source schema diff, the ontology changes Cassis will make (every change on a table placed in the ontology, with everything a drop takes with it) and warnings, terraform-style. `cassis schema apply <ddl>` (or `--plan <id>`) writes the resulting ontology files into the local checkout, app untouched, for review with `git diff`. `cassis schema push <ddl> [--publish]` pushes the new schema and the local ontology to the app (`--yes` in CI). The file speaks only for the schemas it contains — pass `--complete` when it is the project's complete source schema so schemas absent from it are treated as dropped. With `--warehouse` the server introspects the connected warehouse instead of parsing a file; the plan is always whole-source. `cassis schema plan <ddl> --dry-run` is the prepare-ahead variant: the plan is computed synchronously and nothing is kept in Cassis (no plan to apply or resume, the current plan untouched), so a dbt model or migration still in a PR can be planned against safely; `--write-checkout` writes the ontology files it would produce into the checkout, to commit alongside the schema change.
 - `cassis projects list` lists the projects your API key can reach — id (what `--project` and `CASSIS_PROJECT_ID` take), name, published ontology version, and data-source dialect — so a pipeline or agent can discover the project id from the terminal instead of fishing it out of a webapp URL.
 - `cassis status` shows the project's published version (number, label, git commit), whether unpublished changes await publication, the git-sync binding, a schema plan waiting to be applied, and how your local git HEAD relates to the published commit (in sync / N commits ahead / diverged). `cassis status --watch` polls until the published commit matches your local HEAD — e.g. right after merging a PR whose CI publishes the ontology — instead of watching the GitHub Actions tab.
-- `cassis issues` triages the issues Cassis raised on the project — what it found wrong while answering questions (an ontology gap, missing data) — without leaving the checkout: `issues list` (filterable by status, impact and cause), `issues show <id>` for the diagnosis, suggested action and the occurrences behind it, `issues evidence <id> <occurrence-id>` for what the agent actually saw, and `issues resolve` / `dismiss` / `reopen` once you've acted on it.
+- `cassis issues` triages the issues Cassis raised on the project — what it found wrong while answering questions (an ontology gap, missing data) — without leaving the checkout: `issues list` (filterable by status, impact, cause and ontology domain, and showing each issue's domain so you can work through one domain at a time), `issues show <id>` for the diagnosis, suggested action and the occurrences behind it, `issues evidence <id> <occurrence-id>` for what the agent actually saw, and `issues resolve` / `dismiss` / `reopen` once you've acted on it.
 - `cassis verify` runs the full local gate in one verb — `ontology fmt --check`, `ontology check`, `eval run` — stopping at the first failure. One command in a checkout ("is this change safe to merge?"), one job in CI. `--no-eval` skips the eval suite.
 
 ## Install
@@ -118,6 +118,7 @@ cassis schema plan schema.sql --complete
 cassis schema apply schema.sql --complete      # writes cassis/ locally
 cassis schema push schema.sql --complete --yes  # schema + ontology to the app
 cassis schema plan --warehouse                   # warehouse-connected projects: introspect instead
+cassis schema plan future.sql --dry-run --write-checkout  # plan a not-yet-deployed DDL, keep nothing server-side
 
 # List the projects the API key can reach (id, name, published version, dialect):
 cassis projects list
@@ -131,6 +132,9 @@ cassis issues analyze
 cassis issues list --status open
 cassis issues show 019f0000-0000-7000-8000-0000000000e1
 
+# Work one ontology domain at a time (nested domains included):
+cassis issues list --domain sales
+
 # Read what the agent saw for one occurrence (ids from `issues show`):
 cassis issues evidence 019f0000-0000-7000-8000-0000000000e1 019f0000-0000-7000-8000-0000000000c1
 

{cassis_cli-2.1.0 → cassis_cli-2.2.0}/cassis_cli/api.py

@@ -372,6 +372,10 @@ class SchemaPlanConflictError(ApiError):
     """409 from the schema-plan routes: a plan is already active, the project is connected, the plan is stale / expired / not ready."""
 
 
+class SchemaPlanRejectedError(ApiError):
+    """400 from the preview route: the DDL does not parse or reads as truncated (the user's file, not transport)."""
+
+
 class SchemaPlanNotFoundError(ApiError):
     """404 with the server's exact detail `"Schema plan not found"` (a project-scope 404 is a different error)."""
 
@@ -462,6 +466,61 @@ def post_schema_plan_warehouse(
     return _schema_plan_response(response, url)
 
 
+def _schema_plan_preview_response(response: httpx.Response, url: str) -> dict[str, Any]:
+    if response.status_code == 400:
+        raise SchemaPlanRejectedError(str(_detail_or_text(response)))
+    _raise_for_schema_plan_status(response)
+    result = _parse_json_response(response, url)
+    if not isinstance(result, dict) or "document" not in result or not isinstance(result.get("files"), dict):
+        raise ApiError(f"Unexpected response shape from the Cassis API at {url}.")
+    return result
+
+
+def post_schema_plan_preview(
+    *,
+    api_url: str,
+    api_key: str,
+    project_id: str,
+    ddl: str,
+    complete_source: bool = False,
+    transport: Optional[httpx.BaseTransport] = None,
+) -> dict[str, Any]:
+    """POST /api/ci/projects/{project_id}/schema/plans/preview: plan + rendered tree, nothing persisted.
+
+    Synchronous: the server computes the plan in the request (no plan row, no
+    job), so the tree timeout applies. A DDL the server cannot parse, or that
+    reads as truncated, is a 400 → `SchemaPlanRejectedError`.
+    """
+    url = api_url.rstrip("/") + f"/api/ci/projects/{project_id}/schema/plans/preview"
+    try:
+        with _client(timeout=ONTOLOGY_TREE_TIMEOUT_SECONDS, transport=transport) as client:
+            response = client.post(
+                url,
+                json={"ddl": ddl, "complete_source": complete_source},
+                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
+    return _schema_plan_preview_response(response, url)
+
+
+def post_schema_plan_preview_warehouse(
+    *,
+    api_url: str,
+    api_key: str,
+    project_id: str,
+    transport: Optional[httpx.BaseTransport] = None,
+) -> dict[str, Any]:
+    """POST /api/ci/projects/{project_id}/schema/plans/preview/warehouse: the warehouse twin of the preview."""
+    url = api_url.rstrip("/") + f"/api/ci/projects/{project_id}/schema/plans/preview/warehouse"
+    try:
+        with _client(timeout=ONTOLOGY_TREE_TIMEOUT_SECONDS, transport=transport) as client:
+            response = client.post(url, 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
+    return _schema_plan_preview_response(response, url)
+
+
 def get_schema_plan(
     *,
     api_url: str,
@@ -790,11 +849,16 @@ def get_issues(
     status: Optional[str] = None,
     impact: Optional[str] = None,
     cause: Optional[str] = None,
+    domain: Optional[str] = None,
     transport: Optional[httpx.BaseTransport] = None,
 ) -> list[dict[str, Any]]:
     """GET /api/ci/projects/{project_id}/issues and return the issue list."""
     url = api_url.rstrip("/") + f"/api/ci/projects/{project_id}/issues"
-    params = {key: value for key, value in (("status", status), ("impact", impact), ("cause", cause)) if value}
+    params = {
+        key: value
+        for key, value in (("status", status), ("impact", impact), ("cause", cause), ("domain", domain))
+        if value
+    }
     result = _get_issue_json(url, api_key, transport, params=params)
     if not isinstance(result, list) or not all(isinstance(issue, dict) and "id" in issue for issue in result):
         raise ApiError(f"Unexpected response shape from the Cassis API at {url}.")

{cassis_cli-2.1.0 → cassis_cli-2.2.0}/cassis_cli/issues.py

@@ -117,6 +117,9 @@ def list_issues(
     status: Optional[str] = typer.Option(None, "--status", help=f"Filter by status ({', '.join(STATUSES)})."),
     impact: Optional[str] = typer.Option(None, "--impact", help=f"Filter by impact ({', '.join(IMPACTS)})."),
     cause: Optional[str] = typer.Option(None, "--cause", help=f"Filter by cause ({', '.join(CAUSES)})."),
+    domain: Optional[str] = typer.Option(
+        None, "--domain", help="Filter by ontology domain path; nested domains included."
+    ),
     path: Path = _PATH_OPTION,
     project_id: Optional[str] = _PROJECT_OPTION,
     api_key: Optional[str] = _API_KEY_OPTION,
@@ -126,9 +129,11 @@ def list_issues(
 ) -> None:
     """List the project's issues, prioritized by impact then recurrence.
 
-    Prints each issue's id, impact, occurrence count, status and title; the id
-    is what `cassis issues show`, `resolve`, `dismiss` and `reopen` take. Exits
-    0 on success, 2 on usage errors, 3 on transport/API errors.
+    Prints each issue's id, impact, occurrence count, status, primary ontology
+    domain (`-` when Cassis could not attach one) and title; the id is what
+    `cassis issues show`, `resolve`, `dismiss` and `reopen` take. Triage one
+    domain at a time with `--domain`, which covers its nested domains too.
+    Exits 0 on success, 2 on usage errors, 3 on transport/API errors.
     """
     status = _validate_choice(status, STATUSES, "--status")
     impact = _validate_choice(impact, IMPACTS, "--impact")
@@ -144,6 +149,7 @@ def list_issues(
             status=status,
             impact=impact,
             cause=cause,
+            domain=domain,
         )
     except (AuthError, ApiError) as exc:
         raise api_failure(exc) from exc
@@ -153,14 +159,16 @@ def list_issues(
         raise typer.Exit(EXIT_OK)
 
     if not issues:
-        typer.echo("No issues match." if (status or impact or cause) else "No issues on this project.")
+        typer.echo("No issues match." if (status or impact or cause or domain) else "No issues on this project.")
         raise typer.Exit(EXIT_OK)
 
     for issue in issues:
         occurrences = issue.get("occurrence_count_cache") or 0
+        # Primary domain only; --json carries the whole list.
+        domains = issue.get("domains") or []
         typer.echo(
             f"{issue.get('id')}  {issue.get('impact')}  x{occurrences}  "
-            f"{issue.get('status')}  {one_line(issue.get('title'))}"
+            f"{issue.get('status')}  {domains[0] if domains else '-'}  {one_line(issue.get('title'))}"
         )
     raise typer.Exit(EXIT_OK)
 
@@ -201,6 +209,7 @@ def show(
         f"{issue.get('status')}  {issue.get('impact')}  {issue.get('cause')}  "
         f"{issue.get('occurrence_count_cache', len(occurrences))} occurrence(s)"
     )
+    _field("Domains", ", ".join(issue.get("domains") or []) or None)
     _field("Description", issue.get("description"), blank_line=True)
     _field("Suggested action", issue.get("suggested_action"), blank_line=True)
     typer.echo("")

{cassis_cli-2.1.0 → cassis_cli-2.2.0}/cassis_cli/schema.py

@@ -21,6 +21,7 @@ from cassis_cli.api import (
     ApiError,
     AuthError,
     SchemaPlanConflictError,
+    SchemaPlanRejectedError,
     UploadValidationError,
     get_ontology_export,
     get_schema_export,
@@ -29,6 +30,8 @@ from cassis_cli.api import (
     post_ontology_import,
     post_schema_plan,
     post_schema_plan_apply,
+    post_schema_plan_preview,
+    post_schema_plan_preview_warehouse,
     post_schema_plan_warehouse,
 )
 from cassis_cli.common import (
@@ -229,6 +232,17 @@ def plan(
     timeout: float = _TIMEOUT_OPTION,
     json_output: bool = _JSON_OPTION,
     out: Optional[Path] = _OUT_OPTION,
+    dry_run: bool = typer.Option(
+        False,
+        "--dry-run",
+        help="Compute the plan in the request and keep nothing server-side: no plan to apply or resume, "
+        "the project's current plan untouched. For a DDL not deployed to the warehouse yet.",
+    ),
+    write_checkout: bool = typer.Option(
+        False,
+        "--write-checkout",
+        help="With --dry-run: also write the ontology files the plan would produce under <path>/<base-path>.",
+    ),
 ) -> None:
     """Preview what a schema update would change. Nothing is applied.
 
@@ -241,11 +255,46 @@ def plan(
     whole-source. Exits 0 when the plan is ready (even when it is empty), 1
     when the plan failed (unparseable or truncated DDL, unreachable
     warehouse), 2 on usage errors, 3 on transport errors or a timeout.
+
+    --dry-run is the prepare-ahead gesture: the plan is computed synchronously
+    and nothing is kept server-side, so it works for a schema change that is
+    still a PR (a dbt model, a migration) and leaves the project's current plan
+    alone. --write-checkout then writes the resulting ontology files into the
+    checkout, to commit next to the schema change; nothing is pushed.
     """
     api_key = require_api_key(api_key)
     _require_one_source(ddl_file, warehouse)
+    if write_checkout and not dry_run:
+        typer.secho(
+            "--write-checkout needs --dry-run (use `cassis schema apply` otherwise).", fg=typer.colors.RED, err=True
+        )
+        raise typer.Exit(EXIT_USAGE)
     resolved_project = resolve_project_id(project_id, path / base_path, quiet=json_output)
     assert resolved_project is not None
+    if dry_run:
+        preview = _preview(
+            ddl_file,
+            warehouse=warehouse,
+            api_url=api_url,
+            api_key=api_key,
+            project_id=resolved_project,
+            complete_source=complete_source,
+            json_output=json_output,
+            out=out,
+        )
+        if write_checkout:
+            ontology_dir = path / base_path.strip().strip("/")
+            written, deleted, _kept = _write_checkout(ontology_dir, preview["files"], json_output=json_output)
+            typer.secho(
+                f"✓ Wrote {len(written)} ontology file(s) into {ontology_dir}"
+                + (f", deleted {len(deleted)} stale file(s)" if deleted else "")
+                + ". The app is unchanged.",
+                fg=typer.colors.GREEN,
+                err=json_output,
+            )
+        if json_output:
+            typer.echo(json.dumps(preview, indent=2))
+        raise typer.Exit(EXIT_OK)
     record = _plan(
         ddl_file,
         warehouse=warehouse,
@@ -724,6 +773,54 @@ def _plan(
     return record
 
 
+def _preview(
+    ddl_file: Optional[Path],
+    *,
+    warehouse: bool,
+    api_url: str,
+    api_key: str,
+    project_id: str,
+    complete_source: bool,
+    json_output: bool,
+    out: Optional[Path],
+) -> "dict[str, Any]":
+    """Compute a dry-run plan for `ddl_file` (or the warehouse), render it. Return the preview record."""
+    try:
+        if warehouse:
+            preview = post_schema_plan_preview_warehouse(api_url=api_url, api_key=api_key, project_id=project_id)
+        else:
+            assert ddl_file is not None
+            preview = post_schema_plan_preview(
+                api_url=api_url,
+                api_key=api_key,
+                project_id=project_id,
+                ddl=_read_ddl(ddl_file),
+                complete_source=complete_source,
+            )
+    except (SchemaPlanRejectedError, SchemaPlanConflictError) as exc:
+        typer.secho(f"Plan failed: {exc}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(EXIT_VALIDATION_FAILED) from exc
+    except (AuthError, ApiError) as exc:
+        typer.secho(str(exc), fg=typer.colors.RED, err=True)
+        raise typer.Exit(EXIT_TRANSPORT) from exc
+    if out is not None:
+        try:
+            out.write_text(json.dumps(preview, indent=2) + "\n", encoding="utf-8")
+        except OSError as exc:
+            typer.secho(f"Could not write {out}: {exc}", fg=typer.colors.RED, err=True)
+            raise typer.Exit(EXIT_USAGE) from exc
+    # The renderer reads a plan record; a preview is one without an id.
+    record = {"status": "ready", "document": preview.get("document"), "summary": preview.get("summary")}
+    render_plan(record, err=json_output)
+    for warning in preview.get("warnings") or []:
+        typer.secho(f"  warning: {warning}", fg=typer.colors.YELLOW, err=True)
+    if plan_is_empty(record):
+        typer.secho("✓ Schema is up to date (dry run, nothing kept).", fg=typer.colors.GREEN, err=json_output)
+    else:
+        typer.secho("✓ Plan computed (dry run, nothing kept).", fg=typer.colors.GREEN, err=json_output)
+    return preview
+
+
 def _explain_not_ready(record: "dict[str, Any]") -> None:
     status = record.get("status")
     error = record.get("error") or ""

{cassis_cli-2.1.0 → cassis_cli-2.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "cassis-cli"
-version = "2.1.0"
+version = "2.2.0"
 description = "Validate, test and evaluate your Cassis ontology from your terminal, then publish it"
 readme = "README.md"
 license = { text = "Apache-2.0" }