chipgraph 0.1.0__py3-none-any.whl

chipgraph/core/runtime/roles/review.py

@@ -0,0 +1,275 @@
+"""`ReviewReport`: a review task's structured reply (DESIGN.md 4.8, 5.1).
+
+A role that writes no files (the Critic) replies with one JSON object, a `ReviewReport`;
+the engine checks it against what the role was shown and writes it as the task's one
+output (the role's `engine_writes`). What it was shown is a `ReviewScope`: the target,
+the base and head refs, the files of the diff and the new-side line ranges of its hunks
+(`diff_hunks` reads them from a unified diff).
+
+`review_problems(report, scope)` is the pure validator; it lists every problem at once:
+
+- `target`, `base` or `head` other than the scope's;
+- `reviewed` empty, or (with no comments) missing a file of the diff: "no findings" is a
+  claim about every file, so it must say it looked at them all;
+- a duplicate comment id, an empty claim;
+- an empty or unquoted `evidence`: it must quote what the claim rests on, as
+  `path:line text` (or `path:start-end text`, or `model:<key> text`);
+- a comment on a file not in `reviewed`, or on a `file:line` outside the diff's hunks;
+- verdict `approve` with a `blocker` or `major` comment, and `changes_requested` with no
+  comment.
+
+`parse_review(raw)` turns the reply (an object or its JSON text) into a `ReviewReport`,
+or the reasons it is not one. Generic: no harness, tool or project names.
+"""
+
+from __future__ import annotations
+
+import json
+import posixpath
+import re
+from collections.abc import Iterable, Mapping
+from typing import Annotated, Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, StringConstraints, ValidationError
+
+Severity = Literal["blocker", "major", "minor", "nit"]
+"""How much a comment matters: `blocker` and `major` request changes; `minor` and `nit` do not."""
+
+BLOCKING_SEVERITIES: frozenset[str] = frozenset({"blocker", "major"})
+"""Severities an `approve` verdict must not carry."""
+
+Verdict = Literal["approve", "changes_requested"]
+
+CommentId = Annotated[str, StringConstraints(pattern=r"^[A-Za-z0-9][A-Za-z0-9_.-]*$")]
+"""A comment id, unique in its review, e.g. `R1`."""
+
+Category = Annotated[str, StringConstraints(pattern=r"^[a-z][a-z0-9_]*$")]
+"""A comment category, lower_snake_case; the review skill lists the ones to use."""
+
+_EVIDENCE_RE = re.compile(
+    r"^\s*(?:(?P<path>[^\s:]+):(?P<line>\d+)(?:-(?P<end>\d+))?|model:(?P<key>\S+))\s+\S"
+)
+_HUNK_RE = re.compile(r"^@@ -\d+(?:,\d+)? \+(?P<start>\d+)(?:,(?P<count>\d+))? @@")
+
+
+class ReviewComment(BaseModel):
+    """One finding: where it is, what is wrong, what it rests on, what to do."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    id: CommentId = Field(description="Unique in the review, e.g. 'R1'.")
+    severity: Severity = Field(description="blocker | major (request changes), minor | nit.")
+    category: Category = Field(
+        description="What kind of problem, lower_snake_case (the review skill lists them)."
+    )
+    file: str = Field(min_length=1, description="Repo-relative file the comment is on.")
+    line: int = Field(ge=1, description="Line in the new version of `file`, inside the diff.")
+    claim: str = Field(description="What is wrong, in one or two sentences.")
+    evidence: str = Field(
+        description=(
+            "What the claim rests on, quoted: 'path:line text' (a spec or code line), "
+            "'path:start-end text' or 'model:<key> text'. Mandatory."
+        )
+    )
+    suggestion: str = Field(default="", description="What to change, if known.")
+    req_id: str | None = Field(
+        default=None, description="The requirement id the comment is about, if any."
+    )
+
+
+class ReviewReport(BaseModel):
+    """A review task's reply: what was reviewed, the comments, the verdict."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    schema_version: Literal[1] = Field(default=1, description="Schema version of this model.")
+    target: str = Field(min_length=1, description="What was reviewed (the block), as given.")
+    base: str = Field(min_length=1, description="The base ref of the diff, as given.")
+    head: str = Field(min_length=1, description="The head ref of the diff, as given.")
+    reviewed: tuple[str, ...] = Field(
+        description="Repo-relative files looked at; every file of the diff when no comments."
+    )
+    comments: tuple[ReviewComment, ...] = Field(
+        default=(), description="The findings; empty means no findings."
+    )
+    summary: str = Field(description="One short paragraph: what changed and the verdict's reason.")
+    verdict: Verdict = Field(description="approve, or changes_requested.")
+
+
+class ReviewScope(BaseModel):
+    """What a review task was shown: the refs and the diff's files and hunks."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    schema_version: Literal[1] = Field(default=1, description="Schema version of this model.")
+    target: str = Field(description="What is reviewed (the block).")
+    base: str = Field(description="The base ref of the diff.")
+    head: str = Field(description="The head ref of the diff.")
+    hunks: dict[str, tuple[tuple[int, int], ...]] = Field(
+        default_factory=dict,
+        description="Each file of the diff to the new-side line ranges of its hunks (inclusive).",
+    )
+
+    @property
+    def files(self) -> tuple[str, ...]:
+        """The files of the diff, sorted."""
+        return tuple(sorted(self.hunks))
+
+
+def diff_hunks(diff: str) -> dict[str, tuple[tuple[int, int], ...]]:
+    """The new-side line ranges (inclusive, context lines included) per file of a diff.
+
+    `diff` is unified diff text (`git diff` output). A deleted file has no new side and is
+    left out; a hunk that only removes lines covers the line before and after the cut.
+    """
+    hunks: dict[str, list[tuple[int, int]]] = {}
+    current: str | None = None
+    prev = ""
+    for line in diff.splitlines():
+        header, prev = line.startswith("+++ ") and prev.startswith("--- "), line
+        if header:
+            new = line[4:].strip()
+            if new == "/dev/null":
+                current = None
+            else:
+                current = new[2:] if new.startswith("b/") else new
+                hunks.setdefault(current, [])
+            continue
+        match = _HUNK_RE.match(line)
+        if match and current is not None:
+            start = int(match.group("start"))
+            count = int(match.group("count") or "1")
+            if count == 0:
+                hunks[current].append((max(start, 1), start + 1))
+            else:
+                hunks[current].append((start, start + count - 1))
+    return {path: tuple(ranges) for path, ranges in hunks.items()}
+
+
+def _clean_path(path: str) -> bool:
+    text = path.strip()
+    if not text or text.startswith("/") or "\\" in text:
+        return False
+    norm = posixpath.normpath(text)
+    return norm == text and norm not in (".", "..") and not norm.startswith("../")
+
+
+def _ranges(ranges: Iterable[tuple[int, int]]) -> str:
+    return ", ".join(f"{a}-{b}" if a != b else str(a) for a, b in ranges)
+
+
+def evidence_ok(evidence: str) -> bool:
+    """Whether `evidence` quotes a source: `path:line text`, `path:a-b text`, `model:<key> text`."""
+    return bool(_EVIDENCE_RE.match(evidence))
+
+
+def review_problems(report: ReviewReport, scope: ReviewScope) -> list[str]:
+    """Every reason `report` is not a valid review of `scope` (empty: valid)."""
+    problems: list[str] = []
+    for name in ("target", "base", "head"):
+        got, want = getattr(report, name), getattr(scope, name)
+        if got != want:
+            problems.append(f"{name} {got!r} is not the task's {name} {want!r}")
+
+    reviewed = set(report.reviewed)
+    if not report.reviewed:
+        problems.append("reviewed is empty: list the files you looked at")
+    bad = [p for p in report.reviewed if not _clean_path(p)]
+    if bad:
+        problems.append(f"reviewed has paths that are not repo-relative: {', '.join(bad)}")
+    if not report.comments:
+        missing = [f for f in scope.files if f not in reviewed]
+        if missing:
+            problems.append(
+                "a review with no comments says the whole diff is fine, so reviewed must "
+                f"list every file of the diff; missing: {', '.join(missing)}"
+            )
+
+    seen: set[str] = set()
+    for comment in report.comments:
+        where = f"comment {comment.id}"
+        if comment.id in seen:
+            problems.append(f"{where}: duplicate comment id {comment.id!r}")
+        seen.add(comment.id)
+        if not comment.claim.strip():
+            problems.append(f"{where}: claim is empty")
+        if not comment.evidence.strip():
+            problems.append(
+                f"{where}: evidence is empty; quote the spec line or code the claim rests "
+                "on, as 'path:line text'"
+            )
+        elif not evidence_ok(comment.evidence):
+            problems.append(
+                f"{where}: evidence {comment.evidence[:80]!r} does not quote a source; "
+                "write 'path:line text' (or 'path:start-end text', 'model:<key> text')"
+            )
+        if comment.file not in reviewed:
+            problems.append(f"{where}: file {comment.file!r} is not in reviewed")
+        ranges = scope.hunks.get(comment.file)
+        if ranges is None:
+            problems.append(
+                f"{where}: {comment.file}:{comment.line} is outside the diff "
+                f"({comment.file!r} is not one of its files: {', '.join(scope.files) or 'none'})"
+            )
+        elif not any(a <= comment.line <= b for a, b in ranges):
+            problems.append(
+                f"{where}: {comment.file}:{comment.line} is outside the diff (its hunks "
+                f"cover lines {_ranges(ranges)} of {comment.file})"
+            )
+
+    blocking = [c.id for c in report.comments if c.severity in BLOCKING_SEVERITIES]
+    if report.verdict == "approve" and blocking:
+        problems.append(
+            f"verdict 'approve' with blocker or major comments ({', '.join(blocking)}); "
+            "use 'changes_requested' or lower their severity"
+        )
+    if report.verdict == "changes_requested" and not report.comments:
+        problems.append("verdict 'changes_requested' with no comments; say what to change")
+    return problems
+
+
+def _validation_lines(exc: ValidationError) -> list[str]:
+    lines = []
+    for error in exc.errors():
+        loc = ".".join(str(p) for p in error.get("loc", ())) or "review"
+        lines.append(f"review.{loc}: {error.get('msg', 'invalid')}")
+    return lines
+
+
+def parse_review(raw: Mapping[str, Any] | str) -> tuple[ReviewReport | None, list[str]]:
+    """The reply as a `ReviewReport`, or `None` and why it is not one.
+
+    `raw` is the reply object, or its JSON text (a fenced ```json block is unwrapped).
+    """
+    data: Any = raw
+    if isinstance(raw, str):
+        text = raw.strip()
+        fenced = re.fullmatch(r"```(?:json)?\s*\n(?P<body>.*)\n```", text, flags=re.DOTALL)
+        if fenced:
+            text = fenced.group("body")
+        try:
+            data = json.loads(text)
+        except json.JSONDecodeError as exc:
+            return None, [f"review is not valid JSON: {exc}"]
+    if not isinstance(data, Mapping):
+        return None, [f"review must be a JSON object, not {type(data).__name__}"]
+    try:
+        return ReviewReport.model_validate(dict(data)), []
+    except ValidationError as exc:
+        return None, _validation_lines(exc)
+
+
+__all__ = [
+    "BLOCKING_SEVERITIES",
+    "Category",
+    "CommentId",
+    "ReviewComment",
+    "ReviewReport",
+    "ReviewScope",
+    "Severity",
+    "Verdict",
+    "diff_hunks",
+    "evidence_ok",
+    "parse_review",
+    "review_problems",
+]

chipgraph/core/runtime/roles/schema.py

@@ -0,0 +1,82 @@
+"""JSON Schema files for the role and skill files and the review reply, under `schemas/roles/`.
+
+    python -m chipgraph.core.runtime.roles.schema [--check] [--out DIR]
+
+`make schemas` runs it after the contract schemas; `make schemas-check` with `--check`.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from chipgraph.core.runtime.roles.review import ReviewReport
+from chipgraph.core.runtime.roles.skills import SkillSpec
+from chipgraph.core.runtime.roles.spec import RoleSpec
+
+SCHEMA_MODELS = (RoleSpec, SkillSpec, ReviewReport)
+"""The models whose schemas are committed, as `<Model>.schema.json`."""
+
+
+def generate() -> dict[str, str]:
+    """File name to content, for every schema file."""
+    files = {}
+    for model in SCHEMA_MODELS:
+        schema = model.model_json_schema()
+        files[f"{model.__name__}.schema.json"] = json.dumps(schema, indent=2, sort_keys=True) + "\n"
+    return files
+
+
+def _repo_schemas_dir() -> Path:
+    here = Path(__file__).resolve()
+    for candidate in here.parents:
+        if (candidate / "pyproject.toml").is_file():
+            return candidate / "schemas" / "roles"
+    raise FileNotFoundError(f"no pyproject.toml found above {here}")
+
+
+def check(out_dir: Path) -> list[str]:
+    """Problems with the committed files in `out_dir` (empty: up to date)."""
+    expected = generate()
+    problems = []
+    for name, content in expected.items():
+        path = out_dir / name
+        if not path.is_file():
+            problems.append(f"missing: roles/{name}")
+        elif path.read_text(encoding="utf-8") != content:
+            problems.append(f"outdated: roles/{name}")
+    if out_dir.is_dir():
+        for path in sorted(out_dir.glob("*.schema.json")):
+            if path.name not in expected:
+                problems.append(f"extra: roles/{path.name}")
+    return problems
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--check", action="store_true", help="check, do not write; exit 1 if out of date"
+    )
+    parser.add_argument("--out", type=Path, default=None, help="default: schemas/roles/")
+    args = parser.parse_args(argv)
+    out_dir: Path = args.out if args.out is not None else _repo_schemas_dir()
+    if args.check:
+        problems = check(out_dir)
+        for problem in problems:
+            print(f"  {problem}", file=sys.stderr)
+        if problems:
+            print("role schemas out of date: run `make schemas`", file=sys.stderr)
+            return 1
+        print(f"role schemas up to date in {out_dir}")
+        return 0
+    out_dir.mkdir(parents=True, exist_ok=True)
+    for name, content in generate().items():
+        (out_dir / name).write_text(content, encoding="utf-8")
+    print(f"wrote role schemas to {out_dir}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

chipgraph/core/runtime/roles/skills.py

@@ -0,0 +1,134 @@
+"""Skills: per-artifact-kind instructions a role loads for a task (DESIGN.md 5.1, D8).
+
+A skill is a markdown file with a YAML frontmatter::
+
+    ---
+    id: lang-sv/rtl            # <namespace>/<name>
+    description: One line.
+    roles: [author]            # the roles that may use it
+    version: 0.1.0
+    ---
+    The instructions (the body).
+
+Packs list skill files, or directories of `*.md` skill files, in `provides.skills`.
+`load_skills(packs)` reads every skill of the given packs; `SkillSet.resolve(ids, role)`
+returns the skills a task names, and refuses an unknown id or a skill its role may not
+use.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from pathlib import Path
+from types import MappingProxyType
+from typing import Annotated, Literal
+
+import yaml
+from pydantic import BaseModel, ConfigDict, Field, StringConstraints, ValidationError
+
+from chipgraph.core.plugin_api.pack import Pack
+from chipgraph.core.runtime.roles.registry import find_role
+from chipgraph.core.runtime.roles.spec import RoleId, split_frontmatter
+
+SkillId = Annotated[str, StringConstraints(pattern=r"^[a-z0-9][a-z0-9-]*/[a-z0-9][a-z0-9_-]*$")]
+"""A skill id, `<namespace>/<name>`, e.g. `lang-sv/rtl`."""
+
+
+class SkillError(Exception):
+    """A broken skill file, a duplicate or unknown id, or a skill its role may not use."""
+
+
+class SkillSpec(BaseModel):
+    """One skill: its frontmatter plus the instructions (the file's body)."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    schema_version: Literal[1] = Field(default=1, description="Schema version of this model.")
+    id: SkillId = Field(description="The skill id, '<namespace>/<name>'.")
+    description: str = Field(min_length=1, description="One line: what the skill is for.")
+    roles: tuple[RoleId, ...] = Field(min_length=1, description="The roles that may use it.")
+    version: Annotated[str, StringConstraints(pattern=r"^\d+\.\d+\.\d+$")] = Field(
+        description="The skill's version, MAJOR.MINOR.PATCH."
+    )
+    text: str = Field(min_length=1, description="The instructions: the file's body.")
+
+
+def parse_skill_file(path: Path) -> SkillSpec:
+    """Load one skill file. Raises `SkillError` for a bad file or an unknown role."""
+    try:
+        data, body = split_frontmatter(path.read_text(encoding="utf-8"), source=str(path))
+        if "text" in data:
+            raise ValueError(f"{path}: the text is the file's body, not a frontmatter key")
+        skill = SkillSpec.model_validate({**data, "text": body})
+    except (OSError, ValueError, ValidationError, yaml.YAMLError) as exc:
+        raise SkillError(f"invalid skill file {path}: {exc}") from exc
+    unknown = [r for r in skill.roles if find_role(r) is None]
+    if unknown:
+        raise SkillError(f"skill {skill.id!r} in {path} names unknown roles: {', '.join(unknown)}")
+    return skill
+
+
+def _skill_files(path: Path) -> list[Path]:
+    return sorted(path.glob("*.md")) if path.is_dir() else [path]
+
+
+class SkillSet:
+    """The skills of a set of packs, by id."""
+
+    def __init__(self, skills: Mapping[str, SkillSpec], sources: Mapping[str, str]) -> None:
+        self.skills = MappingProxyType(dict(skills))
+        self._sources = MappingProxyType(dict(sources))
+
+    def source(self, skill_id: str) -> str:
+        """Where a skill was loaded from (pack name and file)."""
+        return self._sources[skill_id]
+
+    def get(self, skill_id: str) -> SkillSpec:
+        """The skill `skill_id`; raises `SkillError` if no loaded pack provides it."""
+        skill = self.skills.get(skill_id)
+        if skill is None:
+            known = ", ".join(sorted(self.skills)) or "none"
+            raise SkillError(
+                f"unknown skill {skill_id!r}: no pack of this project provides it "
+                f"(skills available: {known})"
+            )
+        return skill
+
+    def resolve(self, skill_ids: Iterable[str], role: str) -> tuple[SkillSpec, ...]:
+        """The skills `skill_ids` for a task of `role`, in order.
+
+        Raises `SkillError` for an unknown id, or a skill whose `roles` does not list
+        `role` (a `<namespace>/` prefix on the role is ignored).
+        """
+        role_id = role.rsplit("/", 1)[-1]
+        found: list[SkillSpec] = []
+        for skill_id in skill_ids:
+            skill = self.get(skill_id)
+            if role_id not in skill.roles:
+                raise SkillError(
+                    f"skill {skill_id!r} is not for role {role_id!r} "
+                    f"(it may be used by: {', '.join(skill.roles)})"
+                )
+            found.append(skill)
+        return tuple(found)
+
+
+def load_skills(packs: Iterable[Pack]) -> SkillSet:
+    """Every skill the packs provide. Raises `SkillError` for a broken file or a duplicate id."""
+    skills: dict[str, SkillSpec] = {}
+    sources: dict[str, str] = {}
+    for pack in packs:
+        for rel in pack.manifest.provides.skills:
+            for path in _skill_files(pack.path(rel)):
+                skill = parse_skill_file(path)
+                where = f"pack {pack.manifest.name!r} ({path})"
+                if skill.id in skills:
+                    raise SkillError(
+                        f"duplicate skill id {skill.id!r}: in {sources[skill.id]} and {where}"
+                    )
+                skills[skill.id] = skill
+                sources[skill.id] = where
+    return SkillSet(skills, sources)
+
+
+__all__ = ["SkillError", "SkillId", "SkillSet", "SkillSpec", "load_skills", "parse_skill_file"]