mjolnir-qa 0.4.0 → 0.5.2

package/README.gr.md

@@ -0,0 +1,705 @@
+<div align="center">
+
+<img src="assets/readme/logo.png" alt="Mjölnir — Verification Trust Engine" width="800" />
+
+### Τα τεστ σου λένε ψέματα. Το αποδεικνύουμε.
+
+**Verification Trust Engine για QA.** Το Mjölnir ελέγχει suites τεστ και
+CI pipelines, αναφέρει δείκτη αξιοπιστίας και δείχνει ακριβώς πού
+σπάει η εμπιστοσύνη.
+
+[![npm](https://img.shields.io/npm/v/mjolnir-qa.svg?style=flat-square&color=C9A227&labelColor=0B0F17)](https://www.npmjs.com/package/mjolnir-qa)
+[![ci](https://img.shields.io/github/actions/workflow/status/Sergey-Bar/Mjolnir/ci.yml?branch=main&style=flat-square&label=ci&labelColor=0B0F17)](https://github.com/Sergey-Bar/Mjolnir/actions/workflows/ci.yml)
+[![license](https://img.shields.io/badge/license-MIT-C9A227.svg?style=flat-square&labelColor=0B0F17)](LICENSE)
+[![node](https://img.shields.io/badge/node-%E2%89%A5%2022.18-2E8C7F.svg?style=flat-square&labelColor=0B0F17)](https://nodejs.org)
+
+[English](README.md) | [简体中文](README.zh.md) | [繁體中文](README.zht.md) | [한국어](README.ko.md) | [Deutsch](README.de.md) | [Español](README.es.md) | [Français](README.fr.md) | [Italiano](README.it.md) | [Dansk](README.da.md) | [日本語](README.ja.md) | [Polski](README.pl.md) | [Русский](README.ru.md) | [Norsk](README.no.md) | [Português (Brasil)](README.br.md) | [ไทย](README.th.md) | [Türkçe](README.tr.md) | [Українська](README.uk.md) | [বাংলা](README.bn.md) | Ελληνικά | [Tiếng Việt](README.vi.md) | [עברית](README.he.md) | [العربية](README.ar.md) | [Bosanski](README.bs.md)
+
+> 🤖 Machine-assisted translation. The [English README](README.md) is canonical. Last synced: 2026-09-04.
+
+```bash
+npx mjolnir-qa@latest
+```
+
+**Είναι τα τεστ σου άξια εμπιστοσύνης;**
+
+[Δες το σε δράση](#-δες-το-σε-δράση) ·
+[Γρήγορη εκκίνηση](#-γρήγορη-εκκίνηση) ·
+[Τι ελέγχει](#-τι-ελέγχει-το-mjölnir) ·
+[Σκόρ](#πώς-λειτουργεί-το-σκόρ) ·
+[CI](#-ενσωμάτωση-ci) · [Διαμόρφωση](#διαμόρφωση) ·
+[Τεκμηρίωση](#-τεκμηρίωση)
+
+</div>
+
+---
+
+## 🎬 Δες το σε δράση
+
+<p align="center">
+  <img src="assets/readme/demo.svg" alt="Η πλήρης αναφορά --verbose του Mjölnir σε ένα demo repo: WORTHINESS 75/100 NEEDS WORK, ανάλυση διαγνώσεων ανά κατηγορία, λίστα FIX THIS FIRST και κάθε εύρημα με ID κανόνα και αριθμό γραμμής σε CI, Playwright, υγιεινή τεστ και κανόνες Python" width="900" />
+</p>
+
+<sub>Η πλήρης έξοδος του `npx mjolnir-qa ./examples/demo-repo --verbose`,
+αποδομένη από τον πραγματικό reporter — τίποτα περικομμένο.
+Αναδημιουργείται με `npm run docs:demo`;
+[`tests/demo-asset-reproducibility.spec.ts`](tests/demo-asset-reproducibility.spec.ts)
+ρίχνει το CI αν ο artifact αποκλίνει από ό,τι τυπώνει το εργαλείο.</sub>
+
+**Τι μόλις συνέβη:**
+
+1. Το Mjölnir ανακάλυψε τα Playwright specs, τη διαμόρφωσή του, το CI
+   workflow και ένα αρχείο τεστ Python — τέσσερις γλώσσες/μορφές, ένα
+   πέρασμα.
+2. Βρήκε στοιχεία που εξασθενούν την εμπιστοσύνη στη σουίτα — ένα
+   `continue-on-error` που κρύβει job, ένα `|| true` που καταπίνει exit
+   code, σκληρά sleeps, εύθραυστο selector, σκληρά staging URL,
+   αναμονή `networkidle`.
+3. Μετέτρεψε το καθένα σε συγκεκριμένο εύρημα με ID κανόνα, τοποθεσία
+   και fix — και σε ένα σκόρ με το οποίο μπορείς να gated ένα PR.
+
+### Ένα εύρημα από κοντά
+
+Τρέξε `mjolnir explain QA-CI-001` στο πρώτο εύρημα παραπάνω και θα
+πάρεις:
+
+```text
+▚▞ QA-CI-001 — continue-on-error masks a failing verification gate
+
+Severity:    error
+Confidence:  high
+Evidence:    E2
+Measured FP: not yet measured — this rule ships on assumption (see docs/FP-AUDIT.md)
+
+WHAT WAS FOUND (real detector output, not a mockup)
+  Job `security-scan` runs a verification gate under `continue-on-error: true`.
+
+WHY IT MATTERS
+  This job can fail every day and CI will still show green. The checkmark
+  on this workflow cannot be trusted.
+
+HOW TO FIX
+  Remove continue-on-error, or scope it to individual non-blocking steps only.
+```
+
+Αυτή είναι η μονάδα αξίας: όχι νίττα στυλ, αλλά ένα σημείο όπου το CI
+σου σου λέει ότι κάτι πέρασε ενώ δεν πέρασε.
+
+---
+
+## ⚡ Γρήγορη εκκίνηση
+
+Τρέξ' το σε ένα repo για πλήρη αναφορά και δείκτη αξιοπιστίας:
+
+```bash
+npx mjolnir-qa@latest
+```
+
+**Στο CI το προϊόν είναι μία εντολή.** Σκανάρει μόνο ό,τι άγγιξε το
+branch και βγαίνει μη μηδενικά σε νέα προβλήματα:
+
+```bash
+npx mjolnir-qa@latest --scope changed
+```
+
+Ρίξε αυτό σε ένα PR check — το `mjolnir ci install` γράφει το workflow —
+και τελείωσες. Όλα τα άλλα είναι προαιρετικά.
+
+| Εντολή                              | Τι κάνει                                                     |
+| ----------------------------------- | ------------------------------------------------------------ |
+| `mjolnir`                           | Πλήρες σκαν repo + δείκτης αξιοπιστίας                       |
+| `mjolnir --scope changed`           | Μόνο ό,τι引入ε το branch σου — η μορφή CI                    |
+| `mjolnir ci install`                | Δημιουργεί το συμβουλευτικό PR workflow                      |
+| `mjolnir explain QA-CI-001`         | Τι / γιατί / fix + μετρημένο ποσοστό FP για έναν κανόνα      |
+| `mjolnir rules --unmeasured`        | Οι κανόνες που τρέχουν με υπόθεση, όχι με μέτρημα            |
+| `mjolnir --json` / `--format sarif` | Μηχανικά αναγνώσιμο / GitHub Code Scanning                   |
+| `mjolnir --strict`                  | Εκτελεί και κανόνες tier quarantine (υψηλότερος κίνδυνος FP) |
+
+<details>
+<summary><strong>Όταν κάτι είναι flaky</strong></summary>
+
+| Εντολή                              | Τι κάνει                                                        |
+| ----------------------------------- | --------------------------------------------------------------- |
+| `mjolnir forensics ./test-results/` | Πραγματικά δεδομένα runs → ετυμηγορίες `TRUE-FLAKE`, `FLAKY.md` |
+| `mjolnir triage ./test-results/`    | Πρόταση καραντίνας από ιστορικό εκτέλεσης                       |
+| `mjolnir pw-report ./test-results/` | Σύνοψη run Playwright — retries / flakes / τα πιο αργά          |
+| `mjolnir doctor:playwright`         | Βαθύ σκαν μόνο Playwright + Selector Health Score               |
+
+</details>
+
+<details>
+<summary><strong>Σπάνια / αναφορές</strong></summary>
+
+| Εντολή                          | Τι κάνει                                                |
+| ------------------------------- | ------------------------------------------------------- |
+| `mjolnir fix --dry-run` / `fix` | Ασφαλή αυτόματα fix με απόδειξη                         |
+| `mjolnir baseline` / `diff`     | Στιγμιότυπο ευρημάτων, μετά αναφορά μόνο νέων/χειρότερα |
+| `mjolnir impact --since <ref>`  | Τι άλλαξε από προηγούμενο commit                        |
+| `mjolnir debt`                  | Μητρώο τεχνολογικού χρέους τεστ με μοντέλο κόστους      |
+| `mjolnir handover`              | Χάρτης onboarding της σουίτας για νέο QA                |
+| `mjolnir stats`                 | Τοπικοί σωρευτικοί μετρητές όλων των fix που είδε       |
+| `mjolnir badge`                 | shields.io endpoint JSON + snippet                      |
+| `mjolnir rules --md`            | Πλήρης κατάλογος κανόνων (JSON ή Markdown)              |
+| `mjolnir doctor`                | Αυτοέλεγχος της ίδιας της βάσης κανόνων του Mjölnir     |
+| `mjolnir create-rule <ID>`      | Σκαφφάρει νέο κανόνα + fixtures                         |
+| `mjolnir --format mermaid`      | Διάγραμμα αρχιτεκτονικής τεστ για σχόλιο PR             |
+
+</details>
+
+Εγκατάσταση globally αντί για `npx` αν προτιμάς: `npm i -g mjolnir-qa`.
+Απαιτεί Node.js ≥ 22.18. Λειτουργεί σε Windows, macOS και Linux.
+
+---
+
+## 👥 Για ποιον είναι;
+
+- **QA / SDET** που έχουν e2e ή integration σουίτα και χρειάζονται
+  αποδείξεις ότι η σουίτα αξίζει πραγματικά το πράσινο τσεκ που
+  παράγει.
+- **Ομάδες Platform / DevEx** υπεύθυνες για ακεραιότητα CI και release
+  gates — οι άνθρωποι που νοιάζονται να μην μετατρέψει ποτέ ένα
+  `continue-on-error` βουβά κόκκινο pipeline σε πράσινο.
+- **Maintainers OSS** που θέλουν φτηνή, πάντα ενεργή πύλη επαλήθευσης
+  που τρέχει τοπικά και σε CI χωρίς κλήσεις δικτύου.
+
+---
+
+## 🔨 Τι ελέγχει το Mjölnir
+
+|     |                                                                                                                                      |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| ⚖️  | **Δείκτης αξιοπιστίας** — ένας αριθμός, διαφανής πίνακας αφαιρέσεων, καμία μαύρη κάψουλα                                             |
+| 🎭  | **Selector Health Score** — βαθμολογεί τα Playwright locators σου, όχι μόνο το pass rate                                             |
+| 🔬  | **Δικαστική ανάλυση runtime** — διαβάζει πραγματικά δεδομένα Playwright/JUnit για να πιάσει `TRUE-FLAKE`, όχι μόνο στατικές εικασίες |
+| 🚨  | **Κανόνες ακεραιότητας CI** — πιάνει `continue-on-error`, `\|\| true` και άλλα κόλπα ψεύτικου πράσινου                               |
+| 🐍  | **Και τα τέσσερα Playwright bindings** — TypeScript, Python, Java, C#/.NET — plus pytest, JUnit/TestNG και CI workflows              |
+| 🔒  | **Local-first** — μηδενικές κλήσεις δικτύου κατά το σκαν, μηδενική τηλεμετρία, τρέχει σε δευτερόλεπτα                                |
+
+### Οι κανόνες
+
+Κάθε κανόνας έρχεται με fixtures must-fire **και** must-not-fire.
+Κανόνας που ενεργοποιείται στη δική του αρνητική fixture δεν μπορεί να
+να κυκλοφορήσει — αυτός είναι ο τείχος των false positives.
+
+<details>
+<summary><strong>Υγιεινή τεστ</strong></summary>
+
+| ID          | Κανόνας                                               | Severity |
+| ----------- | ----------------------------------------------------- | -------- |
+| QA-TEST-001 | Commitμένος focused τεστ (`.only`, `fit`)             | error    |
+| QA-TEST-002 | Παραλειμένο τεστ χωρίς δικαιολογία                    | error    |
+| QA-TEST-002 | Παραλειμένο τεστ με καταγεγραμμένη δικαιολογία        | warning  |
+| QA-TEST-003 | Τεστ χωρίς assertions                                 | error    |
+| QA-TEST-004 | Σκληρό sleep (`waitForTimeout`, `sleep()`, `delay()`) | warning  |
+| QA-TEST-006 | Κατάχρηση retry που κρύβει flakiness                  | warning  |
+| QA-TEST-010 | Κενό σώμα τεστ                                        | error    |
+
+</details>
+
+<details>
+<summary><strong>Ποιότητα τεστ</strong></summary>
+
+| ID           | Κανόνας                       | Severity |
+| ------------ | ----------------------------- | -------- |
+| QA-TQUAL-001 | Επαλήθευση μόνο με mocks      | info     |
+| QA-TQUAL-002 | Ταυτολογική assertion         | error    |
+| QA-TQUAL-009 | Assertion promise χωρίς await | error    |
+| QA-TQUAL-011 | Σχολιασμένα τεστ              | warning  |
+
+</details>
+
+<details>
+<summary><strong>Playwright 🎭</strong></summary>
+
+| ID        | Κανόνας                                        | Severity |
+| --------- | ---------------------------------------------- | -------- |
+| QA-PW-002 | Assertion locator χωρίς await                  | error    |
+| QA-PW-003 | `page.pause()` / `test.only()` στο commit      | error    |
+| QA-PW-004 | Εύθραυστοι CSS/XPath selectors                 | warning  |
+| QA-PW-005 | Επιχειρησιακή λογική μέσα σε `page.evaluate()` | info     |
+| QA-PW-114 | Legacy element handles (`page.$`)              | info     |
+| QA-PW-118 | Αναμονές `networkidle` (flaky by design)       | info     |
+| QA-PW-123 | Σκληρά URL περιβάλλοντος                       | warning  |
+
+</details>
+
+<details>
+<summary><strong>Ακεραιότητα CI</strong></summary>
+
+| ID        | Κανόνας                                                               | Severity |
+| --------- | --------------------------------------------------------------------- | -------- |
+| QA-CI-001 | Το `continue-on-error` κρύβει αποτυχίες                               | error    |
+| QA-CI-002 | Το `\|\| true` καταπίνει exit codes                                   | error    |
+| QA-CI-005 | Αναφορά καταναλώνεται αλλά ποτέ δεν παράγεται                         | error    |
+| QA-CI-007 | Περιτύλιξη retry γύρω από τεστ                                        | warning  |
+| QA-CI-008 | Step πάντα επιτυχές κρύβει αποτυχίες                                  | error    |
+| QA-CI-009 | Exit code του τεστ δεν προωθείται (`\|` χωρίς pipefail, αλυσίδες `;`) | error    |
+| QA-CI-010 | Τεστ παραλείπονται εκεί που πρέπει να μπλοκάρουν (skip-on-PR guards)  | error    |
+
+</details>
+
+<details>
+<summary><strong>Python / pytest 🐍</strong></summary>
+
+| ID        | Κανόνας                                       | Severity |
+| --------- | --------------------------------------------- | -------- |
+| QA-PY-002 | Παραλειμένο τεστ (`skip`, μη αυστηρό `xfail`) | warning  |
+| QA-PY-003 | Συνάρτηση τεστ χωρίς assertions               | error    |
+| QA-PY-005 | `time.sleep()` σε τεστ                        | warning  |
+| QA-PY-006 | Κενό σώμα τεστ (`pass`)                       | info     |
+| QA-PY-010 | Εξάρτηση από τύχη/χρόνο χωρίς freeze          | info     |
+| QA-PY-012 | Ταυτολογική assertion                         | error    |
+
+Συνολικά 20 κανόνες Python (QA-PY-001…012 υγιεινή pytest + QA-PY-101…108 Playwright-Python).
+
+</details>
+
+<details>
+<summary><strong>Java / JUnit · TestNG ☕</strong></summary>
+
+| ID        | Κανόνας                                    | Severity |
+| --------- | ------------------------------------------ | -------- |
+| QA-JV-101 | Απενεργοποιημένο τεστ (`@Disabled`)        | warning  |
+| QA-JV-102 | Σκληρό sleep (`Thread.sleep()`)            | warning  |
+| QA-JV-103 | Μέθοδος τεστ χωρίς assertions              | error    |
+| QA-JV-105 | Σκληρό sleep Playwright `waitForTimeout()` | warning  |
+| QA-JV-106 | Εύθραυστος selector αντί για role locator  | warning  |
+| QA-JV-108 | Σκληρό URL περιβάλλοντος στο τεστ          | info     |
+| QA-JV-111 | Μαζικό mock `page.route("**")`             | info     |
+
+</details>
+
+<details>
+<summary><strong>C# / .NET — NUnit · xUnit · MSTest 🟣</strong></summary>
+
+| ID        | Κανόνας                                        | Severity |
+| --------- | ---------------------------------------------- | -------- |
+| QA-CS-101 | Παραλειμένο τεστ (`[Ignore]`, `[Fact(Skip=)]`) | warning  |
+| QA-CS-102 | Σκληρό sleep (`Thread.Sleep` / `Task.Delay`)   | warning  |
+| QA-CS-103 | Μέθοδος τεστ χωρίς assertions                  | error    |
+| QA-CS-105 | Σκληρό sleep `WaitForTimeoutAsync()`           | warning  |
+| QA-CS-106 | Εύθραυστος selector αντί για role locator      | warning  |
+| QA-CS-108 | Σκληρό URL περιβάλλοντος στο τεστ              | info     |
+| QA-CS-111 | Μαζικό mock `page.RouteAsync("**")`            | info     |
+
+</details>
+
+> Ο πλήρης ζωντανός κατάλογος — κάθε κανόνας με tier, confidence,
+> κίνδυνο false positive και διαθεσιμότητα autofix — παράγεται από το
+> μητρώο:
+>
+> ```bash
+> mjolnir rules --md
+> ```
+>
+> Οι σελίδες ανά κανόνα ζουν στο [`docs/rules/`](docs/rules/).
+
+### Πόσο από αυτό είναι μετρημένο
+
+**74 από 99 κανόνες φέρουν ποσοστό false positive μετρημένο σε πραγματικό
+κώδικα OSS** (≥ 10 χειροκίνητα ταξινομημένα ευρήματα ο καθένας· βλ.
+[docs/FP-AUDIT.md](docs/FP-AUDIT.md)). Οι άλλοι 19 κυκλοφορούν πάνω στην
+εκτίμηση του συγγραφέα. Το υποσέλιδο κάθε σκαν σου λέει πόσοι από τους
+_ενεργούς_ κανόνες είναι μετρημένοι· `mjolnir rules --unmeasured`
+παραθέτει τους άμετρητους· η σελίδα `mjolnir explain` κάθε κανόνα
+δηλώνει την κατάστασή του. Δημοσιεύουμε το ποσοστό ακόμα κι όταν είναι
+άσχημο — ο QA-CS-103 αυτοελέγχεται στο 95 % και είναι σε καραντίνα γι'
+αυτό. Να μεγαλώσει αυτό το 78 είναι η συνεχιζόμενη δουλειά του έργου.
+
+### Tiers κανόνων και ωριμότητα γλωσσών
+
+Κάθε κανόνας είναι `core`, `extended` ή `quarantine`, ανατεθειμένος από
+το **μετρημένο** ποσοστό false positive του:
+
+| Tier         | Σημασία                                | Προεπιλεγμένο σκαν | `--strict` |
+| ------------ | -------------------------------------- | :----------------: | :--------: |
+| `core`       | ≤ 10 % μετρημένο FP                    |         ✅         |     ✅     |
+| `extended`   | ≤ 30 % μετρημένο FP                    |         ✅         |     ✅     |
+| `quarantine` | πάνω από 30 %, ή ακόμα άμετρο (n < 10) |         ❌         |     ✅     |
+
+| Γλώσσα          | Adapter           | Κάλυψη σήμερα                                                      |
+| --------------- | ----------------- | ------------------------------------------------------------------ |
+| TypeScript / JS | AST μεταγλωττιστή | η ευρύτερη, η πιο μετρημένη — ως επί το πλείστον `core`/`extended` |
+| Python / pytest | Στρώμα regex      | ευρεία, ελεγμένη σε corpus — ως επί το πλείστον `core`/`extended`  |
+| Java            | Στρώμα regex      | νεότερη — ως επί το πλείστον `extended`/`quarantine`               |
+| C# / .NET       | Στρώμα regex      | νεότερη — ως επί το πλείστον `extended`/`quarantine`               |
+
+TypeScript και Python έχουν την ευρύτερη μετρημένη κάλυψη. Η Java και η
+C# κυκλοφορούν, είναι τεκμηριωμένες και μένουν εκτός του headline αριθμού
+μέχρι μια πραγματική σουίτα καταναλωτή (όχι τα ίδια τα τεστ μιας
+βιβλιοθήκης binding) να ελεγχθεί.
+
+---
+
+## Πώς λειτουργεί το σκόρ
+
+<p align="center">
+  <img src="assets/readme/terminal-hero.svg" alt="Έξοδος τερματικού Mjölnir — WORTHINESS 75/100 NEEDS WORK, ανάλυση διαγνώσεων ανά κατηγορία και λίστα FIX THIS FIRST" width="820" />
+</p>
+
+<sub>Αναδημιουργείται με `npm run docs:hero`;
+[`tests/hero-asset-reproducibility.spec.ts`](tests/hero-asset-reproducibility.spec.ts)
+ρίχνει το CI αν ο artifact αποκλίνει από ό,τι τυπώνει ο reporter.</sub>
+
+Το σκόρ είναι διαφανές: **error −8, warning −3, info −1**, μετά
+κανονικοποίηση με την έκθεση της σουίτας (αφαιρέσεις ανά δήλωση τεστ).
+Οι αφαίρεσεις σταθμισμένες με αποδείξεις σημαίνουν ότι τα αδύναμα σήματα
+κοστίζουν λιγότερο. Το τερματικό δείχνει τους ίδιους εκπτώτους αριθμούς
+που χρησιμοποιεί το σκόρ — καμία μαύρη κάψουλα. Πλήρης μέθοδος:
+[docs/SCORING.md](docs/SCORING.md).
+
+**Ετυμηγορίες**
+
+| Score   | Ετυμηγορία       |
+| ------- | ---------------- |
+| ≥ 80    | ✓ **WORTHY**     |
+| 50 – 79 | ⚠ **NEEDS WORK** |
+| < 50    | ✖ **UNWORTHY**   |
+
+**Επίπεδα αποδείξεων** — κάθε εύρημα φέρει ένα· ορίζει το βάρος του
+ευρήματος στο σκόρ:
+
+| Επίπεδο | Σημασία              | Επίδραση στο σκόρ | Παράδειγμα                                          |
+| ------- | -------------------- | ----------------- | --------------------------------------------------- |
+| E2      | Καθορισμένο ελάττωμα | Πλήρης αφαίρεση   | Commitμένο `.only` — δομικά αποδείξιμο              |
+| E1      | Ευρετικό μοτίβο      | Μισή αφαίρεση     | Regex-βρεμένο `sleep()` — ισχυρό σήμα, όχι απόδειξη |
+| E0      | Παρατήρηση           | Μηδέν (μόνο info) | Αναφέρεται αλλά δεν gated ποτέ CI ούτε αφαιρεί      |
+
+Οι περισσότεροι κανόνες είναι **E1**. Το σύνθημα «we prove it»
+αναφέρεται σε αυτό το σύστημα: τα ευρήματα E2 είναι δομική απόδειξη·
+τα ευρήματα E1 είναι σωστά τοποθετημένες προειδοποιήσεις, όχι τυπικές
+αποδείξεις.
+
+Ένα άδειο repo σκοράρει `null`, ποτέ ψεύτικα 100 — δες
+[Μοντέλο εμπιστοσύνης](#μοντέλο-εμπιστοσύνης).
+
+---
+
+## 🎭 Selector Health Score
+
+Η headline μετρική για σουίτες Playwright — πόσο ανθεκτικοί είναι οι
+locators σου:
+
+```text
+▚▞ SELECTOR HEALTH — e2e/checkout.spec.ts
+
+  [█████████████████░░░]  83 / 100
+  role/text: 2 · testid: 1 · css-chains: 1 ⚠ · xpath: 0
+```
+
+Locators με βάση τα roles παίρνουν πλήρες σκόρ. Οι αλυσίδες CSS class
+και το XPath βυθίζουν το σκόρ — σπάνε σε κάθε refactor DOM χωρίς να σου
+λένε ποια συμπεριφορά παλινδρόμησε.
+
+---
+
+## 🔬 Αποδείξεις runtime
+
+Η στατική ανίχνευση flakiness είναι μαντεψιά. Το Mjölnir διαβάζει
+**πραγματικά δεδομένα εκτέλεσης** — αναφορές JSON Playwright και XML
+JUnit από οποιονδήποτε runner:
+
+```bash
+mjolnir forensics ./test-results/
+```
+
+```text
+▚▞ FLAKINESS LEADERBOARD
+
+3 tests · 1 failed · 1 flaky · 1 retried
+
+TRUE-FLAKE completes checkout with saved card (e2e/checkout.spec.ts)
+           ████████████████████ 6.0s · 2 attempts
+FAILING    declines an expired card (e2e/checkout.spec.ts)
+           ████░░░░░░░░░░░░░░░░ 1.1s · 1 attempt
+```
+
+Τεστ που περνά μόνο από την προσπάθεια ≥ 2 δεν είναι τεστ που περνά —
+είναι τυχερό τεστ. Χαρακτηρίζεται `TRUE-FLAKE` ανεξάρτητα από το τελικό
+πράσινο τσεκ.
+
+---
+
+## ⚡ Το Mjölnir δεν είναι ακόμα ένα linter
+
+Τα linters σου λένε αν ο κώδικας ακολουθεί κανόνες. Το Mjölnir σου λέει
+αν η επαλήθευσή σου μπορεί να εμπιστευτεί.
+
+|                                                                | ESLint / SonarQube | Εργαλεία coverage | Χειροκίνητο review | **Mjölnir** |
+| -------------------------------------------------------------- | :----------------: | :---------------: | :----------------: | :---------: |
+| Ακεραιότητα CI workflow (`continue-on-error`, `\|\| true`)     |         ❌         |        ❌         |       σπάνια       |     ✅      |
+| Cross-γλώσσα (TS, Python, Java, C#) από ένα εργαλείο           |         ❌         |        ❌         |         ❌         |     ✅      |
+| Βαθμολογεί ανθεκτικότητα Playwright locators (Selector Health) |         ❌         |        ❌         |       σπάνια       |     ✅      |
+| Σημαίνει τεστ χωρίς πραγματικές assertions                     |   ✅ (plugin)\*    |        ❌         |     καμιά φορά     |     ✅      |
+| Πιάνει σκληρά sleeps (`waitForTimeout`, `time.sleep`)          |   ✅ (plugin)\*    |        ❌         |     καμιά φορά     |     ✅      |
+| Τρέχει σε δευτερόλεπτα, μηδέν κλήσεις δικτύου κατά το σκαν     |         ✅         |        ✅         |         —          |     ✅      |
+
+\*Το `eslint-plugin-jest` (`expect-expect`) και το
+`eslint-plugin-playwright` (`expect-expect`, `no-wait-for-timeout`)
+καλύπτουν αυτά για τα αντίστοιχα frameworks τους.
+
+**Η ανάλυση runtime** είναι ξεχωριστή κατηγορία δίπλα στο στατικό
+linting:
+
+|                                                                | Playwright retry reporter | Allure / ReportPortal | **Mjölnir forensics** |
+| -------------------------------------------------------------- | :-----------------------: | :-------------------: | :-------------------: |
+| Διαβάζει πραγματικά δεδομένα runs για ετυμηγορίες `TRUE-FLAKE` |         μερικώς\*         |     μερικώς (tag)     |          ✅           |
+| Αναφορά triage flakiness από ιστορικό εκτέλεσης                |            ❌             |          ✅           |          ✅           |
+| Ενσωματώνεται με τον στατικό δείκτη αξιοπιστίας                |            ❌             |          ❌           |          ✅           |
+
+\*Το Playwright παρακολουθεί εσωτερικά τα retries αλλά δεν παράγει
+αυτόνομη αναφορά flakiness με ετικέτες ετυμηγοριών.
+
+---
+
+## 🤖 Γιατί όχι απλώς AI code review;
+
+Διαφορετικό πρόβλημα, διαφορετικό στρώμα. Το AI review μπορεί να πιάσει
+ύποπτη αλλαγή τεστ σε ένα diff· δεν αποδεικνύει ότι το σύστημα
+επαλήθευσης συνολικά αξίζει εμπιστοσύνη — και βλέπει μόνο το diff που
+του δείχνεις.
+
+|                                              |      AI code review (Copilot κ.λπ.)      |            **Mjölnir**            |
+| -------------------------------------------- | :--------------------------------------: | :-------------------------------: |
+| Κόστος ανά σκαν                              | Tokens (κλιμακώνεται με το μέγεθος diff) | **Μηδέν** (τοπικό, εγκατεστημένο) |
+| Βλέπει όλη τη σουίτα + όλες τις ρυθμίσεις CI |       Μόνο το PR diff που δείχνεις       |        **Όλα, κάθε φορά**         |
+| Καθοριστικό (ίδιο input → ίδιο output)       |           ❌ (μη καθοριστικό)            |              **✅**               |
+| Πιάνει μοτίβα που κοιμούνται μήνες           |        Μόνο αν είναι στο context         |  **✅** (σκανάρει όλα τα αρχεία)  |
+| Θυμάται ευρήματα μεταξύ runs                 |    ❌ (καμία μνήμη μεταξύ συνεδριών)     |     **✅** (baseline + diff)      |
+| Τρέχει χωρίς ανθρώπινο έναυσμα               |          Χρειάζεται PR ή prompt          | **✅** (CI hook, 3 δευτερόλεπτα)  |
+
+**Χρησιμοποίησέ τα και τα δύο.** Το AI πιάνει νύαντσε, πρόθεση και
+σχεδιαστικά ελαττώματα που καμία regex δεν βρίσκει. Το Mjölnir πιάνει
+τα δομικά μοτίβα που το AI παραβλέπει επειδή φαίνονται «εσκεμμένα» —
+ένα commitμένο `.only`, ένα καταπιμένο exit code, ένα `continue-on-error`
+σε τεστ job. Δεν είναι bugs που χρειάζονται συλλογισμό· είναι γεγονότα
+που χρειάζονται σκαν.
+
+---
+
+## 🤖 Ενσωμάτωση CI
+
+Μία εντολή παράγει PR workflow — συμβουλευτικό από προεπιλογή, ποτέ
+μπλοκάρισμα:
+
+```bash
+mjolnir ci install
+```
+
+Ή σύνδεσέ το εγγενώς σε GitHub Code Scanning μέσω SARIF:
+
+```yaml
+- run: npx mjolnir-qa@latest --format sarif > mjolnir.sarif
+- uses: github/codeql-action/upload-sarif@v3
+  with:
+    sarif_file: mjolnir.sarif
+```
+
+Ρύθμιση editor και pipeline για SARIF:
+[docs/SARIF-INTEGRATION.md](docs/SARIF-INTEGRATION.md).
+
+### Κάλυψη changed-scope
+
+Το `--scope changed` αποδίδει ευρήματα σε γραμμές που πρόσθεσε το branch
+σου σε σχέση με το merge-base με το `main`. Καλύπτει αρχεία τεστ
+(`*.spec.*`, `*.test.*`) συν αρχεία GitHub workflow και ρυθμίσεις
+Playwright στο diff. Όταν το merge-base δεν λύνεται — shallow clone,
+detached HEAD, μη-git στόχος, διαφορετικό default branch — υποβαθμίζει
+ειλικρινά: τα ευρήματα επιστρέφουν σε απόδοση κατά σύνολο αρχείου και η
+αναφορά το λέει. Υπενόμησε την base ref με `--base <ref>`.
+
+---
+
+## Διαμόρφωση
+
+Το Mjölnir είναι zero-config. Ένα προαιρετικό `mjolnir.config.json` (ή
+`.mjolnir.json`) στη ρίζα του repo ρυθμίζει severity, gating και scope —
+δεν αλλάζει ποτέ τη σημασιολογία ανίχνευσης.
+
+| Key                 | Τύπος                                | Επίδραση                                                                                                                                                                      |
+| ------------------- | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `exclude`           | `string[]`                           | Επιπλέον ignore globs (υποσύνολο gitignore), πάνω από τα ενσωματωμένα defaults                                                                                                |
+| `gate`              | `"advisory" \| "error" \| "warning"` | Ποια severity βγαίνουν μη μηδενικά (default `error`; το `advisory` δεν μπλοκάρει ποτέ)                                                                                        |
+| `severityOverrides` | `{ "<RULE-ID>": severity }`          | Επανατάσσει τα ευρήματα ενός κανόνα για το repo σου                                                                                                                           |
+| `ignore`            | `IgnoreEntry[]`                      | Καταστέλλει ευρήματα — **το `reason` απαιτείται**· οι εγγραφές λήγουν μετά από 90 ημέρες (ρητό `expires` date, ή time last-modified του αρχείου ρυθμίσεων για εγγραφές χωρίς) |
+| `plugins`           | `string[]`                           | Πακέτα κανόνων τρίτων (δες [Μοντέλο εμπιστοσύνης](#μοντέλο-εμπιστοσύνης))                                                                                                     |
+
+```json
+{
+  "gate": "error",
+  "exclude": ["legacy/**"],
+  "severityOverrides": { "QA-PW-118": "warning" },
+  "ignore": [
+    {
+      "ruleId": "QA-TEST-004",
+      "files": ["e2e/legacy-login.spec.ts"],
+      "reason": "Third-party widget needs a settle delay; tracked in JIRA-4821",
+      "expires": "2026-12-31"
+    }
+  ]
+}
+```
+
+- **`.mjolnirignore`** — απλό αρχείο τύπου gitignore για εξαιρέσεις
+  διαδρομών, ίδια διάλεκτος με το `exclude`. Χρησιμοποίησέ το για θόρυβο
+  ανά μηχανή· χρησιμοποίησε `exclude` όταν η λίστα ανήκει στον version
+  control, δίπλα στην υπόλοιπη ρύθμιση.
+- **CLI overrides** — `--strict` (συμπερίληψη κανόνων καραντίνας),
+  `--width <cols>` και `--ascii` / `--no-ascii` (απόδοση τερματικού),
+  `--tone blunt` (πιο άκαμπτα μηνύματα), `--max-duration <sec>`
+  (περιορισμένη μερική σκαν).
+- Καταστολή κανόνων και κύκλος ζωής deprecation:
+  [docs/RULE-LIFECYCLE.md](docs/RULE-LIFECYCLE.md).
+
+Οι εγγραφές `ignore` τροφοδοτούν και την αυτόνομη εντολή
+`mjolnir suppressions`, που παραθέτει τι είναι κατασταλμένο τώρα και
+πότε λήγει κάθε εγγραφή.
+
+---
+
+## 📐 Exit codes & συμβόλαια
+
+Παγωμένα — ασφαλή για χτίσιμο CI λογικής:
+
+| Exit code | Σημασία                                                                               |
+| --------- | ------------------------------------------------------------------------------------- |
+| `0`       | Καθαρό — κανένα εύρημα στο ή πάνω από το gate                                         |
+| `1`       | Ευρήματα στο ή πάνω από το gate                                                       |
+| `2`       | Μερικό σκαν (τέλος χρονικού προϋπολογισμού, δυσανάγνωστα αρχεία) — δεν μπλοκάρει ποτέ |
+| `10`      | Λάθος χρήσης (bad flag, λείπει στόχος)                                                |
+| `20`      | Εσωτερικό λάθος                                                                       |
+
+Η αναφορά JSON/SARIF είναι `schemaVersion: 1`. Τα IDs κανόνων
+(`QA-<FAMILY>-NNN`) είναι αμετάβλητα μόλις κυκλοφορήσουν και δεν
+επαναχρησιμοποιούνται ποτέ.
+
+---
+
+## Μοντέλο εμπιστοσύνης
+
+- **Local-first** — μηδέν κλήσεις δικτύου κατά το σκαν. Ποτέ. Μηδενική
+  τηλεμετρία.
+- **Καμία ψεύτικη απόδειξη** — προτιμούμε να πούμε «άγνωστο» παρά
+  «επαληθευμένο». Άδειο repo παίρνει `score: null`, ποτέ ψεύτικα 100.
+- **Μερική ειλικρίνεια** — αν η ανάλυση κόπηκε, η έξοδος το λέει.
+  Ποτέ «complete» όταν δεν είναι.
+- **FP τείχος** — η ανίχνευση τρέχει σε άποψη κώδικα χωρίς
+  σχόλια/strings (οι κανόνες TypeScript χρησιμοποιούν AST
+  μεταγλωττιστή): ένα μοτίβο μέσα σε σχόλιο πρόζας ή doc-παράδειγμα
+  string είναι τεκμηρίωση, όχι εύρημα.
+- **Μετρημένο, όχι δηλωμένο** — μόνο κανόνες με ποσοστό false positive
+  από πραγματικό OSS κώδικα κυκλοφορούν στα headline tiers (δες
+  [Πόσο από αυτό είναι μετρημένο](#πόσο-από-αυτό-είναι-μετρημένο)); το
+  υποσέλιδο σκαν και το `mjolnir rules --unmeasured` σου λένε ποιος
+  ποιος.
+- **Εμπιστοσύνη plugins** — τα plugins είναι πακέτα npm δηλωμένα κάτω
+  από `"plugins"`. **Δεν υπάρχει sandbox**: ο κώδικας plugin τρέχει με
+  πλήρη δικαιώματα Node, το ίδιο μοντέλο εμπιστοσύνης με plugins ESLint
+  ή Vitest. Core προθέματα rule-ID είναι δεσμευμένα και απορρίπτονται
+  από plugins κατά της πλαστοπροσωπίας.
+- **Εξωτερικοί κανόνες τοπικοί στο workspace** (φάκελος, μηδέν δίκτυο) —
+  ένας φάκελος `mjolnir-rules/` δίπλα στον στόχο σκαν φορτώνει custom
+  κανόνες: JSON αρχεία δηλώνουν regex μοτίβα (κανένας κώδικας δεν
+  εκτελείται), `.mjs`/`.js` modules εξάγουν `rules` (πλήρης εμπιστοσύνη
+  Node, όπως plugins). Οι εξωτερικοί κανόνες φέρουν τα ίδια trust
+  metadata με το core· δεν μπορούν ποτέ να κυκλοφορήσουν στο core tier
+  (το core απαιτεί μετρημένο FP από το corpus sidecar — δηλωμένο
+  `tier: "core"` σφίγγεται σε `extended`), τηρούν tier πλαφόν και
+  ελέγχονται για drift: `mjolnir rules --md --external` απεικονίζει τον
+  κατάλογο από τα φορτωμένα αρχεία (provenance `external`), και ο
+  generator matrix δέχεται `--external <root>`.
+
+---
+
+## 🏗️ Αρχιτεκτονική
+
+<details>
+<summary>Ανάπτυξη δέντρου</summary>
+
+```
+mjolnir/
+├── src/
+│   ├── engine/          # LanguageAdapter interface + rule runner
+│   ├── adapters/        # typescript · python · java · csharp · github-actions
+│   ├── rules/           # rules across 8 families + the measured-FP table
+│   ├── playwright/      # Selector Health Score engine
+│   ├── discovery/       # workspace, frameworks, ignore resolution
+│   ├── scope/           # git merge-base changed-scope engine
+│   ├── scorer/          # transparent deduction table + prioritization
+│   ├── reporter/        # terminal · JSON · SARIF 2.1 · Mermaid
+│   ├── forensics/       # run-data ingestion · flake verdicts · triage
+│   ├── config/          # mjolnir.config.json + suppressions
+│   ├── plugins/         # third-party rule loading (no sandbox)
+│   └── commands/        # every subcommand
+└── tests/
+    ├── fixtures/        # must-fire / must-not-fire per rule
+    └── golden/          # frozen score regression locks
+```
+
+</details>
+
+- **Οι κανόνες είναι καθαρές συναρτήσεις** —
+  `(SourceFileContext) → Finding[]`, χωρίς I/O, χωρίς globals. Νέο
+  οικοσύστημα = ένας adapter + οι κανόνες του.
+- **TypeScript/Playwright χρησιμοποιεί AST μεταγλωττιστή** (ts-morph).
+  Python, Java και C# τρέχουν σε κοινό regex στρώμα με μεταμφιεσμένα
+  σχόλια/strings.
+- Ένα στρώμα AST tree-sitter WASM για Java και C# υπάρχει και είναι το
+  επόμενο βήμα ακρίβειας — δεν είναι ακόμα συνδεμένο στον σύγχρονο
+  σκαν pipeline.
+
+---
+
+## 📚 Τεκμηρίωση
+
+| Έγγραφο                                                | Τι περιέχει                                 |
+| ------------------------------------------------------ | ------------------------------------------- |
+| [docs/SCORING.md](docs/SCORING.md)                     | Κανονικοποίηση σκόρ + στάθμιση αποδείξεων   |
+| [docs/FP-AUDIT.md](docs/FP-AUDIT.md)                   | Μετρημένα ποσοστά false positive + μέθοδος  |
+| [docs/RULE-LIFECYCLE.md](docs/RULE-LIFECYCLE.md)       | Καταστάσεις κανόνων, καταστολή, deprecation |
+| [docs/SARIF-INTEGRATION.md](docs/SARIF-INTEGRATION.md) | Έξοδος SARIF + ρύθμιση editor/CI            |
+| [docs/rules/](docs/rules/)                             | Δημιουργημένος κατάλογος ανά κανόνα         |
+| [CONTRIBUTING.md](CONTRIBUTING.md)                     | Dev setup + workflow συμβολής               |
+| [CHANGELOG.md](CHANGELOG.md)                           | Ιστορικό εκδόσεων                           |
+| [SECURITY.md](SECURITY.md)                             | Αναφορά ευπαθειών                           |
+
+---
+
+## 📈 Κατάσταση
+
+**v0.5.x · ανοιχτή beta.** Το JSON schema και τα exit codes είναι
+παγωμένα συμβόλαια. TypeScript και Python έχουν την ευρύτερη μετρημένη
+κάλυψη· Java και C# είναι νεότερα — διαβάστε τα μέσω του
+[πίνακα tiers](#tiers-κανόνων-και-ωριμότητα-γλωσσών).
+
+---
+
+## 🤝 Συνεισφορά
+
+Νέοι κανόνες είναι ο ευκολότερος πρώτος συνεισφορά — μία εντολή
+σκαφφάρει τον κανόνα συν τα fixtures must-fire **και** must-not-fire (ο
+δημιουργημένος κανόνας αστοχεί σκόπιμα στα fixtures μέχρι να
+υλοποιήσεις πραγματική ανίχνευση — stub δεν μπορεί να κυκλοφορήσει):
+
+```bash
+mjolnir create-rule QA-PW-140 --title "Screenshot without diff bound"
+```
+
+Πλήρες dev setup, οι εντολές standing gate και οι νόμοι anti-creep /
+τείχος fixtures είναι στο [CONTRIBUTING.md](CONTRIBUTING.md).
+
+---
+
+<div align="center">
+
+**Σταμάτα να στέλνεις τεστ που δεν εμπιστεύεσαι.**
+
+```bash
+npx mjolnir-qa@latest
+```
+
+**Star ⭐ · Watch 👀 · Contribute 🤝**
+
+Κατασκευάστηκε από [Sergey Bar](https://www.linkedin.com/in/sergeybar/)
+
+</div>