cseq 0.0.1__py3-none-any.whl

cseq/sequence.py

@@ -0,0 +1,281 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field, replace
+
+from .model import CallSiteRecord, CallTargetKind, ProjectIndex
+
+
+@dataclass(frozen=True, slots=True)
+class SequenceMessage:
+    caller: str
+    callee: str
+    label: str
+    external_as_self: bool = False
+    control_context: tuple[str, ...] = ()
+    recursive: bool = False
+    guard_expression: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class SequenceRegion:
+    context: tuple[str, ...]
+    start_message: int
+    end_message: int
+
+    @property
+    def kind(self) -> str:
+        return self.context[-1] if self.context else "ROOT"
+
+
+@dataclass(frozen=True, slots=True)
+class FoldSummary:
+    start_message: int
+    end_message: int
+    hidden_count: int
+    reason: str = "budget"
+
+
+@dataclass(frozen=True, slots=True)
+class FoldPlan:
+    visible_indices: tuple[int, ...]
+    collapsed: tuple[FoldSummary, ...]
+
+
+@dataclass(slots=True)
+class SequenceModel:
+    entry: str
+    messages: list[SequenceMessage] = field(default_factory=list)
+    regions: list[SequenceRegion] = field(default_factory=list)
+
+
+def resolve_direct_calls(index: ProjectIndex) -> None:
+    # Demand-driven symbol indexing: direct-call resolution only needs function
+    # names that actually occur at call sites.  Building a dictionary for every
+    # function is needlessly expensive on multi-million-LOC projects with many
+    # uncalled/static functions.
+    needed_names = {c.callee_name for c in index.callsites if c.callee_name}
+    functions_by_name: dict[str, list] = {}
+    if needed_names:
+        for f in index.functions_named(needed_names):
+            if f.name in needed_names:
+                functions_by_name.setdefault(f.name, []).append(f)
+
+    resolved: list[CallSiteRecord] = []
+    for c in index.callsites:
+        matches = functions_by_name.get(c.callee_name or "", [])
+        same_tu_static = [m for m in matches if m.storage_class == "static" and m.source_path == c.source_path]
+        if same_tu_static:
+            matches = same_tu_static
+        else:
+            matches = [m for m in matches if m.storage_class != "static"]
+        if len(matches) == 1:
+            target = matches[0]
+            resolved.append(replace(c, target_kind=CallTargetKind.INTERNAL_EXACT,
+                                    target_function_id=target.qualified_id,
+                                    target_function_ids=(target.qualified_id,)))
+        elif len(matches) > 1:
+            resolved.append(replace(c, target_kind=CallTargetKind.INTERNAL_POSSIBLE,
+                                    target_function_ids=tuple(sorted(m.qualified_id for m in matches)),
+                                    unknown_possible=False))
+        elif c.callee_name:
+            resolved.append(replace(c, target_kind=CallTargetKind.EXTERNAL_DECLARED))
+        else:
+            resolved.append(c)
+    index.callsites[:] = resolved
+
+
+def build_sequence(index: ProjectIndex, entry: str) -> SequenceModel:
+    by_caller: dict[str, list[CallSiteRecord]] = {}
+    for c in index.callsites:
+        by_caller.setdefault(c.caller_name, []).append(c)
+    model = SequenceModel(entry=entry)
+    active: list[str] = []
+
+    def append_message(msg: SequenceMessage) -> None:
+        model.messages.append(msg)
+
+    def visit(name: str, inherited_context: tuple[str, ...] = ()) -> None:
+        active.append(name)
+        try:
+            for call in by_caller.get(name, []):
+                context = inherited_context + tuple(call.control_context)
+                if call.guard_expression:
+                    context = context + (f"GUARD:{call.guard_expression}",)
+                if call.target_kind == CallTargetKind.INTERNAL_EXACT and call.callee_name:
+                    recursive = call.callee_name in active
+                    append_message(SequenceMessage(name, call.callee_name, call.raw_text,
+                                                   control_context=context, recursive=recursive, guard_expression=call.guard_expression))
+                    if not recursive:
+                        visit(call.callee_name, context)
+                elif call.target_kind == CallTargetKind.INDIRECT_EXACT and call.target_function_ids:
+                    target_id = call.target_function_ids[0]
+                    target = next(iter(index.functions_by_ids({target_id})), None)
+                    target_name = target.name if target else "<indirect>"
+                    recursive = target_name in active
+                    append_message(SequenceMessage(name, target_name, call.raw_text,
+                                                   control_context=context, recursive=recursive, guard_expression=call.guard_expression))
+                    if target and not recursive:
+                        visit(target.name, context)
+                elif call.target_kind == CallTargetKind.INDIRECT_POSSIBLE and call.target_function_ids:
+                    names = []
+                    by_id = {fn.qualified_id: fn for fn in index.functions_by_ids(set(call.target_function_ids))}
+                    for tid in call.target_function_ids:
+                        f = by_id.get(tid)
+                        if f and f.name not in names:
+                            names.append(f.name)
+                    append_message(SequenceMessage(name, name, f"? {call.raw_text} -> {{{', '.join(names)}}}",
+                                                   external_as_self=True, control_context=context, guard_expression=call.guard_expression))
+                elif call.target_kind == CallTargetKind.EXTERNAL_DECLARED:
+                    append_message(SequenceMessage(name, name, call.raw_text, external_as_self=True,
+                                                   control_context=context, guard_expression=call.guard_expression))
+                else:
+                    append_message(SequenceMessage(name, name, f"? {call.raw_text}", external_as_self=True,
+                                                   control_context=context, guard_expression=call.guard_expression))
+        finally:
+            active.pop()
+
+    visit(entry)
+    model.regions = derive_regions(model.messages)
+    return model
+
+
+def derive_regions(messages: list[SequenceMessage]) -> list[SequenceRegion]:
+    """Derive contiguous control regions from message context paths.
+
+    Region information is presentation-neutral metadata. It records where a
+    context is active without expanding loops or recursion.
+    """
+    open_at: dict[tuple[str, ...], int] = {}
+    regions: list[SequenceRegion] = []
+    previous: set[tuple[str, ...]] = set()
+    for i, msg in enumerate(messages):
+        current = {msg.control_context[:depth] for depth in range(1, len(msg.control_context) + 1)}
+        for ctx in sorted(previous - current, key=len, reverse=True):
+            start = open_at.pop(ctx, i)
+            regions.append(SequenceRegion(ctx, start, i - 1))
+        for ctx in sorted(current - previous, key=len):
+            open_at[ctx] = i
+        previous = current
+    end = len(messages) - 1
+    for ctx, start in sorted(open_at.items(), key=lambda x: len(x[0]), reverse=True):
+        regions.append(SequenceRegion(ctx, start, end))
+    return sorted(regions, key=lambda r: (r.start_message, len(r.context), r.end_message))
+
+
+def build_fold_plan(model: SequenceModel, max_messages: int = 200) -> FoldPlan:
+    """Create a deterministic semantic fold plan without changing Sequence IR.
+
+    The budget is spent on semantically valuable events first.  This avoids the
+    failure mode where a uniformly sampled trace hides the one unresolved call,
+    recursion edge, guard boundary, or CPU/control boundary the user actually
+    needs to investigate.
+    """
+    total = len(model.messages)
+    budget = max(1, int(max_messages))
+    if total <= budget:
+        return FoldPlan(tuple(range(total)), ())
+
+    def score(i: int, msg: SequenceMessage) -> int:
+        value = 0
+        if i in {0, total - 1}:
+            value += 10_000
+        if msg.recursive:
+            value += 1_000
+        if msg.label.startswith('?'):
+            value += 900
+        if msg.external_as_self:
+            value += 700
+        if msg.guard_expression:
+            value += 650
+        contexts = tuple(x.upper() for x in msg.control_context)
+        if any(x.startswith('CASE:') or x == 'DEFAULT' for x in contexts):
+            value += 600
+        if any(x.startswith('SWITCH:') for x in contexts):
+            value += 550
+        if any(x.startswith('LOOP:') for x in contexts):
+            value += 500
+        # Context transitions are important entry/exit landmarks.
+        before = model.messages[i - 1].control_context if i > 0 else ()
+        after = model.messages[i + 1].control_context if i + 1 < total else ()
+        if msg.control_context != before:
+            value += 450
+        if msg.control_context != after:
+            value += 400
+        return value
+
+    ranked = sorted(range(total), key=lambda i: (-score(i, model.messages[i]), i))
+    selected = sorted(ranked[:budget])
+
+    # If spare budget remains after de-duplication (defensive), distribute it
+    # across the largest currently hidden spans rather than clustering at start.
+    selected_set = set(selected)
+    while len(selected_set) < budget:
+        hidden = [i for i in range(total) if i not in selected_set]
+        if not hidden:
+            break
+        # Pick the point farthest from any visible event.
+        pick = max(hidden, key=lambda i: (min(abs(i-j) for j in selected_set), -i))
+        selected_set.add(pick)
+    selected = sorted(selected_set)
+
+    collapsed: list[FoldSummary] = []
+    cursor = 0
+    visible = set(selected)
+    while cursor < total:
+        if cursor in visible:
+            cursor += 1
+            continue
+        start = cursor
+        while cursor < total and cursor not in visible:
+            cursor += 1
+        end = cursor - 1
+        hidden_msgs = model.messages[start:end + 1]
+        repeated = len({(m.caller, m.callee, m.label, m.control_context) for m in hidden_msgs}) == 1
+        one_region = len({m.control_context for m in hidden_msgs}) == 1
+        reason = 'repetition' if repeated else ('within-region-budget' if one_region else 'budget')
+        collapsed.append(FoldSummary(start, end, end - start + 1, reason))
+    return FoldPlan(tuple(selected), tuple(collapsed))
+
+
+def render_plantuml(model: SequenceModel) -> str:
+    participants: list[str] = []
+    for m in model.messages:
+        for name in (m.caller, m.callee):
+            if name not in participants:
+                participants.append(name)
+    lines = ["@startuml", "title cseq sequence"]
+    for name in participants:
+        lines.append(f'participant "{_escape(name)}" as {_ident(name)}')
+    lines.append("")
+    open_context: tuple[str, ...] = ()
+    for m in model.messages:
+        common = 0
+        while common < len(open_context) and common < len(m.control_context) and open_context[common] == m.control_context[common]:
+            common += 1
+        for _ in range(len(open_context) - common):
+            lines.append("end")
+        for ctx in m.control_context[common:]:
+            if ctx.lower().startswith("loop:"):
+                label = ctx.split(':', 1)[1]
+                if label.startswith("[infinite] "):
+                    lines.append(f"loop [infinite] {_escape(label[len('[infinite] '):])}")
+                else:
+                    lines.append(f"loop {_escape(label)}")
+            else:
+                lines.append(f"group {_escape(ctx)}")
+        open_context = m.control_context
+        suffix = " <<recursive>>" if m.recursive else ""
+        lines.append(f"{_ident(m.caller)} -> {_ident(m.callee)} : {_escape(m.label)}{suffix}")
+    for _ in open_context:
+        lines.append("end")
+    lines.append("@enduml")
+    return "\n".join(lines) + "\n"
+
+
+def _ident(name: str) -> str:
+    safe = "".join(c if c.isalnum() or c == "_" else "_" for c in name)
+    return f"p_{safe}"
+
+
+def _escape(text: str) -> str:
+    return text.replace("\\", "\\\\").replace('"', '\\"').replace("\n", " ")

