cseq 0.0.1__tar.gz

cseq-0.0.1/PKG-INFO

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: cseq
+Version: 0.0.1
+Summary: C source sequence analysis tool PoC
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Provides-Extra: parser-tree-sitter
+Requires-Dist: tree-sitter==0.26.0; extra == "parser-tree-sitter"
+Requires-Dist: tree-sitter-c==0.24.2; extra == "parser-tree-sitter"
+
+# cseq
+
+Cソースツリーから関数呼出し・分岐・コールバック・実行時markerを解析し、PlantUMLとインタラクティブHTMLを生成するシーケンス解析ツールです。
+
+初回リリースは **Windows + Python 3.11以上** を主対象とします。Tree-sitterを高速な構文フロントエンドとして使用し、型・macro・関数ポインタ等で意味解析が必要な翻訳単位だけClangへ送ります。
+
+## 主な機能
+
+- ディレクトリ以下の `.c` / `.h` を再帰走査
+- entry関数からのシーケンス生成
+- 同名`static`関数を区別
+- 外部未定義関数を内部calleeとして誤認しない
+- `#if/#ifdef`、macro、compiler extensionのfail-soft解析
+- 関数ポインタ、callback、dispatch tableの候補解決
+- if/else、loop、無限loop、switch/case/defaultをSequence IRへ保持
+- RTOS風の無限loopを有限表現
+- CPU group / build configurationを外部設定可能
+- runtime markerログの読込み、CPU/task evidence、静的経路との照合
+- marker自動注入: source直接書換え / Overlay（原本非変更）の両方式
+- PlantUML出力
+- HTML UI: 検索、viewport、LOD、Canvas表示、path query、trace diff、marker suggestion
+- 大きいruntime trace向けbundle/range出力
+- optional linker map / binary symbol / DWARF evidence
+
+## Windowsでの導入
+
+PowerShell例です。
+
+```powershell
+py -3.12 -m venv .venv
+.\.venv\Scripts\Activate.ps1
+python -m pip install --upgrade pip
+pip install "cseq[parser-tree-sitter]"
+```
+
+ローカルwheelから導入する場合:
+
+```powershell
+pip install .\cseq-0.0.1-py3-none-any.whl[parser-tree-sitter]
+```
+
+### Clang
+
+単純なC構文だけならTree-sitterで解析できますが、macro、関数ポインタ、型曖昧性、compiler extension等のselective semantic refinementにはClangを推奨します。
+
+```powershell
+winget install --id LLVM.LLVM --exact
+```
+
+確認:
+
+```powershell
+cseq doctor
+```
+
+`current_execution_mode` が `tree-sitter+clang` なら両backendを利用できます。
+
+## 最短利用例
+
+```powershell
+cseq analyze C:\path\to\project --entry main --json
+cseq plantuml C:\path\to\project --entry main --output sequence.puml
+cseq html C:\path\to\project --entry main --output sequence.html --mode auto
+```
+
+HTMLは小規模時はportable単一HTML、中規模以上ではbundle/rangeへ切替できます。
+
+```powershell
+cseq serve . --port 8000
+```
+
+range/bundleをブラウザで確認する際はローカルHTTP配信を推奨します。
+
+## プロジェクト設定
+
+```powershell
+cseq config init C:\path\to\project
+cseq config validate C:\path\to\project\cseq.toml
+```
+
+`cseq.toml`でentry、compile database、CPU group、build configuration等をプロジェクト固有名に合わせて設定します。cseq本体は特定企業・CPU名称を前提にしません。
+
+`compile_commands.json` がある場合はClang semantic解析の精度向上に利用できます。
+
+## Runtime marker
+
+### 直接書換え
+
+```powershell
+cseq marker apply .\src\worker.c --contains "rx=%d" --id RX01 --manifest .\rx01.json
+```
+
+manifestにbefore/after hashを保存し、安全条件が成立するときだけundoできます。
+
+```powershell
+cseq marker undo .\src\worker.c --manifest .\rx01.json
+```
+
+### Overlay（原本非変更）
+
+```powershell
+cseq marker apply .\src\worker.c `
+  --contains "rx=%d" `
+  --id RX01 `
+  --manifest .\rx01-overlay.json `
+  --overlay-output .\cseq-overlay\worker.c
+```
+
+元sourceは変更されず、marker注入済みコピーだけを生成します。
+
+## Runtime log
+
+marker形式:
+
+```text
+[[CSEQ:RX01]] message...
+```
+
+ログ形式は固定ではなくpatternで指定できます。
+
+```powershell
+cseq trace import run.log `
+  --pattern "[{cpu}] {time} {message}" `
+  --time-format "%H:%M:%S.%f" `
+  --json
+```
+
+CPU間で時刻が隣接しているだけでは因果関係とはみなしません。marker、payload、静的path等のevidenceを分離して扱います。
+
+## HTML UI
+
+```powershell
+cseq html C:\path\to\project `
+  --entry main `
+  --runtime-log run.log `
+  --runtime-pattern "[{cpu}] {time} {message}" `
+  --runtime-time-format "%H:%M:%S.%f" `
+  --output sequence.html `
+  --mode auto
+```
+
+UIは大量eventを全DOM化せず、viewport/LOD/Canvas/range bundleを使います。初回リリースでは深い性能チューニングより、汎用性・正しさ・必要UIを優先します。
+
+## 設計上の原則
+
+- Silent Dropしない。解析不能領域はPARTIAL/OPAQUE等で明示する。
+- static possible と runtime observed を混同しない。
+- CPUのstatic/build/runtime evidenceを分離する。
+- cross-CPU timestamp adjacencyだけで因果を断定しない。
+- Tree-sitterとClangは代替関係ではなく、Fast Syntax + Selective Semantic Refinementとして併用する。
+
+## 開発時検証
+
+```powershell
+python -m pytest -q
+```
+
+Windows実機で全テスト、Tree-sitter/Clang統合acceptance、clean wheel installを確認してからrelease候補を作成します。
+
+## 同梱ドキュメントの出力
+
+インストール済みwheelから、README・設計書（清書版）・実装/検証成績書を1コマンドで取り出せます。
+
+```powershell
+cseq docs readme --output README.md
+cseq docs design --output シーケンス解析_設計書.md
+cseq docs report --output 実装・検証成績書.html
+cseq docs all --output-dir .\cseq-docs
+```
+
+`--output`を省略するとREADME/設計書/成績書の内容を標準出力します。`docs all` は3点を一括で出力します。

cseq-0.0.1/README.md

@@ -0,0 +1,171 @@
+# cseq
+
+Cソースツリーから関数呼出し・分岐・コールバック・実行時markerを解析し、PlantUMLとインタラクティブHTMLを生成するシーケンス解析ツールです。
+
+初回リリースは **Windows + Python 3.11以上** を主対象とします。Tree-sitterを高速な構文フロントエンドとして使用し、型・macro・関数ポインタ等で意味解析が必要な翻訳単位だけClangへ送ります。
+
+## 主な機能
+
+- ディレクトリ以下の `.c` / `.h` を再帰走査
+- entry関数からのシーケンス生成
+- 同名`static`関数を区別
+- 外部未定義関数を内部calleeとして誤認しない
+- `#if/#ifdef`、macro、compiler extensionのfail-soft解析
+- 関数ポインタ、callback、dispatch tableの候補解決
+- if/else、loop、無限loop、switch/case/defaultをSequence IRへ保持
+- RTOS風の無限loopを有限表現
+- CPU group / build configurationを外部設定可能
+- runtime markerログの読込み、CPU/task evidence、静的経路との照合
+- marker自動注入: source直接書換え / Overlay（原本非変更）の両方式
+- PlantUML出力
+- HTML UI: 検索、viewport、LOD、Canvas表示、path query、trace diff、marker suggestion
+- 大きいruntime trace向けbundle/range出力
+- optional linker map / binary symbol / DWARF evidence
+
+## Windowsでの導入
+
+PowerShell例です。
+
+```powershell
+py -3.12 -m venv .venv
+.\.venv\Scripts\Activate.ps1
+python -m pip install --upgrade pip
+pip install "cseq[parser-tree-sitter]"
+```
+
+ローカルwheelから導入する場合:
+
+```powershell
+pip install .\cseq-0.0.1-py3-none-any.whl[parser-tree-sitter]
+```
+
+### Clang
+
+単純なC構文だけならTree-sitterで解析できますが、macro、関数ポインタ、型曖昧性、compiler extension等のselective semantic refinementにはClangを推奨します。
+
+```powershell
+winget install --id LLVM.LLVM --exact
+```
+
+確認:
+
+```powershell
+cseq doctor
+```
+
+`current_execution_mode` が `tree-sitter+clang` なら両backendを利用できます。
+
+## 最短利用例
+
+```powershell
+cseq analyze C:\path\to\project --entry main --json
+cseq plantuml C:\path\to\project --entry main --output sequence.puml
+cseq html C:\path\to\project --entry main --output sequence.html --mode auto
+```
+
+HTMLは小規模時はportable単一HTML、中規模以上ではbundle/rangeへ切替できます。
+
+```powershell
+cseq serve . --port 8000
+```
+
+range/bundleをブラウザで確認する際はローカルHTTP配信を推奨します。
+
+## プロジェクト設定
+
+```powershell
+cseq config init C:\path\to\project
+cseq config validate C:\path\to\project\cseq.toml
+```
+
+`cseq.toml`でentry、compile database、CPU group、build configuration等をプロジェクト固有名に合わせて設定します。cseq本体は特定企業・CPU名称を前提にしません。
+
+`compile_commands.json` がある場合はClang semantic解析の精度向上に利用できます。
+
+## Runtime marker
+
+### 直接書換え
+
+```powershell
+cseq marker apply .\src\worker.c --contains "rx=%d" --id RX01 --manifest .\rx01.json
+```
+
+manifestにbefore/after hashを保存し、安全条件が成立するときだけundoできます。
+
+```powershell
+cseq marker undo .\src\worker.c --manifest .\rx01.json
+```
+
+### Overlay（原本非変更）
+
+```powershell
+cseq marker apply .\src\worker.c `
+  --contains "rx=%d" `
+  --id RX01 `
+  --manifest .\rx01-overlay.json `
+  --overlay-output .\cseq-overlay\worker.c
+```
+
+元sourceは変更されず、marker注入済みコピーだけを生成します。
+
+## Runtime log
+
+marker形式:
+
+```text
+[[CSEQ:RX01]] message...
+```
+
+ログ形式は固定ではなくpatternで指定できます。
+
+```powershell
+cseq trace import run.log `
+  --pattern "[{cpu}] {time} {message}" `
+  --time-format "%H:%M:%S.%f" `
+  --json
+```
+
+CPU間で時刻が隣接しているだけでは因果関係とはみなしません。marker、payload、静的path等のevidenceを分離して扱います。
+
+## HTML UI
+
+```powershell
+cseq html C:\path\to\project `
+  --entry main `
+  --runtime-log run.log `
+  --runtime-pattern "[{cpu}] {time} {message}" `
+  --runtime-time-format "%H:%M:%S.%f" `
+  --output sequence.html `
+  --mode auto
+```
+
+UIは大量eventを全DOM化せず、viewport/LOD/Canvas/range bundleを使います。初回リリースでは深い性能チューニングより、汎用性・正しさ・必要UIを優先します。
+
+## 設計上の原則
+
+- Silent Dropしない。解析不能領域はPARTIAL/OPAQUE等で明示する。
+- static possible と runtime observed を混同しない。
+- CPUのstatic/build/runtime evidenceを分離する。
+- cross-CPU timestamp adjacencyだけで因果を断定しない。
+- Tree-sitterとClangは代替関係ではなく、Fast Syntax + Selective Semantic Refinementとして併用する。
+
+## 開発時検証
+
+```powershell
+python -m pytest -q
+```
+
+Windows実機で全テスト、Tree-sitter/Clang統合acceptance、clean wheel installを確認してからrelease候補を作成します。
+
+## 同梱ドキュメントの出力
+
+インストール済みwheelから、README・設計書（清書版）・実装/検証成績書を1コマンドで取り出せます。
+
+```powershell
+cseq docs readme --output README.md
+cseq docs design --output シーケンス解析_設計書.md
+cseq docs report --output 実装・検証成績書.html
+cseq docs all --output-dir .\cseq-docs
+```
+
+`--output`を省略するとREADME/設計書/成績書の内容を標準出力します。`docs all` は3点を一括で出力します。

cseq-0.0.1/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "cseq"
+version = "0.0.1"
+description = "C source sequence analysis tool PoC"
+readme = "README.md"
+requires-python = ">=3.11"
+
+[project.optional-dependencies]
+parser-tree-sitter = ["tree-sitter==0.26.0", "tree-sitter-c==0.24.2"]
+
+[project.scripts]
+cseq = "cseq.cli:main"
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]
+
+[tool.setuptools.package-data]
+cseq = ["parser_dependency_lock.json", "parser_contract_cases.json", "resources/*.md", "resources/*.html"]

cseq-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

cseq-0.0.1/src/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-0.0.1/src/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))