Add documentation, plugins, and test suite

Initial commit introducing MkDocs documentation, plugin implementations, test suite, CLI, and engine modules. Includes developer and user guides, API reference, test reference, example plugins, and configuration files for CI and documentation deployment. Removes obsolete LLM output file and updates core modules and tests to support new features.

Author: EdgeTypE

.github/workflows/gh-pages.yml

@@ -0,0 +1,25 @@
+name: Deploy MkDocs to GitHub Pages
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.10"
+      - name: Install deps
+        run: pip install mkdocs mkdocs-material
+      - name: Build site
+        run: mkdocs build --site-dir site
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: site

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 PatternLab Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

debug_bmr.py

@@ -0,0 +1,33 @@
+from patternlab.plugin_api import BytesView
+from patternlab.plugins.binary_matrix_rank import BinaryMatrixRankTest
+
+def inspect_rows(m=8, num_matrices=1):
+    bits_per_matrix = m * m
+    total_bytes = (bits_per_matrix * num_matrices) // 8
+    pattern = (b'\xAA\x55') * (total_bytes // 2)
+    bv = BytesView(pattern)
+    bits = bv.bit_view()
+    # Build rows for first matrix
+    mat_bits = bits[0:bits_per_matrix]
+    rows = []
+    for r in range(m):
+        row_bits = mat_bits[r*m:(r+1)*m]
+        val = 0
+        for bit in row_bits:
+            val = (val << 1) | (1 if bit else 0)
+        rows.append((row_bits, val))
+    return rows, bv, pattern
+
+def main():
+    m = 8
+    rows, bv, pattern = inspect_rows(m=m, num_matrices=1)
+    print("First matrix rows (bits, int, bin):")
+    for i, (rb, val) in enumerate(rows):
+        print(f"row {i}: bits={rb} int={val} bin={format(val, '08b')}")
+    # Run full plugin to show ranks
+    res = BinaryMatrixRankTest().run(BytesView(pattern * 8), {"matrix_dim": m, "min_matrices": 8})
+    print("\nFull plugin result p_value:", res.p_value)
+    print("ranks:", res.metrics.get("ranks"))
+
+if __name__ == '__main__':
+    main()

debug_engine.py

@@ -0,0 +1,19 @@
+from patternlab.engine import Engine
+from patternlab.plugin_api import TestPlugin, TestResult
+
+class ObsTest(TestPlugin):
+    def describe(self): return "Observ"
+    def run(self, data, params):
+        _ = data.to_bytes()
+        return TestResult(test_name="obs_test", passed=True, p_value=None)
+
+e = Engine()
+e.register_test("obs_test", ObsTest())
+out = e.analyze(b"\x00\x01\x02", {"tests":[{"name":"obs_test","params":{}}]})
+print("analyze returned:", repr(out))
+import inspect, patternlab.engine
+src = inspect.getsource(patternlab.engine)
+print("\n--- source slice 1000..1320 ---")
+for i, line in enumerate(src.splitlines(), start=1):
+    if 1000 <= i <= 1320:
+        print(f"{i:4d} | {line}")

docs/api-reference.md

@@ -0,0 +1,46 @@
+# API Reference
+
+Bu sayfa PatternLab paketinin programatik API'sinin kısa bir özetini sağlar. Daha geniş referans için kaynak koduna bakın: [`patternlab/engine.py`](patternlab/engine.py:1), [`patternlab/plugin_api.py`](patternlab/plugin_api.py:1), [`patternlab/cli.py`](patternlab/cli.py:1).
+
+Önemli sınıflar ve fonksiyonlar
+- Engine
+  - Ana analiz akışını yöneten sınıf. Kullanım: `Engine().analyze(data_bytes, config)`.
+  - Kaydetme: `engine.register_test(name, plugin_instance)` ve `engine.register_transform(...)`.
+  - Kaynak: [`patternlab/engine.py`](patternlab/engine.py:1)
+- TestPlugin, TransformPlugin, VisualPlugin
+  - Eklenti taban sınıfları. Yeni eklenti yazarken genişletin.
+  - Ayrıntılar: [`patternlab/plugin_api.py`](patternlab/plugin_api.py:1)
+- BytesView
+  - Veri görünümü yardımcı sınıfı (bit_view, slice, vb.).
+  - Kullanım: test eklentileri run metodunda `data: BytesView`.
+- TestResult
+  - Test sonucu taşıyıcısı. Alanlar: test_name, passed, p_value, metrics, z_score, p_values, effect_sizes, flags, fdr_rejected, fdr_q.
+  - Serialize: `serialize_testresult(result)` (bakınız `patternlab/plugin_api.py`).
+
+Hızlı Örnek — Python
+```python
+from patternlab.engine import Engine
+from patternlab.plugins.monobit import MonobitTest
+
+engine = Engine()
+engine.register_test("monobit", MonobitTest())
+
+with open("test.bin","rb") as f:
+    data = f.read()
+
+config = {"tests":[{"name":"monobit","params":{"alpha":0.01}}]}
+output = engine.analyze(data, config)
+print(output["scorecard"])
+```
+
+CLI ile entegrasyon
+- CLI entrypoint: [`patternlab/cli.py`](patternlab/cli.py:1)
+- Örnek: `patternlab analyze input.bin -c docs/configs/example.yml -o report.json`
+
+Dokümantasyon otomatik türetme
+- Eğer ayrıntılı API referansı istenirse, `mkdocstrings` + `pytkdocs` ile otomatik döküm oluşturulabilir. Bunun için `mkdocs.yml` içinde `mkdocstrings` eklentisi ve `requirements-docs.txt` eklenmesi gerekir.
+
+Kaynak dosyaları
+- Engine: [`patternlab/engine.py`](patternlab/engine.py:1)
+- Plugin API: [`patternlab/plugin_api.py`](patternlab/plugin_api.py:1)
+- CLI: [`patternlab/cli.py`](patternlab/cli.py:1)

docs/getting-started.md

@@ -0,0 +1,49 @@
+# Getting Started
+
+Bu sayfa projeyi hızlıca kurup çalıştırmak için gerekli adımları içerir.
+
+Önkoşullar
+- Python 3.10+ kurulu olmalı
+- Depolama kökü: proje dizini (bkz. [`README.md`](README.md:1))
+
+Kurulum (geliştirme)
+```bash
+# sanal ortam
+python -m venv .venv
+.venv/Scripts/activate
+
+# proje bağımlılıkları (geliştirme)
+pip install -e .[dev]
+pip install mkdocs mkdocs-material
+```
+
+Hızlı CLI örneği
+```bash
+# örnek yapılandırma: [`docs/configs/example.yml`](docs/configs/example.yml:1)
+patternlab analyze test.bin -c docs/configs/example.yml -o report.json
+```
+
+Programatik kullanım
+```python
+from patternlab.engine import Engine
+engine = Engine()
+with open("test.bin","rb") as f:
+    data = f.read()
+
+config = {
+  "transforms": [{"name":"xor_const","params":{"xor_value":55}}],
+  "tests": [{"name":"monobit","params":{"alpha":0.01}}]
+}
+out = engine.analyze(data, config)
+print(out["scorecard"])
+```
+
+Yerel dokümantasyon geliştirme
+```bash
+# MkDocs geliştirme sunucusu (canlı yeniden yükleme)
+mkdocs serve
+# yayın (GitHub Pages)
+mkdocs gh-deploy
+```
+
+Daha fazla örnek konfigürasyon için bkz. [`docs/configs/example.yml`](docs/configs/example.yml:1) ve [`docs/configs/example.json`](docs/configs/example.json:1).

docs/index.md

@@ -0,0 +1,38 @@
+# PatternLab Dokümantasyonu
+
+Bu site PatternLab projesi için kapsamlı kullanım, geliştirici rehberi ve test referansı sağlar.
+
+Hızlı erişim:
+- [`Getting Started`](docs/getting-started.md:1)
+- [`User Guide`](docs/user-guide.md:1)
+- [`Plugin Developer Guide`](docs/plugin-developer-guide.md:1)
+- [`API Reference`](docs/api-reference.md:1)
+- [`Test Reference`](docs/test-reference.md:1)
+- Konfig örnekleri: [`docs/configs/example.yml`](docs/configs/example.yml:1) ve [`docs/configs/example.json`](docs/configs/example.json:1)
+
+Yerel olarak siteyi çalıştırma
+```bash
+# Gerekli paketleri kurun (tercihen virtualenv içinde)
+pip install mkdocs mkdocs-material
+
+# Geliştirme sunucusu
+mkdocs serve
+```
+
+GitHub Pages'e hızlı yayım
+```bash
+# ilk kez deploy için repo ayarlarını kontrol edin
+mkdocs gh-deploy
+```
+
+Read the Docs ile yayınlama
+- Projeyi Read the Docs'da etkinleştirin.
+- Gerekirse `requirements-docs.txt` veya `docs/requirements.txt` dosyası ekleyin.
+- (Opsiyonel) RTD yapılandırması için `readthedocs.yml` eklenebilir.
+
+Mevcut Markdown içerik kaynakları
+- Eklenti rehberi: [`docs/plugin-developer-guide.md`](docs/plugin-developer-guide.md:1)
+- Test referansı: [`docs/test-reference.md`](docs/test-reference.md:1)
+- Konfig örnekleri: [`docs/configs/README.md`](docs/configs/README.md:1)
+
+Bu sayfa, MkDocs yapılandırması olan [`mkdocs.yml`](mkdocs.yml:1) dosyası ile eşleşir. Bir sonraki adım olarak "Getting Started" ve "User Guide" sayfalarını zenginleştireceğim.

docs/plugin-developer-guide.md

@@ -96,4 +96,64 @@ Ek referans
 - Engine: [`patternlab/engine.py`](patternlab/engine.py:1)
 - CLI: [`patternlab/cli.py`](patternlab/cli.py:1)
 
-Bu kılavuz, hızlı bir başlangıç sağlar. İleri seviye konu veya örnek isterseniz ayrı bir doküman eklenebilir.
+Bu kılavuz, hızlı bir başlangıç sağlar. İleri seviye konu veya örnek isterseniz ayrı bir doküman eklenebilir.
+
+## Örnek: Tam Bir Test Eklentisi
+
+Aşağıda proje içinde doğrudan kullanılabilecek minimal, test edilebilir bir TestPlugin örneği bulunmaktadır. Bu dosyayı [`patternlab/plugins/my_test.py`](patternlab/plugins/my_test.py:1) olarak ekleyebilirsiniz.
+
+```python
+# python
+from patternlab.plugin_api import TestPlugin, BytesView, TestResult
+
+class MyThresholdTest(TestPlugin):
+    """Basit eşik tabanlı monobit benzeri test örneği."""
+
+    requires = ["bits"]
+
+    def describe(self) -> str:
+        return "my_threshold_test"
+
+    def run(self, data: BytesView, params: dict) -> TestResult:
+        bits = data.bit_view()
+        ones = sum(bits)
+        n = len(bits)
+        threshold = float(params.get("threshold", 0.5))
+        passed = True if n == 0 else (ones / n) > threshold
+        metrics = {"ones": ones, "total_bits": n, "threshold": threshold}
+        return TestResult(test_name=self.describe(), passed=passed, p_value=None, metrics=metrics)
+```
+
+## Örnek Unit Test
+
+Eklentinizi doğrulamak için pytest ile basit bir test yazın. Aşağıdaki örnek dosyayı [`tests/test_my_threshold.py`](tests/test_my_threshold.py:1) olarak oluşturabilirsiniz.
+
+```python
+# python
+from patternlab.plugins.my_test import MyThresholdTest
+from patternlab.plugin_api import BytesView
+
+def test_my_threshold_pass():
+    plugin = MyThresholdTest()
+    # örnek bit dizisi: 6 bit, 5 tane 1 -> oran 0.833
+    data = BytesView(b'\xf8')  # 11111000 (örnek)
+    result = plugin.run(data, {"threshold": 0.7})
+    assert result.passed is True
+    assert result.metrics["ones"] >= 5
+
+def test_my_threshold_fail():
+    plugin = MyThresholdTest()
+    data = BytesView(b'\x0f')  # 00001111 (oran 0.5)
+    result = plugin.run(data, {"threshold": 0.6})
+    assert result.passed is False
+```
+
+## Test ve CI Entegrasyonu
+
+- Yeni eklentiyi ekledikten sonra `pytest` ile testleri çalıştırın.
+- Eklentinin bağımlılıkları varsa bunları `pyproject.toml` veya `docs/requirements.txt` içine ekleyin.
+- Otomatik test çalıştırma için GitHub Actions iş akışlarına test adımı ekleyin (ör: `pytest` çağrısı).
+
+Ek referansler:
+- Eklenti API detayları: [`patternlab/plugin_api.py`](patternlab/plugin_api.py:1)
+- Mevcut eklenti örnekleri: [`patternlab/plugins/monobit.py`](patternlab/plugins/monobit.py:1)

docs/requirements.txt

@@ -0,0 +1,3 @@
+mkdocs
+mkdocs-material
+mkdocstrings[pytkdocs]