pytscheck 0.1.0__py3-none-win_arm64.whl

pytscheck/__init__.py

@@ -0,0 +1,89 @@
+"""PyTSCheck: Python-native TypeScript type checking.
+
+PyTSCheck wraps Microsoft's native TypeScript 7 compiler (``tsgo``) and
+exposes a typed Python API for checking source strings, files, and
+projects. The compiler is bundled inside platform-specific wheels, so no
+Node.js or Go installation is required.
+
+Public API
+----------
+
+The top-level entry points mirror the module-level functions in
+:mod:`pytscheck.api`::
+
+    from pytscheck import check, check_file, check_project
+
+    result = check('const age: number = "twenty";')
+    if not result.success:
+        for diagnostic in result.errors:
+            print(diagnostic.file, diagnostic.line, diagnostic.message)
+
+Adapter authors import from :mod:`pytscheck.adapters` instead; the core
+package never imports a specific adapter.
+
+Stability
+---------
+
+The names re-exported here are the public surface and follow Semantic
+Versioning. Anything not listed in :data:`__all__` is internal and may
+change without notice.
+
+Importing this module is cheap and safe: no subprocess is launched, no
+binary is located, and no network access occurs until a ``check*``
+function is called. This matters for packaging tests that run on machines
+without a bundled compiler.
+"""
+
+from __future__ import annotations
+
+from .api import check, check_file, check_project
+from .config import CompilerOptions
+from .exceptions import (
+    AdapterDiscoveryError,
+    AdapterError,
+    AdapterExtractionError,
+    AdapterMappingError,
+    AdapterProtocolError,
+    AdapterRegistrationError,
+    CompilerExecutionError,
+    CompilerNotFoundError,
+    CompilerTimeoutError,
+    ConfigurationError,
+    OutputParseError,
+    PyTSCheckError,
+    UnsupportedPlatformError,
+)
+from .models import Diagnostic, RelatedInformation, Result, SourceFile
+from .version import ADAPTER_PROTOCOL_VERSION, COMPILER_VERSION, __version__
+
+__all__ = [  # noqa: RUF022 -- Public exports retain the tested version/API group order.
+    # Version metadata
+    "__version__",
+    "COMPILER_VERSION",
+    "ADAPTER_PROTOCOL_VERSION",
+    # Public API
+    "check",
+    "check_file",
+    "check_project",
+    # Configuration
+    "CompilerOptions",
+    # Models
+    "Result",
+    "Diagnostic",
+    "RelatedInformation",
+    "SourceFile",
+    # Exceptions
+    "PyTSCheckError",
+    "UnsupportedPlatformError",
+    "CompilerNotFoundError",
+    "CompilerExecutionError",
+    "CompilerTimeoutError",
+    "OutputParseError",
+    "ConfigurationError",
+    "AdapterError",
+    "AdapterDiscoveryError",
+    "AdapterExtractionError",
+    "AdapterMappingError",
+    "AdapterProtocolError",
+    "AdapterRegistrationError",
+]

pytscheck/__main__.py

