tqlint 0.4.2__tar.gz

tqlint-0.4.2/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: tqlint
+Version: 0.4.2
+Summary: tq inspects a codebase's tests and enforces quality rules so tests remain discoverable, focused, actionable, and maintainable
+Keywords: testing,lint,pytest,quality,developer-tools
+Author: Stephen Lewis
+Author-email: Stephen Lewis <31178492+stelewis@users.noreply.github.com>
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Classifier: Typing :: Typed
+Requires-Dist: click>=8.3.1
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: rich>=14.3.2
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/stelewis/tq
+Project-URL: Repository, https://github.com/stelewis/tq
+Project-URL: Issues, https://github.com/stelewis/tq/issues
+Project-URL: Changelog, https://github.com/stelewis/tq/blob/main/CHANGELOG.md
+Description-Content-Type: text/markdown
+
+# `tq` - Test Quality Toolkit
+
+`tq` inspects a codebase's tests and enforces quality rules so tests remain discoverable, focused, actionable, and maintainable.
+
+## Installation
+
+PyPI distribution name: `tqlint`
+
+Add to a project:
+
+```sh
+uv add --dev tqlint
+uv run tq check
+```
+
+Run without installing (ephemeral):
+
+```sh
+uvx tqlint check
+```
+
+Install as a persistent global tool:
+
+```sh
+uv tool install tqlint
+tq check
+```
+
+Note: `uvx tq check` is not available because the `tq` package name on PyPI is owned by another project.
+
+## Current scope
+
+`tq` currently analyzes Python source and Python tests (`.py`) only.
+
+## Usage
+
+Run checks:
+
+```sh
+uv run tq check
+```
+
+Emit machine-readable diagnostics:
+
+```sh
+uv run tq check --output-format json
+```
+
+## Configuration
+
+Configure `tq` in `pyproject.toml` under `[tool.tq]`:
+
+```toml
+[tool.tq]
+package = "tq"
+source_root = "src"
+test_root = "tests"
+ignore_init_modules = true
+max_test_file_non_blank_lines = 600
+qualifier_strategy = "allowlist"
+allowed_qualifiers = ["regression"]
+```
+
+## Documentation
+
+- See [docs/developer/tools/tq_check.md](docs/developer/tools/tq_check.md) for tool usage and configuration details.
+- See [docs/developer/tools/rules.md](docs/developer/tools/rules.md) for built-in rules.
+
+## Development
+
+Contribution guidelines are in [CONTRIBUTING.md](CONTRIBUTING.md). For local development, follow below steps.
+
+Install dependencies:
+
+```sh
+uv sync
+```
+
+Install pre-commit hooks (including `pre-commit`, `commit-msg`, and `pre-push`):
+
+```sh
+uv run prek install
+```
+
+Run tests:
+
+```sh
+uv run pytest -q
+```

tqlint-0.4.2/README.md

@@ -0,0 +1,89 @@
+# `tq` - Test Quality Toolkit
+
+`tq` inspects a codebase's tests and enforces quality rules so tests remain discoverable, focused, actionable, and maintainable.
+
+## Installation
+
+PyPI distribution name: `tqlint`
+
+Add to a project:
+
+```sh
+uv add --dev tqlint
+uv run tq check
+```
+
+Run without installing (ephemeral):
+
+```sh
+uvx tqlint check
+```
+
+Install as a persistent global tool:
+
+```sh
+uv tool install tqlint
+tq check
+```
+
+Note: `uvx tq check` is not available because the `tq` package name on PyPI is owned by another project.
+
+## Current scope
+
+`tq` currently analyzes Python source and Python tests (`.py`) only.
+
+## Usage
+
+Run checks:
+
+```sh
+uv run tq check
+```
+
+Emit machine-readable diagnostics:
+
+```sh
+uv run tq check --output-format json
+```
+
+## Configuration
+
+Configure `tq` in `pyproject.toml` under `[tool.tq]`:
+
+```toml
+[tool.tq]
+package = "tq"
+source_root = "src"
+test_root = "tests"
+ignore_init_modules = true
+max_test_file_non_blank_lines = 600
+qualifier_strategy = "allowlist"
+allowed_qualifiers = ["regression"]
+```
+
+## Documentation
+
+- See [docs/developer/tools/tq_check.md](docs/developer/tools/tq_check.md) for tool usage and configuration details.
+- See [docs/developer/tools/rules.md](docs/developer/tools/rules.md) for built-in rules.
+
+## Development
+
+Contribution guidelines are in [CONTRIBUTING.md](CONTRIBUTING.md). For local development, follow below steps.
+
+Install dependencies:
+
+```sh
+uv sync
+```
+
+Install pre-commit hooks (including `pre-commit`, `commit-msg`, and `pre-push`):
+
+```sh
+uv run prek install
+```
+
+Run tests:
+
+```sh
+uv run pytest -q
+```

