cassis-cli 3.1.0__tar.gz → 3.2.0__tar.gz

{cassis_cli-3.1.0 → cassis_cli-3.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cassis-cli
-Version: 3.1.0
+Version: 3.2.0
 Summary: Validate, test and evaluate your Cassis context from your terminal, then publish it
 License: Apache-2.0
 License-File: LICENSE
@@ -24,10 +24,10 @@ Description-Content-Type: text/markdown
 
 Validate, test and evaluate your context from your terminal, then publish it. The same commands gate your pull requests in CI:
 
-- `cassis context check` validates the context 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 **context 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 `context 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 context check` validates the context 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 **context 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, `enum_values` the column's type can't store (the same findings `context 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 context fmt` rewrites the context files in canonical form (think `black`/`gofmt` for your context), so hand or agent edits pass the round-trip check.
-- `cassis context upload` uploads the context 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 context files are committed, and the published version records that commit, so `cassis status` can tell whether a checkout matches what is live.
+- `cassis context upload` uploads the context 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 context files are committed, and the published version records that commit, even when the upload changes nothing, so `cassis status` can tell whether a checkout matches what is live.
 - `cassis context pull` downloads the project's unpublished context into your repository checkout (full sync: stale local context 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 context pull` and `cassis context fmt` also write `<base-path>/AGENTS.md`, the Cassis context design guide, into the checkout (default `cassis/AGENTS.md`). It is 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 context directory but is not part of the context 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 context 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).
@@ -55,7 +55,7 @@ The context tree under `<base-path>` (default `cassis/`) is:
 
 - **Project identity**: `project.yml`, the Cassis project id and format version. Written by `pull` and by server-side publish (the places that know the id); a local `fmt` won't create it.
 - **Domains**: Markdown files. Every domain is the `README.md` of its folder: `domains/README.md` for the root, `domains/<path>/README.md` for each sub-domain. Each has a small YAML frontmatter block (`type`, `title`, `description`) and a Markdown body carrying the domain's `context_md`; a generated section at the bottom links the domain's tables and metrics (kept current by `fmt`/`pull`: edit your prose above it, and the PR check fails if the links are stale, so re-run `fmt`). The layout is a Cassis profile inspired by [OKF](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf): the files render on GitHub and read in any Markdown editor, but Cassis validates them strictly (unknown keys are flagged, not preserved).
-- **Tables, joins, metrics**: YAML, unchanged: `tables/<schema>/<table>.yml`, `joins.yml`, `metrics/<name>.yml`.
+- **Tables, joins, metrics**: YAML, unchanged: `tables/<schema>/<table>.yml`, `joins.yml`, `metrics/<name>.yml`. A column can list the values it stores as `enum_values` (items `{value, description?}`, values quoted exactly as stored); see `cassis/AGENTS.md`.
 
 **Migrating an existing repo** (domains were YAML `_project.yml` / `_domain.yml` before cassis-cli 1.1.0): upgrade and run `cassis context fmt` (or `cassis context pull` if you have no local edits). It rewrites the domain files to Markdown and removes the old ones. Review the diff and commit. Cassis reads the old YAML domain files too, so an un-migrated repo keeps working until you convert it. **Uploading requires cassis-cli ≥ 1.1.0**: the server rejects an older CLI (which would drop the Markdown domain files) with a clear upgrade error.
 

{cassis_cli-3.1.0 → cassis_cli-3.2.0}/README.md

@@ -2,10 +2,10 @@
 
 Validate, test and evaluate your context from your terminal, then publish it. The same commands gate your pull requests in CI:
 
-- `cassis context check` validates the context 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 **context 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 `context 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 context check` validates the context 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 **context 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, `enum_values` the column's type can't store (the same findings `context 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 context fmt` rewrites the context files in canonical form (think `black`/`gofmt` for your context), so hand or agent edits pass the round-trip check.
-- `cassis context upload` uploads the context 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 context files are committed, and the published version records that commit, so `cassis status` can tell whether a checkout matches what is live.
+- `cassis context upload` uploads the context 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 context files are committed, and the published version records that commit, even when the upload changes nothing, so `cassis status` can tell whether a checkout matches what is live.
 - `cassis context pull` downloads the project's unpublished context into your repository checkout (full sync: stale local context 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 context pull` and `cassis context fmt` also write `<base-path>/AGENTS.md`, the Cassis context design guide, into the checkout (default `cassis/AGENTS.md`). It is 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 context directory but is not part of the context 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 context 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).
@@ -33,7 +33,7 @@ The context tree under `<base-path>` (default `cassis/`) is:
 
 - **Project identity**: `project.yml`, the Cassis project id and format version. Written by `pull` and by server-side publish (the places that know the id); a local `fmt` won't create it.
 - **Domains**: Markdown files. Every domain is the `README.md` of its folder: `domains/README.md` for the root, `domains/<path>/README.md` for each sub-domain. Each has a small YAML frontmatter block (`type`, `title`, `description`) and a Markdown body carrying the domain's `context_md`; a generated section at the bottom links the domain's tables and metrics (kept current by `fmt`/`pull`: edit your prose above it, and the PR check fails if the links are stale, so re-run `fmt`). The layout is a Cassis profile inspired by [OKF](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf): the files render on GitHub and read in any Markdown editor, but Cassis validates them strictly (unknown keys are flagged, not preserved).
-- **Tables, joins, metrics**: YAML, unchanged: `tables/<schema>/<table>.yml`, `joins.yml`, `metrics/<name>.yml`.
+- **Tables, joins, metrics**: YAML, unchanged: `tables/<schema>/<table>.yml`, `joins.yml`, `metrics/<name>.yml`. A column can list the values it stores as `enum_values` (items `{value, description?}`, values quoted exactly as stored); see `cassis/AGENTS.md`.
 
 **Migrating an existing repo** (domains were YAML `_project.yml` / `_domain.yml` before cassis-cli 1.1.0): upgrade and run `cassis context fmt` (or `cassis context pull` if you have no local edits). It rewrites the domain files to Markdown and removes the old ones. Review the diff and commit. Cassis reads the old YAML domain files too, so an un-migrated repo keeps working until you convert it. **Uploading requires cassis-cli ≥ 1.1.0**: the server rejects an older CLI (which would drop the Markdown domain files) with a clear upgrade error.
 

{cassis_cli-3.1.0 → cassis_cli-3.2.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 = 9
+DOCTRINE_VERSION = 10
 
 # 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-3.1.0 → cassis_cli-3.2.0}/cassis_cli/ontology.py

@@ -375,7 +375,13 @@ def upload(
             f"{result['join_count']} joins, {result['metric_count']} metrics"
         )
         version = result.get("published_version")
-        if version is not None:
+        if version is not None and result.get("unchanged"):
+            typer.secho(
+                f"✓ Context uploaded ({counts}). No change: v{version} stays published, "
+                f"and now records commit {head[:9]}.",
+                fg=typer.colors.GREEN,
+            )
+        elif version is not None:
             typer.secho(f"✓ Context uploaded and published as v{version} ({counts}).", fg=typer.colors.GREEN)
         else:
             typer.secho(

{cassis_cli-3.1.0 → cassis_cli-3.2.0}/cassis_cli/ontology_design_guide.md

@@ -22,7 +22,7 @@ with domains as Markdown and everything else as YAML:
 | **Root context** (`domains/README.md` body) | One free-text block, always in the agent's prompt | markdown |
 | **Domains** | A navigable tree grouping the business by subject area | `path`, `display_name`, `description`, `context_md` |
 | **Tables** | A physical warehouse table (introspected) or a virtual one (SQL-defined) placed in a domain | `name` (`schema.TABLE`), `description`, `synonyms`, `grain`, columns |
-| **Columns** | Enrichment on a table's columns | `description`, `unit`, `synonyms` |
+| **Columns** | Enrichment on a table's columns | `description`, `unit`, `synonyms`, `enum_values` |
 | **Joins** | A known way two tables relate | `from_schema`/`from_table`, `to_schema`/`to_table`, `column_pairs`, `condition_sql`, `cardinality`, `description` |
 | **Metrics** | A reusable business measure | `name`, `display_name`, `expression`, `table_schema`/`table_name`, `filters`, `unit`, `synonyms`, `notes`, `precomputed_in` |
 
@@ -50,8 +50,8 @@ edit surface: you edit the files, open a pull request, and merging syncs and
 publishes it.
 
 Physical tables and their columns come from schema introspection — you never
-invent them; you *enrich* them (place them in a domain, describe them, set units
-and synonyms). The one exception is a virtual table, which you define with a
+invent them; you *enrich* them (place them in a domain, describe them, set units,
+synonyms and stored values). The one exception is a virtual table, which you define with a
 `sql` body (see §5).
 
 The one governing principle everything below serves:
@@ -106,7 +106,7 @@ and must match the warehouse (see §7).
 Put each fact at the lowest layer that fully owns it:
 
 ```
-column synonym / column description      single-column facts: meaning, encoding, unit, date format, nulls
+column enum_values / synonym / description   single-column facts: stored values, meaning, encoding, unit, date format, nulls
   → table description                    single-table facts: scope, mandatory filters, "use this not that"
     → domain context_md                  cross-table routing, disambiguation, vocabulary spanning tables
       → root context                     truly global rules only: corporate identity, entity hierarchy, global conventions
@@ -223,11 +223,31 @@ in the `sql` per §7.
 
 ## 6. Columns
 
-Column enrichment is `description`, `unit`, and `synonyms` — you cannot add or
-rename columns (they come from introspection). The agent sees a column's name,
-type, `unit` and `synonyms` structurally; the `description` carries what those
-don't: meaning, possible values, encoding, date format, null behavior, any
-mandatory filter.
+Column enrichment is `description`, `unit`, `synonyms` and `enum_values` — you
+cannot add or rename columns (they come from introspection). The agent sees a
+column's name, type, `unit`, `synonyms` and `enum_values` structurally; the
+`description` carries what those don't: meaning, encoding, date format, null
+behavior, any mandatory filter.
+
+- **Stored values go in `enum_values`, not in the description.** A categorical
+  column with a small, stable set (a status, type, tier, code) lists every value
+  it stores in `enum_values`, verbatim and case-exact, in a meaningful order
+  (ordinal sets keep their order). A value's meaning goes in that value's own
+  `description`; the column `description` says what the column *means* and never
+  lists values. Free text, identifiers and high-cardinality columns get no
+  `enum_values`; a few notable codes in a large column stay in the description.
+  How to get the list right, and what to do with value lists already written in
+  prose, is §10.
+
+  ```yaml
+  columns:
+  - description: Lifecycle stage of the subscription.
+    enum_values:
+    - value: ACTIVE
+    - value: CANCELLED
+      description: Cancelled by the customer; access runs to period end.
+    name: status
+  ```
 
 - **Prioritize the trap columns.** Disambiguate similarly-named columns
   (`created_at` vs `updated_at`, `amount` vs `net_amount`), numeric-encoded
@@ -370,7 +390,9 @@ warehouse's stored case**, or generated SQL fails with errors like
   `grain`, join endpoints (`from_schema`/`from_table`/…), `column_pairs` and
   `condition_sql`, and metric `table_schema`/`table_name`/`expression`/`filters`. Logical fields — domain paths, display names, descriptions,
   **synonyms**, `context_md` — stay natural language; the matching layer there is
-  case-insensitive and should read naturally.
+  case-insensitive and should read naturally. A column's `enum_values` are data
+  literals, not identifiers, but they are matched exactly too: write each value
+  as stored, case included.
 - **Schema-qualify everything.** Table references in SQL and prose carry the
   `schema.TABLE` form (`dbt_core.fct_orders`), so a scope rule about `raw.users`
   never accidentally catches `core.users`, and a prefix that doesn't match what
@@ -383,12 +405,22 @@ warehouse's stored case**, or generated SQL fails with errors like
 An inaccurate example primes the agent **more strongly** than a correct prose
 description, so a wrong example is worse than none.
 
-- **Use real stored enum values verbatim.** Never hand-wave a list with "etc." —
-  the agent reads `etc.` as license to invent values. If you don't have the exact
-  values, omit the list rather than approximate it. A `DISTINCT` over the column
-  *is* the list of stored values: write it plainly ("Stored values: 'EDITOR'"),
-  with no "observed so far" hedge and no counts. When two columns supposedly
-  share an enum, verify they're identical before encoding both.
+- **`enum_values` is the complete set of stored values, verbatim.** The agent
+  treats it as closed: filter literals come from it, exact case, and a value it
+  doesn't list does not exist. Verify the set against the source before writing
+  it — a `SELECT DISTINCT` over the column, or a `CHECK ... IN (...)` constraint
+  the schema shows — and write it plainly, with no "observed so far" hedge and no
+  counts. If you don't have the exact set, leave `enum_values` out rather than
+  approximate it: a partial list is worse than none, because the agent stops
+  looking for other values. When two columns supposedly share an enum, verify
+  they're identical before encoding both.
+- **Move value lists out of prose.** Older descriptions list values in text
+  ("Possible values: …", "Values:", "One of:", "Stored values: 'EDITOR'"). When
+  you touch a table and find one, move the list into that column's `enum_values`
+  and delete it from the description in the same change, verifying it against
+  the source first when you can. A hedged or open-ended prose list ("etc.",
+  "includes", "e.g.", "and legacy …") is **not** the complete set: verify it, or
+  drop it without promoting it. Never turn an approximation into `enum_values`.
 - **Be wary of analogies to external products** — they mislead the moment the
   real mechanic diverges.
 - **Don't describe things that don't exist.** Every table, column, and value you
@@ -430,10 +462,10 @@ description, so a wrong example is worse than none.
   definitions, not what the data shows today. Row counts, distinct counts, shares,
   distributions, funnel rates and "as of" / "currently" / "observed" statements go
   stale silently, and the answering agent repeats them as fact. Query the data to
-  *verify* a stable fact (stored enum values, a date format, null behaviour) and
-  write only the fact: "Stored values: 'EDITOR', 'ADMIN'", not "only 'EDITOR'
-  observed (6 of 6, 100%)". Complete value lists and constants the business fixes
-  (a 14-day trial) are facts, not measurements.
+  *verify* a stable fact (a column's stored values, a date format, null
+  behaviour) and write only the fact: the values in `enum_values`, not "only
+  'EDITOR' observed (6 of 6, 100%)" in prose. Complete value sets and constants
+  the business fixes (a 14-day trial) are facts, not measurements.
 - **Ask for the business meaning; don't guess.** A term like "active user" or
   "last month" has a project-specific definition (time window, criteria, filters).
   Encode the business's actual definition, not a textbook default.

{cassis_cli-3.1.0 → cassis_cli-3.2.0}/cassis_cli/status.py

@@ -71,12 +71,25 @@ def _local_comparison(path: Path, head: Optional[str], published_sha: Optional[s
     return f"diverged from the published commit {published_sha[:9]}", False
 
 
+def _published_commit(published: "dict[str, Any]") -> Optional[str]:
+    """The newest commit known to hold the published content.
+
+    An upload that changes nothing publishes no version but moves
+    `latest_git_commit_sha` forward. Servers older than that field only send
+    `git_commit_sha`, the commit the version was published from.
+    """
+    return published.get("latest_git_commit_sha") or published.get("git_commit_sha")
+
+
 def _render(status_record: "dict[str, Any]", comparison_text: str) -> None:
     published = status_record.get("published_version")
     if published:
         label = f" {published['label']!r}" if published.get("label") else ""
         sha = published.get("git_commit_sha")
+        latest = _published_commit(published)
         sha_text = f", commit {sha[:9]}" if sha else ""
+        if latest and latest != sha:
+            sha_text += f", unchanged at {latest[:9]}"
         typer.echo(f"Published: v{published['version']}{label} ({published.get('published_at')}{sha_text})")
     else:
         typer.echo("Published: nothing yet")
@@ -164,7 +177,7 @@ def status(
         """The status record plus the local comparison it implies: (record, comparison_text, in_sync)."""
         record = get_project_status(api_url=api_url, api_key=api_key, project_id=project_id)
         published = record.get("published_version") or {}
-        comparison_text, in_sync = _local_comparison(path, head, published.get("git_commit_sha"))
+        comparison_text, in_sync = _local_comparison(path, head, _published_commit(published))
         return record, comparison_text, in_sync
 
     def report(snapshot: "Tuple[dict[str, Any], str, bool]") -> None:
@@ -175,7 +188,7 @@ def status(
             _render(record, comparison_text)
         else:
             published = record.get("published_version") or {}
-            published_sha = published.get("git_commit_sha")
+            published_sha = _published_commit(published)
             version_text = f"v{published['version']}" if published else "nothing published"
             line = f"{version_text} (commit {published_sha[:9] if published_sha else 'none'}); local: {comparison_text}"
             if line != last_line["text"]:

{cassis_cli-3.1.0 → cassis_cli-3.2.0}/pyproject.toml

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