v0.8.2: Quality Rules CLI and Integration

[octo-youcef]

Summary

Completes the quality rules feature that shipped incomplete in v0.8.1. Adds CLI commands, executor, and schema compatibility fixes so users can actually run quality checks.

Context: v0.8.1 shipped foundation (models, queries, formatters) but no CLI interface. Users couldn't use the feature. v0.8.2 completes it.

Changes

CLI Commands (Commit 1)

• mapper quality list - Show all available rules
• mapper quality check <package> - Run all enabled rules
• mapper quality type-coverage <package> - Check type hints
• mapper quality docstring-coverage <package> - Check docstrings
• mapper quality param-complexity <package> - Check param counts
• Support for --json / --csv output formats
• Exit codes for CI/CD (0 = pass, 1 = fail)

Executor (Commit 1)

• QualityExecutor class for running rules against Neo4j
• execute(rule_name, package, config) - Single rule with validation
• execute_all(package, config) - All enabled rules
• Config loading from mapper.toml
• Error handling for missing/disabled rules

Schema Compatibility Fixes (Commit 2)

Problem: Quality rules expected properties that don't exist in current Neo4j schema

• Expected: Function.file_path, Function.parameters array, Function.start_line
• Actual: Module.path, Parameter nodes, no line numbers

Solution:

• Get file paths from Module.path via DEFINES relationships
• Count parameters via HAS_PARAMETER relationships (not array property)
• Defer line numbers to v0.8.4 (GitHub issue Store line numbers for functions/methods/classes #87 created)

Testing (Commit 1, 4)

• 17 new unit tests (executor + CLI)
• 290 total unit tests passing (81% coverage)
• Manual test against datalake/utils (32 functions):
  • Type coverage: 100% ✓
  • Docstring coverage: 50% ✗
  • Param complexity: 1 violation ✗

Commit Structure

1. Add CLI commands and executor - User-facing interface + execution engine
2. Fix quality rules schema - Make queries work with current graph structure
3. Fix linting - Remove unused import, format code
4. Rename test file - Avoid pytest collection conflict
5. Update CHANGELOG - Document v0.8.2 changes
6. Bump version - 0.8.1 → 0.8.2

What to Review

Critical: Schema Compatibility (Commit 2)

The quality rules now query the graph differently than originally designed:

type_coverage.py (lines 41-64):

MATCH (m:Module)-[:DEFINES]->(f:Function {package: $package})
WHERE f.is_public = true

OPTIONAL MATCH (f)-[:HAS_PARAMETER]->(p:Parameter)
WITH m, f,
     count(p) as total_params,
     sum(CASE WHEN p.has_type_hint = true THEN 1 ELSE 0 END) as typed_params
...
RETURN m.path as file_path

Review:

• ✅ Does the query logic match the existing Neo4j schema?
• ✅ Are we correctly using HAS_PARAMETER relationships?
• ✅ Is getting file_path from Module.path the right approach?

Tradeoff: Line numbers deferred to v0.8.4 (issue #87). Output shows line: null. Acceptable?

Important: CLI Interface (Commit 1)

quality.py (lines 40-128 for check command):

@app.command()
def check(
    package: str,
    format_type: OutputFormat = typer.Option(...),
    json_flag: bool = typer.Option(False, "--json"),
    csv_flag: bool = typer.Option(False, "--csv"),
    ...
) -> None:
    # Execute all rules
    exec = executor.QualityExecutor(connection)
    results = exec.execute_all(package, quality_config)
    
    # Exit with appropriate code
    all_passed = all(result.status == "pass" for result in results)
    raise typer.Exit(code=0 if all_passed else 1)

Review:

• ✅ Is the command naming intuitive? (check vs run, type-coverage vs type_coverage)
• ✅ Are the flags clear? (--json shorthand vs --format json)
• ✅ Is exit code logic correct for CI/CD?

Code Quality

executor.py (lines 28-86):

• ✅ Error handling comprehensive enough?
• ✅ Config loading logic (from param vs from file)?
• ✅ "No rules enabled" error helpful?

Test coverage:

• ✅ 17 new tests sufficient for CLI + executor?
• ✅ Mock-based unit tests appropriate here?

Documentation

CHANGELOG.md (lines 10-54):

• ✅ Clearly explains what's new in v0.8.2?
• ✅ Schema compatibility fixes documented?
• ✅ Note about completing v0.8.1 feature clear?

Manual Test Results

Tested against ~/repos/datalake/datalake/utils (32 public functions):

mapper quality check utils

✗ Docstring Coverage: 50.0% (threshold: 90%)
✗ Param Complexity: 1 violation (max: 5 parameters)
✓ Type Coverage: 100.0% (threshold: 80%)

2 of 3 checks failed

JSON output validated, exit codes working correctly.

Before Merge

• Review schema compatibility approach (commit 2)
• Validate CLI interface ergonomics (commit 1)
• Confirm line number deferral acceptable
• Check test coverage sufficient
• Verify CHANGELOG complete

Related Issues

• Completes incomplete v0.8.1 feature
• Created Store line numbers for functions/methods/classes #87 for line number storage (v0.8.4)

[ydkadri]

Some initial feedback

[ydkadri]

Can we create a separate private _quality_helpers module for this. Can we also add an issue to do the same for query helpers

[octo-youcef]

✅ Addressed PR Feedback

Comment 1: Match queries API pattern

Changed CLI interface to match pattern:

Before:

mapper quality check <package>
mapper quality type-coverage <package>

After:

mapper quality run all --package <pkg>
mapper quality run type-coverage --package <pkg>

Changes:

• Simplified to 2 commands: list and run
• run takes check name as argument (not separate commands)
• Package is now required --package option (like queries)
• Special all value (case insensitive) runs all enabled checks

Comment 2: Extract helpers to separate module

Created src/mapper/cli/_quality_helpers.py:

• Extracted run_quality_checks() function
• Handles connection, execution, formatting, error handling
• 95 lines of logic moved out of CLI command file
• Easier to test and maintain

Created GitHub issue #89 for query CLI helpers refactoring (same pattern).

---

Testing:

• 289 unit tests passing (down from 290 - simplified tests for new API)
• All linting checks pass
• Code formatted and clean

Next: Ready for re-review with new API pattern.

[octo-youcef]

✅ Ready for Final Review

All feedback addressed, tests passing, documentation updated.

Summary

• 7 commits: Clean, logical progression from implementation → fixes → version bump → API refactoring
• 289 unit tests passing (81% coverage)
• All linting checks pass (ruff, isort, mypy)
• CHANGELOG updated for v0.8.2
• Version bumped to 0.8.2
• API matches queries pattern: mapper quality run <check> --package <pkg>

What Changed Since Draft

• Refactored CLI to match mapper query run API pattern
• Extracted helpers to _quality_helpers.py module
• Simplified from 4 commands to 2 (list and run)
• Created issue Extract query CLI helpers to separate module #89 for applying same pattern to query CLI

CI Status

• Unit tests: ✅ (289 passing, checked locally)
• Integration tests: ⏭️ Skipped (no Neo4j credentials in test run - expected)

Ready to merge after approval! 🚀