cseq/server.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+from http.server import SimpleHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+import os
+import re
+from typing import BinaryIO
+
+_RANGE_RE = re.compile(r"bytes=(\d*)-(\d*)$")
+
+
+class CseqRequestHandler(SimpleHTTPRequestHandler):
+    """Static-file handler with single-range support for large .cseqdata files."""
+
+    server_version = "cseq-http/1"
+
+    def end_headers(self) -> None:
+        self.send_header("Cache-Control", "no-store")
+        self.send_header("Accept-Ranges", "bytes")
+        super().end_headers()
+
+    def send_head(self):
+        path = Path(self.translate_path(self.path))
+        if path.is_dir():
+            return super().send_head()
+        try:
+            stat = path.stat()
+        except OSError:
+            self.send_error(404, "File not found")
+            return None
+        range_header = self.headers.get("Range")
+        if not range_header:
+            self._cseq_range = None
+            return super().send_head()
+        parsed = _parse_range(range_header, stat.st_size)
+        if parsed is None:
+            self.send_response(416)
+            self.send_header("Content-Range", f"bytes */{stat.st_size}")
+            self.send_header("Content-Length", "0")
+            self.end_headers()
+            return None
+        start, end = parsed
+        ctype = self.guess_type(str(path))
+        try:
+            f = path.open("rb")
+        except OSError:
+            self.send_error(404, "File not found")
+            return None
+        self.send_response(206)
+        self.send_header("Content-type", ctype)
+        self.send_header("Content-Range", f"bytes {start}-{end}/{stat.st_size}")
+        self.send_header("Content-Length", str(end - start + 1))
+        self.send_header("Last-Modified", self.date_time_string(stat.st_mtime))
+        self.end_headers()
+        f.seek(start)
+        self._cseq_range = (start, end)
+        return f
+
+    def copyfile(self, source: BinaryIO, outputfile: BinaryIO) -> None:
+        byte_range = getattr(self, "_cseq_range", None)
+        if byte_range is None:
+            return super().copyfile(source, outputfile)
+        start, end = byte_range
+        remaining = end - start + 1
+        while remaining > 0:
+            chunk = source.read(min(1024 * 1024, remaining))
+            if not chunk:
+                break
+            outputfile.write(chunk)
+            remaining -= len(chunk)
+
+
+def _parse_range(value: str, size: int) -> tuple[int, int] | None:
+    m = _RANGE_RE.fullmatch(value.strip())
+    if not m or size <= 0:
+        return None
+    a, b = m.groups()
+    if not a and not b:
+        return None
+    if not a:
+        length = int(b)
+        if length <= 0:
+            return None
+        start = max(0, size - length)
+        return start, size - 1
+    start = int(a)
+    end = int(b) if b else size - 1
+    if start >= size or start < 0 or end < start:
+        return None
+    return start, min(end, size - 1)
+
+
+def make_server(root: str | Path, host: str = "127.0.0.1", port: int = 8000) -> ThreadingHTTPServer:
+    directory = str(Path(root).resolve())
+
+    class Handler(CseqRequestHandler):
+        def __init__(self, *args, **kwargs):
+            super().__init__(*args, directory=directory, **kwargs)
+
+        def log_message(self, format: str, *args) -> None:
+            # Keep CLI output clean; request logs can be added via a future verbose flag.
+            return
+
+    return ThreadingHTTPServer((host, port), Handler)