tqlint-0.4.2/pyproject.toml

@@ -0,0 +1,153 @@
+[project]
+name = "tqlint"
+version = "0.4.2"
+description = "tq inspects a codebase's tests and enforces quality rules so tests remain discoverable, focused, actionable, and maintainable"
+readme = "README.md"
+license = "MIT"
+keywords = ["testing", "lint", "pytest", "quality", "developer-tools"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Quality Assurance",
+    "Topic :: Software Development :: Testing",
+    "Typing :: Typed",
+]
+authors = [
+    { name = "Stephen Lewis", email = "31178492+stelewis@users.noreply.github.com" }
+]
+requires-python = ">=3.11"
+dependencies = [
+    "click>=8.3.1",
+    "pyyaml>=6.0.3",
+    "rich>=14.3.2",
+]
+
+[project.scripts]
+tq = "tq.cli.main:main"
+tqlint = "tq.cli.main:main"
+
+[project.urls]
+Homepage = "https://github.com/stelewis/tq"
+Repository = "https://github.com/stelewis/tq"
+Issues = "https://github.com/stelewis/tq/issues"
+Changelog = "https://github.com/stelewis/tq/blob/main/CHANGELOG.md"
+
+[build-system]
+requires = ["uv_build>=0.10.4,<0.11.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "tq"
+
+[dependency-groups]
+dev = [
+    "bandit>=1.9.3",
+    "commitizen>=4.9.1",
+    "detect-secrets>=1.5.0",
+    "pip-audit>=2.10.0",
+    "prek>=0.3.1",
+    "pytest>=9.0.2",
+    "pytest-mock>=3.15.1",
+    "ruff>=0.15.0",
+    "ty>=0.0.14",
+]
+
+[tool.ruff]
+line-length = 88
+src = ["src"]
+extend-exclude = ["tmp"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+docstring-code-format = true
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = ["COM812"]  # Per docs guidance: recommended to ignore when using ruff format as formatter enforces consistent use of trailing commas
+
+[tool.ruff.lint.flake8-tidy-imports]
+ban-relative-imports = "all"
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = ["S101", "PLR2004"]
+
+[tool.ruff.lint.pylint]
+max-returns = 10
+
+[tool.pytest.ini_options]
+addopts = [
+    "--import-mode=importlib",
+    "-m",
+    "not integration and not e2e",
+]
+testpaths = ["tests"]
+markers = [
+    "e2e: mark end-to-end tests",
+    "golden: deterministic golden/snapshot fixture tests (offline)",
+    "integration: mark a test as an integration test",
+    "regression: mark tests that exercise known regressions",
+    "smoke: mark quick smoke tests",
+    "slow: mark slow tests that may be skipped in fast CI jobs",
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.commitizen]
+name = "cz_conventional_commits"
+version_provider = "uv"
+version_scheme = "semver"
+tag_format = "$version"
+update_changelog_on_bump = false
+changelog_file = "CHANGELOG.md"
+template = "CHANGELOG.md.j2"
+change_type_order = ["Added", "Changed", "Deprecated", "Removed", "Fixed", "Security"]
+gpg_sign = true
+major_version_zero = true
+
+[tool.commitizen.change_type_map]
+feat = "Added"
+fix = "Fixed"
+perf = "Changed"
+refactor = "Changed"
+docs = "Changed"
+chore = "Changed"
+build = "Changed"
+ci = "Changed"
+test = "Changed"
+style = "Changed"
+revert = "Changed"
+"breaking change" = "Changed"
+"BREAKING CHANGE" = "Changed"
+
+[tool.bandit]
+exclude_dirs = [
+    "tests",
+]
+
+[tool.ty.src]
+exclude = [
+    "tmp/scripts/**",
+]
+
+[tool.tq]
+source_root = "src"
+test_root = "tests"
+package = "tq"
+ignore_init_modules = true
+max_test_file_non_blank_lines = 600
+qualifier_strategy = "allowlist"
+allowed_qualifiers = [
+    "fixtures_golden",
+    "fixtures_synthetic",
+    "regression",
+    "config",
+]

tqlint-0.4.2/src/tq/__init__.py

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

tqlint-0.4.2/src/tq/cli/__init__.py

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

tqlint-0.4.2/src/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()

tqlint-0.4.2/src/tq/config/__init__.py

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