tqlint 0.4.2__py3-none-any.whl

tq/__init__.py

@@ -0,0 +1 @@
+"""tq package."""

tq/cli/__init__.py

@@ -0,0 +1 @@
+"""CLI package for tq command surface."""

tq/cli/main.py

@@ -0,0 +1,283 @@
+"""Command-line interface for tq."""
+
+from __future__ import annotations
+
+import tomllib
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import click
+from rich.console import Console
+
+from tq.config.loader import resolve_tq_config
+from tq.config.models import CliOverrides, ConfigValidationError, TqConfig
+from tq.discovery.filesystem import build_analysis_index
+from tq.engine.context import AnalysisContext
+from tq.engine.rule_id import RuleId
+from tq.engine.runner import RuleEngine
+from tq.reporting.json import print_json_report
+from tq.reporting.terminal import print_report
+from tq.rules.file_too_large import FileTooLargeRule
+from tq.rules.mapping_missing_test import MappingMissingTestRule
+from tq.rules.orphaned_test import OrphanedTestRule
+from tq.rules.qualifiers import QualifierStrategy
+from tq.rules.structure_mismatch import StructureMismatchRule
+
+if TYPE_CHECKING:
+    from tq.rules.contracts import Rule
+
+_BUILTIN_RULE_IDS = (
+    RuleId("mapping-missing-test"),
+    RuleId("structure-mismatch"),
+    RuleId("test-file-too-large"),
+    RuleId("orphaned-test"),
+)
+
+
+_HELP_OPTION_NAMES = {"help_option_names": ["-h", "--help"]}
+
+
+@click.group(context_settings=_HELP_OPTION_NAMES)
+def cli() -> None:
+    """Run tq commands."""
+
+
+@cli.command("check", context_settings=_HELP_OPTION_NAMES)
+@click.option(
+    "--config",
+    "config_path",
+    type=click.Path(path_type=Path, dir_okay=False, exists=True),
+    default=None,
+    help="Use this pyproject file instead of discovered configuration.",
+)
+@click.option(
+    "--isolated",
+    is_flag=True,
+    default=False,
+    help="Ignore discovered configuration files.",
+)
+@click.option("--package", type=str, default=None, help="Target package import path.")
+@click.option("--source-root", type=str, default=None, help="Source tree root path.")
+@click.option("--test-root", type=str, default=None, help="Test tree root path.")
+@click.option(
+    "--max-test-file-non-blank-lines",
+    type=click.IntRange(min=1),
+    default=None,
+    help="Maximum non-blank, non-comment lines per test file.",
+)
+@click.option(
+    "--qualifier-strategy",
+    type=click.Choice([strategy.value for strategy in QualifierStrategy]),
+    default=None,
+    help="Module-name qualifier policy for qualified test files.",
+)
+@click.option(
+    "--allowed-qualifier",
+    "allowed_qualifiers",
+    multiple=True,
+    type=str,
+    help="Allowed qualifier suffix for allowlist strategy.",
+)
+@click.option(
+    "--ignore-init-modules",
+    "ignore_init_modules",
+    flag_value=True,
+    default=None,
+    help="Ignore __init__.py modules in mapping checks.",
+)
+@click.option(
+    "--no-ignore-init-modules",
+    "ignore_init_modules",
+    flag_value=False,
+    default=None,
+    help="Include __init__.py modules in mapping checks.",
+)
+@click.option(
+    "--select",
+    "select_rules",
+    multiple=True,
+    type=str,
+    help="Only run selected rule IDs.",
+)
+@click.option(
+    "--ignore",
+    "ignore_rules",
+    multiple=True,
+    type=str,
+    help="Skip listed rule IDs.",
+)
+@click.option(
+    "--exit-zero",
+    is_flag=True,
+    default=False,
+    help="Always exit with code 0 regardless of findings.",
+)
+@click.option(
+    "--show-suggestions",
+    is_flag=True,
+    default=False,
+    help="Render remediation suggestions in diagnostics output.",
+)
+@click.option(
+    "--output-format",
+    type=click.Choice(["text", "json"]),
+    default="text",
+    show_default=True,
+    help="Select output format.",
+)
+def check_command(  # noqa: PLR0913
+    *,
+    config_path: Path | None,
+    isolated: bool,
+    package: str | None,
+    source_root: str | None,
+    test_root: str | None,
+    max_test_file_non_blank_lines: int | None,
+    qualifier_strategy: str | None,
+    allowed_qualifiers: tuple[str, ...],
+    ignore_init_modules: bool | None,
+    select_rules: tuple[str, ...],
+    ignore_rules: tuple[str, ...],
+    exit_zero: bool,
+    show_suggestions: bool,
+    output_format: str,
+) -> None:
+    """Run built-in tq quality rules against discovered modules and tests."""
+    cwd = Path.cwd()
+    console = Console(stderr=False)
+
+    try:
+        overrides = CliOverrides(
+            package=package,
+            source_root=source_root,
+            test_root=test_root,
+            ignore_init_modules=ignore_init_modules,
+            max_test_file_non_blank_lines=max_test_file_non_blank_lines,
+            qualifier_strategy=(
+                QualifierStrategy(qualifier_strategy)
+                if qualifier_strategy is not None
+                else None
+            ),
+            allowed_qualifiers=allowed_qualifiers or None,
+            select=_parse_rule_id_tuple(values=select_rules),
+            ignore=_parse_rule_id_tuple(values=ignore_rules),
+        )
+        config = resolve_tq_config(
+            cwd=cwd,
+            explicit_config_path=config_path,
+            isolated=isolated,
+            cli_overrides=overrides,
+        )
+    except (ConfigValidationError, ValueError, tomllib.TOMLDecodeError) as error:
+        raise click.UsageError(str(error)) from error
+
+    if not config.source_package_root.exists():
+        msg = (
+            "Configured source package root does not exist: "
+            f"{config.source_package_root}"
+        )
+        raise click.UsageError(
+            msg,
+        )
+    if not config.test_root.exists():
+        msg = f"Configured test root does not exist: {config.test_root}"
+        raise click.UsageError(
+            msg,
+        )
+
+    rules = _build_rules(config=config)
+    index = build_analysis_index(
+        source_root=config.source_package_root,
+        test_root=config.test_root,
+    )
+    context = AnalysisContext.create(index=index)
+    result = RuleEngine(rules=rules).run(context=context)
+
+    if output_format == "json":
+        print_json_report(result=result, console=console, cwd=cwd)
+    else:
+        print_report(
+            result=result,
+            console=console,
+            cwd=cwd,
+            include_suggestions=show_suggestions,
+        )
+
+    if exit_zero:
+        raise click.exceptions.Exit(0)
+
+    raise click.exceptions.Exit(1 if result.has_errors else 0)
+
+
+def _build_rules(*, config: TqConfig) -> tuple[Rule, ...]:
+    """Build active built-in rule set using select/ignore resolution."""
+    selected_rule_ids = _resolve_rule_selection(config=config)
+    selected_set = set(selected_rule_ids)
+
+    builtins: dict[RuleId, Rule] = {
+        RuleId("mapping-missing-test"): MappingMissingTestRule(
+            ignore_init_modules=config.ignore_init_modules,
+            qualifier_strategy=config.qualifier_strategy,
+            allowed_qualifiers=config.allowed_qualifiers,
+        ),
+        RuleId("structure-mismatch"): StructureMismatchRule(),
+        RuleId("test-file-too-large"): FileTooLargeRule(
+            max_non_blank_lines=config.max_test_file_non_blank_lines,
+        ),
+        RuleId("orphaned-test"): OrphanedTestRule(
+            qualifier_strategy=config.qualifier_strategy,
+            allowed_qualifiers=config.allowed_qualifiers,
+        ),
+    }
+
+    return tuple(
+        builtins[rule_id] for rule_id in _BUILTIN_RULE_IDS if rule_id in selected_set
+    )
+
+
+def _resolve_rule_selection(*, config: TqConfig) -> tuple[RuleId, ...]:
+    """Resolve active rule IDs deterministically from select/ignore."""
+    builtin_set = set(_BUILTIN_RULE_IDS)
+
+    requested_select = set(config.select)
+    requested_ignore = set(config.ignore)
+
+    unknown = (requested_select | requested_ignore) - builtin_set
+    if unknown:
+        unknown_ids = ", ".join(sorted(rule_id.value for rule_id in unknown))
+        msg = f"Unknown built-in rule ID(s): {unknown_ids}"
+        raise ConfigValidationError(msg)
+
+    if config.select:
+        selected = tuple(
+            rule_id for rule_id in _BUILTIN_RULE_IDS if rule_id in requested_select
+        )
+    else:
+        selected = _BUILTIN_RULE_IDS
+
+    return tuple(rule_id for rule_id in selected if rule_id not in requested_ignore)
+
+
+def _parse_rule_id_tuple(*, values: tuple[str, ...]) -> tuple[RuleId, ...] | None:
+    """Parse optional CLI rule identifier list into RuleId values."""
+    if not values:
+        return None
+
+    rule_ids: list[RuleId] = []
+    for value in values:
+        try:
+            rule_ids.append(RuleId(value))
+        except ValueError as error:
+            msg = f"Invalid rule ID: {value}"
+            raise ConfigValidationError(msg) from error
+
+    return tuple(rule_ids)
+
+
+def main() -> None:
+    """Run the tq command group."""
+    cli()
+
+
+if __name__ == "__main__":
+    main()

