pycforge 0.15.2__py3-none-any.whl

pycforge/ide/revisions.py

@@ -0,0 +1,400 @@
+from __future__ import annotations
+
+from concurrent.futures import Future
+from dataclasses import dataclass
+from hashlib import sha256
+from threading import Condition, RLock, Thread, current_thread
+from time import monotonic
+from typing import Callable, Sequence
+
+from pycforge.converter.contracts.configuration import DEFAULT_RENDERER, DEFAULT_RULE_SET
+from pycforge.converter.core.canonicalization import canonicalize
+from pycforge.converter.core.diagnostics import Diagnostic
+from pycforge.converter.core.fingerprint import Fingerprint, fingerprint
+from pycforge.converter.core.request import (
+    ConversionRequest,
+    SourceBundle,
+    SourceDocumentInput,
+)
+
+from .model import WorkspaceDocument
+from .positions import TextPositionIndex, build_text_position_index
+
+
+RevisionListener = Callable[["WorkspaceRevision"], None]
+RevisionErrorListener = Callable[[int, BaseException], None]
+
+
+class RevisionBuildError(ValueError):
+    """Raised when an immutable workspace revision cannot be canonicalized."""
+
+    def __init__(self, diagnostics: tuple[Diagnostic, ...]) -> None:
+        self.diagnostics = diagnostics
+        detail = "; ".join(
+            f"{diagnostic.code}: {diagnostic.message}" for diagnostic in diagnostics
+        )
+        super().__init__(detail or "workspace revision could not be canonicalized")
+
+
+@dataclass(frozen=True, slots=True)
+class DocumentIndex:
+    """Cached source-position facts for one immutable document text.
+
+    ``line_starts`` contains Python string offsets. ``utf16_line_starts``
+    contains offsets in UTF-16 code units, matching Qt cursor positions.
+    Both tuples include the first line and add a new entry after every LF.
+    """
+
+    document_id: str
+    module_id: str
+    logical_name: str
+    text_fingerprint: str
+    source_fingerprint: str
+    utf8_sha256: str
+    utf8_size: int
+    line_starts: tuple[int, ...]
+    utf16_line_starts: tuple[int, ...]
+    utf16_compatible: bool
+    position_index: TextPositionIndex
+
+    @property
+    def line_count(self) -> int:
+        return len(self.line_starts)
+
+
+@dataclass(frozen=True, slots=True)
+class WorkspaceRevision:
+    """Fully authenticated, immutable source state ready for conversion."""
+
+    generation: int
+    active_document_id: str
+    source_fingerprint: str
+    bundle_fingerprint: str
+    source_bundle: SourceBundle
+    request: ConversionRequest
+    request_fingerprint: Fingerprint
+    resource_fingerprint: Fingerprint
+    document_indexes: tuple[DocumentIndex, ...]
+    total_utf8_size: int
+
+    @property
+    def active_index(self) -> DocumentIndex:
+        for index in self.document_indexes:
+            if index.document_id == self.active_document_id:
+                return index
+        raise LookupError("active document index is missing")
+
+    @property
+    def line_starts(self) -> tuple[int, ...]:
+        """Cached Python offsets for the active document's line starts."""
+
+        return self.active_index.line_starts
+
+    @property
+    def utf16_line_starts(self) -> tuple[int, ...]:
+        """Cached Qt-compatible offsets for the active document's lines."""
+
+        return self.active_index.utf16_line_starts
+
+    @property
+    def source_utf8_size(self) -> int:
+        return self.active_index.utf8_size
+
+    def index_for(self, document_id: str) -> DocumentIndex:
+        for index in self.document_indexes:
+            if index.document_id == document_id:
+                return index
+        raise KeyError(document_id)
+
+
+@dataclass(frozen=True, slots=True)
+class RevisionInput:
+    """A cheap immutable capture; expensive facts are added by the service."""
+
+    generation: int
+    documents: tuple[WorkspaceDocument, ...]
+    active_document_id: str
+
+
+def source_fingerprint(text: str) -> str:
+    """Return the exact workspace-source identity used by the controller."""
+
+    return fingerprint("workspace-source", text).value
+
+
+def conversion_order(
+    documents: Sequence[WorkspaceDocument],
+) -> tuple[WorkspaceDocument, ...]:
+    primary = tuple(document for document in documents if document.is_primary)
+    if len(primary) != 1:
+        raise ValueError("workspace must contain exactly one primary document")
+    return primary + tuple(document for document in documents if not document.is_primary)
+
+
+def source_bundle_for(
+    documents: Sequence[WorkspaceDocument],
+) -> SourceBundle:
+    ordered = conversion_order(documents)
+
+    def source(document: WorkspaceDocument) -> SourceDocumentInput:
+        return SourceDocumentInput(
+            logical_name=document.logical_name,
+            text=document.text,
+            module_id=document.module_id,
+        )
+
+    return SourceBundle(
+        primary=source(ordered[0]),
+        companions=tuple(source(document) for document in ordered[1:]),
+    )
+
+
+def workspace_bundle_fingerprint(
+    documents: Sequence[WorkspaceDocument],
+) -> str:
+    """Return the exact semantic bundle identity used by WorkspaceController."""
+
+    ordered = conversion_order(documents)
+    semantic = [
+        {
+            "module_id": document.module_id,
+            "logical_name": document.logical_name,
+            "text": document.text,
+            "is_primary": index == 0,
+        }
+        for index, document in enumerate(ordered)
+    ]
+    return fingerprint("workspace-source-bundle", semantic).value
+
+
+def _document_index(document: WorkspaceDocument) -> DocumentIndex:
+    text = document.text
+    encoded = text.encode("utf-8")
+    positions = build_text_position_index(text)
+    return DocumentIndex(
+        document_id=document.document_id,
+        module_id=document.module_id,
+        logical_name=document.logical_name,
+        text_fingerprint=fingerprint("workspace-document-text", text).value,
+        source_fingerprint=source_fingerprint(text),
+        utf8_sha256=sha256(encoded).hexdigest(),
+        utf8_size=len(encoded),
+        line_starts=positions.line_starts,
+        utf16_line_starts=positions.utf16_line_starts,
+        utf16_compatible=positions.utf16_compatible,
+        position_index=positions,
+    )
+
+
+def build_workspace_revision(revision_input: RevisionInput) -> WorkspaceRevision:
+    """Build all proportional revision facts on a non-GUI worker thread."""
+
+    generation = revision_input.generation
+    if not isinstance(generation, int) or isinstance(generation, bool) or generation < 0:
+        raise ValueError("revision generation must be a non-negative integer")
+    documents = revision_input.documents
+    if not documents:
+        raise ValueError("workspace revision must contain at least one document")
+    if any(not isinstance(document, WorkspaceDocument) for document in documents):
+        raise TypeError("workspace revision documents must be WorkspaceDocument values")
+    document_ids = tuple(document.document_id for document in documents)
+    if len(document_ids) != len(set(document_ids)):
+        raise ValueError("workspace revision document IDs must be unique")
+    if revision_input.active_document_id not in document_ids:
+        raise ValueError("active document must belong to the workspace revision")
+
+    active = next(
+        document
+        for document in documents
+        if document.document_id == revision_input.active_document_id
+    )
+    bundle = source_bundle_for(documents)
+    request = ConversionRequest(
+        bundle,
+        rule_set_version=DEFAULT_RULE_SET,
+        renderer_version=DEFAULT_RENDERER,
+    )
+    canonical, diagnostics = canonicalize(request)
+    if canonical is None:
+        raise RevisionBuildError(diagnostics)
+
+    indexes = tuple(_document_index(document) for document in documents)
+    return WorkspaceRevision(
+        generation=generation,
+        active_document_id=revision_input.active_document_id,
+        source_fingerprint=source_fingerprint(active.text),
+        bundle_fingerprint=workspace_bundle_fingerprint(documents),
+        source_bundle=canonical.request.source_bundle,
+        request=canonical.request,
+        request_fingerprint=canonical.request_fingerprint,
+        resource_fingerprint=canonical.resource_fingerprint,
+        document_indexes=indexes,
+        total_utf8_size=sum(index.utf8_size for index in indexes),
+    )
+
+
+@dataclass(slots=True)
+class _RevisionJob:
+    submission: int
+    revision_input: RevisionInput
+    future: Future[WorkspaceRevision]
+
+
+class WorkspaceRevisionService:
+    """One-active, one-latest-pending immutable revision builder.
+
+    The service deliberately owns one dedicated thread. Submissions only
+    capture the already-immutable document tuple; source-proportional work is
+    performed by the service thread. A newer submission replaces the pending
+    job and retires an active job's publication authority.
+    """
+
+    def __init__(
+        self,
+        on_revision: RevisionListener | None = None,
+        *,
+        on_error: RevisionErrorListener | None = None,
+        builder: Callable[[RevisionInput], WorkspaceRevision] = build_workspace_revision,
+        thread_name: str = "pycforge-revision-index",
+    ) -> None:
+        self._on_revision = on_revision
+        self._on_error = on_error
+        self._builder = builder
+        self._condition = Condition(RLock())
+        self._active: _RevisionJob | None = None
+        self._pending: _RevisionJob | None = None
+        self._latest_submission = 0
+        self._closed = False
+        self._thread = Thread(
+            target=self._run,
+            name=thread_name,
+            daemon=True,
+        )
+        self._thread.start()
+
+    def submit(
+        self,
+        generation: int,
+        documents: Sequence[WorkspaceDocument],
+        active_document_id: str,
+    ) -> Future[WorkspaceRevision]:
+        """Capture a revision request without traversing any document text."""
+
+        revision_input = RevisionInput(
+            generation=generation,
+            documents=tuple(documents),
+            active_document_id=active_document_id,
+        )
+        future: Future[WorkspaceRevision] = Future()
+        with self._condition:
+            if self._closed:
+                raise RuntimeError("workspace revision service is closed")
+            self._latest_submission += 1
+            job = _RevisionJob(self._latest_submission, revision_input, future)
+            replaced = self._pending
+            self._pending = job
+            if replaced is not None:
+                replaced.future.cancel()
+            self._condition.notify()
+        return future
+
+    @property
+    def active_generation(self) -> int | None:
+        with self._condition:
+            return (
+                None
+                if self._active is None
+                else self._active.revision_input.generation
+            )
+
+    @property
+    def pending_generation(self) -> int | None:
+        with self._condition:
+            return (
+                None
+                if self._pending is None
+                else self._pending.revision_input.generation
+            )
+
+    @property
+    def is_closed(self) -> bool:
+        with self._condition:
+            return self._closed
+
+    def wait_idle(self, timeout: float | None = None) -> bool:
+        """Wait until neither an active nor pending computation remains."""
+
+        deadline = None if timeout is None else monotonic() + timeout
+        with self._condition:
+            while self._active is not None or self._pending is not None:
+                remaining = None if deadline is None else deadline - monotonic()
+                if remaining is not None and remaining <= 0:
+                    return False
+                self._condition.wait(remaining)
+            return True
+
+    def close(self, *, wait: bool = True, timeout: float | None = None) -> None:
+        """Retire publication immediately and optionally join the worker."""
+
+        with self._condition:
+            if not self._closed:
+                self._closed = True
+                pending = self._pending
+                self._pending = None
+                if pending is not None:
+                    pending.future.cancel()
+                self._condition.notify_all()
+        if wait and current_thread() is not self._thread:
+            self._thread.join(timeout)
+
+    def _run(self) -> None:
+        while True:
+            with self._condition:
+                while self._pending is None and not self._closed:
+                    self._condition.wait()
+                if self._pending is None and self._closed:
+                    self._condition.notify_all()
+                    return
+                job = self._pending
+                self._pending = None
+                self._active = job
+                self._condition.notify_all()
+
+            if not job.future.set_running_or_notify_cancel():
+                with self._condition:
+                    if self._active is job:
+                        self._active = None
+                    self._condition.notify_all()
+                continue
+
+            revision: WorkspaceRevision | None = None
+            failure: BaseException | None = None
+            try:
+                revision = self._builder(job.revision_input)
+            except BaseException as exc:
+                failure = exc
+
+            with self._condition:
+                if self._active is job:
+                    self._active = None
+                publishable = (
+                    not self._closed
+                    and job.submission == self._latest_submission
+                    and self._pending is None
+                )
+                self._condition.notify_all()
+            if failure is None:
+                assert revision is not None
+                if publishable and self._on_revision is not None:
+                    try:
+                        self._on_revision(revision)
+                    except Exception:
+                        pass
+                job.future.set_result(revision)
+            else:
+                if publishable and self._on_error is not None:
+                    try:
+                        self._on_error(job.revision_input.generation, failure)
+                    except Exception:
+                        pass
+                job.future.set_exception(failure)

