modelable 1.0.0__py3-none-any.whl

modelable/commands/compile.py

@@ -0,0 +1,237 @@
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+import click
+
+from modelable.commands.common import console, load_workspace_or_exit
+from modelable.emitters.csharp import emit_csharp
+from modelable.emitters.dbt_yaml import emit_dbt_yaml
+from modelable.emitters.diagnostics import deferred_target
+from modelable.emitters.fhir import emit_fhir_profile
+from modelable.emitters.go import emit_go
+from modelable.emitters.java import emit_java
+from modelable.emitters.json_schema import emit_json_schema
+from modelable.emitters.markdown import emit_markdown
+from modelable.emitters.odcs import emit_odcs
+from modelable.emitters.openlineage import emit_openlineage
+from modelable.emitters.openmetadata import emit_openmetadata
+from modelable.emitters.python import emit_python
+from modelable.emitters.rust import emit_rust
+from modelable.emitters.sql import emit_sql
+from modelable.emitters.targets import list_implemented_codegen_targets
+from modelable.emitters.typescript import emit_typescript
+from modelable.planner.plans import write_plans
+from modelable.registry.factory import get_registry
+from modelable.registry.index import build_registry
+
+_DEFAULT_OUT_DIRS: dict[str, Path] = {
+    target.name: target.default_out_dir
+    for target in list_implemented_codegen_targets()
+    if target.default_out_dir is not None
+}
+
+
+def register_compile_commands(cli_group: click.Group) -> None:
+    cli_group.add_command(compile)
+    cli_group.add_command(docs)
+
+
+@click.command()
+@click.argument("source", type=click.Path(exists=True, path_type=Path))
+@click.option(
+    "--target",
+    required=True,
+    type=click.Choice([target.name for target in list_implemented_codegen_targets()]),
+    help="Artifact target to compile after registry indexing.",
+)
+@click.option(
+    "--out",
+    "out_dir",
+    type=click.Path(path_type=Path),
+    default=None,
+    help="Directory for target artifacts.",
+)
+@click.option(
+    "--registry",
+    "registry_path",
+    type=click.Path(path_type=Path),
+    default=Path(".modelable/registry.db"),
+    help="Path to the registry index file.",
+)
+def compile(source: Path, target: str, out_dir: Path | None, registry_path: Path) -> None:
+    """Compile Modelable definitions and write the local registry index."""
+    workspace = load_workspace_or_exit(source)
+
+    build_registry(workspace, registry_path.parent)
+    registry = get_registry(registry_path)
+    registry.push(registry_path)
+    console.print(f"[green]OK[/green] wrote {registry_path}")
+
+    plans_dir = Path(".modelable/plans")
+    plan_paths = write_plans(workspace, plans_dir)
+    for plan_path in plan_paths:
+        console.print(f"[green]OK[/green] wrote {plan_path}")
+
+    output = out_dir or _DEFAULT_OUT_DIRS[target]
+    output.mkdir(parents=True, exist_ok=True)
+
+    if target == "json-schema":
+        artifacts = emit_json_schema(workspace, output)
+        for art in artifacts:
+            _write_artifact_text(art.path, json.dumps(art.content, indent=2, ensure_ascii=False) + "\n")
+            _print_artifact_result(art)
+        if not artifacts:
+            console.print("[yellow]No artifacts generated.[/yellow]")
+    elif target == "markdown":
+        artifacts = emit_markdown(workspace, output)
+        for art in artifacts:
+            assert isinstance(art.content, str)
+            _write_artifact_text(art.path, art.content)
+            _print_artifact_result(art)
+        if not artifacts:
+            console.print("[yellow]No artifacts generated.[/yellow]")
+    elif target == "typescript":
+        artifacts = emit_typescript(workspace, output)
+        for art in artifacts:
+            assert isinstance(art.content, str)
+            _write_artifact_text(art.path, art.content)
+            _print_artifact_result(art)
+        if not artifacts:
+            console.print("[yellow]No artifacts generated.[/yellow]")
+    elif target == "csharp":
+        artifacts = emit_csharp(workspace, output)
+        for art in artifacts:
+            assert isinstance(art.content, str)
+            _write_artifact_text(art.path, art.content)
+            _print_artifact_result(art)
+        if not artifacts:
+            console.print("[yellow]No artifacts generated.[/yellow]")
+    elif target == "java":
+        artifacts = emit_java(workspace, output)
+        for art in artifacts:
+            assert isinstance(art.content, str)
+            _write_artifact_text(art.path, art.content)
+            _print_artifact_result(art)
+        if not artifacts:
+            console.print("[yellow]No artifacts generated.[/yellow]")
+    elif target == "python":
+        artifacts = emit_python(workspace, output)
+        for art in artifacts:
+            assert isinstance(art.content, str)
+            _write_artifact_text(art.path, art.content)
+            _print_artifact_result(art)
+        if not artifacts:
+            console.print("[yellow]No artifacts generated.[/yellow]")
+    elif target == "rust":
+        artifacts = emit_rust(workspace, output)
+        for art in artifacts:
+            assert isinstance(art.content, str)
+            _write_artifact_text(art.path, art.content)
+            _print_artifact_result(art)
+        if not artifacts:
+            console.print("[yellow]No artifacts generated.[/yellow]")
+    elif target == "go":
+        artifacts = emit_go(workspace, output)
+        for art in artifacts:
+            assert isinstance(art.content, str)
+            _write_artifact_text(art.path, art.content)
+            _print_artifact_result(art)
+        if not artifacts:
+            console.print("[yellow]No artifacts generated.[/yellow]")
+    elif target == "dbt-yaml":
+        artifacts = emit_dbt_yaml(workspace, output)
+        for art in artifacts:
+            assert isinstance(art.content, str)
+            _write_artifact_text(art.path, art.content)
+            _print_artifact_result(art)
+        if not artifacts:
+            console.print("[yellow]No artifacts generated.[/yellow]")
+    elif target == "fhir-profile":
+        artifacts = emit_fhir_profile(workspace, output)
+        for art in artifacts:
+            assert isinstance(art.content, str)
+            _write_artifact_text(art.path, art.content)
+            _print_artifact_result(art)
+        if not artifacts:
+            console.print("[yellow]No artifacts generated.[/yellow]")
+    elif target == "openmetadata":
+        artifacts = emit_openmetadata(workspace, output)
+        for art in artifacts:
+            content = (
+                json.dumps(art.content, indent=2, ensure_ascii=False) + "\n"
+                if isinstance(art.content, dict)
+                else art.content
+            )
+            assert isinstance(content, str)
+            _write_artifact_text(art.path, content)
+            _print_artifact_result(art)
+        if not artifacts:
+            console.print("[yellow]No artifacts generated.[/yellow]")
+    elif target == "openlineage":
+        artifacts = emit_openlineage(workspace, output)
+        for art in artifacts:
+            assert isinstance(art.content, dict)
+            _write_artifact_text(art.path, json.dumps(art.content, indent=2, ensure_ascii=False) + "\n")
+            _print_artifact_result(art)
+        if not artifacts:
+            console.print("[yellow]No artifacts generated.[/yellow]")
+    elif target == "odcs":
+        artifacts = emit_odcs(workspace, output)
+        for art in artifacts:
+            assert isinstance(art.content, str)
+            _write_artifact_text(art.path, art.content)
+            _print_artifact_result(art)
+        if not artifacts:
+            console.print("[yellow]No artifacts generated.[/yellow]")
+    elif target in ("sql-postgres", "sql-clickhouse"):
+        dialect = target.removeprefix("sql-")
+        artifacts = emit_sql(workspace, output, dialect)
+        for art in artifacts:
+            assert isinstance(art.content, str)
+            _write_artifact_text(art.path, art.content)
+            _print_artifact_result(art)
+        if not artifacts:
+            console.print("[yellow]No artifacts generated.[/yellow]")
+    else:
+        console.print(f"[yellow]{deferred_target(target)}[/yellow]")
+
+    sys.exit(0)
+
+
+@click.command()
+@click.argument("source", type=click.Path(exists=True, path_type=Path))
+@click.option(
+    "--out",
+    "out_dir",
+    type=click.Path(path_type=Path),
+    default=None,
+    help="Directory for generated documentation.",
+)
+def docs(source: Path, out_dir: Path | None) -> None:
+    """Generate Markdown documentation from Modelable definitions at SOURCE."""
+    workspace = load_workspace_or_exit(source)
+
+    output = out_dir or Path("./dist/docs")
+    output.mkdir(parents=True, exist_ok=True)
+    artifacts = emit_markdown(workspace, output)
+    for art in artifacts:
+        assert isinstance(art.content, str)
+        art.path.write_text(art.content, encoding="utf-8")
+        _print_artifact_result(art)
+    if not artifacts:
+        console.print("[yellow]No artifacts generated.[/yellow]")
+    sys.exit(0)
+
+
+def _print_artifact_result(art) -> None:
+    for warning in art.warnings:
+        console.print(f"[yellow]WARN[/yellow] {warning}")
+    console.print(f"[green]OK[/green] {art.path} [dim]{art.content_hash}[/dim]")
+
+
+def _write_artifact_text(path: Path, content: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content, encoding="utf-8")

