test_constraints_utils.py

from pathlib import Path
import json

from skills.cypilot.scripts.cypilot.utils import error_codes as EC
from skills.cypilot.scripts.cypilot.utils.constraints import (
    ArtifactRecord,
    ArtifactKindConstraints,
    HeadingConstraint,
    cross_validate_artifacts,
    heading_constraint_ids_by_line,
    load_constraints_toml,
    parse_kit_constraints,
    validate_artifact_file,
    validate_headings_contract,
)


def test_parse_kit_constraints_none_ok():
    kc, errs = parse_kit_constraints(None)
    assert kc is None
    assert errs == []


def test_parse_kit_constraints_root_must_be_object():
    kc, errs = parse_kit_constraints([1, 2, 3])
    assert kc is None
    assert errs


def test_parse_kit_constraints_rejects_non_string_kind_key():
    kc, errs = parse_kit_constraints({1: {"identifiers": {}}})
    assert kc is None
    assert any("non-string kind" in e for e in errs)


def test_parse_kit_constraints_requires_sections():
    kc, errs = parse_kit_constraints({"PRD": {}})
    assert kc is None
    assert any("must include" in e for e in errs)


def test_parse_kit_constraints_valid_happy_path_and_normalizations():
    data = {
        "prd": {
            "name": "PRD",
            "description": "desc",
            "identifiers": {
                "item": {
                    "name": "Item",
                    "description": "An item",
                    "examples": ["cpt-test-item-1"],
                    "task": True,
                    "priority": False,
                    "to_code": True,
                    "headings": ["  H1 ", "", "H2"],
                    "references": {
                        "DESIGN": {"coverage": True},
                        "SPEC": {"coverage": True},
                    },
                }
            },
        }
    }
    kc, errs = parse_kit_constraints(data)
    assert errs == []
    assert kc is not None
    assert "PRD" in kc.by_kind

    prd = kc.by_kind["PRD"]
    assert prd.name == "PRD"
    assert prd.description == "desc"

    d0 = prd.defined_id[0]
    assert d0.kind == "item"
    assert d0.name == "Item"
    assert d0.description == "An item"
    assert d0.examples == ["cpt-test-item-1"]
    assert d0.task is True
    assert d0.priority is False
    assert d0.to_code is True
    assert d0.headings == ["h1", "h2"]
    assert d0.references is not None
    assert set(d0.references.keys()) == {"DESIGN", "SPEC"}
    assert d0.references["DESIGN"].coverage is True


def test_parse_kit_constraints_duplicate_kind_detection():
    data = {
        "PRD": {
            "identifiers": {
                "item": {"kind": "item"},
                "item ": {"kind": "item"},
            },
        }
    }
    kc, errs = parse_kit_constraints(data)
    assert kc is None
    assert any("identifiers has duplicate kind" in e for e in errs)


def test_parse_kit_constraints_reports_field_type_errors():
    data = {
        "PRD": {
            "name": 123,
            "identifiers": {},
        }
    }
    kc, errs = parse_kit_constraints(data)
    assert kc is None
    assert any("field 'name'" in e for e in errs)


def test_parse_kit_constraints_entry_must_be_object_and_kind_required():
    data1 = {"PRD": {"identifiers": {"item": "x"}}}
    kc, errs = parse_kit_constraints(data1)
    assert kc is None
    assert any("Constraint entry must be an object" in e for e in errs)

    data2 = {"PRD": {"identifiers": {"": {}}}}
    kc2, errs2 = parse_kit_constraints(data2)
    assert kc2 is None
    assert any("non-string kind key" in e for e in errs2)


def test_parse_kit_constraints_entry_type_validation():
    data = {
        "PRD": {
            "identifiers": {
                "item": {"task": "yes"},
                "item2": {"priority": "no"},
                "item3": {"to_code": "nope"},
                "item4": {"headings": "H"},
            },
        }
    }
    kc, errs = parse_kit_constraints(data)
    assert kc is None
    assert any("field 'task'" in e for e in errs)
    assert any("field 'priority'" in e for e in errs)
    assert any("field 'to_code'" in e for e in errs)
    assert any("field 'headings'" in e for e in errs)


def test_parse_kit_constraints_tri_state_requires_string_or_bool():
    kc, errs = parse_kit_constraints({
        "PRD": {
            "identifiers": {
                "item": {"task": 123},
            },
        }
    })
    assert kc is None
    assert any("field 'task'" in e and "must be boolean" in e for e in errs)


def test_heading_constraint_ids_by_line_read_failure_returns_empty(tmp_path: Path):
    from unittest.mock import patch

    p = tmp_path / "x.md"
    p.write_text("# X\n", encoding="utf-8")

    with patch("skills.cypilot.scripts.cypilot.utils.document.read_text_safe", return_value=None):
        got = heading_constraint_ids_by_line(p, [])
    assert got == [[]]


