@scemoon/cdh 1.0.9 → 1.0.10-beta.1

package/cdh/validators/ears.py

@@ -1,452 +0,0 @@
-import re
-from pathlib import Path
-
-_EARS_PATTERNS = [
-    ("ubiquitous", r"the\s+system\s+SHALL"),
-    ("event-driven", r"When\s+.+,\s+(the\s+)?\w+\s+SHALL"),
-    ("state-driven", r"While\s+.+,\s+(the\s+)?\w+\s+SHALL"),
-    ("unwanted", r"If\s+.+,\s+(the\s+)?\w+\s+SHALL"),
-    ("optional", r"Where\s+.+,\s+(the\s+)?\w+\s+SHALL"),
-]
-
-_FR_ID_RE = re.compile(r"(\b[A-Z]{2,8}-FR-\d{3}\b)")
-
-_AMBIGUOUS_WORDS = ["should", "may", "might", "could", "would", "perhaps", "maybe"]
-
-_SHALL_RE = re.compile(r"\bSHALL\b", re.IGNORECASE)
-_AMBIGUOUS_RE = re.compile(
-    r"\b(" + "|".join(_AMBIGUOUS_WORDS) + r")\b", re.IGNORECASE
-)
-
-# ── MUSUBI axiom patterns ──
-
-# 1. Atomicity: detect "and" / "or" in the condition clause of event/state/unwanted/optional forms.
-#    Captures the trigger clause between the keyword and the SHALL.
-_ATOMIC_EVENT_RE = re.compile(
-    r"\bWhen\s+(?P<trigger>.+?),\s+(?:the\s+)?\w+\s+SHALL", re.IGNORECASE
-)
-_ATOMIC_STATE_RE = re.compile(
-    r"\bWhile\s+(?P<trigger>.+?),\s+(?:the\s+)?\w+\s+SHALL", re.IGNORECASE
-)
-_ATOMIC_UNWANTED_RE = re.compile(
-    r"\bIf\s+(?P<trigger>.+?),\s+(?:the\s+)?\w+\s+SHALL", re.IGNORECASE
-)
-_ATOMIC_OPTIONAL_RE = re.compile(
-    r"\bWhere\s+(?P<trigger>.+?),\s+(?:the\s+)?\w+\s+SHALL", re.IGNORECASE
-)
-_ATOMIC_CONJUNCTION_RE = re.compile(
-    r"\s+(?:and|or)\s+", re.IGNORECASE
-)
-
-# 2. Observability: unverifiable internal-only verbs.
-_OBSERVABILITY_VERBS = ["think about", "know that", "intend to", "believe", "feel", "understand that"]
-_OBSERVABILITY_RE = re.compile(
-    r"\bthe\s+system\s+SHALL\s+(?:" + "|".join(_OBSERVABILITY_VERBS) + r")\b",
-    re.IGNORECASE,
-)
-
-# 3. Modal clarity: SHALL mixed with weaker modality.
-_MODAL_CLARITY_PATTERNS = [
-    (r"\bthe\s+system\s+SHALL\s+try\s+to\b", "try to"),
-    (r"\bthe\s+system\s+SHALL\s+attempt\s+to\b", "attempt to"),
-    (r"\bthe\s+system\s+SHALL\s+be\s+able\s+to\b", "be able to"),
-    (r"\bthe\s+system\s+SHOULD\s+ensure\b", "SHOULD ensure"),
-    (r"\bSHALL\s+(?:try|attempt|strive)\b", "weaker verb after SHALL"),
-]
-
-# 4. Quantifier: ubiquitous "the system SHALL <verb>" without explicit scope.
-#    Catches bare action verbs without "all/each/every/for" quantifier or clear object.
-_QUANTIFIER_BARE_VERBS = [
-    "respond",
-    "validate",
-    "process",
-    "handle",
-    "manage",
-    "support",
-    "provide",
-    "perform",
-    "execute",
-    "send",
-    "receive",
-]
-_QUANTIFIER_BARE_RE = re.compile(
-    r"\bthe\s+system\s+SHALL\s+(" + "|".join(_QUANTIFIER_BARE_VERBS) + r")\b(?!\s+(?:all|each|every|for|to|from|with|that|which|when|where|if))",
-    re.IGNORECASE,
-)
-
-# 5. Negative capability: bare "SHALL NOT" is non-EARS — use "If <unwanted>, the system SHALL ...".
-_SHALL_NOT_RE = re.compile(r"\bSHALL\s+NOT\b", re.IGNORECASE)
-
-
-def _parse_yaml_frontmatter(text: str) -> tuple[dict | None, str]:
-    """Parse YAML frontmatter from markdown. Returns (parsed_dict, body_text)."""
-    if not text.startswith("---"):
-        return None, text
-    end = text.find("---", 3)
-    if end == -1:
-        return None, text
-    fm_text = text[3:end].strip()
-    body = text[end + 3:].lstrip("\n")
-    fm: dict = {}
-    for line in fm_text.split("\n"):
-        line = line.strip()
-        if ":" in line:
-            key, _, val = line.partition(":")
-            fm[key.strip()] = val.strip().strip('"').strip("'")
-    return fm, body
-
-
-def _find_spec_deltas(root: Path) -> list[Path]:
-    changes_dir = root / "aidlc" / "openspec" / "changes"
-    if not changes_dir.exists():
-        return []
-    return sorted(changes_dir.rglob("spec-delta.md"))
-
-
-def _check_atomicity(body_lines: list[str], path: Path) -> list[dict]:
-    """MUSUBI axiom: detect compound conditions using and/or in EARS triggers."""
-    checks: list[dict] = []
-    flagged = False
-    for i, line in enumerate(body_lines, 1):
-        stripped = line.strip()
-        if not stripped or stripped.startswith("#"):
-            continue
-        for label, regex in (
-            ("event-driven", _ATOMIC_EVENT_RE),
-            ("state-driven", _ATOMIC_STATE_RE),
-            ("unwanted", _ATOMIC_UNWANTED_RE),
-            ("optional", _ATOMIC_OPTIONAL_RE),
-        ):
-            m = regex.search(stripped)
-            if not m:
-                continue
-            trigger = m.group("trigger")
-            # Only flag when the conjunction is inside the trigger clause, not the
-            # response clause (we already split on the first comma before SHALL).
-            if _ATOMIC_CONJUNCTION_RE.search(trigger):
-                flagged = True
-                conjunction = re.search(_ATOMIC_CONJUNCTION_RE, trigger).group(0).strip()
-                checks.append({
-                    "name": "ears-axiom-atomicity",
-                    "status": "warn",
-                    "message": (
-                        f"Line {i}: non-atomic {label} condition — '{conjunction}' joins multiple "
-                        f"triggers in \"{stripped[:100]}\". Split into separate FRs."
-                    ),
-                    "file": str(path),
-                    "line": i,
-                })
-    if not flagged:
-        checks.append({
-            "name": "ears-axiom-atomicity",
-            "status": "pass",
-            "message": "All EARS triggers are atomic (no 'and'/'or' in condition clauses)",
-            "file": str(path),
-        })
-    return checks
-
-
-def _check_observability(body_lines: list[str], path: Path) -> list[dict]:
-    """MUSUBI axiom: detect unverifiable internal-state verbs."""
-    checks: list[dict] = []
-    flagged = False
-    for i, line in enumerate(body_lines, 1):
-        stripped = line.strip()
-        if not stripped or stripped.startswith("#"):
-            continue
-        m = _OBSERVABILITY_RE.search(stripped)
-        if m:
-            flagged = True
-            verb = m.group(0).split("SHALL", 1)[1].strip()
-            checks.append({
-                "name": "ears-axiom-observability",
-                "status": "warn",
-                "message": (
-                    f"Line {i}: unverifiable requirement — 'SHALL {verb}' is an internal state "
-                    f"that cannot be empirically tested. Rephrase as an externally observable action "
-                    f"in: \"{stripped[:100]}\""
-                ),
-                "file": str(path),
-                "line": i,
-            })
-    if not flagged:
-        checks.append({
-            "name": "ears-axiom-observability",
-            "status": "pass",
-            "message": "All SHALL statements describe externally observable behaviour",
-            "file": str(path),
-        })
-    return checks
-
-
-def _check_modal_clarity(body_lines: list[str], path: Path) -> list[dict]:
-    """MUSUBI axiom: detect SHALL combined with weaker modality."""
-    checks: list[dict] = []
-    flagged = False
-    for i, line in enumerate(body_lines, 1):
-        stripped = line.strip()
-        if not stripped or stripped.startswith("#"):
-            continue
-        for pattern, label in _MODAL_CLARITY_PATTERNS:
-            if re.search(pattern, stripped, re.IGNORECASE):
-                flagged = True
-                checks.append({
-                    "name": "ears-axiom-modal-clarity",
-                    "status": "warn",
-                    "message": (
-                        f"Line {i}: ambiguous modality — '{label}' mixed with SHALL in: "
-                        f"\"{stripped[:100]}\". Use SHALL alone or replace with a weaker keyword "
-                        f"throughout."
-                    ),
-                    "file": str(path),
-                    "line": i,
-                })
-    if not flagged:
-        checks.append({
-            "name": "ears-axiom-modal-clarity",
-            "status": "pass",
-            "message": "No SHALL/weaker-modality mixing detected",
-            "file": str(path),
-        })
-    return checks
-
-
-def _check_quantifier(body_lines: list[str], path: Path) -> list[dict]:
-    """MUSUBI axiom: detect ubiquitous SHALL statements missing scope/quantifier."""
-    checks: list[dict] = []
-    flagged = False
-    for i, line in enumerate(body_lines, 1):
-        stripped = line.strip()
-        if not stripped or stripped.startswith("#"):
-            continue
-        # Only apply to ubiquitous form ("the system SHALL <bare-verb>") so we
-        # don't flag condition-bearing forms (event/state/unwanted/optional)
-        # which already imply scope via their trigger.
-        if not re.match(r"^\s*the\s+system\s+SHALL\b", stripped, re.IGNORECASE):
-            continue
-        if _QUANTIFIER_BARE_RE.search(stripped):
-            flagged = True
-            verb_match = re.search(
-                r"\bthe\s+system\s+SHALL\s+(\w+)", stripped, re.IGNORECASE
-            )
-            verb = verb_match.group(1) if verb_match else "<verb>"
-            checks.append({
-                "name": "ears-axiom-quantifier",
-                "status": "warn",
-                "message": (
-                    f"Line {i}: missing quantifier/scope — 'SHALL {verb}' does not specify "
-                    f"what/who/each/all. Add explicit scope (e.g. 'SHALL {verb} each <object>') "
-                    f"in: \"{stripped[:100]}\""
-                ),
-                "file": str(path),
-                "line": i,
-            })
-    if not flagged:
-        checks.append({
-            "name": "ears-axiom-quantifier",
-            "status": "pass",
-            "message": "Ubiquitous SHALL statements declare explicit scope",
-            "file": str(path),
-        })
-    return checks
-
-
-def _check_negative_capability(body_lines: list[str], path: Path) -> list[dict]:
-    """MUSUBI axiom: detect bare 'SHALL NOT' (non-EARS)."""
-    checks: list[dict] = []
-    flagged = False
-    for i, line in enumerate(body_lines, 1):
-        stripped = line.strip()
-        if not stripped or stripped.startswith("#"):
-            continue
-        if _SHALL_NOT_RE.search(stripped):
-            # EARS allows "If <unwanted>, the system SHALL <response>" — only
-            # flag when the line does not also contain that wanted-shape.
-            has_unwanted_shape = re.search(
-                r"\bIf\s+.+,\s+(?:the\s+)?\w+\s+SHALL\b", stripped, re.IGNORECASE
-            )
-            if not has_unwanted_shape:
-                flagged = True
-                checks.append({
-                    "name": "ears-axiom-negative-capability",
-                    "status": "warn",
-                    "message": (
-                        f"Line {i}: bare 'SHALL NOT' is non-EARS — rephrase as "
-                        f"'If <unwanted condition>, the system SHALL <response>' in: "
-                        f"\"{stripped[:100]}\""
-                    ),
-                    "file": str(path),
-                    "line": i,
-                })
-    if not flagged:
-        checks.append({
-            "name": "ears-axiom-negative-capability",
-            "status": "pass",
-            "message": "Negatives expressed via EARS unwanted-form (no bare SHALL NOT)",
-            "file": str(path),
-        })
-    return checks
-
-
-def _check_file(path: Path) -> list[dict]:
-    checks = []
-    try:
-        text = path.read_text(encoding="utf-8")
-    except Exception as e:
-        return [{"name": "read-error", "status": "fail", "message": str(e), "file": str(path)}]
-
-    lines = text.split("\n")
-    seen_shall = False
-    seen_pattern = set()
-    ambiguous_lines = []
-    fr_ids = []
-
-    fm, body_text = _parse_yaml_frontmatter(text)
-    body_lines = body_text.split("\n")
-
-    # ── Frontmatter validation ──
-    if fm is not None:
-        fid = fm.get("id", "")
-        if _FR_ID_RE.match(fid):
-            fr_ids.append(fid)
-            checks.append({
-                "name": "ears-frontmatter-id",
-                "status": "pass",
-                "message": f"Frontmatter declares FR id: {fid}",
-                "file": str(path),
-            })
-        else:
-            checks.append({
-                "name": "ears-frontmatter-id",
-                "status": "warn",
-                "message": f"Frontmatter id '{fid}' does not match FR id pattern (e.g. WEB-FR-001)" if fid else "No 'id' field in frontmatter",
-                "file": str(path),
-            })
-        for req_field in ["title", "status"]:
-            if req_field not in fm:
-                checks.append({
-                    "name": "ears-frontmatter-field",
-                    "status": "warn",
-                    "message": f"Missing frontmatter field: '{req_field}'",
-                    "file": str(path),
-                })
-        if fm.get("status") not in ("draft", "review", "approved", "implemented"):
-            checks.append({
-                "name": "ears-frontmatter-status",
-                "status": "warn",
-                "message": f"Frontmatter status '{fm.get('status', '')}' should be one of: draft, review, approved, implemented",
-                "file": str(path),
-            })
-    else:
-        checks.append({
-            "name": "ears-frontmatter",
-            "status": "warn",
-            "message": "No YAML frontmatter found — FR metadata should be declared at the top of the spec-delta",
-            "file": str(path),
-        })
-
-    for i, line in enumerate(body_lines, 1):
-        stripped = line.strip()
-        if not stripped or stripped.startswith("#"):
-            continue
-
-        match = _FR_ID_RE.search(stripped)
-        if match:
-            fr_ids.append(match.group(1))
-
-        if _SHALL_RE.search(stripped):
-            seen_shall = True
-
-        for pname, p_re in _EARS_PATTERNS:
-            if re.search(p_re, stripped, re.IGNORECASE):
-                seen_pattern.add(pname)
-
-        if _AMBIGUOUS_RE.search(stripped):
-            for w in _AMBIGUOUS_WORDS:
-                if re.search(rf"\b{w}\b", stripped, re.IGNORECASE):
-                    ambiguous_lines.append((i, w, stripped[:80]))
-
-    if not fm and not seen_shall:
-        checks.append({
-            "name": "ears-shall-keyword",
-            "status": "fail",
-            "message": "No requirement uses SHALL keyword — EARS requires SHALL for all functional requirements",
-            "file": str(path),
-        })
-    elif seen_shall:
-        checks.append({
-            "name": "ears-shall-keyword",
-            "status": "pass",
-            "message": "SHALL keyword found in spec delta",
-            "file": str(path),
-        })
-
-    if not seen_pattern:
-        if fm:
-            checks.append({
-                "name": "ears-pattern",
-                "status": "warn",
-                "message": "No recognized EARS pattern (ubiquitous/event-driven/state-driven/unwanted/optional) detected in body",
-                "file": str(path),
-            })
-    else:
-        checks.append({
-            "name": "ears-pattern",
-            "status": "pass",
-            "message": f"Detected EARS patterns: {', '.join(sorted(seen_pattern))}",
-            "file": str(path),
-        })
-
-    # ── FR ID cross-reference check ──
-    if len(fr_ids) >= 2:
-        checks.append({
-            "name": "ears-fr-reference",
-            "status": "pass",
-            "message": f"Cross-references FRs: {', '.join(sorted(set(fr_ids)))}",
-            "file": str(path),
-        })
-
-    if ambiguous_lines:
-        for line_no, word, snippet in ambiguous_lines:
-            checks.append({
-                "name": "ears-ambiguous-word",
-                "status": "warn",
-                "message": f"Line {line_no}: ambiguous word '{word}' in: \"{snippet}\"",
-                "file": str(path),
-                "line": line_no,
-            })
-    else:
-        checks.append({
-            "name": "ears-ambiguous-word",
-            "status": "pass",
-            "message": "No ambiguous terms found",
-        })
-
-    # ── MUSUBI axiom checks (warn-level) ──
-    checks.extend(_check_atomicity(body_lines, path))
-    checks.extend(_check_observability(body_lines, path))
-    checks.extend(_check_modal_clarity(body_lines, path))
-    checks.extend(_check_quantifier(body_lines, path))
-    checks.extend(_check_negative_capability(body_lines, path))
-
-    return checks
-
-
-def run_ears_check(root: Path) -> dict:
-    spec_deltas = _find_spec_deltas(root)
-    if not spec_deltas:
-        return {
-            "passed": False,
-            "checks": [{
-                "name": "ears-spec-found",
-                "status": "fail",
-                "message": "No spec-delta.md found under aidlc/openspec/changes/",
-            }],
-        }
-
-    all_checks = []
-    for sd in spec_deltas:
-        all_checks.extend(_check_file(sd))
-
-    passed = all(c["status"] == "pass" for c in all_checks)
-    return {"passed": passed, "checks": all_checks}

