From 09e5d093affc7eb9d687c1394c8296d846370ce4 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Mon, 24 Aug 2026 08:50:43 +0100 Subject: [PATCH] refactor: migrate repository documentation from Markdown to AsciiDoc --- ABI-FFI-README.md => ABI-FFI-README.adoc | 244 +++++---- ARCHITECTURE.adoc | 48 ++ ARCHITECTURE.md | 47 -- CHANGELOG.adoc | 285 +++++----- CHANGELOG.md | 156 ------ CODE_OF_CONDUCT.adoc | 167 ++++++ CODE_OF_CONDUCT.md | 112 ---- CONTRIBUTING.adoc | 443 ++++++++++++++++ CONTRIBUTING.md | 421 --------------- GOVERNANCE.adoc | 60 +++ GOVERNANCE.md | 60 --- MAINTAINERS.adoc | 177 +++++-- MAINTAINERS.md | 156 ------ PROOF-NEEDS.adoc | 12 + PROOF-NEEDS.md | 14 - RSR_COMPLIANCE.adoc | 640 +++++++++++++++++++++++ RSR_COMPLIANCE.md | 560 -------------------- SECURITY.adoc | 140 +++++ SECURITY.md | 144 ----- TEST-NEEDS.adoc | 223 ++++++++ TEST-NEEDS.md | 276 ---------- TOPOLOGY.md => TOPOLOGY.adoc | 42 +- docs/{API.md => API.adoc} | 402 ++++++++------ docs/tech-debt-2026-05-26.adoc | 67 +++ docs/tech-debt-2026-05-26.md | 54 -- examples/conversions/example.adoc | 48 ++ examples/conversions/example.md | 49 -- llm-warmup-dev.adoc | 19 + llm-warmup-dev.md | 20 - llm-warmup-user.adoc | 19 + llm-warmup-user.md | 20 - 31 files changed, 2556 insertions(+), 2569 deletions(-) rename ABI-FFI-README.md => ABI-FFI-README.adoc (74%) create mode 100644 ARCHITECTURE.adoc delete mode 100644 ARCHITECTURE.md delete mode 100644 CHANGELOG.md create mode 100644 CODE_OF_CONDUCT.adoc delete mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.adoc delete mode 100644 CONTRIBUTING.md create mode 100644 GOVERNANCE.adoc delete mode 100644 GOVERNANCE.md delete mode 100644 MAINTAINERS.md create mode 100644 PROOF-NEEDS.adoc delete mode 100644 PROOF-NEEDS.md create mode 100644 RSR_COMPLIANCE.adoc delete mode 100644 RSR_COMPLIANCE.md create mode 100644 SECURITY.adoc delete mode 100644 SECURITY.md create mode 100644 TEST-NEEDS.adoc delete mode 100644 TEST-NEEDS.md rename TOPOLOGY.md => TOPOLOGY.adoc (87%) rename docs/{API.md => API.adoc} (56%) create mode 100644 docs/tech-debt-2026-05-26.adoc delete mode 100644 docs/tech-debt-2026-05-26.md create mode 100644 examples/conversions/example.adoc delete mode 100644 examples/conversions/example.md create mode 100644 llm-warmup-dev.adoc delete mode 100644 llm-warmup-dev.md create mode 100644 llm-warmup-user.adoc delete mode 100644 llm-warmup-user.md diff --git a/ABI-FFI-README.md b/ABI-FFI-README.adoc similarity index 74% rename from ABI-FFI-README.md rename to ABI-FFI-README.adoc index ada05ff..f1163e3 100644 --- a/ABI-FFI-README.md +++ b/ABI-FFI-README.adoc @@ -1,23 +1,22 @@ - -{{~ Aditionally delete this line and fill out the template below ~}} +\{\{~ Aditionally delete this line and fill out the template below ~}} -# {{PROJECT}} ABI/FFI Documentation +== \{\{PROJECT}} ABI/FFI Documentation -## Overview +=== Overview -This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: +This library follows the *Hyperpolymath RSR Standard* for ABI and FFI +design: -- **ABI (Application Binary Interface)** defined in **Idris2** with formal proofs -- **FFI (Foreign Function Interface)** implemented in **Zig** for C compatibility -- **Generated C headers** bridge Idris2 ABI to Zig FFI -- **Any language** can call through standard C ABI +* *ABI (Application Binary Interface)* defined in *Idris2* with formal +proofs +* *FFI (Foreign Function Interface)* implemented in *Zig* for C +compatibility +* *Generated C headers* bridge Idris2 ABI to Zig FFI +* *Any language* can call through standard C ABI -## Architecture +=== Architecture -``` +.... ┌─────────────────────────────────────────────┐ │ ABI Definitions (Idris2) │ │ src/abi/ │ @@ -49,11 +48,11 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: │ Any Language via C ABI │ │ - Rust, ReScript, Julia, Python, etc. │ └─────────────────────────────────────────────┘ -``` +.... -## Directory Structure +=== Directory Structure -``` +.... {{project}}/ ├── src/ │ ├── abi/ # ABI definitions (Idris2) @@ -81,15 +80,17 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: ├── rust/ ├── rescript/ └── julia/ -``` +.... -## Why Idris2 for ABI? +=== Why Idris2 for ABI? -### 1. **Formal Verification** +==== 1. *Formal Verification* -Idris2's dependent types allow proving properties about the ABI at compile-time: +Idris2’s dependent types allow proving properties about the ABI at +compile-time: -```idris +[source,idris] +---- -- Prove struct size is correct public export exampleStructSize : HasSize ExampleStruct 16 @@ -101,13 +102,14 @@ fieldAligned : Divides 8 (offsetOf ExampleStruct.field) -- Prove ABI is platform-compatible public export abiCompatible : Compatible (ABI 1) (ABI 2) -``` +---- -### 2. **Type Safety** +==== 2. *Type Safety* Encode invariants that C/Zig cannot express: -```idris +[source,idris] +---- -- Non-null pointer guaranteed at type level data Handle : Type where MkHandle : (ptr : Bits64) -> {auto 0 nonNull : So (ptr /= 0)} -> Handle @@ -115,13 +117,14 @@ data Handle : Type where -- Array with length proof data Buffer : (n : Nat) -> Type where MkBuffer : Vect n Byte -> Buffer n -``` +---- -### 3. **Platform Abstraction** +==== 3. *Platform Abstraction* Platform-specific types with compile-time selection: -```idris +[source,idris] +---- CInt : Platform -> Type CInt Linux = Bits32 CInt Windows = Bits32 @@ -129,13 +132,14 @@ CInt Windows = Bits32 CSize : Platform -> Type CSize Linux = Bits64 CSize Windows = Bits64 -``` +---- -### 4. **Safe Evolution** +==== 4. *Safe Evolution* Prove that new ABI versions are backward-compatible: -```idris +[source,idris] +---- -- Compiler enforces compatibility abiUpgrade : ABI 1 -> ABI 2 abiUpgrade old = MkABI2 { @@ -144,71 +148,78 @@ abiUpgrade old = MkABI2 { -- Can add new fields new_features = defaults } -``` +---- -## Why Zig for FFI? +=== Why Zig for FFI? -### 1. **C ABI Compatibility** +==== 1. *C ABI Compatibility* Zig exports C-compatible functions naturally: -```zig +[source,zig] +---- export fn library_function(param: i32) i32 { return param * 2; } -``` +---- -### 2. **Memory Safety** +==== 2. *Memory Safety* Compile-time safety without runtime overhead: -```zig +[source,zig] +---- // Null check enforced at compile time const handle = init() orelse return error.InitFailed; defer free(handle); -``` +---- -### 3. **Cross-Compilation** +==== 3. *Cross-Compilation* Built-in cross-compilation to any platform: -```bash +[source,bash] +---- zig build -Dtarget=x86_64-linux zig build -Dtarget=aarch64-macos zig build -Dtarget=x86_64-windows -``` +---- -### 4. **Zero Dependencies** +==== 4. *Zero Dependencies* No runtime, no libc required (unless explicitly needed): -```zig +[source,zig] +---- // Minimal binary size pub const lib = @import("std"); // Only includes what you use -``` +---- -## Building +=== Building -### Build FFI Library +==== Build FFI Library -```bash +[source,bash] +---- cd ffi/zig zig build # Build debug zig build -Doptimize=ReleaseFast # Build optimized zig build test # Run tests -``` +---- -### Generate C Header from Idris2 ABI +==== Generate C Header from Idris2 ABI -```bash +[source,bash] +---- cd src/abi idris2 --cg c-header Types.idr -o ../../generated/abi/{{project}}.h -``` +---- -### Cross-Compile +==== Cross-Compile -```bash +[source,bash] +---- cd ffi/zig # Linux x86_64 @@ -219,13 +230,14 @@ zig build -Dtarget=aarch64-macos # Windows x86_64 zig build -Dtarget=x86_64-windows -``` +---- -## Usage +=== Usage -### From C +==== From C -```c +[source,c] +---- #include "{{project}}.h" int main() { @@ -241,16 +253,19 @@ int main() { {{project}}_free(handle); return 0; } -``` +---- Compile with: -```bash + +[source,bash] +---- gcc -o example example.c -l{{project}} -L./zig-out/lib -``` +---- -### From Idris2 +==== From Idris2 -```idris +[source,idris] +---- import {{PROJECT}}.ABI.Foreign main : IO () @@ -263,11 +278,12 @@ main = do free handle putStrLn "Success" -``` +---- -### From Rust +==== From Rust -```rust +[source,rust] +---- #[link(name = "{{project}}")] extern "C" { fn {{project}}_init() -> *mut std::ffi::c_void; @@ -286,11 +302,12 @@ fn main() { {{project}}_free(handle); } } -``` +---- -### From Julia +==== From Julia -```julia +[source,julia] +---- const lib{{project}} = "lib{{project}}" function init() @@ -316,27 +333,30 @@ try finally cleanup(handle) end -``` +---- -## Testing +=== Testing -### Unit Tests (Zig) +==== Unit Tests (Zig) -```bash +[source,bash] +---- cd ffi/zig zig build test -``` +---- -### Integration Tests +==== Integration Tests -```bash +[source,bash] +---- cd ffi/zig zig build test-integration -``` +---- -### ABI Verification (Idris2) +==== ABI Verification (Idris2) -```idris +[source,idris] +---- -- Compile-time verification %runElab verifyABI @@ -346,44 +366,44 @@ main = do verifyLayoutsCorrect verifyAlignmentsCorrect putStrLn "ABI verification passed" -``` +---- -## Contributing +=== Contributing When modifying the ABI/FFI: -1. **Update ABI first** (`src/abi/*.idr`) - - Modify type definitions - - Update proofs - - Ensure backward compatibility - -2. **Generate C header** - ```bash - idris2 --cg c-header src/abi/Types.idr -o generated/abi/{{project}}.h - ``` - -3. **Update FFI implementation** (`ffi/zig/src/main.zig`) - - Implement new functions - - Match ABI types exactly - -4. **Add tests** - - Unit tests in Zig - - Integration tests - - ABI verification tests - -5. **Update documentation** - - Function signatures - - Usage examples - - Migration guide (if breaking changes) - -## License +[arabic] +. *Update ABI first* (`+src/abi/*.idr+`) +* Modify type definitions +* Update proofs +* Ensure backward compatibility +. *Generate C header* ++ +[source,bash] +---- +idris2 --cg c-header src/abi/Types.idr -o generated/abi/{{project}}.h +---- +. *Update FFI implementation* (`+ffi/zig/src/main.zig+`) +* Implement new functions +* Match ABI types exactly +. *Add tests* +* Unit tests in Zig +* Integration tests +* ABI verification tests +. *Update documentation* +* Function signatures +* Usage examples +* Migration guide (if breaking changes) + +=== License MPL-2.0 -## See Also +=== See Also -- [Idris2 Documentation](https://idris2.readthedocs.io) -- [Zig Documentation](https://ziglang.org/documentation/master/) -- [Rhodium Standard Repositories](https://github.com/hyperpolymath/rhodium-standard-repositories) -- [FFI Migration Guide](../ffi-migration-guide.md) -- [ABI Migration Guide](../abi-migration-guide.md) +* https://idris2.readthedocs.io[Idris2 Documentation] +* https://ziglang.org/documentation/master/[Zig Documentation] +* https://github.com/hyperpolymath/rhodium-standard-repositories[Rhodium +Standard Repositories] +* link:../ffi-migration-guide.md[FFI Migration Guide] +* link:../abi-migration-guide.md[ABI Migration Guide] diff --git a/ARCHITECTURE.adoc b/ARCHITECTURE.adoc new file mode 100644 index 0000000..1c0a7a6 --- /dev/null +++ b/ARCHITECTURE.adoc @@ -0,0 +1,48 @@ +== Architecture + +=== Overview + +This repository follows a modular, maintainable architecture designed +for clarity, scalability, and long-term sustainability. + +=== Directory Structure + +.... +. +├── src/ # Source code +├── tests/ # Test suites +├── docs/ # Documentation +├── scripts/ # Utility scripts +├── config/ # Configuration files +├── LICENSE # License file +├── LICENSES/ # Full license texts +└── README.adoc # Project documentation +.... + +=== Design Principles + +* *Separation of Concerns*: Each module has a single responsibility +* *Testability*: Code is written to be easily testable +* *Documentation*: All public APIs are documented +* *Configuration*: Environment-specific settings are externalized + +=== Dependencies + +* External dependencies are minimized and clearly declared +* Version pinning is used for reproducibility + +=== Security Considerations + +* Sensitive data is never committed to the repository +* Secrets are managed through environment variables or secure vaults +* Regular dependency audits are performed + +=== Maintainability + +* Code follows consistent style guidelines +* Pull requests require review and CI checks +* Issues and discussions are tracked transparently + +''''' + +_Last updated: 2026-07-18_ diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md deleted file mode 100644 index 607e3d8..0000000 --- a/ARCHITECTURE.md +++ /dev/null @@ -1,47 +0,0 @@ -# Architecture - -## Overview - -This repository follows a modular, maintainable architecture designed for clarity, scalability, and long-term sustainability. - -## Directory Structure - -``` -. -├── src/ # Source code -├── tests/ # Test suites -├── docs/ # Documentation -├── scripts/ # Utility scripts -├── config/ # Configuration files -├── LICENSE # License file -├── LICENSES/ # Full license texts -└── README.adoc # Project documentation -``` - -## Design Principles - -- **Separation of Concerns**: Each module has a single responsibility -- **Testability**: Code is written to be easily testable -- **Documentation**: All public APIs are documented -- **Configuration**: Environment-specific settings are externalized - -## Dependencies - -- External dependencies are minimized and clearly declared -- Version pinning is used for reproducibility - -## Security Considerations - -- Sensitive data is never committed to the repository -- Secrets are managed through environment variables or secure vaults -- Regular dependency audits are performed - -## Maintainability - -- Code follows consistent style guidelines -- Pull requests require review and CI checks -- Issues and discussions are tracked transparently - ---- - -*Last updated: 2026-07-18* diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc index 493dd6e..ed100fd 100644 --- a/CHANGELOG.adoc +++ b/CHANGELOG.adoc @@ -1,154 +1,163 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -// Copyright (c) Jonathan D.A. Jewell -= Changelog +== Changelog All notable changes to this project will be documented in this file. -The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), -and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - -== [Unreleased] - -=== Planned -- JWT-based authentication for HTTP API -- Rate limiting for all endpoints -- TLS support for encrypted connections -- WASM core module for sandboxed conversion execution -- Advanced format support (YAML, XML, TOML) -- Plugin system for custom converters -- LSP 3.18 feature support -- Performance optimizations - -== [0.1.0] - 2025-11-22 - -=== Added -- **LSP Server**: Complete LSP 3.17 implementation with tower-lsp - - Document synchronization (didOpen, didChange, didSave, didClose) - - Code completion with format-aware suggestions - - Hover information showing document statistics - - Execute commands for document conversion - - Diagnostic validation for document formats -- **HTTP REST API**: Full REST API with axum - - POST /api/convert - Convert documents between formats - - GET /api/documents - List all documents - - GET /api/documents/:id - Get specific document - - DELETE /api/documents/:id - Delete document - - POST /api/validate - Validate document format - - GET /api/stats - Server statistics - - GET /api/health - Health check endpoint -- **WebSocket Server**: Real-time document updates - - Subscribe/unsubscribe to document changes - - Document update notifications - - Ping/pong keepalive - - Broadcast messaging -- **Conversion Engine**: Bidirectional format conversion - - Markdown ↔ HTML (full support via pulldown-cmark) - - Markdown ↔ JSON (structured representation) - - HTML ↔ JSON (DOM structure extraction) - - Format validation and diagnostics -- **Document Store**: Lock-free concurrent storage - - DashMap for thread-safe operations - - Document versioning - - Metadata tracking (creation time, modification time) - - UUID-based identification -- **Editor Clients**: 7 editor integrations (all <100 LOC) - - VS Code extension (~70 LOC) - - Neovim plugin (~65 LOC) - - Emacs package (~75 LOC) - - JetBrains plugin (~55 LOC) - - Sublime Text plugin (~60 LOC) - - Zed configuration - - Helix configuration -- **Web UI**: Single-page application - - Live document converter - - Real-time dashboard with WebSocket updates - - Document manager interface - - Server statistics display - - Responsive design for mobile/desktop -- **Infrastructure**: - - Dockerfile with multi-stage builds - - docker-compose.yml for orchestration - - podman-compose.yml for Podman support - - Comprehensive Makefile with 20+ targets - - Example configurations and conversions -- **Documentation**: - - Complete README with quick start - - API documentation with examples - - CONTRIBUTING.md for developers - - SECURITY.md for security policies - - CODE_OF_CONDUCT.md for community - - MAINTAINERS.md for governance -- **Testing**: - - LSP compliance test suite - - HTTP API integration tests - - Core conversion engine tests - - Document store concurrency tests -- **RSR Compliance**: - - .well-known/security.txt (RFC 9116) - - .well-known/ai.txt (AI training policies) - - .well-known/humans.txt (attribution) - - Justfile with build recipes - - flake.nix for Nix reproducible builds - - .gitlab-ci.yml for CI/CD - -=== Changed -- N/A (initial release) - -=== Deprecated -- N/A (initial release) - -=== Removed -- N/A (initial release) - -=== Fixed -- N/A (initial release) - -=== Security -- Memory safety guaranteed by Rust ownership system -- No unsafe code blocks in implementation -- Input validation for all HTTP endpoints -- LSP message validation -- CORS enabled for web UI access - -== Version History - -- [0.1.0] - 2025-11-22: Initial release with core functionality - -== Migration Guides - -=== From Non-LSP Solutions +The format is based on https://keepachangelog.com/en/1.0.0/[Keep a +Changelog], and this project adheres to +https://semver.org/spec/v2.0.0.html[Semantic Versioning]. + +=== [Unreleased] + +==== Planned + +* JWT-based authentication for HTTP API +* Rate limiting for all endpoints +* TLS support for encrypted connections +* WASM core module for sandboxed conversion execution +* Advanced format support (YAML, XML, TOML) +* Plugin system for custom converters +* LSP 3.18 feature support +* Performance optimizations + +=== [0.1.0] - 2025-11-22 + +==== Added + +* *LSP Server*: Complete LSP 3.17 implementation with tower-lsp +** Document synchronization (didOpen, didChange, didSave, didClose) +** Code completion with format-aware suggestions +** Hover information showing document statistics +** Execute commands for document conversion +** Diagnostic validation for document formats +* *HTTP REST API*: Full REST API with axum +** POST /api/convert - Convert documents between formats +** GET /api/documents - List all documents +** GET /api/documents/:id - Get specific document +** DELETE /api/documents/:id - Delete document +** POST /api/validate - Validate document format +** GET /api/stats - Server statistics +** GET /api/health - Health check endpoint +* *WebSocket Server*: Real-time document updates +** Subscribe/unsubscribe to document changes +** Document update notifications +** Ping/pong keepalive +** Broadcast messaging +* *Conversion Engine*: Bidirectional format conversion +** Markdown ↔ HTML (full support via pulldown-cmark) +** Markdown ↔ JSON (structured representation) +** HTML ↔ JSON (DOM structure extraction) +** Format validation and diagnostics +* *Document Store*: Lock-free concurrent storage +** DashMap for thread-safe operations +** Document versioning +** Metadata tracking (creation time, modification time) +** UUID-based identification +* *Editor Clients*: 7 editor integrations (all <100 LOC) +** VS Code extension (~70 LOC) +** Neovim plugin (~65 LOC) +** Emacs package (~75 LOC) +** JetBrains plugin (~55 LOC) +** Sublime Text plugin (~60 LOC) +** Zed configuration +** Helix configuration +* *Web UI*: Single-page application +** Live document converter +** Real-time dashboard with WebSocket updates +** Document manager interface +** Server statistics display +** Responsive design for mobile/desktop +* *Infrastructure*: +** Dockerfile with multi-stage builds +** docker-compose.yml for orchestration +** podman-compose.yml for Podman support +** Comprehensive Makefile with 20+ targets +** Example configurations and conversions +* *Documentation*: +** Complete README with quick start +** API documentation with examples +** CONTRIBUTING.md for developers +** SECURITY.md for security policies +** CODE_OF_CONDUCT.md for community +** MAINTAINERS.md for governance +* *Testing*: +** LSP compliance test suite +** HTTP API integration tests +** Core conversion engine tests +** Document store concurrency tests +* *RSR Compliance*: +** .well-known/security.txt (RFC 9116) +** .well-known/ai.txt (AI training policies) +** .well-known/humans.txt (attribution) +** Justfile with build recipes +** flake.nix for Nix reproducible builds +** .gitlab-ci.yml for CI/CD + +==== Changed + +* N/A (initial release) + +==== Deprecated + +* N/A (initial release) + +==== Removed + +* N/A (initial release) + +==== Fixed + +* N/A (initial release) + +==== Security + +* Memory safety guaranteed by Rust ownership system +* No unsafe code blocks in implementation +* Input validation for all HTTP endpoints +* LSP message validation +* CORS enabled for web UI access + +=== Version History + +* [0.1.0] - 2025-11-22: Initial release with core functionality + +=== Migration Guides + +==== From Non-LSP Solutions If migrating from traditional editor-specific plugins: -1. **Install Server**: Build and install the Rust server -2. **Install Client**: Install editor-specific client for your editor -3. **Configure**: Set server path in client configuration -4. **Test**: Open a Markdown/HTML/JSON file and test conversion commands +[arabic] +. *Install Server*: Build and install the Rust server +. *Install Client*: Install editor-specific client for your editor +. *Configure*: Set server path in client configuration +. *Test*: Open a Markdown/HTML/JSON file and test conversion commands -=== Future Migrations +==== Future Migrations -When upgrading to future versions, consult version-specific migration guides. +When upgrading to future versions, consult version-specific migration +guides. -== Deprecation Policy +=== Deprecation Policy -- **Minor versions**: Features deprecated with 6-month warning -- **Major versions**: Breaking changes allowed with migration guide -- **Security**: Immediate deprecation if security risk identified +* *Minor versions*: Features deprecated with 6-month warning +* *Major versions*: Breaking changes allowed with migration guide +* *Security*: Immediate deprecation if security risk identified -== Support +=== Support -- **Current Version**: 0.1.0 (active development) -- **LTS**: Not yet designated -- **EOL**: None yet +* *Current Version*: 0.1.0 (active development) +* *LTS*: Not yet designated +* *EOL*: None yet -== Links +=== Links -- [Repository](https://github.com/universal-connector/universal-language-connector) -- [Issue Tracker](https://github.com/universal-connector/universal-language-connector/issues) -- [Documentation](https://universal-connector.org/docs) -- [Changelog](https://github.com/universal-connector/universal-language-connector/blob/main/CHANGELOG.md) +* https://github.com/universal-connector/universal-language-connector[Repository] +* https://github.com/universal-connector/universal-language-connector/issues[Issue +Tracker] +* https://universal-connector.org/docs[Documentation] +* https://github.com/universal-connector/universal-language-connector/blob/main/CHANGELOG.md[Changelog] ---- +''''' -**Changelog Format**: [Keep a Changelog](https://keepachangelog.com/) -**Versioning**: [Semantic Versioning](https://semver.org/) +*Changelog Format*: https://keepachangelog.com/[Keep a Changelog] +*Versioning*: https://semver.org/[Semantic Versioning] diff --git a/CHANGELOG.md b/CHANGELOG.md deleted file mode 100644 index df55ff3..0000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,156 +0,0 @@ - -# Changelog - -All notable changes to this project will be documented in this file. - -The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), -and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - -## [Unreleased] - -### Planned -- JWT-based authentication for HTTP API -- Rate limiting for all endpoints -- TLS support for encrypted connections -- WASM core module for sandboxed conversion execution -- Advanced format support (YAML, XML, TOML) -- Plugin system for custom converters -- LSP 3.18 feature support -- Performance optimizations - -## [0.1.0] - 2025-11-22 - -### Added -- **LSP Server**: Complete LSP 3.17 implementation with tower-lsp - - Document synchronization (didOpen, didChange, didSave, didClose) - - Code completion with format-aware suggestions - - Hover information showing document statistics - - Execute commands for document conversion - - Diagnostic validation for document formats -- **HTTP REST API**: Full REST API with axum - - POST /api/convert - Convert documents between formats - - GET /api/documents - List all documents - - GET /api/documents/:id - Get specific document - - DELETE /api/documents/:id - Delete document - - POST /api/validate - Validate document format - - GET /api/stats - Server statistics - - GET /api/health - Health check endpoint -- **WebSocket Server**: Real-time document updates - - Subscribe/unsubscribe to document changes - - Document update notifications - - Ping/pong keepalive - - Broadcast messaging -- **Conversion Engine**: Bidirectional format conversion - - Markdown ↔ HTML (full support via pulldown-cmark) - - Markdown ↔ JSON (structured representation) - - HTML ↔ JSON (DOM structure extraction) - - Format validation and diagnostics -- **Document Store**: Lock-free concurrent storage - - DashMap for thread-safe operations - - Document versioning - - Metadata tracking (creation time, modification time) - - UUID-based identification -- **Editor Clients**: 7 editor integrations (all <100 LOC) - - VS Code extension (~70 LOC) - - Neovim plugin (~65 LOC) - - Emacs package (~75 LOC) - - JetBrains plugin (~55 LOC) - - Sublime Text plugin (~60 LOC) - - Zed configuration - - Helix configuration -- **Web UI**: Single-page application - - Live document converter - - Real-time dashboard with WebSocket updates - - Document manager interface - - Server statistics display - - Responsive design for mobile/desktop -- **Infrastructure**: - - Dockerfile with multi-stage builds - - docker-compose.yml for orchestration - - podman-compose.yml for Podman support - - Comprehensive Makefile with 20+ targets - - Example configurations and conversions -- **Documentation**: - - Complete README with quick start - - API documentation with examples - - CONTRIBUTING.md for developers - - SECURITY.md for security policies - - CODE_OF_CONDUCT.md for community - - MAINTAINERS.md for governance -- **Testing**: - - LSP compliance test suite - - HTTP API integration tests - - Core conversion engine tests - - Document store concurrency tests -- **RSR Compliance**: - - .well-known/security.txt (RFC 9116) - - .well-known/ai.txt (AI training policies) - - .well-known/humans.txt (attribution) - - Justfile with build recipes - - flake.nix for Nix reproducible builds - - .gitlab-ci.yml for CI/CD - -### Changed -- N/A (initial release) - -### Deprecated -- N/A (initial release) - -### Removed -- N/A (initial release) - -### Fixed -- N/A (initial release) - -### Security -- Memory safety guaranteed by Rust ownership system -- No unsafe code blocks in implementation -- Input validation for all HTTP endpoints -- LSP message validation -- CORS enabled for web UI access - -## Version History - -- [0.1.0] - 2025-11-22: Initial release with core functionality - -## Migration Guides - -### From Non-LSP Solutions - -If migrating from traditional editor-specific plugins: - -1. **Install Server**: Build and install the Rust server -2. **Install Client**: Install editor-specific client for your editor -3. **Configure**: Set server path in client configuration -4. **Test**: Open a Markdown/HTML/JSON file and test conversion commands - -### Future Migrations - -When upgrading to future versions, consult version-specific migration guides. - -## Deprecation Policy - -- **Minor versions**: Features deprecated with 6-month warning -- **Major versions**: Breaking changes allowed with migration guide -- **Security**: Immediate deprecation if security risk identified - -## Support - -- **Current Version**: 0.1.0 (active development) -- **LTS**: Not yet designated -- **EOL**: None yet - -## Links - -- [Repository](https://github.com/universal-connector/universal-language-connector) -- [Issue Tracker](https://github.com/universal-connector/universal-language-connector/issues) -- [Documentation](https://universal-connector.org/docs) -- [Changelog](https://github.com/universal-connector/universal-language-connector/blob/main/CHANGELOG.md) - ---- - -**Changelog Format**: [Keep a Changelog](https://keepachangelog.com/) -**Versioning**: [Semantic Versioning](https://semver.org/) diff --git a/CODE_OF_CONDUCT.adoc b/CODE_OF_CONDUCT.adoc new file mode 100644 index 0000000..f9dc84b --- /dev/null +++ b/CODE_OF_CONDUCT.adoc @@ -0,0 +1,167 @@ +== Code of Conduct + +=== Our Pledge + +We as members, contributors, and leaders pledge to make participation in +our community a harassment-free experience for everyone, regardless of +age, body size, visible or invisible disability, ethnicity, sex +characteristics, gender identity and expression, level of experience, +education, socio-economic status, nationality, personal appearance, +race, caste, color, religion, or sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, +welcoming, diverse, inclusive, and healthy community. + +=== Our Standards + +==== Examples of behavior that contributes to a positive environment: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our +mistakes, and learning from the experience +* Focusing on what is best not just for us as individuals, but for the +overall community +* Using welcoming and inclusive language +* Being supportive of newcomers and helping them get started + +==== Examples of unacceptable behavior: + +* The use of sexualized language or imagery, and sexual attention or +advances of any kind +* Trolling, insulting or derogatory comments, and personal or political +attacks +* Public or private harassment +* Publishing others’ private information, such as a physical or email +address, without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a +professional setting +* Dismissing or attacking other people’s contributions based on their +identity or background + +=== Emotional Safety + +We recognize that contributing to open source can be emotionally +demanding. We are committed to: + +* *Acknowledging contributions* - All contributions are valued, +regardless of size +* *Assuming good intentions* - Start with the assumption that people +mean well +* *Providing clear feedback* - Be specific and constructive in code +reviews +* *Respecting boundaries* - Not everyone can respond immediately +* *Celebrating learning* - Mistakes are opportunities to grow +* *Preventing burnout* - Contributors are encouraged to take breaks + +==== Reversibility Principle + +We encourage experimentation by ensuring: * *Branches are cheap* - Try +ideas without fear * *Reverts are acceptable* - It’s okay to undo +changes * *Feedback is kind* - Even when changes aren’t accepted * +*Learning is valued* - Every attempt teaches something + +=== Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our +standards of acceptable behavior and will take appropriate and fair +corrective action in response to any behavior that they deem +inappropriate, threatening, offensive, or harmful. + +Community leaders have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other +contributions that are not aligned to this Code of Conduct, and will +communicate reasons for moderation decisions when appropriate. + +=== Scope + +This Code of Conduct applies within all community spaces, and also +applies when an individual is officially representing the community in +public spaces. Examples of representing our community include using an +official e-mail address, posting via an official social media account, +or acting as an appointed representative at an online or offline event. + +=== Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may +be reported to the community leaders responsible for enforcement at +conduct@universal-connector.org. + +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security +of the reporter of any incident. + +=== Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in +determining the consequences for any action they deem in violation of +this Code of Conduct: + +==== 1. Correction + +*Community Impact*: Use of inappropriate language or other behavior +deemed unprofessional or unwelcome in the community. + +*Consequence*: A private, written warning from community leaders, +providing clarity around the nature of the violation and an explanation +of why the behavior was inappropriate. A public apology may be +requested. + +==== 2. Warning + +*Community Impact*: A violation through a single incident or series of +actions. + +*Consequence*: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, for a specified period of +time. This includes avoiding interactions in community spaces as well as +external channels like social media. Violating these terms may lead to a +temporary or permanent ban. + +==== 3. Temporary Ban + +*Community Impact*: A serious violation of community standards, +including sustained inappropriate behavior. + +*Consequence*: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No +public or private interaction with the people involved, including +unsolicited interaction with those enforcing the Code of Conduct, is +allowed during this period. Violating these terms may lead to a +permanent ban. + +==== 4. Permanent Ban + +*Community Impact*: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of +individuals. + +*Consequence*: A permanent ban from any sort of public interaction +within the community. + +=== Attribution + +This Code of Conduct is adapted from the +https://www.contributor-covenant.org[Contributor Covenant], version 2.1, +available at +https://www.contributor-covenant.org/version/2/1/code_of_conduct.html. + +Community Impact Guidelines were inspired by +https://github.com/mozilla/diversity[Mozilla’s code of conduct +enforcement ladder]. + +The Emotional Safety and Reversibility Principle sections are inspired +by the https://cccp.dev[CCCP (Caring, Consent, Compensation, +Publicity) Manifesto]. + +For answers to common questions about this code of conduct, see the FAQ +at https://www.contributor-covenant.org/faq. Translations are available +at https://www.contributor-covenant.org/translations. + +''''' + +*Version*: 2.1+Emotional Safety *Last Updated*: 2025-11-22 diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md deleted file mode 100644 index 4289a0f..0000000 --- a/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,112 +0,0 @@ - -# Code of Conduct - -## Our Pledge - -We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation. - -We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. - -## Our Standards - -### Examples of behavior that contributes to a positive environment: - -* Demonstrating empathy and kindness toward other people -* Being respectful of differing opinions, viewpoints, and experiences -* Giving and gracefully accepting constructive feedback -* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience -* Focusing on what is best not just for us as individuals, but for the overall community -* Using welcoming and inclusive language -* Being supportive of newcomers and helping them get started - -### Examples of unacceptable behavior: - -* The use of sexualized language or imagery, and sexual attention or advances of any kind -* Trolling, insulting or derogatory comments, and personal or political attacks -* Public or private harassment -* Publishing others' private information, such as a physical or email address, without their explicit permission -* Other conduct which could reasonably be considered inappropriate in a professional setting -* Dismissing or attacking other people's contributions based on their identity or background - -## Emotional Safety - -We recognize that contributing to open source can be emotionally demanding. We are committed to: - -* **Acknowledging contributions** - All contributions are valued, regardless of size -* **Assuming good intentions** - Start with the assumption that people mean well -* **Providing clear feedback** - Be specific and constructive in code reviews -* **Respecting boundaries** - Not everyone can respond immediately -* **Celebrating learning** - Mistakes are opportunities to grow -* **Preventing burnout** - Contributors are encouraged to take breaks - -### Reversibility Principle - -We encourage experimentation by ensuring: -* **Branches are cheap** - Try ideas without fear -* **Reverts are acceptable** - It's okay to undo changes -* **Feedback is kind** - Even when changes aren't accepted -* **Learning is valued** - Every attempt teaches something - -## Enforcement Responsibilities - -Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful. - -Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate. - -## Scope - -This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. - -## Enforcement - -Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at conduct@universal-connector.org. - -All complaints will be reviewed and investigated promptly and fairly. - -All community leaders are obligated to respect the privacy and security of the reporter of any incident. - -## Enforcement Guidelines - -Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct: - -### 1. Correction - -**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community. - -**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested. - -### 2. Warning - -**Community Impact**: A violation through a single incident or series of actions. - -**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban. - -### 3. Temporary Ban - -**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior. - -**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban. - -### 4. Permanent Ban - -**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals. - -**Consequence**: A permanent ban from any sort of public interaction within the community. - -## Attribution - -This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1, available at https://www.contributor-covenant.org/version/2/1/code_of_conduct.html. - -Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity). - -The Emotional Safety and Reversibility Principle sections are inspired by the [CCCP (Caring, Consent, Compensation, Publicity) Manifesto](https://cccp.dev). - -For answers to common questions about this code of conduct, see the FAQ at https://www.contributor-covenant.org/faq. Translations are available at https://www.contributor-covenant.org/translations. - ---- - -**Version**: 2.1+Emotional Safety -**Last Updated**: 2025-11-22 diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc new file mode 100644 index 0000000..d1f8adb --- /dev/null +++ b/CONTRIBUTING.adoc @@ -0,0 +1,443 @@ +== Contributing to Universal Language Connector + +Thank you for your interest in contributing! This document provides +guidelines and instructions for contributing to the project. + +=== Table of Contents + +* link:#code-of-conduct[Code of Conduct] +* link:#getting-started[Getting Started] +* link:#development-setup[Development Setup] +* link:#architecture-overview[Architecture Overview] +* link:#making-changes[Making Changes] +* link:#testing[Testing] +* link:#submitting-changes[Submitting Changes] +* link:#code-style[Code Style] +* link:#adding-new-features[Adding New Features] + +=== Code of Conduct + +* Be respectful and constructive +* Welcome newcomers and help them get started +* Focus on what is best for the community +* Show empathy towards other community members + +=== Getting Started + +[arabic] +. Fork the repository +. Clone your fork: +`+git clone https://github.com/YOUR_USERNAME/universal-language-connector.git+` +. Add upstream remote: +`+git remote add upstream https://github.com/universal-connector/universal-language-connector.git+` +. Create a branch: `+git checkout -b feature/your-feature-name+` + +=== Development Setup + +==== Prerequisites + +* Rust 1.75+ (install via https://rustup.rs/[rustup]) +* Node.js 18+ (for VS Code client development) +* Docker/Podman (optional, for container testing) + +==== Initial Setup + +[source,bash] +---- +# Install development tools +make setup + +# Build the project +make build + +# Run tests +make test + +# Start development server +make dev +---- + +==== Project Structure + +.... +universal-language-server-plugin/ +├── server/ # Rust server implementation +├── clients/ # Editor clients (<100 LOC each) +├── web/ # Web UI +├── deployment/ # Docker and deployment configs +├── docs/ # Documentation +└── examples/ # Usage examples +.... + +=== Architecture Overview + +==== Core Principles + +[arabic] +. *All logic in server* - Clients are thin wrappers (<100 LOC) +. *LSP 3.17 strict compliance* - No custom extensions without +justification +. *Performance targets* - <100ms response, <50MB memory, <500ms startup +. *Server-first thinking* - When in doubt, implement in the server + +==== Technology Stack + +*Server:* - Rust with tokio (async runtime) - tower-lsp (LSP +implementation) - axum (HTTP API) - dashmap (concurrent document +storage) + +*Clients:* - Language-specific LSP client libraries - Minimal code, +maximum delegation to server + +==== Key Components + +[arabic] +. *LSP Handler (`+server/src/lsp.rs+`)* - Language Server Protocol +implementation +. *HTTP API (`+server/src/http.rs+`)* - REST endpoints +. *WebSocket (`+server/src/websocket.rs+`)* - Real-time updates +. *Conversion Core (`+server/src/core.rs+`)* - Document format +conversion +. *Document Store (`+server/src/document_store.rs+`)* - Concurrent +document management + +=== Making Changes + +==== Workflow + +[arabic] +. *Update your fork:* ++ +[source,bash] +---- +git fetch upstream +git rebase upstream/main +---- +. *Make your changes:* +* Write code following style guidelines +* Add tests for new functionality +* Update documentation +. *Test your changes:* ++ +[source,bash] +---- +make test +make lint +make fmt +---- +. *Commit your changes:* ++ +[source,bash] +---- +git add . +git commit -m "feat: add new conversion format" +---- + +==== Commit Message Format + +Follow https://www.conventionalcommits.org/[Conventional Commits]: + +.... +(): + +[optional body] + +[optional footer] +.... + +*Types:* - `+feat+`: New feature - `+fix+`: Bug fix - `+docs+`: +Documentation changes - `+style+`: Code style changes (formatting, etc.) +- `+refactor+`: Code refactoring - `+test+`: Adding or updating tests - +`+chore+`: Maintenance tasks + +*Examples:* + +.... +feat(core): add YAML conversion support +fix(lsp): handle UTF-16 position correctly +docs(api): update WebSocket examples +.... + +=== Testing + +==== Running Tests + +[source,bash] +---- +# All tests +make test + +# Specific test file +cd server && cargo test --test core_tests + +# With output +cd server && cargo test -- --nocapture + +# Integration tests +make test-integration +---- + +==== Writing Tests + +*Unit tests* (same file as code): + +[source,rust] +---- +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn test_conversion() { + // Test code here + } +} +---- + +*Integration tests* (`+server/tests/+`): + +[source,rust] +---- +#[tokio::test] +async fn test_http_endpoint() { + // Test code here +} +---- + +==== Test Coverage + +Aim for >80% code coverage: + +[source,bash] +---- +make test-coverage +---- + +=== Submitting Changes + +==== Pull Request Process + +[arabic] +. *Push to your fork:* ++ +[source,bash] +---- +git push origin feature/your-feature-name +---- +. *Create Pull Request:* +* Go to GitHub and create a PR from your fork +* Fill in the PR template +* Link related issues +. *PR Requirements:* +* All tests must pass +* Code must be formatted (`+make fmt+`) +* Linter must pass (`+make lint+`) +* Documentation updated if needed +* At least one review approval +. *After Approval:* +* Squash commits if requested +* Rebase on main if needed +* Maintainers will merge + +==== PR Title Format + +Use conventional commit format: + +.... +feat: add support for YAML conversion +fix: resolve UTF-16 position handling bug +docs: improve API documentation +.... + +=== Code Style + +==== Rust Code + +Follow standard Rust conventions: + +[source,rust] +---- +// Use rustfmt +cargo fmt + +// Pass clippy +cargo clippy -- -D warnings + +// Naming +const MAX_SIZE: usize = 100; +fn convert_document() {} +struct DocumentStore {} + +// Error handling +fn process() -> Result { + // Use ? operator + let data = fetch_data()?; + Ok(process_data(data)) +} + +// Documentation +/// Converts a document between formats. +/// +/// # Arguments +/// * `request` - Conversion request with content and formats +/// +/// # Returns +/// Converted content or error +pub fn convert(request: ConversionRequest) -> Result { + // Implementation +} +---- + +==== TypeScript/JavaScript + +For client code: + +[source,typescript] +---- +// Use consistent formatting +// Prefer async/await over callbacks +// Document public APIs + +/** + * Converts the current document to HTML + */ +async function convertToHtml(): Promise { + // Implementation +} +---- + +==== Keep Clients Under 100 LOC + +This is a hard constraint. If a client exceeds 100 lines: - Move logic +to the server - Simplify the implementation - Remove unnecessary code + +=== Adding New Features + +==== Adding a New Conversion Format + +[arabic] +. *Add parser dependency* to `+server/Cargo.toml+` +. *Implement converter* in `+server/src/core.rs+` +. *Add tests* in `+server/tests/core_tests.rs+` +. *Update documentation* in `+docs/API.md+` +. *Add examples* to `+examples/conversions/+` + +Example: + +[source,rust] +---- +// In core.rs +pub enum Format { + Markdown, + Html, + Json, + Yaml, // New format +} + +impl ConversionCore { + fn markdown_to_yaml(markdown: &str) -> Result { + // Implementation + } +} +---- + +==== Adding a New Editor Client + +[arabic] +. *Create directory*: `+clients//+` +. *Implement LSP client* using editor’s native API +. *Keep under 100 LOC* +. *Add README* with installation instructions +. *Test end-to-end* with real editor + +Template structure: + +.... +clients/myeditor/ +├── plugin.ext # Main plugin file (<100 LOC) +├── README.md # Installation guide +└── package.json/config # Package metadata (if applicable) +.... + +==== Adding HTTP Endpoints + +[arabic] +. *Define route* in `+server/src/http.rs+` +. *Add handler function* +. *Add tests* in `+server/tests/http_api_tests.rs+` +. *Update API docs* in `+docs/API.md+` + +Example: + +[source,rust] +---- +async fn new_endpoint( + State(state): State>, + Json(payload): Json, +) -> Result, ApiError> { + // Implementation +} + +// In create_router() +.route("/api/new-endpoint", post(new_endpoint)) +---- + +==== Adding LSP Methods + +[arabic] +. *Implement method* in `+server/src/lsp.rs+` +. *Update capabilities* in `+initialize()+` +. *Add tests* in `+server/tests/lsp_compliance.rs+` +. *Document in* `+docs/API.md+` + +Example: + +[source,rust] +---- +#[tower_lsp::async_trait] +impl LanguageServer for UniversalConnectorBackend { + async fn new_method(&self, params: Params) -> LspResult { + // Implementation + } +} +---- + +=== Performance Guidelines + +Always consider performance: + +* Use async/await for I/O operations +* Avoid blocking operations on main thread +* Use `+dashmap+` for concurrent access +* Profile changes with `+cargo bench+` +* Target <100ms response times + +=== Documentation + +Update documentation for: + +* New features +* API changes +* Configuration options +* Breaking changes + +Documentation locations: - API: `+docs/API.md+` - Architecture: +`+docs/ARCHITECTURE.md+` - User guide: `+README.md+` - Code comments: +Inline documentation + +=== Getting Help + +* *Issues*: +https://github.com/universal-connector/universal-language-connector/issues[GitHub +Issues] +* *Discussions*: +https://github.com/universal-connector/universal-language-connector/discussions[GitHub +Discussions] +* *Documentation*: See `+docs/+` directory + +=== Recognition + +Contributors are recognized in: - README.md contributors section - +Release notes - Git commit history + +Thank you for contributing to Universal Language Connector! diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index c0b8287..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,421 +0,0 @@ - -# Contributing to Universal Language Connector - -Thank you for your interest in contributing! This document provides guidelines and instructions for contributing to the project. - -## Table of Contents - -- [Code of Conduct](#code-of-conduct) -- [Getting Started](#getting-started) -- [Development Setup](#development-setup) -- [Architecture Overview](#architecture-overview) -- [Making Changes](#making-changes) -- [Testing](#testing) -- [Submitting Changes](#submitting-changes) -- [Code Style](#code-style) -- [Adding New Features](#adding-new-features) - -## Code of Conduct - -- Be respectful and constructive -- Welcome newcomers and help them get started -- Focus on what is best for the community -- Show empathy towards other community members - -## Getting Started - -1. Fork the repository -2. Clone your fork: `git clone https://github.com/YOUR_USERNAME/universal-language-connector.git` -3. Add upstream remote: `git remote add upstream https://github.com/universal-connector/universal-language-connector.git` -4. Create a branch: `git checkout -b feature/your-feature-name` - -## Development Setup - -### Prerequisites - -- Rust 1.75+ (install via [rustup](https://rustup.rs/)) -- Node.js 18+ (for VS Code client development) -- Docker/Podman (optional, for container testing) - -### Initial Setup - -```bash -# Install development tools -make setup - -# Build the project -make build - -# Run tests -make test - -# Start development server -make dev -``` - -### Project Structure - -``` -universal-language-server-plugin/ -├── server/ # Rust server implementation -├── clients/ # Editor clients (<100 LOC each) -├── web/ # Web UI -├── deployment/ # Docker and deployment configs -├── docs/ # Documentation -└── examples/ # Usage examples -``` - -## Architecture Overview - -### Core Principles - -1. **All logic in server** - Clients are thin wrappers (<100 LOC) -2. **LSP 3.17 strict compliance** - No custom extensions without justification -3. **Performance targets** - <100ms response, <50MB memory, <500ms startup -4. **Server-first thinking** - When in doubt, implement in the server - -### Technology Stack - -**Server:** -- Rust with tokio (async runtime) -- tower-lsp (LSP implementation) -- axum (HTTP API) -- dashmap (concurrent document storage) - -**Clients:** -- Language-specific LSP client libraries -- Minimal code, maximum delegation to server - -### Key Components - -1. **LSP Handler (`server/src/lsp.rs`)** - Language Server Protocol implementation -2. **HTTP API (`server/src/http.rs`)** - REST endpoints -3. **WebSocket (`server/src/websocket.rs`)** - Real-time updates -4. **Conversion Core (`server/src/core.rs`)** - Document format conversion -5. **Document Store (`server/src/document_store.rs`)** - Concurrent document management - -## Making Changes - -### Workflow - -1. **Update your fork:** - ```bash - git fetch upstream - git rebase upstream/main - ``` - -2. **Make your changes:** - - Write code following style guidelines - - Add tests for new functionality - - Update documentation - -3. **Test your changes:** - ```bash - make test - make lint - make fmt - ``` - -4. **Commit your changes:** - ```bash - git add . - git commit -m "feat: add new conversion format" - ``` - -### Commit Message Format - -Follow [Conventional Commits](https://www.conventionalcommits.org/): - -``` -(): - -[optional body] - -[optional footer] -``` - -**Types:** -- `feat`: New feature -- `fix`: Bug fix -- `docs`: Documentation changes -- `style`: Code style changes (formatting, etc.) -- `refactor`: Code refactoring -- `test`: Adding or updating tests -- `chore`: Maintenance tasks - -**Examples:** -``` -feat(core): add YAML conversion support -fix(lsp): handle UTF-16 position correctly -docs(api): update WebSocket examples -``` - -## Testing - -### Running Tests - -```bash -# All tests -make test - -# Specific test file -cd server && cargo test --test core_tests - -# With output -cd server && cargo test -- --nocapture - -# Integration tests -make test-integration -``` - -### Writing Tests - -**Unit tests** (same file as code): -```rust -#[cfg(test)] -mod tests { - use super::*; - - #[test] - fn test_conversion() { - // Test code here - } -} -``` - -**Integration tests** (`server/tests/`): -```rust -#[tokio::test] -async fn test_http_endpoint() { - // Test code here -} -``` - -### Test Coverage - -Aim for >80% code coverage: - -```bash -make test-coverage -``` - -## Submitting Changes - -### Pull Request Process - -1. **Push to your fork:** - ```bash - git push origin feature/your-feature-name - ``` - -2. **Create Pull Request:** - - Go to GitHub and create a PR from your fork - - Fill in the PR template - - Link related issues - -3. **PR Requirements:** - - All tests must pass - - Code must be formatted (`make fmt`) - - Linter must pass (`make lint`) - - Documentation updated if needed - - At least one review approval - -4. **After Approval:** - - Squash commits if requested - - Rebase on main if needed - - Maintainers will merge - -### PR Title Format - -Use conventional commit format: - -``` -feat: add support for YAML conversion -fix: resolve UTF-16 position handling bug -docs: improve API documentation -``` - -## Code Style - -### Rust Code - -Follow standard Rust conventions: - -```rust -// Use rustfmt -cargo fmt - -// Pass clippy -cargo clippy -- -D warnings - -// Naming -const MAX_SIZE: usize = 100; -fn convert_document() {} -struct DocumentStore {} - -// Error handling -fn process() -> Result { - // Use ? operator - let data = fetch_data()?; - Ok(process_data(data)) -} - -// Documentation -/// Converts a document between formats. -/// -/// # Arguments -/// * `request` - Conversion request with content and formats -/// -/// # Returns -/// Converted content or error -pub fn convert(request: ConversionRequest) -> Result { - // Implementation -} -``` - -### TypeScript/JavaScript - -For client code: - -```typescript -// Use consistent formatting -// Prefer async/await over callbacks -// Document public APIs - -/** - * Converts the current document to HTML - */ -async function convertToHtml(): Promise { - // Implementation -} -``` - -### Keep Clients Under 100 LOC - -This is a hard constraint. If a client exceeds 100 lines: -- Move logic to the server -- Simplify the implementation -- Remove unnecessary code - -## Adding New Features - -### Adding a New Conversion Format - -1. **Add parser dependency** to `server/Cargo.toml` -2. **Implement converter** in `server/src/core.rs` -3. **Add tests** in `server/tests/core_tests.rs` -4. **Update documentation** in `docs/API.md` -5. **Add examples** to `examples/conversions/` - -Example: -```rust -// In core.rs -pub enum Format { - Markdown, - Html, - Json, - Yaml, // New format -} - -impl ConversionCore { - fn markdown_to_yaml(markdown: &str) -> Result { - // Implementation - } -} -``` - -### Adding a New Editor Client - -1. **Create directory**: `clients//` -2. **Implement LSP client** using editor's native API -3. **Keep under 100 LOC** -4. **Add README** with installation instructions -5. **Test end-to-end** with real editor - -Template structure: -``` -clients/myeditor/ -├── plugin.ext # Main plugin file (<100 LOC) -├── README.md # Installation guide -└── package.json/config # Package metadata (if applicable) -``` - -### Adding HTTP Endpoints - -1. **Define route** in `server/src/http.rs` -2. **Add handler function** -3. **Add tests** in `server/tests/http_api_tests.rs` -4. **Update API docs** in `docs/API.md` - -Example: -```rust -async fn new_endpoint( - State(state): State>, - Json(payload): Json, -) -> Result, ApiError> { - // Implementation -} - -// In create_router() -.route("/api/new-endpoint", post(new_endpoint)) -``` - -### Adding LSP Methods - -1. **Implement method** in `server/src/lsp.rs` -2. **Update capabilities** in `initialize()` -3. **Add tests** in `server/tests/lsp_compliance.rs` -4. **Document in** `docs/API.md` - -Example: -```rust -#[tower_lsp::async_trait] -impl LanguageServer for UniversalConnectorBackend { - async fn new_method(&self, params: Params) -> LspResult { - // Implementation - } -} -``` - -## Performance Guidelines - -Always consider performance: - -- Use async/await for I/O operations -- Avoid blocking operations on main thread -- Use `dashmap` for concurrent access -- Profile changes with `cargo bench` -- Target <100ms response times - -## Documentation - -Update documentation for: - -- New features -- API changes -- Configuration options -- Breaking changes - -Documentation locations: -- API: `docs/API.md` -- Architecture: `docs/ARCHITECTURE.md` -- User guide: `README.md` -- Code comments: Inline documentation - -## Getting Help - -- **Issues**: [GitHub Issues](https://github.com/universal-connector/universal-language-connector/issues) -- **Discussions**: [GitHub Discussions](https://github.com/universal-connector/universal-language-connector/discussions) -- **Documentation**: See `docs/` directory - -## Recognition - -Contributors are recognized in: -- README.md contributors section -- Release notes -- Git commit history - -Thank you for contributing to Universal Language Connector! diff --git a/GOVERNANCE.adoc b/GOVERNANCE.adoc new file mode 100644 index 0000000..9b836fb --- /dev/null +++ b/GOVERNANCE.adoc @@ -0,0 +1,60 @@ +== Governance + +=== Overview + +This project is governed by the following principles and structures to +ensure transparent, inclusive, and effective decision-making. + +=== Roles and Responsibilities + +==== Maintainers + +Maintainers are responsible for: - Reviewing and merging pull requests - +Managing releases and versioning - Ensuring code quality and standards - +Triaging issues and bug reports - Community engagement and support + +==== Contributors + +Contributors are expected to: - Follow the code of conduct - Submit +well-documented pull requests - Write tests for new functionality - +Maintain existing tests - Update documentation as needed + +=== Decision Making + +==== Minor Changes + +* Can be made by any maintainer +* Include bug fixes, documentation updates, dependency updates + +==== Major Changes + +* Require discussion in issues or pull requests +* Include new features, architectural changes, API changes +* Need approval from at least 2 maintainers + +==== Breaking Changes + +* Require RFC (Request for Comments) process +* Need approval from majority of maintainers +* Must include migration guide + +=== Code of Conduct + +All participants are expected to follow our Code of Conduct. Violations +can be reported to the maintainers. + +=== Communication + +* *Issues*: For bug reports and feature requests +* *Discussions*: For questions and general discussion +* *Pull Requests*: For code contributions + +=== Licensing + +All contributions are made under the terms of the repository’s LICENSE +file. By submitting a pull request, you agree to license your +contributions accordingly. + +''''' + +_Last updated: 2026-07-18_ diff --git a/GOVERNANCE.md b/GOVERNANCE.md deleted file mode 100644 index e27364c..0000000 --- a/GOVERNANCE.md +++ /dev/null @@ -1,60 +0,0 @@ -# Governance - -## Overview - -This project is governed by the following principles and structures to ensure transparent, inclusive, and effective decision-making. - -## Roles and Responsibilities - -### Maintainers - -Maintainers are responsible for: -- Reviewing and merging pull requests -- Managing releases and versioning -- Ensuring code quality and standards -- Triaging issues and bug reports -- Community engagement and support - -### Contributors - -Contributors are expected to: -- Follow the code of conduct -- Submit well-documented pull requests -- Write tests for new functionality -- Maintain existing tests -- Update documentation as needed - -## Decision Making - -### Minor Changes -- Can be made by any maintainer -- Include bug fixes, documentation updates, dependency updates - -### Major Changes -- Require discussion in issues or pull requests -- Include new features, architectural changes, API changes -- Need approval from at least 2 maintainers - -### Breaking Changes -- Require RFC (Request for Comments) process -- Need approval from majority of maintainers -- Must include migration guide - -## Code of Conduct - -All participants are expected to follow our Code of Conduct. Violations can be reported to the maintainers. - -## Communication - -- **Issues**: For bug reports and feature requests -- **Discussions**: For questions and general discussion -- **Pull Requests**: For code contributions - -## Licensing - -All contributions are made under the terms of the repository's LICENSE file. -By submitting a pull request, you agree to license your contributions accordingly. - ---- - -*Last updated: 2026-07-18* diff --git a/MAINTAINERS.adoc b/MAINTAINERS.adoc index aa23a55..999140a 100644 --- a/MAINTAINERS.adoc +++ b/MAINTAINERS.adoc @@ -1,48 +1,159 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -// Copyright (c) Jonathan D.A. Jewell -= Maintainers -:toc: preamble +== Maintainers -This document lists the maintainers of this project and their responsibilities. +This document lists the maintainers of the Universal Language Connector +project. -== Current Maintainers +=== Project Leadership -[cols="2,3,2",options="header"] -|=== -| Name | Role | Contact +==== Creator & Lead Maintainer -| Jonathan D.A. Jewell -| Lead Maintainer -| https://github.com/hyperpolymath[@hyperpolymath] -|=== +* *Role*: Project creator, architecture decisions, final approvals +* *Scope*: All components (server, clients, documentation) +* *TPCF Perimeter*: Perimeter 3 (Community Sandbox - Open) -== Responsibilities +=== Component Maintainers -Maintainers are responsible for: +==== Rust Server -* Reviewing and merging pull requests -* Triaging issues and feature requests -* Ensuring code quality and security standards -* Managing releases and versioning -* Upholding the project's code of conduct +* *Maintainer*: [To be assigned] +* *Components*: LSP handler, HTTP API, WebSocket server, conversion core +* *Responsibilities*: Code review, security patches, performance +optimization -== Becoming a Maintainer +==== Editor Clients -Contributors who demonstrate: +* *VS Code*: [To be assigned] +* *Neovim*: [To be assigned] +* *Emacs*: [To be assigned] +* *JetBrains*: [To be assigned] +* *Sublime Text*: [To be assigned] +* *Zed/Helix*: [To be assigned] -* Consistent, high-quality contributions -* Understanding of the project's goals and standards -* Constructive participation in discussions -* Commitment to the project's long-term health +==== Web UI -May be invited to become maintainers at the discretion of existing maintainers. +* *Maintainer*: [To be assigned] +* *Components*: HTML/CSS/JS dashboard, real-time updates -== Decision Making +==== Documentation -* Routine decisions (bug fixes, minor improvements) can be made by any maintainer -* Significant changes require discussion and consensus among maintainers -* Breaking changes or major features should be discussed in issues before implementation +* *Maintainer*: [To be assigned] +* *Components*: README, API docs, guides, examples -== Contact +==== Infrastructure -For questions about project governance, open an issue or contact the maintainers listed above. +* *Maintainer*: [To be assigned] +* *Components*: CI/CD, Docker, deployment, build system + +=== Maintainer Responsibilities + +==== Code Review + +* Review pull requests within 48 hours +* Ensure code quality and test coverage +* Verify LSP compliance +* Check security implications + +==== Community Management + +* Respond to issues within 72 hours +* Welcome new contributors +* Enforce Code of Conduct +* Maintain positive community culture + +==== Technical Decisions + +* Architecture decisions require consensus +* Breaking changes need RFC process +* Performance targets must be maintained +* Security fixes prioritized + +==== Release Management + +* Follow semantic versioning +* Maintain CHANGELOG.md +* Create release notes +* Tag releases properly + +=== Becoming a Maintainer + +==== Criteria + +[arabic] +. *Sustained Contribution*: 3+ months of quality contributions +. *Technical Expertise*: Deep understanding of component area +. *Community Trust*: Positive interactions, helpful reviews +. *Time Commitment*: Available for regular code review and issue triage + +==== Process + +[arabic] +. Existing maintainer nominates candidate +. Candidate accepts nomination +. One-week community feedback period +. Consensus decision by current maintainers +. Onboarding: repository access, documentation, tools + +=== Stepping Down + +Maintainers can step down at any time by: 1. Notifying other maintainers +2. Ensuring knowledge transfer 3. Removing themselves from +MAINTAINERS.md 4. Transitioning in-progress work + +We deeply appreciate all maintainer contributions, past and present. + +=== Emeritus Maintainers + +Maintainers who have stepped down with honor: + +* [None yet] + +=== Contact + +* *Mailing List*: maintainers@universal-connector.org +* *Private Channel*: [Discord/Slack/Matrix] +* *Security Contact*: security@universal-connector.org + +=== Governance + +==== Decision Making + +* *Consensus*: Preferred method for all decisions +* *Lazy Consensus*: 72-hour timeout for minor changes +* *Voting*: Majority vote if consensus fails (requires 2/3 quorum) +* *Tie-breaking*: Lead maintainer has final say + +==== Conflict Resolution + +[arabic] +. *Discussion*: Open discussion in maintainer channel +. *Mediation*: Neutral third-party mediator +. *Voting*: If mediation fails, use voting process +. *Escalation*: Code of Conduct committee for conduct issues + +=== Tri-Perimeter Contribution Framework (TPCF) + +==== Current Perimeter: Perimeter 3 (Community Sandbox) + +*Access Level*: Open contribution - Anyone can submit pull requests - +Maintainer review required for merge - Two-factor authentication +recommended - Signed commits encouraged + +==== Future Perimeters + +*Perimeter 2 (Trusted Contributors)*: [Not yet implemented] - Regular +contributors with proven track record - Faster review process - Limited +merge access to non-critical components + +*Perimeter 1 (Core Team)*: [Not yet implemented] - Long-term maintainers +- Full repository access - Security-sensitive component access - Release +authority + +=== Updates + +This document should be updated when: - New maintainers are added - +Maintainers step down - Component ownership changes - Governance +processes evolve + +''''' + +*Last Updated*: 2025-11-22 *Version*: 1.0 diff --git a/MAINTAINERS.md b/MAINTAINERS.md deleted file mode 100644 index ba084e3..0000000 --- a/MAINTAINERS.md +++ /dev/null @@ -1,156 +0,0 @@ - -# Maintainers - -This document lists the maintainers of the Universal Language Connector project. - -## Project Leadership - -### Creator & Lead Maintainer -- **Role**: Project creator, architecture decisions, final approvals -- **Scope**: All components (server, clients, documentation) -- **TPCF Perimeter**: Perimeter 3 (Community Sandbox - Open) - -## Component Maintainers - -### Rust Server -- **Maintainer**: [To be assigned] -- **Components**: LSP handler, HTTP API, WebSocket server, conversion core -- **Responsibilities**: Code review, security patches, performance optimization - -### Editor Clients -- **VS Code**: [To be assigned] -- **Neovim**: [To be assigned] -- **Emacs**: [To be assigned] -- **JetBrains**: [To be assigned] -- **Sublime Text**: [To be assigned] -- **Zed/Helix**: [To be assigned] - -### Web UI -- **Maintainer**: [To be assigned] -- **Components**: HTML/CSS/JS dashboard, real-time updates - -### Documentation -- **Maintainer**: [To be assigned] -- **Components**: README, API docs, guides, examples - -### Infrastructure -- **Maintainer**: [To be assigned] -- **Components**: CI/CD, Docker, deployment, build system - -## Maintainer Responsibilities - -### Code Review -- Review pull requests within 48 hours -- Ensure code quality and test coverage -- Verify LSP compliance -- Check security implications - -### Community Management -- Respond to issues within 72 hours -- Welcome new contributors -- Enforce Code of Conduct -- Maintain positive community culture - -### Technical Decisions -- Architecture decisions require consensus -- Breaking changes need RFC process -- Performance targets must be maintained -- Security fixes prioritized - -### Release Management -- Follow semantic versioning -- Maintain CHANGELOG.md -- Create release notes -- Tag releases properly - -## Becoming a Maintainer - -### Criteria -1. **Sustained Contribution**: 3+ months of quality contributions -2. **Technical Expertise**: Deep understanding of component area -3. **Community Trust**: Positive interactions, helpful reviews -4. **Time Commitment**: Available for regular code review and issue triage - -### Process -1. Existing maintainer nominates candidate -2. Candidate accepts nomination -3. One-week community feedback period -4. Consensus decision by current maintainers -5. Onboarding: repository access, documentation, tools - -## Stepping Down - -Maintainers can step down at any time by: -1. Notifying other maintainers -2. Ensuring knowledge transfer -3. Removing themselves from MAINTAINERS.md -4. Transitioning in-progress work - -We deeply appreciate all maintainer contributions, past and present. - -## Emeritus Maintainers - -Maintainers who have stepped down with honor: - -- [None yet] - -## Contact - -- **Mailing List**: maintainers@universal-connector.org -- **Private Channel**: [Discord/Slack/Matrix] -- **Security Contact**: security@universal-connector.org - -## Governance - -### Decision Making - -- **Consensus**: Preferred method for all decisions -- **Lazy Consensus**: 72-hour timeout for minor changes -- **Voting**: Majority vote if consensus fails (requires 2/3 quorum) -- **Tie-breaking**: Lead maintainer has final say - -### Conflict Resolution - -1. **Discussion**: Open discussion in maintainer channel -2. **Mediation**: Neutral third-party mediator -3. **Voting**: If mediation fails, use voting process -4. **Escalation**: Code of Conduct committee for conduct issues - -## Tri-Perimeter Contribution Framework (TPCF) - -### Current Perimeter: Perimeter 3 (Community Sandbox) - -**Access Level**: Open contribution -- Anyone can submit pull requests -- Maintainer review required for merge -- Two-factor authentication recommended -- Signed commits encouraged - -### Future Perimeters - -**Perimeter 2 (Trusted Contributors)**: [Not yet implemented] -- Regular contributors with proven track record -- Faster review process -- Limited merge access to non-critical components - -**Perimeter 1 (Core Team)**: [Not yet implemented] -- Long-term maintainers -- Full repository access -- Security-sensitive component access -- Release authority - -## Updates - -This document should be updated when: -- New maintainers are added -- Maintainers step down -- Component ownership changes -- Governance processes evolve - ---- - -**Last Updated**: 2025-11-22 -**Version**: 1.0 diff --git a/PROOF-NEEDS.adoc b/PROOF-NEEDS.adoc new file mode 100644 index 0000000..7d5132f --- /dev/null +++ b/PROOF-NEEDS.adoc @@ -0,0 +1,12 @@ +== PROOF-NEEDS.md + +=== Template ABI Cleanup (2026-03-29) + +Template ABI removed – was creating false impression of formal +verification. The removed files (Types.idr, Layout.idr, Foreign.idr) +contained only RSR template scaffolding with unresolved +\{\{PROJECT}}/\{\{AUTHOR}} placeholders and no domain-specific proofs. + +When this project needs formal ABI verification, create domain-specific +Idris2 proofs following the pattern in repos like `+typed-wasm+`, +`+proven+`, `+echidna+`, or `+boj-server+`. diff --git a/PROOF-NEEDS.md b/PROOF-NEEDS.md deleted file mode 100644 index fd95f90..0000000 --- a/PROOF-NEEDS.md +++ /dev/null @@ -1,14 +0,0 @@ - -# PROOF-NEEDS.md - -## Template ABI Cleanup (2026-03-29) - -Template ABI removed -- was creating false impression of formal verification. -The removed files (Types.idr, Layout.idr, Foreign.idr) contained only RSR template -scaffolding with unresolved {{PROJECT}}/{{AUTHOR}} placeholders and no domain-specific proofs. - -When this project needs formal ABI verification, create domain-specific Idris2 proofs -following the pattern in repos like `typed-wasm`, `proven`, `echidna`, or `boj-server`. diff --git a/RSR_COMPLIANCE.adoc b/RSR_COMPLIANCE.adoc new file mode 100644 index 0000000..eeec862 --- /dev/null +++ b/RSR_COMPLIANCE.adoc @@ -0,0 +1,640 @@ +== RSR (Rhodium Standard Repository) Compliance Report + +*Project*: Universal Language Connector *Version*: 0.1.0 *RSR Level*: +*Bronze* (targeting Silver) *Date*: 2025-11-22 *Framework*: +https://github.com/rhodium-std/framework + +''''' + +=== Executive Summary + +The Universal Language Connector achieves *Bronze-level RSR compliance* +with most Silver-level requirements met. The project demonstrates best +practices in documentation, security, testing, build automation, and +community governance. + +==== Compliance Score: 95/100 + +[cols=",,",options="header",] +|=== +|Category |Score |Status +|Type Safety |10/10 |✅ Complete +|Memory Safety |10/10 |✅ Complete +|Documentation |10/10 |✅ Complete +|Security |9/10 |⚠️ Minor gaps +|Testing |8/10 |⚠️ Coverage improvable +|Build System |10/10 |✅ Complete +|Licensing |10/10 |✅ Complete +|Community |10/10 |✅ Complete +|Offline-First |3/10 |❌ Network-dependent +|Accessibility |8/10 |⚠️ Web UI needs work +|Attribution |10/10 |✅ Complete +|=== + +''''' + +=== 1. Type Safety ✅ (10/10) + +*Status*: Fully Compliant + +==== Implementation: + +* *Language*: Rust with strict type system +* *Compile-time guarantees*: All type errors caught at compile time +* *No dynamic typing*: Zero use of `+Any+` or runtime type checks +* *Trait bounds*: Extensive use of type constraints +* *Generic safety*: Type parameters properly bounded + +==== Evidence: + +[source,rust] +---- +// Example from core.rs +pub enum Format { + Markdown, + Html, + Json, +} + +pub struct ConversionRequest { + pub content: String, + pub from: Format, + pub to: Format, +} +---- + +==== Verification: + +[source,bash] +---- +cd server && cargo check +# Success - no type errors +---- + +''''' + +=== 2. Memory Safety ✅ (10/10) + +*Status*: Fully Compliant + +==== Implementation: + +* *Ownership model*: Rust borrow checker enforced +* *No unsafe code*: Zero `+unsafe+` blocks in codebase +* *No manual memory management*: All allocations managed by Rust +* *Concurrency safety*: `+DashMap+` for lock-free concurrent access +* *No data races*: Enforced by Rust’s type system + +==== Evidence: + +[source,bash] +---- +cd server && rg "unsafe" src/ +# No results - zero unsafe blocks +---- + +==== Guarantees: + +* ✅ No buffer overflows +* ✅ No use-after-free +* ✅ No double-free +* ✅ No data races +* ✅ No null pointer dereferences + +''''' + +=== 3. Documentation ✅ (10/10) + +*Status*: Fully Compliant + +==== Required Files: + +[width="100%",cols="21%,26%,23%,30%",options="header",] +|=== +|File |Status |Lines |Quality +|README.md |✅ |400+ |Comprehensive + +|LICENSE |✅ |150+ |Dual MIT + Palimpsest v0.8 + +|SECURITY.md |✅ |120+ |RFC-compliant + +|CONTRIBUTING.md |✅ |400+ |Detailed guidelines + +|CODE_OF_CONDUCT.md |✅ |150+ |Contributor Covenant 2.1 + Emotional +Safety + +|MAINTAINERS.md |✅ |120+ |Governance defined + +|CHANGELOG.md |✅ |200+ |Keep a Changelog format + +|docs/API.md |✅ |500+ |Complete API reference +|=== + +==== Additional Documentation: + +* ✅ CLAUDE.md - Architecture and design philosophy +* ✅ Example configurations (examples/configs/) +* ✅ Example conversions (examples/conversions/) +* ✅ Inline code documentation + +==== Quality Metrics: + +* *Coverage*: All public APIs documented +* *Examples*: Multiple usage examples provided +* *Diagrams*: Architecture diagrams included +* *Tutorials*: Quick start guide present + +''''' + +=== 4. Security ⚠️ (9/10) + +*Status*: Mostly Compliant (minor gaps) + +==== Implemented: + +===== ✅ Security.txt (RFC 9116) + +* Location: `+.well-known/security.txt+` +* Contact: security@universal-connector.org +* Expiry: 2026-11-22 +* Policy: Link to SECURITY.md + +===== ✅ SECURITY.md + +* Vulnerability reporting process +* Coordinated disclosure (90-day policy) +* Security scope defined +* Known limitations documented +* Best practices provided + +===== ✅ Memory Safety + +* Rust ownership prevents memory vulnerabilities +* No unsafe code blocks +* No buffer overflows possible + +===== ✅ Input Validation + +* HTTP endpoints validate inputs +* LSP messages validated +* Format validation for conversions + +==== Gaps: + +===== ⚠️ No Authentication (planned v0.2.0) + +* *Impact*: Medium +* *Mitigation*: Deploy behind reverse proxy +* *Status*: Documented in SECURITY.md + +===== ⚠️ No Rate Limiting (planned v0.2.0) + +* *Impact*: Medium (DoS possible) +* *Mitigation*: Reverse proxy rate limiting +* *Status*: Documented + +===== ⚠️ No TLS (by design) + +* *Impact*: Low (expected deployment pattern) +* *Mitigation*: Reverse proxy handles TLS +* *Status*: Recommended deployment + +==== Security Score: 9/10 + +* -1 for missing auth/rate limiting (mitigable) + +''''' + +=== 5. Testing ⚠️ (8/10) + +*Status*: Good (improvement needed) + +==== Test Coverage: + +[cols=",,,",options="header",] +|=== +|Component |Tests |Coverage |Status +|Core Engine |✅ 15 tests |~80% |Good +|Document Store |✅ 5 tests |~90% |Excellent +|LSP Compliance |✅ 10 tests |~60% |Adequate +|HTTP API |⚠️ 12 tests |~40% |Needs work +|WebSocket |⚠️ 2 tests |~20% |Needs work +|=== + +==== Testing Infrastructure: + +* ✅ Unit tests present +* ✅ Integration test structure +* ⚠️ End-to-end tests missing +* ⚠️ Performance benchmarks disabled +* ✅ CI/CD pipeline configured + +==== Verification: + +[source,bash] +---- +cd server && cargo test +# Tests pass but coverage can improve +---- + +==== Improvement Plan: + +[arabic] +. Increase HTTP API test coverage to 80% +. Add WebSocket integration tests +. Implement end-to-end tests with real editors +. Enable performance benchmarks +. Target 90% overall coverage + +==== Testing Score: 8/10 + +* -1 for incomplete HTTP/WebSocket coverage +* -1 for missing E2E tests + +''''' + +=== 6. Build System ✅ (10/10) + +*Status*: Fully Compliant + +==== Multiple Build Systems: + +===== ✅ Cargo (Primary) + +[source,bash] +---- +cargo build --release +cargo test +cargo check +---- + +===== ✅ Makefile + +* 20+ recipes +* Cross-platform support +* All common tasks covered + +===== ✅ Just (Justfile) + +* 30+ recipes +* RSR compliance validation +* Development workflows + +===== ✅ Nix (flake.nix) + +* Reproducible builds +* Development shell +* Docker image generation +* Multiple dev environments + +==== CI/CD: + +===== ✅ GitLab CI (.gitlab-ci.yml) + +* 5 stages (validate, build, test, security, deploy) +* Multiple parallel jobs +* Artifact management +* Security scanning +* Release automation + +==== Build Score: 10/10 + +* Exceeds requirements with multiple build systems + +''''' + +=== 7. Licensing ✅ (10/10) + +*Status*: Fully Compliant + +==== Dual Licensing: + +* ✅ *MIT License*: OSI-approved, permissive +* ✅ *Palimpsest License v0.8*: Emotional labor acknowledgment + +==== License Features: + +* ✅ SPDX identifier: `+MIT AND Palimpsest-0.8+` +* ✅ Clear license terms +* ✅ Attribution requirements +* ✅ Compatibility statement +* ✅ Contributor well-being provisions + +==== License Files: + +* ✅ `+LICENSE+` (dual license) +* ✅ `+.well-known/ai.txt+` (AI training policies) + +==== Licensing Score: 10/10 + +* Meets all RSR licensing requirements + +''''' + +=== 8. Community Governance ✅ (10/10) + +*Status*: Fully Compliant + +==== TPCF (Tri-Perimeter Contribution Framework): + +===== Current Perimeter: *Perimeter 3 (Community Sandbox)* + +* *Access*: Open contribution +* *Review*: Maintainer approval required +* *Trust*: Public GitHub/GitLab +* *Security*: 2FA recommended, signed commits encouraged + +==== Governance Structure: + +===== ✅ MAINTAINERS.md + +* Roles defined +* Responsibilities clear +* Succession planning +* Decision-making process (consensus → voting) +* Conflict resolution + +===== ✅ CODE_OF_CONDUCT.md + +* Contributor Covenant 2.1 +* Emotional Safety additions +* Reversibility Principle +* Enforcement guidelines +* 4-level escalation + +==== Community Features: + +* ✅ Clear contribution guidelines +* ✅ Welcoming to newcomers +* ✅ Multiple ways to contribute +* ✅ Recognition of all contributions +* ✅ Emotional labor acknowledged + +==== Community Score: 10/10 + +* Comprehensive governance framework + +''''' + +=== 9. Offline-First ❌ (3/10) + +*Status*: *Non-Compliant* + +==== Current State: + +* ❌ Server requires network (HTTP/WebSocket) +* ❌ Web UI requires server connection +* ❌ Real-time features depend on network +* ⚠️ Editor clients work offline (LSP over stdio) +* ⚠️ Core conversion logic is offline-capable + +==== Why Non-Compliant: + +The Universal Language Connector is fundamentally a *network service*: - +HTTP API is the primary interface - WebSocket provides real-time updates +- Multi-editor synchronization requires network + +==== Partial Credit (3/10): + +* ✅ No telemetry or tracking +* ✅ No external API calls +* ✅ Core conversion works air-gapped (if extracted) +* ✅ Editor clients use local stdio (no network) + +==== Mitigation: + +Document this as *intentional design decision*: - Server architecture +requires network - Offline-first would compromise multi-editor sync - +Alternative: Standalone converter binary (future) + +==== Offline Score: 3/10 + +* -7 for network dependency (by design) + +''''' + +=== 10. Accessibility ⚠️ (8/10) + +*Status*: Good (improvement needed) + +==== Web UI: + +===== ✅ Implemented: + +* Semantic HTML5 structure +* Keyboard navigation supported +* Focus indicators visible +* Color contrast ratios checked +* Responsive design (mobile/desktop) +* No animations that can’t be disabled + +===== ⚠️ Needs Improvement: + +* ARIA labels incomplete +* Screen reader testing not performed +* No skip-to-content links +* Form labels could be better +* No accessibility statement + +==== Documentation: + +===== ✅ Implemented: + +* Clear, simple language +* Code examples provided +* Multiple formats (MD, HTML) +* Good structure and headings + +==== Accessibility Score: 8/10 + +* -1 for incomplete ARIA labels +* -1 for no screen reader testing + +==== Improvement Plan: + +[arabic] +. Add comprehensive ARIA labels +. Test with screen readers (NVDA, JAWS, VoiceOver) +. Add skip-to-content links +. Create accessibility statement +. Target WCAG 2.1 AAA + +''''' + +=== 11. Attribution ✅ (10/10) + +*Status*: Fully Compliant + +==== .well-known/humans.txt + +===== ✅ Complete Attribution: + +* Project team listed +* Contributors acknowledged +* Inspiration sources credited +* Open source dependencies listed +* Standards organizations thanked + +==== Content: + +* 200+ lines of attribution +* All major contributors named +* Dependencies with authors +* Inspiration acknowledgments +* Community thanks + +==== Attribution Channels: + +* ✅ humans.txt (machine-readable) +* ✅ LICENSE (legal attribution) +* ✅ README.md (user-facing) +* ✅ CONTRIBUTING.md (contributor guide) +* ✅ Code comments (inline attribution) + +==== Attribution Score: 10/10 + +* Comprehensive attribution system + +''''' + +=== RSR Compliance Matrix + +[cols=",,,",options="header",] +|=== +|Requirement |Status |Score |Notes +|*Bronze Level* | | | +|Type Safety |✅ |10/10 |Rust compile-time guarantees +|Memory Safety |✅ |10/10 |Zero unsafe blocks +|README.md |✅ |10/10 |Comprehensive +|LICENSE |✅ |10/10 |Dual MIT + Palimpsest +|Basic Tests |✅ |8/10 |Good coverage, needs improvement +|*Silver Level* | | | +|SECURITY.md |✅ |9/10 |Minor auth gaps +|CONTRIBUTING.md |✅ |10/10 |Detailed guidelines +|CODE_OF_CONDUCT.md |✅ |10/10 |Emotional safety included +|CHANGELOG.md |✅ |10/10 |Keep a Changelog format +|Build automation |✅ |10/10 |Multiple systems +|CI/CD pipeline |✅ |10/10 |GitLab CI complete +|Test coverage 80%+ |⚠️ |7/10 |~65% current +|*Gold Level* | | | +|Offline-first |❌ |3/10 |Network-dependent by design +|WCAG 2.1 AA |⚠️ |8/10 |Needs screen reader testing +|Reproducible builds |✅ |10/10 |Nix flake.nix +|Security audit |⚠️ |8/10 |cargo audit implemented +|*RSR Extras* | | | +|.well-known/security.txt |✅ |10/10 |RFC 9116 compliant +|.well-known/ai.txt |✅ |10/10 |AI training policies +|.well-known/humans.txt |✅ |10/10 |Comprehensive attribution +|TPCF |✅ |10/10 |Perimeter 3 implemented +|Justfile |✅ |10/10 |30+ recipes +|flake.nix |✅ |10/10 |Nix reproducibility +|=== + +''''' + +=== Overall Assessment + +==== Strengths: + +[arabic] +. *Excellent Type & Memory Safety*: Rust provides compile-time +guarantees +. *Comprehensive Documentation*: All required files plus extras +. *Multiple Build Systems*: Cargo, Make, Just, Nix +. *Strong Community Governance*: TPCF, Code of Conduct, MAINTAINERS +. *Dual Licensing*: MIT + Palimpsest v0.8 +. *Security Awareness*: SECURITY.md, security.txt, vulnerability +reporting +. *Attribution Culture*: Comprehensive humans.txt, acknowledgments + +==== Areas for Improvement: + +[arabic] +. *Test Coverage*: Increase from ~65% to 90% +. *Offline-First*: Accept as design constraint or create offline mode +. *Authentication*: Implement JWT auth (v0.2.0) +. *Accessibility*: Complete WCAG 2.1 AA compliance +. *End-to-End Tests*: Add real editor integration tests + +==== Recommended Next Steps: + +===== Immediate (v0.1.1): + +[arabic] +. Increase test coverage to 80% +. Add ARIA labels to web UI +. Complete HTTP API tests + +===== Short-term (v0.2.0): + +[arabic] +. Implement authentication +. Add rate limiting +. Screen reader testing +. Performance benchmarks + +===== Long-term (v0.3.0): + +[arabic] +. WCAG 2.1 AAA compliance +. Offline mode (standalone binary) +. Security audit by third party +. Gold-level RSR compliance + +''''' + +=== Compliance Level: *Bronze* ✅ + +*Rationale:* - All Bronze requirements met - Most Silver requirements +met - Some Gold requirements met - Offline-first exempted (by design) + +*Target:* Silver level (90% compliant, achievable with v0.2.0) + +*Stretch Goal:* Gold level (requires offline-first resolution) + +''''' + +=== Self-Verification + +[source,bash] +---- +# Run RSR compliance check +just validate-rsr + +# Expected output: +# === RSR Framework Compliance Check === +# ✅ Type Safety: Rust compile-time guarantees +# ✅ Memory Safety: Ownership model, zero unsafe blocks +# ✅ README.md +# ✅ LICENSE +# ✅ SECURITY.md +# ✅ CONTRIBUTING.md +# ✅ CODE_OF_CONDUCT.md +# ✅ MAINTAINERS.md +# ✅ CHANGELOG.md +# ✅ .well-known/security.txt +# ✅ .well-known/ai.txt +# ✅ .well-known/humans.txt +# ✅ Justfile +# ✅ Makefile +# ✅ Cargo.toml +# ✅ Tests compile +# === RSR Compliance: Bronze Level === +---- + +''''' + +=== Conclusion + +The Universal Language Connector demonstrates *strong RSR compliance* at +the Bronze level with clear pathways to Silver and Gold. The project +exemplifies modern software development best practices with +comprehensive documentation, robust testing, multiple build systems, and +a caring community culture. + +*Final Score: 95/100* (Bronze ✅, targeting Silver) + +''''' + +*Document Version*: 1.0 *Last Updated*: 2025-11-22 *Next Review*: +2026-01-22 (or at v0.2.0 release) diff --git a/RSR_COMPLIANCE.md b/RSR_COMPLIANCE.md deleted file mode 100644 index 6682e90..0000000 --- a/RSR_COMPLIANCE.md +++ /dev/null @@ -1,560 +0,0 @@ - -# RSR (Rhodium Standard Repository) Compliance Report - -**Project**: Universal Language Connector -**Version**: 0.1.0 -**RSR Level**: **Bronze** (targeting Silver) -**Date**: 2025-11-22 -**Framework**: https://github.com/rhodium-std/framework - ---- - -## Executive Summary - -The Universal Language Connector achieves **Bronze-level RSR compliance** with most Silver-level requirements met. The project demonstrates best practices in documentation, security, testing, build automation, and community governance. - -### Compliance Score: 95/100 - -| Category | Score | Status | -|----------|-------|--------| -| Type Safety | 10/10 | ✅ Complete | -| Memory Safety | 10/10 | ✅ Complete | -| Documentation | 10/10 | ✅ Complete | -| Security | 9/10 | ⚠️ Minor gaps | -| Testing | 8/10 | ⚠️ Coverage improvable | -| Build System | 10/10 | ✅ Complete | -| Licensing | 10/10 | ✅ Complete | -| Community | 10/10 | ✅ Complete | -| Offline-First | 3/10 | ❌ Network-dependent | -| Accessibility | 8/10 | ⚠️ Web UI needs work | -| Attribution | 10/10 | ✅ Complete | - ---- - -## 1. Type Safety ✅ (10/10) - -**Status**: Fully Compliant - -### Implementation: -- **Language**: Rust with strict type system -- **Compile-time guarantees**: All type errors caught at compile time -- **No dynamic typing**: Zero use of `Any` or runtime type checks -- **Trait bounds**: Extensive use of type constraints -- **Generic safety**: Type parameters properly bounded - -### Evidence: -```rust -// Example from core.rs -pub enum Format { - Markdown, - Html, - Json, -} - -pub struct ConversionRequest { - pub content: String, - pub from: Format, - pub to: Format, -} -``` - -### Verification: -```bash -cd server && cargo check -# Success - no type errors -``` - ---- - -## 2. Memory Safety ✅ (10/10) - -**Status**: Fully Compliant - -### Implementation: -- **Ownership model**: Rust borrow checker enforced -- **No unsafe code**: Zero `unsafe` blocks in codebase -- **No manual memory management**: All allocations managed by Rust -- **Concurrency safety**: `DashMap` for lock-free concurrent access -- **No data races**: Enforced by Rust's type system - -### Evidence: -```bash -cd server && rg "unsafe" src/ -# No results - zero unsafe blocks -``` - -### Guarantees: -- ✅ No buffer overflows -- ✅ No use-after-free -- ✅ No double-free -- ✅ No data races -- ✅ No null pointer dereferences - ---- - -## 3. Documentation ✅ (10/10) - -**Status**: Fully Compliant - -### Required Files: - -| File | Status | Lines | Quality | -|------|--------|-------|---------| -| README.md | ✅ | 400+ | Comprehensive | -| LICENSE | ✅ | 150+ | Dual MIT + Palimpsest v0.8 | -| SECURITY.md | ✅ | 120+ | RFC-compliant | -| CONTRIBUTING.md | ✅ | 400+ | Detailed guidelines | -| CODE_OF_CONDUCT.md | ✅ | 150+ | Contributor Covenant 2.1 + Emotional Safety | -| MAINTAINERS.md | ✅ | 120+ | Governance defined | -| CHANGELOG.md | ✅ | 200+ | Keep a Changelog format | -| docs/API.md | ✅ | 500+ | Complete API reference | - -### Additional Documentation: -- ✅ CLAUDE.md - Architecture and design philosophy -- ✅ Example configurations (examples/configs/) -- ✅ Example conversions (examples/conversions/) -- ✅ Inline code documentation - -### Quality Metrics: -- **Coverage**: All public APIs documented -- **Examples**: Multiple usage examples provided -- **Diagrams**: Architecture diagrams included -- **Tutorials**: Quick start guide present - ---- - -## 4. Security ⚠️ (9/10) - -**Status**: Mostly Compliant (minor gaps) - -### Implemented: - -#### ✅ Security.txt (RFC 9116) -- Location: `.well-known/security.txt` -- Contact: security@universal-connector.org -- Expiry: 2026-11-22 -- Policy: Link to SECURITY.md - -#### ✅ SECURITY.md -- Vulnerability reporting process -- Coordinated disclosure (90-day policy) -- Security scope defined -- Known limitations documented -- Best practices provided - -#### ✅ Memory Safety -- Rust ownership prevents memory vulnerabilities -- No unsafe code blocks -- No buffer overflows possible - -#### ✅ Input Validation -- HTTP endpoints validate inputs -- LSP messages validated -- Format validation for conversions - -### Gaps: - -#### ⚠️ No Authentication (planned v0.2.0) -- **Impact**: Medium -- **Mitigation**: Deploy behind reverse proxy -- **Status**: Documented in SECURITY.md - -#### ⚠️ No Rate Limiting (planned v0.2.0) -- **Impact**: Medium (DoS possible) -- **Mitigation**: Reverse proxy rate limiting -- **Status**: Documented - -#### ⚠️ No TLS (by design) -- **Impact**: Low (expected deployment pattern) -- **Mitigation**: Reverse proxy handles TLS -- **Status**: Recommended deployment - -### Security Score: 9/10 -- -1 for missing auth/rate limiting (mitigable) - ---- - -## 5. Testing ⚠️ (8/10) - -**Status**: Good (improvement needed) - -### Test Coverage: - -| Component | Tests | Coverage | Status | -|-----------|-------|----------|--------| -| Core Engine | ✅ 15 tests | ~80% | Good | -| Document Store | ✅ 5 tests | ~90% | Excellent | -| LSP Compliance | ✅ 10 tests | ~60% | Adequate | -| HTTP API | ⚠️ 12 tests | ~40% | Needs work | -| WebSocket | ⚠️ 2 tests | ~20% | Needs work | - -### Testing Infrastructure: -- ✅ Unit tests present -- ✅ Integration test structure -- ⚠️ End-to-end tests missing -- ⚠️ Performance benchmarks disabled -- ✅ CI/CD pipeline configured - -### Verification: -```bash -cd server && cargo test -# Tests pass but coverage can improve -``` - -### Improvement Plan: -1. Increase HTTP API test coverage to 80% -2. Add WebSocket integration tests -3. Implement end-to-end tests with real editors -4. Enable performance benchmarks -5. Target 90% overall coverage - -### Testing Score: 8/10 -- -1 for incomplete HTTP/WebSocket coverage -- -1 for missing E2E tests - ---- - -## 6. Build System ✅ (10/10) - -**Status**: Fully Compliant - -### Multiple Build Systems: - -#### ✅ Cargo (Primary) -```bash -cargo build --release -cargo test -cargo check -``` - -#### ✅ Makefile -- 20+ recipes -- Cross-platform support -- All common tasks covered - -#### ✅ Just (Justfile) -- 30+ recipes -- RSR compliance validation -- Development workflows - -#### ✅ Nix (flake.nix) -- Reproducible builds -- Development shell -- Docker image generation -- Multiple dev environments - -### CI/CD: - -#### ✅ GitLab CI (.gitlab-ci.yml) -- 5 stages (validate, build, test, security, deploy) -- Multiple parallel jobs -- Artifact management -- Security scanning -- Release automation - -### Build Score: 10/10 -- Exceeds requirements with multiple build systems - ---- - -## 7. Licensing ✅ (10/10) - -**Status**: Fully Compliant - -### Dual Licensing: -- ✅ **MIT License**: OSI-approved, permissive -- ✅ **Palimpsest License v0.8**: Emotional labor acknowledgment - -### License Features: -- ✅ SPDX identifier: `MIT AND Palimpsest-0.8` -- ✅ Clear license terms -- ✅ Attribution requirements -- ✅ Compatibility statement -- ✅ Contributor well-being provisions - -### License Files: -- ✅ `LICENSE` (dual license) -- ✅ `.well-known/ai.txt` (AI training policies) - -### Licensing Score: 10/10 -- Meets all RSR licensing requirements - ---- - -## 8. Community Governance ✅ (10/10) - -**Status**: Fully Compliant - -### TPCF (Tri-Perimeter Contribution Framework): - -#### Current Perimeter: **Perimeter 3 (Community Sandbox)** -- **Access**: Open contribution -- **Review**: Maintainer approval required -- **Trust**: Public GitHub/GitLab -- **Security**: 2FA recommended, signed commits encouraged - -### Governance Structure: - -#### ✅ MAINTAINERS.md -- Roles defined -- Responsibilities clear -- Succession planning -- Decision-making process (consensus → voting) -- Conflict resolution - -#### ✅ CODE_OF_CONDUCT.md -- Contributor Covenant 2.1 -- Emotional Safety additions -- Reversibility Principle -- Enforcement guidelines -- 4-level escalation - -### Community Features: -- ✅ Clear contribution guidelines -- ✅ Welcoming to newcomers -- ✅ Multiple ways to contribute -- ✅ Recognition of all contributions -- ✅ Emotional labor acknowledged - -### Community Score: 10/10 -- Comprehensive governance framework - ---- - -## 9. Offline-First ❌ (3/10) - -**Status**: **Non-Compliant** - -### Current State: -- ❌ Server requires network (HTTP/WebSocket) -- ❌ Web UI requires server connection -- ❌ Real-time features depend on network -- ⚠️ Editor clients work offline (LSP over stdio) -- ⚠️ Core conversion logic is offline-capable - -### Why Non-Compliant: -The Universal Language Connector is fundamentally a **network service**: -- HTTP API is the primary interface -- WebSocket provides real-time updates -- Multi-editor synchronization requires network - -### Partial Credit (3/10): -- ✅ No telemetry or tracking -- ✅ No external API calls -- ✅ Core conversion works air-gapped (if extracted) -- ✅ Editor clients use local stdio (no network) - -### Mitigation: -Document this as **intentional design decision**: -- Server architecture requires network -- Offline-first would compromise multi-editor sync -- Alternative: Standalone converter binary (future) - -### Offline Score: 3/10 -- -7 for network dependency (by design) - ---- - -## 10. Accessibility ⚠️ (8/10) - -**Status**: Good (improvement needed) - -### Web UI: - -#### ✅ Implemented: -- Semantic HTML5 structure -- Keyboard navigation supported -- Focus indicators visible -- Color contrast ratios checked -- Responsive design (mobile/desktop) -- No animations that can't be disabled - -#### ⚠️ Needs Improvement: -- ARIA labels incomplete -- Screen reader testing not performed -- No skip-to-content links -- Form labels could be better -- No accessibility statement - -### Documentation: - -#### ✅ Implemented: -- Clear, simple language -- Code examples provided -- Multiple formats (MD, HTML) -- Good structure and headings - -### Accessibility Score: 8/10 -- -1 for incomplete ARIA labels -- -1 for no screen reader testing - -### Improvement Plan: -1. Add comprehensive ARIA labels -2. Test with screen readers (NVDA, JAWS, VoiceOver) -3. Add skip-to-content links -4. Create accessibility statement -5. Target WCAG 2.1 AAA - ---- - -## 11. Attribution ✅ (10/10) - -**Status**: Fully Compliant - -### .well-known/humans.txt - -#### ✅ Complete Attribution: -- Project team listed -- Contributors acknowledged -- Inspiration sources credited -- Open source dependencies listed -- Standards organizations thanked - -### Content: -- 200+ lines of attribution -- All major contributors named -- Dependencies with authors -- Inspiration acknowledgments -- Community thanks - -### Attribution Channels: -- ✅ humans.txt (machine-readable) -- ✅ LICENSE (legal attribution) -- ✅ README.md (user-facing) -- ✅ CONTRIBUTING.md (contributor guide) -- ✅ Code comments (inline attribution) - -### Attribution Score: 10/10 -- Comprehensive attribution system - ---- - -## RSR Compliance Matrix - -| Requirement | Status | Score | Notes | -|-------------|--------|-------|-------| -| **Bronze Level** | | | | -| Type Safety | ✅ | 10/10 | Rust compile-time guarantees | -| Memory Safety | ✅ | 10/10 | Zero unsafe blocks | -| README.md | ✅ | 10/10 | Comprehensive | -| LICENSE | ✅ | 10/10 | Dual MIT + Palimpsest | -| Basic Tests | ✅ | 8/10 | Good coverage, needs improvement | -| **Silver Level** | | | | -| SECURITY.md | ✅ | 9/10 | Minor auth gaps | -| CONTRIBUTING.md | ✅ | 10/10 | Detailed guidelines | -| CODE_OF_CONDUCT.md | ✅ | 10/10 | Emotional safety included | -| CHANGELOG.md | ✅ | 10/10 | Keep a Changelog format | -| Build automation | ✅ | 10/10 | Multiple systems | -| CI/CD pipeline | ✅ | 10/10 | GitLab CI complete | -| Test coverage 80%+ | ⚠️ | 7/10 | ~65% current | -| **Gold Level** | | | | -| Offline-first | ❌ | 3/10 | Network-dependent by design | -| WCAG 2.1 AA | ⚠️ | 8/10 | Needs screen reader testing | -| Reproducible builds | ✅ | 10/10 | Nix flake.nix | -| Security audit | ⚠️ | 8/10 | cargo audit implemented | -| **RSR Extras** | | | | -| .well-known/security.txt | ✅ | 10/10 | RFC 9116 compliant | -| .well-known/ai.txt | ✅ | 10/10 | AI training policies | -| .well-known/humans.txt | ✅ | 10/10 | Comprehensive attribution | -| TPCF | ✅ | 10/10 | Perimeter 3 implemented | -| Justfile | ✅ | 10/10 | 30+ recipes | -| flake.nix | ✅ | 10/10 | Nix reproducibility | - ---- - -## Overall Assessment - -### Strengths: -1. **Excellent Type & Memory Safety**: Rust provides compile-time guarantees -2. **Comprehensive Documentation**: All required files plus extras -3. **Multiple Build Systems**: Cargo, Make, Just, Nix -4. **Strong Community Governance**: TPCF, Code of Conduct, MAINTAINERS -5. **Dual Licensing**: MIT + Palimpsest v0.8 -6. **Security Awareness**: SECURITY.md, security.txt, vulnerability reporting -7. **Attribution Culture**: Comprehensive humans.txt, acknowledgments - -### Areas for Improvement: -1. **Test Coverage**: Increase from ~65% to 90% -2. **Offline-First**: Accept as design constraint or create offline mode -3. **Authentication**: Implement JWT auth (v0.2.0) -4. **Accessibility**: Complete WCAG 2.1 AA compliance -5. **End-to-End Tests**: Add real editor integration tests - -### Recommended Next Steps: - -#### Immediate (v0.1.1): -1. Increase test coverage to 80% -2. Add ARIA labels to web UI -3. Complete HTTP API tests - -#### Short-term (v0.2.0): -1. Implement authentication -2. Add rate limiting -3. Screen reader testing -4. Performance benchmarks - -#### Long-term (v0.3.0): -1. WCAG 2.1 AAA compliance -2. Offline mode (standalone binary) -3. Security audit by third party -4. Gold-level RSR compliance - ---- - -## Compliance Level: **Bronze** ✅ - -**Rationale:** -- All Bronze requirements met -- Most Silver requirements met -- Some Gold requirements met -- Offline-first exempted (by design) - -**Target:** Silver level (90% compliant, achievable with v0.2.0) - -**Stretch Goal:** Gold level (requires offline-first resolution) - ---- - -## Self-Verification - -```bash -# Run RSR compliance check -just validate-rsr - -# Expected output: -# === RSR Framework Compliance Check === -# ✅ Type Safety: Rust compile-time guarantees -# ✅ Memory Safety: Ownership model, zero unsafe blocks -# ✅ README.md -# ✅ LICENSE -# ✅ SECURITY.md -# ✅ CONTRIBUTING.md -# ✅ CODE_OF_CONDUCT.md -# ✅ MAINTAINERS.md -# ✅ CHANGELOG.md -# ✅ .well-known/security.txt -# ✅ .well-known/ai.txt -# ✅ .well-known/humans.txt -# ✅ Justfile -# ✅ Makefile -# ✅ Cargo.toml -# ✅ Tests compile -# === RSR Compliance: Bronze Level === -``` - ---- - -## Conclusion - -The Universal Language Connector demonstrates **strong RSR compliance** at the Bronze level with clear pathways to Silver and Gold. The project exemplifies modern software development best practices with comprehensive documentation, robust testing, multiple build systems, and a caring community culture. - -**Final Score: 95/100** (Bronze ✅, targeting Silver) - ---- - -**Document Version**: 1.0 -**Last Updated**: 2025-11-22 -**Next Review**: 2026-01-22 (or at v0.2.0 release) diff --git a/SECURITY.adoc b/SECURITY.adoc new file mode 100644 index 0000000..e2303e5 --- /dev/null +++ b/SECURITY.adoc @@ -0,0 +1,140 @@ +== Security Policy + +=== Supported Versions + +[cols=",",options="header",] +|=== +|Version |Supported +|0.1.x |:white_check_mark: +|=== + +=== Reporting a Vulnerability + +*DO NOT* open public issues for security vulnerabilities. + +==== Reporting Process + +[arabic] +. *Email*: Send security reports to security@universal-connector.org (if +available) or create a private security advisory on GitHub +. *Include*: +* Description of the vulnerability +* Steps to reproduce +* Potential impact +* Suggested fix (if any) +. *Response Time*: We aim to respond within 48 hours +. *Disclosure*: Coordinated disclosure after patch is available +(typically 90 days) + +==== Security Scope + +*In Scope:* - LSP server vulnerabilities (command injection, memory +safety) - HTTP API vulnerabilities (authentication bypass, injection +attacks) - WebSocket vulnerabilities (message injection, DoS) - +Dependency vulnerabilities - Build process security issues + +*Out of Scope:* - Editor client vulnerabilities (responsibility of +editor maintainers) - Denial of service requiring unrealistic resources +- Social engineering attacks + +=== Security Measures + +==== Current Protections + +[arabic] +. *Memory Safety*: Rust’s ownership system prevents: +* Buffer overflows +* Use-after-free +* Data races +* Null pointer dereferences +. *Input Validation*: +* All HTTP inputs validated +* LSP messages validated against protocol +* Document size limits enforced +* Format validation for conversions +. *Dependency Management*: +* Regular `+cargo audit+` runs +* Minimal dependency surface +* Pinned versions in Cargo.lock +. *Build Security*: +* Reproducible builds via Cargo +* No unsafe code blocks +* Strict compiler warnings + +==== Known Limitations + +[arabic] +. *No Authentication*: Server currently has no authentication mechanism +* *Mitigation*: Deploy behind reverse proxy with auth +* *Status*: Planned for v0.2.0 +. *No Rate Limiting*: APIs not rate-limited +* *Mitigation*: Use reverse proxy rate limiting +* *Status*: Planned for v0.2.0 +. *No TLS*: Server doesn’t implement TLS +* *Mitigation*: Use reverse proxy (nginx, Apache) +* *Status*: Recommended deployment pattern +. *Document Storage*: In-memory only, no persistence +* *Impact*: DoS via memory exhaustion possible +* *Mitigation*: Resource limits at OS/container level +* *Status*: Acceptable for current use case + +=== Security Best Practices + +==== Deployment + +[source,bash] +---- +# Run as non-root user +useradd -r -s /bin/false connector +sudo -u connector ./universal-connector-server + +# Use firewall rules +ufw allow from trusted_ip to any port 8080 +ufw deny 8080 + +# Container security +docker run --read-only --cap-drop=ALL --security-opt=no-new-privileges \ + --memory=100m --cpus=1.0 universal-connector +---- + +==== Configuration + +[source,bash] +---- +# Disable unused features +export ENABLE_LSP=true +export ENABLE_HTTP=false # If not needed +export ENABLE_WS=false # If not needed + +# Bind to localhost only +export HTTP_ADDR=127.0.0.1:8080 +export WS_ADDR=127.0.0.1:8081 +---- + +=== Security Roadmap + +* [ ] v0.2.0: Add JWT-based authentication +* [ ] v0.2.0: Implement rate limiting +* [ ] v0.3.0: Add TLS support +* [ ] v0.3.0: Implement document size limits +* [ ] v0.4.0: Add audit logging +* [ ] v0.4.0: Implement RBAC (Role-Based Access Control) + +=== Vulnerability History + +No vulnerabilities have been reported or discovered as of 2025-11-22. + +=== Contact + +* *Security Email*: security@universal-connector.org +* *PGP Key*: [To be added] +* *GitHub Security Advisories*: [Repository Security Tab] + +=== Acknowledgments + +We appreciate responsible disclosure and will acknowledge security +researchers who report vulnerabilities. + +''''' + +*Last Updated*: 2025-11-22 *Version*: 1.0 diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index 97b3e49..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,144 +0,0 @@ - -# Security Policy - -## Supported Versions - -| Version | Supported | -| ------- | ------------------ | -| 0.1.x | :white_check_mark: | - -## Reporting a Vulnerability - -**DO NOT** open public issues for security vulnerabilities. - -### Reporting Process - -1. **Email**: Send security reports to security@universal-connector.org (if available) or create a private security advisory on GitHub -2. **Include**: - - Description of the vulnerability - - Steps to reproduce - - Potential impact - - Suggested fix (if any) -3. **Response Time**: We aim to respond within 48 hours -4. **Disclosure**: Coordinated disclosure after patch is available (typically 90 days) - -### Security Scope - -**In Scope:** -- LSP server vulnerabilities (command injection, memory safety) -- HTTP API vulnerabilities (authentication bypass, injection attacks) -- WebSocket vulnerabilities (message injection, DoS) -- Dependency vulnerabilities -- Build process security issues - -**Out of Scope:** -- Editor client vulnerabilities (responsibility of editor maintainers) -- Denial of service requiring unrealistic resources -- Social engineering attacks - -## Security Measures - -### Current Protections - -1. **Memory Safety**: Rust's ownership system prevents: - - Buffer overflows - - Use-after-free - - Data races - - Null pointer dereferences - -2. **Input Validation**: - - All HTTP inputs validated - - LSP messages validated against protocol - - Document size limits enforced - - Format validation for conversions - -3. **Dependency Management**: - - Regular `cargo audit` runs - - Minimal dependency surface - - Pinned versions in Cargo.lock - -4. **Build Security**: - - Reproducible builds via Cargo - - No unsafe code blocks - - Strict compiler warnings - -### Known Limitations - -1. **No Authentication**: Server currently has no authentication mechanism - - **Mitigation**: Deploy behind reverse proxy with auth - - **Status**: Planned for v0.2.0 - -2. **No Rate Limiting**: APIs not rate-limited - - **Mitigation**: Use reverse proxy rate limiting - - **Status**: Planned for v0.2.0 - -3. **No TLS**: Server doesn't implement TLS - - **Mitigation**: Use reverse proxy (nginx, Apache) - - **Status**: Recommended deployment pattern - -4. **Document Storage**: In-memory only, no persistence - - **Impact**: DoS via memory exhaustion possible - - **Mitigation**: Resource limits at OS/container level - - **Status**: Acceptable for current use case - -## Security Best Practices - -### Deployment - -```bash -# Run as non-root user -useradd -r -s /bin/false connector -sudo -u connector ./universal-connector-server - -# Use firewall rules -ufw allow from trusted_ip to any port 8080 -ufw deny 8080 - -# Container security -docker run --read-only --cap-drop=ALL --security-opt=no-new-privileges \ - --memory=100m --cpus=1.0 universal-connector -``` - -### Configuration - -```bash -# Disable unused features -export ENABLE_LSP=true -export ENABLE_HTTP=false # If not needed -export ENABLE_WS=false # If not needed - -# Bind to localhost only -export HTTP_ADDR=127.0.0.1:8080 -export WS_ADDR=127.0.0.1:8081 -``` - -## Security Roadmap - -- [ ] v0.2.0: Add JWT-based authentication -- [ ] v0.2.0: Implement rate limiting -- [ ] v0.3.0: Add TLS support -- [ ] v0.3.0: Implement document size limits -- [ ] v0.4.0: Add audit logging -- [ ] v0.4.0: Implement RBAC (Role-Based Access Control) - -## Vulnerability History - -No vulnerabilities have been reported or discovered as of 2025-11-22. - -## Contact - -- **Security Email**: security@universal-connector.org -- **PGP Key**: [To be added] -- **GitHub Security Advisories**: [Repository Security Tab] - -## Acknowledgments - -We appreciate responsible disclosure and will acknowledge security researchers who report vulnerabilities. - ---- - -**Last Updated**: 2025-11-22 -**Version**: 1.0 diff --git a/TEST-NEEDS.adoc b/TEST-NEEDS.adoc new file mode 100644 index 0000000..1cab85f --- /dev/null +++ b/TEST-NEEDS.adoc @@ -0,0 +1,223 @@ +== Test Coverage Report - CRG C Blitz + +=== CRG Grade: C — ACHIEVED 2026-04-04 + +*Project*: universal-language-server-plugin *CRG Target*: Grade C +*Status*: ACHIEVED ✓ + +=== Test Coverage Summary + +All CRG C requirements met with comprehensive test suite covering unit, +property-based, E2E, aspect, contract, and benchmark testing. + +==== Test Statistics + +[cols=",,",options="header",] +|=== +|Category |Count |Status +|*Unit Tests* |35 |✓ PASS +|*Property Tests* |16 |✓ PASS +|*E2E Tests* |14 |✓ PASS +|*Aspect Tests* |14 |✓ PASS +|*Contract Tests* |14 |✓ PASS +|*Benchmark Suites* |17 |✓ CONFIGURED +|*Total Tests* |147 |✓ ALL PASS +|=== + +*Pass Rate*: 100% (147/147) + +=== Test Categories Implemented + +==== 1. Unit Tests (35 tests) + +Located in: - `+server/tests/core_tests.rs+` (210 lines) - +`+server/tests/http_api_tests.rs+` (117 lines) - +`+server/tests/lsp_compliance.rs+` (256 lines) + +Coverage: - Markdown ↔ HTML conversion - Markdown ↔ JSON conversion - +HTML ↔ Markdown conversion - Format detection and validation - Document +store operations - LSP message handling + +==== 2. Property-Based Tests (16 tests) + +*File*: `+server/tests/property_tests.rs+` (280+ lines) + +Tests invariants across random inputs using `+proptest+`: + +✓ TOML parsing never panics ✓ YAML parsing never panics ✓ XML parsing +never panics ✓ JSON parsing never panics ✓ Same-format conversion +preserves content ✓ Document store roundtrip consistency ✓ Document +version increments monotonically ✓ Markdown→HTML produces valid markup ✓ +Format detection is consistent ✓ JSON idempotence ✓ LSP position +non-negativity ✓ Document URI valid UTF-8 ✓ Document stats non-negative +✓ Empty documents handled gracefully ✓ Unicode URIs preserved ✓ Large +documents (1MB) handled without panic + +==== 3. End-to-End Tests (14 tests) + +*File*: `+server/tests/e2e_tests.rs+` (310+ lines) + +Complete workflow pipelines: + +✓ Document lifecycle (open → store → retrieve → convert → verify) ✓ +Hover request workflow ✓ Format request workflow ✓ Diagnostics workflow +✓ Completion request workflow ✓ MD→JSON→MD roundtrip ✓ MD→HTML→MD +roundtrip ✓ Concurrent document operations ✓ Large document conversion +(10K+ lines) ✓ Special character handling (emoji, accents, etc.) ✓ +Document version tracking ✓ YAML↔JSON roundtrip ✓ TOML↔JSON roundtrip ✓ +Format conversion with edge cases + +==== 4. Aspect Tests (14 tests) + +*File*: `+server/tests/aspect_tests.rs+` (420+ lines) + +Security, robustness, and edge-case handling: + +✓ Malformed TOML with null bytes → error, not panic ✓ Malformed JSON +handling ✓ Malformed YAML with tabs ✓ Malformed XML handling ✓ Oversized +documents (1MB, 10MB) handled ✓ Unicode in document paths ✓ Emoji in +content preservation ✓ Multi-byte UTF-8 character preservation ✓ LSP +position out-of-bounds graceful handling ✓ Empty content handling ✓ +Whitespace-only content ✓ Deeply nested JSON structures ✓ Very long +single lines (1MB) ✓ Control characters in content ✓ UTF-8 BOM handling +✓ Mixed line endings (LF/CR/CRLF) ✓ Minimal documents (1 byte) ✓ +Documents with only newlines ✓ Format circular references ✓ Rapid +document updates ✓ Code syntax in content ✓ Concurrent read operations + +==== 5. Contract Tests (14 tests) + +*File*: `+server/tests/contract_tests.rs+` (330+ lines) + +Type system and invariant verification: + +✓ Format::from_str roundtrip consistency ✓ ConversionRequest invariants +✓ ConversionResponse format consistency ✓ Document version always +positive ✓ Document timestamps ordered (created ≤ modified) ✓ Document +stats validity ✓ DocumentStore insert-retrieve consistency ✓ +DocumentStore length accuracy ✓ Format parsing variations +(case-insensitive) ✓ Same-format conversion idempotence ✓ Document +update versioning (1 → 2 → 3) ✓ DocumentStore.contains matches get ✓ +Format extensions are unique ✓ Format clone identity ✓ Document clone +identity ✓ ConversionRequest JSON serialization roundtrip ✓ Document +JSON serialization roundtrip ✓ Document stats accuracy (manual vs +computed) ✓ Validation consistency ✓ Empty format string fails ✓ +Document URI immutability ✓ Document content mutability + +==== 6. Benchmarks (17 suites) + +*File*: `+server/benches/lsp_bench.rs+` (260+ lines) + +Performance baselines using `+criterion+`: + +✓ TOML parse throughput ✓ YAML parse throughput ✓ Markdown→HTML +conversion ✓ JSON→YAML conversion ✓ Document store insert ✓ Document +store get ✓ Document store contains ✓ Document creation ✓ Document stats +computation ✓ Document content update ✓ Large markdown conversion (100+ +paragraphs) ✓ XML parsing ✓ HTML→Markdown conversion ✓ JSON validation ✓ +Document store bulk operations (100 docs) ✓ Format roundtrip +(MD→JSON→MD) ✓ Same-format no-op conversion + +=== Coverage Breakdown + +==== By Layer + +[cols=",,",options="header",] +|=== +|Layer |Tests |Coverage +|Core conversion engine |23 |100% +|Document store |35 |100% +|Format parsers (TOML/YAML/XML) |18 |100% +|LSP protocol |14 |100% +|HTTP API |12 |100% +|Properties & invariants |30 |100% +|Performance |17 |100% +|=== + +==== By Test Type + +[cols=",,,,",options="header",] +|=== +|Type |Tests |Panics |Errors |Warnings +|Unit |35 |0 |0 |0 +|Property |16 |0 |0 |0 +|E2E |14 |0 |0 |0 +|Aspect |14 |0 |0 |0 +|Contract |14 |0 |0 |0 +|*Total* |*147* |*0* |*0* |*0* +|=== + +=== Build Verification + +[source,bash] +---- +# All tests pass in debug mode +$ cargo test --manifest-path server/Cargo.toml +running 147 tests +test result: ok. 147 passed; 0 failed; 0 ignored; 0 measured + +# All tests pass in release mode +$ cargo test --release --manifest-path server/Cargo.toml +running 147 tests +test result: ok. 147 passed; 0 failed; 0 ignored; 0 measured + +# Benchmarks compile and run +$ cargo bench --manifest-path server/Cargo.toml +Compiling universal-connector-server v0.1.0 +Finished bench [optimized] target(s) +Running 17 benchmark suites... +---- + +=== Dependencies Added + +*Dev Dependencies*: - `+proptest = "1.4"+` - Property-based testing - +`+criterion = "0.5"+` - Performance benchmarking + +*Existing Foundations*: - `+tokio-test = "0.4"+` - Async test utilities +- `+tower-test = "0.4"+` - Service testing - `+axum-test = "14.3"+` - +HTTP API testing + +=== CRG C Requirements Met + +✓ *Unit tests* - 35 tests covering all core functionality ✓ *Smoke +tests* - All integration points tested ✓ *Build tests* - Full debug and +release builds pass ✓ *P2P (Property) tests* - 16 property-based +invariant tests ✓ *E2E tests* - 14 complete workflow tests ✓ *Reflexive +tests* - 14 contract tests verifying type invariants ✓ *Contract tests* +- 14 tests ensuring pre/post-conditions ✓ *Aspect tests* - 14 +security/robustness tests ✓ *Benchmarks baselined* - 17 performance +baseline measurements + +=== Files Modified + +*New Test Files*: - `+server/tests/property_tests.rs+` (280 lines) - +`+server/tests/e2e_tests.rs+` (310 lines) - +`+server/tests/aspect_tests.rs+` (420 lines) - +`+server/tests/contract_tests.rs+` (330 lines) - +`+server/benches/lsp_bench.rs+` (260 lines) + +*Configuration Updates*: - `+server/Cargo.toml+` - Added proptest and +criterion dev deps + +*Existing Test Files Unchanged*: - `+server/tests/core_tests.rs+` (210 +lines - baseline unit tests) - `+server/tests/http_api_tests.rs+` (117 +lines - HTTP tests) - `+server/tests/lsp_compliance.rs+` (256 lines - +LSP protocol tests) + +=== Code Quality + +* *SPDX Headers*: All new files include `+MPL-2.0+` headers +* *Documentation*: Each test category documented with clear purposes +* *No Panics*: All tests handle errors gracefully, zero unwrap/expect in +test assertions +* *Type Safety*: Leverages Rust’s type system for contract verification +* *Concurrent Safety*: Includes thread-safety tests with Arc +* *Performance*: Baseline benchmarks establish regression detection + +=== Next Steps + +The test suite is production-ready for: 1. CI/CD integration (all tests +must pass) 2. Regression detection (benchmark baselines established) 3. +Performance optimization (baselines documented) 4. Compliance validation +(LSP & HTTP API fully tested) + +Grade: *C* ✓ ACHIEVED diff --git a/TEST-NEEDS.md b/TEST-NEEDS.md deleted file mode 100644 index a1269c2..0000000 --- a/TEST-NEEDS.md +++ /dev/null @@ -1,276 +0,0 @@ - -# Test Coverage Report - CRG C Blitz - -## CRG Grade: C — ACHIEVED 2026-04-04 - -**Project**: universal-language-server-plugin -**CRG Target**: Grade C -**Status**: ACHIEVED ✓ - -## Test Coverage Summary - -All CRG C requirements met with comprehensive test suite covering unit, property-based, E2E, aspect, contract, and benchmark testing. - -### Test Statistics - -| Category | Count | Status | -|----------|-------|--------| -| **Unit Tests** | 35 | ✓ PASS | -| **Property Tests** | 16 | ✓ PASS | -| **E2E Tests** | 14 | ✓ PASS | -| **Aspect Tests** | 14 | ✓ PASS | -| **Contract Tests** | 14 | ✓ PASS | -| **Benchmark Suites** | 17 | ✓ CONFIGURED | -| **Total Tests** | 147 | ✓ ALL PASS | - -**Pass Rate**: 100% (147/147) - -## Test Categories Implemented - -### 1. Unit Tests (35 tests) - -Located in: -- `server/tests/core_tests.rs` (210 lines) -- `server/tests/http_api_tests.rs` (117 lines) -- `server/tests/lsp_compliance.rs` (256 lines) - -Coverage: -- Markdown ↔ HTML conversion -- Markdown ↔ JSON conversion -- HTML ↔ Markdown conversion -- Format detection and validation -- Document store operations -- LSP message handling - -### 2. Property-Based Tests (16 tests) - -**File**: `server/tests/property_tests.rs` (280+ lines) - -Tests invariants across random inputs using `proptest`: - -✓ TOML parsing never panics -✓ YAML parsing never panics -✓ XML parsing never panics -✓ JSON parsing never panics -✓ Same-format conversion preserves content -✓ Document store roundtrip consistency -✓ Document version increments monotonically -✓ Markdown→HTML produces valid markup -✓ Format detection is consistent -✓ JSON idempotence -✓ LSP position non-negativity -✓ Document URI valid UTF-8 -✓ Document stats non-negative -✓ Empty documents handled gracefully -✓ Unicode URIs preserved -✓ Large documents (1MB) handled without panic - -### 3. End-to-End Tests (14 tests) - -**File**: `server/tests/e2e_tests.rs` (310+ lines) - -Complete workflow pipelines: - -✓ Document lifecycle (open → store → retrieve → convert → verify) -✓ Hover request workflow -✓ Format request workflow -✓ Diagnostics workflow -✓ Completion request workflow -✓ MD→JSON→MD roundtrip -✓ MD→HTML→MD roundtrip -✓ Concurrent document operations -✓ Large document conversion (10K+ lines) -✓ Special character handling (emoji, accents, etc.) -✓ Document version tracking -✓ YAML↔JSON roundtrip -✓ TOML↔JSON roundtrip -✓ Format conversion with edge cases - -### 4. Aspect Tests (14 tests) - -**File**: `server/tests/aspect_tests.rs` (420+ lines) - -Security, robustness, and edge-case handling: - -✓ Malformed TOML with null bytes → error, not panic -✓ Malformed JSON handling -✓ Malformed YAML with tabs -✓ Malformed XML handling -✓ Oversized documents (1MB, 10MB) handled -✓ Unicode in document paths -✓ Emoji in content preservation -✓ Multi-byte UTF-8 character preservation -✓ LSP position out-of-bounds graceful handling -✓ Empty content handling -✓ Whitespace-only content -✓ Deeply nested JSON structures -✓ Very long single lines (1MB) -✓ Control characters in content -✓ UTF-8 BOM handling -✓ Mixed line endings (LF/CR/CRLF) -✓ Minimal documents (1 byte) -✓ Documents with only newlines -✓ Format circular references -✓ Rapid document updates -✓ Code syntax in content -✓ Concurrent read operations - -### 5. Contract Tests (14 tests) - -**File**: `server/tests/contract_tests.rs` (330+ lines) - -Type system and invariant verification: - -✓ Format::from_str roundtrip consistency -✓ ConversionRequest invariants -✓ ConversionResponse format consistency -✓ Document version always positive -✓ Document timestamps ordered (created ≤ modified) -✓ Document stats validity -✓ DocumentStore insert-retrieve consistency -✓ DocumentStore length accuracy -✓ Format parsing variations (case-insensitive) -✓ Same-format conversion idempotence -✓ Document update versioning (1 → 2 → 3) -✓ DocumentStore.contains matches get -✓ Format extensions are unique -✓ Format clone identity -✓ Document clone identity -✓ ConversionRequest JSON serialization roundtrip -✓ Document JSON serialization roundtrip -✓ Document stats accuracy (manual vs computed) -✓ Validation consistency -✓ Empty format string fails -✓ Document URI immutability -✓ Document content mutability - -### 6. Benchmarks (17 suites) - -**File**: `server/benches/lsp_bench.rs` (260+ lines) - -Performance baselines using `criterion`: - -✓ TOML parse throughput -✓ YAML parse throughput -✓ Markdown→HTML conversion -✓ JSON→YAML conversion -✓ Document store insert -✓ Document store get -✓ Document store contains -✓ Document creation -✓ Document stats computation -✓ Document content update -✓ Large markdown conversion (100+ paragraphs) -✓ XML parsing -✓ HTML→Markdown conversion -✓ JSON validation -✓ Document store bulk operations (100 docs) -✓ Format roundtrip (MD→JSON→MD) -✓ Same-format no-op conversion - -## Coverage Breakdown - -### By Layer - -| Layer | Tests | Coverage | -|-------|-------|----------| -| Core conversion engine | 23 | 100% | -| Document store | 35 | 100% | -| Format parsers (TOML/YAML/XML) | 18 | 100% | -| LSP protocol | 14 | 100% | -| HTTP API | 12 | 100% | -| Properties & invariants | 30 | 100% | -| Performance | 17 | 100% | - -### By Test Type - -| Type | Tests | Panics | Errors | Warnings | -|------|-------|--------|--------|----------| -| Unit | 35 | 0 | 0 | 0 | -| Property | 16 | 0 | 0 | 0 | -| E2E | 14 | 0 | 0 | 0 | -| Aspect | 14 | 0 | 0 | 0 | -| Contract | 14 | 0 | 0 | 0 | -| **Total** | **147** | **0** | **0** | **0** | - -## Build Verification - -```bash -# All tests pass in debug mode -$ cargo test --manifest-path server/Cargo.toml -running 147 tests -test result: ok. 147 passed; 0 failed; 0 ignored; 0 measured - -# All tests pass in release mode -$ cargo test --release --manifest-path server/Cargo.toml -running 147 tests -test result: ok. 147 passed; 0 failed; 0 ignored; 0 measured - -# Benchmarks compile and run -$ cargo bench --manifest-path server/Cargo.toml -Compiling universal-connector-server v0.1.0 -Finished bench [optimized] target(s) -Running 17 benchmark suites... -``` - -## Dependencies Added - -**Dev Dependencies**: -- `proptest = "1.4"` - Property-based testing -- `criterion = "0.5"` - Performance benchmarking - -**Existing Foundations**: -- `tokio-test = "0.4"` - Async test utilities -- `tower-test = "0.4"` - Service testing -- `axum-test = "14.3"` - HTTP API testing - -## CRG C Requirements Met - -✓ **Unit tests** - 35 tests covering all core functionality -✓ **Smoke tests** - All integration points tested -✓ **Build tests** - Full debug and release builds pass -✓ **P2P (Property) tests** - 16 property-based invariant tests -✓ **E2E tests** - 14 complete workflow tests -✓ **Reflexive tests** - 14 contract tests verifying type invariants -✓ **Contract tests** - 14 tests ensuring pre/post-conditions -✓ **Aspect tests** - 14 security/robustness tests -✓ **Benchmarks baselined** - 17 performance baseline measurements - -## Files Modified - -**New Test Files**: -- `server/tests/property_tests.rs` (280 lines) -- `server/tests/e2e_tests.rs` (310 lines) -- `server/tests/aspect_tests.rs` (420 lines) -- `server/tests/contract_tests.rs` (330 lines) -- `server/benches/lsp_bench.rs` (260 lines) - -**Configuration Updates**: -- `server/Cargo.toml` - Added proptest and criterion dev deps - -**Existing Test Files Unchanged**: -- `server/tests/core_tests.rs` (210 lines - baseline unit tests) -- `server/tests/http_api_tests.rs` (117 lines - HTTP tests) -- `server/tests/lsp_compliance.rs` (256 lines - LSP protocol tests) - -## Code Quality - -- **SPDX Headers**: All new files include `MPL-2.0` headers -- **Documentation**: Each test category documented with clear purposes -- **No Panics**: All tests handle errors gracefully, zero unwrap/expect in test assertions -- **Type Safety**: Leverages Rust's type system for contract verification -- **Concurrent Safety**: Includes thread-safety tests with Arc -- **Performance**: Baseline benchmarks establish regression detection - -## Next Steps - -The test suite is production-ready for: -1. CI/CD integration (all tests must pass) -2. Regression detection (benchmark baselines established) -3. Performance optimization (baselines documented) -4. Compliance validation (LSP & HTTP API fully tested) - -Grade: **C** ✓ ACHIEVED diff --git a/TOPOLOGY.md b/TOPOLOGY.adoc similarity index 87% rename from TOPOLOGY.md rename to TOPOLOGY.adoc index d9a2fdf..d626a09 100644 --- a/TOPOLOGY.md +++ b/TOPOLOGY.adoc @@ -1,15 +1,8 @@ - - - +== Universal Language Connector — Project Topology -# Universal Language Connector — Project Topology +=== System Architecture -## System Architecture - -``` +.... ┌─────────────────────────────────────────┐ │ EDITOR CLIENTS │ │ (VS Code, Neovim, Emacs, JetBrains) │ @@ -43,11 +36,11 @@ Copyright (c) Jonathan D.A. Jewell │ Justfile Automation .machine_readable/ │ │ Docker / Compose 0-AI-MANIFEST.a2ml │ └─────────────────────────────────────────┘ -``` +.... -## Completion Dashboard +=== Completion Dashboard -``` +.... COMPONENT STATUS NOTES ───────────────────────────────── ────────────────── ───────────────────────────────── SERVER CORE (RUST) @@ -69,25 +62,26 @@ REPO INFRASTRUCTURE ───────────────────────────────────────────────────────────────────────────── OVERALL: ██████████ 100% Production-ready server -``` +.... -## Key Dependencies +=== Key Dependencies -``` +.... stdio Stream ────► tower-lsp ──────► Conversion Core ──────► Editor UI │ │ │ │ ▼ ▼ ▼ ▼ axum API ──────► HTTP Request ─────► JSON Response ─────► Web HUD -``` +.... -## Update Protocol +=== Update Protocol This file is maintained by both humans and AI agents. When updating: -1. **After completing a component**: Change its bar and percentage -2. **After adding a component**: Add a new row in the appropriate section -3. **After architectural changes**: Update the ASCII diagram -4. **Date**: Update the `Last updated` comment at the top of this file +[arabic] +. *After completing a component*: Change its bar and percentage +. *After adding a component*: Add a new row in the appropriate section +. *After architectural changes*: Update the ASCII diagram +. *Date*: Update the `+Last updated+` comment at the top of this file -Progress bars use: `█` (filled) and `░` (empty), 10 characters wide. -Percentages: 0%, 10%, 20%, ... 100% (in 10% increments). +Progress bars use: `+█+` (filled) and `+░+` (empty), 10 characters wide. +Percentages: 0%, 10%, 20%, … 100% (in 10% increments). diff --git a/docs/API.md b/docs/API.adoc similarity index 56% rename from docs/API.md rename to docs/API.adoc index 6e44f7b..9bfa600 100644 --- a/docs/API.md +++ b/docs/API.adoc @@ -1,24 +1,22 @@ - -# Universal Language Connector - API Documentation +== Universal Language Connector - API Documentation -## Overview +=== Overview The Universal Language Connector provides three main APIs: -1. **LSP (Language Server Protocol)** - For editor integration via stdio -2. **HTTP REST API** - For web and programmatic access -3. **WebSocket API** - For real-time document updates +[arabic] +. *LSP (Language Server Protocol)* - For editor integration via stdio +. *HTTP REST API* - For web and programmatic access +. *WebSocket API* - For real-time document updates -## LSP API +=== LSP API -### Server Capabilities +==== Server Capabilities The server implements LSP 3.17 with the following capabilities: -```typescript +[source,typescript] +---- { textDocumentSync: "incremental", completionProvider: { @@ -35,16 +33,18 @@ The server implements LSP 3.17 with the following capabilities: ] } } -``` +---- -### LSP Methods +==== LSP Methods -#### textDocument/didOpen +===== textDocument/didOpen Notifies the server that a document has been opened. -**Parameters:** -```json +*Parameters:* + +[source,json] +---- { "textDocument": { "uri": "file:///path/to/document.md", @@ -53,14 +53,16 @@ Notifies the server that a document has been opened. "text": "# Document content" } } -``` +---- -#### textDocument/didChange +===== textDocument/didChange Notifies the server of document changes. -**Parameters:** -```json +*Parameters:* + +[source,json] +---- { "textDocument": { "uri": "file:///path/to/document.md", @@ -72,14 +74,16 @@ Notifies the server of document changes. } ] } -``` +---- -#### textDocument/completion +===== textDocument/completion Requests completion items at a given position. -**Parameters:** -```json +*Parameters:* + +[source,json] +---- { "textDocument": { "uri": "file:///path/to/document.md" @@ -89,10 +93,12 @@ Requests completion items at a given position. "character": 5 } } -``` +---- + +*Response:* -**Response:** -```json +[source,json] +---- [ { "label": "Convert to HTML", @@ -105,14 +111,16 @@ Requests completion items at a given position. } } ] -``` +---- -#### textDocument/hover +===== textDocument/hover Provides hover information (document statistics). -**Parameters:** -```json +*Parameters:* + +[source,json] +---- { "textDocument": { "uri": "file:///path/to/document.md" @@ -122,79 +130,90 @@ Provides hover information (document statistics). "character": 5 } } -``` +---- + +*Response:* -**Response:** -```json +[source,json] +---- { "contents": { "kind": "markdown", "value": "**Document Statistics**\n\n- Lines: 10\n- Words: 50\n- Characters: 300\n- Version: 2\n- Format: markdown" } } -``` +---- -#### workspace/executeCommand +===== workspace/executeCommand Executes a conversion command. -**Parameters:** -```json +*Parameters:* + +[source,json] +---- { "command": "convert.toHtml", "arguments": ["file:///path/to/document.md"] } -``` +---- -**Response:** -```json +*Response:* + +[source,json] +---- { "content": "

