decl-lang 0.3.0__tar.gz

decl_lang-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 luuvish
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

decl_lang-0.3.0/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: decl-lang
+Version: 0.3.0
+Summary: Decl — a declarative language for describing, generating, and validating structured data: the decl CLI (check / evaluate / validate / fmt), the decl-lsp language server, and a Python API, implemented natively
+Author: luuvish
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/luuvish/decl-lang
+Project-URL: Repository, https://github.com/luuvish/decl-lang
+Project-URL: Issues, https://github.com/luuvish/decl-lang/issues
+Keywords: decl,declarative,schema,validation,configuration,json,language,lsp
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: C
+Classifier: Topic :: Software Development :: Compilers
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: tree-sitter>=0.25
+Provides-Extra: dev
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+# decl
+
+**Decl** is a declarative language for describing, generating, and
+validating structured data — a JSON superset with a strong static type
+system, constraints with first-class diagnostics, references, physical
+quantities, generics, and modules. Pure, deterministic, terminating.
+
+This package is a **native Python implementation** of the whole
+language — the tree-sitter grammar compiled as a C extension plus a
+pure-Python port of the static checker, the evaluator, packages, the
+canonical formatter, and the language server, byte-identical to the
+reference implementation. It ships the `decl` command-line tool, the
+`decl-lsp` language server, and a small Python API. No Node.js is
+involved.
+
+```bash
+pip install decl-lang     # installs as decl-lang, imports as `decl` — the command's name and the module path (decl.runtime)
+```
+
+## Command line
+
+```bash
+decl check schema.decl                   # parse + static checks (module-aware)
+decl evaluate site.decl                  # the exported outputs -> JSON on stdout
+decl evaluate site.decl --output site=site.json --output report   # one document to a file, one to stdout
+decl evaluate cfg.decl --input deployed=doc.json --output deployed   # bind a document, emit its completed value
+decl validate cfg.decl --input deployed=doc.json --expect-errors E4001
+decl validate tests/validation           # judge a fixture corpus
+decl fmt --check src/*.decl              # canonical formatting
+decl repl site.decl                      # an interactive session: expressions, bindings, edits, undo
+decl-lsp                                 # stdio language server for editors
+```
+
+## Python API
+
+```python
+import decl
+
+docs = decl.evaluate("site.decl")  # {"site": {...}} — the exported outputs, by name
+site = decl.evaluate("site.decl", outputs=["site"])["site"]
+done = decl.evaluate("cfg.decl", inputs={"deployed": "doc.json"}, outputs=["deployed"])["deployed"]
+problems = decl.check("schema.decl")  # [] when clean
+report = decl.validate(
+    "cfg.decl", inputs={"deployed": {"host": "h"}}
+)  # a document may be a value, not a file
+text = decl.format_source("const x=1+2\n")  # 'const x = 1 + 2\n'
+```
+
+The functions are the `decl` command line in its own vocabulary:
+`inputs` binds documents by input name (a JSON file path, or the value
+itself), `outputs` names the roots to return — outputs, or inputs bound
+here or demanded through their fallback — and defaults to the entry
+module's exported outputs. The npm package (`evaluate`, `check`,
+`validate`, `formatSource`) and the Rust crate (`decl_lang::evaluate`, …)
+offer the same functions with the same semantics.
+
+Every call runs the same implementation as the CLI and returns its
+machine-readable report; `decl.DeclError.diagnostics` carries the
+diagnostics (`file`, `severity`, `code`, `id`, `path`, `message`) when
+an operation fails.
+
+## A taste of the language
+
+```decl
+type Service = {
+    name: /[a-z][a-z0-9-]*/
+    port?: 1024..65535 = 8080
+    replicas?: 1..64 = 1
+    endpoint = `${name}:${port}`
+    assert grpc_ports: name != "grpc" || port >= 9000
+        else warn `grpc convention is 9000+`
+}
+
+export output demo: Service[] = [
+    { name: "gateway" }
+    { name: "auth", port: 9001, replicas: 2 }
+]
+```
+
+Specification, guide, and sources: https://github.com/luuvish/decl-lang

decl_lang-0.3.0/README.md