package/cdh/validators/fr_namespace.py

@@ -1,143 +0,0 @@
-from __future__ import annotations
-
-import re
-from pathlib import Path
-
-import yaml
-
-_FR_TAG_RE = re.compile(r"@(?P<prefix>[A-Z]+)-FR-(?P<number>\d+)")
-_FR_REF_RE = re.compile(
-    r"(?P<prefix>[A-Z]+)-FR-(?P<number>\d+)",
-)
-
-
-def _load_project_yaml(root: Path) -> dict | None:
-    p = root / "aidlc" / "project.yaml"
-    if not p.exists():
-        return None
-    try:
-        return yaml.safe_load(p.read_text(encoding="utf-8"))
-    except Exception:
-        return None
-
-
-def _build_fr_map(project: dict) -> dict[str, str]:
-    fr_map = {}
-    components = project.get("stack", {}).get("components", [])
-    for c in components:
-        prefix = c.get("fr_prefix", "")
-        if prefix:
-            fr_map[prefix] = c.get("owns", "?")
-    cross = project.get("stack", {}).get("cross_cutting", {})
-    if cross:
-        fr_map["INT"] = "aidlc/contracts/ + aidlc/packages/shared/"
-    return fr_map
-
-
-def _collect_fr_from_spec(root: Path) -> set[str]:
-    changes_dir = root / "aidlc" / "openspec" / "changes"
-    if not changes_dir.exists():
-        return set()
-    frs = set()
-    for spec_file in changes_dir.rglob("spec-delta.md"):
-        text = spec_file.read_text(encoding="utf-8")
-        for m in _FR_REF_RE.finditer(text):
-            frs.add(f"{m.group('prefix')}-FR-{m.group('number')}")
-    return frs
-
-
-def _collect_fr_from_features(root: Path) -> dict[str, set[str]]:
-    frs_by_tag = {}
-    for feature_file in Path(root).rglob("*.feature"):
-        text = feature_file.read_text(encoding="utf-8")
-        for m in _FR_TAG_RE.finditer(text):
-            fr = f"{m.group('prefix')}-FR-{m.group('number')}"
-            tag = m.group(0)
-            frs_by_tag.setdefault(tag, set()).add(fr)
-    all_frs = set()
-    for fr_set in frs_by_tag.values():
-        all_frs.update(fr_set)
-    return all_frs, frs_by_tag
-
-
-def run_fr_check(root: Path) -> dict:
-    checks = []
-
-    project = _load_project_yaml(root)
-    if project is None:
-        return {
-            "passed": False,
-            "checks": [{
-                "name": "fr-project-yaml",
-                "status": "fail",
-                "message": "aidlc/project.yaml not found",
-            }],
-        }
-
-    fr_map = _build_fr_map(project)
-    if not fr_map:
-        checks.append({
-            "name": "fr-prefix-defined",
-            "status": "fail",
-            "message": "No FR prefixes defined in project.yaml stack.components",
-        })
-        return {"passed": False, "checks": checks}
-
-    spec_frs = _collect_fr_from_spec(root)
-    feature_frs, frs_by_tag = _collect_fr_from_features(root)
-
-    if not spec_frs and not feature_frs:
-        return {
-            "passed": True,
-            "checks": [{
-                "name": "fr-skip",
-                "status": "pass",
-                "message": "No FR references found yet (project may be empty)",
-            }],
-        }
-
-    unknown_prefixes = set()
-    for fr in spec_frs | feature_frs:
-        prefix = fr.split("-")[0]
-        if prefix not in fr_map:
-            unknown_prefixes.add(prefix)
-
-    if unknown_prefixes:
-        checks.append({
-            "name": "fr-unknown-prefix",
-            "status": "fail",
-            "message": f"FR prefixes not in project.yaml: {', '.join(sorted(unknown_prefixes))}",
-        })
-    else:
-        checks.append({
-            "name": "fr-unknown-prefix",
-            "status": "pass",
-            "message": "All FR prefixes are defined in project.yaml",
-        })
-
-    spec_only = spec_frs - feature_frs
-    feature_only = feature_frs - spec_frs
-
-    if spec_only:
-        checks.append({
-            "name": "fr-spec-without-feature",
-            "status": "warn",
-            "message": f"FRs in spec-delta but not in any .feature file: {', '.join(sorted(spec_only))}",
-        })
-
-    if feature_only:
-        checks.append({
-            "name": "fr-feature-without-spec",
-            "status": "warn",
-            "message": f"FRs in .feature files but not in spec-delta: {', '.join(sorted(feature_only))}",
-        })
-
-    if not spec_only and not feature_only:
-        checks.append({
-            "name": "fr-consistency",
-            "status": "pass",
-            "message": f"All {len(spec_frs)} FRs are consistent between spec and feature files",
-        })
-
-    has_fail = any(c["status"] == "fail" for c in checks)
-    return {"passed": not has_fail, "checks": checks}