codetour-cli 0.1.0__py3-none-any.whl

codetour_cli/lint.py

@@ -0,0 +1,334 @@
+"""
+Step-level tour linting (ADR-0014).
+
+Checks tours against filesystem ground truth — the algorithmic half of the
+"algorithmic support to inference" duo: models author tours (inference),
+this module verifies what they wrote (algorithm).
+
+Boundary doctrine (ADR-0014): this linter never attempts `adr:...#qst-...`
+handle/deeplink resolution — that belongs to the vscode crew's `tour-lint`,
+which needs their parser/index. Step-level filesystem checks live here.
+
+Pure functions over Tour models + a workspace path; no CLI dependency.
+CLI wiring is deferred until json-source-edit's Phase 2b lands (ADR-0014,
+shared-worktree discipline).
+"""
+
+import json
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+
+from pydantic import ValidationError
+
+from .tour.schema import Tour
+
+# ADR-0014 check-family defaults. Namespaced IDs (`schema/`, `step/`, `tour/`)
+# are compatible with the Council-owned shared-taxonomy proposal (QST-TAXONOMY);
+# `ref/*` is reserved for the vscode crew's tour-lint.
+DEFAULT_SEVERITIES: Dict[str, str] = {
+    "schema/parse-error": "error",
+    "schema/invalid": "error",
+    "step/missing-file": "error",
+    "step/line-out-of-range": "error",
+    "step/pattern-invalid": "error",
+    "step/pattern-no-match": "error",
+    "step/pattern-ambiguous": "warn",
+    "tour/step-title-missing": "warn",
+    "tour/line-not-pattern": "warn",
+    "tour/next-tour-missing": "error",
+    "tour/is-primary-multiple": "warn",
+}
+
+
+@dataclass
+class Finding:
+    """One lint finding, addressable by check ID and location."""
+
+    check_id: str
+    severity: str
+    tour_file: str
+    message: str
+    step_index: Optional[int] = None  # 0-based; None for tour-level findings
+
+    def to_dict(self) -> dict:
+        return {
+            "check_id": self.check_id,
+            "severity": self.severity,
+            "tour_file": self.tour_file,
+            "step_index": self.step_index,
+            "message": self.message,
+        }
+
+
+def _severity(check_id: str, severities: Optional[Dict[str, str]]) -> str:
+    merged = dict(DEFAULT_SEVERITIES)
+    if severities:
+        merged.update(severities)
+    return merged.get(check_id, "warn")
+
+
+def _finding(
+    check_id: str,
+    tour_file: Path,
+    message: str,
+    step_index: Optional[int] = None,
+    severities: Optional[Dict[str, str]] = None,
+) -> Finding:
+    return Finding(
+        check_id=check_id,
+        severity=_severity(check_id, severities),
+        tour_file=str(tour_file),
+        message=message,
+        step_index=step_index,
+    )
+
+
+def _read_file_lines(path: Path) -> Optional[List[str]]:
+    """Read a workspace file's lines, byte-safe (no newline translation).
+
+    Returns None if the file is unreadable as UTF-8 text (binary etc.) —
+    callers treat that as "cannot check line/pattern", not as a finding.
+    """
+    try:
+        return path.read_bytes().decode("utf-8").splitlines()
+    except (OSError, UnicodeDecodeError):
+        return None
+
+
+def load_tour(tour_path: Path) -> Tuple[Optional[Tour], List[Finding]]:
+    """Parse + schema-validate one tour file.
+
+    Returns (tour, findings); tour is None when parse/validation failed.
+    """
+    findings: List[Finding] = []
+    try:
+        raw = tour_path.read_bytes().decode("utf-8")
+    except (OSError, UnicodeDecodeError) as exc:
+        findings.append(
+            _finding("schema/parse-error", tour_path, f"unreadable as UTF-8 text: {exc}")
+        )
+        return None, findings
+
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        findings.append(
+            _finding(
+                "schema/parse-error",
+                tour_path,
+                f"invalid JSON at line {exc.lineno}, column {exc.colno}: {exc.msg}",
+            )
+        )
+        return None, findings
+
+    try:
+        tour = Tour.model_validate(data)
+    except ValidationError as exc:
+        first = exc.errors()[0]
+        loc = ".".join(str(p) for p in first.get("loc", ())) or "(root)"
+        findings.append(
+            _finding(
+                "schema/invalid",
+                tour_path,
+                f"does not validate against the Tour schema: {loc}: {first.get('msg')}",
+            )
+        )
+        return None, findings
+
+    return tour, findings
+
+
+def lint_tour_file(
+    tour_path: Path,
+    workspace_root: Path,
+    severities: Optional[Dict[str, str]] = None,
+) -> Tuple[Optional[Tour], List[Finding]]:
+    """Lint one tour against the workspace. Returns (tour-or-None, findings)."""
+    tour, findings = load_tour(tour_path)
+    if tour is None:
+        return None, findings
+
+    long_lived = bool(tour.ref) or bool(tour.isPrimary)
+
+    for idx, step in enumerate(tour.steps):
+        # schema-level conflict the permissive model can't express
+        if step.file is not None and step.uri is not None:
+            findings.append(
+                _finding(
+                    "schema/invalid",
+                    tour_path,
+                    "step sets both `file` and `uri` (mutually exclusive per the CodeTour schema)",
+                    idx,
+                    severities,
+                )
+            )
+
+        if step.title is None:
+            findings.append(
+                _finding(
+                    "tour/step-title-missing",
+                    tour_path,
+                    "step has no `title` (headings inside `description` render oddly; set `title`)",
+                    idx,
+                    severities,
+                )
+            )
+
+        if step.directory is not None:
+            target_dir = workspace_root / step.directory
+            if not target_dir.is_dir():
+                findings.append(
+                    _finding(
+                        "step/missing-file",
+                        tour_path,
+                        f"directory does not exist in workspace: {step.directory}",
+                        idx,
+                        severities,
+                    )
+                )
+            continue  # directory steps carry no line/pattern checks
+
+        if step.uri is not None or step.file is None:
+            continue  # uri steps and content steps: no filesystem ground truth to check
+
+        target = workspace_root / step.file
+        if not target.is_file():
+            findings.append(
+                _finding(
+                    "step/missing-file",
+                    tour_path,
+                    f"file does not exist in workspace: {step.file}",
+                    idx,
+                    severities,
+                )
+            )
+            continue  # no line/pattern checks against a missing file
+
+        lines = _read_file_lines(target)
+
+        if step.pattern is not None:
+            try:
+                compiled = re.compile(step.pattern)
+            except re.error as exc:
+                findings.append(
+                    _finding(
+                        "step/pattern-invalid",
+                        tour_path,
+                        f"pattern does not compile as a regex: {exc}",
+                        idx,
+                        severities,
+                    )
+                )
+                compiled = None
+            if compiled is not None and lines is not None:
+                matches = sum(1 for line in lines if compiled.search(line))
+                if matches == 0:
+                    findings.append(
+                        _finding(
+                            "step/pattern-no-match",
+                            tour_path,
+                            f"pattern matches no line in {step.file}: {step.pattern!r}",
+                            idx,
+                            severities,
+                        )
+                    )
+                elif matches > 1:
+                    findings.append(
+                        _finding(
+                            "step/pattern-ambiguous",
+                            tour_path,
+                            f"pattern matches {matches} lines in {step.file} "
+                            "(CodeTour navigates to the first match)",
+                            idx,
+                            severities,
+                        )
+                    )
+        elif step.line is not None:
+            if lines is not None and not (1 <= step.line <= len(lines)):
+                findings.append(
+                    _finding(
+                        "step/line-out-of-range",
+                        tour_path,
+                        f"line {step.line} is outside {step.file} (1..{len(lines)})",
+                        idx,
+                        severities,
+                    )
+                )
+            if long_lived:
+                findings.append(
+                    _finding(
+                        "tour/line-not-pattern",
+                        tour_path,
+                        "long-lived tour (has `ref`/`isPrimary`) pins `line` without "
+                        "`pattern` — fragile across code changes",
+                        idx,
+                        severities,
+                    )
+                )
+
+    return tour, findings
+
+
+def lint_collection(
+    tour_paths: List[Path],
+    workspace_root: Path,
+    severities: Optional[Dict[str, str]] = None,
+) -> List[Finding]:
+    """Lint a set of tours together, adding cross-tour checks.
+
+    `nextTour` is matched liberally against sibling tour *titles* and
+    *filenames* (both appear in the wild — Postel's rule, per the
+    methodology's parse-liberally doctrine).
+    """
+    findings: List[Finding] = []
+    parsed: List[Tuple[Path, Tour]] = []
+
+    for tour_path in tour_paths:
+        tour, file_findings = lint_tour_file(tour_path, workspace_root, severities)
+        findings.extend(file_findings)
+        if tour is not None:
+            parsed.append((tour_path, tour))
+
+    known_names = set()
+    for tour_path, tour in parsed:
+        known_names.add(tour.title)
+        known_names.add(tour_path.name)
+        known_names.add(tour_path.stem)
+
+    primaries = [(p, t) for p, t in parsed if t.isPrimary]
+    if len(primaries) > 1:
+        names = ", ".join(p.name for p, _ in primaries)
+        for tour_path, _ in primaries:
+            findings.append(
+                _finding(
+                    "tour/is-primary-multiple",
+                    tour_path,
+                    f"{len(primaries)} tours set `isPrimary` ({names}); CodeTour expects one",
+                    None,
+                    severities,
+                )
+            )
+
+    for tour_path, tour in parsed:
+        if tour.nextTour and tour.nextTour not in known_names:
+            findings.append(
+                _finding(
+                    "tour/next-tour-missing",
+                    tour_path,
+                    f"`nextTour` target not found among sibling tour titles/filenames: "
+                    f"{tour.nextTour!r}",
+                    None,
+                    severities,
+                )
+            )
+
+    return findings
+
+
+def has_errors(findings: List[Finding], strict: bool = False) -> bool:
+    """CI gate: True if any finding is at error level (or any finding, when strict)."""
+    if strict:
+        return bool(findings)
+    return any(f.severity == "error" for f in findings)