@@ -0,0 +1,80 @@
+# decl
+
+**Decl** is a declarative language for describing, generating, and
+validating structured data — a JSON superset with a strong static type
+system, constraints with first-class diagnostics, references, physical
+quantities, generics, and modules. Pure, deterministic, terminating.
+
+This package is a **native Python implementation** of the whole
+language — the tree-sitter grammar compiled as a C extension plus a
+pure-Python port of the static checker, the evaluator, packages, the
+canonical formatter, and the language server, byte-identical to the
+reference implementation. It ships the `decl` command-line tool, the
+`decl-lsp` language server, and a small Python API. No Node.js is
+involved.
+
+```bash
+pip install decl-lang     # installs as decl-lang, imports as `decl` — the command's name and the module path (decl.runtime)
+```
+
+## Command line
+
+```bash
+decl check schema.decl                   # parse + static checks (module-aware)
+decl evaluate site.decl                  # the exported outputs -> JSON on stdout
+decl evaluate site.decl --output site=site.json --output report   # one document to a file, one to stdout
+decl evaluate cfg.decl --input deployed=doc.json --output deployed   # bind a document, emit its completed value
+decl validate cfg.decl --input deployed=doc.json --expect-errors E4001
+decl validate tests/validation           # judge a fixture corpus
+decl fmt --check src/*.decl              # canonical formatting
+decl repl site.decl                      # an interactive session: expressions, bindings, edits, undo
+decl-lsp                                 # stdio language server for editors
+```
+
+## Python API
+
+```python
+import decl
+
+docs = decl.evaluate("site.decl")  # {"site": {...}} — the exported outputs, by name
+site = decl.evaluate("site.decl", outputs=["site"])["site"]
+done = decl.evaluate("cfg.decl", inputs={"deployed": "doc.json"}, outputs=["deployed"])["deployed"]
+problems = decl.check("schema.decl")  # [] when clean
+report = decl.validate(
+    "cfg.decl", inputs={"deployed": {"host": "h"}}
+)  # a document may be a value, not a file
+text = decl.format_source("const x=1+2\n")  # 'const x = 1 + 2\n'
+```
+
+The functions are the `decl` command line in its own vocabulary:
+`inputs` binds documents by input name (a JSON file path, or the value
+itself), `outputs` names the roots to return — outputs, or inputs bound
+here or demanded through their fallback — and defaults to the entry
+module's exported outputs. The npm package (`evaluate`, `check`,
+`validate`, `formatSource`) and the Rust crate (`decl_lang::evaluate`, …)
+offer the same functions with the same semantics.
+
+Every call runs the same implementation as the CLI and returns its
+machine-readable report; `decl.DeclError.diagnostics` carries the
+diagnostics (`file`, `severity`, `code`, `id`, `path`, `message`) when
+an operation fails.
+
+## A taste of the language
+
+```decl
+type Service = {
+    name: /[a-z][a-z0-9-]*/
+    port?: 1024..65535 = 8080
+    replicas?: 1..64 = 1
+    endpoint = `${name}:${port}`
+    assert grpc_ports: name != "grpc" || port >= 9000
+        else warn `grpc convention is 9000+`
+}
+
+export output demo: Service[] = [
+    { name: "gateway" }
+    { name: "auth", port: 9001, replicas: 2 }
+]
+```
+
+Specification, guide, and sources: https://github.com/luuvish/decl-lang

decl_lang-0.3.0/decl/__init__.py