modelable/commands/create.py

@@ -0,0 +1,164 @@
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+import click
+
+from modelable.commands.common import console
+
+
+def register_create_commands(cli_group: click.Group) -> None:
+    cli_group.add_command(create)
+
+
+@click.group()
+def create() -> None:
+    """Create Modelable definition files interactively."""
+
+
+@create.command(name="domain")
+@click.option("--output-dir", "-d", default=".", type=click.Path(path_type=Path), show_default=True)
+def create_domain(output_dir: Path) -> None:
+    """Create a domain definition file."""
+    name = click.prompt("Domain name")
+    out_file = output_dir / f"{name}.mdl"
+    if out_file.exists():
+        raise click.ClickException(f"{out_file} already exists")
+    output_dir.mkdir(parents=True, exist_ok=True)
+    out_file.write_text(_domain_text(name), encoding="utf-8")
+    console.print(f"[green]Created[/green] {out_file}")
+
+
+def _domain_text(name: str) -> str:
+    return f'domain {name} {{\n  owner: "required-team"\n}}\n'
+
+
+_FIELD_TYPES = [
+    "string",
+    "int",
+    "float",
+    "bool",
+    "date",
+    "time",
+    "timestamp",
+    "uuid",
+    "duration",
+    "binary",
+    "decimal",
+]
+
+
+@create.command(name="model")
+@click.option("--output-dir", "-d", default=".", type=click.Path(path_type=Path), show_default=True)
+def create_model(output_dir: Path) -> None:
+    """Create a model (entity/aggregate/event/value) definition file."""
+    domain = click.prompt("Domain name")
+    kind = click.prompt("Model kind", type=click.Choice(["entity", "aggregate", "event", "value"]))
+    name = click.prompt("Model name")
+    version = click.prompt("Version", default=1, type=int)
+    change_kind = click.prompt("Change kind", type=click.Choice(["additive", "breaking"]), default="additive")
+
+    fields: list[dict] = []
+    while True:
+        field_name = click.prompt("Field name (leave blank to finish)", default="", show_default=False)
+        if not field_name:
+            break
+        field_type = click.prompt("Field type", type=click.Choice(_FIELD_TYPES))
+        if field_type == "decimal":
+            precision = click.prompt("Precision", default=18, type=int)
+            scale = click.prompt("Scale", default=2, type=int)
+            field_type = f"decimal({precision}, {scale})"
+        optional = click.confirm("Optional field?", default=False)
+        is_key = click.confirm("Add @key annotation?", default=False)
+        is_pii = click.confirm("Add @pii annotation?", default=False)
+        fields.append(
+            {"name": field_name, "type": field_type, "optional": optional, "is_key": is_key, "is_pii": is_pii}
+        )
+
+    out_file = output_dir / f"{domain}.mdl"
+    if out_file.exists():
+        raise click.ClickException(f"{out_file} already exists")
+    output_dir.mkdir(parents=True, exist_ok=True)
+    out_file.write_text(_model_text(domain, kind, name, version, change_kind, fields), encoding="utf-8")
+    console.print(f"[green]Created[/green] {out_file}")
+
+
+def _model_text(
+    domain: str,
+    kind: str,
+    name: str,
+    version: int,
+    change_kind: str,
+    fields: list[dict],
+) -> str:
+    lines = [f"domain {domain} {{", '  owner: "required-team"', f"  {kind} {name} @ {version} ({change_kind}) {{"]
+    for field in fields:
+        annotations = ""
+        if field.get("is_key"):
+            annotations += "@key "
+        if field.get("is_pii"):
+            annotations += "@pii "
+        optional_marker = "?" if field.get("optional") else ""
+        lines.append(f"    {annotations}{field['name']}{optional_marker}: {field['type']}")
+    lines += ["  }", "}"]
+    return "\n".join(lines) + "\n"
+
+
+@create.command(name="projection")
+@click.option("--output-dir", "-d", default=".", type=click.Path(path_type=Path), show_default=True)
+def create_projection(output_dir: Path) -> None:
+    """Create a projection definition file."""
+    domain = click.prompt("Domain name")
+    name = click.prompt("Projection name")
+    version = click.prompt("Version", default=1, type=int)
+    source_model = click.prompt("Source model ref (e.g. customer.Customer)")
+    source_version = click.prompt("Source version", default=1, type=int)
+    alias = click.prompt("Source alias")
+
+    fields: list[dict] = []
+    while True:
+        field_name = click.prompt("Field name (leave blank to finish)", default="", show_default=False)
+        if not field_name:
+            break
+        mapping = click.prompt("Mapping (alias.field for direct, or CEL expression)")
+        fields.append({"name": field_name, "mapping": mapping})
+
+    out_file = output_dir / f"{domain}.mdl"
+    if out_file.exists():
+        raise click.ClickException(f"{out_file} already exists")
+    output_dir.mkdir(parents=True, exist_ok=True)
+    out_file.write_text(
+        _projection_text(domain, name, version, source_model, source_version, alias, fields),
+        encoding="utf-8",
+    )
+    console.print(f"[green]Created[/green] {out_file}")
+
+
+_DIRECT_MAPPING_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*\.[A-Za-z_][A-Za-z0-9_]*$")
+
+
+def _projection_text(
+    domain: str,
+    name: str,
+    version: int,
+    source_model: str,
+    source_version: int,
+    alias: str,
+    fields: list[dict],
+) -> str:
+    lines = [
+        f"domain {domain} {{",
+        '  owner: "required-team"',
+        f"  projection {name} @ {version}",
+        f"    from {source_model} @ {source_version} as {alias}",
+        "  {",
+    ]
+    for field in fields:
+        mapping = field["mapping"]
+        if _DIRECT_MAPPING_RE.match(mapping):
+            lines.append(f"    {field['name']} <- {mapping}")
+        else:
+            lines.append(f"    {field['name']} = {mapping}")
+    lines += ["  }", "}"]
+    return "\n".join(lines) + "\n"

