coding-convention-reviewer 0.1.0__py3-none-any.whl

coding_convention_reviewer-0.1.0.dist-info/METADATA

@@ -0,0 +1,22 @@
+Metadata-Version: 2.4
+Name: coding-convention-reviewer
+Version: 0.1.0
+Summary: Deterministic, plugin-based coding convention reviewer.
+Requires-Python: >=3.12
+Requires-Dist: cachetools<6,>=5.3
+Requires-Dist: fastapi<1,>=0.115
+Requires-Dist: prometheus-client<1,>=0.20
+Requires-Dist: pydantic<3,>=2.7
+Requires-Dist: python-dotenv<2,>=1.0
+Requires-Dist: pyyaml<7,>=6.0
+Requires-Dist: rich<15,>=13.7
+Requires-Dist: slowapi<1,>=0.1
+Requires-Dist: structlog<26,>=24.0
+Requires-Dist: tree-sitter-typescript<0.24,>=0.20
+Requires-Dist: tree-sitter<0.26,>=0.22
+Requires-Dist: typer<1,>=0.12
+Requires-Dist: uvicorn<1,>=0.30
+Requires-Dist: websockets<15,>=12.0
+Provides-Extra: test
+Requires-Dist: httpx<1,>=0.27; extra == 'test'
+Requires-Dist: pytest<9,>=8.2; extra == 'test'

coding_convention_reviewer-0.1.0.dist-info/RECORD