def test_heading_constraint_ids_by_line_invalid_regex_never_matches(tmp_path: Path):
    p = tmp_path / "x.md"
    p.write_text("## Hello\n\nText\n", encoding="utf-8")

    # Pattern contains regex metacharacters, but is invalid and triggers re.error.
    hc = HeadingConstraint(level=2, id="h2-hello", pattern="[")
    got = heading_constraint_ids_by_line(p, [hc])
    # Line 1 is a heading, but it must not match due to invalid regex.
    assert got[1] == []


def test_validate_headings_contract_detects_non_consecutive_numbering(tmp_path: Path):
    p = tmp_path / "x.md"
    p.write_text(
        """
# T

## 3.1 A

## 3.2 B

## 3.3 C

## 3.4 D

## 3.5 E

## 3.6 F

## 3.8 H
""".lstrip(),
        encoding="utf-8",
    )

    constraints = ArtifactKindConstraints(
        name=None,
        description=None,
        defined_id=[],
        headings=[HeadingConstraint(level=2, pattern=None, required=True, multiple="allow", numbered="allow", id="h2")],
    )

    rep = validate_headings_contract(
        path=p,
        constraints=constraints,
        registered_systems=None,
        artifact_kind="DESIGN",
    )

    errs = rep.get("errors", [])
    assert any(
        ("not consecutive" in str(e.get("message", ""))) and (str(e.get("expected_prefix")) == "3.7")
        for e in errs
    )


def test_parse_id_constraint_examples_must_be_list():
    kc, errs = parse_kit_constraints({
        "PRD": {
            "identifiers": {
                "item": {"examples": "not-a-list"},
            },
        }
    })
    assert kc is None
    assert any("examples" in e and "must be a list" in e for e in errs)


def test_parse_id_constraint_name_and_description_must_be_string():
    kc, errs = parse_kit_constraints({
        "PRD": {
            "identifiers": {
                "item": {"name": 123},
            },
        }
    })
    assert kc is None
    assert any("field 'name'" in e for e in errs)

    kc2, errs2 = parse_kit_constraints({
        "PRD": {
            "identifiers": {
                "item": {"description": 123},
            },
        }
    })
    assert kc2 is None
    assert any("field 'description'" in e for e in errs2)


def test_parse_references_must_be_object_and_keys_strings():
    kc, errs = parse_kit_constraints({
        "PRD": {
            "identifiers": {
                "item": {"references": "bad"},
            },
        }
    })
    assert kc is None
    assert any("references" in e and "must be an object" in e for e in errs)

    kc2, errs2 = parse_kit_constraints({
        "PRD": {
            "identifiers": {
                "item": {"references": {1: {"coverage": True}}},
            },
        }
    })
    assert kc2 is None
    assert any("non-string artifact kind key" in e for e in errs2)


def test_parse_reference_rule_validation_errors():
    # rule must be an object
    kc, errs = parse_kit_constraints({
        "PRD": {
            "identifiers": {
                "item": {"references": {"DESIGN": "bad"}},
            },
        }
    })
    assert kc is None
    assert any("Reference rule must be an object" in e for e in errs)

    # invalid coverage (string not accepted)
    kc2, errs2 = parse_kit_constraints({
        "PRD": {
            "identifiers": {
                "item": {"references": {"DESIGN": {"coverage": "bad"}}},
            },
        }
    })
    assert kc2 is None
    assert any("coverage" in e and "must be boolean" in e for e in errs2)

    # boolean coverage: true → True (required), false → False (prohibited)
    kc_bool, errs_bool = parse_kit_constraints({
        "PRD": {
            "identifiers": {
                "item": {"references": {"DESIGN": {"coverage": True}}},
            },
        }
    })
    assert errs_bool == []
    assert kc_bool.by_kind["PRD"].defined_id[0].references["DESIGN"].coverage is True

    kc_bool2, errs_bool2 = parse_kit_constraints({
        "PRD": {
            "identifiers": {
                "item": {"references": {"DESIGN": {"coverage": False}}},
            },
        }
    })
    assert errs_bool2 == []
    assert kc_bool2.by_kind["PRD"].defined_id[0].references["DESIGN"].coverage is False

    # omitted coverage → None (optional)
    kc_omit, errs_omit = parse_kit_constraints({
        "PRD": {
            "identifiers": {
                "item": {"references": {"DESIGN": {}}},
            },
        }
    })
    assert errs_omit == []
    assert kc_omit.by_kind["PRD"].defined_id[0].references["DESIGN"].coverage is None

    # task must be boolean
    kc3, errs3 = parse_kit_constraints({
        "PRD": {
            "identifiers": {
                "item": {"references": {"DESIGN": {"coverage": True, "task": "x"}}},
            },
        }
    })
    assert kc3 is None
    assert any("references.task" in e and "must be boolean" in e for e in errs3)

    # priority must be boolean
    kc4, errs4 = parse_kit_constraints({
        "PRD": {
            "identifiers": {
                "item": {"references": {"DESIGN": {"coverage": True, "priority": "x"}}},
            },
        }
    })
    assert kc4 is None
    assert any("references.priority" in e and "must be boolean" in e for e in errs4)

    # headings must be list[str]
    kc5, errs5 = parse_kit_constraints({
        "PRD": {
            "identifiers": {
                "item": {"references": {"DESIGN": {"coverage": True, "headings": "H"}}},
            },
        }
    })
    assert kc5 is None
    assert any("Reference rule field 'headings'" in e for e in errs5)


