codetour-cli 0.1.0__tar.gz → 0.2.0__tar.gz

{codetour_cli-0.1.0 → codetour_cli-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codetour-cli
-Version: 0.1.0
+Version: 0.2.0
 Summary: Algorithmic maintenance of CodeTour files — an unofficial companion CLI for the CodeTour VS Code extension
 Author: Jérémie Lumbroso
 License: MIT

{codetour_cli-0.1.0 → codetour_cli-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "codetour-cli"
-version = "0.1.0"
+version = "0.2.0"
 description = "Algorithmic maintenance of CodeTour files — an unofficial companion CLI for the CodeTour VS Code extension"
 authors = [{name = "Jérémie Lumbroso"}]
 readme = "README.md"

{codetour_cli-0.1.0 → codetour_cli-0.2.0}/src/codetour_cli/cli.py

@@ -319,6 +319,77 @@ def load_parsing_schema(report_content: str) -> ParsingSchema:
     return schema
 
 
+def select_review_steps(review, auto_approve_above: Optional[float] = None):
+    """
+    Decide which parsed review steps to apply.
+
+    Base set: steps the human checked (the report workflow's contract).
+    With auto_approve_above set (0.0-1.0), UNCHECKED steps whose confidence
+    clears the threshold are promoted in as well -- except steps marked for
+    deletion, which are never auto-approved: removing a step from a tour is
+    destructive and stays behind an explicit human checkbox regardless of
+    confidence (the same never-auto principle the migrate path applies).
+
+    Returns (selected_steps, promoted_steps) -- promoted ⊆ selected.
+    """
+    selected = list(review.get_corrected_steps())
+    promoted = []
+    if auto_approve_above is not None:
+        cutoff = auto_approve_above * 100.0
+        already = {s.step_number for s in selected}
+        for r in review.step_reviews:
+            if r.step_number in already or r.status_checked:
+                continue
+            if r.is_marked_for_deletion():
+                continue
+            if r.confidence is not None and r.confidence >= cutoff:
+                promoted.append(r)
+        selected.extend(promoted)
+        selected.sort(key=lambda s: s.step_number)
+    return selected, promoted
+
+
+def clean_stale_review_reports(
+    tours_dir: Path,
+    tour_name: str,
+    keep: Optional[Path],
+    dry_run: bool = False,
+) -> list:
+    """
+    Remove MIGRATION-REVIEW-{tour_name}-*.md reports for OTHER target
+    commits than the current run's (whose report, if any, is `keep`).
+
+    Matching is by literal prefix/suffix on the filename, deliberately not
+    glob (tour names are user-controlled; glob metacharacters in a name
+    must not widen the match). In dry_run, returns the candidates without
+    deleting. Returns the list of removed (or would-remove) paths.
+    """
+    prefix = f"MIGRATION-REVIEW-{tour_name}-"
+    removed = []
+    if not tours_dir.is_dir():
+        return removed
+    for p in sorted(tours_dir.iterdir()):
+        if not (p.is_file() and p.name.startswith(prefix) and p.name.endswith(".md")):
+            continue
+        if keep is not None and p.name == keep.name:
+            continue
+        if not dry_run:
+            p.unlink()
+        removed.append(p)
+    return removed
+
+
+def resolve_context_lines(args, config: dict) -> int:
+    """CLI flag wins over config review.context_lines; default 7; floor 0."""
+    cli_val = getattr(args, 'context_lines', None)
+    if cli_val is not None:
+        return max(0, cli_val)
+    try:
+        return max(0, int(config.get('review', {}).get('context_lines', 7)))
+    except (TypeError, ValueError):
+        return 7
+
+
 def generate_review_report(
     tour_path: Path,
     result,
@@ -327,7 +398,8 @@ def generate_review_report(
     repo_root: Path,
     is_dry_run: bool = False,
     no_guidance: bool = False,
-    threshold: Optional[float] = None
+    threshold: Optional[float] = None,
+    context_lines: int = 7
 ) -> Optional[Path]:
     """
     Generate a markdown review report for migrations with low-confidence steps.
@@ -469,8 +541,8 @@ def generate_review_report(
             new_line = None
 
         # Get code context for old and new locations (from specific commits)
-        old_context = get_code_context(repo_root, old_file, old_line, source_commit) if old_line else "(No line number)"
-        new_context = get_code_context(repo_root, new_file, new_line, target_commit) if new_line and update.new_location else "(File deleted)"
+        old_context = get_code_context(repo_root, old_file, old_line, source_commit, context_lines=context_lines) if old_line else "(No line number)"
+        new_context = get_code_context(repo_root, new_file, new_line, target_commit, context_lines=context_lines) if new_line and update.new_location else "(File deleted)"
 
         # Quote the description with chevrons
         quoted_description = quote_with_chevrons(step.description)
@@ -794,6 +866,22 @@ Examples:
         dest='auto_approve',
         help='Automatically approve all changes (skip confirmation prompts)'
     )
+    apply_review_parser.add_argument(
+        '--auto-approve-above',
+        type=float,
+        dest='auto_approve_above',
+        metavar='X',
+        help=(
+            'Additionally apply UNCHECKED steps whose confidence >= X '
+            '(0.0-1.0), on top of the checked ones. Steps marked for '
+            'deletion are never auto-approved -- destructive actions stay '
+            'behind an explicit human checkbox. Note: confidence only ever '
+            'takes 5 exact values (see docs/adr/0016-*.md), so a threshold '
+            'between quanta behaves like the nearest quantum above it. '
+            'ADR-0003\'s "batch approve all above confidence X", in the '
+            'report-based workflow that ADR-0007 shipped.'
+        )
+    )
 
     # migrate command
     migrate_parser = subparsers.add_parser(
@@ -860,6 +948,27 @@ Examples:
         dest='no_lint',
         help='Skip the advisory post-migration lint pass (ADR-0014)'
     )
+    migrate_parser.add_argument(
+        '--clean-reviews',
+        action='store_true',
+        dest='clean_reviews',
+        help=(
+            'After migrating each tour, delete stale MIGRATION-REVIEW-'
+            '{tour}-*.md reports left over from earlier target commits '
+            '(the report for THIS run, if any, is kept). In --dry-run, '
+            'lists what would be cleaned without deleting.'
+        )
+    )
+    migrate_parser.add_argument(
+        '--context-lines',
+        type=int,
+        dest='context_lines',
+        metavar='N',
+        help=(
+            'Lines of code context above/below each reviewed line in the '
+            'review report (default: from config review.context_lines, 7)'
+        )
+    )
 
     args = parser.parse_args()
 
@@ -1451,13 +1560,24 @@ def apply_review_command(args, config: dict) -> int:
         print(f"❌ Failed to load tour: {e}", file=sys.stderr)
         return 2
 
-    # Get only reviewed steps (checkbox checked)
-    corrected_steps = review.get_corrected_steps()
+    # Reviewed steps (checkbox checked), plus -- with --auto-approve-above X --
+    # unchecked steps whose confidence clears the threshold (never deletions).
+    auto_above = getattr(args, 'auto_approve_above', None)
+    if auto_above is not None and not (0.0 <= auto_above <= 1.0):
+        print(f"❌ --auto-approve-above must be between 0.0 and 1.0 (got {auto_above})", file=sys.stderr)
+        return 2
+
+    corrected_steps, promoted_steps = select_review_steps(review, auto_above)
+    if promoted_steps:
+        nums = ", ".join(str(s.step_number) for s in promoted_steps)
+        print(f"🔓 Auto-approving {len(promoted_steps)} unchecked step(s) at confidence ≥ {auto_above:.0%}: {nums}")
 
     if not corrected_steps:
         print("ℹ️  No corrections found in review report")
         print("   The report may not have been edited, or no checkboxes were marked")
         print("   Tip: Check the 'Status' checkbox for steps you want to apply")
+        if auto_above is not None:
+            print(f"   (--auto-approve-above {auto_above} promoted nothing: no unchecked, non-deletion step at that confidence)")
         return 0
 
     # Apply corrections
@@ -1849,6 +1969,7 @@ def migrate_all_tours(args, config: dict) -> int:
             print_migration_summary(result, tour_name, is_dry_run)
 
             # Generate review report if needed
+            report_path = None
             if result.num_needs_review > 0:
                 report_path = generate_review_report(
                     tour_path=tour_info.path,
@@ -1858,7 +1979,8 @@ def migrate_all_tours(args, config: dict) -> int:
                     repo_root=repo_info.repo_path,
                     is_dry_run=is_dry_run,
                     no_guidance=getattr(args, 'no_guidance', False),
-                    threshold=threshold
+                    threshold=threshold,
+                    context_lines=resolve_context_lines(args, config)
                 )
                 if report_path:
                     review_reports.append(report_path)
@@ -1867,6 +1989,20 @@ def migrate_all_tours(args, config: dict) -> int:
                     else:
                         print(f"  📄 Review report: {report_path.relative_to(repo_info.repo_path)}")
 
+            # Optionally clean stale reports from earlier target commits
+            # (keyed on the just-generated report's actual filename -- never
+            # re-derived, since to_commit may be symbolic like "HEAD").
+            if getattr(args, 'clean_reviews', False):
+                stale = clean_stale_review_reports(
+                    tours_dir=tour_info.path.parent,
+                    tour_name=tour_info.path.stem,
+                    keep=report_path,
+                    dry_run=is_dry_run,
+                )
+                if stale:
+                    verb = "Would clean" if is_dry_run else "Cleaned"
+                    print(f"  🧹 {verb} {len(stale)} stale review report(s): " + ", ".join(p.name for p in stale))
+
         except Exception as e:
             log.error("migration_failed", tour=tour_name, error=str(e))
             print(f"  ❌ Failed: {e}\n")

{codetour_cli-0.1.0 → codetour_cli-0.2.0}/src/codetour_cli/config.py

@@ -24,6 +24,14 @@ DEFAULT_CONFIG = {
     "display": {
         "color": True,
         "verbosity": "normal",
+    },
+    "review": {
+        # Lines of code context above/below each reviewed line in review
+        # reports. Ratified at 7 (the shipped default) over ADR-0007's
+        # original ±3 recommendation, made configurable per Jérémie's
+        # 2026-08-29 answer ("so we don't leave people... without a way
+        # to tweak the tool to their context").
+        "context_lines": 7,
     }
 }
 
@@ -57,6 +65,12 @@ display:
 
   # Verbosity level (quiet, normal, verbose)
   verbosity: normal
+
+# Review report preferences
+review:
+  # Lines of code context above/below each reviewed line (override per
+  # run with `migrate --context-lines N`)
+  context_lines: 7
 """
 
 

{codetour_cli-0.1.0 → codetour_cli-0.2.0}/src/codetour_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codetour-cli
-Version: 0.1.0
+Version: 0.2.0
 Summary: Algorithmic maintenance of CodeTour files — an unofficial companion CLI for the CodeTour VS Code extension
 Author: Jérémie Lumbroso
 License: MIT

{codetour_cli-0.1.0 → codetour_cli-0.2.0}/src/codetour_cli.egg-info/SOURCES.txt

@@ -40,6 +40,7 @@ tests/test_logging_setup.py
 tests/test_pattern_validation.py
 tests/test_post_migration_lint.py
 tests/test_review_roundtrip.py
+tests/test_review_workflow_options.py
 tests/test_scenarios.py
 tests/test_schema_validation.py
 tests/test_stepwise_migration.py

codetour_cli-0.2.0/tests/test_review_workflow_options.py

@@ -0,0 +1,170 @@
+"""Tests for the answer-driven review-workflow options (2026-08-29).
+
+ADR-0003's QST-REVIEW-INTERFACE-FUTURE and ADR-0007's three QSTs were
+answered by Jérémie on 2026-08-29; this file covers the three features
+those answers approved:
+
+- `apply-review --auto-approve-above X` -- ADR-0003's decided "batch
+  approve all above confidence X", delivered inside the report-based
+  workflow ADR-0007 shipped. Selection semantics tested at the function
+  seam (`select_review_steps`) with the real parser dataclasses.
+- `migrate --clean-reviews` -- stale-report cleanup (ADR-0007
+  QST "Report persistence", Jérémie: "the excellent idea of a
+  `--clean-reviews` option"). Tested against real files on disk.
+- configurable review context lines (ADR-0007 QST "Code snippet
+  length", Jérémie: "would love if this could be customizable").
+"""
+
+from types import SimpleNamespace
+
+from codetour_cli.cli import (
+    clean_stale_review_reports,
+    resolve_context_lines,
+    select_review_steps,
+)
+from codetour_cli.review_parser import ReviewReport, StepReview
+
+
+def _step(n, checked=False, confidence=None, file="src/x.py", line=10):
+    return StepReview(
+        step_number=n,
+        status_checked=checked,
+        tentative_file=file,
+        tentative_line=line,
+        confidence=confidence,
+    )
+
+
+def _report(steps):
+    return ReviewReport(
+        tour_name="demo.tour",
+        source_commit="aaaa1111",
+        target_commit="bbbb2222",
+        mode="live",
+        step_reviews=steps,
+    )
+
+
+class TestSelectReviewSteps:
+    def test_without_threshold_only_checked_steps_apply(self):
+        review = _report([_step(1, checked=True), _step(2, confidence=95)])
+        selected, promoted = select_review_steps(review, None)
+        assert [s.step_number for s in selected] == [1]
+        assert promoted == []
+
+    def test_promotes_unchecked_steps_at_or_above_cutoff(self):
+        review = _report([
+            _step(1, checked=True, confidence=50),
+            _step(2, confidence=85),   # promoted at 0.8
+            _step(3, confidence=50),   # below cutoff, stays out
+            _step(4, confidence=80),   # exactly at cutoff: >= semantics
+        ])
+        selected, promoted = select_review_steps(review, 0.8)
+        assert [s.step_number for s in selected] == [1, 2, 4]
+        assert [s.step_number for s in promoted] == [2, 4]
+
+    def test_deletion_marked_steps_are_never_auto_promoted(self):
+        # Removing a step from a tour is destructive -- confidence must not
+        # bypass the explicit human checkbox, no matter how high.
+        deletion = _step(2, confidence=99, file="-", line=None)
+        assert deletion.is_marked_for_deletion()
+        review = _report([_step(1, confidence=90), deletion])
+        selected, promoted = select_review_steps(review, 0.5)
+        assert [s.step_number for s in selected] == [1]
+        assert deletion not in selected
+
+    def test_checked_deletion_still_applies_as_before(self):
+        # The human explicitly checked it: pre-existing behavior unchanged.
+        deletion = _step(2, checked=True, file="-", line=None)
+        review = _report([deletion])
+        selected, _ = select_review_steps(review, 0.9)
+        assert selected == [deletion]
+
+    def test_confidence_none_is_never_promoted(self):
+        review = _report([_step(1, confidence=None)])
+        selected, promoted = select_review_steps(review, 0.0)
+        assert selected == [] and promoted == []
+
+    def test_selection_is_ordered_by_step_number(self):
+        review = _report([
+            _step(5, confidence=90),
+            _step(1, checked=True),
+            _step(3, confidence=90),
+        ])
+        selected, _ = select_review_steps(review, 0.5)
+        assert [s.step_number for s in selected] == [1, 3, 5]
+
+
+class TestCleanStaleReviewReports:
+    def _seed(self, tours_dir):
+        names = [
+            "MIGRATION-REVIEW-demo-aaaa1111.md",   # stale (other commit)
+            "MIGRATION-REVIEW-demo-bbbb2222.md",   # current run's report
+            "MIGRATION-REVIEW-demo-cccc3333.md",   # stale (other commit)
+            "MIGRATION-REVIEW-other-dddd4444.md",  # different tour: untouched
+            "MIGRATION-REVIEW-demo-notes.txt",     # not .md: untouched
+        ]
+        for n in names:
+            (tours_dir / n).write_text("x", encoding="utf-8")
+        return names
+
+    def test_removes_only_this_tours_stale_md_reports(self, tmp_path):
+        self._seed(tmp_path)
+        keep = tmp_path / "MIGRATION-REVIEW-demo-bbbb2222.md"
+        removed = clean_stale_review_reports(tmp_path, "demo", keep=keep)
+        assert sorted(p.name for p in removed) == [
+            "MIGRATION-REVIEW-demo-aaaa1111.md",
+            "MIGRATION-REVIEW-demo-cccc3333.md",
+        ]
+        assert keep.exists()
+        assert (tmp_path / "MIGRATION-REVIEW-other-dddd4444.md").exists()
+        assert (tmp_path / "MIGRATION-REVIEW-demo-notes.txt").exists()
+        assert not (tmp_path / "MIGRATION-REVIEW-demo-aaaa1111.md").exists()
+
+    def test_keep_none_cleans_every_report_for_the_tour(self, tmp_path):
+        # A run that needed no review generates no report: everything
+        # stale for that tour goes.
+        self._seed(tmp_path)
+        removed = clean_stale_review_reports(tmp_path, "demo", keep=None)
+        assert len(removed) == 3
+        assert (tmp_path / "MIGRATION-REVIEW-other-dddd4444.md").exists()
+
+    def test_dry_run_lists_candidates_without_deleting(self, tmp_path):
+        self._seed(tmp_path)
+        keep = tmp_path / "MIGRATION-REVIEW-demo-bbbb2222.md"
+        removed = clean_stale_review_reports(tmp_path, "demo", keep=keep, dry_run=True)
+        assert len(removed) == 2
+        for p in removed:
+            assert p.exists()
+
+    def test_prefix_match_is_literal_not_glob(self, tmp_path):
+        # A tour named with glob metacharacters must only match itself --
+        # glob would let "a[b]" match "ab" and delete another tour's report.
+        (tmp_path / "MIGRATION-REVIEW-a[b]-aaaa1111.md").write_text("x", encoding="utf-8")
+        (tmp_path / "MIGRATION-REVIEW-ab-aaaa1111.md").write_text("x", encoding="utf-8")
+        removed = clean_stale_review_reports(tmp_path, "a[b]", keep=None)
+        assert [p.name for p in removed] == ["MIGRATION-REVIEW-a[b]-aaaa1111.md"]
+        assert (tmp_path / "MIGRATION-REVIEW-ab-aaaa1111.md").exists()
+
+    def test_missing_tours_dir_is_a_noop(self, tmp_path):
+        assert clean_stale_review_reports(tmp_path / "absent", "demo", keep=None) == []
+
+
+class TestResolveContextLines:
+    def test_cli_flag_wins_over_config(self):
+        args = SimpleNamespace(context_lines=3)
+        assert resolve_context_lines(args, {"review": {"context_lines": 12}}) == 3
+
+    def test_config_used_when_no_flag(self):
+        args = SimpleNamespace(context_lines=None)
+        assert resolve_context_lines(args, {"review": {"context_lines": 12}}) == 12
+
+    def test_default_is_the_ratified_seven(self):
+        assert resolve_context_lines(SimpleNamespace(context_lines=None), {}) == 7
+
+    def test_negative_values_floor_to_zero(self):
+        assert resolve_context_lines(SimpleNamespace(context_lines=-4), {}) == 0
+
+    def test_garbage_config_falls_back_to_seven(self):
+        args = SimpleNamespace(context_lines=None)
+        assert resolve_context_lines(args, {"review": {"context_lines": "many"}}) == 7