cseq/source_index.py

@@ -0,0 +1,227 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import sqlite3
+import threading
+import os
+import time
+from pathlib import Path
+from typing import Any
+
+
+class SourceFingerprintIndex:
+    """Persistent metadata/hash index for project source files.
+
+    The index is only an acceleration cache. A content hash is reused only when
+    the full stat identity used here is unchanged; otherwise bytes are hashed
+    again. Dependency snapshots are stored separately and validated against the
+    current file hashes before reuse.
+    """
+
+    SCHEMA_VERSION = 1
+
+    def __init__(self, path: str | Path) -> None:
+        self.path = Path(path)
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self.connection = sqlite3.connect(self.path, check_same_thread=False)
+        self._lock = threading.RLock()
+        self.connection.execute("PRAGMA journal_mode=OFF")
+        self.connection.execute("PRAGMA synchronous=OFF")
+        self.connection.execute("PRAGMA temp_store=MEMORY")
+        self.connection.executescript(
+            """
+            CREATE TABLE IF NOT EXISTS meta(
+              key TEXT PRIMARY KEY,
+              value TEXT NOT NULL
+            );
+            CREATE TABLE IF NOT EXISTS files(
+              path TEXT PRIMARY KEY,
+              size INTEGER NOT NULL,
+              mtime_ns INTEGER NOT NULL,
+              ctime_ns INTEGER NOT NULL,
+              dev INTEGER NOT NULL,
+              ino INTEGER NOT NULL,
+              sha256 TEXT NOT NULL
+            ) WITHOUT ROWID;
+            CREATE TABLE IF NOT EXISTS dependencies(
+              tu_path TEXT NOT NULL,
+              context_hash TEXT NOT NULL,
+              source_hash TEXT NOT NULL,
+              fingerprint TEXT NOT NULL,
+              records_json TEXT NOT NULL,
+              PRIMARY KEY(tu_path, context_hash)
+            ) WITHOUT ROWID;
+            """
+        )
+        row = self.connection.execute(
+            "SELECT value FROM meta WHERE key='schema_version'"
+        ).fetchone()
+        old = int(row[0]) if row and str(row[0]).isdigit() else None
+        if old != self.SCHEMA_VERSION:
+            self.connection.execute("DELETE FROM files")
+            self.connection.execute("DELETE FROM dependencies")
+        self.connection.execute(
+            "INSERT OR REPLACE INTO meta(key,value) VALUES('schema_version',?)",
+            (str(self.SCHEMA_VERSION),),
+        )
+        self.connection.commit()
+
+        self.hash_hits = 0
+        self.hash_misses = 0
+        self.dependency_hits = 0
+        self.dependency_misses = 0
+
+    @staticmethod
+    def _stat_identity(path: Path) -> tuple[int, int, int, int, int]:
+        st = path.stat()
+        return (
+            int(st.st_size),
+            int(getattr(st, "st_mtime_ns", int(st.st_mtime * 1_000_000_000))),
+            int(getattr(st, "st_ctime_ns", int(st.st_ctime * 1_000_000_000))),
+            int(getattr(st, "st_dev", 0)),
+            int(getattr(st, "st_ino", 0)),
+        )
+
+    @staticmethod
+    def _hash_file(path: Path) -> str:
+        h = hashlib.sha256()
+        with path.open("rb") as f:
+            for chunk in iter(lambda: f.read(1024 * 1024), b""):
+                h.update(chunk)
+        return h.hexdigest()
+
+    def content_hash(self, path: str | Path) -> str:
+        p = Path(path).resolve()
+        key = str(p)
+        size, mtime_ns, ctime_ns, dev, ino = self._stat_identity(p)
+        with self._lock:
+            row = self.connection.execute(
+                "SELECT size,mtime_ns,ctime_ns,dev,ino,sha256 FROM files WHERE path=?",
+                (key,),
+            ).fetchone()
+        if row and tuple(row[:5]) == (size, mtime_ns, ctime_ns, dev, ino):
+            # Windows filesystems can expose unchanged stat timestamps for a
+            # same-size rewrite performed within one clock tick.  Revalidate
+            # only very recent files; normal warm-cache scans remain metadata-
+            # only while immediate edits cannot silently reuse stale content.
+            recent_windows_file = (
+                os.name == "nt"
+                and 0 <= time.time_ns() - mtime_ns <= 250_000_000
+            )
+            if not recent_windows_file:
+                with self._lock:
+                    self.hash_hits += 1
+                return str(row[5])
+            digest = self._hash_file(p)
+            if digest == str(row[5]):
+                with self._lock:
+                    self.hash_hits += 1
+                return digest
+            with self._lock:
+                self.connection.execute(
+                    """INSERT OR REPLACE INTO files(path,size,mtime_ns,ctime_ns,dev,ino,sha256)
+                       VALUES(?,?,?,?,?,?,?)""",
+                    (key, size, mtime_ns, ctime_ns, dev, ino, digest),
+                )
+                self.hash_misses += 1
+            return digest
+        digest = self._hash_file(p)
+        with self._lock:
+            self.connection.execute(
+                """INSERT OR REPLACE INTO files(path,size,mtime_ns,ctime_ns,dev,ino,sha256)
+                   VALUES(?,?,?,?,?,?,?)""",
+                (key, size, mtime_ns, ctime_ns, dev, ino, digest),
+            )
+            self.hash_misses += 1
+        return digest
+
+    def remove_missing_files(self, current_paths: set[str], project_root: str | Path | None = None) -> int:
+        root = Path(project_root).resolve() if project_root is not None else None
+        with self._lock:
+            rows = [r[0] for r in self.connection.execute("SELECT path FROM files")]
+            stale: list[str] = []
+            for path_text in rows:
+                if path_text in current_paths:
+                    continue
+                if root is not None:
+                    try:
+                        Path(path_text).resolve().relative_to(root)
+                    except ValueError:
+                        # External include hashes are also cached here. A project
+                        # scan must not evict them merely because they are not
+                        # project-owned source files.
+                        continue
+                stale.append(path_text)
+            for path_text in stale:
+                self.connection.execute("DELETE FROM files WHERE path=?", (path_text,))
+        return len(stale)
+
+    def dependency_snapshot(
+        self, tu_path: str, context_hash: str, source_hash: str
+    ) -> tuple[str, list[dict[str, Any]]] | None:
+        with self._lock:
+            row = self.connection.execute(
+                """SELECT source_hash,fingerprint,records_json
+                   FROM dependencies WHERE tu_path=? AND context_hash=?""",
+                (tu_path, context_hash),
+            ).fetchone()
+        if not row or row[0] != source_hash:
+            with self._lock:
+                self.dependency_misses += 1
+            return None
+        try:
+            records = json.loads(row[2])
+        except (TypeError, json.JSONDecodeError):
+            with self._lock:
+                self.dependency_misses += 1
+            return None
+        if not isinstance(records, list):
+            with self._lock:
+                self.dependency_misses += 1
+            return None
+        return str(row[1]), records
+
+    def note_dependency_hit(self) -> None:
+        with self._lock:
+            self.dependency_hits += 1
+
+    def note_dependency_miss(self) -> None:
+        with self._lock:
+            self.dependency_misses += 1
+
+    def put_dependency_snapshot(
+        self,
+        tu_path: str,
+        context_hash: str,
+        source_hash: str,
+        fingerprint: str,
+        records: list[dict[str, Any]],
+    ) -> None:
+        with self._lock:
+            self.connection.execute(
+                """INSERT OR REPLACE INTO dependencies(
+                     tu_path,context_hash,source_hash,fingerprint,records_json
+                   ) VALUES(?,?,?,?,?)""",
+                (
+                    tu_path,
+                    context_hash,
+                    source_hash,
+                    fingerprint,
+                    json.dumps(records, ensure_ascii=False, sort_keys=True, separators=(",", ":")),
+                ),
+            )
+
+    def commit(self) -> None:
+        with self._lock:
+            self.connection.commit()
+
+    def clear(self) -> None:
+        with self._lock:
+            self.connection.execute("DELETE FROM files")
+            self.connection.execute("DELETE FROM dependencies")
+            self.connection.commit()
+
+    def close(self) -> None:
+        with self._lock:
+            self.connection.close()