Linter¶

def build_registry() -> RuleRegistry:
    """Build the rule registry by importing all rule modules.

    Importing ``cxas_scrapi.utils.lint_rules`` triggers the ``@rule``
    decorator on every rule class, populating ``_RULE_REGISTRY``.  We
    then copy those into a ``RuleRegistry`` for config-aware lookups.
    """
    import cxas_scrapi.utils.lint_rules  # noqa: F401,PLC0415

    registry = RuleRegistry()
    for _category, rules in get_registered_rules().items():
        registry.register_all(rules)
    return registry

def build_context(
    project_root: Path,
    config: LintConfig,
    discovery: Discovery,
) -> LintContext:
    """Build the shared lint context from discovered app resources."""
    agents = discovery.discover_agents()
    tools = discovery.discover_tools()

    return LintContext(
        project_root=project_root,
        app_dir=discovery.app_dir,
        evals_dir=project_root / config.evals_dir,
        all_agent_names=set(agents.keys()),
        all_agent_display_names={
            discovery.dir_name_to_display(name) for name in agents
        },
        all_tool_names=set(tools.keys()),
        all_tool_dirs={name: path.parent for name, path in tools.items()},
        options=config.options,
    )

def run_rules(  # noqa: C901
    registry: RuleRegistry,
    config: LintConfig,
    context: LintContext,
    discovery: Discovery,
    report: LintReport,
    categories: Optional[list[str]] = None,
    specific_rules: Optional[set[str]] = None,
):
    """Run lint rules against discovered files."""

    def should_run(rule_obj):
        if specific_rules and rule_obj.id not in specific_rules:
            return False
        if categories and rule_obj.category not in categories:
            return False
        return True

    def _get_severity(rule_obj, file_rel):
        sev = config.get_severity(rule_obj, file_rel)
        return sev if sev != Severity.OFF else None

    def _lint_files(rules: list[Rule], files: dict[str, Path]):
        """Apply rules to a set of discovered files or directories."""
        for _name, file_path in files.items():
            rel = str(file_path.relative_to(context.project_root))
            if config.is_ignored(rel):
                continue
            content = file_path.read_text() if file_path.is_file() else ""
            for rule_obj in rules:
                sev = _get_severity(rule_obj, rel)
                if sev is None:
                    continue
                for result in rule_obj.check(file_path, content, context):
                    result.severity = sev
                    report.add(result)

    def _get_rules(category: str) -> list[Rule]:
        if categories and category not in categories:
            return []
        return [
            r for r in registry.rules_for_category(category) if should_run(r)
        ]

    # Instructions — instruction.txt files + global_instruction.txt
    instruction_files = {
        k: v
        for k, v in discovery.discover_agents().items()
        if v.name == "instruction.txt"
    }
    global_inst = discovery.discover_global_instruction()
    if global_inst:
        instruction_files["global_instruction"] = global_inst
    _lint_files(_get_rules("instructions"), instruction_files)

    # Callbacks
    cb_files = {
        f"{agent}_{cb_type}_{cb_name}": code_path
        for agent, cb_type, cb_name, code_path in discovery.discover_callbacks()
    }
    _lint_files(_get_rules("callbacks"), cb_files)

    # Tools
    _lint_files(_get_rules("tools"), discovery.discover_tools())

    # Evals
    _lint_files(_get_rules("evals"), discovery.discover_evals())

    # Config — app config + agent configs
    config_rules = _get_rules("config")
    if config_rules:
        app_cfg = discovery.discover_app_config()
        config_files = {}
        if app_cfg:
            config_files["app"] = app_cfg
        config_files.update(discovery.discover_agent_configs())
        _lint_files(config_rules, config_files)

    # Target-dispatched rules (structure + schema categories)
    # Rules with a ``target`` property get matched to discovered files.
    target_dispatched = _get_rules("structure") + _get_rules("schema")
    if target_dispatched:
        target_files = {
            "app_config": {},
            "instruction": instruction_files,
            "agent_config": discovery.discover_agent_configs(),
            "tool_config": discovery._discover_resource_dirs("tools"),
            "toolset_config": discovery.discover_toolsets(),
            "guardrail_config": discovery.discover_guardrails(),
            "evaluation_config": discovery.discover_evaluations(),
            "eval_expectation_config": (
                discovery.discover_evaluation_expectations()
            ),
        }
        app_cfg = discovery.discover_app_config()
        if app_cfg:
            target_files["app_config"] = {"app": app_cfg}

        by_target: dict[str, list[Rule]] = {}
        for r in target_dispatched:
            by_target.setdefault(r.target, []).append(r)

        for target_name, rules in by_target.items():
            files = target_files.get(target_name, {})
            if files:
                _lint_files(rules, files)

def rule(category: str):
    """Class decorator that auto-registers a Rule into its category.

    Duplicate rule IDs are silently ignored so that repeated imports
    (or test-time ``@rule`` usage) never produce duplicates.

    Usage::

        @rule("config")
        class InvalidJson(Rule):
            id = "A001"
            ...
    """

    def decorator(cls):
        cls.category = category
        instance = cls()
        if instance.id not in _REGISTERED_IDS:
            _REGISTERED_IDS.add(instance.id)
            _RULE_REGISTRY[category].append(instance)
        return cls

    return decorator