Add artefact serving endpoint and UI enhancements

Introduces a /artefact FastAPI endpoint to securely serve local artefact files for development. Updates the static UI to proxy local artefact and report paths through the new endpoint, improving accessibility of generated reports and artefacts. Adds plugin descriptions in Turkish as a JSON template, enhances the report template with a modal for plugin details, and refines scorecard display. Updates test coverage for visual error handling. Registers new plugins in pyproject.toml.

Author: EdgeTypE

patternlab/api.py

@@ -8,7 +8,7 @@
 """
 from fastapi import FastAPI, UploadFile, File, BackgroundTasks, HTTPException, Body
 from fastapi.staticfiles import StaticFiles
-from fastapi.responses import RedirectResponse
+from fastapi.responses import RedirectResponse, FileResponse
 from fastapi.middleware.cors import CORSMiddleware
 from pydantic import BaseModel
 from typing import Optional, Dict, Any
@@ -96,6 +96,22 @@ async def report(job_id: str):
         return {"job_id": job_id, "status": entry["status"]}
     return {"job_id": job_id, "status": "error", "error": entry.get("error")}
 
+@app.get("/artefact", include_in_schema=False)
+async def artefact(path: str):
+    """
+    Serve an artefact file by absolute path (development helper).
+    Security: only allows files inside the current workspace directory to be served.
+    Usage: /artefact?path=/absolute/path/to/file.png
+    """
+    # Resolve and restrict to workspace root for safety
+    file_path = os.path.abspath(path)
+    workspace_root = os.path.abspath(os.getcwd())
+    if not file_path.startswith(workspace_root):
+        raise HTTPException(status_code=403, detail="forbidden: path outside workspace")
+    if not os.path.exists(file_path) or not os.path.isfile(file_path):
+        raise HTTPException(status_code=404, detail="not_found")
+    return FileResponse(file_path)
+
 @app.get("/health")
 async def health():
     return {"status": "ok"}

patternlab/static_ui/index.html

@@ -153,25 +153,39 @@ <h2 style="margin-top:18px">Sonuç</h2>
         setStatus('Tamamlandı', false);
         const report = j.report || {};
         resultPre.textContent = JSON.stringify(report, null, 2);
-        // If engine included html_report path in top-level, show iframe
+        // If engine included html_report path in top-level, show iframe.
+        // If the path looks like a local file (not an HTTP(S) URL), route it through
+        // the API helper endpoint /artefact so browsers can fetch it via the server.
         if (report && report.html_report){
           const iframe = document.createElement('iframe');
-          iframe.src = report.html_report;
+          let src = report.html_report;
+          // Treat as URL if it begins with http(s)://
+          if (!/^https?:\/\//i.test(src)) {
+            // Otherwise encode and route through artefact endpoint
+            src = '/artefact?path=' + encodeURIComponent(src);
+          }
+          iframe.src = src;
           iframe.style.width = '100%';
           iframe.style.height = '500px';
           artefactsEl.appendChild(iframe);
         }
-        // If artefacts listed as array `artefacts` with URLs, show images/links
+        // If artefacts listed as array `artefacts` with URLs/paths, show images/links.
+        // Non-HTTP paths will be proxied through /artefact?path=...
         if (report && report.artefacts && Array.isArray(report.artefacts)){
           report.artefacts.forEach(a=>{
             const aEl = document.createElement('div');
+            // Normalize path: if it's not an http(s) URL, proxy via /artefact
+            let href = a;
+            if (!/^https?:\/\//i.test(href)) {
+              href = '/artefact?path=' + encodeURIComponent(href);
+            }
             if (/\.(png|jpg|jpeg|svg)$/i.test(a)){
               const img = document.createElement('img');
-              img.src = a;
+              img.src = href;
               aEl.appendChild(img);
             } else {
               const link = document.createElement('a');
-              link.href = a;
+              link.href = href;
               link.textContent = a;
               link.target = '_blank';
               aEl.appendChild(link);

pyproject.toml

@@ -46,10 +46,12 @@ autocorrelation = "patternlab.plugins.autocorrelation:AutocorrelationTest"
 binary_matrix_rank = "patternlab.plugins.binary_matrix_rank:BinaryMatrixRankTest"
 block_frequency = "patternlab.plugins.block_frequency_test:BlockFrequencyTest"
 cusum = "patternlab.plugins.cusum:CumulativeSumsTest"
+dotplot = "patternlab.plugins.dotplot:DotplotPlugin"
 fft_placeholder = "patternlab.plugins.fft_placeholder:FFTPlaceholder"
 fft_spectral = "patternlab.plugins.fft_spectral:FFTSpectralTest"
 linear_complexity = "patternlab.plugins.linear_complexity:LinearComplexityTest"
 longest_run = "patternlab.plugins.longest_run:LongestRunOnesTest"
+lz_complexity = "patternlab.plugins.lz_complexity:LZComplexityPlugin"
 maurers_universal = "patternlab.plugins.maurers_universal:MaurersUniversalTest"
 monobit = "patternlab.plugins.monobit:MonobitTest"
 nist_dft_spectral = "patternlab.plugins.nist_dft_spectral:NISTDFTSpectralTest"

templates/descriptions.json

@@ -0,0 +1,104 @@
+{
+  "monobit": {
+    "title": "Monobit (Frequency) Test",
+    "short": "Bitlerin 0/1 dengesini kontrol eder.",
+    "long": "Test, bit dizisindeki 0 ve 1 sayıları arasındaki oransal dengeyi değerlendirir. Aşırı sapma rasgele olmayanlığı gösterir.",
+    "remediation": "Düşük p-değerleri tekrar eden bit kalıpları veya sabit bit akışı gösterir; veri kaynağını veya ön işleme (örneğin sıkıştırma) kontrol edin."
+  },
+  "runs": {
+    "title": "Runs Test",
+    "short": "Bitler arasındaki ardışık aynı değer (run) dağılımını kontrol eder.",
+    "long": "Test, art arda gelen 0 veya 1 kümelerinin sayısını ve uzunluklarını değerlendirir; beklenenden fazla veya az run rasgeleliği bozar.",
+    "remediation": "Sık tekrar eden alt diziler veya kalıp üretimi varsa, verinin kaynağını veya üretim sürecini inceleyin."
+  },
+  "block_frequency": {
+    "title": "Block Frequency Test",
+    "short": "Büyük bloklarda bit frekansını ölçer.",
+    "long": "Veriyi sabit uzunluklu bloklara ayırır ve her blokta 0/1 oranını değerlendirir; blok içi tutarsızlıklar rasgelelik göstergesidir.",
+    "remediation": "Özellikle yapılandırılmış veri formatlarında (header/payload) blok boyutunu ayarlayın veya transform uygulayın."
+  },
+  "cusum": {
+    "title": "Cumulative Sum (CUSUM) Test",
+    "short": "Bit dizisinin kümülatif toplama sapmalarını inceler.",
+    "long": "CUSUM, pozitif ve negatif sapmaların kümülatif etkisini ölçer; büyük sapan eğilimler rasgele olmayanlığı işaret eder.",
+    "remediation": "Trend oluşturan kaynakları ve sürekli bias'ı araştırın; ön işleme ile düzeltilip düzeltilmeyeceğini test edin."
+  },
+  "serial": {
+    "title": "Serial (Overlapping) Test",
+    "short": "N-gram (bit sıraları) frekanslarını karşılaştırır.",
+    "long": "Seri test, n-bit alt dizilerin beklenen frekanslarını değerlendirir; örtüşen n-gram'ler arasındaki anormallikler ortaya çıkar.",
+    "remediation": "Tekrarlayan motifleri, sıkıştırılmış veya kodlu dizileri kontrol edin; transform zinciri ile test edin."
+  },
+  "approximate_entropy": {
+    "title": "Approximate Entropy",
+    "short": "Verinin düzensizliğini entropi temelli ölçer.",
+    "long": "Yaklaşık entropi, verideki tekrar eden paternlere duyarlıdır; düşük değerler deterministik yapıyı işaret edebilir.",
+    "remediation": "Tekrar eden yapıların kaynağını araştırın veya farklı pencere boyutlarıyla yeniden değerlendir."
+  },
+  "maurers_universal": {
+    "title": "Maurer's Universal Statistical Test",
+    "short": "Sıkıştırılabilirlik üzerinden rastgeleliği değerlendirir.",
+    "long": "Bu test, verinin ideal sıkıştırma oranına göre değerlendirilir; kolay sıkıştırılabilen veri rastgele değildir.",
+    "remediation": "Verinin sıkıştırılabilirliğini kontrol edin; tek tip tekrarlar varsa veri kaynağını gözden geçirin."
+  },
+  "non_overlapping_template": {
+    "title": "Non-overlapping Template Matching",
+    "short": "Belirli şablonların varlığını sayar (çakışma yok).",
+    "long": "Önceden tanımlı sabit uzunluklu şablonların tekrarını sayar; aşırı tekrar şüphelidir.",
+    "remediation": "Şablon setini ve eşik değerlerini gözden geçirin; pre-transform uygulamayı deneyin."
+  },
+  "overlapping_template": {
+    "title": "Overlapping Template Matching",
+    "short": "Belirli şablonların tekrarını çakışma olsa bile sayar.",
+    "long": "Örtüşen şablon örüntülerini sayarak lokal tekrarlılıkları tespit eder.",
+    "remediation": "Verideki sık tekrar eden motifleri inceleyin; gerekirse windowing uygulayın."
+  },
+  "random_excursions": {
+    "title": "Random Excursions",
+    "short": "Saçılma (excursion) ziyaretlerinin dağılımını inceler.",
+    "long": "Random walk temelli bu test, durumların ziyaret sıklıklarını değerlendirir; beklenmeyen dağılımlar düzensizlik göstergesi olabilir.",
+    "remediation": "Uzun aralıklı bağımlılıkları kontrol edin; daha fazla örnekleme ile test edin."
+  },
+  "random_excursions_variant": {
+    "title": "Random Excursions Variant",
+    "short": "Çeşitlendirilmiş excursion sayım metrikleri sunar.",
+    "long": "Variant, farklı durumların ziyaret istatistiklerini ölçerek daha hassas saptamalar yapar.",
+    "remediation": "Anormal değerler görüldüğünde verinin segmentlerini analiz edin."
+  },
+  "nist_dft_spectral": {
+    "title": "NIST DFT Spectral Test",
+    "short": "Dizinin frekans alanındaki anormalliklerini arar.",
+    "long": "Diskret Fourier Transform (DFT) kullanarak tepe (peak) frekansları tespit eder; belirgin spektral tepe rasgele olmayan düzenleri gösterir.",
+    "remediation": "Periyodiklik üreten kaynakları (tekrar eden bloklar, sensor sampling) kontrol edin."
+  },
+  "fft_spectral": {
+    "title": "FFT Spectral (Large-Scale)",
+    "short": "Büyük veriler için spektral test ve downsample koruması.",
+    "long": "FFT tabanlı test, NAIVE_DFT_BIT_LIMIT eşiği üzerinden otomatik örnekleme yapar; yüksek bellek kullanımını engeller.",
+    "remediation": "Eşikleri ve downsample ayarlarını doğrulayın; veri segmentasyonu deneyin."
+  },
+  "linear_complexity": {
+    "title": "Linear Complexity Test",
+    "short": "Verinin LFSR tabanlı karmaşıklığını ölçer.",
+    "long": "Lineer karmaşıklık, diziyi üretebilecek en kısa LFSR uzunluğunu değerlendirir; düşük karmaşıklık deterministik yapıya işaret eder.",
+    "remediation": "Tekrarlayan yapı veya kısa periyotlu kaynakları inceleyin."
+  },
+  "lz_complexity": {
+    "title": "LZ-Complexity",
+    "short": "Lempel-Ziv sıkıştırma temelli karmaşıklık metriği.",
+    "long": "Verinin LZ77/LZ78 tabanlı ayrıştırılabilirliğini ölçer; düşük değerler yüksek tekrarlılık gösterir.",
+    "remediation": "Sık tekrar eden alt dizileri ve protokol başlıklarını kontrol edin."
+  },
+  "dotplot": {
+    "title": "Dotplot (Self-Similarity)",
+    "short": "Verinin kendi içinde tekrar eden bölümlerini görselleştirir.",
+    "long": "Pencerelere bölünmüş veri arasındaki benzerlik matrisi, kopyalanmış veya tekrarlayan blokları gösteren bir ısı haritası üretir.",
+    "remediation": "Tekrarlayan segmentleri ayıklayın veya segment bazlı analiz uygulayın; artefaktları raporlayın."
+  },
+  "binary_matrix_rank": {
+    "title": "Binary Matrix Rank Test",
+    "short": "Bit matrislerinin rank dağılımını test eder.",
+    "long": "Veriden oluşturulan ikili matrislerin rank'leri beklenen dağılımdan saparsa rasgelelik sorgulanır.",
+    "remediation": "Matris boyutlandırmasını ve veri segmentasyonunu kontrol edin."
+  }
+}

templates/report_template.html

@@ -57,13 +57,30 @@ <h5 class="mb-2">Meta</h5>
       <div class="col-12 col-lg-6">
         <div class="card p-3 h-100">
           <h5>Scorecard</h5>
-          <div class="row">
-            {% for k, v in scorecard.items() %}
-            <div class="col-6 col-sm-4 mb-2">
-              <div class="text-muted small">{{ k }}</div>
-              <div class="score-metric">{{ v | tojson }}</div>
+          <div class="d-flex align-items-center flex-wrap">
+            <div class="me-4 text-center">
+              <div class="text-muted small">Failed tests</div>
+              <div class="score-metric" style="color:#d9534f">{{ scorecard.get("failed_tests", 0) }}</div>
+            </div>
+            <div class="me-4 text-center">
+              <div class="text-muted small">Total tests</div>
+              <div class="score-metric">{{ scorecard.get("total_tests", 0) }}</div>
+            </div>
+            <div class="me-4 text-center">
+              <div class="text-muted small">Mean effect size</div>
+              <div class="score-metric">{{ scorecard.get("mean_effect_size") | default("n/a") }}</div>
+            </div>
+            <div class="me-4 text-center">
+              <div class="text-muted small">FDR q</div>
+              <div class="score-metric">{{ scorecard.get("fdr_q") }}</div>
+            </div>
+          </div>
+          <hr/>
+          <div>
+            <small class="text-muted">P-value distribution</small>
+            <div class="mt-2">
+              <canvas id="pvalMini" height="60"></canvas>
             </div>
-            {% endfor %}
           </div>
         </div>
       </div>
@@ -181,6 +198,21 @@ <h6 class="mt-2">Visuals</h6>
 
   </div>
 
+  <!-- Plugin description modal -->
+  <div class="modal fade" id="pluginDescModal" tabindex="-1" aria-labelledby="pluginDescModalLabel" aria-hidden="true">
+    <div class="modal-dialog modal-lg modal-dialog-centered">
+      <div class="modal-content">
+        <div class="modal-header">
+          <h5 class="modal-title" id="pluginDescModalLabel">Plugin description</h5>
+          <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
+        </div>
+        <div class="modal-body">
+          <!-- populated dynamically -->
+        </div>
+      </div>
+    </div>
+  </div>
+
   <!-- Scripts -->
   <script src="https://code.jquery.com/jquery-3.7.1.min.js" integrity="sha256-3gJwYp2k6u9c2Y5nYq3X8bK5jv1Yj2Kp2t9Qjv6v+8w=" crossorigin="anonymous"></script>
   <script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.2/dist/js/bootstrap.bundle.min.js" integrity="sha384-abc" crossorigin="anonymous"></script>
@@ -223,6 +255,20 @@ <h6 class="mt-2">Visuals</h6>
                             '</div>';
             // Use Bootstrap Popover (hover + focus to support keyboard)
             new bootstrap.Popover(btn, { title: d.title || key, content: content, html: true, trigger: 'hover focus', placement: 'auto' });
+            // Add click handler to open modal with full description for accessibility/long text
+            btn.addEventListener('click', function(ev){
+              try {
+                const modal = document.getElementById('pluginDescModal');
+                const titleEl = modal.querySelector('.modal-title');
+                const bodyEl = modal.querySelector('.modal-body');
+                titleEl.textContent = d.title || key;
+                bodyEl.innerHTML = '<p>' + (d.short ? d.short : '') + '</p>' + (d.remediation ? '<p><strong>Remediation:</strong> ' + d.remediation + '</p>' : '') + '<pre class="json" style="margin-top:8px">' + JSON.stringify(d, null, 2) + '</pre>';
+                const bsModal = new bootstrap.Modal(modal);
+                bsModal.show();
+              } catch (e) {
+                console.warn('plugin-help modal show failed', e);
+              }
+            });
           } catch (e) {
             // per-button errors should not break initialization
             console.warn('plugin-help init failed for', btn, e);

tests/test_engine.py

@@ -50,11 +50,22 @@ def test_visual_error_reported_in_visual_errors_and_does_not_fail_test():
     engine.register_test("goodtest", GoodTest())
     engine.register_visual("badvisual", BadVisual())
 
-def test_visual_error_sets_result_status_error():
-    """Test that visual errors set result status to error when motor has new behavior."""
-    engine = Engine()
-    engine.register_test("goodtest", GoodTest())
-    engine.register_visual("badvisual", BadVisual())
+    out = engine.analyze(
+        b"\x00\x01\x02",
+        {
+            "tests": [{"name": "goodtest", "params": {}}],
+        },
+    )
+
+    assert out["results"], "Expected at least one result"
+    r = out["results"][0]
+
+    # Engine should keep the test completed while reporting visual errors separately.
+    assert r.get("status") == "completed"
+    # The serialized result must include the visual_errors entry for the failing visual plugin.
+    assert "visual_errors" in r and any(v.get("visual_name") == "badvisual" for v in r.get("visual_errors"))
+    # GoodTest returns passed=True with p_value=None in the TestResult above.
+    assert r.get("passed") is True