devlyn-cli 4.1.0 → 4.2.1

package/config/skills/_shared/expected-contract.py

@@ -0,0 +1,242 @@
+#!/usr/bin/env python3
+"""Strict JSON and `spec.expected.json` contract validation for the ideate loop's package check and acceptance runner."""
+from __future__ import annotations
+
+import json
+import sys
+import unittest
+
+
+def reject_json_constant(token: str) -> None:
+    raise ValueError(f"invalid JSON numeric constant: {token}")
+
+
+def reject_duplicate_keys(pairs: list[tuple[str, object]]) -> dict:
+    result = {}
+    for key, value in pairs:
+        if key in result:
+            raise ValueError(f"duplicate JSON key: {key}")
+        result[key] = value
+    return result
+
+
+def loads_strict_json(text: str):
+    return json.loads(
+        text,
+        parse_constant=reject_json_constant,
+        object_pairs_hook=reject_duplicate_keys,
+    )
+
+
+EXPECTED_TOP_LEVEL_KEYS = {
+    "verification_commands",
+    "forbidden_patterns",
+    "required_files",
+    "forbidden_files",
+    "max_deps_added",
+    "pure_design",
+}
+EXPECTED_VERIFICATION_COMMAND_KEYS = {
+    "cmd",
+    "argv",
+    "exit_code",
+    "timeout_sec",
+    "stdout_contains",
+    "stdout_not_contains",
+    "contract_refs",
+}
+DEFAULT_TIMEOUT_SEC = 60
+
+
+def verification_timeout_sec(command: dict) -> int:
+    return command.get("timeout_sec", DEFAULT_TIMEOUT_SEC)
+
+
+def validate_command(command: object, label: str) -> str | None:
+    """Validate one command; `argv` and `cmd` are mutually exclusive."""
+    if not isinstance(command, dict):
+        return f"{label} must be an object"
+    if "argv" in command:
+        if "cmd" in command:
+            return f"{label} requires exactly one of cmd or argv"
+        value = command["argv"]
+        if not isinstance(value, list) or not value or not all(isinstance(item, str) for item in value) or not value[0]:
+            return f"{label}.argv must be a string array with non-empty argv[0]"
+    else:
+        cmd = command.get("cmd")
+        if not isinstance(cmd, str) or not cmd.strip():
+            return f"{label}.cmd must be a non-empty string"
+    ec = command.get("exit_code", 0)
+    if isinstance(ec, bool) or not isinstance(ec, int):
+        return f"{label}.exit_code must be int (not bool)"
+    timeout_sec = command.get("timeout_sec", DEFAULT_TIMEOUT_SEC)
+    if isinstance(timeout_sec, bool) or not isinstance(timeout_sec, int) or not 1 <= timeout_sec <= 600:
+        return f"{label}.timeout_sec must be int from 1 to 600 (not bool)"
+    for k in ("stdout_contains", "stdout_not_contains"):
+        v = command.get(k, [])
+        if not isinstance(v, list) or not all(isinstance(s, str) and s for s in v):
+            return f"{label}.{k} must be a list of non-empty strings"
+    return None
+
+
+def validate_shape(data) -> str | None:
+    """Return None if `data` has a non-empty, well-formed `verification_commands`
+    list; else a human-readable error string.
+
+    Each object requires exactly one of a non-empty string `cmd` or a
+    string-array `argv`; `exit_code` defaults to 0 and must be a
+    non-bool int; `timeout_sec` defaults to DEFAULT_TIMEOUT_SEC and must be a
+    non-bool int from 1 through 600; `stdout_contains` and `stdout_not_contains`
+    default to empty lists of non-empty strings. Bool is rejected explicitly
+    because Python's `bool` subclasses `int`.
+    """
+    if not isinstance(data, dict):
+        return "top-level must be a JSON object"
+    cmds = data.get("verification_commands")
+    if not isinstance(cmds, list):
+        return "verification_commands must be a list"
+    if not cmds:
+        return "verification_commands must contain at least one entry"
+    for i, c in enumerate(cmds):
+        err = validate_command(c, f"verification_commands[{i}]")
+        if err:
+            return err
+    return None
+
+
+def validate_string_list(data: object, key: str) -> str | None:
+    value = data.get(key, []) if isinstance(data, dict) else None
+    if not isinstance(value, list) or not all(isinstance(item, str) and item for item in value):
+        return f"{key} must be a list of non-empty strings"
+    return None
+
+
+def validate_expected_shape(data) -> str | None:
+    """Return None if shape matches the sibling spec.expected.json schema.
+
+    Keep this dependency-free: it mirrors `_shared/expected.schema.json` enough
+    to catch malformed contracts before a consumer executes them.
+    """
+    if not isinstance(data, dict):
+        return "top-level must be a JSON object"
+    unknown = sorted(set(data) - EXPECTED_TOP_LEVEL_KEYS)
+    if unknown:
+        return f"unknown top-level key(s): {', '.join(unknown)}"
+    if "verification_commands" in data:
+        commands = data["verification_commands"]
+        if not isinstance(commands, list):
+            return "verification_commands must be a list"
+        if commands:
+            err = validate_shape({"verification_commands": commands})
+            if err:
+                return err
+        for i, command in enumerate(commands):
+            unknown_command_keys = sorted(set(command) - EXPECTED_VERIFICATION_COMMAND_KEYS)
+            if unknown_command_keys:
+                return (
+                    f"verification_commands[{i}] unknown key(s): "
+                    f"{', '.join(unknown_command_keys)}"
+                )
+            contract_refs = command.get("contract_refs", [])
+            if not isinstance(contract_refs, list) or not all(
+                isinstance(item, str) and item for item in contract_refs
+            ):
+                return f"verification_commands[{i}].contract_refs must be a list of non-empty strings"
+    for key in ("required_files", "forbidden_files"):
+        err = validate_string_list(data, key)
+        if err:
+            return err
+    max_deps = data.get("max_deps_added", 0)
+    if isinstance(max_deps, bool) or not isinstance(max_deps, int) or max_deps < 0:
+        return "max_deps_added must be a non-negative integer"
+    if "pure_design" in data and not isinstance(data["pure_design"], bool):
+        return "pure_design must be a boolean"
+    patterns = data.get("forbidden_patterns", [])
+    if not isinstance(patterns, list):
+        return "forbidden_patterns must be a list"
+    for i, pattern in enumerate(patterns):
+        if not isinstance(pattern, dict):
+            return f"forbidden_patterns[{i}] must be an object"
+        unknown_pattern_keys = sorted(set(pattern) - {"pattern", "description", "files", "severity"})
+        if unknown_pattern_keys:
+            return (
+                f"forbidden_patterns[{i}] unknown key(s): "
+                f"{', '.join(unknown_pattern_keys)}"
+            )
+        for key in ("pattern", "description", "severity"):
+            value = pattern.get(key)
+            if not isinstance(value, str) or not value:
+                return f"forbidden_patterns[{i}].{key} must be a non-empty string"
+        if pattern["severity"] not in {"disqualifier", "warning"}:
+            return f"forbidden_patterns[{i}].severity must be disqualifier or warning"
+        files = pattern.get("files", [])
+        if not isinstance(files, list) or not all(isinstance(item, str) and item for item in files):
+            return f"forbidden_patterns[{i}].files must be a list of non-empty strings"
+    return None
+
+
+def slice_diff_to_files(diff_text: str, files: list[str]) -> str:
+    if not files:
+        return diff_text
+    out: list[str] = []
+    keep = False
+    for line in diff_text.splitlines(keepends=True):
+        if line.startswith("diff --git "):
+            keep = any(path in line for path in files)
+        if keep:
+            out.append(line)
+    return "".join(out)
+
+
+class ContractTests(unittest.TestCase):
+    def test_strict_json(self):
+        for text, message in (('{"a":1,"a":2}', "duplicate JSON key"), ('{"a":NaN}', "invalid JSON numeric constant")):
+            with self.assertRaisesRegex(ValueError, message):
+                loads_strict_json(text)
+
+    def test_cmd_and_argv_are_mutually_exclusive(self):
+        ok = {"verification_commands": [{"argv": ["python3", "-c", "pass"], "contract_refs": ["R1"]}, {"cmd": "true"}]}
+        self.assertIsNone(validate_expected_shape(ok))
+        for command, message in (
+            ({"cmd": "true", "argv": ["true"]}, "exactly one of cmd or argv"),
+            ({"argv": []}, "argv must be a string array"),
+            ({"argv": ["", "x"]}, "argv must be a string array"),
+            ({"argv": ["x", 1]}, "argv must be a string array"),
+            ({}, "cmd must be a non-empty string"),
+        ):
+            self.assertIn(message, validate_expected_shape({"verification_commands": [command]}))
+
+    def test_command_fields(self):
+        for command, message in (
+            ({"cmd": "x", "exit_code": True}, "exit_code must be int"),
+            ({"cmd": "x", "timeout_sec": 601}, "timeout_sec must be int from 1 to 600"),
+            ({"cmd": "x", "stdout_contains": "x"}, "stdout_contains must be a list of non-empty strings"),
+            ({"cmd": "x", "stdout_contains": [""]}, "stdout_contains must be a list of non-empty strings"),
+            ({"cmd": "x", "stdout_not_contains": [""]}, "stdout_not_contains must be a list of non-empty strings"),
+            ({"cmd": "x", "contract_refs": [""]}, "contract_refs must be a list of non-empty strings"),
+            ({"cmd": "x", "extra": 1}, "unknown key(s): extra"),
+        ):
+            self.assertIn(message, validate_expected_shape({"verification_commands": [command]}))
+        self.assertEqual(validate_expected_shape([]), "top-level must be a JSON object")
+        self.assertIn("unknown top-level key(s): process_evidence", validate_expected_shape({"process_evidence": []}))
+
+    def test_diff_helpers(self):
+        diff = ('diff --git a/package.json b/package.json\n--- a/package.json\n+++ b/package.json\n@@ -1,3 +1,5 @@\n'
+                ' {\n   "dependencies": {\n+    "left-pad": "1.0.0",\n+    "is-odd": "3.0.0"\n   }\n }\n'
+                'diff --git a/other b/other\n+x\n')
+        self.assertNotIn("other", slice_diff_to_files(diff, ["package.json"]))
+        self.assertEqual(slice_diff_to_files(diff, []), diff)
+
+
+def main() -> int:
+    if sys.argv[1:] != ["--self-test"]:
+        print("usage: expected-contract.py --self-test", file=sys.stderr)
+        return 2
+    result = unittest.TextTestRunner(verbosity=1).run(unittest.defaultTestLoader.loadTestsFromTestCase(ContractTests))
+    if result.wasSuccessful():
+        print(f"expected-contract self-test: PASS ({result.testsRun} tests)")
+    return 0 if result.wasSuccessful() else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/config/skills/_shared/expected.schema.json