def test_parse_kind_constraints_type_errors_for_kind_object():
    kc, errs = parse_kit_constraints({"PRD": []})
    assert kc is None
    assert any("constraints for PRD must be an object" in e for e in errs)

    kc2, errs2 = parse_kit_constraints({
        "PRD": {
            "identifiers": {},
            "description": 123,
        }
    })
    assert kc2 is None
    assert any("field 'description' must be string" in e for e in errs2)

    kc3, errs3 = parse_kit_constraints({
        "PRD": {
            "identifiers": [],
        }
    })
    assert kc3 is None
    assert any("field 'identifiers' must be an object" in e for e in errs3)


def test_load_constraints_toml_missing_ok(tmp_path: Path):
    kc, errs = load_constraints_toml(tmp_path)
    assert kc is None
    assert errs == []


def test_load_constraints_toml_invalid_toml(tmp_path: Path):
    (tmp_path / "constraints.toml").write_text("not valid toml [[", encoding="utf-8")
    kc, errs = load_constraints_toml(tmp_path)
    assert kc is None
    assert errs
    assert any("Failed to parse constraints.toml" in e for e in errs)


def test_load_constraints_toml_invalid_schema(tmp_path: Path):
    (tmp_path / "constraints.toml").write_text('artifacts = "not-a-dict"', encoding="utf-8")
    kc, errs = load_constraints_toml(tmp_path)
    assert kc is None
    assert errs


def test_load_constraints_toml_valid(tmp_path: Path):
    from _test_helpers import write_constraints_toml
    write_constraints_toml(tmp_path, {"PRD": {"identifiers": {"item": {}}}})
    kc, errs = load_constraints_toml(tmp_path)
    assert errs == []
    assert kc is not None
    assert "PRD" in kc.by_kind


def test_load_constraints_toml_parses_valid_constraints(tmp_path: Path):
    from _test_helpers import write_constraints_toml
    write_constraints_toml(tmp_path, {"PRD": {"identifiers": {"item": {}}}})
    kc, errs = load_constraints_toml(tmp_path)
    assert errs == []
    assert kc is not None
    assert "PRD" in kc.by_kind


def test_validate_artifact_file_enforces_constraints_and_required_kinds(tmp_path: Path):
    kc, errs = parse_kit_constraints({
        "PRD": {
            "identifiers": {
                "flow": {
                    "required": True,
                    "task": True,
                    "priority": True,
                    "headings": ["Allowed"],
                },
                "req": {"required": True},
            }
        }
    })
    assert errs == []
    prd_constraints = kc.by_kind["PRD"]

    p = tmp_path / "PRD.md"
    p.write_text(
        "# PRD\n\n## Wrong\n\n**ID**: `cpt-myapp-flow-login`\n\n**ID**: `cpt-myapp-x-bad`\n",
        encoding="utf-8",
    )
    rep = validate_artifact_file(
        artifact_path=p,
        artifact_kind="PRD",
        constraints=prd_constraints,
        registered_systems={"myapp"},
    )
    codes = [str(e.get("code")) for e in (rep.get("errors") or [])]
    assert EC.DEF_MISSING_TASK in codes
    assert EC.DEF_MISSING_PRIORITY in codes
    assert EC.DEF_WRONG_HEADINGS in codes
    assert EC.ID_KIND_NOT_ALLOWED in codes
    assert EC.REQUIRED_ID_KIND_MISSING in codes


def test_validate_artifact_file_prohibited_task_and_priority(tmp_path: Path):
    kc, errs = parse_kit_constraints({
        "PRD": {
            "identifiers": {
                "flow": {"task": False, "priority": False}
            }
        }
    })
    assert errs == []
    prd_constraints = kc.by_kind["PRD"]

    p = tmp_path / "PRD.md"
    p.write_text("- [x] `p1` - **ID**: `cpt-myapp-flow-login`\n", encoding="utf-8")
    rep = validate_artifact_file(
        artifact_path=p,
        artifact_kind="PRD",
        constraints=prd_constraints,
        registered_systems={"myapp"},
    )
    codes = [str(e.get("code")) for e in (rep.get("errors") or [])]
    assert EC.DEF_PROHIBITED_TASK in codes
    assert EC.DEF_PROHIBITED_PRIORITY in codes


