maxitor 3.11.0__py3-none-any.whl

maxitor/graph_builder/__init__.py

@@ -0,0 +1,20 @@
+# packages/maxitor/tools/graph_builder/maxitor/graph_builder/__init__.py
+"""
+maxitor.graph_builder — the ``graph-builder`` command: a repository's graphs, kept in files.
+
+═══════════════════════════════════════════════════════════════════════════════
+PURPOSE
+═══════════════════════════════════════════════════════════════════════════════
+
+Keep each service's graph in one file, checked against the Open Gnomon Protocol
+by version: the config that lists a repository's graphs, the writer and the
+check, and the differences between a file and what its build prints.
+
+═══════════════════════════════════════════════════════════════════════════════
+ARCHITECTURE / DATA FLOW
+═══════════════════════════════════════════════════════════════════════════════
+
+The part imports nothing from ``aoa`` and nothing of ``maxitor.web``;
+``scripts/check_package_boundaries.py`` enforces both, so ``pip install maxitor``
+with no extra is enough to run it.
+"""

maxitor/graph_builder/cli.py

@@ -0,0 +1,136 @@
+# packages/maxitor/tools/graph_builder/maxitor/graph_builder/cli.py
+"""
+The ``graph-builder`` command: ``write``, ``check``, ``validate`` and ``skill``.
+
+═══════════════════════════════════════════════════════════════════════════════
+PURPOSE
+═══════════════════════════════════════════════════════════════════════════════
+
+A developer runs ``graph-builder write`` and commits the graph files with the change;
+CI runs ``graph-builder check`` and fails when a file is stale. ``validate`` tells
+whether one document is a graph, ``skill`` prints the setup skill for agents.
+
+═══════════════════════════════════════════════════════════════════════════════
+ARCHITECTURE / DATA FLOW
+═══════════════════════════════════════════════════════════════════════════════
+
+``read_config`` → ``writer.write`` / ``writer.check`` → one line per graph, the
+lines that explain a failure, and the command that fixes it. Exit codes: 0 —
+every graph is fine; 1 — a graph is not; 2 — the config was refused.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from collections.abc import Callable, Sequence
+from importlib.metadata import version
+from importlib.resources import files
+from pathlib import Path
+
+from maxitor.graph_builder.config import ConfigRefused, Graph, read_config
+from maxitor.graph_builder.schemas import GraphRefused, check_graph
+from maxitor.graph_builder.writer import Outcome, check, write
+
+DEFAULT_CONFIG = "graph-builder.toml"
+
+
+def _shown_path(path: Path) -> str:
+    """A path as a person in the current folder would type it."""
+    relative = os.path.relpath(path)
+    return relative if not relative.startswith("..") else str(path)
+
+
+def _line(outcome: Outcome) -> str:
+    """The one line that says what happened to a graph."""
+    name = outcome.graph.name
+    if outcome.state in ("written", "unchanged"):
+        return f"ok {name} ({outcome.state})"
+    if outcome.state == "current":
+        return f"ok {name}"
+    if outcome.state in ("stale", "missing"):
+        return f"{outcome.state} {name}: {_shown_path(outcome.graph.file)}"
+    return f"{outcome.state} {name}"
+
+
+def _report(outcomes: list[Outcome], config: str) -> int:
+    """Print every outcome and, when one is not fine, the command that fixes it."""
+    for outcome in outcomes:
+        print(_line(outcome))
+        for detail in outcome.details:
+            print(f"  {detail}")
+    broken = [o.graph.name for o in outcomes if o.state in ("failed", "refused")]
+    if broken:
+        print(f"fix the build of {', '.join(broken)}, then run: graph-builder write --config {config}")
+    elif not all(o.ok for o in outcomes):
+        print(f"run: graph-builder write --config {config}, and commit the graph files")
+    return 0 if all(o.ok for o in outcomes) else 1
+
+
+def _run(config: str, action: Callable[[list[Graph]], list[Outcome]]) -> int:
+    """Read the config and report what ``action`` did with its graphs."""
+    try:
+        graphs = read_config(config)
+    except ConfigRefused as refused:
+        print(f"config refused: {config}: {refused}", file=sys.stderr)
+        return 2
+    return _report(action(graphs), config)
+
+
+def _validate(source: str) -> int:
+    """Say whether one document — a file, or ``-`` for standard input — is a graph."""
+    try:
+        text = sys.stdin.read() if source == "-" else Path(source).read_text(encoding="utf-8")
+    except OSError as exc:
+        print(f"refused: cannot read {source}: {exc.strerror}")
+        return 1
+    try:
+        document = json.loads(text)
+        check_graph(document)
+    except ValueError as exc:
+        reason = str(exc) if isinstance(exc, GraphRefused) else f"not JSON ({exc})"
+        print(f"refused: {reason}")
+        return 1
+    print(f"ok {document['schema_version']}: {len(document['nodes'])} nodes, {len(document['edges'])} edges")
+    return 0
+
+
+def _skill() -> int:
+    """Print the setup skill for coding agents, to be saved as ``<skills folder>/aoa-graph-builder-setup/SKILL.md``."""
+    sys.stdout.write(files("maxitor").joinpath("skills", "aoa-graph-builder-setup", "SKILL.md").read_text(encoding="utf-8"))
+    return 0
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """
+    AI-CORE-BEGIN
+    ROLE: The ``graph-builder`` console script.
+    CONTRACT: Returns the exit code: 0 — fine; 1 — a graph is not (stale, missing, failed, refused, not a graph); 2 — the config was refused.
+    AI-CORE-END
+    """
+    parser = argparse.ArgumentParser(prog="graph-builder", description="Keep each graph of a repository in its file.")
+    parser.add_argument("--version", action="version", version=f"graph-builder {version('maxitor')}")
+    commands = parser.add_subparsers(dest="command", required=True)
+    for name, about in (
+        ("write", "build every graph and write the files that changed"),
+        ("check", "build every graph and fail if a file is not what its build prints; writes nothing"),
+    ):
+        command = commands.add_parser(name, help=about, description=about)
+        command.add_argument("--config", default=DEFAULT_CONFIG, help=f"the config (default: {DEFAULT_CONFIG})")
+    validate = commands.add_parser("validate", help="say whether one document is a graph")
+    validate.add_argument("source", help="a graph file, or - for standard input")
+    commands.add_parser("skill", help="print the aoa-graph-builder-setup skill for coding agents")
+    args = parser.parse_args(argv)
+    if args.command == "write":
+        return _run(args.config, write)
+    if args.command == "check":
+        return _run(args.config, check)
+    if args.command == "validate":
+        return _validate(args.source)
+    return _skill()
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

maxitor/graph_builder/config.py

@@ -0,0 +1,141 @@
+# packages/maxitor/tools/graph_builder/maxitor/graph_builder/config.py
+"""
+Read ``graph-builder.toml``: the graphs of one repository.
+
+═══════════════════════════════════════════════════════════════════════════════
+PURPOSE
+═══════════════════════════════════════════════════════════════════════════════
+
+A repository lists its graphs in one file. Each ``[[graph]]`` names a graph, the
+folder its build runs in, the shell command that prints it, and the file it is
+saved in. This module reads that file into ``Graph`` values, or refuses it naming
+the graph and the field that are wrong.
+
+═══════════════════════════════════════════════════════════════════════════════
+ARCHITECTURE / DATA FLOW
+═══════════════════════════════════════════════════════════════════════════════
+
+TOML → the config's own version (``graph_builder = "1.0"``) → its JSON Schema
+(``config_schema.json`` beside this module, the one config version there is) → the rules a schema cannot say: names and
+files unique → ``Graph`` values with paths resolved against the config's folder.
+"""
+
+from __future__ import annotations
+
+import json
+import tomllib
+from dataclasses import dataclass
+from functools import cache
+from importlib.resources import files
+from pathlib import Path
+from typing import Any
+
+from jsonschema import Draft202012Validator
+from jsonschema.exceptions import ValidationError, best_match
+
+CONFIG_VERSIONS: tuple[str, ...] = ("1.0",)
+
+
+@dataclass(frozen=True)
+class Graph:
+    """
+    AI-CORE-BEGIN
+    ROLE: One graph of a repository: what it is called, where and how it is built, where it is saved.
+    INVARIANTS: ``cwd`` and ``file`` are absolute, resolved against the config's folder; ``name`` and ``file`` are unique within one config.
+    AI-CORE-END
+    """
+
+    name: str
+    cwd: Path
+    build: str
+    file: Path
+
+
+class ConfigRefused(ValueError):
+    """
+    AI-CORE-BEGIN
+    ROLE: A config refused: which graph, which field, and why.
+    CONTRACT: ``graph`` is the graph's name (``#n`` when it has none, ``None`` for the config itself); ``field`` is the field at fault, ``""`` for the whole file.
+    AI-CORE-END
+    """
+
+    def __init__(self, graph: str | None, field: str, reason: str) -> None:
+        """Keep the three parts and say them in one line."""
+        self.graph = graph
+        self.field = field
+        self.reason = reason
+        where = [f"graph {graph!r}"] if graph is not None else []
+        where += [field] if field else []
+        super().__init__(f"{', '.join(where)}: {reason}" if where else reason)
+
+
+@cache
+def _config_schema() -> dict[str, Any]:
+    """The JSON Schema of the config, version ``1.0``, read once."""
+    text = files("maxitor.graph_builder").joinpath("config_schema.json").read_text(encoding="utf-8")
+    schema: dict[str, Any] = json.loads(text)
+    return schema
+
+
+def _graph_label(document: dict[str, Any], index: int) -> str:
+    """How a refusal names the graph at ``index``: its name, or its place when it has none."""
+    entry = document["graph"][index]
+    name = entry.get("name") if isinstance(entry, dict) else None
+    return name if isinstance(name, str) and name else f"#{index + 1}"
+
+
+def _refusal(document: dict[str, Any], error: ValidationError) -> ConfigRefused:
+    """Turn the first schema error into a refusal that names the graph and the field."""
+    path = list(error.absolute_path)
+    in_graph = len(path) >= 2 and path[0] == "graph" and isinstance(path[1], int)
+    graph = _graph_label(document, int(path[1])) if in_graph else None
+    inner = path[2:] if graph is not None else path
+    instance, schema = error.instance, error.schema
+    if error.validator == "required" and isinstance(instance, dict) and isinstance(error.validator_value, list):
+        missing = [name for name in error.validator_value if name not in instance]
+        return ConfigRefused(graph, ".".join(map(str, [*inner, missing[0]])), "required")
+    if error.validator == "additionalProperties" and isinstance(instance, dict) and isinstance(schema, dict):
+        unknown = sorted(set(instance) - set(schema.get("properties", {})))
+        return ConfigRefused(graph, ".".join(map(str, [*inner, unknown[0]])), "not a field of the config")
+    return ConfigRefused(graph, ".".join(map(str, inner)), error.message)
+
+
+def read_config(path: str | Path) -> list[Graph]:
+    """
+    AI-CORE-BEGIN
+    ROLE: Read a repository's ``graph-builder.toml`` into its graphs.
+    CONTRACT: Returns the graphs in file order, paths absolute; raises ``ConfigRefused`` naming the graph and the field — a missing file, not TOML, no or unknown ``graph-builder`` version, a missing or unknown field, a repeated name, two graphs with one file.
+    AI-CORE-END
+    """
+    config = Path(path)
+    try:
+        document = tomllib.loads(config.read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        raise ConfigRefused(None, "", f"no config at {config}") from None
+    except tomllib.TOMLDecodeError as exc:
+        raise ConfigRefused(None, "", f"not TOML: {exc}") from None
+    version = document.get("graph_builder")
+    if version is None:
+        raise ConfigRefused(None, "graph_builder", 'required: the config\'s format version, graph_builder = "1.0"')
+    if version not in CONFIG_VERSIONS:
+        known = ", ".join(CONFIG_VERSIONS)
+        raise ConfigRefused(None, "graph_builder", f"unknown config version {version!r}; known: {known}")
+    error = best_match(Draft202012Validator(_config_schema()).iter_errors(document))
+    if error is not None:
+        raise _refusal(document, error)
+    base = config.resolve().parent
+    graphs: list[Graph] = []
+    for entry in document["graph"]:
+        graph = Graph(
+            name=entry["name"],
+            cwd=(base / entry.get("cwd", ".")).resolve(),
+            build=entry["build"],
+            file=(base / entry["file"]).resolve(),
+        )
+        for earlier in graphs:
+            if earlier.name == graph.name:
+                raise ConfigRefused(graph.name, "name", "another graph has this name")
+            if earlier.file == graph.file:
+                raise ConfigRefused(graph.name, "file", f"graph {earlier.name!r} is saved in this file too")
+        graphs.append(graph)
+    return graphs

maxitor/graph_builder/config_schema.json

@@ -0,0 +1,105 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/bystrovmaxim/aoa/main/packages/maxitor/tools/graph_builder/maxitor/graph_builder/config_schema.json",
+  "title": "graph-builder config",
+  "description": "graph-builder.toml: the graphs of one repository, each built by a command and saved in a file.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["graph_builder", "graph"],
+  "properties": {
+    "graph_builder": {
+      "const": "1.0"
+    },
+    "setup": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "skill",
+        "decided",
+        "deferred"
+      ],
+      "description": "Wizard decisions, not evidence of current health or a project release version.",
+      "properties": {
+        "skill": {
+          "type": "string",
+          "pattern": "^[1-9][0-9]*$"
+        },
+        "decided": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "pattern": "^(config|local-update|ci-graph-check|version-tags|graph:.+|exporter:.+)$"
+          }
+        },
+        "deferred": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "enum": [
+              "local-update",
+              "ci-graph-check"
+            ]
+          }
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "deferred": {
+                "contains": {
+                  "const": "local-update"
+                }
+              }
+            }
+          },
+          "then": {
+            "properties": {
+              "decided": {
+                "contains": {
+                  "const": "local-update"
+                }
+              }
+            }
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "deferred": {
+                "contains": {
+                  "const": "ci-graph-check"
+                }
+              }
+            }
+          },
+          "then": {
+            "properties": {
+              "decided": {
+                "contains": {
+                  "const": "ci-graph-check"
+                }
+              }
+            }
+          }
+        }
+      ]
+    },
+    "graph": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["name", "build", "file"],
+        "properties": {
+          "name": {"type": "string", "minLength": 1},
+          "cwd": {"type": "string", "minLength": 1},
+          "build": {"type": "string", "minLength": 1},
+          "file": {"type": "string", "minLength": 1}
+        }
+      }
+    }
+  }
+}

maxitor/graph_builder/differences.py

@@ -0,0 +1,134 @@
+# packages/maxitor/tools/graph_builder/maxitor/graph_builder/differences.py
+"""
+Name what changed between two graph documents, by ``id``.
+
+═══════════════════════════════════════════════════════════════════════════════
+PURPOSE
+═══════════════════════════════════════════════════════════════════════════════
+
+When a saved graph is stale, a person needs to see what moved, not a text diff
+of thousands of lines. Nodes and edges carry an ``id``, so an element is matched
+by it wherever it sits in the file, and each change is one line.
+
+═══════════════════════════════════════════════════════════════════════════════
+ARCHITECTURE / DATA FLOW
+═══════════════════════════════════════════════════════════════════════════════
+
+::
+
+    old, new ──► maxitor.graph_compare.compare ──► one line per element added or removed,
+                                                   one per property of a changed one
+             └─ the other top-level keys (``schema_version``) ──► walked as plain JSON
+             └─ a document compare refuses ──► the whole of it walked as plain JSON
+
+The comparison itself is ``maxitor.graph_compare``'s, the one Maxitor draws from:
+a ``1.0`` graph's edges get their ids by #285's rule. Only a document that cannot be
+compared — a broken file ``check`` still has to explain — falls back to a generic walk:
+objects key by key, an array whose items all carry an ``id`` by ``id``, anything else
+by equality.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterator, Mapping
+from typing import Any
+
+from maxitor.graph_compare import Change, Comparison, GraphNotComparableError, Status, compare
+
+SHOWN_CHARACTERS = 60
+
+_ELEMENTS = ("nodes", "edges")
+"""The top-level keys whose items the comparison matches by id."""
+
+
+def _shown(value: Any) -> str:
+    """A value as one short line: text as it is, anything else as JSON."""
+    text = value if isinstance(value, str) else json.dumps(value, ensure_ascii=False, sort_keys=True)
+    return text if len(text) <= SHOWN_CHARACTERS else text[: SHOWN_CHARACTERS - 1] + "…"
+
+
+def _by_id(items: list[Any]) -> dict[str, Any] | None:
+    """The items keyed by ``id`` when every item is an object with its own ``id``; otherwise ``None``."""
+    keyed: dict[str, Any] = {}
+    for item in items:
+        if not isinstance(item, dict) or not isinstance(item.get("id"), str) or item["id"] in keyed:
+            return None
+        keyed[item["id"]] = item
+    return keyed
+
+
+def _walk(old: Any, new: Any, path: str) -> Iterator[str]:
+    """Every difference under ``path``, one line each, in a stable order — for what the comparison does not read."""
+    if isinstance(old, dict) and isinstance(new, dict):
+        for key in sorted(old.keys() | new.keys()):
+            inner = f"{path}.{key}" if path else key
+            if key not in new:
+                yield f"{inner}: removed"
+            elif key not in old:
+                yield f"{inner}: added"
+            else:
+                yield from _walk(old[key], new[key], inner)
+        return
+    if isinstance(old, list) and isinstance(new, list):
+        old_ids, new_ids = _by_id(old), _by_id(new)
+        if old_ids is not None and new_ids is not None:
+            for item_id in [*old_ids, *(i for i in new_ids if i not in old_ids)]:
+                inner = f"{path}[id={item_id}]"
+                if item_id not in new_ids:
+                    yield f"{inner}: removed"
+                elif item_id not in old_ids:
+                    yield f"{inner}: added"
+                else:
+                    yield from _walk(old_ids[item_id], new_ids[item_id], inner)
+            return
+    if old != new:
+        yield f"{path}: {_shown(old)} → {_shown(new)}"
+
+
+def _compared(comparison: Comparison, kind: str) -> Iterator[str]:
+    """One kind's lines from the comparison: an element added or removed, or each changed property by its path."""
+    for element_id, item in (comparison.nodes if kind == "nodes" else comparison.edges).items():
+        head = f"{kind}[id={element_id}]"
+        if item.status is Status.ADDED or item.status is Status.REMOVED:
+            yield f"{head}: {item.status.value}"
+        for difference in item.differences:
+            path = head + "".join(f".{key}" for key in difference.path)
+            if difference.change is Change.CHANGED:
+                yield f"{path}: {_shown(difference.before)} → {_shown(difference.after)}"
+            else:
+                yield f"{path}: {difference.change.value}"
+
+
+def _lines(old: Any, new: Any) -> Iterator[str]:
+    """Every line, top-level keys in order: nodes and edges from the comparison, the rest walked."""
+    if not (isinstance(old, Mapping) and isinstance(new, Mapping)):
+        yield from _walk(old, new, "")
+        return
+    try:
+        comparison = compare(old, new)
+    except GraphNotComparableError:
+        yield from _walk(old, new, "")
+        return
+    for key in sorted(old.keys() | new.keys()):
+        if key in _ELEMENTS:
+            yield from _compared(comparison, key)
+        elif key not in new:
+            yield f"{key}: removed"
+        elif key not in old:
+            yield f"{key}: added"
+        else:
+            yield from _walk(old[key], new[key], key)
+
+
+def differences(old: Any, new: Any, limit: int = 20) -> list[str]:
+    """
+    AI-CORE-BEGIN
+    ROLE: The differences between two graph documents, one line each, elements matched by ``id``.
+    CONTRACT: Returns ``[]`` when the documents are equal; otherwise at most ``limit`` lines, then ``… and N more``.
+    AI-CORE-END
+    """
+    lines = list(_lines(old, new))
+    if len(lines) > limit:
+        return [*lines[:limit], f"… and {len(lines) - limit} more"]
+    return lines