@topy-ai/maggie 0.7.46 → 0.7.48

package/bundled-tools/clis/maggie_design_lint.py

@@ -0,0 +1,277 @@
+#!/usr/bin/env python3
+"""Static design checks that catch defects before a browser run.
+
+``pressable-check`` flags a pressable or button rendered inside another
+pressable in JSX/TSX. React Native Web renders ``Pressable`` and the
+``Touchable*`` family as ``<button>``-like elements, so a chip with a nested
+remove control becomes ``<button>`` inside ``<button>``: invalid DOM, and taps
+land on the wrong control.
+
+``layer-check`` flags unlayered CSS that competes with Tailwind v4 utilities.
+Tailwind v4 emits utilities inside ``@layer utilities``; any unlayered rule
+wins over every layer regardless of specificity, so an unlayered
+``h1 { font-family }`` beats ``font-*`` and ``.ph { display: inline-block }``
+beats ``hidden`` and ``group-open:inline``.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+SKIP_DIRS = {"node_modules", "dist", "build", ".git", ".expo", ".next", ".astro", ".output", "coverage", ".maggie", ".turbo", ".vercel", ".wrangler"}
+PRESSABLES = ("Pressable", "TouchableOpacity", "TouchableHighlight", "TouchableWithoutFeedback", "TouchableNativeFeedback", "button", "a")
+ALLOW_MARKER = "maggie-allow-nested-pressable"
+JSX_KEYWORDS = {"return", "yield", "await", "default", "case", "in", "of", "else", "do"}
+
+TAILWIND_V4_IMPORT = re.compile(r"""@import\s+(?:url\()?["']tailwindcss["']""")
+LAYERED_IMPORT = re.compile(r"""@import\s+(?:url\()?["']([^"']+)["']\)?\s+layer\(""")
+# At-rules whose bodies are Tailwind theme/utility definitions or descriptors, not competing rules.
+SKIPPED_AT_RULES = {"theme", "utility", "variant", "custom-variant", "keyframes", "font-face", "property", "plugin", "source", "page", "counter-style", "font-feature-values", "starting-style"}
+NESTING_AT_RULES = {"media", "supports", "container", "scope", "document"}
+COMPETING_PROPERTIES = re.compile(
+    r"^(display|visibility|font-family|font-size|font-weight|font-style|line-height|letter-spacing|text-transform|"
+    r"text-align|color|background(-color)?|margin(-[a-z]+)?|padding(-[a-z]+)?|width|height|min-width|max-width|"
+    r"min-height|max-height|gap|border(-[a-z]+)*|position|inset|top|right|bottom|left|z-index|opacity)$"
+)
+ICON_CLASS = re.compile(r"\.(ph|ph-[\w-]+|fa|fa[srb]|fa-[\w-]+|bi|bi-[\w-]+|material-icons[\w-]*|material-symbols[\w-]*|icon|icon-[\w-]+|lucide|lucide-[\w-]+|iconify)(?![\w-])")
+ICON_ATTRIBUTE = re.compile(r"""\[class[\^*|]?=\s*["']?(ph|fa|bi|icon)""")
+TYPE_SELECTOR = re.compile(r"^(\*|[a-zA-Z][a-zA-Z0-9-]*)")
+
+
+def iter_files(roots: list[Path], suffixes: tuple[str, ...]) -> list[Path]:
+    found: list[Path] = []
+    for root in roots:
+        if root.is_file():
+            if root.suffix in suffixes:
+                found.append(root)
+            continue
+        for path in sorted(root.rglob("*")):
+            if path.suffix in suffixes and path.is_file() and not any(part in SKIP_DIRS for part in path.relative_to(root).parts):
+                found.append(path)
+    return found
+
+
+def _display(path: Path, project: Path) -> str:
+    try:
+        return path.resolve().relative_to(project.resolve()).as_posix()
+    except ValueError:
+        return path.name
+
+
+# ---------------------------------------------------------------- pressables
+
+def _strip_jsx_comments(source: str) -> str:
+    """Blank comments while keeping offsets, so line numbers stay correct."""
+    def blank(match: re.Match[str]) -> str:
+        return re.sub(r"[^\n]", " ", match.group(0))
+    source = re.sub(r"/\*.*?\*/", blank, source, flags=re.S)
+    return re.sub(r"(?m)^[ \t]*//[^\n]*", blank, source)
+
+
+def _scan_tag(source: str, start: int) -> tuple[int, bool, str] | None:
+    """Return (end offset, self-closing, attribute text) for a tag at ``start``."""
+    depth = 0
+    quote = ""
+    index = start
+    while index < len(source):
+        char = source[index]
+        if quote:
+            if char == quote and source[index - 1] != "\\":
+                quote = ""
+        elif char in "\"'`":
+            quote = char
+        elif char == "{":
+            depth += 1
+        elif char == "}":
+            depth -= 1
+        elif char == ">" and depth == 0:
+            return index + 1, source[index - 1] == "/", source[start:index]
+        index += 1
+    return None
+
+
+def pressable_findings(path: Path, names: set[str], display: str) -> list[dict[str, object]]:
+    raw = path.read_text(encoding="utf-8", errors="replace")
+    source = _strip_jsx_comments(raw)
+    raw_lines = raw.splitlines()
+    findings: list[dict[str, object]] = []
+    stack: list[tuple[str, bool, int]] = []  # (tag, is_pressable_boundary, line)
+    for match in re.finditer(r"<(/?)([A-Za-z][\w.]*)", source):
+        before = source[:match.start()].rstrip()
+        closing = match.group(1) == "/"
+        name = match.group(2)
+        # A preceding identifier character means a TypeScript generic, not JSX.
+        if not closing and before and (before[-1].isalnum() or before[-1] in "_$."):
+            word = re.search(r"[\w$]+$", before)
+            if not word or word.group(0) not in JSX_KEYWORDS:
+                continue
+        line = source.count("\n", 0, match.start()) + 1
+        if closing:
+            for position in range(len(stack) - 1, -1, -1):
+                if stack[position][0] == name:
+                    del stack[position:]
+                    break
+            continue
+        scanned = _scan_tag(source, match.end())
+        if scanned is None:
+            continue
+        _, self_closing, attributes = scanned
+        is_pressable = name in names
+        # `asChild` delegates rendering to the child (expo-router Link), so it is not a second control.
+        boundary = is_pressable and not re.search(r"\basChild\b", attributes)
+        if is_pressable:
+            outer = next((entry for entry in reversed(stack) if entry[1]), None)
+            allowed = ALLOW_MARKER in (raw_lines[line - 1] if line - 1 < len(raw_lines) else "")
+            if outer and not allowed:
+                findings.append({
+                    "file": display, "line": line, "inner": name, "outer": outer[0], "outerLine": outer[2],
+                    "message": f"<{name}> is nested inside <{outer[0]}> (line {outer[2]}); render them as sibling pressables",
+                })
+        if not self_closing:
+            stack.append((name, boundary, line))
+    return findings
+
+
+def pressable_check(project: Path, paths: list[Path], extra: list[str]) -> dict[str, object]:
+    names = set(PRESSABLES) | set(extra)
+    files = iter_files(paths or [project], (".tsx", ".jsx"))
+    findings: list[dict[str, object]] = []
+    for path in files:
+        findings.extend(pressable_findings(path, names, _display(path, project)))
+    return {"schemaVersion": "maggie-design-pressable-check.v1", "passed": not findings, "checkedFiles": len(files), "pressables": sorted(names), "findings": findings}
+
+
+# ---------------------------------------------------------------- CSS layers
+
+def _strip_css_comments(source: str) -> str:
+    return re.sub(r"/\*.*?\*/", lambda match: re.sub(r"[^\n]", " ", match.group(0)), source, flags=re.S)
+
+
+def _block_end(source: str, open_index: int) -> int:
+    depth = 0
+    quote = ""
+    for index in range(open_index, len(source)):
+        char = source[index]
+        if quote:
+            if char == quote and source[index - 1] != "\\":
+                quote = ""
+        elif char in "\"'":
+            quote = char
+        elif char == "{":
+            depth += 1
+        elif char == "}":
+            depth -= 1
+            if depth == 0:
+                return index
+    return len(source) - 1
+
+
+def _selector_kind(selector: str) -> str | None:
+    if ICON_CLASS.search(selector) or ICON_ATTRIBUTE.search(selector):
+        return "icon"
+    kind = None
+    for part in selector.split(","):
+        compounds = [item for item in re.split(r"\s*[>+~]\s*|\s+", part.strip()) if item]
+        if not compounds:
+            continue
+        last = re.sub(r"::?[\w-]+(\([^)]*\))?", "", compounds[-1])
+        match = TYPE_SELECTOR.match(last)
+        if not match:
+            continue
+        if match.group(1).lower() in {"html", "body"}:
+            kind = kind or "root"
+        else:
+            return "element"
+    return kind
+
+
+def _rule_findings(source: str, start: int, end: int, layered: bool, display: str, findings: list[dict[str, object]]) -> None:
+    index = start
+    while index < end:
+        brace = source.find("{", index, end)
+        semicolon = source.find(";", index, end)
+        if brace == -1:
+            return
+        if semicolon != -1 and semicolon < brace:
+            index = semicolon + 1  # statement at-rule such as @import or @layer a, b;
+            continue
+        prelude = source[index:brace].strip()
+        close = _block_end(source, brace)
+        if prelude.startswith("@"):
+            at_name = re.match(r"@([\w-]+)", prelude)
+            name = at_name.group(1).lower() if at_name else ""
+            if name == "layer":
+                _rule_findings(source, brace + 1, close, True, display, findings)
+            elif name in NESTING_AT_RULES:
+                _rule_findings(source, brace + 1, close, layered, display, findings)
+        elif not layered and prelude:
+            kind = _selector_kind(prelude)
+            body = source[brace + 1:close]
+            properties = sorted({item.split(":", 1)[0].strip().lower() for item in body.split(";") if ":" in item and "{" not in item.split(":", 1)[0]})
+            competing = [item for item in properties if COMPETING_PROPERTIES.match(item)]
+            line = source.count("\n", 0, index + (len(source[index:brace]) - len(source[index:brace].lstrip()))) + 1
+            if kind == "root" and competing:
+                findings.append({
+                    "file": display, "line": line, "selector": " ".join(prelude.split()), "kind": kind, "properties": competing, "severity": "warning",
+                    "message": "unlayered html/body rule overrides utilities placed on that element; prefer @layer base",
+                })
+            elif kind and competing:
+                findings.append({
+                    "file": display, "line": line, "selector": " ".join(prelude.split()), "kind": kind, "properties": competing, "severity": "error",
+                    "message": f"unlayered {kind} rule sets {', '.join(competing)} and overrides Tailwind v4 utilities; move it into @layer {'components' if kind == 'icon' else 'base'}",
+                })
+            elif not kind and "display" in competing:
+                findings.append({
+                    "file": display, "line": line, "selector": " ".join(prelude.split()), "kind": "class", "properties": ["display"], "severity": "warning",
+                    "message": "unlayered rule sets display, so utilities such as hidden cannot toggle this element; prefer @layer components",
+                })
+        index = close + 1
+
+
+def layer_check(project: Path, paths: list[Path], force_v4: bool) -> dict[str, object]:
+    files = iter_files(paths or [project], (".css", ".pcss", ".postcss"))
+    sources = {path.resolve(): _strip_css_comments(path.read_text(encoding="utf-8", errors="replace")) for path in files}
+    tailwind_v4 = force_v4 or any(TAILWIND_V4_IMPORT.search(source) for source in sources.values())
+    if not tailwind_v4:
+        return {"schemaVersion": "maggie-design-layer-check.v1", "passed": True, "status": "skipped", "reason": "no Tailwind v4 entry (@import \"tailwindcss\") found", "checkedFiles": len(files), "findings": []}
+    layered_files: set[Path] = set()
+    for path, source in sources.items():
+        for target in LAYERED_IMPORT.findall(source):
+            layered_files.add((path.parent / target).resolve())
+    findings: list[dict[str, object]] = []
+    for path, source in sources.items():
+        _rule_findings(source, 0, len(source), path in layered_files, _display(path, project), findings)
+    errors = [item for item in findings if item["severity"] == "error"]
+    return {"schemaVersion": "maggie-design-layer-check.v1", "passed": not errors, "status": "checked", "checkedFiles": len(files), "errors": len(errors), "warnings": len(findings) - len(errors), "findings": findings}
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="maggie design", description="Static design checks that run before browser QA.")
+    sub = parser.add_subparsers(dest="command", required=True)
+    pressable = sub.add_parser("pressable-check", help="flag pressables or buttons nested inside another pressable (.tsx/.jsx)")
+    pressable.add_argument("--project", type=Path, default=Path.cwd())
+    pressable.add_argument("--path", type=Path, action="append", default=[], help="file or directory to scan; defaults to the project")
+    pressable.add_argument("--pressable", action="append", default=[], help="extra component name that renders a pressable, for example Chip")
+    layers = sub.add_parser("layer-check", help="flag unlayered CSS that overrides Tailwind v4 utilities")
+    layers.add_argument("--project", type=Path, default=Path.cwd())
+    layers.add_argument("--css", type=Path, action="append", default=[], help="CSS file or directory to scan; defaults to the project")
+    layers.add_argument("--tailwind-v4", action="store_true", help="check even when no @import \"tailwindcss\" entry is found")
+    args = parser.parse_args(argv)
+    try:
+        if args.command == "pressable-check":
+            report = pressable_check(args.project, args.path, args.pressable)
+        else:
+            report = layer_check(args.project, args.css, args.tailwind_v4)
+    except OSError as error:
+        print(f"BLOCKED: maggie-design {args.command}: {error}", file=sys.stderr)
+        return 1
+    print(json.dumps(report, indent=2, ensure_ascii=False))
+    return 0 if report["passed"] else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/bundled-tools/clis/maggie_feedback.py

@@ -10,6 +10,7 @@ import os
 import platform
 import re
 import secrets
+import subprocess
 import sys
 from datetime import datetime, timezone
 from pathlib import Path
@@ -41,6 +42,14 @@ EVIDENCE_KINDS = {"test", "report", "screenshot", "command", "deployment", "issu
 RELATION_KINDS = {"related", "same-run", "same-fingerprint", "duplicates", "validates", "remediates", "caused-by"}
 ACKNOWLEDGEMENT_KEYS = ("status", "feedbackId", "requestId")
 REPO_ROOT = Path(__file__).resolve().parents[2]
+FEEDBACK_TYPES = ("bug", "feature", "quality", "improvement", "general")
+# The hosted endpoint accepts these types. Local-only types are submitted as a
+# hosted type with the original kept in `subtype`, so no endpoint change is needed.
+HOSTED_TYPES = {"bug", "feature", "quality", "general"}
+HOSTED_TYPE_FALLBACK = {"improvement": "feature"}
+REVIEW_MARKER = "REVIEW:"
+FIX_SUBJECT_RE = re.compile(r"^(?:fix|bugfix|hotfix)(?:\([^)]*\))?!?:\s*|^(?:fix|fixes|fixed)\b\s*", re.IGNORECASE)
+FEATURE_SUBJECT_RE = re.compile(r"^(?:feat|perf|refactor)(?:\([^)]*\))?!?:\s*", re.IGNORECASE)
 
 
 def now() -> str:
@@ -230,6 +239,8 @@ def collect(args: argparse.Namespace) -> int:
         # Persist one canonical representation so batch review and the hosted
         # API do not have to guess which indexing convention was used.
         batch_index -= batch_base
+    if args.type not in FEEDBACK_TYPES:
+        raise ValueError(f"type must be one of: {', '.join(FEEDBACK_TYPES)}")
     priority = safe_text(getattr(args, "priority", "") or "normal").lower()
     if priority not in {"low", "normal", "high", "critical"}:
         raise ValueError("priority must be low, normal, high, or critical")
@@ -321,6 +332,16 @@ def preview(args: argparse.Namespace) -> int:
     return 0
 
 
+def hosted_payload(data: dict) -> dict:
+    """Map local-only feedback types onto the hosted contract without losing them."""
+    payload = dict(data)
+    local_type = payload.get("type")
+    if local_type not in HOSTED_TYPES:
+        payload["type"] = HOSTED_TYPE_FALLBACK.get(local_type, "general")
+        payload["subtype"] = local_type
+    return payload
+
+
 def submit(args: argparse.Namespace) -> int:
     if not args.confirm:
         raise ValueError("submit requires --confirm; feedback is never sent implicitly")
@@ -330,7 +351,7 @@ def submit(args: argparse.Namespace) -> int:
     parsed = urlparse(endpoint)
     if parsed.scheme != "https" or not parsed.netloc:
         raise ValueError("endpoint must be an absolute HTTPS URL")
-    payload = dict(data)
+    payload = hosted_payload(data)
     payload["projectContext"] = data.get("projectContext") if data.get("privacy", {}).get("projectContextAllowed") else None
     request = Request(endpoint, data=json.dumps(payload, ensure_ascii=False).encode(), headers={"Content-Type": "application/json", "Accept": "application/json", "User-Agent": "MaggieFeedback/0.1"}, method="POST")
     try:
@@ -352,7 +373,7 @@ def list_feedback(args: argparse.Namespace) -> int:
     for path in sorted(directory.glob("*.json")):
         try:
             data = read_feedback(path)
-            records.append({"feedbackId": data.get("feedbackId"), "skill": data.get("skill"), "status": data.get("submission", {}).get("status", "draft"), "path": str(path)})
+            records.append({"feedbackId": data.get("feedbackId"), "skill": data.get("skill"), "type": data.get("type"), "status": data.get("submission", {}).get("status", "draft"), "path": str(path)})
         except (OSError, ValueError):
             continue
     print(json.dumps(records, indent=2, ensure_ascii=False))
@@ -383,6 +404,9 @@ def collect_batch(args: argparse.Namespace) -> int:
     for index, item in enumerate(items):
         if not isinstance(item, dict):
             raise ValueError(f"items[{index}] must be an object")
+        unedited = [field for field in ("summary", "expected", "actual", "resolution", "validation") if REVIEW_MARKER in str(item.get(field) or "")]
+        if unedited:
+            raise ValueError(f"items[{index}] still has {REVIEW_MARKER} placeholders in: {', '.join(unedited)}; edit or remove the item before creating drafts")
         values = {
             "project": args.project,
             "run_report": None,
@@ -422,6 +446,75 @@ def collect_batch(args: argparse.Namespace) -> int:
     return 0
 
 
+def session_summary(args: argparse.Namespace) -> int:
+    """Draft a reviewable batch file from commit subjects; nothing is collected or submitted."""
+    repo = Path(args.repo).expanduser().resolve()
+    since = str(args.since).strip()
+    if not since or since.startswith("-") or not re.fullmatch(r"[A-Za-z0-9._/@{}~^:-]{1,200}", since):
+        raise ValueError("--since must be a git revision such as a tag, branch, or commit")
+    batch_id = safe_text(args.batch_id) or f"session-{datetime.now(timezone.utc).strftime('%Y%m%d-%H%M%S')}"
+    if not SAFE_BATCH_ID_RE.fullmatch(batch_id):
+        raise ValueError("batch ID is invalid")
+    completed = subprocess.run(
+        ["git", "-C", str(repo), "log", "--no-merges", "--format=%h%x1f%s", f"{since}..HEAD"],
+        capture_output=True, text=True, check=False,
+    )
+    if completed.returncode:
+        raise ValueError("git log failed; check --repo and --since")
+    items = []
+    skipped = 0
+    for line in completed.stdout.splitlines():
+        sha, _, subject = line.partition("\x1f")
+        subject = safe_text(subject)[:200]
+        if not sha or not subject:
+            continue
+        if FIX_SUBJECT_RE.match(subject):
+            kind, text = "bug", FIX_SUBJECT_RE.sub("", subject, count=1)
+        elif FEATURE_SUBJECT_RE.match(subject):
+            kind, text = "improvement", FEATURE_SUBJECT_RE.sub("", subject, count=1)
+        else:
+            skipped += 1
+            continue
+        text = text[:1].upper() + text[1:] if text else subject
+        items.append({
+            "type": kind,
+            "summary": text,
+            "expected": f"{REVIEW_MARKER} what the skill or CLI should have done",
+            "actual": f"{REVIEW_MARKER} what happened before commit {sha}",
+            "fixed": True,
+            "resolution": text,
+            "validation": f"{REVIEW_MARKER} the test or check that verified commit {sha}",
+            "evidence": [f"commit:{sha}"],
+        })
+        if len(items) >= 49:
+            break
+    items.append({
+        "type": "feature",
+        "summary": f"{REVIEW_MARKER} describe an open ask from this session, or delete this item",
+        "expected": "",
+        "actual": "",
+    })
+    manifest = {
+        "batchId": batch_id,
+        "skill": safe_text(args.skill),
+        "runId": safe_text(args.run_id),
+        "phase": safe_text(args.phase) or "session-summary",
+        "reviewRequired": True,
+        "note": "Draft only. Remove items unrelated to Maggie skills or CLIs, replace every REVIEW: and delete the open-ask placeholder if unused. `maggie feedback batch` rejects unedited REVIEW: fields.",
+        "items": items,
+    }
+    project = Path(args.project).resolve()
+    output = Path(args.output) if args.output else project / ".maggie" / "feedback" / "batches" / f"{batch_id}-draft.json"
+    if not output.is_absolute():
+        output = project / output
+    if output.exists():
+        raise ValueError("output already exists; choose another --output or --batch-id")
+    output.parent.mkdir(parents=True, exist_ok=True)
+    output.write_text(json.dumps(manifest, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    print(json.dumps({"status": "draft-written", "batchId": batch_id, "items": len(items), "skippedCommits": skipped, "output": str(output), "submitted": False}, ensure_ascii=False))
+    return 0
+
+
 def batch_review(args: argparse.Namespace) -> int:
     """Aggregate one bounded batch without exposing raw payloads or paths."""
     project = Path(args.project).resolve()
@@ -534,7 +627,7 @@ def main() -> int:
     collect_parser.add_argument("--skill", default="")
     collect_parser.add_argument("--run-id", default="")
     collect_parser.add_argument("--run-report")
-    collect_parser.add_argument("--type", choices=("bug", "feature", "quality", "general"), default="bug")
+    collect_parser.add_argument("--type", choices=FEEDBACK_TYPES, default="bug", help="improvement: a proposal to improve a skill or CLI (submitted as feature with subtype)")
     collect_parser.add_argument("--phase", default="")
     collect_parser.add_argument("--summary", required=True)
     collect_parser.add_argument("--expected", default="")
@@ -563,6 +656,15 @@ def main() -> int:
     batch_parser = sub.add_parser("batch")
     batch_parser.add_argument("--project", default=argparse.SUPPRESS)
     batch_parser.add_argument("--batch-file", required=True)
+    summary_parser = sub.add_parser("session-summary", help="draft batch items from git commit subjects for review")
+    summary_parser.add_argument("--project", default=argparse.SUPPRESS)
+    summary_parser.add_argument("--since", required=True, help="git revision; commits after it are summarized")
+    summary_parser.add_argument("--repo", default=".", help="git repository to read (default: current directory)")
+    summary_parser.add_argument("--batch-id", default="")
+    summary_parser.add_argument("--skill", default="")
+    summary_parser.add_argument("--run-id", default="")
+    summary_parser.add_argument("--phase", default="")
+    summary_parser.add_argument("--output")
     review_parser = sub.add_parser("batch-review")
     review_parser.add_argument("--project", default=argparse.SUPPRESS)
     review_parser.add_argument("--batch-id", required=True)
@@ -575,11 +677,13 @@ def main() -> int:
     submit_parser.add_argument("--endpoint", default=DEFAULT_ENDPOINT)
     submit_parser.add_argument("--confirm", action="store_true")
     list_parser = sub.add_parser("list")
+    list_parser.add_argument("--project", default=argparse.SUPPRESS)
     args = parser.parse_args()
     try:
         if args.command == "collect": return collect(args)
         if args.command == "batch": return collect_batch(args)
         if args.command == "batch-review": return batch_review(args)
+        if args.command == "session-summary": return session_summary(args)
         if args.command == "preview": return preview(args)
         if args.command == "submit": return submit(args)
         return list_feedback(args)