modelable/commands/diff.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+from modelable.commands.common import console
+from modelable.compat.checker import analyze_impact, check_model_version_compatibility
+from modelable.compiler.workspace import load_workspace
+from modelable.llm.context import parse_model_ref_version_spec
+from modelable.registry.resolver import find_dependents, resolve_model_ref
+
+
+def register_diff_commands(cli_group: click.Group) -> None:
+    cli_group.add_command(diff)
+
+
+def run_diff(from_ref: str, to_ref: str, path: Path) -> None:
+    """Compare two published model versions and print the compatibility report."""
+    workspace = load_workspace(path)
+    try:
+        from_domain, from_name, from_version_spec = parse_model_ref_version_spec(from_ref)
+        to_domain, to_name, to_version_spec = parse_model_ref_version_spec(to_ref)
+    except ValueError as exc:
+        raise click.ClickException(str(exc)) from exc
+    if from_domain != to_domain or from_name != to_name:
+        raise click.ClickException("diff requires refs from the same domain and model")
+
+    try:
+        from_model = resolve_model_ref(workspace.mdl, f"{from_domain}.{from_name}", from_version_spec)
+        to_model = resolve_model_ref(workspace.mdl, f"{to_domain}.{to_name}", to_version_spec)
+        report = check_model_version_compatibility(
+            workspace.mdl,
+            from_model.domain_name,
+            from_model.model_name,
+            from_model.version.version,
+            to_model.version.version,
+        )
+    except LookupError as exc:
+        raise click.ClickException(str(exc)) from exc
+
+    console.print(f"{from_ref} -> {to_ref}")
+    console.print(f"status: {report.status}")
+    if report.findings:
+        for finding in report.findings:
+            console.print(f"- {finding}")
+    else:
+        console.print("- no changes")
+
+    dependents = find_dependents(
+        workspace.mdl, from_model.domain_name, from_model.model_name, from_model.version.version
+    )
+    if dependents:
+        impacts = []
+        for dep in dependents:
+            impact = analyze_impact(workspace.mdl, report, dep)
+            if impact.status != "compatible":
+                impacts.append(impact)
+
+        if impacts:
+            console.print("\nImpacted Projections:")
+            for impact in impacts:
+                status_tag = f"[{impact.status.upper()}]"
+                color = "red" if impact.status == "broken" else "yellow"
+                line = (
+                    f"- [{color}]{status_tag}[/{color}] {impact.domain_name}.{impact.projection_name}@{impact.version}"
+                )
+                if impact.reason:
+                    line += f" ({impact.reason})"
+                console.print(line)
+
+    if report.status == "breaking":
+        raise click.exceptions.Exit(1)
+
+
+@click.command()
+@click.argument("from_ref")
+@click.argument("to_ref")
+@click.option("--path", "path", type=click.Path(exists=True, path_type=Path), required=True)
+def diff(from_ref: str, to_ref: str, path: Path) -> None:
+    """Compare two published model versions."""
+    run_diff(from_ref, to_ref, path)