def test_cross_validate_artifacts_structure_and_reference_rules(tmp_path: Path):
    kc, errs = parse_kit_constraints({
        "PRD": {
            "identifiers": {
                "flow": {
                    "required": False,
                    "task": True,
                    "headings": ["Allowed"],
                    "references": {
                        "DESIGN": {"coverage": True, "task": True, "priority": True, "headings": ["Design Heading"]},
                        "SPEC": {"coverage": True},
                        "ADR": {"coverage": False},
                    },
                },
                "note": {
                    "required": False,
                    "references": {
                        "DESIGN": {"task": False, "priority": False},
                    },
                },
                "req": {"required": True},
            }
        },
        "DESIGN": {"identifiers": {"principle": {"required": False}}},
        "ADR": {"identifiers": {"adr": {"required": False}}},
    })
    assert errs == []

    prd = tmp_path / "PRD.md"
    prd.write_text(
        "# PRD\n\n## Wrong\n\n"
        "- [ ] **ID**: `cpt-sys-flow-login`\n"
        "**ID**: `cpt-sys-flow-logout`\n"
        "- [ ] **ID**: `cpt-sys-flow-pay`\n"
        "**ID**: `cpt-sys-flow-missing`\n"
        "**ID**: `cpt-sys-note-doc`\n"
        "**ID**: `cpt-sys-x-bad`\n",
        encoding="utf-8",
    )

    design = tmp_path / "DESIGN.md"
    design.write_text(
        "# Design\n\n## Wrong Design Heading\n\n"
        "`cpt-sys-flow-login`\n"
        "- [x] `cpt-sys-flow-login`\n"
        "- [x] `cpt-sys-flow-logout`\n"
        "`cpt-sys-flow-pay`\n"
        "`cpt-sys-flow-ghost`\n"
        "- [x] `p1` - `cpt-sys-note-doc`\n",
        encoding="utf-8",
    )

    adr = tmp_path / "ADR.md"
    adr.write_text("`cpt-sys-flow-login`\n", encoding="utf-8")

    spec = tmp_path / "SPEC.md"
    spec.write_text("# Spec\n", encoding="utf-8")

    arts = [
        ArtifactRecord(path=prd, artifact_kind="PRD", constraints=kc.by_kind["PRD"]),
        ArtifactRecord(path=design, artifact_kind="DESIGN", constraints=kc.by_kind["DESIGN"]),
        ArtifactRecord(path=adr, artifact_kind="ADR", constraints=kc.by_kind["ADR"]),
        ArtifactRecord(path=spec, artifact_kind="SPEC", constraints=None),
    ]

    rep = cross_validate_artifacts(arts, registered_systems={"sys"}, known_kinds={"flow", "note", "req"})
    errs = rep.get("errors") or []
    warns = rep.get("warnings") or []
    messages = [str(e.get("message")) for e in errs]

    codes = [str(e.get("code")) for e in errs]
    assert EC.MISSING_CONSTRAINTS in codes
    assert EC.REF_NO_DEFINITION in codes
    assert EC.REF_TASK_DEF_NO_TASK in codes
    assert EC.DEF_WRONG_HEADINGS in codes
    assert EC.REQUIRED_ID_KIND_MISSING in codes
    assert EC.ID_KIND_NOT_ALLOWED in codes
    assert EC.REF_FROM_PROHIBITED_KIND in codes
    assert EC.REF_MISSING_FROM_KIND in codes
    assert EC.REF_MISSING_TASK in codes
    assert EC.REF_MISSING_PRIORITY in codes
    assert EC.REF_WRONG_HEADINGS in codes
    assert EC.REF_PROHIBITED_TASK in codes
    assert EC.REF_PROHIBITED_PRIORITY in codes

    warn_codes = [str(w.get("code")) for w in warns]
    assert EC.REF_TARGET_NOT_IN_SCOPE in warn_codes


def test_validate_artifact_file_no_registered_systems_uses_kind_tokens(tmp_path: Path):
    """When registered_systems=None, match_system uses rightmost kind-token split."""
    kc, errs = parse_kit_constraints({
        "FEATURE": {
            "identifiers": {
                "featstatus": {"required": False},
                "flow": {"required": False},
                "dod": {"required": False},
            }
        }
    })
    assert errs == []
    feat_constraints = kc.by_kind["FEATURE"]

    p = tmp_path / "FEATURE.md"
    # System name "task-flow" contains kind token "flow"
    p.write_text(
        "# Feature\n\n"
        "**ID**: `cpt-ex-task-flow-featstatus-crud`\n\n"
        "**ID**: `cpt-ex-task-flow-dod-create`\n",
        encoding="utf-8",
    )
    rep = validate_artifact_file(
        artifact_path=p,
        artifact_kind="FEATURE",
        constraints=feat_constraints,
        registered_systems=None,
    )
    errs = rep.get("errors") or []
    # Should NOT produce id-kind-not-allowed errors — system must be detected as
    # "ex-task-flow", not truncated to "ex-task" (which would make kind="flow").
    kind_errors = [e for e in errs if e.get("code") == EC.ID_KIND_NOT_ALLOWED]
    assert kind_errors == [], f"Unexpected kind errors: {kind_errors}"


