qa-engineer 0.9.0

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

@@ -0,0 +1,175 @@
+"""Product attribution for human-readable reports.
+
+One renderer, one metadata file, three output formats. Every report the pack
+produces for a human ends with the same footer, and changing it means editing
+`branding.json` — nothing else.
+
+## Why this is code and not a string in each skill
+
+A footer typed by a model is a footer that drifts: the tagline gains a word, the
+URL loses a scheme, one report says "Developed by" and the next says "Built by".
+Rendering it deterministically makes every report byte-identical, and makes a
+change to the branding a one-file edit that CI can verify
+(`scripts/check-branding.mjs` fails if any branding string is hardcoded elsewhere).
+
+## What gets a footer, and what must not
+
+Attribution belongs on documents a person reads. It is noise — or worse, a parsing
+hazard — anywhere else.
+
+| Branded | Not branded |
+| --- | --- |
+| HTML reports | JSON and YAML artifacts (`qa-artifacts/*.json`) |
+| PDF reports | CLI stdout, progress output, `--json` output |
+| Rendered Markdown reports meant for people | Markdown written for machine consumption |
+| Generated documentation | Log files, API responses |
+| Evaluation and audit report renderings | The system under test, and anything in a user's own source tree |
+
+The rule behind the table: **if a program will parse it, it gets no footer.** A
+contract artifact is an interface, and appending prose to an interface breaks it.
+
+## Formats
+
+- `footer_html()` — a `<footer>` element with inline styling (so a standalone
+  report file needs no external stylesheet) and the author's site as a link that
+  opens in a new tab with `rel="noopener noreferrer"`.
+- `footer_markdown()` — a thematic break, the four lines, the site as a link.
+- `footer_text()` — rule-separated plain text for PDF writers and terminals-of-last-resort.
+  A PDF library that supports hyperlinks should link the URL; one that does not
+  renders this as-is, which is why the URL appears in full rather than as anchor text.
+
+Standard library only, like the rest of `qa_analysis`.
+"""
+
+import html
+import json
+import pathlib
+
+_METADATA_PATH = pathlib.Path(__file__).resolve().parent / "branding.json"
+
+# The visual width of the plain-text rules. Wide enough to frame the four lines,
+# narrow enough to survive an 80-column terminal or a PDF margin.
+_RULE_WIDTH = 60
+
+_ALLOWED_SCHEMES = ("https://", "http://")
+
+
+class BrandingError(ValueError):
+    """Raised when the branding metadata is missing or unusable."""
+
+
+def metadata():
+    """The branding metadata, as a dict. Read fresh so a change needs no reinstall."""
+    try:
+        with open(_METADATA_PATH, "r", encoding="utf-8") as handle:
+            data = json.load(handle)
+    except (OSError, json.JSONDecodeError) as exc:
+        raise BrandingError(f"could not read branding metadata at {_METADATA_PATH}: {exc}") from exc
+
+    required = ("projectName", "tagline", "author", "website", "attributionPrefix", "authorPrefix")
+    missing = [key for key in required if not data.get(key)]
+    if missing:
+        raise BrandingError(f"branding metadata is missing: {', '.join(missing)}")
+    if not data["website"].startswith(_ALLOWED_SCHEMES):
+        # A footer is rendered into HTML, so a non-http scheme here would be an
+        # injection vector rather than a typo.
+        raise BrandingError(
+            f"branding website must start with http:// or https://, got {data['website']!r}"
+        )
+    return data
+
+
+def _lines(data):
+    """The four footer lines, in order, as plain strings."""
+    return [
+        f"{data['attributionPrefix']} {data['projectName']}",
+        data["tagline"],
+        f"{data['authorPrefix']} {data['author']}",
+        data["website"],
+    ]
+
+
+def footer_text(width=_RULE_WIDTH):
+    """Rule-separated plain text. Used for PDF and any non-markup rendering."""
+    data = metadata()
+    rule = "-" * width
+    body = "\n".join(line.center(width).rstrip() for line in _lines(data))
+    return f"{rule}\n{body}\n{rule}\n"
+
+
+def footer_markdown():
+    """A thematic break and the four lines, with the site as a link."""
+    data = metadata()
+    return (
+        "---\n\n"
+        f"<sub>{data['attributionPrefix']} **{data['projectName']}** — "
+        f"{data['tagline']}<br>\n"
+        f"{data['authorPrefix']} "
+        f"[{data['author']}]({data['website']})</sub>\n"
+    )
+
+
+def footer_html(class_name="qa-pack-attribution"):
+    """A self-contained `<footer>`: inline styles, muted, centered, small.
+
+    The author's site opens in a new tab. `rel="noopener noreferrer"` is not
+    optional — a report may be opened from anywhere, and a new tab that can reach
+    back into `window.opener` is a real hazard.
+    """
+    data = metadata()
+    site = html.escape(data["website"], quote=True)
+    project = html.escape(data["projectName"])
+    tagline = html.escape(data["tagline"])
+    author = html.escape(data["author"])
+    attribution_prefix = html.escape(data["attributionPrefix"])
+    author_prefix = html.escape(data["authorPrefix"])
+    css_class = html.escape(class_name, quote=True)
+
+    return (
+        f'<footer class="{css_class}" style="margin-top:2.5rem;padding-top:1rem;'
+        'border-top:1px solid rgba(128,128,128,0.25);font-size:0.75rem;line-height:1.6;'
+        'color:#6b7280;text-align:center;font-family:system-ui,-apple-system,'
+        'Segoe UI,Roboto,sans-serif;">\n'
+        f'  <div>{attribution_prefix} <strong>{project}</strong></div>\n'
+        f'  <div>{tagline}</div>\n'
+        f'  <div>{author_prefix} '
+        f'<a href="{site}" target="_blank" rel="noopener noreferrer" '
+        'style="color:inherit;text-decoration:underline;">'
+        f'{author}</a></div>\n'
+        '</footer>\n'
+    )
+
+
+_RENDERERS = {
+    "html": footer_html,
+    "markdown": footer_markdown,
+    "md": footer_markdown,
+    "text": footer_text,
+    "txt": footer_text,
+    "pdf": footer_text,  # what a PDF writer embeds when it cannot render markup
+}
+
+FORMATS = ("html", "markdown", "text")
+
+
+def footer(fmt="text"):
+    """Render the footer in `fmt`. Raises BrandingError on an unknown format."""
+    renderer = _RENDERERS.get(fmt.lower())
+    if renderer is None:
+        raise BrandingError(
+            f"unknown branding format {fmt!r}; expected one of: {', '.join(FORMATS)}"
+        )
+    return renderer()
+
+
+def append_to(document, fmt="markdown"):
+    """Return `document` with the footer appended, idempotently.
+
+    Idempotence matters: a report assembled in stages, or regenerated over its own
+    output, must not accumulate footers.
+    """
+    rendered = footer(fmt)
+    if rendered.strip() and rendered.strip() in document:
+        return document
+    separator = "" if document.endswith("\n") else "\n"
+    return f"{document}{separator}\n{rendered}"

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

