cseq 0.0.1__py3-none-any.whl

cseq/__init__.py

@@ -0,0 +1,9 @@
+"""cseq: C source sequence analysis tool."""
+
+__version__ = "0.0.1"
+
+from .api import Analysis, Explanation, MarkerSuggestion, QueryResult, RuntimeSession, analyze
+
+__all__ = [
+    "Analysis", "Explanation", "MarkerSuggestion", "QueryResult", "RuntimeSession", "analyze", "__version__"
+]

cseq/acceptance.py

@@ -0,0 +1,162 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from pathlib import Path
+import shutil
+
+from .explain import explain_call
+from .html import build_html_payload
+from .marker import apply_marker, apply_marker_overlay, undo_marker
+from .model import CallTargetKind
+from .project import Project
+from .runtime import RuntimePattern, build_trace_session
+from .sequence import build_sequence, render_plantuml
+from .trace_analysis import ReconstructionState, reconstruct_static_paths
+
+
+@dataclass(frozen=True, slots=True)
+class AcceptanceCriterion:
+    criterion_id: str
+    name: str
+    status: str
+    evidence: str
+    detail: str = ""
+
+
+@dataclass(frozen=True, slots=True)
+class AcceptanceReport:
+    criteria: tuple[AcceptanceCriterion, ...]
+
+    @property
+    def functional_pass(self) -> bool:
+        return all(c.status == "PASS" for c in self.criteria if c.status != "DEFERRED_TO_LATER_GATE")
+
+    def to_dict(self) -> dict:
+        return {
+            "functional_pass": self.functional_pass,
+            "criteria": [asdict(c) for c in self.criteria],
+        }
+
+
+def run_poc_functional_acceptance(fixtures_root: str | Path, work_root: str | Path) -> AcceptanceReport:
+    fixtures = Path(fixtures_root)
+    work = Path(work_root)
+    work.mkdir(parents=True, exist_ok=True)
+    criteria: list[AcceptanceCriterion] = []
+
+    # A/B: direct call + external separation.
+    basic = Project(fixtures / "basic", use_cache=False).index()
+    calls = {(c.caller_name, c.callee_name): c for c in basic.callsites}
+    direct_ok = (
+        calls[("main", "helper")].target_kind == CallTargetKind.INTERNAL_EXACT
+        and calls[("main", "printf")].target_kind == CallTargetKind.EXTERNAL_DECLARED
+    )
+    criteria.append(AcceptanceCriterion(
+        "POC-01", "Direct Call基本精度とExternal分離",
+        "PASS" if direct_ok else "FAIL", "fixtures/basic",
+    ))
+
+    # C/D/E: indirect target explanation.
+    fptr = Project(fixtures / "fptr_local", use_cache=False).index()
+    explanation = explain_call(fptr, caller="run")
+    indirect_calls = [c for c in explanation.get("calls", []) if c.get("resolution", "").startswith("INDIRECT")]
+    indirect_ok = bool(indirect_calls) and all(c.get("targets") for c in indirect_calls) and any(c.get("value_flow") for c in indirect_calls)
+    criteria.append(AcceptanceCriterion(
+        "POC-02", "Indirect Callbackを理由付きで説明可能",
+        "PASS" if indirect_ok else "FAIL", "fixtures/fptr_local + explain_call",
+    ))
+
+    # L/M: unknown syntax does not drop surrounding functions.
+    unknown = Project(fixtures / "unknown_compiler", use_cache=False).index()
+    names = {f.name for f in unknown.functions()}
+    opaque_count = sum(len(a.opaque_regions) for a in unknown.parse_artifacts)
+    unknown_ok = {"helper", "main"} <= names and opaque_count >= 1
+    criteria.append(AcceptanceCriterion(
+        "POC-03", "未知構文でも解析可能部分を保持",
+        "PASS" if unknown_ok else "FAIL", "fixtures/unknown_compiler",
+        f"functions={sorted(names)}, opaque_regions={opaque_count}",
+    ))
+
+    # H: finite representation of infinite loop.
+    rtos = Project(fixtures / "rtos_infinite", use_cache=False).index()
+    rtos_model = build_sequence(rtos, "main")
+    puml = render_plantuml(rtos_model)
+    rtos_ok = "loop [infinite]" in puml and puml.count("dispatch()") == 1
+    criteria.append(AcceptanceCriterion(
+        "POC-04", "RTOS無限loopを有限表示",
+        "PASS" if rtos_ok else "FAIL", "fixtures/rtos_infinite + PlantUML",
+    ))
+
+    # I: runtime observation + static reconstruction.
+    pattern = RuntimePattern("[{cpu}] {time} {message}", "%H:%M:%S.%f")
+    session = build_trace_session("acceptance", [fixtures / "runtime" / "a.log", fixtures / "runtime" / "b.log"], pattern=pattern)
+    recon_index = Project(fixtures / "reconstruction" / "unique", use_cache=False).index()
+    reconstruction = reconstruct_static_paths(recon_index, "a", "f")
+    runtime_ok = len(session.events) == 3 and reconstruction.state == ReconstructionState.EXACT_PATH
+    criteria.append(AcceptanceCriterion(
+        "POC-05", "Runtime Marker観測と静的経路復元",
+        "PASS" if runtime_ok else "FAIL", "fixtures/runtime + reconstruction/unique",
+    ))
+
+    # G/J: generic CPU rule without company-specific core naming.
+    cpu_root = fixtures / "cpu_rules"
+    cpu = Project(cpu_root, config=cpu_root / "cseq.toml", configuration="GROUP_A_BUILD", use_cache=False).index()
+    cpu_values = {e.value for e in cpu.cpu_evidence}
+    cpu_ok = "CPU_GROUP_A" in cpu_values and "CPU_A2" in cpu_values
+    criteria.append(AcceptanceCriterion(
+        "POC-06", "一般化CPU Ruleで割当可能",
+        "PASS" if cpu_ok else "FAIL", "fixtures/cpu_rules",
+    ))
+
+    # K: marker rewrite minimal and reversible.
+    marker_src = fixtures / "marker" / "main.c"
+    marker_dst = work / "marker_acceptance.c"
+    shutil.copyfile(marker_src, marker_dst)
+    before = marker_dst.read_bytes()
+    manifest = apply_marker(marker_dst, literal_contains="rx=%d", marker_id="ACCEPT01")
+    after = marker_dst.read_bytes()
+    marker_token = b"[[CSEQ:ACCEPT01]] "
+    minimal_ok = after.replace(marker_token, b"", 1) == before and after.count(marker_token) == 1
+    undo_marker(marker_dst, manifest)
+    marker_ok = minimal_ok and marker_dst.read_bytes() == before
+    criteria.append(AcceptanceCriterion(
+        "POC-07", "Marker直接編集が最小差分・可逆",
+        "PASS" if marker_ok else "FAIL", "fixtures/marker + apply/undo",
+    ))
+
+    # PlantUML and HTML consume the exact same SequenceModel instance.
+    basic_model = build_sequence(basic, "main")
+    html_payload = build_html_payload(basic_model)
+    puml2 = render_plantuml(basic_model)
+    shared_ir_ok = len(html_payload["messages"]) == len(basic_model.messages) and "@startuml" in puml2
+    criteria.append(AcceptanceCriterion(
+        "POC-08", "PlantUML / HTMLを同一Sequence IRから生成",
+        "PASS" if shared_ir_ok else "FAIL", "SequenceModel -> render_plantuml/build_html_payload",
+    ))
+
+    # K2: overlay marker mode leaves the original source untouched.
+    overlay_src = fixtures / "marker" / "main.c"
+    overlay_dst = work / "overlay" / "marker_acceptance.c"
+    overlay_before = overlay_src.read_bytes()
+    overlay_manifest = apply_marker_overlay(
+        overlay_src, overlay_dst, literal_contains="rx=%d", marker_id="OVERLAY01"
+    )
+    overlay_ok = (
+        overlay_src.read_bytes() == overlay_before
+        and b"[[CSEQ:OVERLAY01]] " in overlay_dst.read_bytes()
+    )
+    undo_marker(overlay_dst, overlay_manifest)
+    overlay_ok = overlay_ok and overlay_dst.read_bytes() == overlay_before
+    criteria.append(AcceptanceCriterion(
+        "POC-09", "Marker overlay mode preserves the original source",
+        "PASS" if overlay_ok else "FAIL", "apply_marker_overlay + undo",
+    ))
+
+    # Performance-dependent criterion is intentionally delegated to G5.
+    criteria.append(AcceptanceCriterion(
+        "POC-10", "1M Event級UIが構造的に破綻しない",
+        "DEFERRED_TO_LATER_GATE", "G5 Runtime/UI受入",
+        "Functional E2Eでは判定せず、固定済み性能Gateで正式受入する",
+    ))
+
+    return AcceptanceReport(tuple(criteria))