codetour_cli/logging/__init__.py

@@ -0,0 +1,6 @@
+"""
+Logging module for migration operations.
+
+Implements structured logging with structlog for detailed audit trails of
+all migration decisions and operations.
+"""

codetour_cli/logging/setup.py

@@ -0,0 +1,63 @@
+"""
+Structured logging configuration using structlog.
+
+Provides comprehensive logging for all migration operations with clear audit trails.
+"""
+
+import logging
+import sys
+import structlog
+from typing import Optional
+
+
+def configure_logging(
+    level: str = "INFO",
+    use_colors: bool = True,
+    use_json: bool = False
+) -> None:
+    """
+    Configure structured logging for the application.
+
+    Args:
+        level: Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+        use_colors: Whether to use colored output (for terminals)
+        use_json: Whether to output JSON format (for parsing)
+    """
+    processors = [
+        structlog.contextvars.merge_contextvars,
+        structlog.processors.add_log_level,
+        structlog.processors.StackInfoRenderer(),
+        structlog.dev.set_exc_info,
+        structlog.processors.TimeStamper(fmt="iso"),
+    ]
+
+    if use_json:
+        processors.append(structlog.processors.JSONRenderer())
+    else:
+        if use_colors:
+            processors.append(structlog.dev.ConsoleRenderer())
+        else:
+            processors.append(structlog.dev.ConsoleRenderer(colors=False))
+
+    structlog.configure(
+        processors=processors,
+        wrapper_class=structlog.make_filtering_bound_logger(
+            getattr(logging, level.upper(), logging.INFO)
+        ),
+        context_class=dict,
+        logger_factory=structlog.PrintLoggerFactory(file=sys.stderr),
+        cache_logger_on_first_use=True,
+    )
+
+
+def get_logger(name: Optional[str] = None) -> structlog.BoundLogger:
+    """
+    Get a logger instance.
+
+    Args:
+        name: Optional logger name (typically module name)
+
+    Returns:
+        Configured structlog logger
+    """
+    return structlog.get_logger(name)

codetour_cli/migration/__init__.py

@@ -0,0 +1,6 @@
+"""
+Migration module for tracking line changes across Git commits.
+
+This module implements both direct (A→C) and step-by-step (A→B→C) migration
+strategies for updating CodeTour line references.
+"""