cassis-cli 2.3.0__tar.gz → 3.0.0__tar.gz

{cassis_cli-2.3.0 → cassis_cli-3.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cassis-cli
-Version: 2.3.0
+Version: 3.0.0
 Summary: Validate, test and evaluate your Cassis ontology from your terminal, then publish it
 License: Apache-2.0
 License-File: LICENSE
@@ -27,7 +27,7 @@ Validate, test and evaluate your ontology from your terminal, then publish it. T
 - `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. It then prints advisory **ontology quality warnings** for a tree that parsed — tables not assigned to any domain, joins/metrics pointing at unknown tables or columns, missing table/column descriptions (the same findings `ontology test` reports, without the agent run). In a checkout bound to a project (`project.yml`, `--project`, or `CASSIS_PROJECT_ID`), it also cross-checks the tree against the project's source schema: references to tables or columns the warehouse doesn't have print as **warnings** too — advisory only (the object may simply not be built or synced yet). Warnings never fail the check.
 - `cassis schema pull` downloads the data source's full source schema (as Cassis last introspected it) into `<base-path>/.schema.json` — a **gitignored** local snapshot (the command maintains the ignore entry) with a `pulled_at` stamp. The warehouse stays authoritative; the snapshot is a cache for offline/bulk work — e.g. a coding agent grepping table and column names during a modeling pass instead of paging through the MCP `get_source_schema` tool. Re-run to refresh.
 - `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 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. It runs from a git checkout whose ontology files are committed, and the published version records that commit, so `cassis status` can tell whether a checkout matches what is live.
 - `cassis ontology pull` downloads the project's unpublished ontology into your repository checkout (full sync — stale local ontology files are pruned), so you can start editing from the current state, or bootstrap a repo that isn't git-synced (e.g. Bitbucket). Pruning only deletes files that are tracked and unmodified in git (i.e. restorable with `git checkout`); untracked or locally modified files are kept and listed, and every deleted path is printed.
 - `cassis ontology pull` and `cassis ontology fmt` also write `<base-path>/AGENTS.md`, the Cassis ontology modeling guide, into the checkout (default `cassis/AGENTS.md`) — a managed file (generated banner; the CLI overwrites local edits) so a repo-aware coding agent loads current Cassis modeling doctrine by convention. It sits inside the ontology directory but is not part of the ontology tree (which is the YAML files plus the domain Markdown files `domains/**/README.md`), so it is never uploaded, validated, or pruned. Commit it alongside your ontology changes. The guide text ships inside the CLI package, so its version tracks the **installed cassis-cli version** — upgrade the CLI (`pip install -U cassis-cli`) and re-run `fmt` to pick up doctrine updates; an unpinned `pip install cassis-cli` in CI gets them automatically. The banner stamps a doctrine version, and the CLI never *downgrades* the file: if the checkout's `AGENTS.md` was written by a newer doctrine (a newer CLI, or Cassis itself on a publish), `fmt`/`pull` leave it in place, print an upgrade notice, and `fmt --check` still passes.
 - The CLI identifies itself to the API (`User-Agent: cassis-cli/<version>`), and successful API responses advertise the newest published version — when you are behind, commands print a one-line upgrade notice on stderr (purely informational; output and exit codes are unchanged).
@@ -35,8 +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> --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 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 the schema snapshot for a change 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.
+- DDL imports describe one schema snapshot/export file, including ordinary and materialized views; they do not replay incremental migrations. Extraction diagnostics include object names and statement locations. If extraction is incomplete, `schema plan` and `--dry-run` show the extracted inventory and exit 1; `apply`, `push`, and `--write-checkout` cannot save that result. Unknown column types are warnings when all output names are known. Plans also show object-kind, view-definition, comment, and constraint changes. `--json` preserves structured diagnostics and the server-capped inventory.
+
 - `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, 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. When the fix ships through a pull request, write the `PR mention:` line `issues show` prints (`Resolves <id>`) in the PR description instead: Cassis resolves the issue when the PR merges, and `issues show` then reports how it was closed and through which PR.
 - `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.
@@ -77,7 +79,8 @@ cassis ontology check /path/to/checkout
 # --no-prune keeps even the tracked stale files it would otherwise delete):
 cassis ontology pull --project 019f0000-0000-7000-8000-000000000000
 
-# Upload the ontology to a project and publish it immediately:
+# Upload the ontology to a project and publish it immediately (commit the
+# changes under cassis/ first: uploads refuse uncommitted ontology files):
 cassis ontology upload --project 019f0000-0000-7000-8000-000000000000
 
 # Upload without publishing (the tree becomes the project's unpublished ontology, to review in Cassis):
@@ -138,6 +141,7 @@ cassis schema pull
 # Preview, apply locally and push a schema update from a DDL file (DDL-only projects):
 cassis schema plan schema.sql --complete
 cassis schema apply schema.sql --complete      # writes cassis/ locally
+git add cassis && git commit -m "Apply schema update"  # push needs the tree committed
 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
@@ -151,7 +155,8 @@ cassis projects list
 cassis issues analyze
 
 # Triage the issues Cassis raised (filter by --status/--impact/--cause; --json for raw output):
-cassis issues list --status open
+cassis issues list                 # open issues by default
+cassis issues list --status all    # include resolved and dismissed issues
 cassis issues show 019f0000-0000-7000-8000-0000000000e1
 
 # Work one ontology domain at a time (nested domains included):
@@ -162,8 +167,8 @@ cassis issues evidence 019f0000-0000-7000-8000-0000000000e1 019f0000-0000-7000-8
 
 # Close the loop once the fix is published (or reopen). When the fix ships in a pull
 # request, put `Resolves <id>` in its description instead and the merge closes the issue:
-cassis issues resolve 019f0000-0000-7000-8000-0000000000e1
-cassis issues dismiss 019f0000-0000-7000-8000-0000000000e1
+cassis issues resolve 019f0000-0000-7000-8000-0000000000e1 --published
+cassis issues dismiss 019f0000-0000-7000-8000-0000000000e1 --reason irrelevant --detail "Outside our scope"
 cassis issues reopen 019f0000-0000-7000-8000-0000000000e1
 
 # Published version vs local checkout (add --watch to poll until your merge is published):
@@ -212,8 +217,8 @@ cassis ontology fmt --check
 | Code | Meaning                                                                        |
 | ---- | ------------------------------------------------------------------------------ |
 | 0    | Ontology is valid (check) / pulled (pull) / uploaded (upload) / eval run completed all-passed (eval run) / every probe completed (test — whatever its outcome; probes are informational, don't gate CI on them) |
-| 1    | Validation failed (check: findings printed; upload: nothing imported; eval run: invalid tree, failed cases, or failed/cancelled run; test: invalid tree or a probe failed; add-case: duplicate question or gold SQL that does not run; delete-case: no such case in the project; issues: no such issue or occurrence in the project; issues analyze: failed or cancelled analysis run; schema plan/apply: the plan failed (unparseable or truncated DDL), is stale or expired, the apply failed, or the project won't accept it (a plan is being applied, a DDL was given for a warehouse-connected project, or --warehouse for a DDL-only one)) |
-| 2    | Usage error (missing API key or project, no ontology directory, unreadable file, tree over the size limits, `eval run --branch` naming an ontology branch the project does not have) |
+| 1    | Validation failed (check: findings printed; upload: nothing imported; eval run: invalid tree, failed cases, or failed/cancelled run; test: invalid tree or a probe failed; add-case: duplicate question or gold SQL that does not run; delete-case: no such case in the project; issues: no such issue or occurrence in the project; issues analyze: failed or cancelled analysis run; schema plan/apply: extraction is incomplete, the plan failed (unparseable or truncated DDL), is stale or expired, the apply failed, or the project won't accept it (a plan is being applied, a DDL was given for a warehouse-connected project, or --warehouse for a DDL-only one)) |
+| 2    | Usage error (missing API key or project, no ontology directory, unreadable file, tree over the size limits, `eval run --branch` naming an ontology branch the project does not have, `upload` or `schema push` outside a git checkout or with uncommitted ontology files) |
 | 3    | Transport/API error (unreachable API, invalid key, inaccessible project, unexpected response), another eval run or issue analysis already active, out of credits, or `--timeout` reached |
 
 Commands that send the local tree (`check`, `fmt`, `upload`, `eval run`, `test`) accept up to
@@ -296,7 +301,7 @@ ontology-eval:
     CASSIS_PROJECT_ID: $CASSIS_PROJECT_ID
 
 ontology-publish:
-  image: python:3.12-slim
+  image: python:3.12  # not -slim: the upload needs git to record the commit
   rules:
     - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
   script:

{cassis_cli-2.3.0 → cassis_cli-3.0.0}/README.md

@@ -5,7 +5,7 @@ Validate, test and evaluate your ontology from your terminal, then publish it. T
 - `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. It then prints advisory **ontology quality warnings** for a tree that parsed — tables not assigned to any domain, joins/metrics pointing at unknown tables or columns, missing table/column descriptions (the same findings `ontology test` reports, without the agent run). In a checkout bound to a project (`project.yml`, `--project`, or `CASSIS_PROJECT_ID`), it also cross-checks the tree against the project's source schema: references to tables or columns the warehouse doesn't have print as **warnings** too — advisory only (the object may simply not be built or synced yet). Warnings never fail the check.
 - `cassis schema pull` downloads the data source's full source schema (as Cassis last introspected it) into `<base-path>/.schema.json` — a **gitignored** local snapshot (the command maintains the ignore entry) with a `pulled_at` stamp. The warehouse stays authoritative; the snapshot is a cache for offline/bulk work — e.g. a coding agent grepping table and column names during a modeling pass instead of paging through the MCP `get_source_schema` tool. Re-run to refresh.
 - `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 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. It runs from a git checkout whose ontology files are committed, and the published version records that commit, so `cassis status` can tell whether a checkout matches what is live.
 - `cassis ontology pull` downloads the project's unpublished ontology into your repository checkout (full sync — stale local ontology files are pruned), so you can start editing from the current state, or bootstrap a repo that isn't git-synced (e.g. Bitbucket). Pruning only deletes files that are tracked and unmodified in git (i.e. restorable with `git checkout`); untracked or locally modified files are kept and listed, and every deleted path is printed.
 - `cassis ontology pull` and `cassis ontology fmt` also write `<base-path>/AGENTS.md`, the Cassis ontology modeling guide, into the checkout (default `cassis/AGENTS.md`) — a managed file (generated banner; the CLI overwrites local edits) so a repo-aware coding agent loads current Cassis modeling doctrine by convention. It sits inside the ontology directory but is not part of the ontology tree (which is the YAML files plus the domain Markdown files `domains/**/README.md`), so it is never uploaded, validated, or pruned. Commit it alongside your ontology changes. The guide text ships inside the CLI package, so its version tracks the **installed cassis-cli version** — upgrade the CLI (`pip install -U cassis-cli`) and re-run `fmt` to pick up doctrine updates; an unpinned `pip install cassis-cli` in CI gets them automatically. The banner stamps a doctrine version, and the CLI never *downgrades* the file: if the checkout's `AGENTS.md` was written by a newer doctrine (a newer CLI, or Cassis itself on a publish), `fmt`/`pull` leave it in place, print an upgrade notice, and `fmt --check` still passes.
 - The CLI identifies itself to the API (`User-Agent: cassis-cli/<version>`), and successful API responses advertise the newest published version — when you are behind, commands print a one-line upgrade notice on stderr (purely informational; output and exit codes are unchanged).
@@ -13,8 +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> --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 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 the schema snapshot for a change 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.
+- DDL imports describe one schema snapshot/export file, including ordinary and materialized views; they do not replay incremental migrations. Extraction diagnostics include object names and statement locations. If extraction is incomplete, `schema plan` and `--dry-run` show the extracted inventory and exit 1; `apply`, `push`, and `--write-checkout` cannot save that result. Unknown column types are warnings when all output names are known. Plans also show object-kind, view-definition, comment, and constraint changes. `--json` preserves structured diagnostics and the server-capped inventory.
+
 - `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, 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. When the fix ships through a pull request, write the `PR mention:` line `issues show` prints (`Resolves <id>`) in the PR description instead: Cassis resolves the issue when the PR merges, and `issues show` then reports how it was closed and through which PR.
 - `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.
@@ -55,7 +57,8 @@ cassis ontology check /path/to/checkout
 # --no-prune keeps even the tracked stale files it would otherwise delete):
 cassis ontology pull --project 019f0000-0000-7000-8000-000000000000
 
-# Upload the ontology to a project and publish it immediately:
+# Upload the ontology to a project and publish it immediately (commit the
+# changes under cassis/ first: uploads refuse uncommitted ontology files):
 cassis ontology upload --project 019f0000-0000-7000-8000-000000000000
 
 # Upload without publishing (the tree becomes the project's unpublished ontology, to review in Cassis):
@@ -116,6 +119,7 @@ cassis schema pull
 # Preview, apply locally and push a schema update from a DDL file (DDL-only projects):
 cassis schema plan schema.sql --complete
 cassis schema apply schema.sql --complete      # writes cassis/ locally
+git add cassis && git commit -m "Apply schema update"  # push needs the tree committed
 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
@@ -129,7 +133,8 @@ cassis projects list
 cassis issues analyze
 
 # Triage the issues Cassis raised (filter by --status/--impact/--cause; --json for raw output):
-cassis issues list --status open
+cassis issues list                 # open issues by default
+cassis issues list --status all    # include resolved and dismissed issues
 cassis issues show 019f0000-0000-7000-8000-0000000000e1
 
 # Work one ontology domain at a time (nested domains included):
@@ -140,8 +145,8 @@ cassis issues evidence 019f0000-0000-7000-8000-0000000000e1 019f0000-0000-7000-8
 
 # Close the loop once the fix is published (or reopen). When the fix ships in a pull
 # request, put `Resolves <id>` in its description instead and the merge closes the issue:
-cassis issues resolve 019f0000-0000-7000-8000-0000000000e1
-cassis issues dismiss 019f0000-0000-7000-8000-0000000000e1
+cassis issues resolve 019f0000-0000-7000-8000-0000000000e1 --published
+cassis issues dismiss 019f0000-0000-7000-8000-0000000000e1 --reason irrelevant --detail "Outside our scope"
 cassis issues reopen 019f0000-0000-7000-8000-0000000000e1
 
 # Published version vs local checkout (add --watch to poll until your merge is published):
@@ -190,8 +195,8 @@ cassis ontology fmt --check
 | Code | Meaning                                                                        |
 | ---- | ------------------------------------------------------------------------------ |
 | 0    | Ontology is valid (check) / pulled (pull) / uploaded (upload) / eval run completed all-passed (eval run) / every probe completed (test — whatever its outcome; probes are informational, don't gate CI on them) |
-| 1    | Validation failed (check: findings printed; upload: nothing imported; eval run: invalid tree, failed cases, or failed/cancelled run; test: invalid tree or a probe failed; add-case: duplicate question or gold SQL that does not run; delete-case: no such case in the project; issues: no such issue or occurrence in the project; issues analyze: failed or cancelled analysis run; schema plan/apply: the plan failed (unparseable or truncated DDL), is stale or expired, the apply failed, or the project won't accept it (a plan is being applied, a DDL was given for a warehouse-connected project, or --warehouse for a DDL-only one)) |
-| 2    | Usage error (missing API key or project, no ontology directory, unreadable file, tree over the size limits, `eval run --branch` naming an ontology branch the project does not have) |
+| 1    | Validation failed (check: findings printed; upload: nothing imported; eval run: invalid tree, failed cases, or failed/cancelled run; test: invalid tree or a probe failed; add-case: duplicate question or gold SQL that does not run; delete-case: no such case in the project; issues: no such issue or occurrence in the project; issues analyze: failed or cancelled analysis run; schema plan/apply: extraction is incomplete, the plan failed (unparseable or truncated DDL), is stale or expired, the apply failed, or the project won't accept it (a plan is being applied, a DDL was given for a warehouse-connected project, or --warehouse for a DDL-only one)) |
+| 2    | Usage error (missing API key or project, no ontology directory, unreadable file, tree over the size limits, `eval run --branch` naming an ontology branch the project does not have, `upload` or `schema push` outside a git checkout or with uncommitted ontology files) |
 | 3    | Transport/API error (unreachable API, invalid key, inaccessible project, unexpected response), another eval run or issue analysis already active, out of credits, or `--timeout` reached |
 
 Commands that send the local tree (`check`, `fmt`, `upload`, `eval run`, `test`) accept up to
@@ -274,7 +279,7 @@ ontology-eval:
     CASSIS_PROJECT_ID: $CASSIS_PROJECT_ID
 
 ontology-publish:
-  image: python:3.12-slim
+  image: python:3.12  # not -slim: the upload needs git to record the commit
   rules:
     - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
   script:

{cassis_cli-2.3.0 → cassis_cli-3.0.0}/cassis_cli/api.py

@@ -204,12 +204,17 @@ def post_ontology_import(
     project_id: str,
     files: dict[str, str],
     publish: bool,
+    git_commit_sha: str,
     label: Optional[str] = None,
     transport: Optional[httpx.BaseTransport] = None,
 ) -> dict[str, Any]:
-    """POST the ontology tree to /api/ci/projects/{project_id}/ontology/import and return the response body."""
+    """POST the ontology tree to /api/ci/projects/{project_id}/ontology/import and return the response body.
+
+    ``git_commit_sha`` is the commit the files were read from, recorded on the
+    version the import publishes.
+    """
     url = api_url.rstrip("/") + f"/api/ci/projects/{project_id}/ontology/import"
-    body: dict[str, Any] = {"files": files, "publish": publish}
+    body: dict[str, Any] = {"files": files, "publish": publish, "git_commit_sha": git_commit_sha}
     if label is not None:
         body["label"] = label
     try:
@@ -915,13 +920,20 @@ def post_issue_status(
     project_id: str,
     issue_id: str,
     status: str,
+    reason: Optional[str] = None,
+    detail: Optional[str] = None,
+    confirm_published: bool = False,
     transport: Optional[httpx.BaseTransport] = None,
 ) -> dict[str, Any]:
     """POST /api/ci/projects/{project_id}/issues/{issue_id}/status and return the updated issue."""
     url = api_url.rstrip("/") + f"/api/ci/projects/{project_id}/issues/{issue_id}/status"
     try:
         with _client(transport=transport) as client:
-            response = client.post(url, json={"status": status}, headers={"Authorization": f"Bearer {api_key}"})
+            response = client.post(
+                url,
+                json={"status": status, "reason": reason, "detail": detail, "confirm_published": confirm_published},
+                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
 
@@ -1021,7 +1033,7 @@ def post_ontology_test(
     if response.status_code == 400:
         raise OntologyTestValidationError(_detail_or_text(response))
     if response.status_code == 402:
-        raise ApiError("Your organization has run out of credits. Contact your administrator to top up.")
+        raise ApiError("Your organization has run out of credits. Contact your Cassis administrator to top up.")
     if response.status_code in (403, 404):
         raise _project_scope_error(response)
     if response.status_code >= 400:

{cassis_cli-2.3.0 → cassis_cli-3.0.0}/cassis_cli/common.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import hashlib
 import os
 import re
 import subprocess
@@ -106,6 +107,133 @@ def git_file_states(directory: Path) -> Optional[tuple[set[str], set[str]]]:
     return tracked, dirty
 
 
+def require_committed_tree(path: Path, base_path: str, files: "dict[str, str]") -> str:
+    """Return the ``HEAD`` commit that holds exactly the ontology ``files`` about to be uploaded.
+
+    An upload records this commit on the version it publishes, so the uploaded
+    files must be the ontology files of ``base_path`` at ``HEAD``: the same paths
+    with the same text, up to line endings (``collect_files`` reads CRLF as LF,
+    and line endings carry no ontology meaning). ``files`` is what ``collect_tree`` read, keyed by path
+    relative to the base path. Exits 2 (usage) when ``path`` is not a git checkout
+    with a commit, or when the two differ: a file modified, staged, renamed,
+    deleted, untracked, gitignored, missing from a sparse checkout or inside a
+    submodule. Files the upload does not send never block.
+    """
+    ontology_dir = path / Path(base_path)
+    env = {**os.environ, "GIT_OPTIONAL_LOCKS": "0"}
+
+    def fail(reason: str) -> "typer.Exit":
+        typer.secho(
+            f"{reason} Upload the ontology from a git checkout of the repository that holds it: "
+            "Cassis records the commit each published version comes from.",
+            fg=typer.colors.RED,
+            err=True,
+        )
+        return typer.Exit(EXIT_USAGE)
+
+    def git(*args: str) -> str:
+        try:
+            proc = subprocess.run(
+                ["git", *args],
+                cwd=ontology_dir,
+                env=env,
+                capture_output=True,
+                text=True,
+                errors="replace",
+            )
+        except OSError as exc:
+            raise fail(f"Could not run git ({exc}).") from exc
+        if proc.returncode != 0:
+            detail = proc.stderr.strip().splitlines()
+            raise fail(f"{path} is not a git checkout with a commit" + (f" (git: {detail[0]})." if detail else "."))
+        return proc.stdout
+
+    head = git("rev-parse", "--verify", "HEAD").strip()
+    # Run from ontology_dir, ls-tree lists paths relative to it. A submodule is a
+    # "commit" entry, so the files inside it count as not committed.
+    committed: "dict[str, str]" = {}
+    for entry in git("ls-tree", "-r", "-z", "HEAD", ".").split("\0"):
+        if not entry:
+            continue
+        meta, rel = entry.split("\t", 1)
+        _mode, kind, blob = meta.split()
+        if kind == "blob" and is_ontology_file(rel):
+            committed[rel] = blob
+    # Compare the content about to be uploaded, not the files on disk: a clean
+    # filter can make a working-tree file hash to its committed blob while the
+    # text read from it differs. Its blob id is computed here; a blob that does
+    # not match is accepted when it holds the same text up to line endings,
+    # which `collect_files` already reads as LF (a CRLF commit uploads as LF).
+    differing_blobs = {
+        p: committed[p] for p in files if p in committed and _blob_id(files[p], committed[p]) != committed[p]
+    }
+    committed_text = _read_blobs(ontology_dir, env, set(differing_blobs.values()), fail)
+    differing = sorted(
+        {p for p in files if p not in committed}
+        | {p for p, blob in differing_blobs.items() if _lf(committed_text.get(blob)) != _lf(files[p])}
+        | (committed.keys() - files.keys())
+    )
+    if differing:
+        shown = "\n".join(f"  {base_path}/{p}" for p in differing[:20])
+        more = f"\n  … and {len(differing) - 20} more" if len(differing) > 20 else ""
+        typer.secho(
+            f"Uncommitted changes under {base_path}/ (these files differ from HEAD):\n{shown}{more}\n"
+            f"Commit the changes under {base_path}/, then upload again.",
+            fg=typer.colors.RED,
+            err=True,
+        )
+        raise typer.Exit(EXIT_USAGE)
+    return head
+
+
+def _blob_id(content: str, like: str) -> str:
+    """The git blob id of ``content``, in the hash ``like`` (a blob id of the repository) uses."""
+    data = content.encode("utf-8")
+    digest = hashlib.sha256() if len(like) == 64 else hashlib.sha1()
+    digest.update(b"blob %d\0" % len(data) + data)
+    return digest.hexdigest()
+
+
+def _read_blobs(
+    cwd: Path, env: "dict[str, str]", blobs: "set[str]", fail: "Callable[[str], typer.Exit]"
+) -> "dict[str, str]":
+    """Read committed blobs in one ``git cat-file --batch``, keyed by blob id; non-UTF-8 blobs are left out."""
+    if not blobs:
+        return {}
+    try:
+        proc = subprocess.run(
+            ["git", "cat-file", "--batch"],
+            cwd=cwd,
+            env=env,
+            input="".join(f"{blob}\n" for blob in sorted(blobs)).encode(),
+            capture_output=True,
+        )
+    except OSError as exc:
+        raise fail(f"Could not run git ({exc}).") from exc
+    if proc.returncode != 0:
+        raise fail(f"Could not read committed files (git: {proc.stderr.decode(errors='replace').strip()}).")
+    texts: "dict[str, str]" = {}
+    out, pos = proc.stdout, 0
+    while pos < len(out):
+        header_end = out.index(b"\n", pos)
+        fields = out[pos:header_end].split()
+        pos = header_end + 1
+        if len(fields) != 3:  # "<id> missing"
+            continue
+        size = int(fields[2])
+        try:
+            texts[fields[0].decode()] = out[pos : pos + size].decode("utf-8")
+        except UnicodeDecodeError:
+            pass
+        pos += size + 1  # the content is followed by a newline
+    return texts
+
+
+def _lf(text: Optional[str]) -> Optional[str]:
+    """``text`` with CRLF and CR line endings read as LF, as ``Path.read_text`` reads them."""
+    return None if text is None else text.replace("\r\n", "\n").replace("\r", "\n")
+
+
 def sync_ontology_tree(
     ontology_dir: Path,
     files: "dict[str, str]",

{cassis_cli-2.3.0 → cassis_cli-3.0.0}/cassis_cli/guide.py

@@ -31,7 +31,7 @@ GUIDE_FILENAME = "AGENTS.md"
 # Monotonic version of the doctrine text below. Bump it whenever
 # ontology_design_guide.md changes (a backend test enforces the pairing) — it
 # is what lets an older writer recognize a newer guide and leave it alone.
-DOCTRINE_VERSION = 7
+DOCTRINE_VERSION = 8
 
 # Must stay byte-identical to backend/app/services/ontology_guide.py::_BANNER —
 # the server-side git export writes the same file, and differing banners would

{cassis_cli-2.3.0 → cassis_cli-3.0.0}/cassis_cli/issues.py

@@ -10,6 +10,7 @@ conversations that arrived since the last pass, without waiting for the nightly
 from __future__ import annotations
 
 import json
+import sys
 from pathlib import Path
 from typing import Any, Optional
 
@@ -45,7 +46,8 @@ from cassis_cli.common import (
 
 app = typer.Typer(no_args_is_help=True, help="Triage the project's issues.")
 
-STATUSES = ("open", "resolved", "dismissed")
+STATUSES = ("open", "resolved", "dismissed", "all")
+DISMISS_REASONS = ("invalid", "irrelevant", "duplicate", "declined")
 IMPACTS = ("wrong_answer", "unreliable_answer", "no_answer", "inefficient")
 CAUSES = ("ontology_gap", "missing_data")
 
@@ -114,7 +116,7 @@ def _field(label: str, value: Any, *, blank_line: bool = False) -> None:
 
 @app.command(name="list")
 def list_issues(
-    status: Optional[str] = typer.Option(None, "--status", help=f"Filter by status ({', '.join(STATUSES)})."),
+    status: Optional[str] = typer.Option("open", "--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(
@@ -212,9 +214,23 @@ def show(
         f"{issue.get('occurrence_count_cache', len(occurrences))} occurrence(s)"
     )
     _field("Domains", ", ".join(issue.get("domains") or []) or None)
-    if issue.get("resolved_via"):
+    if issue.get("resolved_via") and issue.get("status") != "open":
         ref = issue.get("resolved_ref")
         _field("Resolved via", f"{issue['resolved_via']}{f' ({ref})' if ref else ''}")
+    _field("Dismiss reason", issue.get("dismiss_reason"))
+    _field("Dismiss detail", issue.get("dismiss_detail"))
+    if issue.get("fix_applied_at"):
+        _field("Fix", "Applied; awaiting publication")
+    for event in issue.get("status_history") or []:
+        _field(
+            "History",
+            f"{event.get('created_at')}  {event.get('from_status')} -> {event.get('to_status')}  "
+            f"{event.get('via')}  {event.get('actor_kind')}"
+            + (f"  {event['reason']}" if event.get("reason") else "")
+            + (f"  {event['detail']}" if event.get("detail") else "")
+            + (f"  {event['ref']}" if event.get("ref") else ""),
+        )
+
     _field("Description", issue.get("description"), blank_line=True)
     _field("Suggested action", issue.get("suggested_action"), blank_line=True)
     typer.echo("")
@@ -283,6 +299,9 @@ def _set_status(
     api_key: Optional[str],
     api_url: str,
     base_path: str,
+    reason: Optional[str] = None,
+    detail: Optional[str] = None,
+    confirm_published: bool = False,
 ) -> None:
     """Post a new status for the issue and confirm it on one line."""
     api_key = require_api_key(api_key)
@@ -295,6 +314,9 @@ def _set_status(
             project_id=project_id,
             issue_id=issue_id,
             status=status,
+            reason=reason,
+            detail=detail,
+            confirm_published=confirm_published,
         )
     except IssueNotFoundError as exc:
         raise _not_found_failure(exc) from exc
@@ -307,6 +329,11 @@ def _set_status(
 
 @app.command()
 def resolve(
+    published: bool = typer.Option(
+        False,
+        "--published",
+        help="Confirm the fix is in the published ontology; required without an interactive terminal.",
+    ),
     issue_id: str = typer.Argument(..., help="Id of the issue to resolve (from `cassis issues list`)."),
     path: Path = _PATH_OPTION,
     project_id: Optional[str] = _PROJECT_OPTION,
@@ -322,9 +349,18 @@ def resolve(
     go through a PR. Exits 0 on success, 1 when the issue does not exist in
     the project, 2 on usage errors, 3 on transport/API errors.
     """
+    if not published:
+        if not sys.stdin.isatty():
+            typer.secho(
+                "Use --published to confirm the fix is in the published ontology.", fg=typer.colors.RED, err=True
+            )
+            raise typer.Exit(EXIT_USAGE)
+        if not typer.confirm("Is the fix already in the published ontology?"):
+            raise typer.Exit(EXIT_USAGE)
     _set_status(
         issue_id=issue_id,
         status="resolved",
+        confirm_published=True,
         path=path,
         project_id=project_id,
         api_key=api_key,
@@ -335,6 +371,8 @@ def resolve(
 
 @app.command()
 def dismiss(
+    reason: str = typer.Option(..., "--reason", help=f"Why this issue is dismissed: {', '.join(DISMISS_REASONS)}."),
+    detail: Optional[str] = typer.Option(None, "--detail", help="Additional context for the dismissal."),
     issue_id: str = typer.Argument(..., help="Id of the issue to dismiss (from `cassis issues list`)."),
     path: Path = _PATH_OPTION,
     project_id: Optional[str] = _PROJECT_OPTION,
@@ -347,9 +385,12 @@ def dismiss(
     Exits 0 on success, 1 when the issue does not exist in the project, 2 on
     usage errors, 3 on transport/API errors.
     """
+    _validate_choice(reason, DISMISS_REASONS, "--reason")
     _set_status(
         issue_id=issue_id,
         status="dismissed",
+        reason=reason,
+        detail=detail,
         path=path,
         project_id=project_id,
         api_key=api_key,

{cassis_cli-2.3.0 → cassis_cli-3.0.0}/cassis_cli/ontology.py

@@ -29,6 +29,7 @@ from cassis_cli.common import (
 from cassis_cli.common import collect_tree as _collect_tree
 from cassis_cli.common import is_legacy_domain_file as _is_legacy_domain_file
 from cassis_cli.common import require_api_key as _require_api_key
+from cassis_cli.common import require_committed_tree as _require_committed_tree
 from cassis_cli.common import resolve_project_id as _resolve_project_id
 from cassis_cli.common import sync_ontology_tree as _sync_ontology_tree
 from cassis_cli.guide import DOCTRINE_VERSION, GUIDE_FILENAME, guide_status, refresh_guide
@@ -332,11 +333,14 @@ def upload(
 
     Replaces the project's unpublished ontology with the local tree (full
     replace) and, unless --no-publish is passed, publishes it immediately as a
-    new version. Exits 0 on success, 1 when the tree fails validation, 2 on
-    usage errors, 3 on transport/API errors.
+    new version. The checkout must be a git repository whose ontology files
+    match HEAD: the published version records that commit. Exits 0 on success,
+    1 when the tree fails validation, 2 on usage errors (including uncommitted
+    changes under the base path), 3 on transport/API errors.
     """
     api_key = _require_api_key(api_key)
     files, base_path = _collect_tree(path, base_path)
+    head = _require_committed_tree(path, base_path, files)
     project_id = _resolve_project_id(project_id, path / Path(base_path))
 
     try:
@@ -346,6 +350,7 @@ def upload(
             project_id=project_id,
             files=files,
             publish=publish,
+            git_commit_sha=head,
             label=label,
         )
     except AuthError as exc:

{cassis_cli-2.3.0 → cassis_cli-3.0.0}/cassis_cli/ontology_design_guide.md

@@ -484,14 +484,21 @@ checkout:
 Merging the pull request syncs and publishes the ontology; nothing reaches
 production answers until then.
 
-When the change came from a Cassis issue, merging is still not the last step.
-Confirm the published version contains it (`cassis status`, or
-`get_project_status` over MCP), then propose resolving that issue —
-`cassis issues resolve <id>`, or `update_issue_status`. Propose it to whoever
-owns the project: resolving needs the editor or admin role, and it records an
-outcome without changing any ontology. Never resolve before publication, and
-never silently — an issue nobody resolves stays in the triage queue and reads
-as a gap that was never fixed.
+When the change fixes Cassis issues, say so in the pull request instead of
+closing them by hand. Write one mention per issue in the PR description:
+`Resolves <id>` (the full id, or its first 13 characters or more; `Closes` and
+`Fixes` are accepted too). `cassis issues show <id>` prints the exact line to
+copy, as `PR mention:`. Cassis resolves each mentioned issue when the pull
+request merges and the ontology is published, and records the pull request on
+the issue, so the resolution carries the change that earned it.
+
+Resolving by hand is for outcomes that never go through a pull request:
+`cassis issues resolve <id>`, or `update_issue_status` over MCP. It needs the
+editor or admin role, changes no ontology, and belongs to whoever owns the
+project. Confirm first that the published version really contains the fix
+(`cassis status`, or `get_project_status`). Never resolve before publication,
+and never silently: an issue nobody resolves stays in the triage queue and
+reads as a gap that was never fixed.
 
 ---
 

{cassis_cli-2.3.0 → cassis_cli-3.0.0}/cassis_cli/schema.py

@@ -46,10 +46,11 @@ from cassis_cli.common import (
     collect_tree,
     poll_until,
     require_api_key,
+    require_committed_tree,
     resolve_project_id,
     sync_ontology_tree,
 )
-from cassis_cli.schema_plan import plan_counts, plan_is_empty, render_plan
+from cassis_cli.schema_plan import plan_counts, plan_extraction_complete, plan_is_empty, render_plan
 
 app = typer.Typer(help="Pull the data source's schema; plan, apply (locally) and push a schema update from DDL.")
 
@@ -219,7 +220,7 @@ def _require_one_source(
 @app.command()
 def plan(
     ddl_file: Optional[Path] = typer.Argument(
-        None, help="Path to the DDL file (.sql, .ddl, .txt) containing CREATE TABLE statements. Or --warehouse."
+        None, help="Path to the DDL file (.sql, .ddl, .txt) describing tables and views. Or --warehouse."
     ),
     warehouse: bool = _WAREHOUSE_OPTION,
     path: Path = _PATH_OPTION,
@@ -258,7 +259,7 @@ def plan(
 
     --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
+    still a PR (the desired schema snapshot) 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.
     """
@@ -282,6 +283,10 @@ def plan(
             json_output=json_output,
             out=out,
         )
+        if not plan_extraction_complete(preview):
+            if json_output:
+                typer.echo(json.dumps(preview, indent=2))
+            raise typer.Exit(EXIT_VALIDATION_FAILED)
         if write_checkout:
             ontology_dir = path / base_path.strip().strip("/")
             written, deleted, _kept = _write_checkout(ontology_dir, preview["files"], json_output=json_output)
@@ -309,7 +314,7 @@ def plan(
     )
     if json_output:
         typer.echo(json.dumps(record, indent=2))
-    if record.get("status") != "ready":
+    if record.get("status") != "ready" or not plan_extraction_complete(record):
         raise typer.Exit(EXIT_VALIDATION_FAILED)
     raise typer.Exit(EXIT_OK)
 
@@ -366,7 +371,7 @@ def apply(
         timeout=timeout,
         json_output=json_output,
     )
-    if record.get("status") != "ready":
+    if record.get("status") != "ready" or not plan_extraction_complete(record):
         raise typer.Exit(EXIT_VALIDATION_FAILED)
     try:
         checkout = get_schema_plan_checkout(
@@ -430,15 +435,17 @@ def push(
     Two steps, in order: the new schema (a DDL file, or the connected
     warehouse with --warehouse) is planned and applied server-side (new
     schema version, tracked schema updated, ontology edits the plan lists),
-    then the local ontology tree replaces the project's unpublished ontology
-    (so hand edits made after `cassis schema apply` land too). Pass --publish
-    to publish it as a new version. Exits 0 when pushed, 1 when the plan
-    failed / is stale or the upload was rejected, 2 on usage errors, 3 on
-    transport errors.
+    then the local ontology tree replaces the project's unpublished ontology.
+    Commit the tree `cassis schema apply` wrote, and any hand edits, before
+    pushing: the push refuses uncommitted changes under the base path, and a
+    published version records the commit. Pass --publish to publish it as a
+    new version. Exits 0 when pushed, 1 when the plan failed / is stale or the
+    upload was rejected, 2 on usage errors, 3 on transport errors.
     """
     api_key = require_api_key(api_key)
     _require_one_source(ddl_file, warehouse)
     files, base_path = collect_tree(path, base_path)
+    head = require_committed_tree(path, base_path, files)
     resolved_project = resolve_project_id(project_id, path / Path(base_path), quiet=json_output)
     assert resolved_project is not None
 
@@ -454,7 +461,7 @@ def push(
         timeout=timeout,
         json_output=json_output,
     )
-    if record.get("status") != "ready":
+    if record.get("status") != "ready" or not plan_extraction_complete(record):
         raise typer.Exit(EXIT_VALIDATION_FAILED)
     _require_marker_matches(path / Path(base_path), record)
     if not yes:
@@ -502,7 +509,13 @@ def push(
     typer.echo(f"Uploading {len(files)} ontology file(s)…", err=True)
     try:
         upload = post_ontology_import(
-            api_url=api_url, api_key=api_key, project_id=resolved_project, files=files, publish=publish, label=label
+            api_url=api_url,
+            api_key=api_key,
+            project_id=resolved_project,
+            files=files,
+            publish=publish,
+            git_commit_sha=head,
+            label=label,
         )
     except UploadValidationError as exc:
         typer.secho("Ontology upload rejected:", fg=typer.colors.RED, bold=True, err=True)
@@ -568,8 +581,8 @@ def _require_checkout_in_sync(
     if len(differing) > 10:
         typer.secho(f"  … {len(differing) - 10} more", fg=typer.colors.RED, err=True)
     typer.secho(
-        "Bring the checkout up to date first (`cassis ontology pull`), or push your local edits "
-        "(`cassis ontology upload --no-publish`), then apply again. `--force` overwrites the local files.",
+        "Bring the checkout up to date first (`cassis ontology pull`), or commit your local edits and push "
+        "them (`cassis ontology upload --no-publish`), then apply again. `--force` overwrites the local files.",
         fg=typer.colors.RED,
         err=True,
     )
@@ -764,7 +777,9 @@ def _plan(
             raise typer.Exit(EXIT_USAGE) from exc
     if record.get("status") == "ready":
         render_plan(record, err=json_output)
-        if plan_is_empty(record):
+        if not plan_extraction_complete(record):
+            pass  # The renderer already explains the blocking diagnostics.
+        elif plan_is_empty(record):
             typer.secho("✓ Schema is up to date.", fg=typer.colors.GREEN, err=json_output)
         else:
             typer.secho(f"✓ Plan ready: {plan_id}", fg=typer.colors.GREEN, err=json_output)
@@ -814,6 +829,8 @@ def _preview(
     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 not plan_extraction_complete(record):
+        return preview
     if plan_is_empty(record):
         typer.secho("✓ Schema is up to date (dry run, nothing kept).", fg=typer.colors.GREEN, err=json_output)
     else:

{cassis_cli-2.3.0 → cassis_cli-3.0.0}/cassis_cli/schema_plan.py

@@ -7,6 +7,7 @@ keeps stdout to the JSON record alone.
 
 from __future__ import annotations
 
+import json
 from typing import Any
 
 import typer
@@ -30,6 +31,39 @@ def _line(text: str, *, err: bool, mark: str | None = None, bold: bool = False)
 def render_plan(plan: dict[str, Any], *, err: bool) -> None:
     """Print the plan: schema diff, ontology changes with their cascade, warnings, footer."""
     document = plan.get("document") or {}
+    diagnostics = document.get("diagnostics") or []
+    if diagnostics:
+        _line(f"Extraction diagnostics ({len(diagnostics)})", err=err, bold=True)
+        for diagnostic in diagnostics:
+            location = diagnostic.get("object_name") or ""
+            if diagnostic.get("line") is not None:
+                location += f" line {diagnostic['line']}"
+                if diagnostic.get("column") is not None:
+                    location += f":{diagnostic['column']}"
+            severity = diagnostic.get("severity", "info")
+            _line(
+                f"  {severity}: {diagnostic.get('code')} {location.strip()}: {diagnostic.get('message')}",
+                err=err,
+                mark="-" if severity == "error" else "~",
+            )
+    if not plan_extraction_complete(plan):
+        objects = document.get("extracted_objects") or []
+        _line(f"Extracted objects ({document.get('extracted_object_count', len(objects))})", err=err, bold=True)
+        for obj in objects[:50]:
+            _line(
+                f"  {obj.get('schema_name')}.{obj.get('name')}  {obj.get('table_type')}"
+                f"  ({obj.get('column_count')} columns)",
+                err=err,
+            )
+        if len(objects) > 50 or document.get("extracted_objects_truncated"):
+            _line("  … list capped; use --json or --out for the full returned inventory", err=err)
+        _line(
+            "Schema extraction is incomplete. Resolve the errors and plan again; nothing can be applied.",
+            err=err,
+            mark="-",
+            bold=True,
+        )
+        return
     diff = document.get("schema_diff") or {}
     tables = diff.get("tables") or []
     _line(f"Schema diff ({len(tables)} table{'s' if len(tables) != 1 else ''})", err=err, bold=True)
@@ -44,6 +78,11 @@ def render_plan(plan: dict[str, Any], *, err: bool) -> None:
         if t.get("in_ontology"):
             suffix += "  (in ontology)"
         _line(f"  {mark} {name}{suffix}", err=err, mark=mark)
+        for metadata in t.get("metadata_changes") or []:
+            _line(f"      ~ {metadata.get('field')}", err=err, mark="~")
+            for label, value in (("from", metadata.get("old_value")), ("to", metadata.get("new_value"))):
+                formatted = value if isinstance(value, str) else json.dumps(value, indent=2, ensure_ascii=False)
+                _line(f"        {label}: " + formatted.replace("\n", "\n              "), err=err)
         for c in t.get("columns") or []:
             cmark = _MARK.get(c.get("kind", ""), "~")
             if c.get("kind") == "renamed":
@@ -127,4 +166,13 @@ def plan_counts(plan: dict[str, Any]) -> tuple[int, int, int, int]:
 def plan_is_empty(plan: dict[str, Any]) -> bool:
     document = plan.get("document") or {}
     diff = document.get("schema_diff") or {}
-    return not (diff.get("tables") or document.get("ontology_changes") or document.get("warnings"))
+    return plan_extraction_complete(plan) and not (
+        diff.get("tables") or document.get("ontology_changes") or document.get("warnings")
+    )
+
+
+def plan_extraction_complete(plan: dict[str, Any]) -> bool:
+    document = plan.get("document") or {}
+    return document.get("extraction_complete") is not False and not any(
+        d.get("severity") == "error" for d in document.get("diagnostics") or []
+    )

{cassis_cli-2.3.0 → cassis_cli-3.0.0}/cassis_cli/status.py

@@ -88,7 +88,13 @@ def _render(status_record: "dict[str, Any]", comparison_text: str) -> None:
     else:
         typer.echo("Git sync: not configured")
     schema_plan = status_record.get("schema_plan")
-    if isinstance(schema_plan, dict) and schema_plan.get("status") == "ready":
+    if (
+        isinstance(schema_plan, dict)
+        and schema_plan.get("status") == "ready"
+        and schema_plan.get("extraction_complete", True) is False
+    ):
+        typer.echo("Schema plan: blocked by incomplete extraction (create a new plan after resolving the errors)")
+    elif isinstance(schema_plan, dict) and schema_plan.get("status") == "ready":
         changes = schema_plan.get("ontology_changes")
         changes_text = f", {changes} ontology change(s)" if changes is not None else ""
         typer.echo(f"Schema plan: ready{changes_text} (cassis schema apply --plan {schema_plan.get('id')})")

{cassis_cli-2.3.0 → cassis_cli-3.0.0}/pyproject.toml

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