katalyst-taxonomy-cli 2.0.1a2__tar.gz → 2.0.1a4__tar.gz

{katalyst_taxonomy_cli-2.0.1a2 → katalyst_taxonomy_cli-2.0.1a4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: katalyst-taxonomy-cli
-Version: 2.0.1a2
+Version: 2.0.1a4
 Summary: CLI for katalyst-taxonomy — the kata command
 Author: eSimplicity
 License: Proprietary
@@ -8,5 +8,12 @@ Requires-Python: >=3.12
 Requires-Dist: click>=8.1
 Requires-Dist: katalyst-core<1,>=0.1
 Requires-Dist: katalyst-engine<6,>=5
+Requires-Dist: katalyst-plugin-context<1,>=0.2
+Requires-Dist: katalyst-plugin-harness<1,>=0.1
+Requires-Dist: katalyst-plugin-scaffolding<2,>=1
 Requires-Dist: katalyst-taxonomy-mcp<5,>=4
 Requires-Dist: katalyst-taxonomy<6,>=5
+Provides-Extra: bard
+Requires-Dist: katalyst-plugin-bard<1,>=0.1; extra == 'bard'
+Provides-Extra: tui
+Requires-Dist: katalyst-taxonomy-tui<3,>=2; extra == 'tui'

{katalyst_taxonomy_cli-2.0.1a2 → katalyst_taxonomy_cli-2.0.1a4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "katalyst-taxonomy-cli"
-version = "2.0.1a2"
+version = "2.0.1a4"
 description = "CLI for katalyst-taxonomy — the kata command"
 license = { text = "Proprietary" }
 requires-python = ">=3.12"
@@ -15,8 +15,20 @@ dependencies = [
     "katalyst-engine>=5,<6",
     "click>=8.1",
     "katalyst-core>=0.1,<1",
+    # The plugins that ship with kata: `kata tax context|harness|add`. Bounded to the
+    # config-rooted runtime, like the plugins' own floors on this package (a cycle pip
+    # and uv both resolve: a plugin's command imports this package's context and options).
+    "katalyst-plugin-context>=0.2,<1",
+    "katalyst-plugin-harness>=0.1,<1",
+    "katalyst-plugin-scaffolding>=1,<2",
 ]
 
+[project.optional-dependencies]
+# `kata tax bard`: the web UI plugin.
+bard = ["katalyst-plugin-bard>=0.1,<1"]
+# `kata tui`: the terminal UI.
+tui = ["katalyst-taxonomy-tui>=2,<3"]
+
 [project.scripts]
 kata = "katalyst_taxonomy_cli.__main__:main"
 

{katalyst_taxonomy_cli-2.0.1a2 → katalyst_taxonomy_cli-2.0.1a4}/src/katalyst_taxonomy_cli/_wiring.py

@@ -123,7 +123,9 @@ def _named(registry: BackendRegistry, target: str | None, address: str) -> tuple
     A prefix and ``--backend`` that disagree is an error rather than one silently
     winning: the command was told two different stores.
     """
-    if address:
+    from katalyst_taxonomy.config.routing import split_backend_prefix
+
+    if address and (target is None or split_backend_prefix(address)[0] is not None):
         parsed = registry.address(address)
         if target and target != parsed.backend:
             raise click.ClickException(
@@ -135,7 +137,7 @@ def _named(registry: BackendRegistry, target: str | None, address: str) -> tuple
             from katalyst_taxonomy.config.routing import UnknownBackendError
 
             raise UnknownBackendError(target, registry.profile_backends())
-        return target, ""
+        return target, address
     return None, ""
 
 

{katalyst_taxonomy_cli-2.0.1a2 → katalyst_taxonomy_cli-2.0.1a4}/src/katalyst_taxonomy_cli/app.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import importlib.util
 import subprocess
 import sys
 from pathlib import Path
@@ -77,6 +78,42 @@ class KataGroup(click.Group):
             raise click.ClickException(str(exc)) from exc
 
 
+def _missing_extra(name: str) -> str | None:
+    """The extra of this package named *name* whose requirements are not installed.
+
+    A command group a plugin contributes is offered as an extra of the same name
+    (``katalyst-taxonomy-cli[<name>]``). Read from this distribution's own metadata, so
+    the CLI names no plugin: ``None`` when there is no such extra, or it is installed.
+    """
+    import importlib.metadata as metadata
+    import re
+
+    try:
+        requirements = metadata.requires("katalyst-taxonomy-cli") or []
+    except metadata.PackageNotFoundError:
+        return None
+    marker = re.compile(rf"""extra\s*==\s*['"]{re.escape(name)}['"]""")
+    wanted = [r for r in requirements if marker.search(r)]
+    if not wanted:
+        return None
+    for requirement in wanted:
+        distribution = re.split(r"[\s;<>=!~\[(]", requirement, maxsplit=1)[0]
+        try:
+            metadata.distribution(distribution)
+        except metadata.PackageNotFoundError:
+            return name
+    return None
+
+
+def _not_installed_message(extra: str, label: str) -> str:
+    return (
+        f"{label} is not installed. Install it with:\n"
+        f"    pip install 'katalyst-taxonomy-cli[{extra}]'\n"
+        f"or, for a uv tool install:\n"
+        f"    uv tool install 'katalyst-taxonomy-cli[{extra}]'"
+    )
+
+
 class TaxGroup(click.Group):
     """The ``tax`` group, which resolves plugin-contributed commands **lazily**.
 
@@ -114,6 +151,16 @@ class TaxGroup(click.Group):
         self._ensure_plugin_commands(ctx)
         return super().get_command(ctx, cmd_name)
 
+    def resolve_command(
+        self, ctx: click.Context, args: list[str]
+    ) -> tuple[str | None, click.Command | None, list[str]]:
+        name = args[0] if args else None
+        if name and self.get_command(ctx, name) is None:
+            extra = _missing_extra(name)
+            if extra is not None:
+                raise click.ClickException(_not_installed_message(extra, f"`kata tax {name}`"))
+        return super().resolve_command(ctx, args)
+
     def _ensure_plugin_commands(self, ctx: click.Context) -> None:
         if self._plugin_commands_resolved:
             return
@@ -159,6 +206,13 @@ def _installed_katalyst_packages() -> list[tuple[str, str]]:
     return sorted(found.items())
 
 
+def _schema_versions() -> list[tuple[str, str]]:
+    """Every schema installed (katalyst-core, and each bundle), with its version."""
+    from katalyst_engine.evolution import installed_releases
+
+    return [(release.name, str(release.version)) for release in installed_releases()]
+
+
 def _print_version(ctx: click.Context, _param: click.Parameter, value: bool) -> None:
     if not value or ctx.resilient_parsing:
         return
@@ -170,6 +224,12 @@ def _print_version(ctx: click.Context, _param: click.Parameter, value: bool) ->
     click.echo(f"kata {__version__}")
     for name, version in _installed_katalyst_packages():
         click.echo(f"  {name} {version}")
+    click.echo("schemas:")
+    try:
+        for name, version in _schema_versions():
+            click.echo(f"  {name} {version}")
+    except Exception as exc:  # a bundle that does not load must not hide the versions
+        click.echo(f"  unavailable: {exc}")
     for line in install_lines():
         click.echo(line)
     try:
@@ -227,8 +287,8 @@ def _select_home(ctx: click.Context, _param: click.Parameter, value: str | None)
     # Not eager, so it runs after --home (which is) and reports the home chosen.
     callback=_print_version,
     help=(
-        "Show the kata version, every installed Katalyst package, the install (and what it "
-        "was built from) and the home, then exit."
+        "Show the kata version, every installed Katalyst package, the schema bundles with "
+        "their versions, the install (and what it was built from) and the home, then exit."
     ),
 )
 @click.option(
@@ -295,7 +355,12 @@ def _configure_logging() -> None:
 
 @cli.command("tui")
 def tui_cmd() -> None:
-    """Launch the interactive terminal UI."""
+    """Launch the interactive terminal UI.
+
+    The UI is an extra: ``pip install 'katalyst-taxonomy-cli[tui]'``.
+    """
+    if importlib.util.find_spec("katalyst_taxonomy_tui") is None:
+        raise click.ClickException(_not_installed_message("tui", "the terminal UI"))
     try:
         subprocess.run(
             [sys.executable, "-m", "katalyst_taxonomy_tui"],
@@ -466,12 +531,14 @@ def _register_core_commands() -> None:
         kinds,
         lifecycle,
         lint,
+        migrate,
         plugin,
         promote,
         query,
         relate,
         relocate,
         remove,
+        rescaffold,
         resolve,
         rollback,
         self_update,
@@ -505,6 +572,7 @@ def _register_core_commands() -> None:
     tax.add_command(show.show)
     tax.add_command(kinds.kinds)
     tax.add_command(lint.lint)
+    tax.add_command(migrate.migrate)
     tax.add_command(deps.deps)
     tax.add_command(status.status)
     tax.add_command(rollback.rollback)
@@ -528,6 +596,7 @@ def _register_core_commands() -> None:
     tax.add_command(export.export)
     tax.add_command(backend.backend)
     tax.add_command(remove.remove)
+    tax.add_command(rescaffold.rescaffold)
 
 
 def resolve_plugin_commands() -> None:

{katalyst_taxonomy_cli-2.0.1a2 → katalyst_taxonomy_cli-2.0.1a4}/src/katalyst_taxonomy_cli/commands/config_schemas.py

@@ -60,7 +60,11 @@ def build_schemas_payload(
     from katalyst_taxonomy.config.schemas import selection_from_config
     from katalyst_taxonomy.engine import bridge
     from katalyst_taxonomy.services.schema_gate import check_declared_bundles
-    from katalyst_taxonomy.services.schema_report import schemas_payload
+    from katalyst_taxonomy.services.schema_report import (
+        core_schema,
+        schema_versions,
+        schemas_payload,
+    )
     from katalyst_taxonomy.sources.template_resolver import TemplateResolver
 
     effective = config_resolver().resolve(profile=profile)
@@ -90,6 +94,8 @@ def build_schemas_payload(
                 if candidate.distribution
             },
             declared=declared,
+            schema_versions=schema_versions(candidates),
+            core_schema=core_schema(),
             scaffold_providers=resolver.scaffold_template_providers(),
             repo_root=None,
             filesystem=RealFilesystem(),
@@ -155,19 +161,24 @@ def _render_text(out: OutputPort, payload: dict[str, Any]) -> None:
         ]
     )
 
+    core = payload.get("core")
+    if core:
+        out.key_value([("katalyst-core schema", _schema_text(core))])
+
     out.heading("Bundles")
     bundles: list[dict[str, Any]] = payload["bundles"]
     if not bundles:
         out.info("No schema bundles discovered.")
     else:
         out.table(
-            ["", "bundle", "distribution", "version", "kinds", "note"],
+            ["", "bundle", "distribution", "version", "schema", "kinds", "note"],
             [
                 [
                     "*" if entry["enabled"] else "x",
                     str(entry["name"]),
                     str(entry.get("distribution") or "-"),
                     str(entry.get("resolvedVersion") or entry["version"] or "-"),
+                    _schema_text(entry.get("schema")),
                     str(len(entry["kinds"])),
                     str(
                         entry["reason"] or entry.get("sourceWarning") or entry["entryPoint"] or "-"
@@ -239,6 +250,19 @@ def _render_text(out: OutputPort, payload: dict[str, Any]) -> None:
         )
 
 
+def _schema_text(schema: dict[str, Any] | None) -> str:
+    """``9.0.0 (unreleased; latest archived 8.0.0)``: a schema's version and archive state."""
+    if not schema:
+        return "-"
+    from katalyst_engine.core.version import Version
+    from katalyst_engine.evolution import ArchiveState
+
+    archive = schema["archive"]
+    latest = archive["latest"]
+    state = ArchiveState(archive["state"], Version.parse(latest) if latest else None)
+    return f"{schema['version']} ({state})"
+
+
 def attach(group: click.Group) -> None:
     """Add ``schemas`` to the ``kata config`` group.
 

{katalyst_taxonomy_cli-2.0.1a2 → katalyst_taxonomy_cli-2.0.1a4}/src/katalyst_taxonomy_cli/commands/core.py

@@ -23,6 +23,12 @@
                                        the diff
     kata core schema archive --bundle B
                                        archive the current modules as the released version
+    kata core schema docs [PATH...] [--bundle B] [--check] [--kind K]
+                                       write the generated field tables of the pages
+                                       under PATH; --check fails when any is stale
+    kata core schema changelog [--bundle B] [--from VERSION]
+                                       the "Schema changes" section of a release: what was
+                                       added, what broke, and the migration step for each
 
 Records and graphs are read against every installed module (``katalyst_core.modules``).
 """
@@ -466,3 +472,118 @@ def schema_archive(bundle: str) -> None:
     except (FileExistsError, SchemaVersionMismatchError) as exc:
         raise click.ClickException(str(exc)) from exc
     click.echo(f"Archived {release.name} {release.version} in {target}")
+
+
+# Named from the function (``docs``), so no command-name literal reads as a bundle name.
+@schema.command()
+@click.argument("paths", nargs=-1, type=click.Path(exists=True, path_type=Path))
+@click.option(
+    "--bundle",
+    "bundle",
+    default=None,
+    help="Read kinds from this schema only (needed when two define the same kind).",
+)
+@click.option(
+    "--check",
+    is_flag=True,
+    help="Write nothing; fail when a generated region is stale (for CI).",
+)
+@click.option(
+    "--kind",
+    "kind",
+    default=None,
+    help="Print the markdown for one kind (to start a page), and write nothing.",
+)
+def docs(paths: tuple[Path, ...], bundle: str | None, check: bool, kind: str | None) -> None:
+    """Write the generated field tables of the markdown pages under PATH.
+
+    A page marks where a table goes with a line of its own, ``<!-- generated:kind:NAME -->``
+    (a kind's parent and fields: type, required, allowed values, references and their
+    relationship types, descriptions) or ``<!-- generated:wing:NAME -->`` (a wing's kinds:
+    where each is stored and its parent), and closes it with ``<!-- /generated -->``. The
+    text between is rewritten from the schemas' LinkML modules; everything else on the page
+    is yours.
+    """
+    from katalyst_engine.schema_docs import (
+        DocsError,
+        RegionError,
+        catalog_from_releases,
+        page_files,
+        refresh_page,
+        render_kind,
+    )
+
+    if kind is None and not paths:
+        raise click.UsageError("name the pages to write: one or more files or directories")
+    catalog = catalog_from_releases(_releases(bundle))
+    try:
+        if kind is not None:
+            click.echo(render_kind(catalog.kind(kind, bundle=bundle)))
+            return
+        stale_total = 0
+        for page in page_files(paths):
+            text = page.read_text(encoding="utf-8")
+            try:
+                new_text, stale = refresh_page(text, catalog, bundle=bundle)
+            except (RegionError, DocsError) as exc:
+                raise click.ClickException(f"{page}: {exc}") from exc
+            stale_total += len(stale)
+            for region in stale:
+                click.echo(f"{page}:{region.line}: generated:{region.label} is stale")
+            if stale and not check:
+                page.write_text(new_text, encoding="utf-8")
+    except DocsError as exc:
+        raise click.ClickException(str(exc)) from exc
+    if check:
+        if stale_total:
+            raise click.ClickException(
+                f"{stale_total} generated region(s) are stale; "
+                f"run kata core schema docs {' '.join(str(p) for p in paths)}"
+            )
+        click.echo("generated regions are current")
+    else:
+        click.echo(f"Updated {stale_total} generated region(s)")
+
+
+@schema.command("changelog")
+@_BUNDLE
+@click.option(
+    "--from",
+    "since",
+    default=None,
+    help="The archived version to compare with (default: the latest).",
+)
+@click.option(
+    "--heading-level",
+    "level",
+    type=click.IntRange(1, 5),
+    default=2,
+    show_default=True,
+    help="The level of the section's heading (2: ##).",
+)
+def schema_changelog(bundle: str | None, since: str | None, level: int) -> None:
+    """The "Schema changes" section of a release, from the classified diff and the migration.
+
+    For each schema whose modules changed since its last archived version: what was added,
+    what broke, and for each breaking change the `kata tax migrate` step that handles it
+    (or the reason it is accepted). Markdown on stdout, for the release notes.
+    """
+    from katalyst_engine.core.version import Version
+    from katalyst_engine.evolution import build_changelog, render_changelog
+
+    logs: list[Any] = []
+    for release in _releases(bundle):
+        try:
+            old = Version.parse(since) if since else None
+            log = build_changelog(release, old)
+        except (ValueError, FileNotFoundError) as exc:
+            raise click.ClickException(str(exc)) from exc
+        if log is None:
+            click.echo(f"{release.name}: no released version is archived", err=True)
+        else:
+            logs.append(log)
+    text = render_changelog(logs, level=level)
+    if not text:
+        click.echo("No schema changes since the last released version.", err=True)
+        return
+    click.echo(text, nl=False)

{katalyst_taxonomy_cli-2.0.1a2 → katalyst_taxonomy_cli-2.0.1a4}/src/katalyst_taxonomy_cli/commands/create.py

@@ -41,7 +41,24 @@ from katalyst_taxonomy_cli.context import CliContext
     "from_file",
     default=None,
     metavar="PATH",
-    help="Spec fields from a YAML or JSON file (- for stdin); --set applies over them.",
+    help=(
+        "Spec fields from a YAML or JSON file (- for stdin), or a whole document's spec, "
+        "labels and annotations; --set, --label and --annotation apply over them."
+    ),
+)
+@click.option(
+    "--label",
+    "label_pairs",
+    multiple=True,
+    metavar="KEY=VALUE",
+    help="Set a label (metadata.labels), which filters and permission grants match. Repeat.",
+)
+@click.option(
+    "--annotation",
+    "annotation_pairs",
+    multiple=True,
+    metavar="KEY=VALUE",
+    help="Set an annotation (metadata.annotations), a record nothing matches on. Repeat.",
 )
 @click.option("--target-dir", default=None, help="Override output directory.")
 @click.option(
@@ -75,6 +92,8 @@ def create(
     scaffold_variant: str | None,
     set_fields: tuple[str, ...],
     from_file: str | None,
+    label_pairs: tuple[str, ...],
+    annotation_pairs: tuple[str, ...],
     target_dir: str | None,
     backend_target: str | None,
     dry_run: bool,
@@ -96,24 +115,34 @@ def create(
     a value of its type (boolean, integer, list, map) and allowed values, a reference
     naming a node of the referenced kind.
 
+    --label KEY=VALUE and --annotation KEY=VALUE go in the node's metadata, on any kind.
+    A key is a name of letters, digits, '-', '_' and '.' (at most 63), optionally after a
+    DNS prefix and '/' (example.org/team); a label's value is such a name (or empty), an
+    annotation's any text.
+
     Examples:
 
-        kata tax create stage verify --set halt_on_failure=false --set concern_order=maintainability
+        kata tax create layer api --under shop.backend --set audited=false --set tier=gold
+
+        kata tax create layer worker --under shop.backend --set priority=10 --set limits.region=eu-west
 
-        kata tax create operation probe --set order=10 --set scope.regions=eu-west
+        kata tax create capability checkout --under shop --set 'hooks=[{"on":"push","branches":["main"]}]'
 
-        kata tax create venue ci --set 'triggers=[{"on":"push","environments":["dev"]}]'
+        kata tax create stack web --under shop --set limits.log_level=debug
 
-        kata tax create environment qa --set template_replacements.log_level=debug
+        kata tax create layer api --under shop.backend --label team=payments --annotation source=docs/api.md
     """
     from katalyst_taxonomy.adapters.orchestration import run_create
     from katalyst_taxonomy.config.routing import split_backend_prefix
 
-    from katalyst_taxonomy_cli.fields import parse_set, read_spec_file
+    from katalyst_taxonomy_cli.fields import parse_pairs, parse_set, read_node_file
 
     from .._wiring import resolve_backend
 
     resolved_parent = parent or parent_alt
+    node_file = read_node_file(from_file)
+    labels = {**node_file.labels, **parse_pairs(label_pairs, option="--label")}
+    annotations = {**node_file.annotations, **parse_pairs(annotation_pairs, option="--annotation")}
 
     # The backend is `--backend`, or the `backend:` prefix of NAME. Without either, the
     # repository is the one the current directory is inside — even with one repository,
@@ -134,7 +163,9 @@ def create(
         description=description,
         owners=owners or (),
         fields=parse_set(set_fields),
-        spec=read_spec_file(from_file),
+        spec=node_file.spec,
+        labels=labels,
+        annotations=annotations,
         parent=resolved_parent,
         scaffold_variant=scaffold_variant,
         target_dir=target_dir,

{katalyst_taxonomy_cli-2.0.1a2 → katalyst_taxonomy_cli-2.0.1a4}/src/katalyst_taxonomy_cli/commands/init.py

@@ -66,7 +66,7 @@ def init(
 
     Writes the taxonomy root (.global/taxonomy/) and version.yaml — together the
     "initialized" marker — and registers the repository as a filesystem backend of a
-    profile in the user config file (<user config home>/config.yaml): the --profile
+    profile in the active home's config (`kata config path` prints it): the --profile
     profile (created when it is not declared), else the active one; a file with no
     profiles gets a new `local`, made active. The backend is named --backend, else for
     the directory; a name the profile already declares for another directory is refused

{katalyst_taxonomy_cli-2.0.1a2 → katalyst_taxonomy_cli-2.0.1a4}/src/katalyst_taxonomy_cli/commands/lifecycle.py

@@ -118,10 +118,12 @@ def import_(ctx: CliContext, file: Path, backend_target: str) -> None:
             resolved.backend,
             [cast("dict[str, Any]", d) for d in documents],
             create=lambda request: create_node(resolved.backend, request),
+            source=file,
         )
     except ImportError_ as exc:
         ctx.output.echo(f"Error: {exc}")
-        ctx.output.echo("Error: nothing was imported.")
+        if not exc.left_behind:
+            ctx.output.echo("Error: nothing was imported.")
         raise SystemExit(1) from exc
     for fqtn in created:
         ctx.output.echo(f"Imported: {resolved.name}:{fqtn}")

{katalyst_taxonomy_cli-2.0.1a2 → katalyst_taxonomy_cli-2.0.1a4}/src/katalyst_taxonomy_cli/commands/lint.py

@@ -16,21 +16,39 @@ from katalyst_taxonomy_cli.context import CliContext
     is_flag=True,
     help=(
         "Treat advisory findings (governance id collisions, duplicate names, undeclared "
-        "spec keys, misplaced documents) as errors."
+        "spec keys, misplaced documents, shape findings and shape warnings) as errors."
+    ),
+)
+@click.option(
+    "--backend",
+    default=None,
+    help=(
+        "Report only this backend's findings. Its documents are still checked against "
+        "the graph of every backend the profile reads."
     ),
 )
 @click.pass_obj
-def lint(ctx: CliContext, verbose: bool, strict: bool) -> None:
+def lint(ctx: CliContext, verbose: bool, strict: bool, backend: str | None) -> None:
     """Validate taxonomy against schema — everything the active profile reads.
 
-    Document checks run over every backend the profile reads. Repository-local checks
-    (plugin rules, plugin-document schemas, version constraints) run once per
-    filesystem backend, and each finding is labelled [backend].
+    Every check runs over one graph: the documents of every backend the profile reads,
+    so a reference into another backend (other:shop.storefront.checkout) is checked
+    against the node it names. Each finding is labelled [backend] when the profile
+    reads more than one. Repository-local checks (plugin rules, plugin-document schemas,
+    version constraints) run once per filesystem backend. A backend that cannot be read
+    is an error naming it.
     """
     from katalyst_taxonomy.adapters.orchestration import run_lint
+    from katalyst_taxonomy.config.routing import BackendUnavailableError
 
     try:
-        result = run_lint(profile=ctx.profile)
+        result = run_lint(profile=ctx.profile, backend=backend)
+    except BackendUnavailableError as exc:
+        raise click.ClickException(
+            f"{exc}\nLint checks the graph of every backend the profile reads, so each "
+            "must be readable: make it reachable, or lint with a profile that does not "
+            "read it."
+        ) from exc
     except ValueError as exc:
         # A `filters` block that cannot be honoured — `include: []`, a clause
         # declaring `match.backend` — is a user error (#217), and lint does not go
@@ -39,6 +57,17 @@ def lint(ctx: CliContext, verbose: bool, strict: bool) -> None:
         # it still reaches the root group and still exits 7.
         raise click.ClickException(str(exc)) from exc
 
+    labelled = len(result.graph_backends) > 1
+
+    def _where(path: object) -> str:
+        """``[backend] path: `` for a finding about a file, as much as is known."""
+        label = ""
+        if labelled and isinstance(path, Path):
+            owner = result.backend_of(path)
+            label = f"[{owner}] " if owner else ""
+        shown = f"{path}: " if path is not None and str(path) not in ("", ".") else ""
+        return f"{label}{shown}"
+
     # Version constraint warnings are advisory (they do not make the taxonomy
     # invalid) but must still be surfaced — previously they were unreachable
     # when the taxonomy was otherwise valid, and only shown under --verbose.
@@ -99,21 +128,15 @@ def lint(ctx: CliContext, verbose: bool, strict: bool) -> None:
             ("Misplaced documents", result.misplaced_documents),
             ("Relationships no kind carries", result.uncarried_relationships),
             ("Shape findings", result.shape_findings),
+            ("Shape warnings", result.shape_warnings),
         ):
             if not found:
                 continue
             ctx.output.echo(f"\n{title} ({len(found)}):")
             for violation in found:
-                where = f"{violation.path}: " if str(violation.path) not in ("", ".") else ""
-                ctx.output.echo(f"  {severity}: {where}{violation.message}")
+                ctx.output.echo(f"  {severity}: {_where(violation.path)}{violation.message}")
             if not strict:
                 ctx.output.echo("  Re-run with --strict to fail on these.")
-        # A shape's warnings (e.g. coverage) are a report, strict or not.
-        if result.shape_warnings:
-            ctx.output.echo(f"\nShape warnings ({len(result.shape_warnings)}):")
-            for violation in result.shape_warnings:
-                where = f"{violation.path}: " if str(violation.path) not in ("", ".") else ""
-                ctx.output.echo(f"  WARNING: {where}{violation.message}")
 
     def _print_history_notes() -> None:
         found = result.removed_history_targets
@@ -121,8 +144,7 @@ def lint(ctx: CliContext, verbose: bool, strict: bool) -> None:
             return
         ctx.output.echo(f"\nHistory references to removed nodes ({len(found)}):")
         for violation in found:
-            where = f"{violation.path}: " if str(violation.path) not in ("", ".") else ""
-            ctx.output.echo(f"  INFO: {where}{violation.message}")
+            ctx.output.echo(f"  INFO: {_where(violation.path)}{violation.message}")
 
     strict_findings = (
         len(result.governance_id_collisions)
@@ -131,6 +153,7 @@ def lint(ctx: CliContext, verbose: bool, strict: bool) -> None:
         + len(result.misplaced_documents)
         + len(result.uncarried_relationships)
         + len(result.shape_findings)
+        + len(result.shape_warnings)
     )
     strict_failure = strict and strict_findings > 0
 
@@ -142,6 +165,10 @@ def lint(ctx: CliContext, verbose: bool, strict: bool) -> None:
             for repo in result.repositories
         )
         ctx.output.echo(f"  Repositories checked: {repositories or '(none)'}")
+        if result.focus is not None:
+            ctx.output.echo(
+                f"  Findings for: {result.focus}; graph: {', '.join(result.graph_backends)}"
+            )
         # Show the receipts: a gate that verified nothing must not look identical
         # to one that verified everything.
         ctx.output.echo(
@@ -179,14 +206,14 @@ def lint(ctx: CliContext, verbose: bool, strict: bool) -> None:
     if result.document_errors:
         ctx.output.echo(f"\nDocument errors ({len(result.document_errors)}):")
         for err in result.document_errors:
-            ctx.output.echo(f"  {err.path}: {err.message}")
+            ctx.output.echo(f"  {_where(err.path)}{err.message}")
 
     # Positioned between document and plugin-schema errors so block order is
     # fixed across runs and corpora.
     if result.reference_errors:
         ctx.output.echo(f"\nReference errors ({len(result.reference_errors)}):")
         for ref_err in result.reference_errors:
-            ctx.output.echo(f"  {ref_err.path}: {ref_err.message}")
+            ctx.output.echo(f"  {_where(ref_err.path)}{ref_err.message}")
 
     if result.plugin_schema_errors:
         ctx.output.echo(f"\nSchema errors ({len(result.plugin_schema_errors)}):")