@pennyfarthing/core 10.1.0 → 10.2.0

package/pennyfarthing_scripts/brownfield/discover.py

@@ -11,7 +11,6 @@ import re
 from dataclasses import dataclass, field
 from enum import Enum
 from pathlib import Path
-from typing import Literal
 
 # Try to import tomllib (Python 3.11+) or fall back to tomli
 try:
@@ -642,7 +641,7 @@ def generate_ai_guidance_doc(result: DiscoveryResult) -> str:
 
     if result.tech_stack:
         # Get unique tech names
-        tech_names = sorted(set(item.name.lower() for item in result.tech_stack))[:10]
+        tech_names = sorted({item.name.lower() for item in result.tech_stack})[:10]
         lines.extend([
             "## Key Technologies",
             "",

package/pennyfarthing_scripts/cli.py

@@ -31,35 +31,40 @@ def cli():
 
 
 # Import and register sprint group (lazy registration preserves startup time)
-from pennyfarthing_scripts.sprint.cli import sprint
+from pennyfarthing_scripts.sprint.cli import sprint  # noqa: E402
 
 cli.add_command(sprint)
 
 # Import and register hotspots group
-from pennyfarthing_scripts.hotspots.cli import hotspots
+from pennyfarthing_scripts.hotspots.cli import hotspots  # noqa: E402
 
 cli.add_command(hotspots)
 
 # Import and register jira group
-from pennyfarthing_scripts.jira.cli import jira
+from pennyfarthing_scripts.jira.cli import jira  # noqa: E402
 
 cli.add_command(jira)
 
 # Import and register deadcode group
-from pennyfarthing_scripts.deadcode.cli import deadcode
+from pennyfarthing_scripts.deadcode.cli import deadcode  # noqa: E402
 
 cli.add_command(deadcode)
 
 # Import and register theme group
-from pennyfarthing_scripts.theme.cli import theme
+from pennyfarthing_scripts.theme.cli import theme  # noqa: E402
 
 cli.add_command(theme)
 
 # Import and register healthscore group
-from pennyfarthing_scripts.healthscore.cli import healthscore
+from pennyfarthing_scripts.healthscore.cli import healthscore  # noqa: E402
 
 cli.add_command(healthscore)
 
+# Import and register validate group
+from pennyfarthing_scripts.validate.cli import validate  # noqa: E402
+
+cli.add_command(validate)
+
 
 @cli.group()
 def agent():

package/pennyfarthing_scripts/codemarkers/__init__.py

@@ -2,18 +2,22 @@
 Code marker analysis — TODO, FIXME, HACK, XXX detection with git blame.
 
 Story 80-1: Python codemarkers module.
+Story 80-2: @deprecated detection and caller cross-reference.
 """
 
+from pennyfarthing_scripts.codemarkers.analyze import analyze_deprecations, analyze_repo
 from pennyfarthing_scripts.codemarkers.models import (
     CodeMarker,
     CodeMarkersResult,
+    DeprecationMarker,
     MarkerSummary,
 )
-from pennyfarthing_scripts.codemarkers.analyze import analyze_repo
 
 __all__ = [
     "CodeMarker",
     "CodeMarkersResult",
+    "DeprecationMarker",
     "MarkerSummary",
+    "analyze_deprecations",
     "analyze_repo",
 ]

package/pennyfarthing_scripts/codemarkers/analyze.py

@@ -12,12 +12,13 @@ import fnmatch
 import re
 import time
 from collections import defaultdict
-from datetime import datetime, timezone
+from datetime import UTC, datetime
 from pathlib import Path
 
 from pennyfarthing_scripts.codemarkers.models import (
     CodeMarker,
     CodeMarkersResult,
+    DeprecationMarker,
     MarkerSummary,
 )
 
@@ -286,7 +287,7 @@ async def analyze_repo(
             if author_time > 0:
                 age_days = (now - author_time) / 86400
                 date_str = datetime.fromtimestamp(
-                    author_time, tz=timezone.utc
+                    author_time, tz=UTC
                 ).isoformat()
             else:
                 age_days = 0.0
@@ -324,3 +325,177 @@ async def analyze_repo(
         markers=markers,
         summary=summary,
     )
+
+
+# =============================================================================
+# @deprecated detection (Story 80-2)
+# =============================================================================
+
+# File extensions to scan for @deprecated JSDoc tags
+_DEPRECATION_EXTENSIONS = frozenset({".ts", ".tsx", ".js"})
+
+# Pattern to find @deprecated in JSDoc comments
+_DEPRECATED_PATTERN = re.compile(r"@deprecated\b(.*)")
+
+# Pattern to extract symbol name from export declarations
+_SYMBOL_PATTERN = re.compile(
+    r"export\s+(?:default\s+)?(?:function|class|const|let|var|interface|type|enum)\s+(\w+)"
+)
+
+
+def _grep_deprecations(root: Path, excludes: list[str]) -> list[dict]:
+    """Scan TypeScript/JS files for @deprecated JSDoc tags.
+
+    For each @deprecated tag found, extracts the symbol name from the
+    next export declaration line following the JSDoc block.
+
+    Args:
+        root: Directory to scan recursively
+        excludes: Glob patterns for files/dirs to skip
+
+    Returns:
+        List of dicts: {path, line, symbol, text}
+    """
+    results: list[dict] = []
+
+    for file_path in sorted(root.rglob("*")):
+        if not file_path.is_file():
+            continue
+
+        if file_path.suffix.lower() not in _DEPRECATION_EXTENSIONS:
+            continue
+
+        rel_path = str(file_path.relative_to(root))
+
+        if _should_exclude(rel_path, excludes):
+            continue
+
+        try:
+            content = file_path.read_text(encoding="utf-8", errors="strict")
+        except (UnicodeDecodeError, OSError):
+            continue
+
+        lines = content.split("\n")
+        for line_num, line_text in enumerate(lines, start=1):
+            match = _DEPRECATED_PATTERN.search(line_text)
+            if not match:
+                continue
+
+            # Extract the @deprecated text
+            deprecated_text = line_text.strip()
+
+            # Look ahead for the symbol declaration
+            symbol = ""
+            for ahead in lines[line_num:]:  # line_num is already 1-indexed, so lines[line_num:] starts after current
+                sym_match = _SYMBOL_PATTERN.search(ahead)
+                if sym_match:
+                    symbol = sym_match.group(1)
+                    break
+                # Stop looking if we hit another JSDoc or a blank line after the block closes
+                stripped = ahead.strip()
+                if stripped and not stripped.startswith("*") and not stripped.startswith("/") and not stripped == "":
+                    break
+
+            if symbol:
+                results.append({
+                    "path": rel_path,
+                    "line": line_num,
+                    "symbol": symbol,
+                    "text": deprecated_text,
+                })
+
+    return results
+
+
+def _count_callers(
+    symbol: str, root: Path, defining_file: str
+) -> tuple[int, list[str]]:
+    """Count files that import/reference a deprecated symbol.
+
+    Greps all TypeScript/JS files for the symbol name, excluding
+    the file that defines it.
+
+    Args:
+        symbol: The deprecated symbol name to search for
+        root: Directory to scan
+        defining_file: Relative path of the file defining the symbol (excluded)
+
+    Returns:
+        (caller_count, list_of_caller_paths)
+    """
+    callers: list[str] = []
+
+    for file_path in sorted(root.rglob("*")):
+        if not file_path.is_file():
+            continue
+
+        if file_path.suffix.lower() not in _DEPRECATION_EXTENSIONS:
+            continue
+
+        rel_path = str(file_path.relative_to(root))
+
+        if rel_path == defining_file:
+            continue
+
+        try:
+            content = file_path.read_text(encoding="utf-8", errors="strict")
+        except (UnicodeDecodeError, OSError):
+            continue
+
+        if symbol in content:
+            callers.append(rel_path)
+
+    return len(callers), callers
+
+
+async def analyze_deprecations(
+    path: Path,
+    excludes: list[str] | None = None,
+) -> dict:
+    """Analyze a directory for @deprecated symbols and their callers.
+
+    Args:
+        path: Directory to scan
+        excludes: Additional file patterns to exclude
+
+    Returns:
+        Dict with success, deprecations (list of DeprecationMarker),
+        summary (total_deprecations, deprecations_with_callers), and
+        optionally error.
+    """
+    resolved = Path(path).resolve()
+
+    if not resolved.exists():
+        return {
+            "success": False,
+            "error": f"Path not found: {resolved}",
+        }
+
+    all_excludes = DEFAULT_EXCLUDES + (excludes or [])
+
+    raw = _grep_deprecations(resolved, all_excludes)
+
+    markers: list[DeprecationMarker] = []
+    for item in raw:
+        count, caller_list = _count_callers(
+            item["symbol"], resolved, item["path"]
+        )
+        markers.append(DeprecationMarker(
+            path=item["path"],
+            line=item["line"],
+            symbol=item["symbol"],
+            text=item["text"],
+            caller_count=count,
+            callers=caller_list,
+        ))
+
+    with_callers = sum(1 for m in markers if m.caller_count > 0)
+
+    return {
+        "success": True,
+        "deprecations": markers,
+        "summary": {
+            "total_deprecations": len(markers),
+            "deprecations_with_callers": with_callers,
+        },
+    }

package/pennyfarthing_scripts/codemarkers/cli.py

@@ -127,3 +127,53 @@ def summary(repo, repo_path, days, top, fmt, output_file, exclude):
     else:
         from pennyfarthing_scripts.codemarkers.formatters import format_summary
         format_summary(result, file=click.get_text_stream("stdout"))
+
+
+def _run_deprecation_analysis(repo_path, exclude):
+    """Run deprecation analysis and return result dict."""
+    from pennyfarthing_scripts.codemarkers.analyze import analyze_deprecations
+
+    excludes = list(exclude) if exclude else None
+    if repo_path:
+        p = Path(repo_path).resolve()
+    else:
+        from pennyfarthing_scripts.common.config import get_project_root
+        p = get_project_root()
+
+    return asyncio.run(analyze_deprecations(p, excludes))
+
+
+@codemarkers.command()
+@_common_options
+def deprecations(repo, repo_path, days, top, fmt, output_file, exclude):
+    """Scan for @deprecated symbols and cross-reference callers."""
+    result = _run_deprecation_analysis(repo_path, exclude)
+
+    if fmt == "json":
+        import json
+        from dataclasses import asdict
+
+        output = {
+            "success": result["success"],
+            "deprecations": [asdict(m) for m in result.get("deprecations", [])],
+            "summary": result.get("summary", {}),
+        }
+        text = json.dumps(output, indent=2)
+    else:
+        lines = []
+        deps = result.get("deprecations", [])
+        summary = result.get("summary", {})
+        lines.append(f"Total deprecations: {summary.get('total_deprecations', 0)}")
+        lines.append(f"With active callers: {summary.get('deprecations_with_callers', 0)}")
+        lines.append("")
+        for m in deps[:top]:
+            callers_str = f" ({m.caller_count} callers)" if m.caller_count else ""
+            lines.append(f"  {m.symbol} @ {m.path}:{m.line}{callers_str}")
+            lines.append(f"    {m.text}")
+        text = "\n".join(lines)
+
+    if output_file:
+        Path(output_file).write_text(text)
+        click.echo(f"Output written to {output_file}", err=True)
+    else:
+        click.echo(text)

package/pennyfarthing_scripts/codemarkers/formatters.py

@@ -16,7 +16,6 @@ from typing import TextIO
 from pennyfarthing_scripts.codemarkers.models import (
     CodeMarker,
     CodeMarkersResult,
-    MarkerSummary,
 )
 
 

package/pennyfarthing_scripts/codemarkers/models.py

@@ -43,3 +43,18 @@ class CodeMarkersResult:
     markers: list[CodeMarker] = field(default_factory=list)
     summary: MarkerSummary | None = None
     error: str | None = None
+
+
+@dataclass
+class DeprecationMarker:
+    """A deprecated symbol with caller cross-reference data (Story 80-2).
+
+    Stub: Dev will implement full functionality.
+    """
+
+    path: str
+    line: int
+    symbol: str
+    text: str
+    caller_count: int = 0
+    callers: list[str] = field(default_factory=list)

package/pennyfarthing_scripts/common/__init__.py

@@ -5,8 +5,16 @@ This package provides shared utilities used across all CLI tools:
 - config: Project configuration loading
 """
 
+from pennyfarthing_scripts.common.config import (
+    find_project_root,
+    get_project_root,
+    load_pennyfarthing_config,
+    load_yaml_config,
+)
 from pennyfarthing_scripts.common.output import (
     Colors,
+    _colorize,
+    _supports_color,
     bold,
     debug,
     dim,
@@ -16,15 +24,6 @@ from pennyfarthing_scripts.common.output import (
     info,
     success,
     warn,
-    _colorize,
-    _supports_color,
-)
-
-from pennyfarthing_scripts.common.config import (
-    find_project_root,
-    get_project_root,
-    load_pennyfarthing_config,
-    load_yaml_config,
 )
 
 __all__ = [

package/pennyfarthing_scripts/common/config.py

@@ -78,7 +78,7 @@ def load_yaml_config(path: Path) -> dict[str, Any] | None:
     if not path.exists():
         return None
 
-    with open(path, "r") as f:
+    with open(path) as f:
         return yaml.safe_load(f)
 
 

package/pennyfarthing_scripts/complexity/__init__.py

@@ -5,8 +5,8 @@ Wraps eslint with complexity rules to extract per-file metrics:
 cyclomatic complexity, function length, nesting depth, and line counts.
 """
 
-from pennyfarthing_scripts.complexity.models import FileComplexity, ComplexityResult
 from pennyfarthing_scripts.complexity.analyze import analyze_complexity
+from pennyfarthing_scripts.complexity.models import ComplexityResult, FileComplexity
 
 __all__ = [
     "FileComplexity",

package/pennyfarthing_scripts/complexity/analyze.py

@@ -13,7 +13,7 @@ import json
 import re
 from pathlib import Path
 
-from pennyfarthing_scripts.complexity.models import FileComplexity, ComplexityResult
+from pennyfarthing_scripts.complexity.models import ComplexityResult, FileComplexity
 
 # Regex patterns for extracting numeric values from ESLint messages
 COMPLEXITY_RE = re.compile(r"complexity of (\d+)")

package/pennyfarthing_scripts/complexity/cli.py

@@ -9,9 +9,13 @@ from __future__ import annotations
 
 import asyncio
 from pathlib import Path
+from typing import TYPE_CHECKING
 
 import click
 
+if TYPE_CHECKING:
+    from pennyfarthing_scripts.complexity.models import ComplexityResult
+
 
 @click.group()
 def complexity():
@@ -39,7 +43,7 @@ def _common_options(fn):
     return fn
 
 
-def _run_analysis(target_path: str | None, exclude: tuple) -> "ComplexityResult":
+def _run_analysis(target_path: str | None, exclude: tuple) -> ComplexityResult:
     """Run analysis and return result."""
     from pennyfarthing_scripts.complexity.analyze import analyze_complexity
 

package/pennyfarthing_scripts/complexity/formatters.py

@@ -11,7 +11,7 @@ import io
 import json
 from dataclasses import asdict
 
-from pennyfarthing_scripts.complexity.models import FileComplexity, ComplexityResult
+from pennyfarthing_scripts.complexity.models import ComplexityResult, FileComplexity
 
 
 def format_file_table(files: list[FileComplexity], top_n: int = 20) -> str:

package/pennyfarthing_scripts/context.py

@@ -9,7 +9,6 @@ import os
 import time
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Optional
 
 try:
     import yaml
@@ -45,8 +44,8 @@ class ContextResult:
 
     # Status
     status: str = "OK"  # OK, HIGH
-    warning: Optional[str] = None  # None, High, Critical
-    recommendation: Optional[str] = None
+    warning: str | None = None  # None, High, Critical
+    recommendation: str | None = None
 
     # Mode settings
     permission_mode: str = "manual"
@@ -56,7 +55,7 @@ class ContextResult:
     is_cyclist: bool = False
 
     # Error state
-    error: Optional[str] = None
+    error: str | None = None
 
     def to_env_vars(self) -> str:
         """Output as shell environment variables."""
@@ -111,7 +110,7 @@ class ContextResult:
         return "\n".join(lines)
 
 
-def load_config(project_dir: Optional[str] = None) -> ContextConfig:
+def load_config(project_dir: str | None = None) -> ContextConfig:
     """Load context configuration from config files.
 
     Checks .pennyfarthing/config.local.yaml first, falls back to
@@ -166,7 +165,7 @@ def _apply_config(config: ContextConfig, data: dict) -> None:
         config.relay_mode = wf.get("relay_mode", False) is True
 
 
-def get_claude_project_path(project_dir: Optional[str] = None) -> Path:
+def get_claude_project_path(project_dir: str | None = None) -> Path:
     """Get the Claude Code project path for transcripts.
 
     Claude Code stores transcripts at ~/.claude/projects/<path-with-dashes>
@@ -184,10 +183,10 @@ def get_claude_project_path(project_dir: Optional[str] = None) -> Path:
 
 def find_transcript(
     project_path: Path,
-    explicit_session: Optional[str] = None,
-    session_id_env: Optional[str] = None,
+    explicit_session: str | None = None,
+    session_id_env: str | None = None,
     stale_threshold_seconds: int = 60,
-) -> Optional[Path]:
+) -> Path | None:
     """Find the appropriate transcript file.
 
     Priority:
@@ -208,7 +207,7 @@ def find_transcript(
         return None
 
     # Helper to find most recent transcript
-    def most_recent() -> Optional[Path]:
+    def most_recent() -> Path | None:
         transcripts = sorted(
             [f for f in project_path.glob("*.jsonl") if "agent-" not in f.name],
             key=lambda f: f.stat().st_mtime,
@@ -236,7 +235,7 @@ def find_transcript(
     return most_recent()
 
 
-def parse_transcript(transcript_path: Path) -> tuple[Optional[int], Optional[int]]:
+def parse_transcript(transcript_path: Path) -> tuple[int | None, int | None]:
     """Parse transcript for first and last usage totals.
 
     Returns:
@@ -265,7 +264,7 @@ def parse_transcript(transcript_path: Path) -> tuple[Optional[int], Optional[int
     return first_total, last_total
 
 
-def detect_cyclist(project_dir: Optional[str] = None) -> bool:
+def detect_cyclist(project_dir: str | None = None) -> bool:
     """Detect if running inside Cyclist.
 
     Checks:
@@ -300,7 +299,7 @@ def detect_cyclist(project_dir: Optional[str] = None) -> bool:
                     result = s.connect_ex(("127.0.0.1", port))
                     if result == 0:
                         return True
-            except (ValueError, OSError, socket.error):
+            except (ValueError, OSError):
                 # Port file invalid or port not responding
                 continue
 
@@ -308,8 +307,8 @@ def detect_cyclist(project_dir: Optional[str] = None) -> bool:
 
 
 def check_context(
-    explicit_session: Optional[str] = None,
-    project_dir: Optional[str] = None,
+    explicit_session: str | None = None,
+    project_dir: str | None = None,
 ) -> ContextResult:
     """Check current context usage.
 

package/pennyfarthing_scripts/deadcode/analyze.py

@@ -9,10 +9,9 @@ from __future__ import annotations
 
 import asyncio
 import fnmatch
-from datetime import datetime, timezone
-from pathlib import Path
-
 import re
+from datetime import UTC, datetime
+from pathlib import Path
 
 from pennyfarthing_scripts.deadcode.models import (
     DeadCodeResult,
@@ -156,7 +155,7 @@ async def find_stale_files(
         filtered.append(fpath)
 
     # Enrich each stale file
-    now = datetime.now(timezone.utc)
+    now = datetime.now(UTC)
     stale_files = []
     for fpath in sorted(filtered):
         # Get last commit date

package/pennyfarthing_scripts/deadcode/cli.py

@@ -41,8 +41,8 @@ def _common_options(fn):
 
 def _run_analysis(repo: str | None, repo_path: str | None, days: int, exclude: tuple, branch: str):
     """Run analysis and return result."""
-    from pennyfarthing_scripts.deadcode.analyze import analyze_repo, find_stale_files
     from pennyfarthing_scripts.common.config import get_project_root
+    from pennyfarthing_scripts.deadcode.analyze import analyze_repo
 
     excludes = list(exclude) if exclude else None
 
@@ -109,8 +109,8 @@ def _exports_options(fn):
 
 def _run_exports_analysis(repo: str | None, repo_path: str | None):
     """Run unused export analysis and return result."""
-    from pennyfarthing_scripts.deadcode.analyze import find_unused_exports
     from pennyfarthing_scripts.common.config import get_project_root
+    from pennyfarthing_scripts.deadcode.analyze import find_unused_exports
 
     if repo_path:
         p = Path(repo_path).resolve()