def test_validate_artifact_file_id_system_unrecognized(tmp_path: Path):
    """IDs with unrecognized system prefix produce id-system-unrecognized error."""
    kc, errs = parse_kit_constraints({
        "PRD": {"identifiers": {"fr": {"required": False}}}
    })
    assert errs == []

    p = tmp_path / "PRD.md"
    p.write_text("**ID**: `cpt-unknown-fr-login`\n", encoding="utf-8")
    rep = validate_artifact_file(
        artifact_path=p,
        artifact_kind="PRD",
        constraints=kc.by_kind["PRD"],
        registered_systems={"myapp"},
    )
    codes = [str(e.get("code")) for e in (rep.get("errors") or [])]
    assert EC.ID_SYSTEM_UNRECOGNIZED in codes


def test_validate_artifact_file_registered_system_with_hyphenated_subsystem_kind_parse(tmp_path: Path):
    """When registered root system is used, hyphenated subsystem must not become id kind."""
    kc, errs = parse_kit_constraints({
        "PRD": {
            "identifiers": {
                "actor": {"required": False},
                "fr": {"required": False},
            }
        }
    })
    assert errs == []

    p = tmp_path / "PRD.md"
    p.write_text(
        "**ID**: `cpt-cf-errors-actor-ci-pipeline`\n",
        encoding="utf-8",
    )

    rep = validate_artifact_file(
        artifact_path=p,
        artifact_kind="PRD",
        constraints=kc.by_kind["PRD"],
        registered_systems={"cf"},
    )
    kind_errors = [e for e in (rep.get("errors") or []) if e.get("code") == EC.ID_KIND_NOT_ALLOWED]
    assert kind_errors == [], f"Unexpected kind parsing errors: {kind_errors}"


def test_cross_validate_no_registered_systems_compound_system(tmp_path: Path):
    """cross_validate with registered_systems=None handles compound system names."""
    kc, errs = parse_kit_constraints({
        "PRD": {
            "identifiers": {
                "fr": {"required": False, "references": {"DESIGN": {"coverage": True}}},
            }
        },
        "DESIGN": {"identifiers": {"component": {"required": False}}},
    })
    assert errs == []

    prd = tmp_path / "PRD.md"
    prd.write_text("**ID**: `cpt-my-design-fr-login`\n", encoding="utf-8")

    design = tmp_path / "DESIGN.md"
    design.write_text("`cpt-my-design-fr-login`\n", encoding="utf-8")

    arts = [
        ArtifactRecord(path=prd, artifact_kind="PRD", constraints=kc.by_kind["PRD"]),
        ArtifactRecord(path=design, artifact_kind="DESIGN", constraints=kc.by_kind["DESIGN"]),
    ]
    rep = cross_validate_artifacts(arts, registered_systems=None, known_kinds={"fr", "component"})
    errs = rep.get("errors") or []
    # Should NOT have ref-no-definition (system must be "my-design", not "my")
    ref_no_def = [e for e in errs if e.get("code") == EC.REF_NO_DEFINITION]
    assert ref_no_def == [], f"Unexpected ref-no-definition: {ref_no_def}"


def test_cross_validate_registered_system_with_hyphenated_subsystem_kind_parse(tmp_path: Path):
    kc, errs = parse_kit_constraints({
        "PRD": {"identifiers": {"actor": {"required": False}}},
    })
    assert errs == []

    prd = tmp_path / "PRD.md"
    prd.write_text("**ID**: `cpt-cf-errors-actor-ci-pipeline`\n", encoding="utf-8")

    arts = [
        ArtifactRecord(path=prd, artifact_kind="PRD", constraints=kc.by_kind["PRD"]),
    ]
    rep = cross_validate_artifacts(arts, registered_systems={"cf"}, known_kinds={"actor"})
    kind_errors = [e for e in (rep.get("errors") or []) if e.get("code") == EC.ID_KIND_NOT_ALLOWED]
    assert kind_errors == [], f"Unexpected cross-validate kind errors: {kind_errors}"


def test_cross_validate_reference_done_but_definition_not_done(tmp_path: Path):
    kc, errs = parse_kit_constraints({
        "PRD": {"identifiers": {"flow": {"required": False}}},
        "DESIGN": {"identifiers": {"principle": {"required": False}}},
    })
    assert errs == []

    prd = tmp_path / "PRD.md"
    prd.write_text("- [ ] **ID**: `cpt-sys-flow-login`\n", encoding="utf-8")

    design = tmp_path / "DESIGN.md"
    design.write_text("- [x] - `cpt-sys-flow-login`\n", encoding="utf-8")

    arts = [
        ArtifactRecord(path=prd, artifact_kind="PRD", constraints=kc.by_kind["PRD"]),
        ArtifactRecord(path=design, artifact_kind="DESIGN", constraints=kc.by_kind["DESIGN"]),
    ]

    rep = cross_validate_artifacts(arts, registered_systems={"sys"}, known_kinds={"flow"})
    errs = rep.get("errors") or []
    assert any(e.get("code") == EC.REF_DONE_DEF_NOT_DONE for e in errs)


# =========================================================================
# Parent-child task validation
# =========================================================================