@@ -0,0 +1,46 @@
+reviewer/__init__.py,sha256=JfD0oiKF_AvIvbQePxznINztpBfIQaCoaO0j9An8EcM,65
+reviewer/__main__.py,sha256=r2ZWgN-PH7PDvutkbq1V-EC8aRPcFNxmIdYyDTUKssU,68
+reviewer/cli.py,sha256=aW-hKbYe7r0bO_rmOVjO3iMCes3lKofIjtcMiqTOLdc,4243
+reviewer/core/__init__.py,sha256=2vKGcQOJarEvL7d36BeS3pzYUNieApvW2WKTq0Q-Dgw,40
+reviewer/core/logging.py,sha256=dpQ03MdK30Q6WpUMjId50sHh7bahLH-kAREscO1nf44,916
+reviewer/core/metrics.py,sha256=2S6mFmYzVyL0xPbdcTjIov-uBnw5lmZB3f5P-2I8l3A,1089
+reviewer/core/scanner.py,sha256=15htLVB5KA0GdNWiNZNGpZrtq-u0fqWtTw9mJhNbuh0,1697
+reviewer/core/service.py,sha256=ofyR-idK1Sh7FM5UX3lNcHZ36jzKpnzow6RxlazdPd0,3486
+reviewer/core/config/__init__.py,sha256=cwsMA5CQDPnhXcQWBMLsjsOqreLcCwYqbBSU8iQ308o,204
+reviewer/core/config/loader.py,sha256=hpphaFSJhMPpIcs4U2XotdLbnQKJGJ7BFAiVBAxorBI,1051
+reviewer/core/config/models.py,sha256=9xxNjIALsT32i4H98_IDojXmL4XD9ZhWql-iKeq1oG0,1146
+reviewer/core/engine/__init__.py,sha256=37kkpAcMSJhewQEvLz_7Tkj_ZquhYkLq4R75ju6N2jU,251
+reviewer/core/engine/models.py,sha256=v81dvKLB_8KyxKme9-BGS4kO71_2jKSIORnml-CAH50,839
+reviewer/core/engine/registry.py,sha256=8lkWtqUdnYftDHteXrQ72Q8VskxBLME9gh0ZCzVjUMo,948
+reviewer/core/engine/runner.py,sha256=GqnxtBJ2En1Iu9dppNPCHinL9wTccwjXUa8PqmAEjrk,2287
+reviewer/core/engine/suppression.py,sha256=7rDhWu4rdzeSawTKkIEOrj5Z_ynsver25KyJ8UMU1Xk,1013
+reviewer/core/parser/__init__.py,sha256=YpF97w7hsxuMMtAGQMhhrg4GxmQWtSJvlCkeHgV4OKg,255
+reviewer/core/parser/base.py,sha256=4IGKZV7FrGCGduQBhKDejrgZSnfRmo_Q68Zn7Q-jszY,424
+reviewer/core/parser/cache.py,sha256=pO0-2S0PbjGZe3CXs-pftkKfUdw3asRVX27LZVBEJ8s,698
+reviewer/core/parser/python_ast.py,sha256=8PETtH8OI1CJe062Lidb88VpBPlk34ZXmhkdizXfJZ4,476
+reviewer/core/parser/typescript.py,sha256=h96VvkF-0tSuXqCSF5NS0ujqzBpvSi8yTwFQNHdOMRk,1312
+reviewer/core/reporting/__init__.py,sha256=bk2icz3G2urgAsJMGqpTsTfa6HsdcTv8hv4ZdaeRFAA,265
+reviewer/core/reporting/models.py,sha256=b9iaz9-Zbw13v9CDxvQ9HUP6Ubgl47u8k-yv_qQyaTk,916
+reviewer/core/reporting/reporters.py,sha256=IkOSM0SUvTh3dRf_dCT9bCq5Nmtsno2_yxPBbFJlNCI,2869
+reviewer/core/storage/__init__.py,sha256=D6KNz291urHI68hXf1DMvPgdf7qT5FkB0bXVhGSbfVM,75
+reviewer/core/storage/store.py,sha256=J4OXg-Ff4J6NRXzPSQ6-qspvzDjfAfWdrxlz6AUOEC0,4281
+reviewer/plugins/__init__.py,sha256=I_L4YzsMHMFCKJPoSw3_R_3-p0DPtOwFNL7WK-aRgO8,37
+reviewer/plugins/defaults.py,sha256=nBewnb4wxdGbDR0hDgaTLhR_0ou-01ixH5wBt4Whfo4,667
+reviewer/plugins/django/__init__.py,sha256=Ne5ZmuCPu3ovGmhgn6TjlGr1ZkjMASVyCW_Qq1C8PcI,86
+reviewer/plugins/django/plugin.py,sha256=yBmetLbUxDd9bzwlwIJJDiL1bAzxi_Xs6gFkybbTLVk,1266
+reviewer/plugins/django/rules.py,sha256=16_OKUzXNaSnzcgBUFoaXAHAjNIFtlXA8S2LWexR0Zk,6138
+reviewer/plugins/fastapi/__init__.py,sha256=oFqvqYMQ2oW8daGni9uuvv6sm_RCLedU_BDFoKGp0Ps,87
+reviewer/plugins/fastapi/plugin.py,sha256=jJATXYlfaTEPykswOGZECuoYuMHp7Ib5dLWjgZp2urA,1760
+reviewer/plugins/fastapi/rules.py,sha256=3aImWAsbHsMEwopfeSxjjrCuGbjWAuROKAq-MgzndSU,6067
+reviewer/plugins/python/__init__.py,sha256=ILNyG3VHMnmujYjkkylwmKI9XCCIZMMhXLvgP3FVRBo,86
+reviewer/plugins/python/plugin.py,sha256=hI3d9wTPwV89HTyoQnDiKzlaljAb-js7xAYZpuiuJB4,1317
+reviewer/plugins/python/rules.py,sha256=BPuiaXn15iHvbmv9eX-J8uGhXZQWOUMvxlDtIWrkL4M,5161
+reviewer/plugins/react/__init__.py,sha256=Kg7wf6YuzFOWvb3oP-bBOqTiwzj1QjGky1MN2Wi_VGE,85
+reviewer/plugins/react/plugin.py,sha256=5Oi__GhQLO648-_qzWS_63SgvUcNQ6wsIoLo0Gqgxsk,4561
+reviewer/plugins/react/rules.py,sha256=9Jr_DbZ0YCC-C8t9O4r9gWazzxsl-cNvOXG8lDIiIhI,23359
+reviewer/server/__init__.py,sha256=Rqy8v4XzxCvTPQfWzCfALkaCJ1sml82a1K5ZLsRqNtw,44
+reviewer/server/app.py,sha256=xC2x90tD5g1Gk2jLfLh38_N89-P2wJXIvdvvJoW1wH0,15231
+coding_convention_reviewer-0.1.0.dist-info/METADATA,sha256=XE5fEHQPbxyhjOHJzHAQn7PmFfXyVqSDoccJXXQ_kiI,765
+coding_convention_reviewer-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+coding_convention_reviewer-0.1.0.dist-info/entry_points.txt,sha256=GWn2Qn3T74NOhzOieyzZRjYNI5fV7Mprb6RLDJCPP5g,46
+coding_convention_reviewer-0.1.0.dist-info/RECORD,,

coding_convention_reviewer-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

coding_convention_reviewer-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+reviewer = reviewer.cli:app

reviewer/__init__.py