@@ -6,79 +6,27 @@
   "type": "object",
   "additionalProperties": false,
   "properties": {
-    "process_evidence": {
+    "verification_commands": {
       "type": "array",
-      "description": "Declared process obligations captured during implementation. Each id is unique within its phase; the shared process-evidence runner records raw streams and validates the expectation before IMPLEMENT can pass.",
+      "description": "Each command must pass on the task's committed source. At least one entry is required when the spec has any observable runtime check (CLI, test command, HTTP request).",
       "items": {
         "type": "object",
         "additionalProperties": false,
-        "required": ["id", "phase"],
         "oneOf": [
           { "required": ["cmd"], "not": { "required": ["argv"] } },
           { "required": ["argv"], "not": { "required": ["cmd"] } }
         ],
         "properties": {
-          "id": {
-            "type": "string",
-            "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$",
-            "description": "Stable evidence id, unique within its phase and safe as one path component."
-          },
-          "phase": {
-            "const": "implement",
-            "description": "The phase that must produce this expected-contract obligation."
-          },
           "cmd": {
             "type": "string",
-            "minLength": 1,
-            "description": "Exact shell command executed by the shared runner."
+            "description": "Shell command, executed via `subprocess.run(..., shell=True)` from the build's working directory.",
+            "minLength": 1
           },
           "argv": {
             "type": "array",
             "minItems": 1,
             "items": { "type": "string" },
-            "description": "Exact argv executed without a shell; argv[0] must be non-empty."
-          },
-          "exit_code": {
-            "type": "integer",
-            "minimum": 0,
-            "description": "Required exit code. Default 0 if omitted.",
-            "default": 0
-          },
-          "timeout_sec": {
-            "type": "integer",
-            "minimum": 1,
-            "maximum": 600,
-            "description": "Per-command timeout in seconds. Default 60 if omitted.",
-            "default": 60
-          },
-          "stdout_contains": {
-            "type": "array",
-            "items": { "type": "string", "minLength": 1 },
-            "description": "Each UTF-8 substring must occur in the concatenated raw stdout and stderr bytes.",
-            "default": []
-          },
-          "stdout_not_contains": {
-            "type": "array",
-            "items": { "type": "string", "minLength": 1 },
-            "description": "No UTF-8 substring may occur in the concatenated raw stdout and stderr bytes.",
-            "default": []
-          }
-        }
-      },
-      "default": []
-    },
-    "verification_commands": {
-      "type": "array",
-      "description": "Each command is executed against the post-BUILD code. Each pass/fail contributes to verify_score. At least one entry is required when the spec has any observable runtime check (CLI, test command, HTTP request).",
-      "items": {
-        "type": "object",
-        "additionalProperties": false,
-        "required": ["cmd"],
-        "properties": {
-          "cmd": {
-            "type": "string",
-            "description": "Shell command, executed via `subprocess.run(..., shell=True)` from the build's working directory.",
-            "minLength": 1
+            "description": "Exact argv executed without a shell; argv[0] must be non-empty. Preferred for generated and Windows contracts."
           },
           "exit_code": {
             "type": "integer",
@@ -106,7 +54,7 @@
           },
           "contract_refs": {
             "type": "array",
-            "description": "For hidden BENCH_FIXTURE_DIR commands, exact substrings from spec.md that this oracle verifies. Hidden oracles may test only visible spec clauses.",
+            "description": "Requirements this command verifies. Ideate loop tasks name requirement IDs (R1, R2, ...) from the task Requirements and require at least one.",
             "items": { "type": "string", "minLength": 1 },
             "default": []
           }
@@ -115,7 +63,7 @@
     },
     "forbidden_patterns": {
       "type": "array",
-      "description": "Regex patterns scanned across diff.patch. Match at severity=disqualifier is a hard-floor fail; match at severity=warning is judge-only critical-finding.",
+      "description": "Regex patterns scanned across the task's diff.",
       "items": {
         "type": "object",
         "additionalProperties": false,
@@ -140,14 +88,14 @@
           "severity": {
             "type": "string",
             "enum": ["disqualifier", "warning"],
-            "description": "disqualifier = hard-floor fail (DQ). warning = judge-visible critical-finding only."
+            "description": "disqualifier blocks acceptance; warning is recorded."
           }
         }
       }
     },
     "required_files": {
       "type": "array",
-      "description": "Files specified by literal paths that must exist after the arm runs; globs are not expanded.",
+      "description": "Files specified by literal paths that must exist in the committed source; globs are not expanded.",
       "items": { "type": "string", "minLength": 1 },
       "default": []
     },
@@ -157,21 +105,9 @@
       "items": { "type": "string", "minLength": 1 },
       "default": []
     },
-    "tier_a_waivers": {
-      "type": "array",
-      "description": "Optional fnmatch globs exempted from Tier A scope-oracle path checks when the spec explicitly authorizes those files.",
-      "items": { "type": "string", "minLength": 1 },
-      "default": []
-    },
-    "spec_output_files": {
-      "type": "array",
-      "description": "Files or globs that define the spec-authorized output surface for scope oracles. Touched files outside this set must be reachable from it via static imports or separately waived.",
-      "items": { "type": "string", "minLength": 1 },
-      "default": []
-    },
     "max_deps_added": {
       "type": "integer",
-      "description": "Hard cap on new entries under dependencies/devDependencies in package.json. Exceeds → DQ.",
+      "description": "Hard cap on package names the root package.json's dependencies and devDependencies gain over the task inputs; a move between them adds none.",
       "minimum": 0,
       "default": 0
     },
@@ -179,27 +115,6 @@
       "type": "boolean",
       "description": "Declares that every Requirement is pure-design (no observable runtime check). Lets verification_commands stay empty without failing shape validation. Contradictory (and rejected) when true alongside a non-empty verification_commands.",
       "default": false
-    },
-    "required_risk_probe_requirements": {
-      "type": "array",
-      "description": "Language-neutral replacement for prose-keyword risk-probe classification: explicit {tag, derived_from} obligations the spec author declares directly. When `--risk-probes` is enabled, risk-probes.jsonl must include a probe whose tags include `tag` and whose derived_from exactly equals `derived_from` for each entry.",
-      "items": {
-        "type": "object",
-        "additionalProperties": false,
-        "required": ["tag", "derived_from"],
-        "properties": {
-          "tag": {
-            "type": "string",
-            "description": "One of the risk-probe tags defined in _shared/spec-verify-check.py:RISK_PROBE_TAGS (e.g. ordering_inversion, rollback_state, shape_contract)."
-          },
-          "derived_from": {
-            "type": "string",
-            "description": "Exact substring of the sibling spec.md's visible verification section that demands this tag.",
-            "minLength": 1
-          }
-        }
-      },
-      "default": []
     }
   }
 }