cseq/api.py

@@ -0,0 +1,328 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterable, Mapping
+
+from .explain import explain_call
+from .html import render_html
+from .model import ProjectIndex
+from .project import Project
+from .query import query_calls, query_paths, query_unresolved
+from .runtime import RuntimePattern, TraceSession as _TraceSession, build_trace_session
+from .runtime_cpu import apply_runtime_cpu_evidence
+from .runtime_address import discover_runtime_address_evidence
+from .sequence import SequenceModel, build_sequence, render_plantuml
+from .trace_analysis import ReconstructionState, reconstruct_static_paths, score_marker_suggestions, discover_correlations, fit_clock_alignments
+
+
+@dataclass(frozen=True, slots=True)
+class Explanation:
+    """Stable public explanation facade; internal Evidence/IR objects stay hidden."""
+    _data: Mapping[str, object]
+
+    @property
+    def found(self) -> bool:
+        return bool(self._data.get("found"))
+
+    def to_dict(self) -> dict[str, object]:
+        return dict(self._data)
+
+
+@dataclass(frozen=True, slots=True)
+class QueryResult:
+    kind: str
+    _data: Mapping[str, object]
+
+    def to_dict(self) -> dict[str, object]:
+        return dict(self._data)
+
+
+@dataclass(frozen=True, slots=True)
+class RuntimeSession:
+    """Read-only runtime-session facade for Python callers."""
+    _session: _TraceSession
+
+    @property
+    def name(self) -> str:
+        return self._session.name
+
+    @property
+    def event_count(self) -> int:
+        return len(self._session.events)
+
+    @property
+    def cpus(self) -> tuple[str, ...]:
+        return tuple(sorted({e.cpu_hint for e in self._session.events if e.cpu_hint}))
+
+    @property
+    def tasks(self) -> tuple[str, ...]:
+        return tuple(sorted({e.task_hint for e in self._session.events if e.task_hint}))
+
+    def rows(self) -> tuple[dict[str, object], ...]:
+        return tuple({
+            "event_index": e.event_index,
+            "marker_id": e.marker_id,
+            "timestamp": e.timestamp_raw,
+            "cpu": e.cpu_hint,
+            "task": e.task_hint,
+            "message": e.message,
+            "payload": e.payload_dict(),
+        } for e in self._session.events)
+
+    def correlations(self) -> tuple[dict[str, object], ...]:
+        return tuple({
+            "left_event_index": r.left_event_index,
+            "right_event_index": r.right_event_index,
+            "relation_type": r.relation_type.value,
+            "keys": r.keys,
+            "values": r.values,
+            "score": r.score,
+        } for r in discover_correlations(self._session.events))
+
+    def clock_alignments(self) -> tuple[dict[str, object], ...]:
+        relations = discover_correlations(self._session.events)
+        return tuple({
+            "source_domain": a.source_domain,
+            "target_domain": a.target_domain,
+            "scale": a.scale,
+            "offset_seconds": a.offset_seconds,
+            "anchor_count": a.anchor_count,
+            "max_abs_residual_seconds": a.max_abs_residual_seconds,
+            "confidence": a.confidence,
+        } for a in fit_clock_alignments(self._session.events, relations))
+
+
+@dataclass(frozen=True, slots=True)
+class MarkerSuggestion:
+    function_name: str
+    score: float
+    distinguished_path_pairs: int
+    total_path_pairs: int
+    reason: str
+
+
+@dataclass(slots=True)
+class Analysis:
+    """Stable public facade over the internal ProjectIndex/IR implementation."""
+    project: Project
+    index: ProjectIndex
+
+    @property
+    def cache_hits(self) -> int:
+        return self.project.cache_hits
+
+    @property
+    def cache_misses(self) -> int:
+        return self.project.cache_misses
+
+    @property
+    def analysis_cache_hits(self) -> int:
+        return self.project.analysis_cache_hits
+
+    @property
+    def analysis_cache_misses(self) -> int:
+        return self.project.analysis_cache_misses
+
+    @property
+    def plugin_evidence(self) -> tuple[dict[str, object], ...]:
+        return tuple({
+            "plugin": e.plugin_name,
+            "kind": e.kind.value,
+            "target": e.target,
+            "type": e.evidence_type,
+            "value": e.value,
+            "confidence": e.confidence,
+        } for e in self.project.plugin_result.evidence)
+
+    @property
+    def linker_evidence(self) -> tuple[dict[str, object], ...]:
+        return tuple({
+            "symbol": e.symbol_name, "address": e.address,
+            "object_file": e.object_file, "section": e.section,
+            "matched_function_ids": e.matched_function_ids,
+            "provenance": e.provenance,
+        } for e in self.index.linker_evidence)
+
+    @property
+    def binary_evidence(self) -> tuple[dict[str, object], ...]:
+        return tuple({
+            "symbol": e.symbol_name, "address": e.address, "size": e.size,
+            "kind": e.symbol_kind, "matched_function_ids": e.matched_function_ids,
+            "binary_hash": e.binary_hash, "provenance": e.provenance,
+        } for e in self.index.binary_evidence)
+
+    def resolve_binary_address(self, address: int, *, load_bias: int = 0) -> dict[str, object] | None:
+        image = self.project.binary_image
+        if image is None:
+            return None
+        sym = image.resolve_address(address, load_bias=load_bias)
+        if sym is None:
+            return None
+        return {"name": sym.name, "address": sym.address, "size": sym.size, "kind": sym.kind}
+
+    @property
+    def dwarf_evidence(self) -> tuple[dict[str, object], ...]:
+        return tuple({
+            "function_id": e.function_id, "source": e.source_path,
+            "line": e.line, "address": e.address, "dwarf_file": e.dwarf_file,
+            "provenance": e.provenance,
+        } for e in self.index.dwarf_evidence)
+
+    def resolve_source_address(self, address: int, *, load_bias: int = 0) -> dict[str, object] | None:
+        dwarf = self.project.dwarf_index
+        if dwarf is None:
+            return None
+        row = dwarf.resolve_address(address, load_bias=load_bias)
+        if row is None:
+            return None
+        return {"file": row.file, "line": row.line, "address": row.address}
+
+    @property
+    def plugin_diagnostics(self) -> tuple[dict[str, str], ...]:
+        return tuple({
+            "plugin": d.plugin_name,
+            "severity": d.severity,
+            "code": d.code,
+            "message": d.message,
+        } for d in self.project.plugin_result.diagnostics)
+
+    def sequence(self, entry: str = "main") -> SequenceModel:
+        return build_sequence(self.index, entry)
+
+    def plantuml(self, entry: str = "main") -> str:
+        return render_plantuml(self.sequence(entry))
+
+    def html(self, entry: str = "main", **kwargs) -> str:
+        return render_html(self.sequence(entry), **kwargs)
+
+    # Backward-compatible raw result methods.
+    def explain(self, caller: str, callee: str | None = None) -> dict[str, object]:
+        return explain_call(self.index, caller=caller, callee_text=callee)
+
+    def calls(self, function: str) -> dict[str, object]:
+        return query_calls(self.index, function)
+
+    def unresolved(self) -> dict[str, object]:
+        return query_unresolved(self.index)
+
+    def paths(self, start: str, end: str) -> dict[str, object]:
+        return query_paths(self.index, start, end)
+
+    # Stable typed facades.
+    def explanation(self, caller: str, callee: str | None = None) -> Explanation:
+        return Explanation(self.explain(caller, callee))
+
+    def query(self, kind: str, **kwargs) -> QueryResult:
+        if kind == "calls":
+            function = kwargs.get("function")
+            if not isinstance(function, str) or not function:
+                raise ValueError("query('calls') requires function=<name>")
+            payload = self.calls(function)
+        elif kind == "unresolved":
+            payload = self.unresolved()
+        elif kind == "paths":
+            start, end = kwargs.get("start"), kwargs.get("end")
+            if not isinstance(start, str) or not isinstance(end, str) or not start or not end:
+                raise ValueError("query('paths') requires start=<name>, end=<name>")
+            payload = self.paths(start, end)
+        else:
+            raise ValueError(f"unknown query kind: {kind}")
+        return QueryResult(kind, payload)
+
+    def runtime_session(
+        self,
+        paths: Iterable[str | Path],
+        *,
+        name: str = "default",
+        pattern: str | None = None,
+        time_format: str | None = None,
+    ) -> RuntimeSession:
+        runtime_pattern = RuntimePattern(pattern, time_format) if pattern else None
+        return RuntimeSession(build_trace_session(name, paths, pattern=runtime_pattern))
+
+    def observe_runtime(
+        self,
+        paths: Iterable[str | Path],
+        *,
+        name: str = "default",
+        pattern: str | None = None,
+        time_format: str | None = None,
+    ) -> RuntimeSession:
+        """Import a runtime session and add unambiguous observed CPU evidence.
+
+        StaticAffinity and BuildDomain evidence are preserved; observations are
+        appended as the independent OBSERVED_RUNTIME_DOMAIN layer.
+        """
+        runtime_pattern = RuntimePattern(pattern, time_format) if pattern else None
+        session = build_trace_session(name, paths, pattern=runtime_pattern)
+        apply_runtime_cpu_evidence(self.index, session)
+        return RuntimeSession(session)
+
+    def runtime_address_evidence(
+        self,
+        session: RuntimeSession,
+        *,
+        load_bias: int = 0,
+        trusted_keys: Iterable[str] = (),
+    ) -> tuple[dict[str, object], ...]:
+        image = self.project.binary_image
+        if image is None:
+            return ()
+        rows = discover_runtime_address_evidence(
+            session._session.events, image, dwarf=self.project.dwarf_index,
+            load_bias=load_bias, trusted_keys=trusted_keys,
+        )
+        return tuple({
+            "event_index": e.event_index, "marker_id": e.marker_id,
+            "key": e.payload_key, "value": e.payload_value,
+            "runtime_address": e.runtime_address, "linked_address": e.linked_address,
+            "symbol": e.symbol_name, "symbol_size": e.symbol_size,
+            "source_file": e.source_file, "source_line": e.source_line,
+            "confidence": e.confidence, "provenance": e.provenance,
+        } for e in rows)
+
+    def marker_suggestions(self, start: str, end: str, *, count: int = 5) -> tuple[MarkerSuggestion, ...]:
+        reconstruction = reconstruct_static_paths(self.index, start, end)
+        if reconstruction.state != ReconstructionState.AMBIGUOUS_PATH:
+            return ()
+        suggestions = score_marker_suggestions(reconstruction.paths, count=count)
+        return tuple(MarkerSuggestion(
+            s.function_name,
+            s.information_gain_score,
+            s.distinguished_path_pairs,
+            s.total_path_pairs,
+            s.reason,
+        ) for s in suggestions)
+
+
+def analyze(
+    path: str | Path,
+    *,
+    config: str | Path | None = None,
+    configuration: str | None = None,
+    defines: Iterable[str] = (),
+    compile_db: str | Path | None = None,
+    linker_map: str | Path | None = None,
+    binary: str | Path | None = None,
+    dwarf: str | Path | None = None,
+    use_cache: bool = True,
+    cache_dir: str | Path | None = None,
+    jobs: int = 1,
+    static_store: str | Path | None = None,
+) -> Analysis:
+    project = Project(
+        path,
+        config=config,
+        configuration=configuration,
+        defines=tuple(defines),
+        compile_db=compile_db,
+        linker_map=linker_map,
+        binary=binary,
+        dwarf=dwarf,
+        use_cache=use_cache,
+        cache_dir=cache_dir,
+        jobs=jobs,
+        static_store=static_store,
+    )
+    return Analysis(project=project, index=project.index())