@@ -0,0 +1,3 @@
+"""Coding Convention Reviewer package."""
+
+__version__ = "0.1.0"

reviewer/__main__.py

@@ -0,0 +1,5 @@
+from reviewer.cli import app
+
+
+if __name__ == "__main__":
+    app()

reviewer/cli.py

@@ -0,0 +1,106 @@
+from __future__ import annotations
+
+import time
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from reviewer.core.engine import PluginRegistry
+from reviewer.core.logging import configure_logging, get_logger
+from reviewer.core.reporting import console_report, github_report, json_report, sarif_report
+from reviewer.core.reporting.models import Severity
+from reviewer.core.service import scan_project
+from reviewer.plugins.defaults import create_default_registry
+
+app = typer.Typer(help="Deterministic coding convention reviewer.")
+logger = get_logger(__name__)
+
+
+@app.callback()
+def main() -> None:
+    """Deterministic coding convention reviewer."""
+
+
+def default_registry() -> PluginRegistry:
+    return create_default_registry()
+
+
+def _has_failing_findings(severities: list[Severity]) -> bool:
+    return any(severity in {Severity.WARNING, Severity.ERROR} for severity in severities)
+
+
+@app.command()
+def scan(
+    target: Annotated[Path, typer.Argument(help="File or directory to scan.")] = Path("."),
+    config: Annotated[Path | None, typer.Option("--config", "-c", help="Path to reviewer.yaml.")] = None,
+    json_output: Annotated[bool, typer.Option("--json", help="Print machine-readable JSON output.")] = False,
+    output_format: Annotated[str, typer.Option("--format", help="Output format: console, json, github.")] = "console",
+    changed_files: Annotated[Path | None, typer.Option("--changed-files", help="Newline-delimited list of changed files.")] = None,
+) -> None:
+    configure_logging()
+    logger.info("scan_started", target=str(target))
+    _t0 = time.perf_counter()
+    findings = scan_project(target, config, changed_files, default_registry())
+    logger.info("scan_completed", finding_count=len(findings), duration_ms=round((time.perf_counter() - _t0) * 1000, 1))
+    selected_format = "json" if json_output else output_format
+
+    if selected_format == "json":
+        typer.echo(json_report(findings))
+    elif selected_format == "github":
+        output = github_report(findings)
+        if output:
+            typer.echo(output)
+    elif selected_format == "sarif":
+        typer.echo(sarif_report(findings))
+    elif selected_format == "console":
+        console_report(findings)
+    else:
+        raise typer.BadParameter("format must be one of: console, json, github, sarif")
+
+    raise typer.Exit(code=1 if _has_failing_findings([finding.severity for finding in findings]) else 0)
+
+
+@app.command()
+def init(
+    output: Annotated[Path, typer.Option("--output", "-o", help="Output path for config file.")] = Path("reviewer.yaml"),
+) -> None:
+    """Scaffold a reviewer.yaml with all known rules and documentation."""
+    registry = default_registry()
+    plugins: dict[str, list] = {}
+    for rule in registry.rules:
+        plugins.setdefault(rule.plugin, []).append(rule)
+
+    lines: list[str] = ["# reviewer.yaml — generated by `reviewer init`", "rules:"]
+    for plugin_name, rules in plugins.items():
+        lines.append(f"  # ── {plugin_name} ──────────────────────────────")
+        for rule in rules:
+            doc = (rule.check.__doc__ or "").strip().splitlines()[0] if rule.check.__doc__ else ""
+            if doc:
+                lines.append(f"  # {doc}")
+            lines.append(f"  {rule.id}:")
+            lines.append(f"    enabled: true")
+            lines.append(f"    severity: {rule.severity.value}")
+        lines.append("")
+
+    content = "\n".join(lines)
+    output.write_text(content, encoding="utf-8")
+    rule_count = sum(len(r) for r in plugins.values())
+    typer.echo(f"Created {output} with {rule_count} rules across {len(plugins)} plugins.")
+
+
+@app.command()
+def api(
+    host: Annotated[str, typer.Option("--host", help="Host for the local API server.")] = "127.0.0.1",
+    port: Annotated[int, typer.Option("--port", "-p", help="Port for the local API server.")] = 8766,
+) -> None:
+    """Start the local API server."""
+    import uvicorn
+
+    configure_logging()
+    typer.echo(f"Starting Coding Convention Reviewer API at http://{host}:{port}")
+    uvicorn.run("reviewer.server.app:create_app", factory=True, host=host, port=port, reload=True)
+
+
+if __name__ == "__main__":
+    app()