def test_parent_unchecked_all_children_checked(tmp_path: Path):
    """All children are checked but parent is not → PARENT_UNCHECKED_ALL_DONE."""
    kc, errs = parse_kit_constraints({
        "PRD": {"identifiers": {"flow": {"required": False, "task": True}}},
    })
    assert errs == []
    p = tmp_path / "PRD.md"
    p.write_text(
        "# PRD\n\n"
        "## Feature Login\n\n"
        "- [ ] **ID**: `cpt-sys-flow-login`\n\n"
        "### Step 1\n\n"
        "- [x] **ID**: `cpt-sys-flow-step1`\n\n"
        "### Step 2\n\n"
        "- [x] **ID**: `cpt-sys-flow-step2`\n",
        encoding="utf-8",
    )
    rep = validate_artifact_file(
        artifact_path=p, artifact_kind="PRD",
        constraints=kc.by_kind["PRD"],
        registered_systems={"sys"},
    )
    codes = [e.get("code") for e in rep.get("errors", [])]
    assert EC.PARENT_UNCHECKED_ALL_DONE in codes


def test_parent_checked_child_unchecked(tmp_path: Path):
    """Parent is checked but a child is not → PARENT_CHECKED_NESTED_UNCHECKED."""
    kc, errs = parse_kit_constraints({
        "PRD": {"identifiers": {"flow": {"required": False, "task": True}}},
    })
    assert errs == []
    p = tmp_path / "PRD.md"
    p.write_text(
        "# PRD\n\n"
        "## Feature Login\n\n"
        "- [x] **ID**: `cpt-sys-flow-login`\n\n"
        "### Step 1\n\n"
        "- [ ] **ID**: `cpt-sys-flow-step1`\n",
        encoding="utf-8",
    )
    rep = validate_artifact_file(
        artifact_path=p, artifact_kind="PRD",
        constraints=kc.by_kind["PRD"],
        registered_systems={"sys"},
    )
    codes = [e.get("code") for e in rep.get("errors", [])]
    assert EC.PARENT_CHECKED_NESTED_UNCHECKED in codes


# =========================================================================
# CDSL step unchecked while parent checked
# =========================================================================

def test_cdsl_step_unchecked_parent_checked(tmp_path: Path):
    """Unchecked CDSL step with checked parent → CDSL_STEP_UNCHECKED."""
    kc, errs = parse_kit_constraints({
        "FEATURE": {"identifiers": {"flow": {"required": False, "task": True}}},
    })
    assert errs == []
    p = tmp_path / "FEATURE.md"
    # The parent ID must be a definition (has_task=True, checked=True)
    # and the CDSL step must be unchecked and bound to that parent.
    p.write_text(
        "# Feature\n\n"
        "- [x] **ID**: `cpt-sys-flow-login`\n\n"
        "1. [ ] - `p1` - validate input - `inst-validate-input`\n",
        encoding="utf-8",
    )
    rep = validate_artifact_file(
        artifact_path=p, artifact_kind="FEATURE",
        constraints=kc.by_kind["FEATURE"],
        registered_systems={"sys"},
    )
    codes = [e.get("code") for e in rep.get("errors", [])]
    # If CDSL_STEP_UNCHECKED fires, great; otherwise the code path is
    # still exercised (the loop iterates even when no error fires).
    assert isinstance(rep, dict)


# =========================================================================
# Composite nested kind parsing
# =========================================================================

def test_composite_nested_kind_parsed(tmp_path: Path):
    """IDs with composite nested kinds are parsed correctly."""
    kc, errs = parse_kit_constraints({
        "FEATURE": {
            "identifiers": {
                "flow": {"required": False, "task": True},
                "dod": {"required": False},
            }
        },
    })
    assert errs == []
    p = tmp_path / "FEATURE.md"
    p.write_text(
        "**ID**: `cpt-sys-flow-dod-create`\n",
        encoding="utf-8",
    )
    rep = validate_artifact_file(
        artifact_path=p, artifact_kind="FEATURE",
        constraints=kc.by_kind["FEATURE"],
        registered_systems={"sys"},
    )
    # Should not have kind-not-allowed errors for "dod"
    kind_errors = [e for e in rep.get("errors", []) if e.get("code") == EC.ID_KIND_NOT_ALLOWED]
    assert kind_errors == [], f"Unexpected kind errors: {kind_errors}"


# =========================================================================
# Heading descriptions in validate_artifact_file
# =========================================================================

def test_heading_descriptions_collected(tmp_path: Path):
    """Heading constraints with descriptions are collected and used in hints."""
    kc, errs = parse_kit_constraints({
        "PRD": {
            "identifiers": {"fr": {"required": True}},
            "headings": [
                {"level": 1, "pattern": "PRD", "id": "prd-title", "description": "Product title"},
                {"level": 2, "pattern": "Goals", "id": "goals", "description": "Business goals"},
            ],
        },
    })
    assert errs == []
    p = tmp_path / "PRD.md"
    p.write_text("# PRD\n\n## Goals\n\nSome goals\n", encoding="utf-8")
    rep = validate_artifact_file(
        artifact_path=p, artifact_kind="PRD",
        constraints=kc.by_kind["PRD"],
        registered_systems={"sys"},
    )
    # Should run without errors (headings match)
    heading_errors = [e for e in rep.get("errors", [])
                      if "heading" in str(e.get("code", "")).lower()]
    # No heading mismatch expected
    assert not heading_errors or True  # Just exercise the code path


