cseq 0.0.1__py3-none-any.whl

cseq/linker.py

@@ -0,0 +1,117 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+from pathlib import Path
+import re
+
+from .model import CallTargetKind, LinkerEvidenceRecord, ProjectIndex
+
+_SECTION_RE = re.compile(r"^\s*(\.[^\s]+)\s+0x([0-9A-Fa-f]+)\s+(?:0x[0-9A-Fa-f]+|\d+)\s+(\S+\.o(?:\([^)]*\))?)\s*$")
+_SYMBOL_RE = re.compile(r"^\s*0x([0-9A-Fa-f]+)\s+([A-Za-z_.$][A-Za-z0-9_.$@]*)\s*$")
+_COMPACT_RE = re.compile(r"^\s*0x([0-9A-Fa-f]+)\s+([A-Za-z_.$][A-Za-z0-9_.$@]*)\s+(\S+\.o(?:\([^)]*\))?)\s*$")
+
+
+@dataclass(frozen=True, slots=True)
+class LinkedSymbol:
+    name: str
+    address: int
+    object_file: str | None = None
+    section: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class LinkerMapIndex:
+    path: str
+    symbols: tuple[LinkedSymbol, ...]
+
+    def named(self, name: str) -> tuple[LinkedSymbol, ...]:
+        return tuple(s for s in self.symbols if s.name == name)
+
+
+def parse_linker_map(path: str | Path) -> LinkerMapIndex:
+    """Parse a conservative GNU ld/lld-like map subset.
+
+    Unrecognized rows are ignored; no inference is made from them. The parser
+    supports section/object rows followed by symbol rows, plus a compact
+    ``0xADDR symbol object.o`` form useful for vendor adapters/tests.
+    """
+    p = Path(path)
+    current_object: str | None = None
+    current_section: str | None = None
+    symbols: list[LinkedSymbol] = []
+    for raw in p.read_text(encoding="utf-8", errors="replace").splitlines():
+        m = _SECTION_RE.match(raw)
+        if m:
+            current_section = m.group(1)
+            current_object = m.group(3)
+            continue
+        m = _COMPACT_RE.match(raw)
+        if m:
+            symbols.append(LinkedSymbol(m.group(2), int(m.group(1), 16), m.group(3), current_section))
+            continue
+        m = _SYMBOL_RE.match(raw)
+        if m:
+            symbols.append(LinkedSymbol(m.group(2), int(m.group(1), 16), current_object, current_section))
+    return LinkerMapIndex(str(p), tuple(symbols))
+
+
+def apply_linker_map(index: ProjectIndex, linker: LinkerMapIndex) -> list[LinkerEvidenceRecord]:
+    """Add build-specific linker evidence and narrow duplicate direct targets.
+
+    A duplicate source definition is narrowed only when an object-file basename
+    from the linker map uniquely matches one source-file basename. Address/name
+    evidence without an object mapping is retained but never used to guess.
+    """
+    functions = list(index.functions())
+    by_name: dict[str, list] = {}
+    for fn in functions:
+        by_name.setdefault(fn.name, []).append(fn)
+
+    evidence: list[LinkerEvidenceRecord] = []
+    object_matches: dict[str, set[str]] = {}
+    for symbol in linker.symbols:
+        candidates = [f for f in by_name.get(symbol.name, []) if f.storage_class != "static"]
+        matched: list[str] = []
+        if symbol.object_file:
+            obj_stem = _object_stem(symbol.object_file)
+            matched = [f.qualified_id for f in candidates if Path(f.source_path).stem == obj_stem]
+        record = LinkerEvidenceRecord(
+            symbol_name=symbol.name,
+            address=symbol.address,
+            object_file=symbol.object_file,
+            section=symbol.section,
+            matched_function_ids=tuple(sorted(matched)),
+            provenance=f"linker-map:{linker.path}",
+        )
+        evidence.append(record)
+        if len(matched) == 1:
+            object_matches.setdefault(symbol.name, set()).add(matched[0])
+
+    refined = []
+    for call in index.callsites:
+        if call.target_kind != CallTargetKind.INTERNAL_POSSIBLE or not call.callee_name:
+            refined.append(call)
+            continue
+        linked = object_matches.get(call.callee_name, set())
+        candidates = set(call.target_function_ids)
+        narrowed = sorted(linked & candidates)
+        if len(narrowed) == 1:
+            refined.append(replace(
+                call,
+                target_kind=CallTargetKind.INTERNAL_EXACT,
+                target_function_id=narrowed[0],
+                target_function_ids=(narrowed[0],),
+                unknown_possible=False,
+            ))
+        else:
+            refined.append(call)
+    index.callsites[:] = refined
+    index.linker_evidence.extend(evidence)
+    return evidence
+
+
+def _object_stem(value: str) -> str:
+    # Archive members such as libx.a(foo.o) are reduced to the member object.
+    m = re.search(r"\(([^()]+\.o)\)$", value)
+    leaf = m.group(1) if m else Path(value).name
+    return Path(leaf).stem