reviewer/core/__init__.py

@@ -0,0 +1 @@
+"""Framework-agnostic reviewer core."""

reviewer/core/config/__init__.py

@@ -0,0 +1,4 @@
+from reviewer.core.config.loader import load_config
+from reviewer.core.config.models import ReviewerConfig, RuleConfig, ScanConfig
+
+__all__ = ["ReviewerConfig", "RuleConfig", "ScanConfig", "load_config"]

reviewer/core/config/loader.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import structlog
+import yaml
+
+from reviewer.core.config.models import ReviewerConfig
+
+logger = structlog.get_logger(__name__)
+
+
+def load_config(config_path: Path | None = None, start_dir: Path | None = None) -> ReviewerConfig:
+    start_dir = (start_dir or Path.cwd()).resolve()
+    path = config_path
+    if path is None:
+        candidate = start_dir / "reviewer.yaml"
+        path = candidate if candidate.exists() else None
+
+    if path is None:
+        return ReviewerConfig()
+
+    with path.open("r", encoding="utf-8") as handle:
+        data = yaml.safe_load(handle) or {}
+    config = ReviewerConfig.model_validate(data)
+
+    try:
+        from reviewer.plugins.defaults import create_default_registry
+        known_ids = {rule.id for rule in create_default_registry().rules}
+        for rule_id in config.rules:
+            if rule_id not in known_ids:
+                logger.warning("unknown_rule_in_config", rule_id=rule_id)
+    except Exception:
+        pass
+
+    return config

reviewer/core/config/models.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class ScanConfig(BaseModel):
+    include: list[str] = Field(default_factory=lambda: ["**/*"])
+    exclude: list[str] = Field(
+        default_factory=lambda: [
+            ".git/**",
+            ".venv/**",
+            "__pycache__/**",
+            "node_modules/**",
+            "dist/**",
+            "build/**",
+        ]
+    )
+
+
+class RuleConfig(BaseModel):
+    enabled: bool = True
+    severity: str | None = None
+    limit: int | None = None
+    options: dict[str, Any] = Field(default_factory=dict)
+
+    model_config = {"extra": "allow"}
+
+    def option(self, key: str, default: Any = None) -> Any:
+        if hasattr(self, key):
+            value = getattr(self, key)
+            if value is not None:
+                return value
+        return self.options.get(key, default)
+
+
+class ReviewerConfig(BaseModel):
+    reviewer: ScanConfig = Field(default_factory=ScanConfig)
+    rules: dict[str, RuleConfig] = Field(default_factory=dict)
+
+    def rule(self, rule_id: str) -> RuleConfig:
+        return self.rules.get(rule_id, RuleConfig())

reviewer/core/engine/__init__.py

@@ -0,0 +1,5 @@
+from reviewer.core.engine.models import Plugin, Rule, RuleContext
+from reviewer.core.engine.registry import PluginRegistry
+from reviewer.core.engine.runner import run_review
+
+__all__ = ["Plugin", "PluginRegistry", "Rule", "RuleContext", "run_review"]

reviewer/core/engine/models.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+
+from reviewer.core.config.models import ReviewerConfig, RuleConfig
+from reviewer.core.parser.base import ParseResult, Parser
+from reviewer.core.reporting.models import Finding, Severity
+
+
+@dataclass(frozen=True)
+class RuleContext:
+    path: Path
+    root: Path
+    parse_result: ParseResult
+    config: ReviewerConfig
+    rule_config: RuleConfig
+
+
+RuleCheck = Callable[[RuleContext], list[Finding]]
+
+
+@dataclass(frozen=True)
+class Rule:
+    id: str
+    plugin: str
+    languages: set[str]
+    check: RuleCheck
+    severity: Severity = Severity.WARNING
+
+
+@dataclass(frozen=True)
+class Plugin:
+    name: str
+    version: str
+    supported_extensions: set[str]
+    parsers: list[Parser]
+    rules: list[Rule]

reviewer/core/engine/registry.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from reviewer.core.engine.models import Plugin, Rule
+from reviewer.core.parser.base import Parser
+
+
+class PluginRegistry:
+    def __init__(self) -> None:
+        self._plugins: list[Plugin] = []
+
+    def register(self, plugin: Plugin) -> None:
+        self._plugins.append(plugin)
+
+    @property
+    def plugins(self) -> list[Plugin]:
+        return list(self._plugins)
+
+    @property
+    def supported_extensions(self) -> set[str]:
+        return {extension for plugin in self._plugins for extension in plugin.supported_extensions}
+
+    @property
+    def rules(self) -> list[Rule]:
+        return [rule for plugin in self._plugins for rule in plugin.rules]
+
+    def parser_for_extension(self, extension: str) -> Parser | None:
+        for plugin in self._plugins:
+            for parser in plugin.parsers:
+                if extension in parser.extensions:
+                    return parser
+        return None

