process-bigraph-lang 0.1.0__py3-none-win_amd64.whl

process_bigraph_lang/bin/.gitignore

@@ -0,0 +1,4 @@
+# Ignore everything in this directory
+*
+# Except this file
+!.gitignore

process_bigraph_lang/bin/cli-native.exe

@@ -0,0 +1,4 @@
+[diffend] Oversized file quarantined before diffing.
+name: process_bigraph_lang/bin/cli-native.exe
+size: 82848027 bytes
+sha256: 12cb10ac6a84072036b1578eb07a35dcb175cdd61e71ca004afd1e7adeadb4a4

process_bigraph_lang/v2/__init__.py

@@ -0,0 +1,56 @@
+"""
+The `.pblang` v2 language, Python side.
+
+The v2 language is a tree-shaped, verifiable projection of a process-bigraph composite document
+(see `docs/v2/design.md`). The grammar, the checker, the compiler and the decompiler are TypeScript (`dsl/`),
+run here through `cli-native`; this package is the Python entry to them, plus what has to be Python:
+
+- `compile_text` / `compile_file`: `.pblang` text -> parsed, checked -> a `{"schema", "state"}` document or a
+  CompositeSpec mapping (`CompileError` when the checker finds errors)
+- `decompile`: a document or a CompositeSpec mapping -> canonical `.pblang` text plus sidecar assets
+- `check_file` / `check_text`: the checker's findings (`Diagnostic`s)
+- `describe_module` / `InterfaceRegistry`: interface declarations ("headers") from a package's classes, as the
+  JSON manifest the CLI reads; `render_interfaces` has the CLI print the `.pblang` header file
+- `normalize_document` / `equivalent` / `diff_documents`: equivalence of two documents modulo representation
+
+There is no Python model of a composite: a Python tool that builds composites targets the DSL text.
+"""
+
+from process_bigraph_lang.v2.api import (
+    CompileError,
+    Compiled,
+    Printed,
+    compile_file,
+    compile_text,
+    decompile,
+    dumps,
+    loads,
+    read_json,
+    write_json,
+)
+from process_bigraph_lang.v2.check import Diagnostic, check_file, check_text
+from process_bigraph_lang.v2.interfaces import InterfaceRegistry, describe_module, render_interfaces
+from process_bigraph_lang.v2.normalize import deep_equal, diff_documents, equivalent, normalize_document
+
+__all__ = [
+    "CompileError",
+    "Compiled",
+    "Diagnostic",
+    "InterfaceRegistry",
+    "Printed",
+    "check_file",
+    "check_text",
+    "compile_file",
+    "compile_text",
+    "decompile",
+    "deep_equal",
+    "describe_module",
+    "diff_documents",
+    "dumps",
+    "equivalent",
+    "loads",
+    "normalize_document",
+    "read_json",
+    "render_interfaces",
+    "write_json",
+]

process_bigraph_lang/v2/__main__.py