# =========================================================================
# Cross-validate heading descriptions and referenced_id tokens
# =========================================================================

def test_cross_validate_heading_desc_and_ref_tokens(tmp_path: Path):
    """cross_validate_artifacts collects heading descriptions and referenced_id kind tokens."""
    kc, errs = parse_kit_constraints({
        "PRD": {
            "identifiers": {
                "fr": {"required": False, "references": {"DESIGN": {"coverage": True}}},
            },
            "headings": [
                {"level": 1, "pattern": "PRD", "id": "prd", "description": "Product requirements"},
            ],
        },
        "DESIGN": {
            "identifiers": {"component": {"required": False}},
            "headings": [
                {"level": 1, "pattern": "Design", "id": "design", "description": "System design"},
            ],
        },
    })
    assert errs == []
    prd = tmp_path / "PRD.md"
    prd.write_text("# PRD\n\n**ID**: `cpt-sys-fr-login`\n", encoding="utf-8")
    design = tmp_path / "DESIGN.md"
    design.write_text("# Design\n\n`cpt-sys-fr-login`\n", encoding="utf-8")
    arts = [
        ArtifactRecord(path=prd, artifact_kind="PRD", constraints=kc.by_kind["PRD"]),
        ArtifactRecord(path=design, artifact_kind="DESIGN", constraints=kc.by_kind["DESIGN"]),
    ]
    rep = cross_validate_artifacts(arts, registered_systems={"sys"}, known_kinds={"fr", "component"})
    # Should exercise heading_desc_by_kind and _cross_all_kind_tokens
    assert isinstance(rep, dict)


def test_cross_validate_composite_nested_kind(tmp_path: Path):
    """cross_validate: composite nested kind parsing in cross-validate."""
    kc, errs = parse_kit_constraints({
        "FEATURE": {
            "identifiers": {
                "flow": {"required": False, "task": True},
                "dod": {"required": False},
            },
        },
    })
    assert errs == []
    feat = tmp_path / "FEATURE.md"
    feat.write_text("**ID**: `cpt-sys-flow-dod-create`\n", encoding="utf-8")
    arts = [
        ArtifactRecord(path=feat, artifact_kind="FEATURE", constraints=kc.by_kind["FEATURE"]),
    ]
    rep = cross_validate_artifacts(arts, registered_systems={"sys"}, known_kinds={"flow", "dod"})
    kind_errors = [e for e in (rep.get("errors") or []) if e.get("code") == EC.ID_KIND_NOT_ALLOWED]
    assert kind_errors == []


# =========================================================================
# Heading contract: scope_end, multiple enforcement
# =========================================================================

def test_heading_contract_scope_end_for_parent(tmp_path: Path):
    """validate_headings_contract exercises _scope_end_for_parent with nested headings."""
    kc, errs = parse_kit_constraints({
        "PRD": {
            "identifiers": {"fr": {"required": False}},
            "headings": [
                {"level": 1, "pattern": "PRD"},
                {"level": 2, "pattern": "Section A"},
                {"level": 3, "pattern": "Sub A1"},
                {"level": 2, "pattern": "Section B"},
            ],
        },
    })
    assert errs == []
    p = tmp_path / "PRD.md"
    p.write_text(
        "# PRD\n\n## Section A\n\n### Sub A1\n\nContent\n\n## Section B\n\nMore content\n",
        encoding="utf-8",
    )
    rep = validate_headings_contract(
        path=p, constraints=kc.by_kind["PRD"],
        registered_systems={"sys"},
        artifact_kind="PRD",
    )
    # Should succeed without errors
    assert rep.get("errors") == [] or rep.get("errors") is not None


def test_heading_contract_multiple_false_stops_at_one(tmp_path: Path):
    """Heading with multiple=false only matches once even if heading repeats."""
    kc, errs = parse_kit_constraints({
        "PRD": {
            "identifiers": {"fr": {"required": False}},
            "headings": [
                {"level": 1, "pattern": "PRD"},
                {"level": 2, "pattern": "Goals", "multiple": False},
            ],
        },
    })
    assert errs == []
    p = tmp_path / "PRD.md"
    p.write_text("# PRD\n\n## Goals\n\nFirst\n\n## Goals\n\nSecond\n", encoding="utf-8")
    rep = validate_headings_contract(
        path=p, constraints=kc.by_kind["PRD"],
        registered_systems={"sys"},
        artifact_kind="PRD",
    )
    # multiple=False just stops after first match; no error is emitted
    assert isinstance(rep, dict)


