qa-engineer 0.9.2 → 0.11.0

package/shared/analysis/lib/qa_analysis/context.py

@@ -1,233 +0,0 @@
-"""Deterministic parsing of `.qa/context.md`.
-
-`qa-init` writes the project profile as a Markdown file whose frontmatter holds
-the machine-readable facts, and every other skill reads it. The contract for
-those facts is a JSON Schema (`shared/analysis/schemas/context.schema.json`) —
-but nothing could check a *real* `.qa/context.md` against it, because the
-toolkit is standard-library-only and the frontmatter is YAML. Validation ran
-against a hand-written JSON fixture instead, so the contract was unenforced
-exactly where it mattered.
-
-This module closes that gap without adding a dependency or changing the file
-format: it parses the **explicit subset** of YAML the context contract uses,
-then hands the result to the existing contract validator.
-
-## The supported subset
-
-Deliberately small, and everything outside it is an error rather than a guess:
-
-- `key: value` mappings, nested by two-space indentation
-- block sequences (`- item`), including nested under a key
-- flow collections only when empty: `[]` and `{}`
-- scalars: double- or single-quoted strings, bare strings, integers, floats,
-  `true`/`false`, `null`/`~`/empty
-- `#` comments on their own line or after a value
-- the leading/trailing `---` fences
-
-Not supported, and rejected loudly: anchors/aliases, multi-line block scalars
-(`|`, `>`), non-empty flow collections, multi-document streams, and tabs for
-indentation. A generator that needs one of those has outgrown the contract, and
-the right response is to change the contract deliberately — not to have a parser
-quietly misread it.
-"""
-
-import re
-
-from . import contracts
-
-_FENCE = "---"
-_TRUE = ("true", "True", "TRUE")
-_FALSE = ("false", "False", "FALSE")
-_NULL = ("null", "Null", "NULL", "~", "")
-_UNSUPPORTED_SCALARS = ("|", ">")
-_INT = re.compile(r"^-?\d+$")
-_FLOAT = re.compile(r"^-?\d+\.\d+$")
-
-
-class MalformedContext(ValueError):
-    """Raised when `.qa/context.md` cannot be parsed or fails its contract."""
-
-
-def split_frontmatter(text):
-    """Return (frontmatter_text, body_text). Raises if the fences are missing."""
-    lines = text.split("\n")
-    start = None
-    for index, line in enumerate(lines):
-        if line.strip() == "":
-            continue
-        if line.rstrip() == _FENCE:
-            start = index
-        break
-    if start is None:
-        raise MalformedContext(
-            "no frontmatter: the file must open with a '---' fence "
-            "(see the qa-init context template)"
-        )
-    for index in range(start + 1, len(lines)):
-        if lines[index].rstrip() == _FENCE:
-            return "\n".join(lines[start + 1:index]), "\n".join(lines[index + 1:])
-    raise MalformedContext("unterminated frontmatter: no closing '---' fence")
-
-
-def _strip_comment(value):
-    """Remove a trailing `#` comment that is not inside quotes."""
-    quote = None
-    for index, char in enumerate(value):
-        if quote:
-            if char == quote:
-                quote = None
-        elif char in ("'", '"'):
-            quote = char
-        elif char == "#" and (index == 0 or value[index - 1] in " \t"):
-            return value[:index]
-    return value
-
-
-def _scalar(raw, line_number):
-    text = _strip_comment(raw).strip()
-    if text[:1] in _UNSUPPORTED_SCALARS:
-        raise MalformedContext(
-            f"line {line_number}: block scalars ('|', '>') are outside the supported subset"
-        )
-    if text[:1] in ("&", "*"):
-        raise MalformedContext(
-            f"line {line_number}: anchors and aliases are outside the supported subset"
-        )
-    if len(text) >= 2 and text[0] == text[-1] and text[0] in ("'", '"'):
-        return text[1:-1]
-    if text == "[]":
-        return []
-    if text == "{}":
-        return {}
-    if text.startswith("[") or text.startswith("{"):
-        raise MalformedContext(
-            f"line {line_number}: only empty flow collections ('[]', '{{}}') are supported; "
-            "use a block sequence or mapping"
-        )
-    if text in _TRUE:
-        return True
-    if text in _FALSE:
-        return False
-    if text in _NULL:
-        return None
-    if _INT.match(text):
-        return int(text)
-    if _FLOAT.match(text):
-        return float(text)
-    return text
-
-
-def parse_frontmatter(text):
-    """Parse the supported YAML subset into a dict. Raises MalformedContext.
-
-    The parser keeps a stack of `(key_indent, container)` frames. `key_indent` is
-    the column at which that container's own entries start, so a line's indent
-    alone decides which container it belongs to: pop every frame deeper than the
-    line, and the top of the stack is the target.
-    """
-    root = {}
-    stack = [(0, root)]
-    pending = None  # (key, indent) — a key whose value is a block that follows
-
-    def resolve_pending_as_null():
-        """A key with no value and no nested block is a null field."""
-        nonlocal pending
-        if pending is not None:
-            stack[-1][1][pending[0]] = None
-            pending = None
-
-    for number, raw_line in enumerate(text.split("\n"), start=1):
-        leading = raw_line[: len(raw_line) - len(raw_line.lstrip())]
-        if "\t" in leading:
-            raise MalformedContext(f"line {number}: tab indentation is not supported")
-        stripped = raw_line.strip()
-        if not stripped or stripped.startswith("#"):
-            continue
-        if stripped == _FENCE:
-            raise MalformedContext(f"line {number}: unexpected '---' inside frontmatter")
-
-        indent = len(raw_line) - len(raw_line.lstrip(" "))
-
-        # --- sequence item ---
-        if stripped.startswith("- ") or stripped == "-":
-            item = _scalar(stripped[2:] if len(stripped) > 1 else "", number)
-            if pending is not None:
-                # A sequence may sit at the key's indent or deeper.
-                parent = stack[-1][1]
-                parent[pending[0]] = []
-                stack.append((indent, parent[pending[0]]))
-                pending = None
-            while len(stack) > 1 and stack[-1][0] > indent:
-                stack.pop()
-            container = stack[-1][1]
-            if not isinstance(container, list):
-                raise MalformedContext(f"line {number}: sequence item outside a sequence")
-            container.append(item)
-            continue
-
-        # --- mapping entry ---
-        if ":" not in stripped:
-            raise MalformedContext(
-                f"line {number}: expected 'key: value' or '- item', got {stripped!r}"
-            )
-
-        if pending is not None:
-            if indent > pending[1]:
-                # The pending key opens a nested mapping at this indent.
-                parent = stack[-1][1]
-                parent[pending[0]] = {}
-                stack.append((indent, parent[pending[0]]))
-                pending = None
-            else:
-                resolve_pending_as_null()
-
-        # Leave the frames this line does not belong to. A sequence frame at the
-        # same indent as a key also ends here (`packages:` / `- a` / `ci:`).
-        while len(stack) > 1 and (
-            stack[-1][0] > indent
-            or (isinstance(stack[-1][1], list) and stack[-1][0] >= indent)
-        ):
-            stack.pop()
-
-        key, _, value = stripped.partition(":")
-        key = key.strip()
-        if not key:
-            raise MalformedContext(f"line {number}: empty key")
-        container = stack[-1][1]
-        if not isinstance(container, dict):
-            raise MalformedContext(f"line {number}: mapping key inside a sequence")
-
-        if _strip_comment(value).strip() == "":
-            pending = (key, indent)  # a block or a null follows
-        else:
-            container[key] = _scalar(value, number)
-
-    resolve_pending_as_null()
-    return root
-
-
-def parse(text, schema=None):
-    """Parse `.qa/context.md` text and, when a schema is given, validate it.
-
-    Returns {"context": <dict>, "body": <str>, "valid": bool, "errors": [...]}.
-    Raises MalformedContext when the text cannot be parsed at all — a parse
-    failure is not a validation result.
-    """
-    frontmatter, body = split_frontmatter(text)
-    context = parse_frontmatter(frontmatter)
-    result = {"context": context, "body": body, "valid": True, "errors": []}
-    if schema is not None:
-        ok, errors = contracts.validate(context, schema)
-        result["valid"] = ok
-        result["errors"] = errors
-    return result
-
-
-def parse_file(path, schema=None):
-    """Read and parse a `.qa/context.md` file."""
-    try:
-        with open(path, "r", encoding="utf-8") as handle:
-            text = handle.read()
-    except OSError as exc:
-        raise MalformedContext(f"could not read {path}: {exc}") from exc
-    return parse(text, schema=schema)