@@ -0,0 +1,221 @@
+"""``python -m pytscheck`` and the ``pytscheck`` console script.
+
+This module is intentionally small. It exposes three things:
+
+- ``--version``  : print pytscheck / compiler / protocol versions
+- ``--where``    : print the path to the bundled tsgo binary
+- ``check``      : a minimal CLI over the public API (Phase 2+)
+
+Every subcommand maps to a public function in :mod:`pytscheck.api`. The
+CLI never reimplements logic: it parses arguments, calls the API, and
+formats the result.
+
+Exit codes
+----------
+
+  0  success (no errors)
+  1  type errors were reported
+  2  usage / configuration error
+  3  operational failure (missing binary, crash, timeout, unparsable output)
+
+The distinction between 1 and 3 matters for CI: a tool that wants to fail
+the build on type errors should treat 1 as a normal failure and 3 as an
+infrastructure problem.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from .exceptions import (
+    CompilerExecutionError,
+    CompilerNotFoundError,
+    CompilerTimeoutError,
+    ConfigurationError,
+    OutputParseError,
+    PyTSCheckError,
+    UnsupportedPlatformError,
+)
+from .models import Diagnostic, Result
+from .version import ADAPTER_PROTOCOL_VERSION, COMPILER_VERSION, __version__
+
+EXIT_OK = 0
+EXIT_TYPE_ERRORS = 1
+EXIT_USAGE = 2
+EXIT_OPERATIONAL = 3
+
+
+# ---------------------------------------------------------------------------
+# Argument parsing
+# ---------------------------------------------------------------------------
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="pytscheck",
+        description="Type-check TypeScript from Python.",
+    )
+    parser.add_argument(
+        "--version",
+        action="store_true",
+        help="print versions and exit",
+    )
+    parser.add_argument(
+        "--where",
+        action="store_true",
+        help="print the path to the bundled tsgo binary and exit",
+    )
+
+    sub = parser.add_subparsers(dest="command", metavar="COMMAND")
+
+    # --- check string -----------------------------------------------------
+    p_str = sub.add_parser("string", help="check an in-memory source string")
+    p_str.add_argument("source", help="TypeScript source text")
+    p_str.add_argument("--filename", default="input.ts", help="virtual filename")
+    p_str.add_argument("--json", action="store_true", help="emit JSON diagnostics")
+    p_str.add_argument("--keep-raw", action="store_true", help="include raw compiler output")
+
+    # --- check file -------------------------------------------------------
+    p_file = sub.add_parser("file", help="check a single file")
+    p_file.add_argument("path", type=Path, help="path to a .ts / .tsx / .mts / .cts file")
+    p_file.add_argument("--json", action="store_true", help="emit JSON diagnostics")
+    p_file.add_argument("--keep-raw", action="store_true", help="include raw compiler output")
+
+    # --- check project ----------------------------------------------------
+    p_proj = sub.add_parser("project", help="check a project directory")
+    p_proj.add_argument("root", type=Path, help="project root directory")
+    p_proj.add_argument("--json", action="store_true", help="emit JSON diagnostics")
+    p_proj.add_argument("--keep-raw", action="store_true", help="include raw compiler output")
+
+    return parser
+
+
+# ---------------------------------------------------------------------------
+# Output formatting
+# ---------------------------------------------------------------------------
+
+
+def _format_diagnostic(d: Diagnostic) -> str:
+    """One-line, grep-friendly rendering of a diagnostic."""
+    loc = f"{d.file or '<global>'}({d.line},{d.column})"
+    return f"{loc}: {d.category} TS{d.code}: {d.message}"
+
+
+def _print_result(result: Result, *, as_json: bool) -> None:
+    if as_json:
+        import json
+
+        payload = {
+            "success": result.success,
+            "compiler_version": result.compiler_version,
+            "elapsed_seconds": result.elapsed_seconds,
+            "diagnostics": [
+                {
+                    "file": d.file,
+                    "origin_file": d.origin_file,
+                    "line": d.line,
+                    "column": d.column,
+                    "end_line": d.end_line,
+                    "end_column": d.end_column,
+                    "code": d.code,
+                    "category": d.category,
+                    "message": d.message,
+                }
+                for d in result.diagnostics
+            ],
+        }
+        print(json.dumps(payload, indent=2))
+        return
+
+    for d in result.diagnostics:
+        print(_format_diagnostic(d))
+    if result.success:
+        print(f"ok ({result.elapsed_seconds:.2f}s)")
+    else:
+        n = len(result.errors)
+        print(f"{n} error{'s' if n != 1 else ''} ({result.elapsed_seconds:.2f}s)")
+
+
+# ---------------------------------------------------------------------------
+# Command handlers
+# ---------------------------------------------------------------------------
+
+
+def _cmd_version() -> int:
+    print(f"pytscheck {__version__}")
+    print(f"bundled compiler {COMPILER_VERSION}")
+    print(f"adapter protocol {ADAPTER_PROTOCOL_VERSION}")
+    return EXIT_OK
+
+
+def _cmd_where() -> int:
+    from .runner import binary_path
+
+    try:
+        print(binary_path())
+    except PyTSCheckError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return EXIT_OPERATIONAL
+    return EXIT_OK
+
+
+def _cmd_check(args: argparse.Namespace) -> int:
+    # Import lazily so --version / --where never pull in the runner.
+    from .api import check, check_file, check_project
+
+    try:
+        if args.command == "string":
+            result = check(
+                args.source,
+                filename=args.filename,
+                keep_raw=args.keep_raw,
+            )
+        elif args.command == "file":
+            result = check_file(args.path, keep_raw=args.keep_raw)
+        elif args.command == "project":
+            result = check_project(args.root, keep_raw=args.keep_raw)
+        else:  # pragma: no cover - argparse enforces this
+            print(f"unknown command: {args.command}", file=sys.stderr)
+            return EXIT_USAGE
+    except ConfigurationError as exc:
+        print(f"configuration error: {exc}", file=sys.stderr)
+        return EXIT_USAGE
+    except (
+        CompilerNotFoundError,
+        CompilerTimeoutError,
+        CompilerExecutionError,
+        OutputParseError,
+        UnsupportedPlatformError,
+    ) as exc:
+        print(f"operational error: {exc}", file=sys.stderr)
+        return EXIT_OPERATIONAL
+
+    _print_result(result, as_json=args.json)
+    return EXIT_OK if result.success else EXIT_TYPE_ERRORS
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    if args.version:
+        return _cmd_version()
+    if args.where:
+        return _cmd_where()
+
+    if args.command in {"string", "file", "project"}:
+        return _cmd_check(args)
+
+    parser.print_help()
+    return EXIT_USAGE
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pytscheck/adapters/__init__.py

@@ -0,0 +1,38 @@
+"""Compiler-agnostic adapter system.
+
+Adapters let external Python tools submit generated TypeScript and receive
+diagnostics mapped back to their own source files. The pytscheck core never
+imports a specific adapter; tools register theirs through the
+``pytscheck.adapters`` entry-point group.
+"""
+
+from __future__ import annotations
+
+from .base import CompilerAdapter
+from .context import DeclarationResource, ProjectContext
+from .errors import (
+    AdapterError,
+    AdapterExtractionError,
+    AdapterMappingError,
+    AdapterProtocolError,
+    AdapterRegistrationError,
+)
+from .registry import get_adapter, register_adapter, unregister_adapter
+from .source_maps import remap_diagnostics
+from .sources import collect_sources
+
+__all__ = [
+    "AdapterError",
+    "AdapterExtractionError",
+    "AdapterMappingError",
+    "AdapterProtocolError",
+    "AdapterRegistrationError",
+    "CompilerAdapter",
+    "DeclarationResource",
+    "ProjectContext",
+    "collect_sources",
+    "get_adapter",
+    "register_adapter",
+    "remap_diagnostics",
+    "unregister_adapter",
+]

pytscheck/adapters/base.py

@@ -0,0 +1,33 @@
+"""The compiler-agnostic adapter protocol."""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from ..models import SourceFile
+
+
+@runtime_checkable
+class CompilerAdapter(Protocol):
+    """Structural protocol implemented by every adapter.
+
+    Implementations live in the consuming tool's package. pytscheck core
+    never imports them directly; registration is via the entry-point group
+    ``pytscheck.adapters``.
+    """
+
+    @property
+    def name(self) -> str:
+        """A short, unique identifier (e.g. ``"teloc"``)."""
+        ...
+
+    def get_sources(self, project_root: str) -> list[SourceFile]:
+        """Return the TypeScript sources to check.
+
+        Must raise :class:`AdapterExtractionError` (not return a diagnostic)
+        if the tool cannot produce TypeScript for any input.
+        """
+        ...
+
+
+__all__ = ["CompilerAdapter"]

pytscheck/adapters/compatibility.py

@@ -0,0 +1,28 @@
+"""Protocol-version and capability compatibility checks."""
+
+from __future__ import annotations
+
+from ..version import ADAPTER_PROTOCOL_VERSION
+from .base import CompilerAdapter
+from .errors import AdapterProtocolError
+
+
+def check_protocol_version(adapter: CompilerAdapter) -> None:
+    """Verify the adapter declares a compatible protocol version.
+
+    Adapters may expose ``protocol_version`` (a string). If absent, we assume
+    "1.x" compatibility and accept.
+    """
+    declared = getattr(adapter, "protocol_version", None)
+    if declared is None:
+        return
+    if not isinstance(declared, str):
+        raise AdapterProtocolError(f"adapter {adapter.name!r} has non-string protocol_version")
+    if declared.split(".")[0] != ADAPTER_PROTOCOL_VERSION.split(".")[0]:
+        raise AdapterProtocolError(
+            f"adapter {adapter.name!r} speaks protocol {declared}, "
+            f"core speaks {ADAPTER_PROTOCOL_VERSION}"
+        )
+
+
+__all__ = ["check_protocol_version"]

pytscheck/adapters/context.py

@@ -0,0 +1,38 @@
+"""Optional framework-independent context for generated project checking."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass(frozen=True, slots=True)
+class DeclarationResource:
+    """Declarations shipped by a Python package, optionally exposed as a module.
+
+    ``resource`` is a package-relative file or directory. Resources may come
+    from ordinary installations or zip importers; no Node installation is needed.
+    """
+
+    package: str
+    resource: str = "types"
+    module: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class ProjectContext:
+    """Opt into project configuration, real files and declaration resources.
+
+    Paths are relative to the root passed to ``check_project`` unless absolute.
+    Caller options override ``compiler_options``, which override tsconfig.
+    Generated paths must not overwrite an existing project file.
+    """
+
+    tsconfig: str | Path | None = None
+    inherit_tsconfig: bool = True
+    include_project_files: bool = True
+    declaration_paths: tuple[str | Path, ...] = ()
+    declaration_resources: tuple[DeclarationResource, ...] = ()
+    compiler_options: dict[str, object] = field(default_factory=dict)
+    max_workspace_files: int = 100_000
+    max_workspace_bytes: int = 512 * 1024 * 1024

