diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000..e11c735 --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,5 @@ +{ + "githubPullRequests.ignoredPullRequestBranches": [ + "main" + ] +} \ No newline at end of file diff --git a/design/srs-Clients-Plugin.md b/design/srs-Clients-Plugin.md new file mode 100644 index 0000000..8792002 --- /dev/null +++ b/design/srs-Clients-Plugin.md @@ -0,0 +1,788 @@ +# Software Requirements Specification: Structured Markdown Clients + +Version: 0.2 +Date: 2026-06-29 +Status: Draft for implementation planning +Related specifications: +- [srs-Parser-Reader-SRS.md](srs-Parser-Reader-SRS.md) +- [imp-Parser-Reader-SRS.md](imp-Parser-Reader-SRS.md) +- [srs-VS-Code-Plugin.md](srs-VS-Code-Plugin.md) +- [2026-06-28-b1-parse-assess-implementation-update.md](2026-06-28-b1-parse-assess-implementation-update.md) +- [2026-06-28-Future-Implementation-Tasks.md](2026-06-28-Future-Implementation-Tasks.md) + +## 1. Introduction + +### 1.1 Purpose + +This Software Requirements Specification defines client applications that demonstrate and operationalize the Structured Markdown specification and parser. + +The clients are not the semantic source of truth. They are user-facing applications over an engine-owned semantic layer: + +`article` contains `unit` contains `component` contains `attribute`. + +The Structured Markdown parser engine and specification provide the agnostic semantic layer. Client tools consume that layer to help users inspect, validate, triage, repair, report on, and prepare Markdown or rendered HTML content for downstream workflows such as DITA XML, Schema.org, RAG ingestion, dependency analysis, author feedback, CI reporting, and migration planning. + +### 1.2 Client Strategy + +The first-class client shall be a standalone Electron application. The Electron client shall provide a repository-level workbench for content architects, documentation engineers, DITA migration specialists, RAG pipeline owners, and technical writers who need to assess and improve content across files and folders. + +The VS Code extension shall be an additional client. It shall provide in-editor authoring feedback for writers and technical authors working inside Markdown files. + +Both clients shall illustrate the same core claim: Structured Markdown is an engine-owned, client-agnostic semantic layer. Electron, VS Code, CLI, CI, and future clients shall consume the same parser contract rather than reimplementing parser logic. + +### 1.3 Scope + +The client system shall: + +- Consume parser engine output through stable machine-readable contracts. +- Display structured Markdown article, unit, component, and attribute data. +- Display diagnostics, unknown structures, validation state, and transform-readiness state. +- Help users understand whether content is suitable for DITA XML, Schema.org output, RAG chunking, XML serialization, or authoring compliance. +- Support the primary SRS use cases for content architects, writers, metadata owners, transform developers, RAG pipeline owners, CI maintainers, support engineers, and QA engineers. +- Keep parser, schema, validation, transform-readiness, and semantic classification logic inside the parser engine. + +The client system shall not: + +- Replace the parser engine. +- Duplicate the Structured Markdown schema model in client code. +- Reimplement article, unit, component, attribute, validation, or readiness decisions. +- Guarantee complete DITA migration by itself. +- Execute untrusted Markdown, embedded HTML, scripts, or code blocks. +- Require network access for normal local validation and assessment workflows. + +### 1.4 Audience + +This document is intended for: + +- Electron client developers. +- VS Code extension developers. +- Parser engine maintainers. +- Content architects. +- Documentation engineers. +- Technical writers and Markdown authors. +- DITA migration specialists. +- RAG pipeline owners. +- Release engineers. +- QA engineers. + +### 1.5 Definitions + +| Term | Definition | +|---|---| +| Engine | The Structured Markdown parser package that parses Markdown and rendered HTML into structured contracts, diagnostics, validation results, references, provenance, and readiness reports. | +| Semantic layer | The engine-owned, versioned content model that represents articles, units, components, attributes, metadata hooks, references, diagnostics, and readiness state. | +| Electron client | The first-class standalone desktop application for repository-level content assessment, parser demonstration, reporting, and migration/RAG planning. | +| VS Code extension | The additional editor-integrated client for inline authoring validation and feedback. | +| Client | Any application that consumes the engine-owned Structured Markdown contract. | +| Contract boundary | The versioned JSON request/response boundary between clients and the parser engine. | +| Profile | A named validation, schema, metadata, or transform-readiness configuration. | +| Transform readiness | Engine-provided assessment of whether parsed content has enough explicit structure, metadata, provenance, and diagnostics for target transforms. | +| Unknown structure | Article, unit, component, or attribute content that the parser preserves but cannot confidently classify. | +| RAG ingestion shape | Structured chunking and metadata contract for retrieval, citation, filtering, and generation workflows. | + +### 1.6 References + +- Primary parser SRS: [srs-Parser-Reader-SRS.md](srs-Parser-Reader-SRS.md). +- Parser implementation SRS: [imp-Parser-Reader-SRS.md](imp-Parser-Reader-SRS.md). +- Previous VS Code plugin SRS: [srs-VS-Code-Plugin.md](srs-VS-Code-Plugin.md). +- Structured Markdown model and schemas. +- DITA 1.3 topic categories: topic, concept, task/how-to, reference, troubleshooting, glossary, and glossentry. +- Robert Horn information mapping types: concept, procedure, principle, process, and fact. + +## 2. Overall Description + +### 2.1 Product Perspective + +The client system shall sit above the parser engine. The engine remains authoritative for parsing, model construction, schema validation, diagnostics, reference classification, transform-readiness evaluation, and contract serialization. + +The Electron and VS Code clients shall be peers over the same engine boundary: + +```mermaid +flowchart TD + Markdown[Markdown / Rendered HTML / Repository] --> Engine[Structured Markdown Parser Engine] + Engine --> Contract[Versioned JSON Contract] + Contract --> Electron[Electron Workbench] + Contract --> VSCode[VS Code Extension] + Contract --> CLI[CLI / CI / Scripts] + + Electron --> E1[Repository Assessment] + Electron --> E2[Structure Explorer] + Electron --> E3[Readiness Dashboards] + Electron --> E4[Reports and Exports] + + VSCode --> V1[Inline Diagnostics] + VSCode --> V2[Quick Fixes] + VSCode --> V3[Outline View] + VSCode --> V4[Authoring Feedback] +``` + +The Electron client shall emphasize repository-level review, assessment, migration planning, and batch reporting. The VS Code extension shall emphasize file-level authoring feedback while a writer is editing. + +### 2.2 Product Functions + +The shared client system shall provide: + +- Engine discovery and health checks. +- Contract version compatibility checks. +- File and repository validation through the parser engine. +- Structured model inspection. +- Diagnostic presentation. +- Transform-readiness presentation for DITA, Schema.org, XML, and RAG workflows. +- Metadata and taxonomy hook visibility. +- Unknown structure visibility. +- Report export. +- Debug views for engine requests and responses. +- Offline operation after installation. + +The Electron client shall additionally provide: + +- Repository open/import workflow. +- Batch parse and assessment runs. +- Inventory dashboards and filtering. +- File-to-file comparison across assessment runs. +- Aggregated unknown-unit and diagnostic views. +- DITA readiness and RAG readiness work queues. +- Reference and image review views. +- Exportable markdown, CSV, and JSON reports. +- Optional launch/open-in-editor integration. + +The VS Code extension shall additionally provide: + +- Inline diagnostics in the editor. +- Problems panel integration. +- Validate-on-save and optional validate-on-change. +- Structure outline for the current file. +- Code actions for safe quick fixes. +- Status bar validation state. +- Workspace scan command where practical. + +### 2.3 User Classes + +| User class | Primary client | Needs | +|---|---|---| +| Content architect | Electron | Repository-wide structure visibility, article triage, taxonomy hooks, readiness summaries, unknown-content reports. | +| Documentation engineer | Electron | Repeatable batch assessment, CSV/JSON exports, parser health, pipeline diagnostics, CI evidence. | +| Technical writer | VS Code and Electron | In-editor authoring feedback plus broader structure/readiness review. | +| Markdown author | VS Code | Fast diagnostics, clear messages, safe quick fixes, low-noise validation. | +| DITA migration specialist | Electron | DITA topic classification, strict/degraded readiness, unknown-unit work queues, export planning. | +| RAG pipeline owner | Electron | Chunkability, metadata, provenance, reference/image counts, quality filters. | +| Metadata owner | Electron and VS Code | Article and unit metadata visibility, missing taxonomy signals, profile-aware checks. | +| Support engineer | Electron | Debuggable parser output, raw request/response views, reproducible reports. | +| CI maintainer | CLI and Electron | Deterministic reports, stable exit behavior, evidence that batch outputs match expectations. | +| QA engineer | Electron and CLI | Fixture review, regression comparison, contract compatibility evidence. | + +### 2.4 Operating Environment + +The Electron client shall support: + +- macOS, Windows, and Linux desktop environments. +- Local repository folders. +- Local parser engine execution through CLI, managed Python, bundled engine, or long-running local service. +- Offline operation after installation. + +The VS Code extension shall support: + +- VS Code desktop on macOS, Windows, and Linux. +- Markdown files using VS Code language id `markdown`. +- Workspace Trust. +- Local validation without network access. +- Remote development environments when the parser engine is available in the extension host. + +### 2.5 Design and Implementation Constraints + +- CLIENT-REQ-001: Clients shall consume engine-owned contracts and shall not parse source content directly when the engine can provide the required data. +- CLIENT-REQ-002: Clients shall not import parser implementation modules for semantic decisions. +- CLIENT-REQ-003: Clients shall not read schema files as a substitute for engine output. +- CLIENT-REQ-004: Clients shall not infer undocumented domain meaning from incidental JSON fields. +- CLIENT-REQ-005: Clients shall reject or quarantine engine responses that fail contract validation. +- CLIENT-REQ-006: Clients shall distinguish engine errors from content authoring errors. +- CLIENT-REQ-007: Clients shall not send source content to external services by default. +- CLIENT-REQ-008: Clients shall not mutate source Markdown automatically without explicit user action. +- CLIENT-REQ-009: Clients shall show unknown structures as first-class model objects. +- CLIENT-REQ-010: Clients shall preserve the distinction between transform possibility and schema compliance. + +## 3. Engine Contract Boundary + +### 3.1 Contract Ownership + +The parser engine shall own all public request and response contracts. Clients may generate TypeScript or other client-side type mirrors from engine-provided JSON Schema, but those mirrors are compatibility aids, not independent sources of truth. + +Minimum contract families: + +- Engine health. +- Version and contract schema. +- Single-file validation. +- Repository or pipeline run. +- Structure inspection. +- Diagnostics inspection. +- Reference inspection. +- Transform readiness. +- RAG chunk-readiness or chunk-preview. +- Quick-fix hints where safe. +- Report export metadata. + +### 3.2 Minimum Engine Commands + +The clients should be able to call stable engine commands or equivalent service endpoints: + +```text +structure-parser --version --json +structure-parser contract-schema --json +structure-parser parse --json +structure-parser validate-markdown --profile --json +structure-parser inspect-structure --profile --json +structure-parser inspect-diagnostics --profile --json +structure-parser inspect-references --profile --json +structure-parser transform-readiness --profile --json +structure-parser pipe --out --report +``` + +The VS Code extension should additionally support stdin validation for unsaved buffers when the engine exposes it: + +```text +structure-parser validate-markdown --stdin --path --profile --json +``` + +### 3.3 Contract Data Requirements + +Client-facing responses shall include: + +- `contractVersion` +- `engineVersion` +- request status +- source path or logical URI +- parser configuration/profile summary +- diagnostics with stable codes, severities, messages, and ranges where available +- structured article/unit/component/attribute data +- validation state, including explicit `not_attempted` or `null` status where relevant +- transform-readiness state +- references and resolution states +- image references and image metadata where available +- triage status and unknown markers +- timing and performance metadata where available + +### 3.4 Contract Compatibility + +- CLIENT-REQ-011: Contract models shall be versioned independently from internal parser models. +- CLIENT-REQ-012: Patch contract changes may add optional fields only. +- CLIENT-REQ-013: Minor contract changes may add optional features, new diagnostic codes, or new enum values that older clients can ignore safely. +- CLIENT-REQ-014: Major contract changes may remove fields, rename fields, or change field semantics. +- CLIENT-REQ-015: Clients shall check engine contract compatibility before enabling validation features. +- CLIENT-REQ-016: Shared contract fixtures shall be used by the engine and clients. + +## 4. Electron Client Requirements + +### 4.1 Electron Client Purpose + +The Electron client shall be the first-class client for demonstrating and using Structured Markdown as a repository-level semantic layer. + +It shall make the parser useful beyond single-file authoring by supporting assessment, triage, migration planning, RAG-readiness review, report export, and parser debugging across folders of Markdown content. + +### 4.2 Electron Functional Requirements + +- ELEC-FR-001: The Electron client shall open a local content repository or folder. +- ELEC-FR-002: The Electron client shall discover Markdown files through the parser engine or pipeline contract. +- ELEC-FR-003: The Electron client shall run a repository assessment through the parser engine. +- ELEC-FR-004: The Electron client shall display a dashboard of parsed, failed, warning, and unknown-classification counts. +- ELEC-FR-005: The Electron client shall display article-type distribution. +- ELEC-FR-006: The Electron client shall display DITA, Schema.org, XML, and RAG readiness summaries. +- ELEC-FR-007: The Electron client shall display files in a sortable/filterable inventory table. +- ELEC-FR-008: The Electron client shall provide a structured model explorer for a selected file. +- ELEC-FR-009: The structured model explorer shall show article, units, components, attributes, metadata hooks, references, images, diagnostics, validation state, and readiness state. +- ELEC-FR-010: The Electron client shall show unknown units, components, and attributes as first-class review items. +- ELEC-FR-011: The Electron client shall provide work queues for DITA readiness issues, RAG readiness issues, unknown classifications, schema validation failures, unresolved references, and image issues. +- ELEC-FR-012: The Electron client shall compare assessment runs when two compatible result sets are available. +- ELEC-FR-013: The Electron client shall export markdown, CSV, and JSON reports. +- ELEC-FR-014: The Electron client shall support opening a selected source file in the user's configured editor. +- ELEC-FR-015: The Electron client shall expose raw engine request/response debug output in a dedicated debug view. +- ELEC-FR-016: The Electron client shall not edit source files in the MVP unless a future explicit authoring mode is approved. + +### 4.3 Electron Views + +The Electron MVP shall include: + +- Repository dashboard. +- File inventory. +- Structure explorer. +- Diagnostics panel. +- Transform-readiness panel. +- RAG-readiness panel. +- Reference and image panel. +- Assessment-run history. +- Report export panel. +- Engine health/debug panel. + +### 4.4 Electron Use Cases + +#### ELEC-UC-001 Assess Repository + +Primary actor: Content architect +Goal: Understand how a repository maps into Structured Markdown. + +Main flow: + +1. User opens a repository folder. +2. Electron discovers Markdown files or asks the engine pipeline to discover them. +3. User starts an assessment. +4. Engine parses files and returns parsed outputs, diagnostics, readiness, and inventory data. +5. Electron displays aggregate metrics and file-level results. +6. User filters by unknown units, article type, readiness status, or diagnostics. + +#### ELEC-UC-002 Plan DITA Migration + +Primary actor: DITA migration specialist +Goal: Identify which files can become DITA topics, concepts, tasks/how-tos, or references. + +Main flow: + +1. User selects the DITA readiness view. +2. Electron groups files by DITA readiness and article type. +3. Electron highlights degraded or blocked files. +4. User inspects unknown units, validation absence, validation failures, and article triage confidence. +5. User exports a migration-readiness report. + +#### ELEC-UC-003 Review RAG Suitability + +Primary actor: RAG pipeline owner +Goal: Identify which files can produce useful chunks and metadata. + +Main flow: + +1. User selects the RAG readiness view. +2. Electron shows chunkability, article/unit metadata, diagnostics, unknown-unit counts, source paths, references, and image counts. +3. User filters lower-confidence chunks or files. +4. User exports a RAG assessment report. + +#### ELEC-UC-004 Debug Parser Behavior + +Primary actor: Support engineer +Goal: Understand why the parser classified content in a particular way. + +Main flow: + +1. User selects a parsed file. +2. Electron displays structure, diagnostics, triage metadata, source spans, and raw engine output. +3. User identifies whether a problem is source content, schema validation, classifier uncertainty, missing reference resolution, or engine error. + +### 4.5 Electron Nonfunctional Requirements + +- ELEC-NFR-001: The Electron client shall remain responsive during repository assessment. +- ELEC-NFR-002: Long-running operations shall show progress, cancellation, and partial results where the engine supports them. +- ELEC-NFR-003: The Electron client shall not execute Markdown, embedded HTML, scripts, or fenced code blocks. +- ELEC-NFR-004: Source content shall not leave the local machine by default. +- ELEC-NFR-005: Telemetry, if ever added, shall be disabled by default and shall not include source content. +- ELEC-NFR-006: UI controls shall be keyboard accessible. +- ELEC-NFR-007: Diagnostic and readiness states shall not rely on color alone. +- ELEC-NFR-008: The application shall store recent repository paths and assessment metadata only with user consent or clear settings. + +## 5. VS Code Extension Requirements + +### 5.1 VS Code Client Purpose + +The VS Code extension shall be an additional client focused on authoring-time feedback inside the editor. + +It shall help Markdown authors repair and maintain content while preserving the rule that the engine owns parsing, validation, diagnostics, and readiness decisions. + +### 5.2 VS Code Functional Requirements + +- VSC-FR-001: The extension shall discover the parser engine through workspace setting, user setting, managed environment, or `PATH`. +- VSC-FR-002: The extension shall verify engine version and contract compatibility. +- VSC-FR-003: The extension shall validate the current Markdown file on explicit command. +- VSC-FR-004: The extension shall support validate-on-save. +- VSC-FR-005: The extension should support debounced validate-on-change when performance allows. +- VSC-FR-006: The extension shall map engine diagnostics to VS Code Problems and editor ranges. +- VSC-FR-007: The extension shall show a status bar item with active profile, validation state, and engine health. +- VSC-FR-008: The extension shall provide a structure outline for the active file. +- VSC-FR-009: The extension shall provide a transform-readiness view for the active file. +- VSC-FR-010: The extension shall show unknown structures as first-class outline and diagnostic items. +- VSC-FR-011: The extension should provide safe quick fixes when engine hints or local deterministic rules make the edit low-risk. +- VSC-FR-012: The extension should provide a workspace scan command where practical. +- VSC-FR-013: The extension shall provide an export validation report command. +- VSC-FR-014: The extension shall provide a check-engine command. + +### 5.3 VS Code Nonfunctional Requirements + +- VSC-NFR-001: The extension shall debounce live validation with a configurable interval. +- VSC-NFR-002: The extension shall cancel or ignore stale validation results. +- VSC-NFR-003: The extension should return feedback for typical files under 1 second after debounce when using a warm engine. +- VSC-NFR-004: The extension shall show a nonblocking status indicator when validation exceeds 3 seconds. +- VSC-NFR-005: The extension shall respect Workspace Trust. +- VSC-NFR-006: The extension shall pass engine arguments as structured process arguments, not shell strings. +- VSC-NFR-007: The extension shall not send source content to any external service by default. +- VSC-NFR-008: The extension shall not automatically edit documents without explicit user action. +- VSC-NFR-009: The extension UI shall support keyboard navigation and VS Code themes. + +### 5.4 VS Code Use Cases + +#### VSC-UC-001 Get Authoring Feedback + +Primary actor: Markdown author +Goal: See parser diagnostics while editing. + +Main flow: + +1. User opens or saves a Markdown file. +2. Extension sends file content or file path to the engine. +3. Engine returns diagnostics, structure, validation state, and readiness state. +4. Extension maps diagnostics to Problems, editor ranges, and status. +5. User revises the file. + +#### VSC-UC-002 Inspect Current File Structure + +Primary actor: Technical writer +Goal: Understand how the parser sees the current Markdown file. + +Main flow: + +1. User opens the Structure Outline. +2. Extension displays article, units, components, attributes, metadata hooks, and unknown structures. +3. User selects a node. +4. Editor reveals the source range where available. + +#### VSC-UC-003 Apply Safe Quick Fix + +Primary actor: Markdown author +Goal: Apply a deterministic repair. + +Main flow: + +1. User selects a diagnostic with a quick fix. +2. Extension shows safe or suggested actions. +3. User chooses an action. +4. Extension applies the edit through the VS Code workspace edit API. +5. Extension revalidates the document. + +## 6. Shared Architecture + +### 6.1 Layering Rules + +| Layer | Owns | Must not own | +|---|---|---| +| Electron client | Desktop workbench UI, repository dashboards, assessment views, local app state, report rendering, engine process lifecycle. | Parser semantics, schema validation, model classification, transform-readiness decisions. | +| VS Code extension | Editor UI, diagnostics presentation, code actions, status bar, outline, VS Code workspace integration. | Parser semantics, schema validation, model classification, transform-readiness decisions. | +| Contract boundary | Versioned JSON payloads generated from engine-owned Pydantic models. | UI-specific state, parser internals, business logic outside the contract. | +| Parser engine | Parsing, model construction, validation, diagnostics, readiness, references, quick-fix hints where safe, Pydantic validation, JSON serialization. | Electron UI, VS Code UI, editor state, desktop app state. | + +All client-to-engine and engine-to-client data shall cross the contract boundary. + +### 6.2 Logical Architecture + +```mermaid +flowchart TB + subgraph ClientLayer[Client Applications] + Electron[Electron Workbench] + VSCode[VS Code Extension] + CLI[CLI / CI] + end + + subgraph AdapterLayer[Engine Adapters] + CliAdapter[CLI Adapter] + ManagedAdapter[Managed Python Adapter] + ServerAdapter[Local Service / Language Server Adapter] + end + + subgraph Contract[Versioned Contract Boundary] + Requests[Pydantic-validated Requests] + Responses[Pydantic-validated Responses] + Schemas[Generated JSON Schema] + end + + subgraph EngineLayer[Parser Engine] + Parser[Parser Orchestrator] + Pipeline[Repository Pipeline] + Model[Structured Markdown Model] + Validation[Schema Validation] + Readiness[Transform Readiness] + Reports[Report Data] + end + + Electron --> CliAdapter + Electron --> ManagedAdapter + Electron --> ServerAdapter + VSCode --> CliAdapter + VSCode --> ServerAdapter + CLI --> Parser + CliAdapter --> Requests + ManagedAdapter --> Requests + ServerAdapter --> Requests + Requests --> Parser + Requests --> Pipeline + Parser --> Model + Parser --> Validation + Parser --> Readiness + Pipeline --> Parser + Validation --> Responses + Readiness --> Responses + Reports --> Responses + Responses --> Electron + Responses --> VSCode + Schemas --> Electron + Schemas --> VSCode +``` + +### 6.3 Adapter Strategy + +Both clients may use these engine integration modes: + +| Mode | Description | Best fit | +|---|---|---| +| CLI adapter | Invoke `structure-parser` commands and consume JSON output. | Alpha clients, CI-like operations, Electron batch workflows. | +| Managed Python adapter | Client manages or locates a Python environment containing the engine. | Beta clients and controlled installs. | +| Bundled engine | Client ships an engine runtime or packaged executable. | Production desktop distribution. | +| Local service / language server | Long-running parser service with cancellation and caching. | Production real-time editor feedback and large repository UX. | + +## 7. User Interface Requirements + +### 7.1 Electron UI + +The Electron client shall use dense, workbench-style views suitable for repeated assessment and review. + +Required high-level navigation: + +- Repository. +- Inventory. +- Structure. +- Diagnostics. +- Readiness. +- RAG. +- References and images. +- Reports. +- Settings. +- Engine health. + +The Electron client shall avoid marketing-style landing pages. The first useful screen after opening a repository shall be the actual repository assessment workspace. + +### 7.2 VS Code UI + +The VS Code extension shall use native VS Code surfaces: + +- Command Palette commands. +- Problems diagnostics. +- Editor squiggles and hover messages. +- Code actions. +- Status bar. +- Tree view for structure. +- Webview or custom panel for readiness and report detail. +- Output channel for engine logs. + +### 7.3 Shared Presentation Rules + +- CLIENT-REQ-017: Clients shall distinguish author action from content-architect action. +- CLIENT-REQ-018: Clients shall show validation absence distinctly from validation success. +- CLIENT-REQ-019: Clients shall show `unknown` as uncertainty, not as failure by itself. +- CLIENT-REQ-020: Clients shall distinguish `ready`, `degraded`, `blocked`, and `not_attempted` readiness states where the engine provides them. +- CLIENT-REQ-021: Clients shall show source provenance and ranges where available. +- CLIENT-REQ-022: Clients shall provide report exports that preserve engine diagnostic codes and readiness states. + +## 8. Packaging and Installation + +### 8.1 Electron Packaging + +The Electron client shall be packaged as a desktop application for macOS, Windows, and Linux. + +Packaging options: + +| Option | Description | Recommended phase | +|---|---|---| +| External engine | User installs parser engine separately. | Alpha | +| Managed engine | Electron creates or manages a Python environment. | Beta | +| Bundled engine | Electron bundles engine runtime and model schemas. | Production | +| Local service | Electron starts and manages a long-running engine service. | Production for larger repositories | + +### 8.2 VS Code Packaging + +The VS Code extension shall be packaged as a `.vsix` and may later be distributed through VS Code Marketplace, Open VSX, or internal enterprise channels. + +Packaging options: + +| Option | Description | Recommended phase | +|---|---|---| +| External engine | User configures `structure-parser` path or relies on `PATH`. | Alpha | +| Managed extension environment | Extension installs or locates parser engine. | Beta | +| Bundled engine or server | Extension bundles engine or starts a local language-server-style process. | Production | + +### 8.3 Shared Packaging Requirements + +- CLIENT-REQ-023: Clients shall report engine path, engine version, schema availability, and contract compatibility. +- CLIENT-REQ-024: Clients shall degrade gracefully when the engine is missing, too old, or incompatible. +- CLIENT-REQ-025: Clients shall support offline use after installation when the engine is available locally. +- CLIENT-REQ-026: Clients shall document installation, configuration, troubleshooting, and engine compatibility. + +## 9. Acceptance Criteria + +### 9.1 Shared MVP Acceptance Criteria + +- CLIENT-AC-001: Client can discover a configured parser engine. +- CLIENT-AC-002: Client can run an engine health check. +- CLIENT-AC-003: Client validates engine responses against the advertised contract. +- CLIENT-AC-004: Client can display diagnostics with code, severity, message, and source location where available. +- CLIENT-AC-005: Client can display article, unit, component, and attribute structure. +- CLIENT-AC-006: Client can display unknown structures. +- CLIENT-AC-007: Client can display transform-readiness state. +- CLIENT-AC-008: Client does not reimplement parser semantics. +- CLIENT-AC-009: Client can export a report containing engine version, diagnostics, readiness, and structure summary. + +### 9.2 Electron MVP Acceptance Criteria + +- ELEC-AC-001: Electron app opens a local repository folder. +- ELEC-AC-002: Electron app runs a repository assessment through the engine. +- ELEC-AC-003: Electron app shows a file inventory with parse status, diagnostics, article type, and readiness status. +- ELEC-AC-004: Electron app shows aggregate unknown-unit, diagnostic, article-type, reference, image, and readiness metrics. +- ELEC-AC-005: Electron app provides a file structure explorer. +- ELEC-AC-006: Electron app exports markdown and CSV assessment reports. +- ELEC-AC-007: Electron app handles missing or incompatible engines gracefully. + +### 9.3 VS Code MVP Acceptance Criteria + +- VSC-AC-001: VS Code extension activates for Markdown files. +- VSC-AC-002: VS Code extension validates the current file on explicit command. +- VSC-AC-003: Engine diagnostics appear in VS Code Problems. +- VSC-AC-004: Diagnostics with ranges appear as editor squiggles. +- VSC-AC-005: Extension shows active profile and validation state in the status bar. +- VSC-AC-006: Extension includes a check-engine command. +- VSC-AC-007: Extension does not import parser internals or read model schemas directly. + +### 9.4 Production Acceptance Criteria + +- CLIENT-AC-010: Engine schemas are packaged and available without a repository checkout. +- CLIENT-AC-011: Engine contract is versioned and covered by compatibility tests. +- CLIENT-AC-012: Electron, VS Code, and engine tests pass on macOS, Windows, and Linux. +- CLIENT-AC-013: Clients can run without network access after local installation. +- CLIENT-AC-014: Security review confirms source content does not leave the local machine by default. +- CLIENT-AC-015: Accessibility review confirms keyboard usability and non-color-only status communication. +- CLIENT-AC-016: Long-running operations provide progress and do not freeze the UI. + +## 10. Implementation Readiness + +The parser engine is close enough to support a narrow Electron MVP sooner than a full VS Code real-time authoring experience. + +Current strengths: + +- Markdown and rendered HTML parsing exist. +- Article, unit, component, and attribute contracts exist. +- Diagnostics and readiness concepts exist. +- Repository pipeline output exists. +- CSV inventory reporting exists. +- JSON output exists. + +Current blockers: + +- Extension-facing and client-facing contracts need to be stabilized. +- Validation absence must be represented honestly in readiness output. +- Schema resources must be available from installed packages. +- Article triage should be made more conservative and generic. +- RAG chunk quality metadata needs a stable contract. +- Quick-fix hints are not yet mature. +- Real-time validation likely needs a warm engine or local service. + +Implication: + +- Electron MVP should come first because it can work well with batch parser output and repository assessment latency. +- VS Code MVP should follow once single-file validation, diagnostic ranges, contract schemas, and engine health commands are stable. +- Production VS Code real-time feedback should wait for a persistent local service or language-server-style adapter. + +## 11. Implementation Plan + +### Phase 1: Shared Engine Contract Stabilization + +- Define client-facing Pydantic contracts for health, validation, structure, diagnostics, references, readiness, pipeline runs, quick-fix hints, and reports. +- Add `contract-schema --json`. +- Add contract fixture tests. +- Package model schemas as runtime resources. +- Make DITA readiness explicit when validation is not attempted. +- Add article triage evidence metadata. + +### Phase 2: Electron MVP + +- Scaffold Electron application. +- Add engine discovery and health check. +- Add open-repository workflow. +- Run `structure-parser pipe` or equivalent engine pipeline call. +- Display repository dashboard and file inventory. +- Display selected-file structure, diagnostics, references, images, and readiness. +- Export markdown and CSV reports. + +### Phase 3: Electron Assessment Workbench + +- Add assessment-run history. +- Add comparison between runs. +- Add DITA readiness queue. +- Add RAG readiness queue. +- Add unknown classification review queue. +- Add reference and image review. +- Add configurable profiles. + +### Phase 4: VS Code MVP + +- Scaffold VS Code extension. +- Add engine discovery and check-engine command. +- Add validate-current-file command. +- Map diagnostics to Problems and editor ranges. +- Add status bar state. +- Add structure outline. + +### Phase 5: VS Code Authoring Feedback + +- Add validate-on-save. +- Add debounced validate-on-change. +- Add stale-result cancellation. +- Add safe quick fixes. +- Add transform-readiness panel. +- Add workspace scan where practical. + +### Phase 6: Production Packaging + +- Add managed or bundled engine strategy. +- Add local service or language-server-style adapter. +- Add cross-platform packaging. +- Add security, accessibility, and offline installation tests. +- Prepare internal, marketplace, or enterprise distribution. + +## 12. Open Questions + +- Should the Electron MVP use generated parsed JSON files on disk, direct engine API calls, or both? +- Should the Electron app manage parser output directories, or treat them as explicit user-selected assessment artifacts? +- Should Electron include source editing, or should editing stay in external editors and VS Code? +- What report formats are required first: markdown, CSV, JSON, HTML, or all four? +- Should RAG chunk preview be part of the Electron MVP or beta? +- Should DITA XML export live inside the Electron client, the parser engine, or a separate transformer package? +- Should both clients use the same generated TypeScript contract package? +- What profile configuration file should be shared by CLI, Electron, and VS Code? +- Should the long-running engine be a formal Language Server Protocol implementation or a custom local JSON-RPC service? + +## 13. Traceability Matrix + +| Primary SRS concern | Electron client | VS Code extension | +|---|---|---| +| Parse source content | Repository assessment and file inventory | Validate current file | +| Preserve structure and provenance | Structure explorer and source spans | Structure outline and editor ranges | +| Classify references and metadata | References/images panel and metadata views | Current-file references and metadata outline | +| Expose diagnostics | Diagnostics dashboard and work queues | Problems panel and editor squiggles | +| Normalize outputs | Assessment artifacts and report exports | Engine contract responses | +| Downstream validation | Readiness dashboards and queues | Readiness panel for active file | +| DITA transform readiness | Migration-readiness view | Current-file readiness view | +| RAG ingestion shape | RAG readiness and chunk-quality views | Current-file RAG warnings | +| Dependency/reference analysis | Repository reference and image review | Current-file reference diagnostics | +| Reporting | Markdown, CSV, and JSON exports | Export validation report | +| Debugging | Engine health and raw response view | Output channel and debug command | +| CI and automation | Review of pipeline outputs | Workspace scan support | + +## 14. Summary Recommendation + +Build the clients as demonstrations and practical interfaces over the same engine-owned semantic layer. + +Make Electron the first-class client because it best matches the primary SRS use cases around repository assessment, content architecture, DITA migration planning, RAG readiness, reporting, and parser debugging. + +Keep the VS Code extension as an additional client focused on authoring-time feedback. It should reuse the same contract and should not become the place where parser semantics live. + +The strategic product shape is: + +```text +Structured Markdown specification + -> parser engine and semantic contract + -> Electron workbench + -> VS Code authoring client + -> CLI / CI / future clients +``` + +This keeps Structured Markdown useful as an agnostic semantic layer while giving different users the client experience that matches their work. diff --git a/design/srs-VS-Code-Plugin.md b/design/srs-VS-Code-Plugin.md deleted file mode 100644 index c80dd90..0000000 --- a/design/srs-VS-Code-Plugin.md +++ /dev/null @@ -1,1255 +0,0 @@ -# Software Requirements Specification: VS Code Structured Markdown Authoring Plugin - -Version: 0.1 -Date: 2026-06-26 -Status: Draft for implementation planning -Related specifications: -- [srs-Parser-Reader-SRS.md](srs-Parser-Reader-SRS.md) -- [imp-Parser-Reader-SRS.md](imp-Parser-Reader-SRS.md) -- [2026-06-26-feedback-update.md](2026-06-26-feedback-update.md) - -## 1. Introduction - -### 1.1 Purpose - -This Software Requirements Specification defines a secondary VS Code extension that uses the Structured Markdown Parser engine to provide real-time authoring feedback for Markdown content. The plugin shall help authors create, repair, and maintain Markdown that conforms to the project model: - -`article` contains `unit` contains `component` contains `attribute`. - -The plugin is intended to feel familiar to users of Markdown linters, XML authoring tools, and language-server-backed editor integrations. It shall surface model validation results directly in VS Code through diagnostics, editor squiggles, quick fixes, outline views, status indicators, and transform-readiness reports. - -### 1.2 Scope - -The VS Code plugin shall: - -- Validate Markdown files against the Structured Markdown model through the parser engine. -- Provide author-facing feedback while editing, on save, and on explicit command. -- Map parser diagnostics to VS Code Problems, inline ranges, status bar items, and optional side-panel reports. -- Help authors correct Markdown so it can be transformed into downstream formats such as DITA, Schema.org representations, and RAG ingestion shapes. -- Expose metadata and taxonomy hooks at article and unit levels without forcing metadata into every component or inline attribute. -- Provide packaging and installation paths for development, beta, and production use. - -The VS Code plugin shall not: - -- Replace the parser engine or duplicate its model validation logic. -- Provide a full WYSIWYG Markdown editor. -- Guarantee a lossless DITA migration by itself. -- Execute untrusted Markdown or embedded HTML as code. -- Require network access for validation. - -### 1.3 Audience - -This document is intended for: - -- Extension developers implementing the VS Code plugin. -- Parser engine maintainers stabilizing the engine interface. -- Content architects defining schema profiles and authoring rules. -- Technical writers and Markdown authors evaluating authoring workflows. -- Release engineers packaging the plugin and engine. - -### 1.4 Definitions - -| Term | Definition | -| --- | --- | -| Article | A single Markdown file or rendered HTML page represented as the root content object. | -| Unit | A logical chunk inside an article, often introduced by a heading or other sectioning construct. | -| Component | A block-level Markdown or HTML construct such as paragraph, list, table, block quote, code block, or heading. | -| Attribute | An inline construct such as emphasis, strong text, link, code span, or other span-level content. | -| Engine | The Structured Markdown Parser package that parses Markdown and rendered HTML into structured contracts and diagnostics. | -| Extension | The VS Code plugin described by this SRS. | -| Diagnostic | A structured finding reported to an author, such as an error, warning, hint, or informational message. | -| Profile | A named schema, rule set, or target transformation context used to validate content. | -| Transform readiness | An assessment of whether parsed content is ready for downstream DITA, Schema.org, or RAG ingestion transformation. | -| Quick fix | A VS Code code action that proposes a safe edit for a diagnostic. | -| Contract | The versioned request and response boundary between the VS Code extension and the parser engine. | -| Pydantic contract model | A Python Pydantic model in the parser engine package that validates engine inputs, outputs, diagnostics, structure summaries, quick-fix hints, and readiness reports. | - -### 1.5 References - -- IEEE 830 style SRS organization. -- VS Code Extension API for diagnostics, code actions, language features, webviews, tree views, configuration, and extension packaging. -- Structured Markdown Parser SRS. -- Structured Markdown model schemas. -- Production readiness assessment in `design/2026-06-26-feedback-update.md`. -- DITA 1.3 information types: topic, concept, task/how-to, reference, troubleshooting, glossary, and glossentry. -- Robert Horn information mapping types: concept, procedure, principle, process, and fact. - -## 2. Overall Description - -### 2.1 Product Perspective - -The extension shall be an editor integration for the existing parser engine. The extension is responsible for editor behavior, author experience, packaging, and presentation. The engine remains responsible for parsing, model interpretation, schema validation, diagnostics, and transform-readiness evaluation. - -The extension and parser engine shall be separate layers. The extension shall not import parser internals, load model schemas directly, run parser validation logic in TypeScript, or infer domain meaning from undocumented fields. The only supported boundary between the extension and the engine shall be a versioned contract serialized as JSON and validated by Pydantic models owned by the parser engine package. - -The engine layer shall own: - -- Markdown and HTML parsing. -- Article, unit, component, and attribute construction. -- JSON Schema validation. -- Diagnostic generation. -- Transform-readiness evaluation. -- Quick-fix hint generation where safe. -- Pydantic contract validation and serialization. - -The VS Code extension layer shall own: - -- VS Code activation, commands, views, and settings. -- Debounce, cancellation, and editor-session state. -- Process or server lifecycle management for the engine adapter. -- Mapping validated engine diagnostics to VS Code diagnostics. -- Mapping validated quick-fix hints to VS Code code actions. -- Rendering structure, readiness, and report views. - -The extension may integrate with the engine through one of three implementation modes: - -1. CLI adapter: invoke the installed `structure-parser` command and consume JSON output. -2. Managed Python adapter: run the parser package from a plugin-managed virtual environment. -3. Language server adapter: communicate with a long-running parser service using JSON-RPC or a compatible protocol. - -The preferred long-term architecture is a language-server-style adapter because it supports cancellation, caching, incremental validation, and responsive editor feedback. The preferred MVP architecture is a CLI adapter because it can be implemented with the current package shape once stable machine-readable command output is guaranteed. - -### 2.2 Product Functions - -The extension shall provide: - -- Real-time Markdown validation with debounce and stale-request cancellation. -- Diagnostics in VS Code Problems and editor ranges. -- Quick fixes for common structural and metadata issues. -- A structured outline showing article, units, components, and attributes. -- A transform-readiness view for DITA, Schema.org, and RAG ingestion targets. -- Model/profile selection at workspace and file scope. -- Metadata and taxonomy assistance for article and unit hooks. -- Engine discovery, health checks, and version compatibility checks. -- Exportable validation reports. -- Offline operation after installation. - -### 2.3 User Classes - -| User class | Needs | -| --- | --- | -| Markdown author | Immediate feedback, clear messages, quick fixes, low noise, safe edits. | -| Technical writer | Transform-readiness guidance, structural outline, content-type guidance, repeatable checks. | -| Content architect | Schema/profile configuration, taxonomy hooks, rule severity control, migration readiness. | -| DITA migration specialist | Evidence that Markdown maps cleanly to DITA topics, concepts, tasks/how-to, references, troubleshooting, and glossary entries. | -| RAG pipeline owner | Validation that content can produce explicit shapes with usable provenance, metadata, and chunk boundaries. | -| Extension administrator | Predictable installation, engine version control, workspace policy, offline packaging. | - -### 2.4 Operating Environment - -The extension shall support: - -- VS Code desktop on macOS, Windows, and Linux. -- VS Code compatible distributions where the required APIs are available. -- Markdown files using VS Code language id `markdown`. -- Workspaces that contain a Structured Markdown model, schema profile, or configuration file. -- Local validation without network access. - -The extension should support: - -- Remote development environments such as SSH, Dev Containers, and WSL when engine execution is available in the remote extension host. -- Multi-root workspaces with independent configuration per root. - -### 2.5 Design and Implementation Constraints - -- The parser engine shall remain the authoritative validator. -- The parser engine shall remain the owner of all domain contracts and Pydantic validation models. -- The extension shall consume machine-readable engine output rather than scraping human-readable text. -- The extension shall reject engine output that does not validate against the advertised contract version. -- The extension shall not mutate documents automatically without an explicit user action. -- The extension shall pass file paths and arguments safely, without shell interpolation. -- The extension shall respect VS Code Workspace Trust. -- The extension shall degrade gracefully when the engine is unavailable, too old, or returns invalid JSON. -- The extension shall avoid network access by default. - -### 2.6 Feasibility Assessment - -The plugin is feasible, but production readiness depends on hardening the parser package as a reusable engine. - -Current feasibility: - -| Target | Feasibility | Assessment | -| --- | ---: | --- | -| Manual validate command | 8/10 | Feasible with current CLI shape if stable JSON output and exit codes are maintained. | -| Validate on save | 7/10 | Feasible once schema reference and packaged model issues are fixed. | -| Real-time validation while typing | 5/10 | Feasible for small files, but current observed CLI latency around 10 seconds is too slow for keystroke feedback. Needs caching, debounce, cancellation, and ideally a long-running server. | -| Problems integration | 8/10 | Feasible if diagnostics include stable ranges, severities, codes, and messages. | -| Quick fixes | 6/10 | Feasible for narrow repairs. Requires diagnostic codes and safe edit recipes from engine or extension rules. | -| Transform-readiness panel | 7/10 | Feasible because the package already contains readiness concepts, but the report contract must be stable. | -| Production Marketplace release | 5/10 | Feasible after packaging, schema resource, lint, type checking, CI, and install smoke-test blockers are resolved. | - -Production blockers from the package readiness assessment that affect the plugin: - -- Schema `$ref` resolution must be fixed before the extension can trust validation results. -- The `model/` schemas must be packaged as runtime resources, not only found from a repository checkout. -- The CLI and Python API need stable JSON contracts for parse, validate, inspect, diagnostics, readiness, and version output. -- Engine execution needs predictable performance targets or a persistent server mode. -- Ruff, mypy, CI, and wheel installation smoke tests should be addressed before Marketplace release. - -Conclusion: an MVP VS Code extension is practical after the schema packaging and machine-readable CLI contracts are stabilized. A production real-time authoring tool is practical after engine startup cost, validation latency, cancellation, and installation workflows are improved. - -## 3. Specific Requirements - -### 3.1 Functional Requirements - -#### VSC-FR-001 Engine Discovery - -The extension shall discover the parser engine using the following precedence: - -1. Workspace setting `structuredMarkdown.engine.path`. -2. User setting `structuredMarkdown.engine.path`. -3. A managed extension environment if installed. -4. The `structure-parser` executable on `PATH`. - -The extension shall expose an `Structured Markdown: Check Engine` command that reports engine path, engine version, schema model path, supported contract version, and health status. - -#### VSC-FR-002 Version Compatibility - -The extension shall verify that the engine supports the minimum contract version required by the extension. If the engine is incompatible, the extension shall show a clear warning and disable validation actions that would produce unreliable results. - -#### VSC-FR-003 Validation Triggers - -The extension shall support validation on: - -- Document open. -- Document change after a configurable debounce interval. -- Document save. -- Explicit command. -- Workspace scan command. - -The extension shall allow users to disable live validation while keeping validate-on-save enabled. - -#### VSC-FR-004 Diagnostic Mapping - -The extension shall map engine diagnostics to VS Code diagnostics with: - -- File URI. -- Start and end range. -- Severity. -- Message. -- Diagnostic code. -- Source value `structured-markdown`. -- Optional related information. -- Optional target transform context. - -Diagnostics without precise ranges shall be attached to the nearest known article, unit, or component range. If no range is available, they shall be attached to the first line of the document and marked as document-level findings. - -#### VSC-FR-005 Diagnostic Severity - -The extension shall support these severity levels: - -| Engine severity | VS Code severity | -| --- | --- | -| error | Error | -| warning | Warning | -| info | Information | -| hint | Hint | - -The extension shall allow severity overrides by rule code in workspace settings. - -#### VSC-FR-006 Author-Facing Messages - -Each diagnostic shown to an author shall include: - -- What is wrong. -- Why it matters for the selected model or transform target. -- The smallest safe next action where known. - -The extension should avoid parser-internal terminology unless the selected user mode is `architect` or `debug`. - -#### VSC-FR-007 Quick Fixes - -The extension shall provide quick fixes for diagnostics that have deterministic, low-risk repairs. Initial quick fixes should include: - -- Insert missing required article metadata. -- Insert missing top-level heading. -- Normalize heading order when the safe edit is local. -- Add an empty metadata hook to an article or unit. -- Replace unsupported inline markup with a supported equivalent. -- Add table header separators when the intended table shape is clear. -- Convert known ambiguous constructs to explicit structured equivalents when the edit is local and reversible. - -The extension shall label speculative fixes as suggestions and shall not apply them automatically. - -#### VSC-FR-008 Structured Outline - -The extension shall provide a tree view showing: - -- Article root. -- Units. -- Components within each unit. -- Attributes within each component when expanded. -- Unknown units and unknown components. -- Metadata hooks at article and unit levels. -- Diagnostic counts by tree node. - -Selecting a tree item shall reveal the corresponding document range in the editor. - -#### VSC-FR-009 Transform Readiness View - -The extension shall provide a transform-readiness view for: - -- DITA topic, concept, how-to/task, reference, troubleshooting, glossary, and glossentry. -- Schema.org output shapes. -- RAG ingestion shapes with provenance, chunk boundaries, metadata, and taxonomy hooks. - -The view shall distinguish: - -- Ready. -- Needs author action. -- Needs content-architect decision. -- Unsupported by current model. -- Unknown because parsing failed. - -#### VSC-FR-010 Metadata and Taxonomy Assistance - -The extension shall identify article-level and unit-level metadata hooks and help authors inspect or add metadata values. The extension shall not require component-level or attribute-level metadata unless a selected profile explicitly allows it. - -#### VSC-FR-011 Profile Selection - -The extension shall support validation profiles. A profile may define: - -- Target information type. -- Required article metadata. -- Required unit metadata. -- Allowed unit types. -- Allowed component types and ordering constraints. -- Target transform readiness rules. -- Rule severity overrides. - -The active profile shall be visible in the status bar. - -#### VSC-FR-012 Unknown Structure Handling - -When the engine reports unknown units, components, or attributes, the extension shall show them as first-class model objects rather than hiding them. Unknown objects shall be eligible for diagnostics, outline display, and transform-readiness warnings. - -#### VSC-FR-013 Export Report - -The extension shall provide an `Structured Markdown: Export Validation Report` command that writes a JSON or Markdown report containing diagnostics, structure summary, active profile, engine version, and transform-readiness status. - -#### VSC-FR-014 Workspace Scan - -The extension should provide a workspace scan command that validates Markdown files in the current workspace and produces a summary by file. The command shall respect ignore patterns and workspace trust. - -#### VSC-FR-015 Debug View - -The extension should provide an optional debug view that displays raw engine request and response data for troubleshooting. - -#### VSC-FR-016 Layer Boundary Enforcement - -The extension shall communicate with the parser engine only through the documented engine adapter contract. The extension shall not: - -- Import Python parser modules directly into extension code. -- Read parser model schema files as a substitute for engine output. -- Reimplement article, unit, component, or attribute classification. -- Depend on undocumented JSON fields. -- Parse human-readable CLI output. - -The extension may use generated TypeScript types derived from the Pydantic contract schemas, but those types shall be treated as client-side mirrors of the engine-owned contract, not as an independent source of truth. - -#### VSC-FR-017 Pydantic Contract Enforcement - -The parser engine shall validate every request and response that crosses the extension boundary with Pydantic before data is accepted as contract-compliant. The engine shall: - -- Validate incoming validation, structure, readiness, and version requests. -- Validate outgoing diagnostics, structure summaries, readiness reports, quick-fix hints, and health responses. -- Emit a machine-readable contract error when validation fails. -- Include `contractVersion`, `engineVersion`, and response `status` in all extension-facing responses. -- Provide JSON Schema generated from the Pydantic models for extension-side type generation and compatibility tests. - -The extension shall treat Pydantic validation failures reported by the engine as engine contract errors, not content authoring errors. - -### 3.2 External Interface Requirements - -#### 3.2.1 VS Code UI Interfaces - -The extension shall contribute: - -- Commands: - - `Structured Markdown: Validate Current File` - - `Structured Markdown: Validate Workspace` - - `Structured Markdown: Show Structure Outline` - - `Structured Markdown: Show Transform Readiness` - - `Structured Markdown: Check Engine` - - `Structured Markdown: Select Profile` - - `Structured Markdown: Export Validation Report` -- Diagnostics collection for Markdown files. -- Code actions for supported diagnostic codes. -- Status bar item showing validation state and active profile. -- Tree view for structure outline. -- Webview or custom editor panel for transform-readiness and author guidance. -- Configuration settings under `structuredMarkdown`. - -#### 3.2.2 Engine Interface - -The extension shall call the engine through a stable request and response contract. This contract shall be defined by Pydantic models in the parser engine package and serialized as JSON for CLI, managed Python, and language-server transport modes. - -Minimum engine commands: - -```text -structure-parser --version --json -structure-parser validate-markdown --profile --json -structure-parser inspect-structure --profile --json -structure-parser transform-readiness --profile --json -``` - -The extension should support stdin validation for unsaved buffers: - -```text -structure-parser validate-markdown --stdin --path --profile --json -``` - -If stdin validation is unavailable, the extension shall validate unsaved buffers through a temporary file only when workspace trust allows it and the file is written in a secure temporary directory. - -The engine interface shall expose a contract schema command: - -```text -structure-parser contract-schema --json -``` - -The command shall return JSON Schema generated from the Pydantic contract models so the extension can verify compatibility and generate TypeScript types. - -#### 3.2.3 Configuration Interface - -The extension shall support these settings: - -```json -{ - "structuredMarkdown.engine.path": "", - "structuredMarkdown.engine.mode": "cli", - "structuredMarkdown.validation.enabled": true, - "structuredMarkdown.validation.onChange": true, - "structuredMarkdown.validation.onSave": true, - "structuredMarkdown.validation.debounceMs": 750, - "structuredMarkdown.validation.maxFileSizeKb": 512, - "structuredMarkdown.profile.default": "topic", - "structuredMarkdown.profile.path": "", - "structuredMarkdown.diagnostics.severityOverrides": {}, - "structuredMarkdown.reports.outputFormat": "markdown", - "structuredMarkdown.debug.rawEngineOutput": false -} -``` - -#### 3.2.4 File System Interface - -The extension shall read Markdown documents and optional workspace configuration files. It shall not write to source Markdown files except when the user explicitly applies a quick fix or command that edits the document. - -### 3.3 Data Requirements - -#### 3.3.1 Validation Request - -The extension shall send or derive a validation request that conforms to the engine-owned Pydantic request model: - -```json -{ - "contractVersion": "1.0", - "documentUri": "file:///workspace/docs/example.md", - "logicalPath": "docs/example.md", - "content": "# Example\n\nBody text.", - "profile": "topic", - "targets": ["dita", "schema.org", "rag"], - "includeStructure": true, - "includeReadiness": true -} -``` - -#### 3.3.2 Validation Response - -The engine response consumed by the extension shall be produced from the engine-owned Pydantic response model and shall include: - -```json -{ - "contractVersion": "1.0", - "engineVersion": "0.1.0", - "status": "completed", - "document": { - "uri": "file:///workspace/docs/example.md", - "articleType": "topic", - "range": { "startLine": 0, "startColumn": 0, "endLine": 10, "endColumn": 0 } - }, - "diagnostics": [], - "structure": {}, - "transformReadiness": {}, - "timingMs": 142 -} -``` - -The extension shall treat missing required fields, invalid field types, unknown contract versions, or failed Pydantic validation as an engine contract error and surface a single diagnostic or status message instead of showing partial, misleading validation results. - -#### 3.3.3 Code Action Contract - -Quick fixes may be supplied by the engine or derived by the extension. Each fix shall include: - -- Diagnostic code. -- Human-readable title. -- Edit range. -- Replacement text or structured edit. -- Safety level: `safe`, `suggested`, or `manual`. -- Optional explanation. - -#### 3.3.4 Pydantic Contract Model Set - -The parser engine shall define extension-facing Pydantic models for at least: - -- `EngineHealthRequest` -- `EngineHealthResponse` -- `ValidationRequest` -- `ValidationResponse` -- `StructureInspectionRequest` -- `StructureInspectionResponse` -- `TransformReadinessRequest` -- `TransformReadinessResponse` -- `DiagnosticContract` -- `RangeContract` -- `RelatedInformationContract` -- `QuickFixHintContract` -- `ContractErrorResponse` - -The contract models shall be versioned independently from internal parser implementation classes. Internal engine models may evolve, but extension-facing contract changes shall follow semantic compatibility rules: - -- Patch changes may add optional fields only. -- Minor changes may add optional features, new diagnostic codes, or new enum values when the extension can ignore them safely. -- Major changes may remove or rename fields, change required fields, or change semantics. - -The engine shall include a contract test suite that validates representative JSON fixtures against the Pydantic models. The extension shall include a compatibility test suite that validates the generated TypeScript contract mirrors against those fixtures. - -## 4. Use Cases - -### 4.1 Use Case Overview - -```mermaid -flowchart LR - Author[Markdown Author] - Architect[Content Architect] - Migration[DITA Migration Specialist] - RagOwner[RAG Pipeline Owner] - Admin[Extension Administrator] - - Plugin[VS Code Structured Markdown Plugin] - Engine[Structured Markdown Parser Engine] - - Author --> UC1[Get live feedback] - Author --> UC2[Apply quick fixes] - Author --> UC3[Inspect structure] - Architect --> UC4[Configure profiles] - Migration --> UC5[Assess DITA readiness] - RagOwner --> UC6[Assess RAG ingestion shape] - Admin --> UC7[Install and verify engine] - - UC1 --> Plugin - UC2 --> Plugin - UC3 --> Plugin - UC4 --> Plugin - UC5 --> Plugin - UC6 --> Plugin - UC7 --> Plugin - Plugin --> Engine -``` - -### 4.2 UC-001 Live Author Feedback - -Primary actor: Markdown author -Precondition: A Markdown file is open and validation is enabled. -Trigger: The author edits the document. -Main flow: - -1. The extension detects a document change. -2. The extension waits for the configured debounce interval. -3. The extension cancels any stale validation for the same document. -4. The extension sends the current content to the engine. -5. The engine returns diagnostics and structure data. -6. The extension maps findings to editor squiggles, Problems, and status bar state. -7. The author uses the feedback to repair the content. - -Postcondition: The author sees current validation status without leaving the editor. - -### 4.3 UC-002 Apply a Quick Fix - -Primary actor: Markdown author -Precondition: A diagnostic has a supported quick fix. -Trigger: The author invokes the VS Code code action menu. -Main flow: - -1. The extension lists available fixes for the selected diagnostic. -2. The author selects a fix. -3. The extension applies the edit through the VS Code workspace edit API. -4. The extension revalidates the changed document. - -Postcondition: The document reflects the selected edit and diagnostics are refreshed. - -### 4.4 UC-003 Inspect Structured Model - -Primary actor: Technical writer -Precondition: A Markdown file has been parsed. -Trigger: The writer opens the Structure Outline. -Main flow: - -1. The extension displays the article root. -2. The extension shows units, components, attributes, metadata hooks, and unknown structures. -3. The writer selects a node. -4. The editor reveals the corresponding source range. - -Postcondition: The writer can understand how the parser sees the document. - -### 4.5 UC-004 Check Migration Readiness - -Primary actor: DITA migration specialist -Precondition: A target profile is selected. -Trigger: The specialist opens Transform Readiness. -Main flow: - -1. The extension requests readiness analysis from the engine. -2. The extension groups results by DITA target type. -3. The extension distinguishes author fixes from architecture decisions. -4. The specialist exports a readiness report. - -Postcondition: The migration specialist has actionable evidence for transformation planning. - -### 4.6 UC-005 Validate RAG Ingestion Shape - -Primary actor: RAG pipeline owner -Precondition: A RAG profile is selected. -Trigger: The owner validates a file or workspace. -Main flow: - -1. The extension requests validation for provenance, chunking, metadata, and taxonomy hooks. -2. The engine reports whether content can form explicit ingestion shapes. -3. The extension displays blockers and warnings. - -Postcondition: The owner can identify content that will produce weak or ambiguous ingestion records. - -## 5. Architecture - -### 5.1 Layering Rules - -The system shall be organized into two primary layers and one explicit contract boundary: - -| Layer | Owns | Must not own | -| --- | --- | --- | -| VS Code plugin layer | Editor UI, commands, views, settings, diagnostics presentation, code-action presentation, report rendering, engine process lifecycle. | Parser domain logic, schema validation, model classification, transform-readiness decisions, Pydantic model definitions. | -| Contract boundary | Versioned JSON payloads generated from parser-owned Pydantic models. | Business logic, editor UI, parser internals. | -| Parser engine layer | Parsing, model construction, schema validation, diagnostics, transform-readiness, quick-fix hint generation, Pydantic validation, JSON serialization. | VS Code UI, editor state, VS Code-specific diagnostic objects. | - -All data crossing from the extension to the engine shall enter through the contract boundary. All data crossing from the engine to the extension shall leave through the same boundary. This rule applies equally to CLI, managed Python, and language-server transport modes. - -### 5.2 Logical Architecture - -```mermaid -flowchart TB - subgraph VSCode[VS Code] - Editor[Markdown Editor] - Problems[Problems Panel] - Status[Status Bar] - Tree[Structure Tree View] - Webview[Readiness and Guidance Webview] - Settings[Workspace and User Settings] - end - - subgraph Extension[Structured Markdown Extension Host] - Controller[Validation Controller] - Debounce[Debounce and Cancellation] - Adapter[Engine Adapter] - TypeMirror[Generated TypeScript Contract Mirrors] - Mapper[Diagnostic and Range Mapper] - Actions[Code Action Provider] - Cache[Result Cache] - Reporter[Report Exporter] - end - - subgraph Contract[Versioned JSON Contract Boundary] - Requests[Pydantic-validated Requests] - Responses[Pydantic-validated Responses] - SchemasJSON[Generated Contract JSON Schema] - end - - subgraph EngineLayer[Parser Engine Layer] - CLI[CLI Process Adapter] - Server[Optional Language Server Adapter] - Contracts[Pydantic Contract Models] - Parser[Structured Markdown Parser Engine] - Schemas[Packaged Model Schemas] - end - - Editor --> Controller - Settings --> Controller - Controller --> Debounce - Debounce --> Adapter - TypeMirror --> Adapter - Adapter --> Requests - Responses --> Cache - SchemasJSON --> TypeMirror - Requests --> CLI - Requests --> Server - CLI --> Parser - Server --> Parser - Contracts --> Responses - Contracts --> SchemasJSON - Parser --> Schemas - Parser --> Contracts - Cache --> Mapper - Mapper --> Problems - Mapper --> Status - Mapper --> Tree - Mapper --> Webview - Actions --> Editor - Cache --> Actions - Cache --> Reporter -``` - -### 5.3 Domain Class Diagram - -```mermaid -classDiagram - class ExtensionController { - +activate() - +validateDocument(uri) - +validateWorkspace() - +selectProfile() - +checkEngine() - } - - class DocumentSession { - +uri - +version - +profile - +state - +lastResult - } - - class EngineAdapter { - +mode - +validate(request) - +inspectStructure(request) - +transformReadiness(request) - +checkHealth() - } - - class ContractMirror { - +contractVersion - +validateClientShape(payload) - +decodeEngineResponse(payload) - } - - class PydanticContractModels { - +validateRequest(payload) - +serializeResponse(result) - +jsonSchema() - } - - class ValidationResult { - +contractVersion - +engineVersion - +diagnostics - +structure - +transformReadiness - +timingMs - } - - class DiagnosticMapper { - +toVsCodeDiagnostics(result) - +mapRange(modelRange) - +applySeverityOverrides() - } - - class CodeActionProvider { - +provideCodeActions(document, range, diagnostics) - +applyFix(fix) - } - - class StructureTreeProvider { - +refresh(result) - +reveal(node) - } - - class ReadinessPanel { - +render(result) - +exportReport() - } - - ExtensionController "1" --> "*" DocumentSession - ExtensionController "1" --> "1" EngineAdapter - EngineAdapter "1" --> "1" ContractMirror - EngineAdapter "1" --> "1" PydanticContractModels : JSON boundary - ExtensionController "1" --> "1" DiagnosticMapper - ExtensionController "1" --> "1" CodeActionProvider - ExtensionController "1" --> "1" StructureTreeProvider - ExtensionController "1" --> "1" ReadinessPanel - PydanticContractModels "1" --> "*" ValidationResult - DiagnosticMapper "1" --> "*" ValidationResult - CodeActionProvider "1" --> "*" ValidationResult -``` - -### 5.4 Live Validation Sequence - -```mermaid -sequenceDiagram - participant A as Author - participant E as VS Code Editor - participant C as Extension Controller - participant D as Debounce/Cancellation - participant R as Contract Request Mirror - participant P as Parser Engine - participant K as Pydantic Contracts - participant M as Diagnostic Mapper - participant V as VS Code UI - - A->>E: Edit Markdown - E->>C: onDidChangeTextDocument - C->>D: schedule validation - D-->>D: cancel stale request - D-->>D: wait debounce interval - D->>R: build contract request - R->>P: send JSON request - P->>K: validate request - K->>P: accepted request - P->>K: validate response - K-->>P: serialized response - P-->>R: validated JSON response - R-->>D: decoded contract response - D->>C: result for current document version - C->>M: map diagnostics and structure - M->>V: update Problems, squiggles, status, views - V-->>A: show actionable feedback -``` - -### 5.5 Document Validation State - -```mermaid -stateDiagram-v2 - [*] --> Idle - Idle --> Scheduled: document changed - Scheduled --> Validating: debounce elapsed - Scheduled --> Scheduled: document changed again - Validating --> Stale: newer document version exists - Stale --> Scheduled: reschedule - Validating --> Valid: no blocking diagnostics - Validating --> Invalid: errors or warnings returned - Validating --> EngineError: engine unavailable or invalid response - Valid --> Scheduled: document changed - Invalid --> Scheduled: document changed - EngineError --> Scheduled: retry requested - Valid --> [*]: document closed - Invalid --> [*]: document closed - EngineError --> [*]: document closed -``` - -## 6. UI Specification - -### 6.1 Primary Editor Feedback - -```mermaid -flowchart TB - subgraph Editor[Markdown Editor] - Text[Source text] - Squiggles[Inline squiggles] - Lightbulb[Quick-fix lightbulb] - Hover[Hover explanation] - end - - subgraph Panels[VS Code Panels] - Problems[Problems list] - Output[Structured Markdown output channel] - end - - subgraph Chrome[Editor Chrome] - Status[Status bar: profile, validation state, engine health] - end - - Text --> Squiggles - Squiggles --> Hover - Squiggles --> Lightbulb - Squiggles --> Problems - Status --> Output -``` - -### 6.2 Structure Outline View - -```mermaid -flowchart TB - Outline[Structure Outline] - Article[Article: topic] - Metadata[Article metadata hooks] - Unit1[Unit: concept] - Unit2[Unit: procedure] - Unknown[Unknown component] - Para[Component: paragraph] - List[Component: ordered list] - Link[Attribute: link] - Emph[Attribute: emphasis] - - Outline --> Article - Article --> Metadata - Article --> Unit1 - Article --> Unit2 - Unit1 --> Para - Unit1 --> Unknown - Unit2 --> List - Para --> Link - Para --> Emph -``` - -### 6.3 Transform Readiness Panel - -```mermaid -flowchart LR - subgraph Panel[Transform Readiness] - Summary[Overall status] - Dita[DITA readiness] - SchemaOrg[Schema.org readiness] - Rag[RAG readiness] - Actions[Recommended author actions] - Export[Export report] - end - - Summary --> Dita - Summary --> SchemaOrg - Summary --> Rag - Dita --> Actions - SchemaOrg --> Actions - Rag --> Actions - Actions --> Export -``` - -### 6.4 Quick Fix Flow - -```mermaid -flowchart TD - Diagnostic[Diagnostic shown in editor] - Menu[Code action menu] - Fix[Safe quick fix] - Suggestion[Suggested manual fix] - Edit[Workspace edit] - Revalidate[Revalidate document] - Updated[Updated diagnostics] - - Diagnostic --> Menu - Menu --> Fix - Menu --> Suggestion - Fix --> Edit - Suggestion --> Edit - Edit --> Revalidate - Revalidate --> Updated -``` - -## 7. Nonfunctional Requirements - -### 7.1 Performance - -- VSC-NFR-001: The extension shall debounce live validation, with a default interval of 750 ms. -- VSC-NFR-002: The extension shall cancel or ignore stale validation results. -- VSC-NFR-003: The extension should return feedback for typical files under 1 second after debounce when using a warm engine. -- VSC-NFR-004: The extension shall show a nonblocking status indicator when validation exceeds 3 seconds. -- VSC-NFR-005: The extension shall skip live validation for files larger than the configured maximum and offer manual validation instead. - -### 7.2 Reliability - -- VSC-NFR-006: The extension shall continue operating if one validation request fails. -- VSC-NFR-007: The extension shall not clear old diagnostics until a newer valid result or explicit engine error state is available. -- VSC-NFR-008: The extension shall log engine errors to an output channel with enough detail for troubleshooting. - -### 7.3 Usability - -- VSC-NFR-009: Diagnostics shall be written in author-facing language. -- VSC-NFR-010: The extension shall distinguish author action from content-architect action. -- VSC-NFR-011: The extension shall support a quiet mode that reports only errors. -- VSC-NFR-012: The extension shall keep common actions available through the Command Palette. - -### 7.4 Security and Privacy - -- VSC-NFR-013: The extension shall not send document content to any external service by default. -- VSC-NFR-014: The extension shall not execute Markdown, embedded HTML, scripts, or fenced code blocks. -- VSC-NFR-015: The extension shall pass engine arguments as structured process arguments, not shell strings. -- VSC-NFR-016: The extension shall respect VS Code Workspace Trust before running workspace-local engine paths. -- VSC-NFR-017: Telemetry, if ever added, shall be disabled by default and shall not include source content. - -### 7.5 Accessibility - -- VSC-NFR-018: All extension UI shall be accessible through keyboard navigation. -- VSC-NFR-019: Webview content shall use semantic HTML and support VS Code themes. -- VSC-NFR-020: Diagnostic information shall not rely on color alone. - -### 7.6 Maintainability - -- VSC-NFR-021: Extension logic shall be separated into controller, engine adapter, diagnostic mapper, code action provider, tree provider, and report rendering modules. -- VSC-NFR-022: Engine contract types shall be generated or centrally defined to prevent drift. -- VSC-NFR-023: The extension shall include unit tests for diagnostic mapping and code actions. -- VSC-NFR-024: The extension shall include integration tests for command activation and sample Markdown validation. - -## 8. Packaging and Installation - -### 8.1 Extension Package - -The VS Code extension shall be packaged as a `.vsix` using the VS Code extension packaging toolchain, typically `@vscode/vsce`. The extension package shall include: - -- `package.json` with activation events, commands, views, configuration, and extension metadata. -- Compiled TypeScript extension code. -- Webview assets where used. -- Default icons and UI resources. -- README, changelog, license, and troubleshooting guide. -- Optional bundled engine bootstrap scripts. - -The extension shall be installable by: - -- VS Code Marketplace. -- Open VSX Registry, if desired. -- Manual `.vsix` installation. -- Internal enterprise extension distribution. - -### 8.2 Engine Packaging Options - -#### Option A: External Engine Dependency - -The extension requires users to install the Python package separately and configure the engine path or rely on `PATH`. - -Advantages: - -- Small extension package. -- Simple development workflow. -- Clear separation between extension and engine release cycles. - -Disadvantages: - -- Higher setup burden. -- More support cases from missing Python, wrong virtual environment, or incompatible engine versions. -- Harder offline installation. - -Recommended for: first MVP and internal alpha. - -#### Option B: Managed Extension Environment - -The extension creates or uses a managed Python environment and installs the parser engine wheel into it. - -Advantages: - -- Better author experience. -- Extension can control engine version. -- More predictable validation behavior. - -Disadvantages: - -- Requires Python availability or bundling strategy. -- More complex updates and troubleshooting. -- Network access may be needed unless wheels are bundled. - -Recommended for: beta. - -#### Option C: Bundled Engine - -The extension bundles the engine and model schemas, either as a packaged Python environment, native executable, or platform-specific artifact. - -Advantages: - -- Best end-user installation experience. -- Works offline after `.vsix` installation. -- Strong version compatibility. - -Disadvantages: - -- Larger extension package. -- Platform-specific release complexity. -- More release engineering work. - -Recommended for: production if enterprise or nontechnical author adoption is a priority. - -#### Option D: Language Server Package - -The parser engine is exposed through a long-running language server that the extension starts and manages. - -Advantages: - -- Best fit for real-time validation. -- Supports cancellation, caching, incremental parsing, and richer editor features. -- Aligns with familiar editor tooling architecture. - -Disadvantages: - -- Requires additional server protocol design and tests. -- More complex than CLI invocation. - -Recommended for: production real-time authoring. - -### 8.3 Recommended Packaging Path - -The recommended release path is: - -1. Alpha: CLI adapter with external engine dependency and explicit engine path setting. -2. Beta: managed Python environment with engine install and health check commands. -3. Production: language-server-style engine adapter with packaged schemas, stable contract versioning, and optional bundled wheels or server artifacts. - -### 8.4 Installation Flow - -```mermaid -flowchart TD - Install[Install VS Code extension] - Activate[Open Markdown file] - Discover[Discover parser engine] - Found{Engine found?} - Version{Compatible version?} - Ready[Enable validation] - Missing[Show install/configure engine action] - Incompatible[Show upgrade/downgrade action] - Validate[Run health check] - - Install --> Activate - Activate --> Discover - Discover --> Found - Found -- yes --> Version - Found -- no --> Missing - Version -- yes --> Validate - Version -- no --> Incompatible - Validate --> Ready -``` - -## 9. Acceptance Criteria - -### 9.1 MVP Acceptance Criteria - -- VSC-AC-001: Installing the extension activates it for Markdown files. -- VSC-AC-002: The extension can discover a configured `structure-parser` executable. -- VSC-AC-003: The `Check Engine` command reports engine path, version, and health state. -- VSC-AC-004: The extension validates the current Markdown file on explicit command. -- VSC-AC-005: Engine diagnostics appear in VS Code Problems with correct severity and source. -- VSC-AC-006: Diagnostics with ranges are shown as editor squiggles. -- VSC-AC-007: The extension validates on save when enabled. -- VSC-AC-008: The extension shows a status bar item with active profile and validation state. -- VSC-AC-009: The extension handles missing or incompatible engines gracefully. -- VSC-AC-010: The extension includes documentation for installation, configuration, and troubleshooting. -- VSC-AC-011: Engine responses consumed by the extension validate against the parser-owned Pydantic contract models. -- VSC-AC-012: The extension does not import parser internals or read model schema files directly. - -### 9.2 Beta Acceptance Criteria - -- VSC-AC-013: Live validation works with debounce and stale-result cancellation. -- VSC-AC-014: The Structure Outline shows article, units, components, attributes, metadata hooks, and unknown structures. -- VSC-AC-015: At least five common diagnostics provide quick fixes. -- VSC-AC-016: Transform-readiness view reports DITA, Schema.org, and RAG readiness. -- VSC-AC-017: Workspace validation produces a summary report. -- VSC-AC-018: The extension supports profile selection and severity overrides. -- VSC-AC-019: Generated TypeScript contract mirrors are produced from Pydantic JSON Schema and covered by compatibility fixtures. - -### 9.3 Production Acceptance Criteria - -- VSC-AC-020: The extension and engine pass CI on macOS, Windows, and Linux. -- VSC-AC-021: The parser model schemas are available from an installed package without requiring a repository checkout. -- VSC-AC-022: The engine contract is versioned and covered by compatibility tests. -- VSC-AC-023: Typical warm validation completes within the configured real-time target. -- VSC-AC-024: The extension is packaged as `.vsix` and can be installed offline. -- VSC-AC-025: Marketplace or internal distribution documentation is complete. -- VSC-AC-026: Security review confirms no source content leaves the local machine by default. -- VSC-AC-027: Accessibility review confirms keyboard and screen-reader usability for extension views. -- VSC-AC-028: A layered architecture test or static check prevents the extension package from importing parser implementation modules directly. - -## 10. Implementation Readiness Assessment - -### 10.1 Current Readiness - -The VS Code plugin can be planned now, but implementation should begin with a narrow CLI-backed MVP. The parser package already has the right conceptual foundation: - -- Article, unit, component, and attribute contracts. -- JSON Schema model files. -- Diagnostics concepts. -- Transform-readiness concepts. -- CLI entry points that can be adapted for editor use. - -However, production plugin work should not assume the engine is ready as an installable editor dependency until the package readiness blockers are fixed. - -### 10.2 Required Engine Capabilities Before MVP - -The parser engine should provide: - -- Stable JSON output for validation and inspection commands. -- Pydantic request and response models for every extension-facing command. -- Generated JSON Schema for the extension-facing contract models. -- Stable diagnostic range format using zero-based line and column values. -- Stable severity and diagnostic code taxonomy. -- Reliable schema reference resolution. -- Packaged model schema resources. -- `--version --json` or equivalent health output. -- Exit codes that distinguish validation failure from engine failure. - -### 10.3 Required Engine Capabilities Before Production - -The parser engine should provide: - -- Fast warm validation. -- Optional stdin validation for unsaved buffers. -- Persistent server mode or language server mode. -- Cancellation support. -- Contract versioning and backward compatibility policy. -- Contract fixture tests shared by the parser engine and extension. -- Generated TypeScript type mirrors derived from Pydantic JSON Schema. -- Machine-readable quick-fix hints where possible. -- Install smoke tests for wheels and extension-managed environments. - -## 11. Implementation Plan Summary - -### Phase 1: Engine Contract Stabilization - -- Define JSON contracts for version, validation, structure, diagnostics, readiness, and quick-fix hints. -- Implement the extension-facing contracts as Pydantic models in the parser engine layer. -- Generate JSON Schema from the Pydantic models for extension compatibility tests. -- Fix schema `$ref` resolution. -- Package model schemas with the Python distribution. -- Add contract tests and CLI smoke tests. - -### Phase 2: VS Code MVP - -- Scaffold a TypeScript VS Code extension. -- Add engine discovery and health check. -- Add explicit validate command. -- Map diagnostics into Problems and editor ranges. -- Add status bar state. -- Document local development installation. - -### Phase 3: Authoring Feedback - -- Add validate-on-save and debounced validate-on-change. -- Add stale-result cancellation. -- Add initial quick fixes. -- Add Structure Outline tree. -- Add profile selection and severity overrides. - -### Phase 4: Readiness and Migration Views - -- Add transform-readiness panel. -- Add DITA, Schema.org, and RAG grouping. -- Add export report command. -- Add workspace validation. - -### Phase 5: Production Packaging - -- Add managed engine install or language server integration. -- Add extension tests. -- Add CI for extension and engine compatibility. -- Package `.vsix`. -- Prepare Marketplace, Open VSX, or internal distribution. - -## 12. Open Questions - -- Should the first extension use an external CLI dependency only, or should it immediately manage a Python environment? -- Should the production engine adapter be a custom server or a formal Language Server Protocol implementation? -- Which diagnostic codes should be eligible for automatic quick fixes in the first beta? -- Where should schema profiles live: repository root, `.vscode`, `model/`, or a project configuration file? -- Should transform-readiness be computed on every validation or only on demand? -- Should taxonomy metadata be edited through front matter, sidecar files, or inline structured blocks? -- What minimum VS Code version should be supported? -- Should the extension target VS Code Marketplace, Open VSX, or internal distribution first? - -## 13. Traceability Matrix - -| Parser SRS concern | VS Code plugin requirement | -| --- | --- | -| Parse source content | VSC-FR-003, VSC-FR-004 | -| Preserve structure and provenance | VSC-FR-008, VSC-FR-009 | -| Classify references and metadata | VSC-FR-010, VSC-FR-011 | -| Expose diagnostics | VSC-FR-004, VSC-FR-005, VSC-FR-006 | -| Normalized outputs | VSC-FR-013, 3.3 Data Requirements | -| Downstream validation | VSC-FR-009, VSC-FR-014 | -| Dependency analysis | VSC-FR-008, VSC-FR-013 | -| Reporting | VSC-FR-013, VSC-AC-017 | -| Debugging | VSC-FR-015, VSC-NFR-008 | -| Automation | Engine contract requirements and Phase 5 packaging | - -## 14. Summary Recommendation - -Build the VS Code plugin in stages. Start with a CLI-backed validation MVP after the parser engine has stable JSON output, packaged schemas, and reliable schema references. Treat real-time authoring feedback as a beta feature until validation latency is low enough for editor use. For production, move toward a persistent language-server-style adapter so the extension can provide the responsiveness authors expect from Markdown linters and XML authoring tools.