package/shared/analysis/lib/qa_analysis/contracts.py

@@ -1,158 +0,0 @@
-"""Deterministic contract validation.
-
-A dependency-free validator for the subset of JSON Schema the pack's contracts
-use. It exists so no skill ever emits a result that violates its own contract,
-and so CI can gate on it without a third-party dependency.
-
-The supported subset is declared once, in `SUPPORTED_KEYWORDS`, and is the
-**same** subset the JavaScript twin implements
-(`packages/installer/lib/core/schema-validate.mjs`). Two rules keep that promise
-honest:
-
-1. A keyword outside the subset is an **error**, never a silent no-op — a
-   contract author cannot accidentally write a constraint that looks enforced
-   and isn't.
-2. `tests/parity/validator-cases.json` runs through both validators and both
-   must agree on every case.
-
-The subset includes `allOf` / `if` / `then` / `else` because the pack's safety
-invariants are cross-field implications ("classification `passed` implies exit
-code 0"). Those must be enforced at runtime by the contract itself, not only by
-evaluation fixtures.
-
-This validates the pack's own schemas; it is not a general-purpose JSON Schema
-implementation, and it says so rather than pretending to be one.
-"""
-
-import json
-import re
-
-_TYPES = {
-    "object": dict,
-    "array": list,
-    "string": str,
-    "number": (int, float),
-    "integer": int,
-    "boolean": bool,
-    "null": type(None),
-}
-
-# The complete supported subset. Anything else is reported as a schema error.
-# Keep in sync with SUPPORTED in packages/installer/lib/core/schema-validate.mjs
-# and the table in docs/skills/output-contracts.md (checked by
-# scripts/check-spec-code-sync.mjs).
-SUPPORTED_KEYWORDS = frozenset({
-    "$schema", "$id", "title", "description", "type", "properties", "required",
-    "additionalProperties", "items", "enum", "const", "pattern", "minimum",
-    "maximum", "minItems", "maxItems", "minLength", "maxLength", "default",
-    "examples", "format", "allOf", "if", "then", "else",
-})
-
-# RFC 3339 date-time. Defined here (rather than delegating to
-# datetime.fromisoformat, which also accepts date-only strings and varies by
-# interpreter version) so both validators accept exactly the same set.
-_DATE_TIME = re.compile(
-    r"^\d{4}-\d{2}-\d{2}[Tt]\d{2}:\d{2}:\d{2}(\.\d+)?([Zz]|[+-]\d{2}:\d{2})$"
-)
-
-
-def load_schema(path):
-    with open(path, "r", encoding="utf-8") as handle:
-        return json.load(handle)
-
-
-def validate(instance, schema, path="$"):
-    """Validate instance against schema. Returns (ok, errors) where errors is a
-    list of human-readable "path: problem" strings."""
-    errors = []
-    _validate(instance, schema, path, errors)
-    return (not errors, errors)
-
-
-def _type_ok(value, expected):
-    types = expected if isinstance(expected, list) else [expected]
-    for name in types:
-        py = _TYPES.get(name)
-        if py is None:
-            continue
-        # bool is a subclass of int; keep them distinct.
-        if name == "integer" and isinstance(value, bool):
-            continue
-        if name == "number" and isinstance(value, bool):
-            continue
-        if isinstance(value, py):
-            return True
-    return False
-
-
-def _matches(value, schema):
-    """True when value satisfies schema. Used for if/then branch selection, so
-    it must not leak errors into the caller's list."""
-    probe = []
-    _validate(value, schema, "$", probe)
-    return not probe
-
-
-def _validate(value, schema, path, errors):
-    for keyword in schema:
-        if keyword not in SUPPORTED_KEYWORDS:
-            errors.append(f"{path}: schema uses unsupported keyword \"{keyword}\"")
-
-    if "type" in schema and not _type_ok(value, schema["type"]):
-        errors.append(f"{path}: expected type {schema['type']}, got {type(value).__name__}")
-        return  # further checks assume the type held
-
-    if "const" in schema and value != schema["const"]:
-        errors.append(f"{path}: expected const {schema['const']!r}, got {value!r}")
-
-    if "enum" in schema and value not in schema["enum"]:
-        errors.append(f"{path}: {value!r} is not one of {schema['enum']}")
-
-    if isinstance(value, str):
-        if "pattern" in schema and not re.search(schema["pattern"], value):
-            errors.append(f"{path}: {value!r} does not match pattern {schema['pattern']}")
-        if schema.get("format") == "date-time" and not _DATE_TIME.match(value):
-            errors.append(f"{path}: {value!r} is not a valid date-time")
-        if "minLength" in schema and len(value) < schema["minLength"]:
-            errors.append(f"{path}: shorter than minLength {schema['minLength']}")
-        if "maxLength" in schema and len(value) > schema["maxLength"]:
-            errors.append(f"{path}: longer than maxLength {schema['maxLength']}")
-
-    if isinstance(value, (int, float)) and not isinstance(value, bool):
-        if "minimum" in schema and value < schema["minimum"]:
-            errors.append(f"{path}: {value} < minimum {schema['minimum']}")
-        if "maximum" in schema and value > schema["maximum"]:
-            errors.append(f"{path}: {value} > maximum {schema['maximum']}")
-
-    if isinstance(value, list):
-        if "minItems" in schema and len(value) < schema["minItems"]:
-            errors.append(f"{path}: fewer than minItems {schema['minItems']}")
-        if "maxItems" in schema and len(value) > schema["maxItems"]:
-            errors.append(f"{path}: more than maxItems {schema['maxItems']}")
-        if "items" in schema:
-            for i, item in enumerate(value):
-                _validate(item, schema["items"], f"{path}[{i}]", errors)
-
-    if isinstance(value, dict):
-        for key in schema.get("required", []):
-            if key not in value:
-                errors.append(f"{path}: missing required property '{key}'")
-        properties = schema.get("properties", {})
-        for key, sub in properties.items():
-            if key in value:
-                _validate(value[key], sub, f"{path}.{key}", errors)
-        if schema.get("additionalProperties") is False:
-            for key in value:
-                if key not in properties:
-                    errors.append(f"{path}: additional property '{key}' is not allowed")
-
-    # Applicators last: the invariant layer. `additionalProperties` deliberately
-    # does not see properties introduced by these subschemas (same rule as
-    # JSON Schema 2020-12, and the same as the JavaScript twin).
-    for sub in schema.get("allOf", []):
-        _validate(value, sub, path, errors)
-
-    if "if" in schema:
-        branch = schema.get("then") if _matches(value, schema["if"]) else schema.get("else")
-        if branch is not None:
-            _validate(value, branch, path, errors)