modelable/commands/graph.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import click
+
+from modelable.commands.common import console, load_workspace_or_exit
+from modelable.graph.export import build_graph_export, write_graph_export
+
+
+def register_graph_commands(cli_group: click.Group) -> None:
+    cli_group.add_command(graph)
+
+
+@click.group()
+def graph() -> None:
+    """Graph export commands for the normalized workspace graph."""
+
+
+@graph.command(name="export")
+@click.argument("source", type=click.Path(exists=True, path_type=Path))
+@click.option(
+    "--path",
+    "path",
+    type=click.Path(exists=True, path_type=Path),
+    default=None,
+    help="Workspace path to load instead of SOURCE.",
+)
+@click.option(
+    "--focus",
+    "focus",
+    default=None,
+    help="Optional model or projection ref to center the graph.",
+)
+@click.option(
+    "--out",
+    "out_path",
+    type=click.Path(path_type=Path),
+    required=True,
+    help="Output file for the canonical graph JSON.",
+)
+def export_graph(source: Path, path: Path | None, focus: str | None, out_path: Path) -> None:
+    """Export the normalized workspace graph as deterministic JSON."""
+    workspace = load_workspace_or_exit(path or source)
+    try:
+        graph_export = build_graph_export(workspace, focus=focus)
+    except (LookupError, ValueError) as exc:
+        console.print(f"[red]ERROR[/red] {exc}")
+        sys.exit(1)
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    write_graph_export(graph_export, out_path)
+    console.print(f"[green]OK[/green] wrote {out_path}")