prizmkit 1.0.0 → 1.0.1

package/bundled/skills/app-planner/scripts/validate-and-generate.py

@@ -0,0 +1,758 @@
+#!/usr/bin/env python3
+"""
+validate-and-generate.py - Validate and generate feature-list.json files
+for the dev-pipeline system.
+
+Commands:
+  validate    Validate an existing feature-list.json
+  template    Generate a blank template feature-list.json
+  summary     Print a summary table of features from a feature-list.json
+
+Usage:
+  python3 validate-and-generate.py validate --input feature-list.json [--output validated.json]
+  python3 validate-and-generate.py template --output feature-list.json
+  python3 validate-and-generate.py summary --input feature-list.json [--format markdown|json]
+
+Python 3.6+ required. No external dependencies.
+"""
+
+import argparse
+import collections
+import json
+import os
+import re
+import sys
+from datetime import datetime, timezone
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+SCHEMA_VERSION = "dev-pipeline-feature-list-v1"
+
+VALID_STATUSES = {"pending", "in_progress", "completed", "failed", "skipped", "split"}
+VALID_COMPLEXITIES = {"low", "medium", "high"}
+VALID_GRANULARITIES = {"feature", "sub_feature", "auto"}
+
+FEATURE_ID_RE = re.compile(r"^F-\d{3}(-[A-Z])?$")
+SUB_FEATURE_ID_RE = re.compile(r"^F-\d{3}-[A-Z]$")
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _err(msg):
+    """Print an error message to stderr."""
+    print("ERROR: {}".format(msg), file=sys.stderr)
+
+
+def _warn(msg):
+    """Print a warning message to stderr."""
+    print("WARNING: {}".format(msg), file=sys.stderr)
+
+
+def _info(msg):
+    """Print an informational message to stderr."""
+    print("INFO: {}".format(msg), file=sys.stderr)
+
+
+def _load_json(path):
+    """Load and return parsed JSON from *path*.
+
+    Returns (data, error_message).  On success error_message is None.
+    """
+    if not os.path.isfile(path):
+        return None, "File not found: {}".format(path)
+    try:
+        with open(path, "r", encoding="utf-8") as fh:
+            data = json.load(fh)
+        return data, None
+    except json.JSONDecodeError as exc:
+        return None, "JSON parse error in {}: {}".format(path, exc)
+    except Exception as exc:
+        return None, "Failed to read {}: {}".format(path, exc)
+
+
+def _write_json(path, data):
+    """Write *data* as pretty-printed JSON to *path*."""
+    parent = os.path.dirname(path)
+    if parent and not os.path.isdir(parent):
+        os.makedirs(parent, exist_ok=True)
+    with open(path, "w", encoding="utf-8") as fh:
+        json.dump(data, fh, indent=2, ensure_ascii=False)
+        fh.write("\n")
+
+
+# ---------------------------------------------------------------------------
+# Cycle detection (Kahn's algorithm)
+# ---------------------------------------------------------------------------
+
+
+def _detect_cycles(features):
+    """Return (has_cycles: bool, max_depth: int) using Kahn's topological sort.
+
+    *features* is the list of feature dicts.  We build a graph from the
+    ``dependencies`` field and run Kahn's algorithm.
+
+    Returns a tuple ``(has_cycles, max_depth)`` where *max_depth* is the
+    longest path in the DAG (0 if there are cycles or a single node).
+    """
+    id_set = {f["id"] for f in features}
+    # Build adjacency list and in-degree map.
+    adj = {fid: [] for fid in id_set}       # dependency -> [dependent]
+    in_degree = {fid: 0 for fid in id_set}
+
+    for feat in features:
+        fid = feat["id"]
+        for dep in feat.get("dependencies", []):
+            if dep in id_set:
+                adj[dep].append(fid)
+                in_degree[fid] += 1
+
+    # Kahn's algorithm
+    queue = collections.deque()
+    for fid, deg in in_degree.items():
+        if deg == 0:
+            queue.append(fid)
+
+    sorted_order = []
+    # Track depth for each node to compute max dependency depth.
+    depth = {fid: 0 for fid in id_set}
+
+    while queue:
+        node = queue.popleft()
+        sorted_order.append(node)
+        for neighbour in adj[node]:
+            in_degree[neighbour] -= 1
+            new_depth = depth[node] + 1
+            if new_depth > depth[neighbour]:
+                depth[neighbour] = new_depth
+            if in_degree[neighbour] == 0:
+                queue.append(neighbour)
+
+    has_cycles = len(sorted_order) != len(id_set)
+    max_depth = max(depth.values()) if depth else 0
+    return has_cycles, max_depth
+
+
+# ---------------------------------------------------------------------------
+# Validation
+# ---------------------------------------------------------------------------
+
+
+def validate_feature_list(data):
+    """Validate a parsed feature-list data structure.
+
+    Returns a dict with keys ``valid``, ``errors``, ``warnings``, ``stats``.
+    """
+    errors = []
+    warnings = []
+
+    # ------------------------------------------------------------------
+    # 1. Top-level schema validation
+    # ------------------------------------------------------------------
+    schema = data.get("$schema")
+    if schema != SCHEMA_VERSION:
+        errors.append(
+            "$schema must be '{}', got '{}'".format(SCHEMA_VERSION, schema)
+        )
+
+    app_name = data.get("app_name")
+    if not isinstance(app_name, str) or not app_name.strip():
+        errors.append("app_name must be a non-empty string")
+
+    features = data.get("features")
+    if not isinstance(features, list) or len(features) == 0:
+        errors.append("features must be a non-empty array")
+        # Early-out: nothing else to validate if features are missing.
+        return {
+            "valid": False,
+            "errors": errors,
+            "warnings": warnings,
+            "stats": {
+                "total_features": 0,
+                "total_sub_features": 0,
+                "complexity_distribution": {},
+                "max_dependency_depth": 0,
+                "has_cycles": False,
+            },
+        }
+
+    # ------------------------------------------------------------------
+    # 2. Per-feature validation
+    # ------------------------------------------------------------------
+    required_keys = {
+        "id", "title", "description", "priority",
+        "dependencies", "acceptance_criteria", "status",
+    }
+
+    seen_ids = set()
+    priorities = []
+    complexity_dist = {"low": 0, "medium": 0, "high": 0}
+    total_sub_features = 0
+
+    for idx, feat in enumerate(features):
+        label = "features[{}]".format(idx)
+
+        # -- Required keys --
+        if not isinstance(feat, dict):
+            errors.append("{} is not an object".format(label))
+            continue
+
+        missing = required_keys - set(feat.keys())
+        if missing:
+            errors.append("{} missing required keys: {}".format(
+                label, ", ".join(sorted(missing))
+            ))
+
+        # -- ID format & uniqueness --
+        fid = feat.get("id", "")
+        if not FEATURE_ID_RE.match(str(fid)):
+            errors.append(
+                "{}: id '{}' does not match pattern F-NNN or F-NNN-X".format(label, fid)
+            )
+        if fid in seen_ids:
+            errors.append("{}: duplicate id '{}'".format(label, fid))
+        seen_ids.add(fid)
+
+        # -- Title / description --
+        for key in ("title", "description"):
+            val = feat.get(key)
+            if not isinstance(val, str) or not val.strip():
+                errors.append("{}: {} must be a non-empty string".format(label, key))
+
+        # -- Priority --
+        priority = feat.get("priority")
+        if isinstance(priority, int) and priority > 0:
+            priorities.append(priority)
+        else:
+            errors.append("{}: priority must be a positive integer, got {}".format(
+                label, repr(priority)
+            ))
+
+        # -- Dependencies (list of strings) --
+        deps = feat.get("dependencies")
+        if not isinstance(deps, list):
+            errors.append("{}: dependencies must be an array".format(label))
+
+        # -- Acceptance criteria --
+        criteria = feat.get("acceptance_criteria")
+        if isinstance(criteria, list):
+            if len(criteria) < 1:
+                errors.append("{}: must have at least 1 acceptance criterion".format(label))
+            elif len(criteria) < 3:
+                warnings.append(
+                    "{}: only {} acceptance criteria (recommend at least 3)".format(
+                        label, len(criteria)
+                    )
+                )
+        else:
+            errors.append("{}: acceptance_criteria must be an array".format(label))
+
+        # -- Status --
+        status = feat.get("status")
+        if status not in VALID_STATUSES:
+            errors.append(
+                "{}: status '{}' invalid, must be one of: {}".format(
+                    label, status, ", ".join(sorted(VALID_STATUSES))
+                )
+            )
+        if status and status != "pending":
+            warnings.append(
+                "{}: status is '{}' (expected 'pending' for new plans)".format(label, status)
+            )
+
+        # -- Complexity (optional but validated if present) --
+        complexity = feat.get("estimated_complexity")
+        if complexity is not None:
+            if complexity not in VALID_COMPLEXITIES:
+                errors.append(
+                    "{}: estimated_complexity '{}' invalid, must be one of: {}".format(
+                        label, complexity, ", ".join(sorted(VALID_COMPLEXITIES))
+                    )
+                )
+            else:
+                complexity_dist[complexity] += 1
+
+        # -- Granularity (optional but validated if present) --
+        granularity = feat.get("session_granularity")
+        if granularity is not None:
+            if granularity not in VALID_GRANULARITIES:
+                errors.append(
+                    "{}: session_granularity '{}' invalid, must be one of: {}".format(
+                        label, granularity, ", ".join(sorted(VALID_GRANULARITIES))
+                    )
+                )
+            if granularity == "auto":
+                subs = feat.get("sub_features")
+                if not isinstance(subs, list) or len(subs) == 0:
+                    warnings.append(
+                        "{}: granularity is 'auto' but no sub_features defined".format(label)
+                    )
+
+        # -- Sub-features --
+        subs = feat.get("sub_features")
+        if isinstance(subs, list):
+            for sidx, sub in enumerate(subs):
+                sub_label = "{}->sub_features[{}]".format(label, sidx)
+                if not isinstance(sub, dict):
+                    errors.append("{} is not an object".format(sub_label))
+                    continue
+
+                sub_missing = {"id", "title", "description"} - set(sub.keys())
+                if sub_missing:
+                    errors.append("{} missing required keys: {}".format(
+                        sub_label, ", ".join(sorted(sub_missing))
+                    ))
+
+                sub_id = sub.get("id", "")
+                if not SUB_FEATURE_ID_RE.match(str(sub_id)):
+                    errors.append(
+                        "{}: id '{}' must be F-NNN-X format".format(sub_label, sub_id)
+                    )
+
+                # Sub-feature ID should share parent prefix
+                parent_prefix = str(fid).rstrip("ABCDEFGHIJKLMNOPQRSTUVWXYZ").rstrip("-")
+                sub_prefix = str(sub_id)[:5]  # e.g. "F-001"
+                if parent_prefix and sub_prefix != parent_prefix:
+                    warnings.append(
+                        "{}: sub-feature '{}' does not share parent prefix '{}'".format(
+                            sub_label, sub_id, parent_prefix
+                        )
+                    )
+
+                if sub_id in seen_ids:
+                    errors.append("{}: duplicate id '{}'".format(sub_label, sub_id))
+                seen_ids.add(sub_id)
+                total_sub_features += 1
+
+    # -- Priority uniqueness --
+    if len(priorities) != len(set(priorities)):
+        dup_prios = [
+            p for p, c in collections.Counter(priorities).items() if c > 1
+        ]
+        warnings.append(
+            "Duplicate priorities found: {}".format(
+                ", ".join(str(p) for p in sorted(dup_prios))
+            )
+        )
+
+    # ------------------------------------------------------------------
+    # 3. Dependency validation
+    # ------------------------------------------------------------------
+    all_ids = {f.get("id") for f in features}
+    for idx, feat in enumerate(features):
+        label = "features[{}]".format(idx)
+        deps = feat.get("dependencies", [])
+        if isinstance(deps, list):
+            for dep in deps:
+                if dep not in all_ids:
+                    errors.append(
+                        "{}: dependency '{}' does not exist in feature list".format(label, dep)
+                    )
+
+    # -- Cycle detection --
+    has_cycles, max_depth = _detect_cycles(features)
+    if has_cycles:
+        errors.append("Dependency graph contains cycles (not a valid DAG)")
+
+    # ------------------------------------------------------------------
+    # 4. Build result
+    # ------------------------------------------------------------------
+    is_valid = len(errors) == 0
+
+    return {
+        "valid": is_valid,
+        "errors": errors,
+        "warnings": warnings,
+        "stats": {
+            "total_features": len(features),
+            "total_sub_features": total_sub_features,
+            "complexity_distribution": complexity_dist,
+            "max_dependency_depth": max_depth,
+            "has_cycles": has_cycles,
+        },
+    }
+
+
+# ---------------------------------------------------------------------------
+# Template generation
+# ---------------------------------------------------------------------------
+
+
+def generate_template():
+    """Return a template feature-list dict with placeholder values."""
+    now = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+    return {
+        "$schema": SCHEMA_VERSION,
+        "app_name": "YOUR_APP_NAME",
+        "app_description": "YOUR_APP_DESCRIPTION",
+        "created_at": now,
+        "created_by": "app-planner",
+        "source_spec": "",
+        "features": [
+            {
+                "id": "F-001",
+                "title": "Project Infrastructure Setup",
+                "description": (
+                    "Initialize project structure, configure build tools, "
+                    "set up development environment."
+                ),
+                "priority": 1,
+                "estimated_complexity": "medium",
+                "dependencies": [],
+                "acceptance_criteria": [
+                    "Project builds successfully",
+                    "Development server starts",
+                    "Linting and formatting configured",
+                ],
+                "status": "pending",
+                "session_granularity": "feature",
+                "sub_features": [],
+            }
+        ],
+        "global_context": {
+            "tech_stack": "",
+            "design_system": "",
+            "testing_strategy": "",
+        },
+    }
+
+
+# ---------------------------------------------------------------------------
+# Summary
+# ---------------------------------------------------------------------------
+
+
+def _build_dependency_graph_text(features):
+    """Build a human-readable text representation of the dependency graph.
+
+    Produces an arrow-chain format that shows all dependency paths,
+    including convergent edges (where multiple paths lead to the same node).
+
+    Returns a list of lines.
+    """
+    all_ids = [f["id"] for f in features]
+
+    # Build adjacency: dependency -> list of dependents (forward edges)
+    dependents = {fid: [] for fid in all_ids}
+    has_parent = set()
+    for feat in features:
+        for dep in feat.get("dependencies", []):
+            if dep in dependents:
+                dependents[dep].append(feat["id"])
+                has_parent.add(feat["id"])
+
+    # Sort children for deterministic output
+    for fid in dependents:
+        dependents[fid] = sorted(set(dependents[fid]))
+
+    # Roots: features with no incoming dependencies
+    roots = [fid for fid in all_ids if fid not in has_parent]
+    if not roots:
+        return ["(cycle detected - no root nodes)"]
+    if not any(dependents[r] for r in all_ids):
+        # No dependencies at all
+        return ["(no dependencies)"]
+
+    result_lines = []
+
+    def _render(node, prefix, is_continuation):
+        """Render a node and its dependents recursively.
+
+        *prefix*: whitespace to print before " -> node" on branch lines.
+        *is_continuation*: True if this node is appended on the same line
+                           as its parent (first child).
+        """
+        children = dependents.get(node, [])
+        if not children:
+            return
+
+        for i, child in enumerate(children):
+            if i == 0:
+                # First child: continue on the same line
+                result_lines[-1] += " -> {}".format(child)
+                _render(child, prefix + " " * (len(node) + 4), True)
+            else:
+                # Subsequent children: new line, indented under the arrow
+                line = "{}-> {}".format(prefix, child)
+                result_lines.append(line)
+                child_prefix = prefix + " " * (len(child) + 4)
+                _render(child, child_prefix, True)
+
+    for root in sorted(roots):
+        result_lines.append(root)
+        _render(root, " " * len(root), False)
+
+    return result_lines
+
+
+def generate_summary_markdown(data):
+    """Generate a markdown summary of the feature list."""
+    app_name = data.get("app_name", "Unknown")
+    features = data.get("features", [])
+
+    lines = []
+    lines.append("# Feature Summary: {}".format(app_name))
+    lines.append("")
+
+    # Table header
+    lines.append("| ID | Title | Complexity | Priority | Dependencies | Criteria | Granularity |")
+    lines.append("|----|-------|------------|----------|--------------|----------|-------------|")
+
+    for feat in features:
+        fid = feat.get("id", "?")
+        title = feat.get("title", "?")
+        complexity = feat.get("estimated_complexity", "-")
+        priority = feat.get("priority", "?")
+        deps = feat.get("dependencies", [])
+        deps_str = ", ".join(deps) if deps else "-"
+        criteria_count = len(feat.get("acceptance_criteria", []))
+        granularity = feat.get("session_granularity", "-")
+
+        lines.append("| {} | {} | {} | {} | {} | {} | {} |".format(
+            fid, title, complexity, priority, deps_str, criteria_count, granularity
+        ))
+
+    lines.append("")
+
+    # Dependency graph
+    lines.append("## Dependency Graph")
+    graph_lines = _build_dependency_graph_text(features)
+    for gl in graph_lines:
+        lines.append(gl)
+    lines.append("")
+
+    # Statistics
+    complexity_dist = {"low": 0, "medium": 0, "high": 0}
+    total_sub = 0
+    for feat in features:
+        c = feat.get("estimated_complexity")
+        if c in complexity_dist:
+            complexity_dist[c] += 1
+        subs = feat.get("sub_features")
+        if isinstance(subs, list):
+            total_sub += len(subs)
+
+    _, max_depth = _detect_cycles(features)
+
+    lines.append("## Statistics")
+    lines.append("- Total features: {}".format(len(features)))
+    if total_sub > 0:
+        lines.append("- Total sub-features: {}".format(total_sub))
+    lines.append("- Complexity: {} low, {} medium, {} high".format(
+        complexity_dist["low"], complexity_dist["medium"], complexity_dist["high"]
+    ))
+    lines.append("- Max dependency depth: {}".format(max_depth))
+
+    return "\n".join(lines)
+
+
+def generate_summary_json(data):
+    """Generate a JSON summary of the feature list."""
+    features = data.get("features", [])
+
+    complexity_dist = {"low": 0, "medium": 0, "high": 0}
+    total_sub = 0
+    for feat in features:
+        c = feat.get("estimated_complexity")
+        if c in complexity_dist:
+            complexity_dist[c] += 1
+        subs = feat.get("sub_features")
+        if isinstance(subs, list):
+            total_sub += len(subs)
+
+    has_cycles, max_depth = _detect_cycles(features)
+
+    feature_summaries = []
+    for feat in features:
+        feature_summaries.append({
+            "id": feat.get("id"),
+            "title": feat.get("title"),
+            "priority": feat.get("priority"),
+            "estimated_complexity": feat.get("estimated_complexity"),
+            "dependencies": feat.get("dependencies", []),
+            "acceptance_criteria_count": len(feat.get("acceptance_criteria", [])),
+            "session_granularity": feat.get("session_granularity"),
+            "status": feat.get("status"),
+        })
+
+    return {
+        "app_name": data.get("app_name", ""),
+        "features": feature_summaries,
+        "stats": {
+            "total_features": len(features),
+            "total_sub_features": total_sub,
+            "complexity_distribution": complexity_dist,
+            "max_dependency_depth": max_depth,
+            "has_cycles": has_cycles,
+        },
+    }
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+
+
+def cmd_validate(args):
+    """Handle the 'validate' command."""
+    if not args.input:
+        _err("--input is required for the validate command")
+        return 2
+
+    data, load_err = _load_json(args.input)
+    if load_err:
+        _err(load_err)
+        result = {
+            "valid": False,
+            "errors": [load_err],
+            "warnings": [],
+            "stats": {
+                "total_features": 0,
+                "total_sub_features": 0,
+                "complexity_distribution": {},
+                "max_dependency_depth": 0,
+                "has_cycles": False,
+            },
+        }
+        print(json.dumps(result, indent=2, ensure_ascii=False))
+        return 2
+
+    result = validate_feature_list(data)
+
+    # Print results to stdout
+    print(json.dumps(result, indent=2, ensure_ascii=False))
+
+    # Log to stderr for humans
+    if result["valid"]:
+        _info("Validation passed with {} warning(s)".format(len(result["warnings"])))
+    else:
+        _err("Validation failed with {} error(s) and {} warning(s)".format(
+            len(result["errors"]), len(result["warnings"])
+        ))
+
+    for e in result["errors"]:
+        _err("  " + e)
+    for w in result["warnings"]:
+        _warn("  " + w)
+
+    # Optionally write validated/cleaned output
+    if args.output and result["valid"]:
+        _write_json(args.output, data)
+        _info("Validated output written to {}".format(args.output))
+
+    return 0 if result["valid"] else 1
+
+
+def cmd_template(args):
+    """Handle the 'template' command."""
+    if not args.output:
+        _err("--output is required for the template command")
+        return 2
+
+    template = generate_template()
+    _write_json(args.output, template)
+    _info("Template written to {}".format(args.output))
+    return 0
+
+
+def cmd_summary(args):
+    """Handle the 'summary' command."""
+    if not args.input:
+        _err("--input is required for the summary command")
+        return 2
+
+    data, load_err = _load_json(args.input)
+    if load_err:
+        _err(load_err)
+        return 2
+
+    output_format = getattr(args, "format", "markdown") or "markdown"
+
+    if output_format == "json":
+        summary = generate_summary_json(data)
+        print(json.dumps(summary, indent=2, ensure_ascii=False))
+    else:
+        summary = generate_summary_markdown(data)
+        print(summary)
+
+    return 0
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Validate and generate feature-list.json files for the dev-pipeline system.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=(
+            "Examples:\n"
+            "  %(prog)s validate --input feature-list.json\n"
+            "  %(prog)s validate --input feature-list.json --output validated.json\n"
+            "  %(prog)s template --output feature-list.json\n"
+            "  %(prog)s summary --input feature-list.json\n"
+            "  %(prog)s summary --input feature-list.json --format json\n"
+        ),
+    )
+
+    subparsers = parser.add_subparsers(dest="command", help="Command to execute")
+
+    # -- validate --
+    p_validate = subparsers.add_parser(
+        "validate",
+        help="Validate an existing feature-list.json",
+    )
+    p_validate.add_argument(
+        "--input", required=True, help="Path to input feature-list.json"
+    )
+    p_validate.add_argument(
+        "--output", help="Path to write validated output (optional)"
+    )
+
+    # -- template --
+    p_template = subparsers.add_parser(
+        "template",
+        help="Generate a blank template feature-list.json",
+    )
+    p_template.add_argument(
+        "--output", required=True, help="Path to write template file"
+    )
+
+    # -- summary --
+    p_summary = subparsers.add_parser(
+        "summary",
+        help="Print a summary table of features from a feature-list.json",
+    )
+    p_summary.add_argument(
+        "--input", required=True, help="Path to input feature-list.json"
+    )
+    p_summary.add_argument(
+        "--format",
+        choices=["json", "markdown"],
+        default="markdown",
+        help="Output format (default: markdown)",
+    )
+
+    args = parser.parse_args()
+
+    if not args.command:
+        parser.print_help(sys.stderr)
+        return 2
+
+    dispatch = {
+        "validate": cmd_validate,
+        "template": cmd_template,
+        "summary": cmd_summary,
+    }
+
+    handler = dispatch.get(args.command)
+    if handler is None:
+        _err("Unknown command: {}".format(args.command))
+        return 2
+
+    return handler(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())