pi-apexlang 0.1.0

package/skills/apexlang/runtime/internal/python/validate_apexlang_vocab.py

@@ -0,0 +1,281 @@
+#!/usr/bin/env python3
+"""Validate and optionally normalize APEXlang scaffold vocabulary."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from validator_common import LOG_ROOT, display_path, line_no, write_report
+
+DEFAULT_REPORT = LOG_ROOT / "apexlang-vocab-report.json"
+SUPPORTED_MMD_VERSION = "26.1.0+3102"
+
+
+@dataclass(frozen=True)
+class AliasRule:
+    """Mapping rule for replacing legacy vocabulary with canonical APEXlang terms."""
+    old: str
+    new: str
+    kind: str  # "block" or "property"
+
+
+ALIAS_RULES: tuple[AliasRule, ...] = (
+    AliasRule(old="nav", new="navigation", kind="block"),
+    AliasRule(old="navMenu", new="navigationMenu", kind="block"),
+    AliasRule(old="navBar", new="navigationBar", kind="block"),
+    AliasRule(old="themeNo", new="themeNumber", kind="property"),
+    AliasRule(old="js", new="javaScript", kind="block"),
+    AliasRule(old="navBarList", new="navigationBarList", kind="property"),
+    AliasRule(old="navMenuListPosition", new="navigationMenuListPosition", kind="property"),
+    AliasRule(old="navMenuListTop", new="navigationMenuListTop", kind="property"),
+    AliasRule(old="navMenuListSide", new="navigationMenuListSide", kind="property"),
+    AliasRule(old="pageNo", new="pageNumber", kind="property"),
+)
+
+MIXED_PAIRS: tuple[tuple[str, str], ...] = tuple((rule.old, rule.new) for rule in ALIAS_RULES)
+
+
+def parse_args(argv: list[str]) -> argparse.Namespace:
+    """Parse command-line options for vocabulary validation and rewrite mode."""
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--app-path", required=True, help="Path to the target application folder.")
+    parser.add_argument("--rewrite", action="store_true", help="Rewrite deterministic aliases in place.")
+    parser.add_argument("--check-only", action="store_true", help="Check vocabulary only and do not rewrite.")
+    parser.add_argument(
+        "--report-path",
+        default=str(DEFAULT_REPORT),
+        help="JSON report output path.",
+    )
+    return parser.parse_args(argv)
+
+
+def resolve_mmd_version(app_path: Path) -> str:
+    """Read the APEXlang MMD version from application metadata when available."""
+    apexlang_path = app_path / ".apex/apexlang.json"
+    if not apexlang_path.exists():
+        return ""
+    try:
+        payload = json.loads(apexlang_path.read_text(encoding="utf-8"))
+    except Exception:
+        return ""
+    if not isinstance(payload, dict):
+        return ""
+    value = payload.get("mmdVersion")
+    return str(value).strip() if value is not None else ""
+
+
+def is_supported_mmd_version(mmd_version: str) -> bool:
+    """Return whether an MMD version matches the active APEXlang baseline."""
+    return mmd_version.strip() == SUPPORTED_MMD_VERSION
+
+
+def collect_target_files(app_path: Path) -> list[Path]:
+    """Collect application DSL files that can contain legacy vocabulary."""
+    files: list[Path] = []
+    patterns = (
+        "application.apx",
+        "shared-components/themes/**/theme.apx",
+        "shared-components/component-settings.example.md",
+        "shared-components/breadcrumbs.apx",
+        "pages/p00001-*.apx",
+        "pages/p09999-*.apx",
+    )
+    for pattern in patterns:
+        files.extend(app_path.glob(pattern))
+    unique = sorted({path.resolve() for path in files if path.exists() and path.is_file()})
+    return [Path(p) for p in unique]
+
+
+def find_pattern(rule: AliasRule) -> re.Pattern[str]:
+    """Build the regex used to find a legacy alias rule."""
+    token = re.escape(rule.old)
+    if rule.kind == "block":
+        return re.compile(rf"(?m)^(\s*)({token})(\s*)\{{")
+    return re.compile(rf"(?m)^(\s*)({token})(\s*:)")
+
+
+def find_canonical_pattern(rule: AliasRule) -> re.Pattern[str]:
+    """Build the regex used to find the canonical target for an alias rule."""
+    token = re.escape(rule.new)
+    if rule.kind == "block":
+        return re.compile(rf"(?m)^\s*{token}\s*\{{")
+    return re.compile(rf"(?m)^\s*{token}\s*:")
+
+
+
+def run(argv: list[str]) -> int:
+    """Validate or rewrite vocabulary aliases and write the JSON report."""
+    args = parse_args(argv)
+    rewrite_enabled = bool(args.rewrite and not args.check_only)
+
+    app_path = Path(args.app_path).expanduser()
+    if not app_path.is_absolute():
+        app_path = (Path.cwd() / app_path).resolve()
+
+    report_path = Path(args.report_path).expanduser()
+    if not report_path.is_absolute():
+        report_path = (Path.cwd() / report_path).resolve()
+
+    report: dict[str, Any] = {
+        "app_path": str(app_path),
+        "mmd_version": "",
+        "supported_version": False,
+        "rewrite_requested": bool(args.rewrite),
+        "check_only": bool(args.check_only),
+        "files_scanned": [],
+        "files_touched": [],
+        "rewrites": [],
+        "legacy_aliases_found": [],
+        "mixed_vocabulary_detected": False,
+        "mixed_vocabulary_files": [],
+        "blocking_reason": "",
+        "unresolved": [],
+    }
+
+    if not app_path.exists():
+        report["blocking_reason"] = "APP_PATH_REQUIRED"
+        report["unresolved"].append(
+            {
+                "file": str(app_path),
+                "rule": "app_path",
+                "message": "Application path does not exist",
+            }
+        )
+        write_report(report_path, report)
+        print("Vocabulary compatibility check failed: application path does not exist.")
+        return 1
+
+    mmd_version = resolve_mmd_version(app_path)
+    report["mmd_version"] = mmd_version
+    report["supported_version"] = is_supported_mmd_version(mmd_version)
+    target_files = collect_target_files(app_path)
+    report["files_scanned"] = [display_path(path) for path in target_files]
+
+    if not mmd_version:
+        report["blocking_reason"] = "MMD_VERSION_REQUIRED"
+        report["unresolved"].append(
+            {
+                "file": display_path(app_path / ".apex/apexlang.json"),
+                "rule": "mmdVersion",
+                "message": "Unable to resolve mmdVersion from .apex/apexlang.json",
+            }
+        )
+        write_report(report_path, report)
+        print("Vocabulary compatibility check failed: missing mmdVersion.")
+        return 1
+
+    if not report["supported_version"]:
+        report["blocking_reason"] = "UNSUPPORTED_MMD_VERSION"
+        report["unresolved"].append(
+            {
+                "file": display_path(app_path / ".apex/apexlang.json"),
+                "rule": "mmdVersion",
+                "message": f"Unsupported mmdVersion '{mmd_version}'. Supported version is {SUPPORTED_MMD_VERSION}.",
+            }
+        )
+        write_report(report_path, report)
+        print(f"Vocabulary compatibility check failed: unsupported mmdVersion (supported version {SUPPORTED_MMD_VERSION}).")
+        return 1
+
+    touched_files: set[str] = set()
+
+    for path in target_files:
+        original_text = path.read_text(encoding="utf-8")
+        updated_text = original_text
+
+        for rule in ALIAS_RULES:
+            pattern = find_pattern(rule)
+            matches = list(pattern.finditer(updated_text))
+            if not matches:
+                continue
+
+            for match in matches:
+                record = {
+                    "file": display_path(path),
+                    "line": line_no(updated_text, match.start(2)),
+                    "legacy_key": rule.old,
+                    "expected_key": rule.new,
+                    "kind": rule.kind,
+                }
+                report["legacy_aliases_found"].append(record)
+                report["rewrites"].append(
+                    {
+                        "file": display_path(path),
+                        "line": record["line"],
+                        "from": rule.old,
+                        "to": rule.new,
+                        "kind": rule.kind,
+                    }
+                )
+
+            if rewrite_enabled:
+                if rule.kind == "block":
+                    updated_text = pattern.sub(rf"\1{rule.new}\3{{", updated_text)
+                else:
+                    updated_text = pattern.sub(rf"\1{rule.new}\3", updated_text)
+
+        if rewrite_enabled and updated_text != original_text:
+            path.write_text(updated_text, encoding="utf-8")
+            touched_files.add(display_path(path))
+
+    report["files_touched"] = sorted(touched_files)
+
+    mixed_files: set[str] = set()
+    canonical_present_any = False
+    legacy_present_any = False
+    for path in target_files:
+        text = path.read_text(encoding="utf-8")
+        rel_path = display_path(path)
+        for rule in ALIAS_RULES:
+            legacy_pattern = find_pattern(rule)
+            canonical_pattern = find_canonical_pattern(rule)
+            if legacy_pattern.search(text):
+                legacy_present_any = True
+            if canonical_pattern.search(text):
+                canonical_present_any = True
+            for match in legacy_pattern.finditer(text):
+                report["unresolved"].append(
+                    {
+                        "file": rel_path,
+                        "line": line_no(text, match.start(2)),
+                        "legacy_key": rule.old,
+                        "expected_key": rule.new,
+                        "kind": rule.kind,
+                    }
+                )
+            if legacy_pattern.search(text) and canonical_pattern.search(text):
+                mixed_files.add(rel_path)
+
+    if legacy_present_any and canonical_present_any:
+        mixed_files.add("<app>")
+
+    report["mixed_vocabulary_files"] = sorted(mixed_files)
+    report["mixed_vocabulary_detected"] = bool(mixed_files)
+
+    if report["mixed_vocabulary_detected"]:
+        report["blocking_reason"] = "MIXED_VOCABULARY_DETECTED"
+    elif report["unresolved"]:
+        report["blocking_reason"] = "LEGACY_VOCABULARY_DETECTED"
+
+    write_report(report_path, report)
+
+    if report["mixed_vocabulary_detected"]:
+        print("Vocabulary compatibility check failed: mixed legacy and canonical vocabulary detected.")
+        return 1
+
+    if report["unresolved"]:
+        print("Vocabulary compatibility check failed: unresolved legacy aliases remain.")
+        return 1
+
+    print("Vocabulary compatibility check passed.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(run(sys.argv[1:]))

package/skills/apexlang/runtime/internal/python/validate_validations.py

@@ -0,0 +1,289 @@
+#!/usr/bin/env python3
+"""Validate APEXlang snippets for deterministic governance checks."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+from validator_common import COMPONENT_POLICIES_PATH, LOG_ROOT, VALIDATIONS_TEMPLATE_ROOT, ROOT, collect_targets, display_path, issue_to_record, line_no, write_report
+
+COMPONENT_POLICY_PATH = COMPONENT_POLICIES_PATH
+DEFAULT_REPORT = LOG_ROOT / "apexlang-validations-report.json"
+GOSPEL_REGEX = re.compile(
+    r"validation\s+(?P<static_id>[A-Za-z0-9_-]+)\s*\(\s*"
+    r"name:\s*[^\n]+?\n"
+    r"\s*execution\s*\{\s*sequence:\s*(?P<sequence>\d+)\s*\}\s*"
+    r"validation\s*\{(?P<validation_body>.*?)\}\s*"
+    r"error\s*\{\s*errorMessage:\s*[^\n]+?\n\s*associatedItem:\s*@(?P<item>[A-Za-z0-9_]+)\s*\}\s*"
+    r"(?:serverSideCondition\s*\{\s*whenButtonPressed:\s*@[A-Za-z0-9_-]+?\s*\}\s*)?"
+    r"(?:security\s*\{\s*authorizationScheme:\s*[^\n]+?\}\s*)?"
+    r"\)",
+    re.DOTALL,
+)
+
+
+def find_blocks(text: str, keyword: str) -> list[tuple[int, str]]:
+    """Return (start_idx, block_text) pairs for top-level keyword blocks."""
+    results: list[tuple[int, str]] = []
+    pattern = re.compile(rf"^\s*{re.escape(keyword)}\s+[A-Za-z0-9_$-]+\s*\(", re.MULTILINE)
+    for match in pattern.finditer(text):
+        start = match.start()
+        depth = 0
+        for idx in range(start, len(text)):
+            ch = text[idx]
+            if ch == "(":
+                depth += 1
+            elif ch == ")":
+                depth -= 1
+                if depth == 0:
+                    results.append((start, text[start : idx + 1]))
+                    break
+    return results
+
+
+def find_validation_blocks(text: str) -> list[tuple[int, str, str]]:
+    """Return (start_idx, static_id, block_text) triples for every validation."""
+    results: list[tuple[int, str, str]] = []
+    for start_idx, block in find_blocks(text, "validation"):
+        match = re.search(r"^\s*validation\s+([A-Za-z0-9_-]+)", block, re.MULTILINE)
+        if match:
+            results.append((start_idx, match.group(1), block))
+    return results
+
+
+def lint_validation_file(path: Path) -> list[str]:
+    """Validate validation snippets against the required deterministic skeleton."""
+    text = path.read_text(encoding="utf-8", errors="ignore")
+    issues: list[str] = []
+    for start_idx, static_id, block in find_validation_blocks(text):
+        if not GOSPEL_REGEX.search(block):
+            issues.append(
+                f"{display_path(path)}:{line_no(text, start_idx)}: "
+                f"VALIDATION_RULE_SKELETON validation '{static_id}' deviates from gospel skeleton"
+            )
+        if not static_id.upper().startswith("VAL_"):
+            issues.append(
+                f"{display_path(path)}:{line_no(text, start_idx)}: "
+                f"VALIDATION_RULE_STATIC_ID validation '{static_id}' static ID must start with VAL_"
+            )
+    return issues
+
+
+
+def load_component_policy_rules(scope: str) -> list[dict]:
+    """Load component policy lint rules for the requested component scope."""
+    try:
+        data = json.loads(COMPONENT_POLICY_PATH.read_text(encoding="utf-8"))
+    except Exception as exc:
+        raise RuntimeError(f"Failed to parse component policy JSON: {COMPONENT_POLICY_PATH} ({exc})") from exc
+
+    if not isinstance(data, dict) or not isinstance(data.get("rules"), list):
+        raise RuntimeError("component-policies.json must contain a 'rules' array")
+
+    rules: list[dict] = []
+    for rule in data["rules"]:
+        if not isinstance(rule, dict):
+            raise RuntimeError("component policy rule must be an object")
+
+        if rule.get("scope") != scope:
+            continue
+
+        # Scope-first validation: only validate schema required by this lint mode.
+        required = ["id", "scope", "when", "forbid", "severity", "message"]
+        for key in required:
+            if key not in rule:
+                raise RuntimeError(f"component policy rule missing required key: {key}")
+        if not isinstance(rule["when"], dict) or "action" not in rule["when"]:
+            raise RuntimeError(f"component policy rule {rule['id']} must define when.action")
+        if not isinstance(rule["forbid"], list):
+            raise RuntimeError(f"component policy rule {rule['id']} must define forbid as a list")
+
+        rules.append(rule)
+    return rules
+
+
+def lint_button_rules(path: Path, rules: list[dict]) -> list[str]:
+    """Validate button snippets against component policy requirements."""
+    text = path.read_text(encoding="utf-8", errors="ignore")
+    issues: list[str] = []
+
+    for start_idx, button_block in find_blocks(text, "button"):
+        behavior_blocks = re.finditer(r"\bbehavior\s*\{(?P<body>.*?)\}", button_block, re.DOTALL)
+        for behavior_match in behavior_blocks:
+            body = behavior_match.group("body")
+            action_match = re.search(r"\baction\s*:\s*([A-Za-z0-9_]+)", body)
+            if not action_match:
+                continue
+
+            action_value = action_match.group(1)
+            for rule in rules:
+                if rule.get("severity") != "error":
+                    continue
+                if action_value != rule["when"].get("action"):
+                    continue
+
+                for forbidden_attr in rule["forbid"]:
+                    if re.search(rf"\b{re.escape(forbidden_attr)}\s*:", body):
+                        absolute_idx = start_idx + behavior_match.start()
+                        issues.append(
+                            f"{display_path(path)}:{line_no(text, absolute_idx)}: "
+                            f"{rule['id']} {rule['message']}"
+                        )
+    return issues
+
+
+def lint_chart_series_rules(path: Path) -> list[str]:
+    """Validate chart series snippets for deterministic SQL and labeling rules."""
+    text = path.read_text(encoding="utf-8", errors="ignore")
+    issues: list[str] = []
+
+    for region_start, region_block in find_blocks(text, "region"):
+        if not re.search(r"\btype\s*:\s*chart\b", region_block):
+            continue
+
+        region_match = re.search(r"^\s*region\s+([A-Za-z0-9_-]+)", region_block, re.MULTILINE)
+        region_name = region_match.group(1) if region_match else "<unknown-region>"
+        seen_sequences: dict[int, str] = {}
+
+        for series_offset, series_block in find_blocks(region_block, "series"):
+            series_match = re.search(r"^\s*series\s+([A-Za-z0-9_-]+)", series_block, re.MULTILINE)
+            series_name = series_match.group(1) if series_match else "<unknown-series>"
+            absolute_idx = region_start + series_offset
+
+            execution_match = re.search(
+                r"\bexecution\s*\{(?P<body>.*?)\}",
+                series_block,
+                re.DOTALL,
+            )
+            if not execution_match:
+                issues.append(
+                    f"{display_path(path)}:{line_no(text, absolute_idx)}: "
+                    f"CHART_RULE_001 chart region '{region_name}' series '{series_name}' must define execution.sequence explicitly"
+                )
+                continue
+
+            sequence_match = re.search(r"\bsequence\s*:\s*(\d+)\b", execution_match.group("body"))
+            if not sequence_match:
+                issues.append(
+                    f"{display_path(path)}:{line_no(text, absolute_idx)}: "
+                    f"CHART_RULE_002 chart region '{region_name}' series '{series_name}' execution block must include sequence: <positive integer>"
+                )
+                continue
+
+            sequence = int(sequence_match.group(1))
+            if sequence <= 0:
+                issues.append(
+                    f"{display_path(path)}:{line_no(text, absolute_idx)}: "
+                    f"CHART_RULE_003 chart region '{region_name}' series '{series_name}' execution.sequence must be a positive integer"
+                )
+                continue
+
+            if sequence in seen_sequences:
+                issues.append(
+                    f"{display_path(path)}:{line_no(text, absolute_idx)}: "
+                    f"CHART_RULE_004 chart region '{region_name}' reuses execution.sequence {sequence} for series '{series_name}' and '{seen_sequences[sequence]}'"
+                )
+                continue
+
+            seen_sequences[sequence] = series_name
+
+    return issues
+
+
+def run_validation_lint(paths: list[str], report_path: str = "") -> int:
+    """Run validation skeleton linting and optionally write a JSON report."""
+    targets = collect_targets(paths, (".apx", ".md"), warn_missing=True)
+    if not targets:
+        targets = sorted(VALIDATIONS_TEMPLATE_ROOT.glob("*.md"))
+
+    issues: list[str] = []
+    for target in targets:
+        issues.extend(lint_validation_file(target))
+
+    if report_path:
+        resolved_report_path = Path(report_path).expanduser()
+        if not resolved_report_path.is_absolute():
+            resolved_report_path = (Path.cwd() / resolved_report_path).resolve()
+        write_report(
+            resolved_report_path,
+            {
+                "mode": "validations",
+                "status": "fail" if issues else "pass",
+                "targets": [display_path(target) for target in targets],
+                "issues": [issue_to_record(issue) for issue in issues],
+            },
+        )
+
+    if issues:
+        print("VALIDATION_LINT_FAILED")
+        for issue in issues:
+            print(" -", issue)
+        return 1
+
+    print("VALIDATION_LINT_OK")
+    return 0
+
+
+def run_button_rule_lint(paths: list[str]) -> int:
+    """Run button policy linting and print all discovered issues."""
+    rules = load_component_policy_rules(scope="button.behavior")
+    targets = collect_targets(paths, (".apx",))
+    if not targets:
+        targets = sorted((ROOT / "applications").rglob("*.apx"))
+
+    issues: list[str] = []
+    for target in targets:
+        issues.extend(lint_button_rules(target, rules))
+
+    if issues:
+        print("APX_BUTTON_RULE_FAILED")
+        for issue in issues:
+            print(" -", issue)
+        return 1
+
+    print("APX_BUTTON_RULE_OK")
+    return 0
+
+
+def run_chart_rule_lint(paths: list[str]) -> int:
+    """Run chart-series policy linting and print all discovered issues."""
+    targets = collect_targets(paths, (".apx",))
+    if not targets:
+        targets = sorted((ROOT / "applications").rglob("*.apx"))
+
+    issues: list[str] = []
+    for target in targets:
+        issues.extend(lint_chart_series_rules(target))
+
+    if issues:
+        print("APX_CHART_RULE_FAILED")
+        for issue in issues:
+            print(" -", issue)
+        return 1
+
+    print("APX_CHART_RULE_OK")
+    return 0
+
+
+def main(argv: list[str]) -> int:
+    """Dispatch validation, button, or chart-series lint modes from CLI arguments."""
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--apx-button-rules", action="store_true", help="Lint APEX button behavior rules")
+    parser.add_argument("--apx-chart-rules", action="store_true", help="Lint APEX chart series execution rules")
+    parser.add_argument("--report-path", default=str(DEFAULT_REPORT), help="Optional JSON report output path.")
+    parser.add_argument("paths", nargs="*", help="Files or directories to lint")
+    args = parser.parse_args(argv)
+
+    if args.apx_button_rules:
+        return run_button_rule_lint(args.paths)
+    if args.apx_chart_rules:
+        return run_chart_rule_lint(args.paths)
+    return run_validation_lint(args.paths, report_path=args.report_path)
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))