@@ -0,0 +1,255 @@
+"""Python API for the Decl language.
+
+Every operation runs the native Python implementation (``decl.runtime``),
+held byte-identical to the reference implementation by
+tests/parity/differential.py. The functions mirror the ``decl`` command
+line, in its vocabulary: ``evaluate`` binds inputs and returns outputs.
+
+    >>> import decl
+    >>> decl.evaluate("site.decl")          # {"site": {...}} — the exported outputs
+    >>> decl.evaluate("cfg.decl", inputs={"deployed": "doc.json"}, outputs=["deployed"])["deployed"]
+    >>> decl.check("schema.decl")           # [] when clean, else diagnostics
+    >>> decl.validate("cfg.decl", inputs={"deployed": {"host": "h"}})
+    ...                                     # a document may be a value, not a file
+    >>> decl.format_source("const x=1+2\\n")                          # 'const x = 1 + 2\\n'
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from collections.abc import Iterable, Mapping, Sequence
+from typing import Any, TypedDict, cast
+
+__all__ = [
+    "DeclError",
+    "Diagnostic",
+    "check",
+    "evaluate",
+    "evaluate_source",
+    "format_file",
+    "format_source",
+    "validate",
+]
+__version__ = "0.3.0"
+
+
+class Diagnostic(TypedDict, total=False):
+    """One diagnostic, in the report's field order (§12.2)."""
+
+    file: str
+    code: str
+    id: str
+    severity: str
+    message: str
+    path: str
+
+
+class DeclError(Exception):
+    """Raised when an operation fails; ``diagnostics`` carries the report
+    (empty for a usage error such as an unknown input or root)."""
+
+    def __init__(self, message: str, diagnostics: Sequence[Diagnostic] = ()):
+        super().__init__(message)
+        self.diagnostics: list[Diagnostic] = list(diagnostics)
+
+
+# a document to bind to an input: the path of a JSON file, or the value itself
+InputDocument = "str | os.PathLike[str] | Any"
+Inputs = "Mapping[str, InputDocument] | Iterable[tuple[str, InputDocument]]"
+
+
+def _tagged(file: str, d: dict[str, Any]) -> Diagnostic:
+    o: dict[str, Any] = {"file": file}
+    if d.get("code"):
+        o["code"] = d["code"]
+    if d.get("id"):
+        o["id"] = d["id"]
+    o["severity"] = d["severity"]
+    o["message"] = d["message"]
+    o["path"] = d.get("path", "")
+    return cast(Diagnostic, o)
+
+
+def _fail(fallback: str, diagnostics: list[Any]) -> None:
+    raise DeclError(diagnostics[0]["message"] if diagnostics else fallback, diagnostics)
+
+
+def _file_tag(given: str, entry: Any, module_path: str) -> str:
+    return given if entry is not None and module_path == entry.path else module_path
+
+
+def _pairs(inputs: Any) -> list[Any]:
+    if inputs is None:
+        return []
+    return list(inputs.items()) if isinstance(inputs, Mapping) else list(inputs)
+
+
+def _bind_inputs(modules: list[Any], file: str, inputs: Any) -> list[Any]:
+    """The documents to bind, each to the module that declares its input (§10)."""
+    from .runtime.semantics import read_json
+
+    binds = []
+    for name, doc in _pairs(inputs):
+        module = next((m for m in modules if name in m.env.inputs), None)
+        if module is None:
+            raise DeclError(f"no input named {name}")
+        if isinstance(doc, (str, os.PathLike)):
+            try:
+                with open(doc, encoding="utf-8") as fh:
+                    text = fh.read()
+            except OSError:
+                _fail(
+                    "",
+                    [
+                        {
+                            "file": file,
+                            "code": "E6004",
+                            "severity": "error",
+                            "message": f"bound document cannot be read: {doc}",
+                            "path": name,
+                        }
+                    ],
+                )
+            where = str(doc)
+        else:
+            text, where = json.dumps(doc), name
+        try:
+            raw = read_json(text)
+        except Exception:
+            _fail(
+                "",
+                [
+                    {
+                        "file": file,
+                        "code": "E6004",
+                        "severity": "error",
+                        "message": f"bound document is not well-formed JSON: {where}",
+                        "path": name,
+                    }
+                ],
+            )
+        binds.append({"module": module, "input": name, "raw": raw})
+    return binds
+
+
+def evaluate(
+    path: str | os.PathLike[str],
+    *,
+    inputs: Mapping[str, Any] | Iterable[tuple[str, Any]] | None = None,
+    outputs: Iterable[str] | None = None,
+) -> dict[str, Any]:
+    """Evaluate a module on the native runtime: bind the ``inputs`` documents
+    (by input name; a JSON file path, or the value itself), run the pipeline,
+    and return the requested roots' documents by name — ``outputs`` may name
+    outputs and inputs (bound here, or demanded through their fallback);
+    by default the entry module's exported outputs (§5.5). Raises DeclError
+    with the diagnostics on any error-severity outcome."""
+    from .runtime.checker import check_module
+    from .runtime.cli import open_universe
+    from .runtime.module import run_universe
+
+    file = str(path)
+    r = open_universe(file)
+    if r["diags"] or r["entry"] is None:
+        _fail(f"{file}: cannot be loaded", [_tagged(file, d) for d in r["diags"]])
+    entry = r["entry"]
+    checks = [
+        _tagged(_file_tag(file, entry, m.path), d)
+        for m in r["modules"]
+        for d in check_module(m.decls, m.env)
+    ]
+    if checks:
+        _fail("", checks)
+    u = run_universe(r["modules"], entry, _bind_inputs(r["modules"], file, inputs))
+    report = [_tagged(file, d) for d in u["diags"]]
+    if any(d["severity"] == "error" for d in report):
+        _fail("", report)
+    names = (
+        list(outputs)
+        if outputs is not None
+        else [o["name"] for o in entry.env.outputs if o.get("exported")]
+    )
+    out: dict[str, Any] = {}
+    for n in names:
+        if n not in entry.env.roots:
+            raise DeclError(f"no root named {n}", report)
+        out[n] = json.loads(u["eng"].serialize(entry.env.roots[n], n))
+    return out
+
+
+def check(*paths: str | os.PathLike[str]) -> list[Diagnostic]:
+    """Parse and statically check entry files (module-aware) on the native
+    runtime. Returns diagnostics; empty means clean."""
+    from .runtime.cli import check_files
+
+    return [_tagged(d["file"], d) for d in check_files([str(p) for p in paths])]
+
+
+def validate(
+    path: str | os.PathLike[str],
+    *,
+    inputs: Mapping[str, Any] | Iterable[tuple[str, Any]] | None = None,
+    expect_errors: Iterable[str] | None = None,
+) -> list[Diagnostic]:
+    """Validate a file: static checks, then evaluation with the ``inputs``
+    documents bound; returns every diagnostic (all severities). Raises
+    DeclError when the file does not parse. With ``expect_errors`` the set
+    of error codes must match exactly; DeclError carries the mismatch."""
+    from .runtime.checker import check_module
+    from .runtime.cli import open_universe
+    from .runtime.module import run_universe
+    from .runtime.parse import parse_source
+    from .runtime.pipeline import run_pipeline
+
+    file = str(path)
+    with open(file, encoding="utf-8") as fh:
+        src = fh.read()
+    parsed = parse_source(src)
+    if parsed["errors"]:
+        raise DeclError(f"{file}: {len(parsed['errors'])} parse error(s)")
+    decls = parsed["decls"]
+    diags = [_tagged(file, d) for d in check_module(decls)]
+    if not diags:
+        if _pairs(inputs):
+            r = open_universe(file)
+            u = run_universe(r["modules"], r["entry"], _bind_inputs(r["modules"], file, inputs))
+            diags = [_tagged(file, d) for d in u["diags"]]
+        else:
+            diags = [_tagged(file, d) for d in run_pipeline(decls)["diags"]]
+    if expect_errors is not None:
+        want = sorted(expect_errors)
+        got = sorted(d.get("code") or "" for d in diags if d["severity"] == "error")
+        if set(want) != set(got):
+            raise DeclError(f"expected errors {want}, got {got}", diags)
+    return diags
+
+
+def evaluate_source(text: str) -> dict[str, Any]:
+    """Parse, check, and evaluate one module given as source text; returns
+    the report dict (phase, ok, parse_errors, checks, diagnostics, outputs, inputs)."""
+    from .runtime.pipeline import evaluate_source as run
+
+    return run(text)
+
+
+def format_file(path: str | os.PathLike[str], *, check: bool = False) -> bool:
+    """Canonically format a file in place. Returns True if it was (or would be) changed."""
+    with open(path, encoding="utf-8") as f:
+        src = f.read()
+    out = format_source(src)
+    if out != src and not check:
+        with open(path, "w", encoding="utf-8") as f:
+            f.write(out)
+    return out != src
+
+
+def format_source(text: str) -> str:
+    """Return the canonical formatting of a Decl source string; raises
+    DeclError when it does not parse."""
+    from .runtime.fmt import format_source as fmt
+
+    try:
+        return fmt(text)
+    except ValueError as e:
+        raise DeclError(str(e)) from None

