@caddis/cli 0.1.0 → 0.2.0

package/bundles/antigravity-plugin-extras/skills/data-contract-pipeline/scripts/generate_gap_report.py

@@ -0,0 +1,81 @@
+"""Generate human-readable gap reports from gap_register.json."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from collections import Counter
+from datetime import date
+from pathlib import Path
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Generate gap report markdown.")
+    parser.add_argument("--gaps", type=Path, required=True, help="gap_register.json")
+    parser.add_argument("--output", type=Path, required=True, help="gap report markdown path")
+    parser.add_argument("--ui-gap-brief", type=Path, help="Optional ui_gap_brief.md path")
+    args = parser.parse_args()
+
+    register = json.loads(args.gaps.read_text(encoding="utf-8-sig"))
+    gaps = register.get("gaps", [])
+    counts = Counter(gap.get("gap_type", "unknown") for gap in gaps)
+
+    lines = [
+        "# Data Contract Gap Report",
+        "",
+        f"Generated: {date.today().isoformat()}",
+        "",
+        "## Summary",
+        "",
+    ]
+    if counts:
+        for key, count in sorted(counts.items()):
+            lines.append(f"- `{key}`: {count}")
+    else:
+        lines.append("- No gaps found.")
+
+    lines.extend(["", "## Gaps", ""])
+    for gap in gaps:
+        label = gap.get("ui_name") or gap.get("requirement") or gap.get("requirement_id") or "Unnamed"
+        lines.extend(
+            [
+                f"### {label}",
+                "",
+                f"- Status: `{gap.get('status', 'unknown')}`",
+                f"- Gap type: `{gap.get('gap_type', 'unknown')}`",
+                f"- Candidate source field: `{gap.get('source_field_candidate', '')}`",
+                f"- Notes: {gap.get('notes', '')}",
+                "",
+            ]
+        )
+
+    args.output.parent.mkdir(parents=True, exist_ok=True)
+    args.output.write_text("\n".join(lines).rstrip() + "\n", encoding="utf-8")
+
+    if args.ui_gap_brief:
+        required = [gap for gap in gaps if gap.get("gap_type") == "required-unplaced"]
+        brief = [
+            "# UI Gap Brief",
+            "",
+            "Use this brief to place required data that is not present in the mockup/final UI.",
+            "",
+        ]
+        for gap in required:
+            brief.extend(
+                [
+                    f"## {gap.get('requirement_id', 'Requirement')}",
+                    "",
+                    f"- Requirement: {gap.get('requirement', '')}",
+                    "- Proposed placement: TBD by product/design.",
+                    "- Component type: TBD.",
+                    "- DisplayDTO fields: TBD.",
+                    "- Acceptance criteria: Field is visible in the agreed UI location and has source-to-screen lineage.",
+                    "",
+                ]
+            )
+        args.ui_gap_brief.parent.mkdir(parents=True, exist_ok=True)
+        args.ui_gap_brief.write_text("\n".join(brief).rstrip() + "\n", encoding="utf-8")
+
+
+if __name__ == "__main__":
+    main()

package/bundles/antigravity-plugin-extras/skills/data-contract-pipeline/scripts/generate_mapping_doc.py

@@ -0,0 +1,294 @@
+"""
+Generate Mapping Doc — Produces a human-readable field mapping document
+from Pydantic ingestion model + display DTO + optional TypeScript types.
+
+Usage:
+    python scripts/generate_mapping_doc.py \
+        --ingestion src.models.ingestion.nps_monthly:NpsMonthlyPayload \
+        --dto src.models.responses.nps_monthly:NpsMonthlyResponse \
+        --ts-types frontend/src/types/nps-monthly.ts \
+        --output docs/mapping/nps-monthly-mapping.md
+
+    # Check mode — exit 1 if existing doc is stale
+    python scripts/generate_mapping_doc.py \
+        --ingestion src.models.ingestion.nps_monthly:NpsMonthlyPayload \
+        --dto src.models.responses.nps_monthly:NpsMonthlyResponse \
+        --check docs/mapping/nps-monthly-mapping.md
+
+Part of the data-contract-pipeline skill.
+"""
+
+from __future__ import annotations
+
+import argparse
+import importlib
+import re
+import sys
+from datetime import date
+from pathlib import Path
+from typing import Any, get_type_hints
+
+
+def load_class(dotted_path: str) -> type:
+    """Import a class from 'module.path:ClassName' or 'module.path.ClassName'."""
+    if ":" in dotted_path:
+        module_path, class_name = dotted_path.rsplit(":", 1)
+    else:
+        module_path, _, class_name = dotted_path.rpartition(".")
+    if not module_path:
+        raise ValueError(
+            f"Invalid class path: {dotted_path}. "
+            f"Expected: module.path:ClassName or module.path.ClassName"
+        )
+    module = importlib.import_module(module_path)
+    cls = getattr(module, class_name, None)
+    if cls is None:
+        raise AttributeError(f"{class_name} not found in {module_path}")
+    return cls
+
+
+def get_field_info(model_cls: type) -> list[dict[str, str]]:
+    """Extract field name, alias, and type string from a Pydantic model."""
+    hints = get_type_hints(model_cls, include_extras=True)
+    rows: list[dict[str, str]] = []
+    for name, field in model_cls.model_fields.items():
+        alias = field.alias or name
+        type_str = _type_repr(hints.get(name, Any))
+        rows.append({
+            "field_name": name,
+            "alias": alias,
+            "type": type_str,
+        })
+    return rows
+
+
+def _type_repr(tp: Any) -> str:
+    """Compact string repr of a type annotation."""
+    origin = getattr(tp, "__origin__", None)
+    args = getattr(tp, "__args__", None)
+    if origin is not None and args:
+        origin_name = getattr(origin, "__name__", str(origin))
+        arg_strs = ", ".join(_type_repr(a) for a in args)
+        return f"{origin_name}[{arg_strs}]"
+    if hasattr(tp, "__name__"):
+        return tp.__name__
+    return str(tp)
+
+
+def parse_ts_interface(ts_path: Path) -> dict[str, str]:
+    """Extract property names and types from a TypeScript interface file.
+
+    Returns {propertyName: tsType}.
+    """
+    if not ts_path.exists():
+        return {}
+    text = ts_path.read_text(encoding="utf-8")
+    props: dict[str, str] = {}
+    # Match:  propertyName: type;  or  propertyName?: type;
+    for match in re.finditer(
+        r"^\s+(\w+)\??:\s*(.+?);", text, re.MULTILINE,
+    ):
+        props[match.group(1)] = match.group(2).strip()
+    return props
+
+
+def build_mapping_table(
+    ingestion_fields: list[dict[str, str]],
+    dto_fields: list[dict[str, str]],
+    ts_props: dict[str, str],
+) -> tuple[list[str], list[str]]:
+    """Build the field mapping rows and dropped field rows.
+
+    Returns (mapping_rows, dropped_rows) as lists of markdown table lines.
+    """
+    dto_by_alias: dict[str, dict[str, str]] = {
+        f["alias"]: f for f in dto_fields
+    }
+    dto_by_name: dict[str, dict[str, str]] = {
+        f["field_name"]: f for f in dto_fields
+    }
+
+    mapping_rows: list[str] = []
+    covered_aliases: set[str] = set()
+
+    for ing in ingestion_fields:
+        json_key = ing["alias"]
+        py_field = ing["field_name"]
+        py_type = ing["type"]
+
+        # Find matching DTO field by alias or name
+        dto = dto_by_alias.get(json_key) or dto_by_name.get(py_field)
+        if dto:
+            dto_alias = dto["alias"]
+            covered_aliases.add(dto_alias)
+            ts_prop = ts_props.get(dto_alias, "—")
+            mapping_rows.append(
+                f"| `{json_key}` | `{py_field}` | `{dto_alias}` "
+                f"| `{ts_prop}` | `{py_type}` | |"
+            )
+        else:
+            mapping_rows.append(
+                f"| `{json_key}` | `{py_field}` | — | — "
+                f"| `{py_type}` | **Not in DTO** |"
+            )
+
+    # Dropped fields: in ingestion but not in DTO
+    dropped_rows: list[str] = []
+    for ing in ingestion_fields:
+        json_key = ing["alias"]
+        py_field = ing["field_name"]
+        dto = dto_by_alias.get(json_key) or dto_by_name.get(py_field)
+        if not dto:
+            dropped_rows.append(
+                f"| `{json_key}` | Not mapped to display DTO |"
+            )
+
+    return mapping_rows, dropped_rows
+
+
+def generate_doc(
+    ingestion_cls: type,
+    dto_cls: type,
+    ts_path: Path | None = None,
+) -> str:
+    """Generate the full mapping document as a markdown string."""
+    source_name = ingestion_cls.__name__.replace("Payload", "")
+    ing_fields = get_field_info(ingestion_cls)
+    dto_fields = get_field_info(dto_cls)
+    ts_props = parse_ts_interface(ts_path) if ts_path else {}
+
+    mapping_rows, dropped_rows = build_mapping_table(
+        ing_fields, dto_fields, ts_props,
+    )
+
+    field_table = "\n".join(mapping_rows) if mapping_rows else "| _(no fields)_ | | | | | |"
+    dropped_table = "\n".join(dropped_rows) if dropped_rows else "| _(none)_ | |"
+
+    ing_module = ingestion_cls.__module__
+    dto_module = dto_cls.__module__
+    today = date.today().isoformat()
+
+    return f"""# {source_name} — UI ↔ JSON Data Mapping
+
+> **Auto-generated reference** — do not hand-edit.
+> Regenerate with: `python scripts/generate_mapping_doc.py`
+> Source of truth: contract tests + Pydantic models
+
+---
+
+## Data Source
+
+| Property | Value |
+|----------|-------|
+| Ingestion Model | `{ing_module}.{ingestion_cls.__name__}` |
+| Display DTO | `{dto_module}.{dto_cls.__name__}` |
+| TS Types | `{ts_path or '—'}` |
+
+---
+
+## Field Mapping
+
+| JSON Key | Python Field | DTO Alias | TypeScript Property | Type | Notes |
+|----------|-------------|-----------|--------------------:|------|-------|
+{field_table}
+
+---
+
+## Intentionally Dropped Fields
+
+Fields present in the source but NOT exposed to the frontend:
+
+| JSON Key | Reason |
+|----------|--------|
+{dropped_table}
+
+---
+
+## Changelog
+
+| Date | Change |
+|------|--------|
+| {today} | Auto-generated from models |
+"""
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Generate or check a field mapping doc from Pydantic models"
+    )
+    parser.add_argument(
+        "--ingestion", required=True,
+        help="Dotted path to ingestion model (module.path:ClassName)",
+    )
+    parser.add_argument(
+        "--dto", required=True,
+        help="Dotted path to display DTO (module.path:ClassName)",
+    )
+    parser.add_argument(
+        "--ts-types", type=Path, default=None,
+        help="Path to TypeScript interface file (optional)",
+    )
+    parser.add_argument(
+        "--output", type=Path, default=None,
+        help="Write mapping doc to this file (generate mode)",
+    )
+    parser.add_argument(
+        "--check", type=Path, default=None,
+        help="Compare existing doc against models (check mode, exit 1 if stale)",
+    )
+    args = parser.parse_args()
+
+    if not args.output and not args.check:
+        parser.error("Provide --output (generate) or --check (validate)")
+
+    try:
+        ingestion_cls = load_class(args.ingestion)
+        dto_cls = load_class(args.dto)
+    except (ValueError, AttributeError, ModuleNotFoundError) as e:
+        print(f"Error loading model: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    doc = generate_doc(ingestion_cls, dto_cls, args.ts_types)
+
+    if args.output:
+        args.output.parent.mkdir(parents=True, exist_ok=True)
+        args.output.write_text(doc, encoding="utf-8")
+        print(f"✅ Mapping doc written to {args.output}")
+        sys.exit(0)
+
+    if args.check:
+        if not args.check.exists():
+            print(f"❌ Mapping doc not found: {args.check}", file=sys.stderr)
+            sys.exit(1)
+
+        existing = args.check.read_text(encoding="utf-8")
+        # Compare the Field Mapping table sections only (ignore dates/changelog)
+        new_table = _extract_table(doc)
+        old_table = _extract_table(existing)
+
+        if new_table == old_table:
+            print("✅ Mapping doc is current.")
+            sys.exit(0)
+        else:
+            print("❌ Mapping doc is STALE — regenerate it.")
+            print(f"  Expected {len(new_table)} lines, found {len(old_table)} lines.")
+            sys.exit(1)
+
+
+def _extract_table(text: str) -> list[str]:
+    """Extract the Field Mapping table rows for comparison."""
+    lines: list[str] = []
+    in_section = False
+    for line in text.splitlines():
+        if "## Field Mapping" in line:
+            in_section = True
+            continue
+        if in_section and line.startswith("## "):
+            break
+        if in_section and line.startswith("|") and "JSON Key" not in line and "---" not in line:
+            lines.append(line.strip())
+    return lines
+
+
+if __name__ == "__main__":
+    main()

package/bundles/antigravity-plugin-extras/skills/data-contract-pipeline/scripts/ts_dto_compare.py

@@ -0,0 +1,214 @@
+"""
+TypeScript ↔ DTO Comparator
+
+Compares TypeScript interface properties against Python Pydantic DTO aliases
+to detect D4 (alias mismatch) and D5 (type mismatch) drift.
+
+Usage:
+    python scripts/ts_dto_compare.py \
+        --ts frontend/src/types/my-source.ts \
+        --dto src.models.responses.my_source.MyResponse
+
+Part of the data-contract-pipeline skill.
+"""
+
+from __future__ import annotations
+
+import importlib
+import re
+import sys
+from pathlib import Path
+
+
+# Python → TypeScript type mapping
+PYTHON_TO_TS_TYPE: dict[str, str] = {
+    "str": "string",
+    "int": "number",
+    "float": "number",
+    "bool": "boolean",
+    "list": "Array",
+    "dict": "Record",
+    "None": "null",
+    "Any": "any",
+}
+
+
+def load_class(dotted_path: str) -> type:
+    """Import a class from a dotted module path."""
+    module_path, _, class_name = dotted_path.rpartition(".")
+    if not module_path:
+        raise ValueError(f"Invalid class path: {dotted_path}")
+    module = importlib.import_module(module_path)
+    cls = getattr(module, class_name, None)
+    if cls is None:
+        raise AttributeError(f"{class_name} not found in {module_path}")
+    return cls
+
+
+def extract_ts_properties(ts_source: str) -> dict[str, str]:
+    """
+    Extract property names and types from a TypeScript interface.
+
+    Returns dict of {property_name: type_string}.
+    Handles basic types — not deep generics or union types.
+    """
+    properties: dict[str, str] = {}
+
+    # Match: propertyName: type; or propertyName?: type;
+    pattern = re.compile(
+        r"^\s*(\w+)\s*\??\s*:\s*(.+?)\s*;",
+        re.MULTILINE,
+    )
+
+    for match in pattern.finditer(ts_source):
+        prop_name = match.group(1)
+        prop_type = match.group(2).strip()
+        properties[prop_name] = prop_type
+
+    return properties
+
+
+def get_dto_aliases_and_types(dto_cls: type) -> dict[str, str]:
+    """
+    Get DTO field aliases and their simplified type names.
+
+    Returns dict of {alias: simplified_python_type}.
+    """
+    result: dict[str, str] = {}
+    for name, info in dto_cls.model_fields.items():
+        alias = info.alias or name
+        # Get the annotation type and simplify
+        annotation = info.annotation
+        type_name = getattr(annotation, "__name__", str(annotation))
+        result[alias] = type_name
+    return result
+
+
+def python_type_to_ts(python_type: str) -> str:
+    """Convert a simplified Python type string to expected TypeScript type."""
+    # Handle Optional/union types
+    python_type = python_type.replace("NoneType", "None")
+
+    # Direct mapping
+    if python_type in PYTHON_TO_TS_TYPE:
+        return PYTHON_TO_TS_TYPE[python_type]
+
+    # Handle list[T]
+    list_match = re.match(r"list\[(.+)]", python_type)
+    if list_match:
+        inner = python_type_to_ts(list_match.group(1))
+        return f"{inner}[]"
+
+    # Handle dict[str, T]
+    dict_match = re.match(r"dict\[str,\s*(.+)]", python_type)
+    if dict_match:
+        inner = python_type_to_ts(dict_match.group(1))
+        return f"Record<string, {inner}>"
+
+    return python_type
+
+
+def compare(
+    ts_properties: dict[str, str],
+    dto_fields: dict[str, str],
+) -> list[str]:
+    """
+    Compare TypeScript properties against DTO aliases.
+
+    Returns list of drift findings.
+    """
+    findings: list[str] = []
+
+    ts_names = set(ts_properties.keys())
+    dto_names = set(dto_fields.keys())
+
+    # D4 — Alias mismatch: DTO field not in TypeScript
+    for name in sorted(dto_names - ts_names):
+        findings.append(
+            f"D4: DTO alias '{name}' not found in TypeScript interface"
+        )
+
+    # D4 — Alias mismatch: TypeScript property not in DTO
+    for name in sorted(ts_names - dto_names):
+        findings.append(
+            f"D4: TypeScript property '{name}' not found in DTO aliases"
+        )
+
+    # D5 — Type mismatch (for shared properties)
+    for name in sorted(ts_names & dto_names):
+        expected_ts = python_type_to_ts(dto_fields[name])
+        actual_ts = ts_properties[name]
+
+        # Normalize for comparison (strip whitespace, lowercase basic types)
+        norm_expected = expected_ts.lower().strip()
+        norm_actual = actual_ts.lower().strip()
+
+        if norm_expected != norm_actual:
+            findings.append(
+                f"D5: Type mismatch for '{name}': "
+                f"DTO expects '{expected_ts}', TS has '{actual_ts}'"
+            )
+
+    return findings
+
+
+def main() -> None:
+    """CLI entry point."""
+    import argparse
+
+    parser = argparse.ArgumentParser(
+        description="Compare TypeScript interface properties against Python DTO aliases"
+    )
+    parser.add_argument(
+        "--ts",
+        type=Path,
+        required=True,
+        help="Path to TypeScript types file",
+    )
+    parser.add_argument(
+        "--dto",
+        type=str,
+        required=True,
+        help="Dotted path to DTO class (e.g., src.models.responses.nps.NpsResponse)",
+    )
+    args = parser.parse_args()
+
+    # Load TypeScript source
+    if not args.ts.exists():
+        print(f"Error: TypeScript file not found: {args.ts}", file=sys.stderr)
+        sys.exit(1)
+
+    ts_source = args.ts.read_text(encoding="utf-8")
+    ts_properties = extract_ts_properties(ts_source)
+
+    if not ts_properties:
+        print(
+            f"Warning: No properties found in {args.ts}. "
+            f"Is the interface defined with standard syntax?",
+            file=sys.stderr,
+        )
+
+    # Load DTO
+    try:
+        dto_cls = load_class(args.dto)
+    except (ValueError, AttributeError, ModuleNotFoundError) as e:
+        print(f"Error loading DTO: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    dto_fields = get_dto_aliases_and_types(dto_cls)
+
+    # Compare
+    findings = compare(ts_properties, dto_fields)
+
+    if not findings:
+        print(f"✅ No drift detected ({len(ts_properties)} properties matched).")
+        sys.exit(0)
+    else:
+        print(f"❌ {len(findings)} drift finding(s):\n")
+        for finding in findings:
+            print(f"  {finding}")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

package/bundles/antigravity-plugin-extras/skills/data-contract-pipeline/scripts/validate_lineage.py

@@ -0,0 +1,51 @@
+"""Validate that production UI fields have source-to-screen lineage."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+
+REQUIRED_KEYS = (
+    "ui_component",
+    "ui_label",
+    "frontend_field",
+    "api_field",
+    "display_dto_field",
+    "source",
+    "source_field",
+)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Validate lineage_manifest.json coverage.")
+    parser.add_argument("--lineage", type=Path, required=True, help="lineage_manifest.json")
+    parser.add_argument(
+        "--allow-partial",
+        action="store_true",
+        help="Return success for partial/evolving contracts.",
+    )
+    args = parser.parse_args()
+
+    manifest = json.loads(args.lineage.read_text(encoding="utf-8-sig"))
+    findings: list[str] = []
+    for idx, item in enumerate(manifest.get("lineage", []), start=1):
+        status = item.get("status", "contract-backed")
+        if status in {"deferred", "mockup-only", "source-capability-only"}:
+            continue
+        missing = [key for key in REQUIRED_KEYS if not item.get(key)]
+        if missing:
+            findings.append(f"L{idx}: missing {', '.join(missing)}")
+
+    if findings:
+        for finding in findings:
+            print(finding)
+        sys.exit(0 if args.allow_partial else 1)
+    print("Lineage validation passed.")
+
+
+if __name__ == "__main__":
+    main()