tq/config/__init__.py

@@ -0,0 +1 @@
+"""Configuration domain for tq CLI and engine composition."""

tq/config/loader.py

@@ -0,0 +1,356 @@
+"""Strict configuration loading and precedence resolution for tq."""
+
+from __future__ import annotations
+
+import tomllib
+from pathlib import Path
+from typing import Any
+
+from tq.config.models import (
+    CliOverrides,
+    ConfigValidationError,
+    PartialTqConfig,
+    TqConfig,
+)
+from tq.engine.rule_id import RuleId
+from tq.rules.qualifiers import QualifierStrategy
+
+DEFAULT_IGNORE_INIT_MODULES = False
+DEFAULT_MAX_TEST_FILE_NON_BLANK_LINES = 600
+DEFAULT_QUALIFIER_STRATEGY = QualifierStrategy.ANY_SUFFIX
+
+_CONFIG_KEYS = {
+    "package",
+    "source_root",
+    "test_root",
+    "ignore_init_modules",
+    "max_test_file_non_blank_lines",
+    "qualifier_strategy",
+    "allowed_qualifiers",
+    "select",
+    "ignore",
+}
+
+
+def resolve_tq_config(
+    *,
+    cwd: Path,
+    explicit_config_path: Path | None,
+    isolated: bool,
+    cli_overrides: CliOverrides,
+) -> TqConfig:
+    """Resolve final tq config with strict precedence and validation."""
+    discovered = PartialTqConfig()
+
+    if explicit_config_path is not None:
+        config_path = explicit_config_path.resolve()
+        discovered = _load_partial_from_pyproject(
+            path=config_path,
+            require_section=True,
+        )
+    elif not isolated:
+        user_config_path = Path.home() / ".config" / "tq" / "pyproject.toml"
+        project_config_path = _find_project_pyproject(cwd)
+
+        if user_config_path.exists():
+            user_partial = _load_partial_from_pyproject(
+                path=user_config_path,
+                require_section=False,
+            )
+            discovered = _merge_partial(discovered, user_partial)
+
+        if project_config_path is not None:
+            project_partial = _load_partial_from_pyproject(
+                path=project_config_path,
+                require_section=False,
+            )
+            discovered = _merge_partial(discovered, project_partial)
+
+    merged = _merge_partial(discovered, _partial_from_cli(cli_overrides))
+    return _materialize_config(cwd=cwd, partial=merged)
+
+
+def _find_project_pyproject(cwd: Path) -> Path | None:
+    """Find nearest project ``pyproject.toml`` starting from cwd."""
+    for candidate_dir in (cwd, *cwd.parents):
+        candidate = candidate_dir / "pyproject.toml"
+        if candidate.exists():
+            return candidate
+    return None
+
+
+def _load_partial_from_pyproject(
+    *,
+    path: Path,
+    require_section: bool,
+) -> PartialTqConfig:
+    """Load strict partial tq config from a pyproject file."""
+    if not path.exists():
+        msg = f"Config file not found: {path}"
+        raise ConfigValidationError(msg)
+
+    with path.open("rb") as handle:
+        document = tomllib.load(handle)
+
+    tool_section = document.get("tool", {})
+    tq_section = tool_section.get("tq")
+
+    if tq_section is None:
+        if require_section:
+            msg = f"Missing [tool.tq] section in config file: {path}"
+            raise ConfigValidationError(
+                msg,
+            )
+        return PartialTqConfig()
+
+    if not isinstance(tq_section, dict):
+        msg = "[tool.tq] must be a table"
+        raise ConfigValidationError(msg)
+
+    unknown_keys = set(tq_section) - _CONFIG_KEYS
+    if unknown_keys:
+        keys = ", ".join(sorted(unknown_keys))
+        msg = f"Unknown [tool.tq] key(s): {keys}"
+        raise ConfigValidationError(msg)
+
+    return PartialTqConfig(
+        package=_expect_optional_str(tq_section, "package"),
+        source_root=_expect_optional_str(tq_section, "source_root"),
+        test_root=_expect_optional_str(tq_section, "test_root"),
+        ignore_init_modules=_expect_optional_bool(tq_section, "ignore_init_modules"),
+        max_test_file_non_blank_lines=_expect_optional_positive_int(
+            tq_section,
+            "max_test_file_non_blank_lines",
+        ),
+        qualifier_strategy=_expect_optional_qualifier_strategy(
+            tq_section,
+            "qualifier_strategy",
+        ),
+        allowed_qualifiers=_expect_optional_string_tuple(
+            tq_section,
+            "allowed_qualifiers",
+        ),
+        select=_expect_optional_rule_ids(tq_section, "select"),
+        ignore=_expect_optional_rule_ids(tq_section, "ignore"),
+    )
+
+
+def _partial_from_cli(overrides: CliOverrides) -> PartialTqConfig:
+    """Convert CLI overrides into a partial config representation."""
+    return PartialTqConfig(
+        package=overrides.package,
+        source_root=overrides.source_root,
+        test_root=overrides.test_root,
+        ignore_init_modules=overrides.ignore_init_modules,
+        max_test_file_non_blank_lines=overrides.max_test_file_non_blank_lines,
+        qualifier_strategy=overrides.qualifier_strategy,
+        allowed_qualifiers=overrides.allowed_qualifiers,
+        select=overrides.select,
+        ignore=overrides.ignore,
+    )
+
+
+def _merge_partial(base: PartialTqConfig, override: PartialTqConfig) -> PartialTqConfig:
+    """Merge two partial configs where ``override`` takes precedence."""
+    return PartialTqConfig(
+        package=override.package if override.package is not None else base.package,
+        source_root=(
+            override.source_root
+            if override.source_root is not None
+            else base.source_root
+        ),
+        test_root=(
+            override.test_root if override.test_root is not None else base.test_root
+        ),
+        ignore_init_modules=(
+            override.ignore_init_modules
+            if override.ignore_init_modules is not None
+            else base.ignore_init_modules
+        ),
+        max_test_file_non_blank_lines=(
+            override.max_test_file_non_blank_lines
+            if override.max_test_file_non_blank_lines is not None
+            else base.max_test_file_non_blank_lines
+        ),
+        qualifier_strategy=(
+            override.qualifier_strategy
+            if override.qualifier_strategy is not None
+            else base.qualifier_strategy
+        ),
+        allowed_qualifiers=(
+            override.allowed_qualifiers
+            if override.allowed_qualifiers is not None
+            else base.allowed_qualifiers
+        ),
+        select=override.select if override.select is not None else base.select,
+        ignore=override.ignore if override.ignore is not None else base.ignore,
+    )
+
+
+def _materialize_config(*, cwd: Path, partial: PartialTqConfig) -> TqConfig:
+    """Validate and materialize a final runtime config."""
+    if not partial.package:
+        msg = "Missing required configuration key: tool.tq.package"
+        raise ConfigValidationError(
+            msg,
+        )
+    if not partial.source_root:
+        msg = "Missing required configuration key: tool.tq.source_root"
+        raise ConfigValidationError(
+            msg,
+        )
+    if not partial.test_root:
+        msg = "Missing required configuration key: tool.tq.test_root"
+        raise ConfigValidationError(
+            msg,
+        )
+
+    allowed_qualifiers = tuple(sorted(set(partial.allowed_qualifiers or ())))
+    qualifier_strategy = partial.qualifier_strategy or DEFAULT_QUALIFIER_STRATEGY
+
+    if qualifier_strategy is QualifierStrategy.ALLOWLIST and not allowed_qualifiers:
+        msg = (
+            "tool.tq.allowed_qualifiers must be non-empty when "
+            "tool.tq.qualifier_strategy is 'allowlist'"
+        )
+        raise ConfigValidationError(
+            msg,
+        )
+
+    source_root = _resolve_path(cwd=cwd, value=partial.source_root)
+    test_root = _resolve_path(cwd=cwd, value=partial.test_root)
+
+    return TqConfig(
+        package=partial.package,
+        source_root=source_root,
+        test_root=test_root,
+        ignore_init_modules=(
+            partial.ignore_init_modules
+            if partial.ignore_init_modules is not None
+            else DEFAULT_IGNORE_INIT_MODULES
+        ),
+        max_test_file_non_blank_lines=(
+            partial.max_test_file_non_blank_lines
+            if partial.max_test_file_non_blank_lines is not None
+            else DEFAULT_MAX_TEST_FILE_NON_BLANK_LINES
+        ),
+        qualifier_strategy=qualifier_strategy,
+        allowed_qualifiers=allowed_qualifiers,
+        select=partial.select or (),
+        ignore=partial.ignore or (),
+    )
+
+
+def _resolve_path(*, cwd: Path, value: str) -> Path:
+    """Resolve a config path relative to cwd."""
+    candidate = Path(value)
+    if candidate.is_absolute():
+        return candidate
+    return (cwd / candidate).resolve()
+
+
+def _expect_optional_str(document: dict[str, Any], key: str) -> str | None:
+    """Read optional non-empty string field from config document."""
+    value = document.get(key)
+    if value is None:
+        return None
+    if not isinstance(value, str):
+        msg = f"tool.tq.{key} must be a string"
+        raise ConfigValidationError(msg)
+    if not value.strip():
+        msg = f"tool.tq.{key} must be non-empty"
+        raise ConfigValidationError(msg)
+    return value
+
+
+def _expect_optional_bool(document: dict[str, Any], key: str) -> bool | None:
+    """Read optional boolean field from config document."""
+    value = document.get(key)
+    if value is None:
+        return None
+    if not isinstance(value, bool):
+        msg = f"tool.tq.{key} must be a boolean"
+        raise ConfigValidationError(msg)
+    return value
+
+
+def _expect_optional_positive_int(document: dict[str, Any], key: str) -> int | None:
+    """Read optional positive integer field from config document."""
+    value = document.get(key)
+    if value is None:
+        return None
+    if not isinstance(value, int):
+        msg = f"tool.tq.{key} must be an integer"
+        raise ConfigValidationError(msg)
+    if value < 1:
+        msg = f"tool.tq.{key} must be >= 1"
+        raise ConfigValidationError(msg)
+    return value
+
+
+def _expect_optional_qualifier_strategy(
+    document: dict[str, Any],
+    key: str,
+) -> QualifierStrategy | None:
+    """Read optional qualifier strategy enum value from config document."""
+    value = document.get(key)
+    if value is None:
+        return None
+    if not isinstance(value, str):
+        msg = f"tool.tq.{key} must be a string"
+        raise ConfigValidationError(msg)
+
+    try:
+        return QualifierStrategy(value)
+    except ValueError as error:
+        choices = ", ".join(strategy.value for strategy in QualifierStrategy)
+        msg = f"tool.tq.{key} must be one of: {choices}"
+        raise ConfigValidationError(
+            msg,
+        ) from error
+
+
+def _expect_optional_string_tuple(
+    document: dict[str, Any],
+    key: str,
+) -> tuple[str, ...] | None:
+    """Read optional list of non-empty strings from config document."""
+    value = document.get(key)
+    if value is None:
+        return None
+    if not isinstance(value, list):
+        msg = f"tool.tq.{key} must be an array of strings"
+        raise ConfigValidationError(msg)
+
+    items: list[str] = []
+    for item in value:
+        if not isinstance(item, str) or not item.strip():
+            msg = f"tool.tq.{key} must contain only non-empty strings"
+            raise ConfigValidationError(
+                msg,
+            )
+        items.append(item)
+
+    return tuple(items)
+
+
+def _expect_optional_rule_ids(
+    document: dict[str, Any],
+    key: str,
+) -> tuple[RuleId, ...] | None:
+    """Read optional list of rule identifiers from config document."""
+    values = _expect_optional_string_tuple(document, key)
+    if values is None:
+        return None
+
+    rule_ids: list[RuleId] = []
+    for value in values:
+        try:
+            rule_ids.append(RuleId(value))
+        except ValueError as error:
+            msg = f"tool.tq.{key} contains invalid rule id: {value}"
+            raise ConfigValidationError(
+                msg,
+            ) from error
+
+    return tuple(rule_ids)