decl_lang-0.3.0/decl/_tree_sitter/__init__.py

@@ -0,0 +1,11 @@
+"""The Decl grammar as a `tree_sitter.Language` (compiled C extension)."""
+
+from __future__ import annotations
+
+from tree_sitter import Language
+
+from ._binding import language as _language_ptr
+
+LANGUAGE = Language(_language_ptr())
+
+__all__ = ["LANGUAGE"]

decl_lang-0.3.0/decl/_tree_sitter/_binding.pyi

@@ -0,0 +1,3 @@
+"""The C extension (binding.c): the grammar as a capsule the `tree_sitter` package accepts."""
+
+def language() -> object: ...

decl_lang-0.3.0/decl/_tree_sitter/binding.c

@@ -0,0 +1,26 @@
+/* Python binding for the Decl tree-sitter grammar: exposes the language
+ * as a PyCapsule the `tree_sitter` package accepts. The grammar sources
+ * (parser.c, scanner.c) are synced from ../../tree-sitter-decl/src. */
+#include <Python.h>
+
+typedef struct TSLanguage TSLanguage;
+TSLanguage *tree_sitter_decl(void);
+
+static PyObject *binding_language(PyObject *self, PyObject *args) {
+    (void)self; (void)args;
+    return PyCapsule_New(tree_sitter_decl(), "tree_sitter.Language", NULL);
+}
+
+static PyMethodDef methods[] = {
+    {"language", binding_language, METH_NOARGS, "Get the tree-sitter language for Decl."},
+    {NULL, NULL, 0, NULL}
+};
+
+static struct PyModuleDef module = {
+    PyModuleDef_HEAD_INIT, "_binding", "Decl tree-sitter grammar", -1, methods,
+    NULL, NULL, NULL, NULL
+};
+
+PyMODINIT_FUNC PyInit__binding(void) {
+    return PyModule_Create(&module);
+}