pycforge/ide/search_service.py

@@ -0,0 +1,280 @@
+"""Bounded background literal search for the optional PyQt workspace.
+
+The service in this module is deliberately independent of Qt.  It owns one
+daemon worker thread and one replaceable pending request, so rapid editor or
+query changes cannot build an unbounded queue.  Results contain Qt-compatible
+UTF-16 positions, but only a bounded prefix of the matches is retained.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import re
+from threading import Condition, Thread
+from time import monotonic
+from typing import Callable
+
+
+DEFAULT_MATCH_LIMIT = 5_000
+DEFAULT_SCAN_CHUNK = 64 * 1024
+
+
+@dataclass(frozen=True, slots=True)
+class LiteralSearchResult:
+    """The bounded result of one immutable literal-search request."""
+
+    generation: int
+    ranges: tuple[tuple[int, int], ...]
+    total_count: int
+    elapsed_seconds: float
+
+    @property
+    def truncated(self) -> bool:
+        return self.total_count > len(self.ranges)
+
+
+@dataclass(frozen=True, slots=True)
+class _SearchRequest:
+    generation: int
+    text: str
+    query: str
+    match_case: bool
+    whole_word: bool
+    callback: Callable[[LiteralSearchResult], None]
+
+
+def _qt_ranges(
+    text: str, ranges: tuple[tuple[int, int], ...]
+) -> tuple[tuple[int, int], ...]:
+    """Convert ordered Python code-point ranges to Qt UTF-16 positions."""
+
+    converted: list[tuple[int, int]] = []
+    codepoint_position = 0
+    qt_position = 0
+    for start, end in ranges:
+        qt_position += len(text[codepoint_position:start].encode("utf-16-le")) // 2
+        qt_start = qt_position
+        qt_position += len(text[start:end].encode("utf-16-le")) // 2
+        converted.append((qt_start, qt_position))
+        codepoint_position = end
+    return tuple(converted)
+
+
+def _bounded_literal_search(
+    request: _SearchRequest,
+    *,
+    match_limit: int,
+    scan_chunk: int,
+    cancelled: Callable[[], bool],
+) -> LiteralSearchResult | None:
+    """Scan an immutable request in cancellable windows.
+
+    Searching bounded windows instead of invoking one full-document regex
+    search gives the supervisor a cancellation point even when the document
+    contains no matches.  Window ownership is based on match start positions;
+    an overlap large enough for the literal and its word-boundary lookahead
+    preserves the same non-overlapping semantics as ``re.finditer``.
+    """
+
+    started = monotonic()
+    if cancelled():
+        return None
+    if not request.query or len(request.query) > len(request.text):
+        return LiteralSearchResult(request.generation, (), 0, monotonic() - started)
+
+    expression = re.escape(request.query)
+    if request.whole_word:
+        expression = rf"(?<!\w){expression}(?!\w)"
+    flags = 0 if request.match_case else re.IGNORECASE
+    pattern = re.compile(expression, flags)
+
+    stored: list[tuple[int, int]] = []
+    total_count = 0
+    text_length = len(request.text)
+    # Avoid repeatedly scanning a very large literal through small overlapping
+    # windows.  Ordinary queries retain the 64 KiB cancellation granularity.
+    ownership_width = max(scan_chunk, len(request.query) + 1)
+    ownership_start = 0
+    last_match_end = 0
+    matches_since_cancel_check = 0
+
+    while ownership_start < text_length:
+        if cancelled():
+            return None
+        ownership_end = min(text_length, ownership_start + ownership_width)
+        search_start = max(ownership_start, last_match_end)
+        # Include enough right context for a match that begins in this window
+        # plus one code point for the whole-word lookahead.
+        search_end = min(
+            text_length,
+            ownership_end + len(request.query) + (1 if request.whole_word else 0),
+        )
+        for match in pattern.finditer(request.text, search_start, search_end):
+            start, end = match.span()
+            if start >= ownership_end:
+                break
+            total_count += 1
+            if len(stored) < match_limit:
+                stored.append((start, end))
+            last_match_end = end
+            matches_since_cancel_check += 1
+            if matches_since_cancel_check >= 256:
+                matches_since_cancel_check = 0
+                if cancelled():
+                    return None
+        ownership_start = ownership_end
+
+    return LiteralSearchResult(
+        request.generation,
+        _qt_ranges(request.text, tuple(stored)),
+        total_count,
+        monotonic() - started,
+    )
+
+
+class AsyncLiteralSearchService:
+    """Latest-wins literal search with one daemon worker and bounded results."""
+
+    def __init__(
+        self,
+        *,
+        match_limit: int = DEFAULT_MATCH_LIMIT,
+        scan_chunk: int = DEFAULT_SCAN_CHUNK,
+    ) -> None:
+        if isinstance(match_limit, bool) or not isinstance(match_limit, int):
+            raise TypeError("match_limit must be an integer")
+        if isinstance(scan_chunk, bool) or not isinstance(scan_chunk, int):
+            raise TypeError("scan_chunk must be an integer")
+        if match_limit <= 0:
+            raise ValueError("match_limit must be positive")
+        if scan_chunk <= 0:
+            raise ValueError("scan_chunk must be positive")
+        self._match_limit = match_limit
+        self._scan_chunk = scan_chunk
+        self._condition = Condition()
+        self._generation = 0
+        self._active_generation: int | None = None
+        self._pending: _SearchRequest | None = None
+        self._closed = False
+        self._worker = Thread(
+            target=self._worker_main,
+            name="pycforge-literal-search",
+            daemon=True,
+        )
+        self._worker.start()
+
+    @property
+    def worker_is_daemon(self) -> bool:
+        return self._worker.daemon
+
+    @property
+    def active_generation(self) -> int | None:
+        with self._condition:
+            return self._active_generation
+
+    @property
+    def pending_generation(self) -> int | None:
+        with self._condition:
+            return self._pending.generation if self._pending is not None else None
+
+    def submit(
+        self,
+        text: str,
+        query: str,
+        *,
+        match_case: bool = False,
+        whole_word: bool = False,
+        callback: Callable[[LiteralSearchResult], None],
+    ) -> int:
+        """Replace the pending request and return its monotonic generation."""
+
+        if not isinstance(text, str) or not isinstance(query, str):
+            raise TypeError("text and query must be strings")
+        if not callable(callback):
+            raise TypeError("callback must be callable")
+        with self._condition:
+            if self._closed:
+                raise RuntimeError("search service is closed")
+            self._generation += 1
+            generation = self._generation
+            self._pending = _SearchRequest(
+                generation,
+                text,
+                query,
+                bool(match_case),
+                bool(whole_word),
+                callback,
+            )
+            self._condition.notify()
+            return generation
+
+    def cancel(self) -> int:
+        """Cancel the active generation and discard the pending request."""
+
+        with self._condition:
+            if self._closed:
+                return self._generation
+            self._generation += 1
+            self._pending = None
+            self._condition.notify()
+            return self._generation
+
+    def close(self, *, wait_seconds: float = 0.05) -> None:
+        """Stop accepting work and cooperatively end the daemon worker."""
+
+        with self._condition:
+            if self._closed:
+                return
+            self._closed = True
+            self._generation += 1
+            self._pending = None
+            self._condition.notify()
+        if wait_seconds > 0:
+            self._worker.join(timeout=wait_seconds)
+
+    def _is_cancelled(self, generation: int) -> bool:
+        with self._condition:
+            return self._closed or generation != self._generation
+
+    def _worker_main(self) -> None:
+        while True:
+            with self._condition:
+                while self._pending is None and not self._closed:
+                    self._condition.wait()
+                if self._closed:
+                    return
+                request = self._pending
+                self._pending = None
+                assert request is not None
+                self._active_generation = request.generation
+
+            result = _bounded_literal_search(
+                request,
+                match_limit=self._match_limit,
+                scan_chunk=self._scan_chunk,
+                cancelled=lambda: self._is_cancelled(request.generation),
+            )
+
+            with self._condition:
+                if self._active_generation == request.generation:
+                    self._active_generation = None
+                deliver = (
+                    result is not None
+                    and not self._closed
+                    and request.generation == self._generation
+                )
+            if deliver:
+                try:
+                    request.callback(result)
+                except Exception:
+                    # A disappearing Qt receiver or a consumer callback must
+                    # not retire the sole search worker.
+                    continue
+
+
+__all__ = [
+    "AsyncLiteralSearchService",
+    "DEFAULT_MATCH_LIMIT",
+    "DEFAULT_SCAN_CHUNK",
+    "LiteralSearchResult",
+]