katalyst-taxonomy-cli 2.0.1a1__py3-none-any.whl

katalyst_taxonomy_cli/commands/core.py

@@ -0,0 +1,468 @@
+"""``kata core`` — katalyst-core, the LinkML module every schema module imports.
+
+::
+
+    kata core check [--module PATH]    hold a module (katalyst-core by default) to the
+                                       core contract: URIs under declared prefixes, a
+                                       delete policy on every relationship
+    kata core save RECORDS OUT         write a records document to its graph form (Turtle)
+    kata core load GRAPH               read a graph back as a records document (YAML)
+    kata core validate RECORDS         run the local shapes (generated from the installed
+                                       modules); fails on a violation
+    kata core coverage RECORDS         run the global shapes (gates); reports, never fails
+    kata core kinds                    every node kind the installed modules define
+    kata core query RECORDS [--module PATH] [--is-a CLASS] [--name NAME] [--as-of DATE]
+                    [--engine in-memory|oxigraph]
+                                       ask the query interface; the engine is a choice
+
+    kata core schema diff [--bundle B] [--from VERSION] [--json] [--write-migration]
+                                       the classified diff of a schema's modules against
+                                       an archived version; a migration skeleton
+    kata core schema check [--bundle B]
+                                       the version gate: the bump and the migration match
+                                       the diff
+    kata core schema archive --bundle B
+                                       archive the current modules as the released version
+
+Records and graphs are read against every installed module (``katalyst_core.modules``).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import click
+
+__all__ = ["core"]
+
+_EXISTING = click.Path(exists=True, dir_okay=False, path_type=Path)
+
+
+@click.group("core")
+def core() -> None:
+    """katalyst-core: the base schema every Katalyst module imports."""
+
+
+@core.command("check")
+@click.option(
+    "--module",
+    "module",
+    type=_EXISTING,
+    default=None,
+    help="A LinkML module that imports katalyst_core. Default: katalyst-core itself.",
+)
+def check(module: Path | None) -> None:
+    """Hold a LinkML module to the core contract."""
+    from katalyst_core import installed_modules, open_module
+    from katalyst_core.contract import check_contract
+    from katalyst_core.local import LocalModuleError, check_local_module
+
+    if module is not None:
+        try:
+            check_local_module(module, installed_modules())
+        except LocalModuleError as exc:
+            raise click.ClickException(str(exc)) from exc
+    try:
+        report = check_contract(open_module(module))
+    except Exception as exc:  # a module LinkML itself cannot open
+        raise click.ClickException(f"cannot open {module}: {exc}") from exc
+    if not report.ok:
+        for problem in report.problems:
+            click.echo(problem, err=True)
+        raise click.ClickException(
+            f"{report.module}: {len(report.problems)} problem(s) with the core contract"
+        )
+    click.echo(
+        f"OK: {report.module} ({report.classes} classes, {report.slots} slots): "
+        "every class and slot has a URI under a declared prefix; "
+        "every relationship has a delete policy"
+    )
+
+
+@core.command("save")
+@click.argument("records", type=_EXISTING)
+@click.argument("out", type=click.Path(dir_okay=False, path_type=Path))
+def save(records: Path, out: Path) -> None:
+    """Write the records in RECORDS (YAML) to OUT as an RDF graph (Turtle)."""
+    import yaml
+    from katalyst_core import open_installed
+    from katalyst_core.graph import CoreDataError, to_graph
+
+    document: Any = yaml.safe_load(records.read_text(encoding="utf-8")) or {}
+    if not isinstance(document, dict):
+        raise click.ClickException(f"{records}: expected a mapping with prefixes and records")
+    try:
+        graph = to_graph(open_installed(), document)  # pyright: ignore[reportUnknownArgumentType]
+    except CoreDataError as exc:
+        raise click.ClickException(f"{records}: {exc}") from exc
+    out.write_text(graph.serialize(format="turtle"), encoding="utf-8")
+    click.echo(f"Saved {len(document.get('records') or [])} record(s) to {out}")  # pyright: ignore[reportUnknownArgumentType, reportUnknownMemberType]
+
+
+@core.command("load")
+@click.argument("graph_file", metavar="GRAPH", type=_EXISTING)
+def load(graph_file: Path) -> None:
+    """Read the records in GRAPH (Turtle) and print them as YAML."""
+    import yaml
+    from katalyst_core import open_installed
+    from katalyst_core.graph import from_graph
+    from rdflib import Graph
+
+    graph = Graph(bind_namespaces="none")
+    graph.parse(graph_file, format="turtle")
+    document = from_graph(open_installed(), graph)
+    click.echo(yaml.safe_dump(document, sort_keys=False, allow_unicode=True), nl=False)
+
+
+def _records_graph(records: Path, modules: tuple[Path, ...] = ()) -> tuple[Any, Any]:
+    """The installed modules (and local ``modules``), and ``records`` as an RDF graph."""
+    import yaml
+    from katalyst_core import local_modules, open_installed
+    from katalyst_core.graph import CoreDataError, to_graph
+
+    document: Any = yaml.safe_load(records.read_text(encoding="utf-8")) or {}
+    if not isinstance(document, dict):
+        raise click.ClickException(f"{records}: expected a mapping with prefixes and records")
+    from katalyst_core.local import LocalModuleError
+
+    try:
+        sv = open_installed(local_modules(modules))
+    except LocalModuleError as exc:
+        raise click.ClickException(str(exc)) from exc
+    try:
+        return sv, to_graph(sv, document)  # pyright: ignore[reportUnknownArgumentType]
+    except CoreDataError as exc:
+        raise click.ClickException(f"{records}: {exc}") from exc
+
+
+@core.command("validate")
+@click.argument("records", type=_EXISTING)
+@click.option(
+    "--module",
+    "modules",
+    type=_EXISTING,
+    multiple=True,
+    help="A local LinkML module to read the records against (repeatable).",
+)
+def validate(records: Path, modules: tuple[Path, ...]) -> None:
+    """Run the local shapes over RECORDS; fail on any violation."""
+    from katalyst_core.shapes import local_shapes, run_shapes
+
+    sv, graph = _records_graph(records, modules)
+    findings = run_shapes(sv, graph, local_shapes(sv))
+    violations = [f for f in findings if f.severity == "violation"]
+    for finding in findings:
+        click.echo(str(finding), err=finding.severity == "violation")
+    if violations:
+        raise click.ClickException(f"{records}: {len(violations)} violation(s)")
+    click.echo(f"OK: {records} conforms to the installed modules")
+
+
+@core.command("coverage")
+@click.argument("records", type=_EXISTING)
+@click.option(
+    "--module",
+    "modules",
+    type=_EXISTING,
+    multiple=True,
+    help="A local LinkML module to read the records against (repeatable).",
+)
+def coverage(records: Path, modules: tuple[Path, ...]) -> None:
+    """Run the global shapes over RECORDS and report what they find (never fails).
+
+    The global shapes are the baseline's gates; they target the baseline classes, so they
+    also check every local subtype of them (``--module``).
+    """
+    from katalyst_core.shapes import global_shapes, run_shapes
+
+    sv, graph = _records_graph(records, modules)
+    findings = run_shapes(sv, graph, global_shapes())
+    # A global rule is about the node as a whole, so its finding names the node alone.
+    for finding in findings:
+        click.echo(f"{finding.focus}: {finding.message}")
+    click.echo(f"{len(findings)} finding(s)")
+
+
+@core.command("kinds")
+def kinds() -> None:
+    """Every node kind the installed modules define, one per line."""
+    from katalyst_core import kinds as module_kinds
+    from katalyst_core import open_installed
+
+    for kind in sorted(module_kinds(open_installed())):
+        click.echo(kind)
+
+
+@core.command("query")
+@click.argument("records", type=_EXISTING)
+@click.option(
+    "--module",
+    "modules",
+    type=_EXISTING,
+    multiple=True,
+    help="A local LinkML module to read the records against (repeatable).",
+)
+@click.option("--is-a", "is_a", default=None, help="Records of this class or any subtype.")
+@click.option("--name", default=None, help="Records with this name.")
+@click.option(
+    "--as-of",
+    "as_of",
+    type=click.DateTime(formats=["%Y-%m-%d", "%Y-%m-%dT%H:%M:%S"]),
+    default=None,
+    help="Only what was recorded as true at this date.",
+)
+@click.option(
+    "--engine",
+    type=click.Choice(["oxigraph", "in-memory"]),
+    default="oxigraph",
+    show_default=True,
+    help="The engine below the query interface.",
+)
+@click.option(
+    "--mappings",
+    "mapping_files",
+    type=_EXISTING,
+    multiple=True,
+    help=(
+        "An SSSOM mapping set (TSV, repeatable). Confirmed exact matches apply at query "
+        "time; every other row is reported and not applied."
+    ),
+)
+def query(
+    records: Path,
+    modules: tuple[Path, ...],
+    is_a: str | None,
+    name: str | None,
+    as_of: Any,
+    engine: str,
+    mapping_files: tuple[Path, ...],
+) -> None:
+    """Ask the query interface about RECORDS and print the matching records (YAML)."""
+    import yaml
+    from katalyst_core.mappings import MappingSet, read_sssom
+    from katalyst_core.query import QueryEngineUnavailable, open_engine
+
+    sv, graph = _records_graph(records, modules)
+    mappings = MappingSet.merge(read_sssom(f) for f in mapping_files) if mapping_files else None
+    for skipped in mappings.not_applied if mappings else ():
+        click.echo(f"Mapping not applied: {skipped}: {skipped.why_not()}", err=True)
+    try:
+        answer = open_engine(engine, sv, graph, mappings)
+        if is_a is not None:
+            found = answer.instances_of(is_a)
+            if name is not None or as_of is not None:
+                wanted = {str(r["id"]) for r in answer.find(name=name, as_of=as_of)}
+                found = [r for r in found if str(r["id"]) in wanted]
+        else:
+            found = answer.find(name=name, as_of=as_of)
+    except (QueryEngineUnavailable, LookupError) as exc:
+        raise click.ClickException(str(exc)) from exc
+    click.echo(yaml.safe_dump({"records": found}, sort_keys=False, allow_unicode=True), nl=False)
+
+
+@core.command("migrate")
+@click.argument("records", type=_EXISTING)
+@click.option(
+    "--spec",
+    type=_EXISTING,
+    required=True,
+    help="The LinkML-Map transformation specification of the breaking change.",
+)
+@click.option(
+    "--from",
+    "source",
+    type=_EXISTING,
+    required=True,
+    help="The module the records were written against (the old baseline version).",
+)
+@click.option(
+    "--to",
+    "target",
+    type=_EXISTING,
+    required=True,
+    help="The module to migrate them to (the new baseline version).",
+)
+@click.option(
+    "--out",
+    type=click.Path(dir_okay=False, path_type=Path),
+    default=None,
+    help="Where to write the migrated records. Default: print them.",
+)
+def migrate(records: Path, spec: Path, source: Path, target: Path, out: Path | None) -> None:
+    """Migrate RECORDS from one baseline version to the next with a LinkML-Map spec.
+
+    Each record of a class the spec derives is transformed; every slot the spec does not
+    consume carries over unchanged. The result must conform to the new version.
+    """
+    import yaml
+    from katalyst_core import open_module
+    from katalyst_core.graph import CoreDataError, to_graph
+    from katalyst_core.migrate import MigrationError, migrate_records
+    from katalyst_core.shapes import local_shapes, run_shapes
+
+    document: Any = yaml.safe_load(records.read_text(encoding="utf-8")) or {}
+    if not isinstance(document, dict):
+        raise click.ClickException(f"{records}: expected a mapping with prefixes and records")
+    old, new = open_module(source), open_module(target)
+    try:
+        migrated = migrate_records(document, spec=spec, source=old, target=new)  # pyright: ignore[reportUnknownArgumentType]
+        graph = to_graph(new, migrated)
+    except (MigrationError, CoreDataError) as exc:
+        raise click.ClickException(f"{records}: {exc}") from exc
+    violations = [f for f in run_shapes(new, graph, local_shapes(new)) if f.severity == "violation"]
+    for finding in violations:
+        click.echo(str(finding), err=True)
+    if violations:
+        raise click.ClickException(
+            f"{records}: the migrated records break {target.name} ({len(violations)} violation(s))"
+        )
+    text = yaml.safe_dump(migrated, sort_keys=False, allow_unicode=True)
+    if out is None:
+        click.echo(text, nl=False)
+    else:
+        out.write_text(text, encoding="utf-8")
+        click.echo(f"Migrated {len(migrated['records'])} record(s) to {out}")
+
+
+# --- kata core schema: versions, the archive, the diff, migrations ------------------
+
+
+@core.group("schema")
+def schema() -> None:
+    """Schema versions: the classified diff, the version gate, the archive.
+
+    A schema is katalyst-core or an installed bundle (by its manifest name). Its released
+    versions are archived beside its modules (``released/<version>/``), its migrations in
+    ``migrations/<from>-to-<to>.yaml``.
+    """
+
+
+def _releases(bundle: str | None) -> list[Any]:
+    from katalyst_engine.evolution import installed_releases
+
+    releases = installed_releases()
+    if bundle is None:
+        return releases
+    chosen = [r for r in releases if r.name == bundle]
+    if not chosen:
+        names = ", ".join(r.name for r in releases)
+        raise click.ClickException(f"no schema named {bundle!r}; installed: {names}")
+    return chosen
+
+
+_BUNDLE = click.option(
+    "--bundle",
+    "bundle",
+    default=None,
+    help="katalyst-core or a bundle's name (default: every installed schema).",
+)
+
+
+@schema.command("diff")
+@_BUNDLE
+@click.option(
+    "--from",
+    "since",
+    default=None,
+    help="The archived version to compare with (default: the latest).",
+)
+@click.option("--json", "as_json", is_flag=True, help="Print the changes as JSON.")
+@click.option(
+    "--write-migration",
+    is_flag=True,
+    help="Write migrations/<from>-to-<to>.yaml with a step or an accept per breaking change.",
+)
+def schema_diff(
+    bundle: str | None, since: str | None, as_json: bool, write_migration: bool
+) -> None:
+    """Print the classified diff of the current modules against an archived version."""
+    import json
+
+    from katalyst_engine.core.version import Version
+    from katalyst_engine.evolution import migration_skeleton
+    from katalyst_engine.evolution.diff import diff_modules
+    from katalyst_engine.evolution.gate import required_bump
+
+    releases = _releases(bundle)
+    if write_migration and len(releases) != 1:
+        raise click.ClickException("--write-migration needs --bundle")
+    out: dict[str, Any] = {}
+    for release in releases:
+        try:
+            old = Version.parse(since) if since else release.latest_released()
+        except ValueError as exc:
+            raise click.ClickException(str(exc)) from exc
+        if old is None:
+            click.echo(f"{release.name} {release.version}: no released version is archived")
+            continue
+        try:
+            archived = release.released_modules(old)
+        except FileNotFoundError as exc:
+            raise click.ClickException(str(exc)) from exc
+        diff = diff_modules(archived, release.modules)
+        need = required_bump(diff.impact)
+        if as_json:
+            out[release.name] = {
+                "from": str(old),
+                "to": str(release.version),
+                "bump": need,
+                **diff.to_dict(),
+            }
+        else:
+            click.echo(diff.summary(f"{release.name} {old} -> {release.version}"))
+            if diff.changes:
+                click.echo(f"Needs a {need} bump.")
+        if write_migration:
+            new = release.version
+            if new <= old:
+                new = {"major": old.next_major(), "minor": old.next_minor()}.get(
+                    need, old.next_patch()
+                )
+            path = release.migration_file(old, new)
+            if path.exists():
+                raise click.ClickException(f"{path} exists; edit it, or remove it to start again")
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_text(migration_skeleton(diff, old, new), encoding="utf-8")
+            click.echo(f"Wrote {path}", err=as_json)
+            if new != release.version:
+                click.echo(
+                    f"Bump {release.name} to {new}: its manifest and every module's version",
+                    err=as_json,
+                )
+    if as_json:
+        click.echo(json.dumps(out, indent=2, default=str))
+
+
+@schema.command("check")
+@_BUNDLE
+def schema_check(bundle: str | None) -> None:
+    """The version gate: fail when a bump or a migration does not match the diff."""
+    from katalyst_engine.evolution import check_release
+
+    failed: list[str] = []
+    for release in _releases(bundle):
+        report = check_release(release)
+        click.echo(report.summary(), err=not report.ok)
+        if not report.ok:
+            failed.append(release.name)
+    if failed:
+        raise click.ClickException(f"the schema version gate failed for {', '.join(failed)}")
+
+
+@schema.command("archive")
+@click.option("--bundle", "bundle", required=True, help="katalyst-core or a bundle's name.")
+def schema_archive(bundle: str) -> None:
+    """Archive the current modules as the released version (do this when you release it)."""
+    from katalyst_engine.evolution import SchemaVersionMismatchError, check_release
+
+    (release,) = _releases(bundle)
+    report = check_release(release)
+    if not report.ok:
+        click.echo(report.summary(), err=True)
+        raise click.ClickException(f"{bundle} does not pass the gate; fix it before archiving")
+    try:
+        target = release.archive()
+    except (FileExistsError, SchemaVersionMismatchError) as exc:
+        raise click.ClickException(str(exc)) from exc
+    click.echo(f"Archived {release.name} {release.version} in {target}")

katalyst_taxonomy_cli/commands/create.py

@@ -0,0 +1,145 @@
+"""kata tax create — Create a new taxonomy node."""
+
+from __future__ import annotations
+
+import click
+
+from katalyst_taxonomy_cli.context import CliContext
+
+
+@click.command("create")
+@click.argument("node_type")
+@click.argument("name")
+@click.option("-d", "--description", default=None, help="Node description.")
+@click.option("-O", "--owner", "owners", multiple=True, help="Owner email(s).")
+@click.option(
+    "--under",
+    "parent",
+    default=None,
+    help="The parent's qualified name (shop.backend), or backend:fqtn.",
+)
+@click.option("--parent", "parent_alt", default=None, help="Alias for --under.")
+@click.option(
+    "--scaffold-variant",
+    "scaffold_variant",
+    default=None,
+    help="Scaffold variant to scaffold the node's directory from; any scaffoldable kind.",
+)
+@click.option(
+    "--set",
+    "set_fields",
+    multiple=True,
+    metavar="KEY=VALUE",
+    help=(
+        "Set a field the kind declares, typed by its declaration. Repeat a key for a "
+        "list; a dotted key (scope.regions=x) sets a key of a map field; a JSON "
+        "value sets a list or map whole."
+    ),
+)
+@click.option(
+    "--from-file",
+    "from_file",
+    default=None,
+    metavar="PATH",
+    help="Spec fields from a YAML or JSON file (- for stdin); --set applies over them.",
+)
+@click.option("--target-dir", default=None, help="Override output directory.")
+@click.option(
+    "--backend",
+    "backend_target",
+    default=None,
+    help=(
+        "Backend to create the node in (or write NAME as backend:name). Defaults to the "
+        "filesystem backend the current directory is inside; from any other directory "
+        "it must be named."
+    ),
+)
+@click.option(
+    "--dry-run",
+    is_flag=True,
+    default=False,
+    help=(
+        "Check it and show what it would write — its document and every file its "
+        "scaffold and create hooks add or change — without writing anything."
+    ),
+)
+@click.pass_obj
+def create(
+    ctx: CliContext,
+    node_type: str,
+    name: str,
+    description: str | None,
+    owners: tuple[str, ...],
+    parent: str | None,
+    parent_alt: str | None,
+    scaffold_variant: str | None,
+    set_fields: tuple[str, ...],
+    from_file: str | None,
+    target_dir: str | None,
+    backend_target: str | None,
+    dry_run: bool,
+) -> None:
+    """Create a NODE_TYPE node called NAME, in the backend --backend names.
+
+    Every backend takes the same path: the node is checked against its kind and written
+    through the backend; a backend that keeps documents as files (a repository) writes
+    it as katalyst.taxonomy/v2alpha at the kind's storage path (or --target-dir), and
+    --scaffold-variant scaffolds the node's directory from an
+    installed template (see kata tax add) — a variant not installed is refused, with the
+    command that installs it. --under/--parent names the parent by its qualified name
+    (a layer under stack backend of system shop: --under shop.backend); a bare name of
+    a nested parent is refused with the qualified names it may mean. --dry-run checks
+    the same and writes nothing: it prints the document and the files it would write.
+
+    --set KEY=VALUE and --from-file give the node's fields, typed and checked as
+    kata tax update checks them: a field the kind declares (or description / owners),
+    a value of its type (boolean, integer, list, map) and allowed values, a reference
+    naming a node of the referenced kind.
+
+    Examples:
+
+        kata tax create stage verify --set halt_on_failure=false --set concern_order=maintainability
+
+        kata tax create operation probe --set order=10 --set scope.regions=eu-west
+
+        kata tax create venue ci --set 'triggers=[{"on":"push","environments":["dev"]}]'
+
+        kata tax create environment qa --set template_replacements.log_level=debug
+    """
+    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 .._wiring import resolve_backend
+
+    resolved_parent = parent or parent_alt
+
+    # 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,
+    # a directory none holds is an error naming the candidates, not a write elsewhere.
+    prefix, name = split_backend_prefix(name)
+    if prefix is not None and backend_target is not None and prefix != backend_target:
+        raise click.ClickException(
+            f"{prefix}:{name} names backend {prefix!r} but --backend is {backend_target!r}."
+        )
+    chosen = prefix or backend_target or ctx.repository(None, from_cwd=True).name
+    resolved = resolve_backend(ctx, chosen)
+
+    exit_code = run_create(
+        ctx.cwd,
+        node_type,
+        name,
+        backend_name=resolved.name,
+        description=description,
+        owners=owners or (),
+        fields=parse_set(set_fields),
+        spec=read_spec_file(from_file),
+        parent=resolved_parent,
+        scaffold_variant=scaffold_variant,
+        target_dir=target_dir,
+        profile=ctx.profile,
+        dry_run=dry_run,
+    )
+    if exit_code != 0:
+        raise SystemExit(exit_code)

katalyst_taxonomy_cli/commands/deps.py

@@ -0,0 +1,48 @@
+"""kata tax deps — Show dependency graph."""
+
+from __future__ import annotations
+
+import io
+
+import click
+
+from katalyst_taxonomy_cli.context import CliContext
+
+
+@click.command("deps")
+@click.option(
+    "--format",
+    "fmt",
+    type=click.Choice(["tree", "list", "json", "mermaid"]),
+    default=None,
+    help="Output format.",
+)
+@click.option("--node", default=None, help="Filter to specific node.")
+@click.option("--reverse", is_flag=True, help="Show reverse dependencies (dependents).")
+@click.pass_obj
+def deps(ctx: CliContext, fmt: str | None, node: str | None, reverse: bool) -> None:
+    """Show dependency graph."""
+    from katalyst_taxonomy.services.deps import build_dependency_graph
+    from katalyst_taxonomy.services.deps_formatting import (
+        output_json,
+        output_list,
+        output_mermaid,
+        output_tree,
+    )
+
+    fmt = fmt or ctx.output_format or "tree"
+    service = ctx.taxonomy_service
+    graph = build_dependency_graph(service)
+
+    buf = io.StringIO()
+
+    if fmt == "json":
+        output_json(graph, service, buf)
+    elif fmt == "list":
+        output_list(graph, service, buf)
+    elif fmt == "mermaid":
+        output_mermaid(graph, service, node, buf)
+    else:
+        output_tree(graph, service, node, reverse, buf)
+
+    ctx.output.echo(buf.getvalue().rstrip())