@@ -0,0 +1,129 @@
+"""Unified CLI for the analysis core.
+
+Every analyzer is reachable as a subcommand that writes JSON to stdout, so the
+toolkit is usable from a shell, from CI, and (once bundled) by a skill. Exit
+code 0 on success, 2 on a malformed artifact or bad usage.
+
+Usage:
+  python -m qa_analysis.cli junit <path>
+  python -m qa_analysis.cli har <path> [--slow-ms N]
+  python -m qa_analysis.cli discover [--root DIR] [--path P ...]
+  python -m qa_analysis.cli diff-guard <diff-file>
+  python -m qa_analysis.cli redact <file>
+  python -m qa_analysis.cli validate <instance.json> <schema.json>
+  python -m qa_analysis.cli classify "<error message>" [--http-status N]
+  python -m qa_analysis.cli context [--root DIR] [--path .qa/context.md]
+  python -m qa_analysis.cli branding [--format html|markdown|text]
+"""
+
+import argparse
+import json
+import pathlib
+import sys
+
+from . import junit, har, discovery, diff_guard, redaction, contracts, taxonomy
+from . import branding as branding_module
+from . import context as context_module
+from .context import MalformedContext
+from .junit import MalformedArtifact
+
+_SCHEMA_DIR_CANDIDATES = (
+    # Repository layout: shared/analysis/lib/qa_analysis -> shared/analysis/schemas
+    pathlib.Path(__file__).resolve().parents[2] / "schemas",
+    # Bundled layout: package data travels with the package.
+    pathlib.Path(__file__).resolve().parent / "schemas",
+)
+
+
+def _context_schema():
+    """The context contract, in whichever layout this package is running from."""
+    for base in _SCHEMA_DIR_CANDIDATES:
+        candidate = base / "context.schema.json"
+        if candidate.is_file():
+            return contracts.load_schema(candidate)
+    return None
+
+
+def _emit(obj):
+    json.dump(obj, sys.stdout, indent=2, sort_keys=True)
+    sys.stdout.write("\n")
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(prog="qa-analysis", description="Deterministic QA analysis toolkit")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p = sub.add_parser("junit"); p.add_argument("path")
+    p = sub.add_parser("har"); p.add_argument("path"); p.add_argument("--slow-ms", type=int, default=1000)
+    p = sub.add_parser("discover"); p.add_argument("--root", default="."); p.add_argument("--path", action="append", default=[])
+    p = sub.add_parser("diff-guard"); p.add_argument("path")
+    p = sub.add_parser("redact"); p.add_argument("path")
+    p = sub.add_parser("validate"); p.add_argument("instance"); p.add_argument("schema")
+    p = sub.add_parser("classify"); p.add_argument("message"); p.add_argument("--http-status", type=int, default=None)
+    p = sub.add_parser("context"); p.add_argument("--root", default="."); p.add_argument("--path", default=None)
+    p = sub.add_parser("branding")
+    p.add_argument("--format", default="text", choices=list(branding_module.FORMATS) + ["pdf", "md", "txt"])
+    p.add_argument("--metadata", action="store_true", help="emit the branding metadata as JSON instead")
+
+    args = parser.parse_args(argv)
+
+    try:
+        if args.command == "junit":
+            _emit(junit.parse_junit(args.path))
+        elif args.command == "har":
+            _emit(har.parse_har(args.path, slow_ms=args.slow_ms))
+        elif args.command == "discover":
+            result = discovery.discover(root=args.root, explicit=args.path or None)
+            _emit({k: [a.to_dict() if hasattr(a, "to_dict") else a for a in v] for k, v in result.items()})
+        elif args.command == "diff-guard":
+            with open(args.path, "r", encoding="utf-8") as handle:
+                issues = diff_guard.check_diff(handle.read())
+            _emit({"issues": issues, "safe": not any(i["severity"] == "high" for i in issues)})
+        elif args.command == "redact":
+            with open(args.path, "r", encoding="utf-8") as handle:
+                sys.stdout.write(redaction.redact_text(handle.read()))
+        elif args.command == "validate":
+            with open(args.instance, "r", encoding="utf-8") as handle:
+                instance = json.load(handle)
+            ok, errors = contracts.validate(instance, contracts.load_schema(args.schema))
+            _emit({"valid": ok, "errors": errors})
+            return 0 if ok else 1
+        elif args.command == "classify":
+            classification, confidence, reason = taxonomy.classify(args.message, http_status=args.http_status)
+            _emit({"classification": classification, "confidence": confidence, "reason": reason})
+        elif args.command == "context":
+            path = args.path or str(pathlib.Path(args.root) / ".qa" / "context.md")
+            schema = _context_schema()
+            parsed = context_module.parse_file(path, schema=schema)
+            _emit({
+                "path": path,
+                "context": parsed["context"],
+                "valid": parsed["valid"],
+                "errors": parsed["errors"],
+                "schemaChecked": schema is not None,
+            })
+            return 0 if parsed["valid"] else 1
+        elif args.command == "branding":
+            # Written to stdout verbatim, not as JSON: the caller pastes this into
+            # a rendered report, so it must be the exact bytes to embed.
+            if args.metadata:
+                _emit(branding_module.metadata())
+            else:
+                sys.stdout.write(branding_module.footer(args.format))
+    except branding_module.BrandingError as exc:
+        _emit({"error": "branding-error", "detail": str(exc)})
+        return 2
+    except MalformedContext as exc:
+        _emit({"error": "malformed-context", "detail": str(exc)})
+        return 2
+    except MalformedArtifact as exc:
+        _emit({"error": "malformed-artifact", "detail": str(exc)})
+        return 2
+    except (OSError, json.JSONDecodeError) as exc:
+        _emit({"error": "io-error", "detail": str(exc)})
+        return 2
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -0,0 +1,233 @@
+"""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)