reviewer/core/engine/runner.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from pathlib import Path
+
+from reviewer.core.config.models import ReviewerConfig
+from reviewer.core.engine.models import RuleContext
+from reviewer.core.engine.registry import PluginRegistry
+from reviewer.core.engine.suppression import parse_suppressions
+from reviewer.core.parser.base import ParseResult
+from reviewer.core.reporting.models import Finding, Severity
+
+
+def run_review(
+    paths: list[Path],
+    root: Path,
+    config: ReviewerConfig,
+    registry: PluginRegistry,
+    *,
+    pre_parsed: dict[Path, ParseResult] | None = None,
+    progress_callback: Callable[[str, int, int], None] | None = None,
+) -> list[Finding]:
+    findings: list[Finding] = []
+    total = len(paths)
+    for idx, path in enumerate(paths):
+        if pre_parsed is not None and path in pre_parsed:
+            parse_result = pre_parsed[path]
+        else:
+            parser = registry.parser_for_extension(path.suffix)
+            if parser is None:
+                continue
+            parse_result = parser.parse(path)
+
+        suppressions = parse_suppressions(parse_result.source)
+        if suppressions.ignore_file:
+            continue
+
+        for rule in sorted(registry.rules, key=lambda item: item.id):
+            if parse_result.language not in rule.languages:
+                continue
+            rule_config = config.rule(rule.id)
+            if not rule_config.enabled:
+                continue
+            severity = Severity(rule_config.severity) if rule_config.severity else rule.severity
+            context = RuleContext(
+                path=path,
+                root=root,
+                parse_result=parse_result,
+                config=config,
+                rule_config=rule_config,
+            )
+            for finding in rule.check(context):
+                if suppressions.is_ignored(finding.line, finding.rule):
+                    continue
+                if finding.severity != severity:
+                    finding = finding.model_copy(update={"severity": severity})
+                findings.append(finding)
+
+        if progress_callback is not None:
+            progress_callback(str(path), idx + 1, total)
+
+    return sorted(findings, key=lambda item: (item.file, item.line, item.rule))

reviewer/core/engine/suppression.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class Suppressions:
+    ignore_file: bool = False
+    lines: dict[int, set[str]] = field(default_factory=dict)
+
+    def is_ignored(self, line: int, rule_id: str) -> bool:
+        if self.ignore_file:
+            return True
+        ignored = self.lines.get(line, set())
+        return "*" in ignored or rule_id in ignored
+
+
+def parse_suppressions(source: str) -> Suppressions:
+    lines: dict[int, set[str]] = {}
+    ignore_file = False
+    for index, line in enumerate(source.splitlines(), start=1):
+        if "reviewer: ignore-file" in line:
+            ignore_file = True
+        marker = "reviewer: ignore"
+        if marker not in line:
+            continue
+        after = line.split(marker, 1)[1].strip()
+        rule_ids = {part.strip() for part in after.replace(",", " ").split() if part.strip()}
+        lines[index] = rule_ids or {"*"}
+    return Suppressions(ignore_file=ignore_file, lines=lines)

reviewer/core/logging.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+import logging
+import os
+
+import structlog
+
+
+def configure_logging() -> None:
+    structlog.configure(
+        processors=[
+            structlog.stdlib.filter_by_level,
+            structlog.stdlib.add_logger_name,
+            structlog.stdlib.add_log_level,
+            structlog.stdlib.PositionalArgumentsFormatter(),
+            structlog.processors.TimeStamper(fmt="iso"),
+            structlog.processors.StackInfoRenderer(),
+            structlog.processors.format_exc_info,
+            structlog.processors.UnicodeDecoder(),
+            structlog.dev.ConsoleRenderer() if os.isatty(1) else structlog.processors.JSONRenderer(),
+        ],
+        context_class=dict,
+        logger_factory=structlog.stdlib.LoggerFactory(),
+        cache_logger_on_first_use=True,
+    )
+
+
+def get_logger(name: str = __name__) -> structlog.BoundLogger:
+    return structlog.get_logger(name)