cseq/binary.py

@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from hashlib import sha256
+from pathlib import Path
+import bisect
+import subprocess
+import shutil
+import os
+
+from .model import BinaryEvidenceRecord, ProjectIndex
+
+
+@dataclass(frozen=True, slots=True)
+class BinarySymbol:
+    name: str
+    address: int
+    size: int
+    kind: str
+
+
+@dataclass(frozen=True, slots=True)
+class BinaryImage:
+    path: str
+    content_hash: str
+    symbols: tuple[BinarySymbol, ...]
+
+    def resolve_address(self, runtime_address: int, *, load_bias: int = 0) -> BinarySymbol | None:
+        """Resolve a runtime PC/function-pointer address against linked symbols.
+
+        ``load_bias`` is subtracted explicitly for PIE/ASLR images. Zero-size
+        symbols are bounded by the next symbol address when possible.
+        """
+        address = int(runtime_address) - int(load_bias)
+        symbols = self.symbols
+        starts = [s.address for s in symbols]
+        pos = bisect.bisect_right(starts, address) - 1
+        if pos < 0:
+            return None
+        sym = symbols[pos]
+        if sym.size > 0:
+            return sym if sym.address <= address < sym.address + sym.size else None
+        next_start = symbols[pos + 1].address if pos + 1 < len(symbols) else None
+        if next_start is None:
+            return sym if address == sym.address else None
+        return sym if sym.address <= address < next_start else None
+
+
+def _existing_executable_path(path: str | Path) -> Path:
+    p = Path(path)
+    if p.exists():
+        return p
+    if os.name == "nt":
+        candidate = Path(str(p) + ".exe")
+        if candidate.exists():
+            return candidate
+    return p
+
+
+def load_binary_image(path: str | Path, *, nm: str = "nm") -> BinaryImage:
+    p = _existing_executable_path(path)
+    data = p.read_bytes()
+    nm_exe = shutil.which(nm) or (shutil.which("llvm-nm") if nm == "nm" else None) or nm
+    proc = subprocess.run(
+        [nm_exe, "-n", "-S", "--defined-only", str(p)],
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+        check=False,
+    )
+    if proc.returncode != 0:
+        raise RuntimeError(f"nm failed for {p}: {proc.stderr.strip()}")
+    symbols: list[BinarySymbol] = []
+    for line in proc.stdout.splitlines():
+        parts = line.split()
+        if len(parts) < 3:
+            continue
+        try:
+            address = int(parts[0], 16)
+            if len(parts) >= 4:
+                size = int(parts[1], 16)
+                kind = parts[2]
+                name = " ".join(parts[3:])
+            else:
+                # PE/COFF nm commonly omits symbol sizes even with -S.
+                # Keep zero-size symbols; resolve_address bounds them by the
+                # next symbol just as it already does for ELF zero-size rows.
+                size = 0
+                kind = parts[1]
+                name = " ".join(parts[2:])
+        except ValueError:
+            continue
+        # Text/weak text symbols are executable function candidates. Keep no
+        # object/data symbols in the function-address index.
+        if kind not in {"T", "t", "W", "w"}:
+            continue
+        symbols.append(BinarySymbol(name, address, size, kind))
+    symbols.sort(key=lambda x: (x.address, x.name))
+    return BinaryImage(str(p), sha256(data).hexdigest(), tuple(symbols))
+
+
+def apply_binary_evidence(index: ProjectIndex, image: BinaryImage) -> list[BinaryEvidenceRecord]:
+    by_name: dict[str, list] = {}
+    for fn in index.functions():
+        by_name.setdefault(fn.name, []).append(fn)
+    out: list[BinaryEvidenceRecord] = []
+    for sym in image.symbols:
+        matches = by_name.get(sym.name, [])
+        # A binary symbol alone does not identify which duplicate source
+        # definition supplied it. Bind only unique source-name matches.
+        ids = (matches[0].qualified_id,) if len(matches) == 1 else ()
+        out.append(BinaryEvidenceRecord(
+            symbol_name=sym.name,
+            address=sym.address,
+            size=sym.size,
+            symbol_kind=sym.kind,
+            matched_function_ids=ids,
+            binary_hash=image.content_hash,
+            provenance=f"binary:{image.path}",
+        ))
+    index.binary_evidence.extend(out)
+    return out