@@ -0,0 +1,204 @@
+"""
+`python -m process_bigraph_lang.v2 compile <file.pblang> [--interfaces m.json]... [--to document|spec] [-o out]`:
+parse and check the text, then write the document (JSON) or the CompositeSpec (yaml); errors stop it.
+`python -m process_bigraph_lang.v2 decompile <doc.json | spec.composite.yaml>`: a document as `.pblang` text.
+`python -m process_bigraph_lang.v2 check <file.pblang | doc.json> [--interfaces m.json]...`: the checker's findings.
+`python -m process_bigraph_lang.v2 diff <a.json> <b.json>`: explain how two documents differ after normalization.
+`python -m process_bigraph_lang.v2 describe <module>...` / `describe-model <sbml>`: headers from code or SBML.
+
+Documents are JSON (`bigraph_schema.json_codec` encoding, so numpy arrays survive) or CompositeSpec yaml.
+Sidecar assets of `decompile` are written next to the output when `--out` is given, else listed on stderr.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+from typing import Any
+
+from process_bigraph_lang.v2 import (
+    CompileError,
+    InterfaceRegistry,
+    compile_file,
+    decompile,
+    diff_documents,
+    equivalent,
+    loads,
+    render_interfaces,
+)
+
+
+def _load(path: Path) -> dict[str, Any]:
+    text = path.read_text(encoding="utf-8")
+    if path.suffix in (".yaml", ".yml"):
+        import yaml
+
+        loaded = yaml.safe_load(text)
+    else:
+        loaded = loads(text)
+    if not isinstance(loaded, dict):
+        raise SystemExit(f"{path}: not a document")
+    return loaded
+
+
+def _manifests(args: argparse.Namespace) -> list[Path]:
+    return [Path(m) for m in getattr(args, "interfaces", None) or []]
+
+
+def _decompile(args: argparse.Namespace) -> int:
+    path = Path(args.document)
+    printed = decompile(_load(path), name=path.stem.replace(".composite", ""), manifests=_manifests(args))
+    if args.out:
+        out = Path(args.out)
+        out.write_text(printed.text, encoding="utf-8")
+        for asset_name, content in printed.assets.items():
+            target = out.parent / asset_name
+            target.parent.mkdir(parents=True, exist_ok=True)
+            target.write_bytes(content)
+        print(f"wrote {out} and {len(printed.assets)} asset(s)", file=sys.stderr)
+    else:
+        sys.stdout.write(printed.text)
+        for asset_name in printed.assets:
+            print(f"asset (not written): {asset_name}", file=sys.stderr)
+    return 0
+
+
+def _compile(args: argparse.Namespace) -> int:
+    try:
+        compiled = compile_file(args.document, manifests=_manifests(args), to=args.to, strict=args.strict)
+    except CompileError as error:
+        for diagnostic in error.diagnostics:
+            print(diagnostic, file=sys.stderr)
+        print("compile failed", file=sys.stderr)
+        return 1
+    for diagnostic in compiled.diagnostics:
+        print(diagnostic, file=sys.stderr)
+    if args.to == "spec":
+        import yaml
+
+        text = yaml.safe_dump(compiled.document, sort_keys=False)
+    else:
+        from process_bigraph_lang.v2 import dumps
+
+        text = dumps(compiled.document) + "\n"
+    if args.out:
+        Path(args.out).write_text(text, encoding="utf-8")
+        print(f"wrote {args.out}", file=sys.stderr)
+    else:
+        sys.stdout.write(text)
+    return 0
+
+
+def _diff(args: argparse.Namespace) -> int:
+    import process_bigraph as pg  # type: ignore[import-untyped]
+
+    core = pg.allocate_core()
+    a, b = _load(Path(args.a)), _load(Path(args.b))
+    if equivalent(a, b, core):
+        return 0
+    print(diff_documents(a, b, core))
+    return 1
+
+
+def _describe(args: argparse.Namespace) -> int:
+    registry = InterfaceRegistry.from_modules(*args.modules)
+    if args.manifest:
+        registry.write_manifest(Path(args.manifest))
+    files = {
+        module: render_interfaces([d for d in registry.decls if d.module == module], module) for module in args.modules
+    }
+    if args.out and (len(files) > 1 or Path(args.out).is_dir()):
+        out_dir = Path(args.out)
+        out_dir.mkdir(parents=True, exist_ok=True)
+        for module, text in files.items():
+            (out_dir / f"{module}.pblang").write_text(text, encoding="utf-8")
+        print(f"wrote {len(files)} interface file(s) to {out_dir}", file=sys.stderr)
+    elif args.out:
+        Path(args.out).write_text(next(iter(files.values())), encoding="utf-8")
+    else:
+        sys.stdout.write("".join(files.values()))
+    return 0
+
+
+def _check(args: argparse.Namespace) -> int:
+    from process_bigraph_lang.v2.check import check_file, check_text
+
+    source = Path(args.document)
+    manifests = _manifests(args)
+    if source.suffix in (".json", ".yaml", ".yml"):  # a document: decompile it, then check the text
+        printed = decompile(_load(source), name=source.stem, manifests=manifests)
+        diagnostics = check_text(printed.text, manifests)
+    else:
+        diagnostics = check_file(source, manifests)
+    for diagnostic in diagnostics:
+        print(diagnostic)
+    errors = sum(1 for d in diagnostics if d.severity == "error")
+    print(f"{errors} error(s), {sum(1 for d in diagnostics if d.severity == 'warning')} warning(s)", file=sys.stderr)
+    return 1 if errors else 0
+
+
+def _describe_model(args: argparse.Namespace) -> int:
+    import json
+
+    from process_bigraph_lang.v2.sbml import describe_sbml, print_model_header
+
+    header = describe_sbml(args.model)
+    if args.manifest:
+        Path(args.manifest).write_text(json.dumps(header.to_dict(), indent=2) + "\n", encoding="utf-8")
+    text = print_model_header(header)
+    if args.out:
+        Path(args.out).write_text(text, encoding="utf-8")
+    else:
+        sys.stdout.write(text)
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="python -m process_bigraph_lang.v2")
+    commands = parser.add_subparsers(dest="command", required=True)
+    compile_cmd = commands.add_parser("compile", help="parse and check a .pblang file, then write the document")
+    compile_cmd.add_argument("document", help="a .pblang file (file(...) references resolve next to it)")
+    compile_cmd.add_argument("--interfaces", action="append", help="a manifest.json (repeatable)")
+    compile_cmd.add_argument("--to", choices=["document", "spec"], default="document")
+    compile_cmd.add_argument("--strict", action="store_true", help="warnings fail the compile too")
+    compile_cmd.add_argument("-o", "--out", help="write the document (JSON) or CompositeSpec (yaml) here")
+    compile_cmd.set_defaults(run=_compile)
+    decompile_cmd = commands.add_parser(
+        "decompile", aliases=["print"], help="print a document or CompositeSpec as .pblang text"
+    )
+    decompile_cmd.add_argument("document")
+    decompile_cmd.add_argument("--out", help="write the text here (assets go next to it)")
+    decompile_cmd.add_argument(
+        "--interfaces", action="append", help="a manifest.json (repeatable); matching addresses print as imports"
+    )
+    decompile_cmd.set_defaults(run=_decompile)
+    describe_cmd = commands.add_parser("describe", help="generate interface declarations from Python modules")
+    describe_cmd.add_argument("modules", nargs="+", help="importable module names (run in the package's env)")
+    describe_cmd.add_argument("--manifest", help="write the JSON manifest here")
+    describe_cmd.add_argument(
+        "--out", help="the .pblang interface file (one module) or a directory (one file per module)"
+    )
+    describe_cmd.set_defaults(run=_describe)
+    model_cmd = commands.add_parser("describe-model", help="generate a model header from an SBML file")
+    model_cmd.add_argument("model", help="an SBML file")
+    model_cmd.add_argument("--manifest", help="write the JSON form here")
+    model_cmd.add_argument("--out", help="write the .pblang model header here")
+    model_cmd.set_defaults(run=_describe_model)
+    check_cmd = commands.add_parser("check", help="statically check a .pblang file or a document against manifests")
+    check_cmd.add_argument(
+        "document", help="a .pblang file, or a document (.json) / CompositeSpec (.yaml) to decompile and check"
+    )
+    check_cmd.add_argument("--interfaces", action="append", help="a manifest.json (repeatable)")
+    check_cmd.set_defaults(run=_check)
+    diff_cmd = commands.add_parser("diff", help="compare two documents after normalization (exit 1 if they differ)")
+    diff_cmd.add_argument("a")
+    diff_cmd.add_argument("b")
+    diff_cmd.set_defaults(run=_diff)
+    args = parser.parse_args(argv)
+    result: int = args.run(args)
+    return result
+
+
+if __name__ == "__main__":
+    sys.exit(main())

process_bigraph_lang/v2/api.py

@@ -0,0 +1,192 @@
+"""
+The public Python API of v2: text in, checked documents out; documents in, text out. All of it runs in the DSL
+CLI (`cli-native`, TypeScript): parsing, checking, compiling and decompiling. There is no Python model of a
+composite, so a Python tool that builds composites targets the DSL text, where the result is checked, reviewed
+and documented (docs/v2/design.md, section 5.3).
+
+- `compile_text` / `compile_file`: `.pblang` text -> parse -> check -> a process-bigraph `{"schema", "state"}`
+  document or a CompositeSpec mapping. An error-level finding stops the compile (`CompileError` carries every
+  finding); warnings and infos come back on the result.
+- `decompile`: a document or a CompositeSpec mapping -> canonical `.pblang` text plus sidecar assets.
+
+Documents cross the CLI boundary as JSON in `bigraph_schema.json_codec`'s encoding (numpy arrays tagged), with
+tuples tagged as `{"__tuple__": true, "data": [...]}` so that they survive too.
+"""
+
+from __future__ import annotations
+
+import os
+import tempfile
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Literal
+
+from bigraph_schema import json_codec  # type: ignore[import-untyped]
+
+from process_bigraph_lang.v2.check import Diagnostic, check_file, registry_manifests
+from process_bigraph_lang.v2.interfaces import InterfaceRegistry
+from process_bigraph_lang.v2.langium import run_cli
+
+Target = Literal["document", "spec"]
+
+
+@dataclass
+class Compiled:
+    """What `compile_text` / `compile_file` return: the artifact and the findings that did not stop the compile."""
+
+    document: dict[str, Any]
+    diagnostics: list[Diagnostic] = field(default_factory=list)
+
+    @property
+    def warnings(self) -> list[Diagnostic]:
+        return [d for d in self.diagnostics if d.severity == "warning"]
+
+
+@dataclass
+class Printed:
+    """What `decompile` returns: the `.pblang` text and its sidecar assets (`<name>.assets/...`), by path."""
+
+    text: str
+    assets: dict[str, bytes] = field(default_factory=dict)
+
+
+class CompileError(Exception):
+    """The text did not pass the checker; `diagnostics` holds every finding, errors first."""
+
+    def __init__(self, diagnostics: list[Diagnostic]):
+        self.diagnostics = diagnostics
+        errors = [d for d in diagnostics if d.severity == "error"]
+        super().__init__("\n".join(str(d) for d in errors or diagnostics))
+
+
+def compile_text(
+    text: str,
+    *,
+    registry: InterfaceRegistry | None = None,
+    manifests: list[Path] | None = None,
+    to: Target = "document",
+    strict: bool = False,
+    force: bool = False,
+    assets: dict[str, bytes] | None = None,
+) -> Compiled:
+    """Compile v2 text. `assets` holds the sidecar files `file(...)` references name, by path."""
+    with tempfile.TemporaryDirectory() as tmp:
+        source = Path(tmp) / "document.pblang"
+        source.write_text(text, encoding="utf-8")
+        for name, content in (assets or {}).items():
+            target = Path(tmp) / name
+            target.parent.mkdir(parents=True, exist_ok=True)
+            target.write_bytes(content)
+        return compile_file(source, registry=registry, manifests=manifests, to=to, strict=strict, force=force)
+
+
+def compile_file(
+    path: str | os.PathLike[str],
+    *,
+    registry: InterfaceRegistry | None = None,
+    manifests: list[Path] | None = None,
+    to: Target = "document",
+    strict: bool = False,
+    force: bool = False,
+) -> Compiled:
+    """
+    Compile a `.pblang` file; `file(...)` references resolve next to it. `force` compiles despite the checker's
+    errors (parse errors still stop it): the escape for documents that rely on defaults the checker flags.
+    """
+    source = Path(path).resolve()
+    with tempfile.TemporaryDirectory() as tmp:
+        manifest_paths = [*(manifests or []), *registry_manifests(registry, Path(tmp))]
+        diagnostics = check_file(source, manifest_paths)
+        fatal = set() if force else {"error", "warning"} if strict else {"error"}
+        if any(d.severity in fatal for d in diagnostics) or any(d.code == "P001" for d in diagnostics):
+            raise CompileError(diagnostics)
+        out = Path(tmp) / ("compiled.yaml" if to == "spec" else "compiled.json")
+        args = ["compile", str(source), "--to", to, "--out", str(out), *(["--force"] if force else [])]
+        if manifest_paths:
+            args += ["--interfaces", *[str(Path(m).resolve()) for m in manifest_paths]]
+        run_cli(*args)
+        text = out.read_text(encoding="utf-8")
+    if to == "spec":
+        import yaml
+
+        return Compiled(yaml.safe_load(text), diagnostics)
+    return Compiled(loads(text), diagnostics)
+
+
+def decompile(
+    mapping: dict[str, Any],
+    *,
+    name: str = "document",
+    registry: InterfaceRegistry | None = None,
+    manifests: list[Path] | None = None,
+) -> Printed:
+    """Canonical `.pblang` text (and sidecar assets) for a document or a CompositeSpec mapping (told apart by keys)."""
+    with tempfile.TemporaryDirectory() as tmp:
+        source = Path(tmp) / f"{name}.json"
+        source.write_text(dumps(mapping), encoding="utf-8")
+        out = Path(tmp) / f"{name}.pblang"
+        args = ["decompile", str(source), "--name", name, "--out", str(out)]
+        manifest_paths = [*(manifests or []), *registry_manifests(registry, Path(tmp))]
+        if manifest_paths:
+            args += ["--interfaces", *[str(Path(m).resolve()) for m in manifest_paths]]
+        run_cli(*args)
+        printed = Printed(out.read_text(encoding="utf-8"))
+        assets_dir = Path(tmp) / f"{name}.assets"
+        if assets_dir.is_dir():
+            for asset in sorted(assets_dir.iterdir()):
+                printed.assets[f"{name}.assets/{asset.name}"] = asset.read_bytes()
+        return printed
+
+
+# --- the JSON that crosses the CLI boundary ----------------------------------------------------------------------
+
+
+def dumps(document: Any) -> str:
+    """`bigraph_schema.json_codec` encoding, plus tuples tagged so that they come back as tuples."""
+    return str(json_codec.dumps(_tag_tuples(document)))
+
+
+def loads(text: str) -> Any:
+    return _untag_tuples(json_codec.loads(text))
+
+
+def _tag_tuples(value: Any) -> Any:
+    if isinstance(value, tuple):
+        return {"__tuple__": True, "data": [_tag_tuples(v) for v in value]}
+    if isinstance(value, dict):
+        return {k: _tag_tuples(v) for k, v in value.items()}
+    if isinstance(value, list):
+        return [_tag_tuples(v) for v in value]
+    return value
+
+
+def _untag_tuples(value: Any) -> Any:
+    if isinstance(value, dict):
+        if value.get("__tuple__") is True and isinstance(value.get("data"), list):
+            return tuple(_untag_tuples(v) for v in value["data"])
+        return {k: _untag_tuples(v) for k, v in value.items()}
+    if isinstance(value, list):
+        return [_untag_tuples(v) for v in value]
+    return value
+
+
+def write_json(document: Any, path: str | os.PathLike[str]) -> None:
+    Path(path).write_text(dumps(document) + "\n", encoding="utf-8")
+
+
+def read_json(path: str | os.PathLike[str]) -> Any:
+    return loads(Path(path).read_text(encoding="utf-8"))
+
+
+__all__ = [
+    "CompileError",
+    "Compiled",
+    "Printed",
+    "compile_file",
+    "compile_text",
+    "decompile",
+    "dumps",
+    "loads",
+    "read_json",
+    "write_json",
+]

process_bigraph_lang/v2/check.py

@@ -0,0 +1,73 @@
+"""
+Static checks of a composite, run by the DSL CLI's `check` command (the checker lives in TypeScript,
+`dsl/src/language/v2/check.ts`, so the editor, the browser and the CLI share one implementation).
+
+`check_file` runs `cli-native check --json` on a `.pblang` file with header manifests; `check_text` does the same
+for text. Both return the findings of the `pblang-diagnostics/1` envelope as `Diagnostic`s.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from process_bigraph_lang.v2.interfaces import InterfaceRegistry
+from process_bigraph_lang.v2.langium import run_cli
+
+
+@dataclass
+class Diagnostic:
+    code: str
+    slug: str
+    severity: str  # error | warning | info | hint
+    path: str  # document path, slash-joined (as `fill_sites` spells it)
+    message: str
+    line: int | None = None
+
+    def __str__(self) -> str:
+        return f"{self.severity:7} {self.code} {self.slug:24} {self.path}: {self.message}"
+
+
+def check_text(
+    text: str, manifests: list[Path] | None = None, registry: InterfaceRegistry | None = None
+) -> list[Diagnostic]:
+    """Check v2 text against header manifests and/or a registry (written as a manifest)."""
+    with tempfile.TemporaryDirectory() as tmp:
+        source = Path(tmp) / "document.pblang"
+        source.write_text(text, encoding="utf-8")
+        return check_file(source, [*(manifests or []), *registry_manifests(registry, Path(tmp))])
+
+
+def check_file(path: str | os.PathLike[str], manifests: list[Path] | None = None) -> list[Diagnostic]:
+    """Check a `.pblang` file against header manifests through the CLI."""
+    args = ["check", str(Path(path).resolve()), "--json"]
+    if manifests:
+        args += ["--interfaces", *[str(Path(m).resolve()) for m in manifests]]
+    result = run_cli(*args, check=False)
+    if not result.stdout.strip():
+        raise RuntimeError(f"Langium CLI failed on {path}: {result.stderr.strip()}")
+    envelope: dict[str, Any] = json.loads(result.stdout)
+    return [
+        Diagnostic(
+            d["code"],
+            d["slug"],
+            d["severity"],
+            d["path"],
+            d["message"],
+            d.get("range", {}).get("start", {}).get("line"),
+        )
+        for d in envelope.get("diagnostics", [])
+    ]
+
+
+def registry_manifests(registry: InterfaceRegistry | None, directory: Path) -> list[Path]:
+    """A registry written as a manifest file in `directory` (none when the registry is empty)."""
+    if registry is None or not registry.decls:
+        return []
+    manifest = directory / "registry.manifest.json"
+    manifest.write_text(json.dumps(registry.to_manifest(), default=str), encoding="utf-8")
+    return [manifest]