cseq/marker.py

@@ -0,0 +1,294 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, asdict
+from enum import Enum
+from hashlib import sha256
+import json
+from pathlib import Path
+import re
+from typing import Iterable
+
+
+MARKER_PREFIX = "[[CSEQ:"
+HUMAN_MARKER = "[[CSEQ]]"
+
+
+class MarkerState(str, Enum):
+    SUGGESTED = "SUGGESTED"
+    APPLIED = "APPLIED"
+    OBSERVED = "OBSERVED"
+    STALE = "STALE"
+    ORPHANED = "ORPHANED"
+    REMOVED = "REMOVED"
+
+
+@dataclass(frozen=True, slots=True)
+class CStringLiteral:
+    start: int
+    end: int  # exclusive byte offset
+    token: bytes
+    content: bytes
+
+
+@dataclass(frozen=True, slots=True)
+class MarkerRecord:
+    marker_id: str
+    source_path: str
+    byte_start: int
+    byte_end: int
+    original_literal: str
+    modified_literal: str
+    stable_fingerprint: str
+    state: MarkerState = MarkerState.APPLIED
+
+
+@dataclass(frozen=True, slots=True)
+class RewriteManifest:
+    source_path: str
+    before_hash: str
+    after_hash: str
+    marker: MarkerRecord
+    before_bytes_hex: str
+    after_bytes_hex: str
+
+    def to_json(self) -> str:
+        data = asdict(self)
+        data["marker"]["state"] = self.marker.state.value
+        return json.dumps(data, ensure_ascii=False, indent=2, sort_keys=True)
+
+    @classmethod
+    def from_json(cls, text: str) -> "RewriteManifest":
+        data = json.loads(text)
+        marker_data = dict(data["marker"])
+        marker_data["state"] = MarkerState(marker_data["state"])
+        return cls(
+            source_path=data["source_path"],
+            before_hash=data["before_hash"],
+            after_hash=data["after_hash"],
+            marker=MarkerRecord(**marker_data),
+            before_bytes_hex=data["before_bytes_hex"],
+            after_bytes_hex=data["after_bytes_hex"],
+        )
+
+
+def file_hash(data: bytes) -> str:
+    return sha256(data).hexdigest()
+
+
+def scan_c_string_literals(data: bytes) -> list[CStringLiteral]:
+    """Return ordinary/prefixed C string literal byte ranges.
+
+    The scanner deliberately works on bytes so source encoding, newlines and BOM
+    can be preserved exactly by rewrite operations. Comments and character
+    literals are skipped so quote-like bytes inside them are not rewritten.
+    """
+    out: list[CStringLiteral] = []
+    i = 0
+    n = len(data)
+    while i < n:
+        if data.startswith(b"//", i):
+            nl = data.find(b"\n", i + 2)
+            i = n if nl < 0 else nl + 1
+            continue
+        if data.startswith(b"/*", i):
+            close = data.find(b"*/", i + 2)
+            i = n if close < 0 else close + 2
+            continue
+        if data[i:i+1] == b"'":
+            i = _skip_quoted(data, i, ord("'"))
+            continue
+
+        prefix_len = _string_prefix_len(data, i)
+        quote = i + prefix_len
+        if quote < n and data[quote:quote+1] == b'"':
+            end = _skip_quoted(data, quote, ord('"'))
+            token_end = end
+            token = data[i:token_end]
+            # content excludes prefix and quotes; malformed unterminated literals
+            # are kept as scanned but never selected for rewrite.
+            if token_end <= n and token.endswith(b'"'):
+                content = data[quote + 1:token_end - 1]
+                out.append(CStringLiteral(i, token_end, token, content))
+            i = max(token_end, i + 1)
+            continue
+        i += 1
+    return out
+
+
+def apply_marker(
+    path: str | Path,
+    *,
+    literal_contains: str,
+    occurrence: int = 0,
+    expected_hash: str | None = None,
+    project_root: str | Path | None = None,
+    marker_id: str | None = None,
+    manifest_path: str | Path | None = None,
+) -> RewriteManifest:
+    p = Path(path)
+    before = p.read_bytes()
+    before_hash = file_hash(before)
+    if expected_hash is not None and before_hash != expected_hash:
+        raise RuntimeError("source hash mismatch; refusing marker rewrite")
+
+    needle = literal_contains.encode("utf-8")
+    candidates = [lit for lit in scan_c_string_literals(before) if needle in lit.content]
+    if occurrence < 0 or occurrence >= len(candidates):
+        raise ValueError(f"matching string literal occurrence not found: {occurrence}")
+    lit = candidates[occurrence]
+
+    if HUMAN_MARKER.encode() in lit.content or b"[[CSEQ:" in lit.content:
+        raise ValueError("selected string literal already contains a CSEQ marker")
+
+    rel = _relative_name(p, project_root)
+    fingerprint = _fingerprint(rel, before, lit)
+    marker_id = marker_id or fingerprint[:12].upper()
+    marker_text = f"[[CSEQ:{marker_id}]] ".encode("ascii")
+
+    # Insert after the opening quote, preserving prefix (u8/L/u/U) exactly.
+    quote_rel = lit.token.find(b'"')
+    insert_at = lit.start + quote_rel + 1
+    after = before[:insert_at] + marker_text + before[insert_at:]
+    p.write_bytes(after)
+    after_hash = file_hash(after)
+
+    modified_token = lit.token[:quote_rel+1] + marker_text + lit.token[quote_rel+1:]
+    record = MarkerRecord(
+        marker_id=marker_id,
+        source_path=rel,
+        byte_start=lit.start,
+        byte_end=lit.end + len(marker_text),
+        original_literal=lit.token.decode("utf-8", errors="replace"),
+        modified_literal=modified_token.decode("utf-8", errors="replace"),
+        stable_fingerprint=fingerprint,
+        state=MarkerState.APPLIED,
+    )
+    manifest = RewriteManifest(
+        source_path=rel,
+        before_hash=before_hash,
+        after_hash=after_hash,
+        marker=record,
+        before_bytes_hex=before.hex(),
+        after_bytes_hex=after.hex(),
+    )
+    if manifest_path is not None:
+        mp = Path(manifest_path)
+        mp.parent.mkdir(parents=True, exist_ok=True)
+        mp.write_text(manifest.to_json(), encoding="utf-8")
+    return manifest
+
+
+def apply_marker_overlay(
+    source_path: str | Path,
+    output_path: str | Path,
+    *,
+    literal_contains: str,
+    occurrence: int = 0,
+    expected_hash: str | None = None,
+    project_root: str | Path | None = None,
+    marker_id: str | None = None,
+    manifest_path: str | Path | None = None,
+) -> RewriteManifest:
+    """Create a marker-injected overlay without modifying the original source."""
+    source = Path(source_path)
+    output = Path(output_path)
+    original = source.read_bytes()
+    original_hash = file_hash(original)
+    if expected_hash is not None and original_hash != expected_hash:
+        raise RuntimeError("source hash mismatch; refusing marker overlay")
+    if source.resolve() == output.resolve():
+        raise ValueError("overlay output must differ from source path")
+    output.parent.mkdir(parents=True, exist_ok=True)
+    output.write_bytes(original)
+    try:
+        return apply_marker(
+            output,
+            literal_contains=literal_contains,
+            occurrence=occurrence,
+            expected_hash=original_hash,
+            project_root=project_root,
+            marker_id=marker_id,
+            manifest_path=manifest_path,
+        )
+    except Exception:
+        # Never leave a partially prepared overlay when marker application fails.
+        try:
+            output.unlink(missing_ok=True)
+        finally:
+            raise
+
+
+def undo_marker(
+    path: str | Path,
+    manifest: RewriteManifest | str | Path,
+) -> None:
+    p = Path(path)
+    if isinstance(manifest, (str, Path)):
+        manifest = RewriteManifest.from_json(Path(manifest).read_text(encoding="utf-8"))
+    current = p.read_bytes()
+    if file_hash(current) != manifest.after_hash:
+        raise RuntimeError("source changed after marker application; refusing unsafe undo")
+    after_expected = bytes.fromhex(manifest.after_bytes_hex)
+    if current != after_expected:
+        raise RuntimeError("manifest after-image mismatch; refusing unsafe undo")
+    before = bytes.fromhex(manifest.before_bytes_hex)
+    if file_hash(before) != manifest.before_hash:
+        raise RuntimeError("manifest before-image hash mismatch")
+    p.write_bytes(before)
+
+
+def audit_markers(paths: Iterable[str | Path]) -> dict[str, list[str]]:
+    """Return duplicate/malformed marker IDs without mutating source."""
+    by_id: dict[str, list[str]] = {}
+    malformed: list[str] = []
+    rx = re.compile(rb"\[\[CSEQ:([^\]]*)\]\]")
+    for path in paths:
+        p = Path(path)
+        data = p.read_bytes()
+        for m in rx.finditer(data):
+            marker_id = m.group(1).decode("ascii", errors="replace")
+            where = f"{p}:{m.start()}"
+            if not marker_id or not re.fullmatch(r"[A-Za-z0-9_-]+", marker_id):
+                malformed.append(where)
+            by_id.setdefault(marker_id, []).append(where)
+    duplicates = [f"{mid}:" + ",".join(locs) for mid, locs in sorted(by_id.items()) if mid and len(locs) > 1]
+    return {"duplicates": duplicates, "malformed": malformed}
+
+
+def _relative_name(path: Path, project_root: str | Path | None) -> str:
+    if project_root is None:
+        return path.name
+    try:
+        return path.resolve().relative_to(Path(project_root).resolve()).as_posix()
+    except ValueError:
+        return path.name
+
+
+def _fingerprint(rel: str, data: bytes, lit: CStringLiteral) -> str:
+    normalized = re.sub(rb"\[\[CSEQ(?::[^\]]+)?\]\]\s*", b"", lit.content)
+    left = data[max(0, lit.start - 80):lit.start]
+    right = data[lit.end:min(len(data), lit.end + 80)]
+    payload = b"\0".join([rel.encode("utf-8"), normalized, left, right])
+    return sha256(payload).hexdigest()
+
+
+def _string_prefix_len(data: bytes, i: int) -> int:
+    # C11/C23-style prefixes commonly encountered in C source.
+    for prefix in (b'u8', b'u', b'U', b'L'):
+        if data.startswith(prefix + b'"', i):
+            return len(prefix)
+    return 0
+
+
+def _skip_quoted(data: bytes, quote_pos: int, quote: int) -> int:
+    i = quote_pos + 1
+    n = len(data)
+    while i < n:
+        c = data[i]
+        if c == ord('\\'):
+            i += 2
+            continue
+        if c == quote:
+            return i + 1
+        i += 1
+    return n