reviewer/core/metrics.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+import time
+from contextlib import contextmanager
+from typing import Generator
+
+from prometheus_client import Counter, Gauge, Histogram
+
+scan_total = Counter(
+    "reviewer_scans_total",
+    "Total scans run",
+    ["status"],
+)
+
+scan_duration = Histogram(
+    "reviewer_scan_duration_seconds",
+    "Scan duration in seconds",
+    buckets=[1, 5, 10, 30, 60, 120, 300],
+)
+
+findings_total = Counter(
+    "reviewer_findings_total",
+    "Findings by severity",
+    ["severity"],
+)
+
+files_scanned = Histogram(
+    "reviewer_files_scanned",
+    "Number of files per scan",
+)
+
+scan_in_progress = Gauge(
+    "reviewer_scan_in_progress",
+    "Whether a scan is currently running",
+)
+
+
+@contextmanager
+def track_scan() -> Generator[None, None, None]:
+    scan_in_progress.inc()
+    start = time.monotonic()
+    try:
+        yield
+        scan_total.labels(status="success").inc()
+    except Exception:
+        scan_total.labels(status="error").inc()
+        raise
+    finally:
+        scan_duration.observe(time.monotonic() - start)
+        scan_in_progress.dec()

reviewer/core/parser/__init__.py

@@ -0,0 +1,5 @@
+from reviewer.core.parser.base import ParseResult, Parser
+from reviewer.core.parser.python_ast import PythonAstParser
+from reviewer.core.parser.typescript import TypeScriptParser
+
+__all__ = ["ParseResult", "Parser", "PythonAstParser", "TypeScriptParser"]

reviewer/core/parser/base.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Protocol
+
+from pydantic import BaseModel, ConfigDict
+
+
+class ParseResult(BaseModel):
+    path: Path
+    source: str
+    tree: Any
+    language: str
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+
+class Parser(Protocol):
+    language: str
+    extensions: set[str]
+
+    def parse(self, path: Path) -> ParseResult:
+        ...

reviewer/core/parser/cache.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+import threading
+from pathlib import Path
+
+from cachetools import LRUCache
+
+from reviewer.core.parser.base import ParseResult, Parser
+
+_CACHE: LRUCache[str, tuple[float, ParseResult]] = LRUCache(maxsize=256)
+_LOCK = threading.Lock()
+
+
+def cached_parse(path: Path, parser: Parser) -> ParseResult:
+    key = str(path.resolve())
+    try:
+        mtime = path.stat().st_mtime
+    except OSError:
+        return parser.parse(path)
+
+    with _LOCK:
+        entry = _CACHE.get(key)
+        if entry is not None and entry[0] == mtime:
+            return entry[1]
+
+    result = parser.parse(path)
+
+    with _LOCK:
+        _CACHE[key] = (mtime, result)
+
+    return result

reviewer/core/parser/python_ast.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+
+from reviewer.core.parser.base import ParseResult
+
+
+class PythonAstParser:
+    language = "python"
+    extensions = {".py"}
+
+    def parse(self, path: Path) -> ParseResult:
+        source = path.read_text(encoding="utf-8")
+        return ParseResult(
+            path=path,
+            source=source,
+            tree=ast.parse(source, filename=str(path)),
+            language=self.language,
+        )

reviewer/core/parser/typescript.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+import threading
+from pathlib import Path
+from typing import Any
+
+from reviewer.core.parser.base import ParseResult
+
+_local = threading.local()
+
+
+class TypeScriptParser:
+    language = "typescript"
+    extensions = {".ts", ".tsx"}
+
+    def _load_parser(self) -> Any:
+        parser = getattr(_local, "ts_parser", None)
+        if parser is not None:
+            return parser
+
+        try:
+            from tree_sitter import Language, Parser
+            import tree_sitter_typescript as tstypescript
+        except ImportError as exc:
+            raise RuntimeError(
+                "TypeScript parsing requires tree-sitter and tree-sitter-typescript."
+            ) from exc
+
+        parser = Parser()
+        language_factory = tstypescript.language_tsx
+        language = Language(language_factory())
+        if hasattr(parser, "set_language"):
+            parser.set_language(language)
+        else:
+            parser.language = language
+        _local.ts_parser = parser
+        return parser
+
+    def parse(self, path: Path) -> ParseResult:
+        source = path.read_text(encoding="utf-8")
+        parser = self._load_parser()
+        tree = parser.parse(source.encode("utf-8"))
+        return ParseResult(path=path, source=source, tree=tree, language=self.language)