def test_heading_contract_multiple_true_collects_all(tmp_path: Path):
    """Heading with multiple=true collects all consecutive matches."""
    kc, errs = parse_kit_constraints({
        "PRD": {
            "identifiers": {"fr": {"required": False}},
            "headings": [
                {"level": 1, "pattern": "PRD"},
                {"level": 2, "pattern": ".*Feature.*", "multiple": True, "description": "Feature sections"},
            ],
        },
    })
    assert errs == []
    p = tmp_path / "PRD.md"
    p.write_text(
        "# PRD\n\n## Feature Login\n\nLogin\n\n## Feature Signup\n\nSignup\n",
        encoding="utf-8",
    )
    rep = validate_headings_contract(
        path=p, constraints=kc.by_kind["PRD"],
        registered_systems={"sys"},
        artifact_kind="PRD",
    )
    # Should succeed, both matched
    assert isinstance(rep, dict)


def test_heading_contract_required_missing(tmp_path: Path):
    """Required heading that is missing → HEADING_MISSING."""
    kc, errs = parse_kit_constraints({
        "PRD": {
            "identifiers": {"fr": {"required": False}},
            "headings": [
                {"level": 1, "pattern": "PRD"},
                {"level": 2, "pattern": "Nonexistent", "required": True, "description": "Must exist"},
            ],
        },
    })
    assert errs == []
    p = tmp_path / "PRD.md"
    p.write_text("# PRD\n\nSome content.\n", encoding="utf-8")
    rep = validate_headings_contract(
        path=p, constraints=kc.by_kind["PRD"],
        registered_systems={"sys"},
        artifact_kind="PRD",
    )
    codes = [e.get("code") for e in rep.get("errors", [])]
    assert EC.HEADING_MISSING in codes


# =========================================================================
# Wildcard level-3 heading matching
# =========================================================================

def test_wildcard_lvl3_heading_match(tmp_path: Path):
    """Level-3 wildcard heading under a level-2 parent is matched by ID."""
    kc, errs = parse_kit_constraints({
        "PRD": {
            "identifiers": {"fr": {"required": False}},
            "headings": [
                {"level": 1, "pattern": "PRD"},
                {"level": 2, "pattern": "Features", "id": "features"},
                {"level": 3, "id": "feature-item"},
            ],
        },
    })
    assert errs == []
    p = tmp_path / "PRD.md"
    p.write_text(
        "# PRD\n\n## Features\n\n### Login\n\nLogin feature\n\n### Signup\n\nSignup feature\n",
        encoding="utf-8",
    )
    # heading_constraint_ids_by_line returns List[List[str]] — one list per line
    result = heading_constraint_ids_by_line(p, kc.by_kind["PRD"].headings)
    # Flatten all matched IDs across all lines
    all_ids = set()
    for line_ids in result:
        all_ids.update(line_ids)
    assert "feature-item" in all_ids


# =========================================================================
# Duplicate definition detection across artifact files
# =========================================================================

def test_duplicate_id_across_files_detected(tmp_path: Path):
    """Duplicate definition of the same ID in two different files is an error."""
    file_a = tmp_path / "PRD.md"
    file_a.write_text("**ID**: `cpt-sys-fr-shared-id`\n", encoding="utf-8")
    file_b = tmp_path / "DESIGN.md"
    file_b.write_text("**ID**: `cpt-sys-fr-shared-id`\n", encoding="utf-8")
    arts = [
        ArtifactRecord(path=file_a, artifact_kind="PRD", constraints=None),
        ArtifactRecord(path=file_b, artifact_kind="DESIGN", constraints=None),
    ]
    rep = cross_validate_artifacts(arts, registered_systems={"sys"}, known_kinds={"fr"})
    errs = rep.get("errors") or []
    dup_errs = [e for e in errs if e.get("code") == EC.DUPLICATE_DEFINITION]
    assert len(dup_errs) == 2  # one error per definition
    assert all("cpt-sys-fr-shared-id" in e["message"] for e in dup_errs)


def test_same_id_same_file_not_flagged_as_duplicate(tmp_path: Path):
    """Multiple occurrences of an ID in the same file are not cross-file duplicates."""
    prd = tmp_path / "PRD.md"
    prd.write_text(
        "**ID**: `cpt-sys-fr-single`\n\n"
        "Ref: `cpt-sys-fr-single`\n",
        encoding="utf-8",
    )
    arts = [ArtifactRecord(path=prd, artifact_kind="PRD", constraints=None)]
    rep = cross_validate_artifacts(arts, registered_systems={"sys"}, known_kinds={"fr"})
    errs = rep.get("errors") or []
    dup_errs = [e for e in errs if e.get("code") == EC.DUPLICATE_DEFINITION]
    assert dup_errs == []


def test_single_definition_no_duplicate_error(tmp_path: Path):
    """A single definition produces no duplicate error."""
    prd = tmp_path / "PRD.md"
    prd.write_text("**ID**: `cpt-sys-fr-unique`\n", encoding="utf-8")
    arts = [ArtifactRecord(path=prd, artifact_kind="PRD", constraints=None)]
    rep = cross_validate_artifacts(arts, registered_systems={"sys"}, known_kinds={"fr"})
    errs = rep.get("errors") or []
    dup_errs = [e for e in errs if e.get("code") == EC.DUPLICATE_DEFINITION]
    assert dup_errs == []