From 156b4b6a5952722b957a16673a6642dc8c91ac68 Mon Sep 17 00:00:00 2001 From: PythonWoods Date: Sun, 26 Jul 2026 18:50:51 +0200 Subject: [PATCH 1/3] feat(cli): add --json shorthand alias to score command (ECOSYSTEM-FEAT-002) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds a --json flag to `zenzic score` as an ergonomic shorthand for --format json. When passed, it overrides the output format to JSON before any rendering logic runs, suppressing all rich/text output and emitting a single deterministic JSON object on stdout. Intended for programmatic consumers (e.g., editor integrations) that need to parse the score without grepping through rich terminal output. The flag is functionally identical to `--format json` / `-f json` — same code path, same ScoreReport.to_dict() schema, same exit code contract. Schema emitted on stdout: {"project": "zenzic", "score": 98, "status": "success", "categories": [...], "suppression_debt_pts": 2, ...} Architectural invariants preserved: - Radical Unawareness (ADR-075): Core emits JSON to stdout, unaware of consumer. - Zero Subprocess: no child processes spawned by Core. Part of: ECOSYSTEM-FEAT-002-DQS-WORKSPACE-UI (v0.26.0 Deterministic Quality Platform) Signed-off-by: PythonWoods --- src/zenzic/cli/_standalone.py | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/src/zenzic/cli/_standalone.py b/src/zenzic/cli/_standalone.py index 08bb48be..b13ade43 100644 --- a/src/zenzic/cli/_standalone.py +++ b/src/zenzic/cli/_standalone.py @@ -233,8 +233,21 @@ def score( "--breakdown", help="Explode scoring categories showing individual occurred Z-Codes and transparent math.", ), + json_flag: bool = typer.Option( + False, + "--json", + help=( + "Shorthand for --format json. Suppresses all rich/text output and emits a single " + "JSON object on stdout. Intended for programmatic consumers (e.g., editor integrations)." + ), + ), ) -> None: """Compute a 0–100 documentation quality score across all checks.""" + # ECOSYSTEM-FEAT-002: --json is a shorthand alias for --format json. + # Programmatic consumers (e.g., editor integrations) should prefer this flag + # over --format json for ergonomic clarity. + if json_flag: + output_format = "json" if ci: no_header = True From f88d7302f540f6164fe54f46c4782e964c1c7f2f Mon Sep 17 00:00:00 2001 From: PythonWoods Date: Sun, 26 Jul 2026 18:53:46 +0200 Subject: [PATCH 2/3] docs(cli): document --json flag for zenzic score (Mirror Law ADR-020) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Per la Mirror Law (ADR-020), i runbook e la documentazione devono riflettere esattamente le procedure e le flag CLI reali. Aggiornamenti a docs/reference/cli.md — tab 'zenzic score': - Aggiunta riga --json alla tabella dei flag: shorthand for --format json, per consumer programmatici (editor integration, shell scripts). - Documentati i flag precedentemente mancanti: --breakdown, --save, --check-stamp, --no-header, --ci (completamento della tabella). - Aggiunto esempio 'zenzic score --json' nel blocco di usage examples. - Aggiunta sezione collassabile 'JSON Output Schema (--json)' con lo schema completo di ScoreReport.to_dict() e i valori possibili di 'status'. Verificato con: just docs-build (mkdocs build --strict, 0 errori). Part of: ECOSYSTEM-FEAT-002-DQS-WORKSPACE-UI (v0.26.0 Deterministic Quality Platform) Signed-off-by: PythonWoods --- docs/reference/cli.md | 44 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/docs/reference/cli.md b/docs/reference/cli.md index e5215eee..ef883895 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -54,7 +54,13 @@ Select a command tab to view its execution flags, default behaviors, and usage e | `--fail-under` | — | `0` | Minimum required score. Fails quality gate (Exit 1) if score falls below threshold. | | `--stamp` | — | `false` | Updates README.md status badge with the newly computed DQS score. | | `--format` | `-f` | `text` | Output format: `text` or `json`. | + | `--json` | — | `false` | Shorthand for `--format json`. Suppresses all rich/text output and emits a single JSON object on `stdout`. Preferred for programmatic consumers (e.g., editor integrations, shell scripts). | | `--strict` | `-s` | `false` | Includes external HTTP link validation in score calculation. | + | `--breakdown` | — | `false` | Expands category breakdown showing individual Z-Codes and transparent penalty math. | + | `--save` | — | `false` | Saves score snapshot to `.zenzic-score.json` for use with `zenzic diff`. | + | `--check-stamp` | — | `false` | Verifies badge stamp files contain the current score URL. Exits 1 if any badge is stale. | + | `--no-header` | — | `false` | Suppresses the Zenzic banner (set automatically by `--ci`). | + | `--ci` | — | `false` | CI shorthand: sets `--no-header`. | **Usage Examples:** ```bash title="Terminal" @@ -66,8 +72,46 @@ Select a command tab to view its execution flags, default behaviors, and usage e # Stamp status badge into README.md zenzic score --stamp + + # Emit machine-readable JSON for programmatic consumers (editor integrations, scripts) + zenzic score --json + + # Equivalent long form + zenzic score --format json ``` + ??? info "JSON Output Schema (`--json`)" + When `--json` (or `--format json`) is passed, the command emits a single JSON + object on `stdout` with no rich/text output. Suitable for piping to `jq` or + parsing in editor extensions. + + ```json + { + "project": "", + "score": 98, + "threshold": 0, + "status": "success", + "timestamp": "2026-07-26T16:49:29+00:00", + "categories": [ + { "name": "structural", "weight": 0.30, "issues": 0, "category_score": 1.0, + "contribution": 0.30, "raw_penalty": 0, "is_capped": false }, + { "name": "navigation", "weight": 0.25, "issues": 0, "category_score": 1.0, + "contribution": 0.25, "raw_penalty": 0, "is_capped": false }, + { "name": "content", "weight": 0.20, "issues": 0, "category_score": 1.0, + "contribution": 0.20, "raw_penalty": 0, "is_capped": false }, + { "name": "brand", "weight": 0.25, "issues": 0, "category_score": 1.0, + "contribution": 0.25, "raw_penalty": 0, "is_capped": false } + ], + "suppression_count": 2, + "suppression_cap": 30, + "suppression_debt_pts": 2, + "debt_status": "MANAGED DEBT" + } + ``` + + Possible values of `status`: `success`, `failing` (score < `fail_under`), + `security_breach` (Z2xx finding detected). + === "zenzic diff" Evaluate score delta and finding changes against a stored baseline file: From 6cefc6abac0302574ba6e5d1f25e35cef5c02a11 Mon Sep 17 00:00:00 2001 From: PythonWoods Date: Sun, 26 Jul 2026 18:57:19 +0200 Subject: [PATCH 3/3] docs(roadmap): realign milestones for v0.26.0 DQS Workspace UI shift (ROADMAP-ALIGN-004) Realigns public ROADMAP.md and internal 0. Priority Table.md: - Promotes DQS Workspace UI to [v0.26] milestone. - Shifts Deterministic Quality Platform to [v0.27]. - Shifts Governance & Extensibility to [v0.28]. - Shifts Ecosystem Expansion to [v0.29]. - Shifts Operational Excellence to [v0.30]. - Marks Prompt 8 (DQS Workspace UI) as [x] Completata (v0.26.0). Verifications: - zenzic check all --strict: DQS 98/100 (Passed) - just docs-build: 0 errors (Passed) Architectural invariants preserved: Mirror Law (ADR-020). Part of: ROADMAP-ALIGN-004-V026-SHIFT Signed-off-by: PythonWoods --- .../Roadmaps/0. Priority Table.md | 73 +++++++++++++++++++ ROADMAP.md | 15 ++-- 2 files changed, 83 insertions(+), 5 deletions(-) create mode 100644 .draft/OrchestrationPrompts/Roadmaps/0. Priority Table.md diff --git a/.draft/OrchestrationPrompts/Roadmaps/0. Priority Table.md b/.draft/OrchestrationPrompts/Roadmaps/0. Priority Table.md new file mode 100644 index 00000000..07fbf4a1 --- /dev/null +++ b/.draft/OrchestrationPrompts/Roadmaps/0. Priority Table.md @@ -0,0 +1,73 @@ +# Zenzic Roadmap & Prompt Priority Table + +| Stato | Priorità | Prompt | Feature | Motivazione architetturale | +| :--- | :--- | ---: | :--- | :--- | +| `[x]` | **P0** | Prompt 1 | **Zenzic Language Server (ZLS) & VS Code Integration** | Fondamento della strategia "Shift-Left". Senza ZLS stabile, le funzionalità IDE successive non hanno una base affidabile. (Rilasciato in v0.23.x). | +| `[x]` | **P0** | Prompt 10 | **Incremental Analysis Engine** | Necessario per rendere ZLS réellement utilizzabile. Riduce il costo delle analisi incrementali e preserva il requisito di latenza sub-50ms. (Rilasciato in v0.23.x). | +| `[x]` | **P1** | Prompt 7 | **VS Code Code Actions (Quick Fixes)** | Completa il ciclo diagnostica → remediation. Abilita Quick Fixes deterministici via `textDocument/codeAction` e `WorkspaceEdit` in-memory. (Rilasciato in v0.24.0). | +| `[x]` | **P1** | Prompt 8 | **DQS Workspace UI** | Porta la qualità globale nell'ambiente autore tramite un bridge asincrono deterministico CLI (`zenzic score --json`) e visualizzazione nella Status Bar di VS Code. (Completata in v0.26.0). | +| `[x]` | **P0** | — | **LSP Stabilization & Hot-Reloading** | Parità di governance CLI-IDE e hot-reloading guidato da `watched_config_files` dell'Adapter. (Rilasciato in v0.25.0). | +| `[ ]` | **P0** | Prompt 6 | **Smart Link Graph** | Completa il modello VSM trasformandolo da sistema di risoluzione a motore di analisi topologica completa. Abilita rilevamento di isole, cicli e struttura documentale. | +| `[ ]` | **P0** | Prompt 15 | **Baseline & Regression Tracking** | Introduce il controllo evolutivo della qualità. Indispensabile per CI enterprise e per impedire regressioni DQS. | +| `[ ]` | **P1** | Prompt 2 | **Semantic Linting & Readability Metrics** | Estende Zenzic oltre la validazione strutturale verso la qualità del contenuto mantenendo il paradigma deterministic static analysis. | +| `[ ]` | **P1** | Prompt 16 | **Configuration Validation Engine** | Riduce errori operativi e diventa la sorgente unica per CLI, VS Code e documentazione tramite Mirror Law. | +| `[ ]` | **P1** | Prompt 14 | **Policy-as-Code Engine** | Formalizza la governance. Trasforma configurazioni sparse e ADR in un modello dichiarativo verificabile. | +| `[ ]` | **P2** | Prompt 3 | **Docusaurus Bridge Architecture** | Prima implementazione concreta dell'ecosistema adapter. Valida il modello VSM artifact-based fuori dal Core. | +| `[ ]` | **P2** | Prompt 4 | **Sphinx Adapter** | Estende la compatibilità open-source. Deve seguire la stabilizzazione del contratto BaseAdapter. | +| `[ ]` | **P2** | Prompt 5 | **Hugo Adapter** | Analogo allo Sphinx Adapter. Priorità inferiore perché dipende dall'efficacia del modello adapter. | +| `[ ]` | **P2** | Prompt 12 | **Custom Rule SDK v3** | Importante per ecosistema e community, ma richiede prima stabilità dell'engine di analisi e sandbox. | +| `[ ]` | **P2** | Prompt 13 | **SARIF Enterprise Integration** | Migliora integrazione security e compliance, ma non modifica il cuore architetturale. | +| `[ ]` | **P3** | Prompt 17 | **Performance Telemetry Engine** | Utile per ottimizzazione e governance operativa, ma deve seguire la stabilizzazione del runtime. | +| `[ ]` | **P3** | Prompt 19 | **Zenzic Audit Mode** | Feature enterprise ad alto valore, ma richiede stabilità di DQS, Policy Engine e SARIF. | +| `[ ]` | **P3** | Prompt 18 | **Multi Repository Documentation Graph** | Feature avanzata che amplia il dominio, ma richiede prima maturità completa di VSM, Smart Graph e artifact composition. | +| `[ ]` | **P3** | Prompt 9 | **VS Code Configuration Autocomplete** | Importante per UX, ma subordinata alla stabilizzazione dello schema configurativo e del Configuration Validation Engine. | + +--- + +## Sequenza milestone aggiornata + +| Milestone | Obiettivo | Prompt coinvolti | Stato | +| :--- | :--- | :--- | :--- | +| **v0.23 — Authoring Intelligence Foundation** | Portare Zenzic dentro l'IDE con feedback immediato | 1 → 10 | `[x] Completata` | +| **v0.24 — Interactive Intelligence** | Completa il ciclo diagnostica → remediation nell'IDE | 7 | `[x] Completata` | +| **v0.25 — LSP Stabilization & Hot-Reloading** | Parità CLI-IDE, hot-reload adapter, path normalization | — | `[x] Rilasciata` | +| **v0.26 — DQS Workspace UI** | Visualizzazione deterministica DQS nell'editor via CLI bridge asincrono | 8 | `[x] Completata (v0.26.0)` | +| **v0.27 — Deterministic Quality Platform** | Evolvere da validator a quality governance engine | 6 → 15 → 2 → 16 | `[ ] In programma` | +| **v0.28 — Governance & Extensibility** | Aprire SDK, policy e integrazioni enterprise | 14 → 12 → 13 → 19 | `[ ] In programma` | +| **v0.29 — Ecosystem Expansion** | Espandere il perimetro verso framework esterni | 3 → 4 → 5 → 18 | `[ ] In programma` | +| **v0.30 — Operational Excellence** | Ottimizzazione e osservabilità avanzata | 17 → 9 | `[ ] In programma` | + +--- + +## Dipendenze critiche + +```text +ZLS (v0.23.x - Complete) + │ + ├── Incremental Analysis Engine (v0.23.x - Complete) + │ │ + │ ├── Code Actions (v0.24.0 - Complete) + │ ├── DQS Workspace UI (v0.26.0 - Complete) + │ └── Hot-Reloading & Governance Parity (v0.25.0 - Complete) + │ + ├── Smart Link Graph (v0.27) + │ │ + │ └── Multi Repository Graph (v0.29) + │ + ├── DQS Model + │ │ + │ ├── Baseline Tracking (v0.27) + │ ├── Policy Engine (v0.28) + │ └── Audit Mode (v0.28) + │ + └── Adapter Contract + │ + ├── Docusaurus (v0.29) + ├── Sphinx (v0.29) + └── Hugo (v0.29) +``` + +Questa sequenza mantiene una progressione coerente: + +**Core deterministico → IDE intelligence → LSP Stabilization → Quality Governance → Ecosystem Expansion → Enterprise Platform**. + diff --git a/ROADMAP.md b/ROADMAP.md index 49bf426c..1e9efab0 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -30,7 +30,6 @@ Before advancing the core feature set, the following infrastructural and validat *Completing the diagnostic-to-remediation loop within the IDE.* - **VS Code Code Actions (Quick Fixes):** Implement `textDocument/codeAction` via LSP to allow users to instantly apply deterministic fixes (e.g., `Z121`, `Z603`) directly from the editor. -- **DQS Workspace UI:** Bring the Document Quality Score (DQS) into the authoring environment via a dedicated VS Code sidebar panel, providing global repository state without leaving the editor. ### [v0.25] — LSP Stabilization & Hot-Reloading @@ -40,7 +39,13 @@ Before advancing the core feature set, the following infrastructural and validat - **Adapter-Driven Config Hot-Reloading:** Enable real-time VSM topology rebuilds in VS Code when engine configuration files (e.g., `mkdocs.yml`, `zensical.toml`) change, without requiring an LSP server restart. - **BaseAdapter Contract Hardening:** Expose `watched_config_files` on the `BaseAdapter` interface to preserve Adapter Neutrality across third-party engines. -### [v0.26] — Deterministic Quality Platform +### [v0.26] — DQS Workspace UI + +*Bringing the global Documentation Quality Score into the authoring environment via an asynchronous, deterministic CLI execution bridge.* + +- **Asynchronous CLI Execution Bridge:** Restore DQS visualization in the VS Code Status Bar via `child_process.execFile` calling `zenzic score --json`, guaranteeing 100% mathematical parity with CI/CD without blocking LSP performance. + +### [v0.27] — Deterministic Quality Platform *Evolving from a strict validator to a comprehensive quality governance engine.* @@ -49,7 +54,7 @@ Before advancing the core feature set, the following infrastructural and validat - **Semantic Readability Metrics:** Extend Zenzic beyond structural validation into content quality (e.g., deterministic Flesch-Kincaid scoring) while maintaining the static analysis paradigm. - **Configuration Validation Engine:** Reduce operational errors by establishing a single source of truth for configuration schemas across the CLI, VS Code, and documentation. -### [v0.27] — Governance & Extensibility +### [v0.28] — Governance & Extensibility *Opening the engine to enterprise policies and custom integrations.* @@ -58,7 +63,7 @@ Before advancing the core feature set, the following infrastructural and validat - **SARIF Enterprise Integration:** Enhance security and compliance integrations for enterprise dashboards. - **Zenzic Audit Mode:** High-value enterprise reporting mode requiring stable DQS, Policy Engine, and SARIF outputs. -### [v0.28] — Ecosystem Expansion +### [v0.29] — Ecosystem Expansion *Expanding the perimeter to external frameworks.* @@ -66,7 +71,7 @@ Before advancing the core feature set, the following infrastructural and validat - **Sphinx & Hugo Adapters:** Extend open-source compatibility following the stabilization of the `BaseAdapter` contract. - **Multi-Repository Documentation Graph:** Advanced feature to analyze documentation spanning multiple repositories, requiring full maturity of the VSM and artifact composition. -### [v0.29] — Operational Excellence +### [v0.30] — Operational Excellence *Advanced observability and developer experience.*