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.* 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: 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