Converted HTML

", "format": "html", "warnings": [] } -``` +---- -## HTTP REST API +=== HTTP REST API -Base URL: `http://localhost:8080/api` +Base URL: `+http://localhost:8080/api+` -### Endpoints +==== Endpoints -#### POST /api/convert +===== POST /api/convert Convert document between formats. -**Request:** -```json +*Request:* + +[source,json] +---- { "content": "# Hello World", "from": "markdown", "to": "html" } -``` +---- -**Response:** -```json +*Response:* + +[source,json] +---- { "content": "

Hello World

", "from": "markdown", "to": "html", "warnings": [] } -``` +---- -**Status Codes:** -- `200 OK` - Conversion successful -- `400 Bad Request` - Invalid format or content -- `500 Internal Server Error` - Conversion failed +*Status Codes:* - `+200 OK+` - Conversion successful - +`+400 Bad Request+` - Invalid format or content - +`+500 Internal Server Error+` - Conversion failed -#### GET /api/documents +===== GET /api/documents List all documents in the server. -**Response:** -```json +*Response:* + +[source,json] +---- { "documents": [ { @@ -209,14 +228,16 @@ List all documents in the server. ], "count": 1 } -``` +---- -#### GET /api/documents/:id +===== GET /api/documents/:id Get a specific document by ID. -**Response:** -```json +*Response:* + +[source,json] +---- { "id": "550e8400-e29b-41d4-a716-446655440000", "uri": "file:///path/to/document.md", @@ -226,209 +247,235 @@ Get a specific document by ID. "created_at": "2025-11-22T12:00:00Z", "modified_at": "2025-11-22T12:05:00Z" } -``` +---- -**Status Codes:** -- `200 OK` - Document found -- `404 Not Found` - Document not found +*Status Codes:* - `+200 OK+` - Document found - `+404 Not Found+` - +Document not found -#### DELETE /api/documents/:id +===== DELETE /api/documents/:id Delete a document by ID. -**Status Codes:** -- `204 No Content` - Document deleted -- `404 Not Found` - Document not found +*Status Codes:* - `+204 No Content+` - Document deleted - +`+404 Not Found+` - Document not found -#### POST /api/validate +===== POST /api/validate Validate document format. -**Request:** -```json +*Request:* + +[source,json] +---- { "content": "# Valid Markdown", "format": "markdown" } -``` +---- + +*Response:* -**Response:** -```json +[source,json] +---- { "valid": true, "diagnostics": [] } -``` +---- For invalid content: -```json + +[source,json] +---- { "valid": false, "diagnostics": [ "Invalid JSON: unexpected token at line 1" ] } -``` +---- -#### GET /api/stats +===== GET /api/stats Get server statistics. -**Response:** -```json +*Response:* + +[source,json] +---- { "document_count": 5, "uptime_seconds": 3600, "version": "0.1.0" } -``` +---- -#### GET /api/health +===== GET /api/health Health check endpoint. -**Response:** -```json +*Response:* + +[source,json] +---- { "status": "healthy", "version": "0.1.0" } -``` +---- -### Error Responses +==== Error Responses All errors return a standard error object: -```json +[source,json] +---- { "error": "Error message description" } -``` +---- -## WebSocket API +=== WebSocket API -WebSocket URL: `ws://localhost:8081` +WebSocket URL: `+ws://localhost:8081+` -### Message Types +==== Message Types -#### Subscribe +===== Subscribe Subscribe to document updates. -**Client → Server:** -```json +*Client → Server:* + +[source,json] +---- { "type": "Subscribe", "document_id": "550e8400-e29b-41d4-a716-446655440000" } -``` +---- -#### Unsubscribe +===== Unsubscribe Unsubscribe from document updates. -**Client → Server:** -```json +*Client → Server:* + +[source,json] +---- { "type": "Unsubscribe", "document_id": "550e8400-e29b-41d4-a716-446655440000" } -``` +---- -#### DocumentUpdated +===== DocumentUpdated Document update notification. -**Server → Client:** -```json +*Server → Client:* + +[source,json] +---- { "type": "DocumentUpdated", "document_id": "550e8400-e29b-41d4-a716-446655440000", "content": "# Updated content", "timestamp": "2025-11-22T12:10:00Z" } -``` +---- -#### Ping/Pong +===== Ping/Pong Keep-alive messages. -**Client → Server:** -```json +*Client → Server:* + +[source,json] +---- { "type": "Ping" } -``` +---- -**Server → Client:** -```json +*Server → Client:* + +[source,json] +---- { "type": "Pong" } -``` +---- -#### Error +===== Error Error notification. -**Server → Client:** -```json +*Server → Client:* + +[source,json] +---- { "type": "Error", "message": "Error description" } -``` +---- -## Supported Formats +=== Supported Formats -### Format Identifiers +==== Format Identifiers -- `markdown` or `md` - Markdown -- `html` or `htm` - HTML -- `json` - JSON +* `+markdown+` or `+md+` - Markdown +* `+html+` or `+htm+` - HTML +* `+json+` - JSON -### Conversion Matrix +==== Conversion Matrix -| From | To | Status | Notes | -|----------|----------|--------|--------------------------------| -| Markdown | HTML | ✅ | Full support via pulldown-cmark | -| Markdown | JSON | ✅ | Structured representation | -| HTML | Markdown | ⚠️ | Lossy conversion | -| HTML | JSON | ✅ | DOM structure extraction | -| JSON | Markdown | ✅ | Key-value representation | -| JSON | HTML | ✅ | Via Markdown intermediary | +[cols=",,,",options="header",] +|=== +|From |To |Status |Notes +|Markdown |HTML |✅ |Full support via pulldown-cmark +|Markdown |JSON |✅ |Structured representation +|HTML |Markdown |⚠️ |Lossy conversion +|HTML |JSON |✅ |DOM structure extraction +|JSON |Markdown |✅ |Key-value representation +|JSON |HTML |✅ |Via Markdown intermediary +|=== -## Authentication & Security +=== Authentication & Security -Currently, the server does not implement authentication. For production use: +Currently, the server does not implement authentication. For production +use: -- Deploy behind a reverse proxy (nginx, Apache) -- Use TLS/SSL for encrypted connections -- Implement authentication at the proxy level -- Restrict access via firewall rules +* Deploy behind a reverse proxy (nginx, Apache) +* Use TLS/SSL for encrypted connections +* Implement authentication at the proxy level +* Restrict access via firewall rules -## Rate Limiting +=== Rate Limiting No rate limiting is currently implemented. Consider adding: -- Request rate limiting at proxy level -- Connection limits for WebSocket -- Resource usage monitoring +* Request rate limiting at proxy level +* Connection limits for WebSocket +* Resource usage monitoring -## CORS +=== CORS CORS is enabled for all origins in development. For production: -- Configure specific allowed origins -- Restrict allowed methods and headers -- Implement proper preflight handling +* Configure specific allowed origins +* Restrict allowed methods and headers +* Implement proper preflight handling -## Examples +=== Examples -### cURL Examples +==== cURL Examples -**Convert Markdown to HTML:** -```bash +*Convert Markdown to HTML:* + +[source,bash] +---- curl -X POST http://localhost:8080/api/convert \ -H "Content-Type: application/json" \ -d '{ @@ -436,22 +483,28 @@ curl -X POST http://localhost:8080/api/convert \ "from": "markdown", "to": "html" }' -``` +---- + +*List documents:* -**List documents:** -```bash +[source,bash] +---- curl http://localhost:8080/api/documents -``` +---- -**Health check:** -```bash +*Health check:* + +[source,bash] +---- curl http://localhost:8080/api/health -``` +---- + +==== JavaScript/Fetch Examples -### JavaScript/Fetch Examples +*Convert document:* -**Convert document:** -```javascript +[source,javascript] +---- const response = await fetch('http://localhost:8080/api/convert', { method: 'POST', headers: { 'Content-Type': 'application/json' }, @@ -464,10 +517,12 @@ const response = await fetch('http://localhost:8080/api/convert', { const result = await response.json(); console.log(result.content); -``` +---- + +*WebSocket connection:* -**WebSocket connection:** -```javascript +[source,javascript] +---- const ws = new WebSocket('ws://localhost:8081'); ws.onopen = () => { @@ -481,19 +536,20 @@ ws.onmessage = (event) => { const message = JSON.parse(event.data); console.log('Received:', message); }; -``` +---- -## Performance Considerations +=== Performance Considerations -- **Response Time Target:** <100ms for all operations -- **Memory Usage:** <50MB steady state -- **Startup Time:** <500ms -- **Concurrent Connections:** Supports 100+ simultaneous clients +* *Response Time Target:* <100ms for all operations +* *Memory Usage:* <50MB steady state +* *Startup Time:* <500ms +* *Concurrent Connections:* Supports 100+ simultaneous clients -## Versioning +=== Versioning -API version is included in all responses via the `version` field. +API version is included in all responses via the `+version+` field. -Current version: `0.1.0` +Current version: `+0.1.0+` -Future versions will maintain backward compatibility within major versions following Semantic Versioning (SemVer). +Future versions will maintain backward compatibility within major +versions following Semantic Versioning (SemVer). diff --git a/docs/tech-debt-2026-05-26.adoc b/docs/tech-debt-2026-05-26.adoc new file mode 100644 index 0000000..3a39e91 --- /dev/null +++ b/docs/tech-debt-2026-05-26.adoc @@ -0,0 +1,67 @@ +== Tech-Debt Audit — universal-language-server-plugin — 2026-05-26 + +*Source:* estate-wide automated scan 2026-05-26. *Companion:* +https://github.com/hyperpolymath/standards/tree/main/docs/audits[`+hyperpolymath/standards+` +2026-05-26-estate-*-debt audits]. *Combined severity:* `+MEDIUM+`. + +This file records the _raw findings_ — it does not by itself fix the +debt. Each section ends with a '`Recommended next move`' line; closing +the debt is follow-up work. + +=== 1. Proof debt + +No proof-bearing files (`+*.v+`, `+*.lean+`, `+*.agda+`, `+*.idr+`, +`+*.idr2+`, `+*.fst+`, `+*.dfy+`, `+*.tla+`, `+*.ads+`, `+*.adb+`) found +in this repo. + +*Recommended next move:* none. + +=== 2. Licence debt + +[cols=",",options="header",] +|=== +|Field |Value +|LICENSE file |`+LICENSE+` +|SPDX header |`+MPL-2.0+` +|Manifest licence |`+NONE+` +|Body classifier |`+Palimp-MPL-2.0+` +|Severity |`+ok+` +|=== + +*Recommended next move:* none for licence. + +=== 3. Documentation debt + +[cols=",",options="header",] +|=== +|Field |Value +|README lines |424 +|`+docs/+` files |2 +|`+docs/+` LoC |531 +|CHANGELOG.md |Y +|CONTRIBUTING.md |Y +|CODE_OF_CONDUCT.md |Y +|SECURITY.md |Y +|Severity |`+MEDIUM+` +|=== + +*Recommended next move:* introduce a `+docs/+` directory. The README at +424 lines has likely grown to do the work of `+docs/+` — split it into a +thin README + `+docs/architecture.md+`, `+docs/usage.md+`, etc. +Heavy-wiki exemplars to copy from: `+affinescript+`, `+boj-server+`, +`+echidna+`, `+hypatia+`. + +=== Cross-references + +* Estate proof-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-proof-debt.md+` +* Estate licence-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-licence-debt.md+` +* Estate documentation-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-documentation-debt.md+` + +''''' + +🤖 Generated by Claude Code estate-wide tech-debt scan (2026-05-26). +This file is informational — closing the debt is follow-up work owned by +the maintainer. diff --git a/docs/tech-debt-2026-05-26.md b/docs/tech-debt-2026-05-26.md deleted file mode 100644 index 1dc042c..0000000 --- a/docs/tech-debt-2026-05-26.md +++ /dev/null @@ -1,54 +0,0 @@ - -# Tech-Debt Audit — universal-language-server-plugin — 2026-05-26 - -**Source:** estate-wide automated scan 2026-05-26. -**Companion:** [`hyperpolymath/standards` 2026-05-26-estate-*-debt audits](https://github.com/hyperpolymath/standards/tree/main/docs/audits). -**Combined severity:** `MEDIUM`. - -This file records the *raw findings* — it does not by itself fix the debt. Each section ends with a 'Recommended next move' line; closing the debt is follow-up work. - -## 1. Proof debt - -No proof-bearing files (`*.v`, `*.lean`, `*.agda`, `*.idr`, `*.idr2`, `*.fst`, `*.dfy`, `*.tla`, `*.ads`, `*.adb`) found in this repo. - -**Recommended next move:** none. - -## 2. Licence debt - -| Field | Value | -|---|---| -| LICENSE file | `LICENSE` | -| SPDX header | `MPL-2.0` | -| Manifest licence | `NONE` | -| Body classifier | `Palimp-MPL-2.0` | -| Severity | `ok` | - -**Recommended next move:** none for licence. - -## 3. Documentation debt - -| Field | Value | -|---|---| -| README lines | 424 | -| `docs/` files | 2 | -| `docs/` LoC | 531 | -| CHANGELOG.md | Y | -| CONTRIBUTING.md | Y | -| CODE_OF_CONDUCT.md | Y | -| SECURITY.md | Y | -| Severity | `MEDIUM` | - -**Recommended next move:** introduce a `docs/` directory. The README at 424 lines has likely grown to do the work of `docs/` — split it into a thin README + `docs/architecture.md`, `docs/usage.md`, etc. Heavy-wiki exemplars to copy from: `affinescript`, `boj-server`, `echidna`, `hypatia`. - -## Cross-references - -- Estate proof-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-proof-debt.md` -- Estate licence-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-licence-debt.md` -- Estate documentation-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-documentation-debt.md` - ---- - -🤖 Generated by Claude Code estate-wide tech-debt scan (2026-05-26). This file is informational — closing the debt is follow-up work owned by the maintainer. diff --git a/examples/conversions/example.adoc b/examples/conversions/example.adoc new file mode 100644 index 0000000..129a683 --- /dev/null +++ b/examples/conversions/example.adoc @@ -0,0 +1,48 @@ +== Example Markdown Document + +This is an example Markdown document for testing the Universal Language +Connector. + +=== Features + +* *Bold text* +* _Italic text_ +* `+Code inline+` + +=== Code Block + +[source,rust] +---- +fn main() { + println!("Hello, Universal Connector!"); +} +---- + +=== Links + +https://github.com/universal-connector[Universal Language Connector] + +=== Lists + +[arabic] +. First item +. Second item +. Third item + +Unordered: - Apple - Banana - Cherry + +=== Blockquote + +____ +This is a blockquote It can span multiple lines +____ + +=== Table + +[cols=",",options="header",] +|=== +|Feature |Status +|LSP |✅ +|HTTP |✅ +|WebSocket |✅ +|=== diff --git a/examples/conversions/example.md b/examples/conversions/example.md deleted file mode 100644 index 14b8fed..0000000 --- a/examples/conversions/example.md +++ /dev/null @@ -1,49 +0,0 @@ - -# Example Markdown Document - -This is an example Markdown document for testing the Universal Language Connector. - -## Features - -- **Bold text** -- *Italic text* -- `Code inline` - -## Code Block - -```rust -fn main() { - println!("Hello, Universal Connector!"); -} -``` - -## Links - -[Universal Language Connector](https://github.com/universal-connector) - -## Lists - -1. First item -2. Second item -3. Third item - -Unordered: -- Apple -- Banana -- Cherry - -## Blockquote - -> This is a blockquote -> It can span multiple lines - -## Table - -| Feature | Status | -|---------|--------| -| LSP | ✅ | -| HTTP | ✅ | -| WebSocket | ✅ | diff --git a/llm-warmup-dev.adoc b/llm-warmup-dev.adoc new file mode 100644 index 0000000..7b874b7 --- /dev/null +++ b/llm-warmup-dev.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — universal-language-server-plugin (Developer) + +=== What is universal-language-server-plugin? + +See README.adoc for overview. + +=== Key Commands + +* `+just setup+` — set up development environment +* `+just build+` — build the project +* `+just test+` — run tests +* `+just doctor+` — diagnose issues +* `+just heal+` — attempt auto-repair + +=== Quick Context + +* License: MPL-2.0 +* Part of hyperpolymath ecosystem +* See EXPLAINME.adoc for architecture diff --git a/llm-warmup-dev.md b/llm-warmup-dev.md deleted file mode 100644 index b3f9ce1..0000000 --- a/llm-warmup-dev.md +++ /dev/null @@ -1,20 +0,0 @@ - -# LLM Warmup — universal-language-server-plugin (Developer) - -## What is universal-language-server-plugin? -See README.adoc for overview. - -## Key Commands -- `just setup` — set up development environment -- `just build` — build the project -- `just test` — run tests -- `just doctor` — diagnose issues -- `just heal` — attempt auto-repair - -## Quick Context -- License: MPL-2.0 -- Part of hyperpolymath ecosystem -- See EXPLAINME.adoc for architecture diff --git a/llm-warmup-user.adoc b/llm-warmup-user.adoc new file mode 100644 index 0000000..3223c14 --- /dev/null +++ b/llm-warmup-user.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — universal-language-server-plugin (User) + +=== What is universal-language-server-plugin? + +See README.adoc for overview. + +=== Key Commands + +* `+just setup+` — set up development environment +* `+just build+` — build the project +* `+just test+` — run tests +* `+just doctor+` — diagnose issues +* `+just heal+` — attempt auto-repair + +=== Quick Context + +* License: MPL-2.0 +* Part of hyperpolymath ecosystem +* See EXPLAINME.adoc for architecture diff --git a/llm-warmup-user.md b/llm-warmup-user.md deleted file mode 100644 index f2fc646..0000000 --- a/llm-warmup-user.md +++ /dev/null @@ -1,20 +0,0 @@ - -# LLM Warmup — universal-language-server-plugin (User) - -## What is universal-language-server-plugin? -See README.adoc for overview. - -## Key Commands -- `just setup` — set up development environment -- `just build` — build the project -- `just test` — run tests -- `just doctor` — diagnose issues -- `just heal` — attempt auto-repair - -## Quick Context -- License: MPL-2.0 -- Part of hyperpolymath ecosystem -- See EXPLAINME.adoc for architecture