pytscheck/adapters/discovery.py

@@ -0,0 +1,43 @@
+"""Entry-point discovery for third-party adapters."""
+
+from __future__ import annotations
+
+from importlib.metadata import entry_points
+
+from ..defaults import DEFAULT_ADAPTER_ENTRY_POINT_GROUP
+from .base import CompilerAdapter
+from .errors import AdapterDiscoveryError
+from .registry import register_adapter
+
+
+def discover_adapters(
+    group: str = DEFAULT_ADAPTER_ENTRY_POINT_GROUP,
+) -> tuple[str, ...]:
+    """Discover and register all adapters advertised under ``group``.
+
+    Returns the names of adapters that were newly registered.
+    """
+    registered: list[str] = []
+    try:
+        eps = entry_points(group=group)
+    except Exception as exc:  # pragma: no cover - importlib.metadata is stable
+        raise AdapterDiscoveryError(f"entry-point discovery failed: {exc}") from exc
+
+    for ep in eps:
+        try:
+            obj = ep.load()
+            adapter = obj() if isinstance(obj, type) else obj
+        except Exception as exc:
+            raise AdapterDiscoveryError(
+                f"failed to load adapter entry point {ep.name!r}: {exc}"
+            ) from exc
+
+        if not isinstance(adapter, CompilerAdapter):
+            raise AdapterDiscoveryError(f"entry point {ep.name!r} did not yield a CompilerAdapter")
+        register_adapter(adapter)
+        registered.append(adapter.name)
+
+    return tuple(registered)
+
+
+__all__ = ["discover_adapters"]

pytscheck/adapters/errors.py

@@ -0,0 +1,25 @@
+"""Adapter-layer exceptions.
+
+Re-exported from the top-level exception hierarchy so callers can catch
+``pytscheck.AdapterError`` without knowing about this submodule.
+"""
+
+from __future__ import annotations
+
+from ..exceptions import (
+    AdapterDiscoveryError,
+    AdapterError,
+    AdapterExtractionError,
+    AdapterMappingError,
+    AdapterProtocolError,
+    AdapterRegistrationError,
+)
+
+__all__ = [
+    "AdapterDiscoveryError",
+    "AdapterError",
+    "AdapterExtractionError",
+    "AdapterMappingError",
+    "AdapterProtocolError",
+    "AdapterRegistrationError",
+]