chore: update project structure, naming, and add reporting infrastructure

- Update all 7 phase docs with source/target location references (golang/ for Go source, dotnet/ for .NET version) - Rename NATS.Server to ZB.MOM.NatsNet.Server in phase 4-7 docs - Update solution layout to dotnet/src/ and dotnet/tests/ structure - Create CLAUDE.md with project summary and phase links - Update .gitignore: track porting.db, add standard .NET patterns - Add golang/nats-server as git submodule - Add reports/generate-report.sh and pre-commit hook - Add documentation_rules.md to version control
2026-02-26 06:38:56 -05:00
parent ca6ed0f09f
commit 8d68f63e6c
13 changed files with 547 additions and 63 deletions
--- a/documentation_rules.md
+++ b/documentation_rules.md
@@ -0,0 +1,318 @@
+# Documentation Rules
+
+This document defines the documentation system for the NATS .NET server project. It provides guidelines for generating, updating, and maintaining project documentation.
+
+The documentation is intended for internal team reference — explaining what the system is, how it works, how to extend it, and how to debug it.
+
+## Folder Structure
+
+```
+Documentation/
+├── Instructions/              # Guidelines for LLMs (meta-documentation)
+│   └── (this file serves as the single instructions reference)
+│
+├── GettingStarted/            # Onboarding, prerequisites, first run
+├── Protocol/                  # Wire protocol, parser, command types
+├── Subscriptions/             # SubList trie, subject matching, wildcards
+├── Server/                    # NatsServer orchestrator, NatsClient handler
+├── Configuration/             # NatsOptions, appsettings, CLI arguments
+├── Operations/                # Deployment, monitoring, health checks, troubleshooting
+└── Plans/                     # Design documents and implementation plans
+```
+
+Future module folders (add as modules are ported):
+
+```
+├── Authentication/            # Auth mechanisms, NKeys, JWT, accounts
+├── Clustering/                # Routes, gateways, leaf nodes
+├── JetStream/                 # Streams, consumers, storage, RAFT
+├── Monitoring/                # HTTP endpoints (/varz, /connz, etc.)
+├── WebSocket/                 # WebSocket transport
+└── TLS/                       # TLS configuration and setup
+```
+
+---
+
+## Style Guide
+
+### Tone and Voice
+
+- **Technical and direct** — no marketing language. Avoid "powerful", "robust", "seamless", "blazing fast".
+- **Assume the reader is a .NET developer** — don't explain dependency injection, async/await, or LINQ basics.
+- **Explain "why" not just "what"** — document reasoning behind patterns and decisions.
+- **Use present tense** — "The parser reads..." not "The parser will read..."
+
+### Formatting Rules
+
+| Aspect | Convention |
+|--------|------------|
+| File names | `PascalCase.md` |
+| H1 (`#`) | Document title only, Title Case |
+| H2 (`##`) | Major sections, Title Case |
+| H3+ (`###`) | Subsections, Sentence case |
+| Code blocks | Always specify language (`csharp`, `json`, `bash`, `xml`) |
+| Code snippets | 5-25 lines typical; include class/method context |
+| Cross-references | Relative paths: `[See SubList](../Subscriptions/SubList.md)` |
+| Inline code | Backticks for code refs: `NatsServer`, `SubList.Match()`, `NatsOptions` |
+| Lists | Bullets for unordered, numbers for sequential steps |
+| Tables | For structured reference (config options, command formats) |
+
+### Naming Conventions
+
+- Match code terminology exactly: `SubList` not "Subject List", `NatsClient` not "NATS Client Handler"
+- Use backticks for all code references: `NatsParser`, `appsettings.json`, `dotnet test`
+- Spell out acronyms on first use: "NATS Adaptive Edge Messaging (NATS)" — common acronyms that don't need expansion: API, JSON, TCP, HTTP, TLS, JWT
+
+### Code Snippet Guidelines
+
+**Do:**
+- Copy snippets from actual source files
+- Include enough context (class name, method signature)
+- Specify the language in code blocks
+- Show 5-25 line examples
+
+```csharp
+// Good — shows class context
+public sealed class NatsServer : IMessageRouter, ISubListAccess, IDisposable
+{
+    public async Task StartAsync(CancellationToken ct)
+    {
+        _listener = new Socket(AddressFamily.InterNetwork, SocketType.Stream, ProtocolType.Tcp);
+        _listener.Bind(new IPEndPoint(IPAddress.Parse(_options.Host), _options.Port));
+        _listener.Listen(128);
+    }
+}
+```
+
+**Don't:**
+- Invent example code that doesn't exist in the codebase
+- Include 100+ line dumps without explanation
+- Use pseudocode when real code is available
+- Omit the language specifier on code blocks
+
+### Structure Conventions
+
+Every documentation file must include:
+
+1. **Title and purpose** — H1 heading with 1-2 sentence description
+2. **Key concepts** — if the topic requires background understanding
+3. **Code examples** — embedded snippets from actual codebase
+4. **Configuration** — if the component has configurable options
+5. **Related documentation** — links to related topics
+
+Organize content from general to specific:
+1. Overview/introduction
+2. Key concepts
+3. Basic usage
+4. Advanced usage / internals
+5. Configuration
+6. Troubleshooting
+7. Related documentation
+
+End each document with:
+```markdown
+## Related Documentation
+
+- [Related Topic](../Component/Topic.md)
+```
+
+### What to Avoid
+
+- Don't document the obvious (e.g., "The constructor creates a new instance")
+- Don't duplicate source code comments — reference the file instead
+- Don't include temporary information (dates, version numbers, "coming soon")
+- Don't over-explain .NET basics
+
+---
+
+## Generating Documentation
+
+### Document Types
+
+Each component folder should contain these standard files:
+
+| File | Purpose |
+|------|---------|
+| `Overview.md` | What the component does, key concepts, architecture |
+| `Development.md` | How to add/modify features, patterns to follow |
+| `Configuration.md` | All configurable options with defaults and examples |
+| `Troubleshooting.md` | Common issues, error messages, debugging steps |
+
+Create additional topic-specific files as needed (e.g., `Protocol/Parser.md`, `Subscriptions/SubList.md`).
+
+### Generation Process
+
+1. **Identify scope** — which component folder does this belong to? (See Component Map below)
+2. **Read source code** — understand the current implementation, identify key classes/methods/patterns, note configuration options
+3. **Check existing documentation** — avoid duplication, cross-reference rather than repeat
+4. **Write documentation** — follow the style guide, use real code snippets
+5. **Verify accuracy** — confirm snippets match source, verify file paths and class names, test commands
+
+### Creating New Component Folders
+
+1. Create the folder under `Documentation/`
+2. Add at minimum `Overview.md`
+3. Add other standard files as content warrants
+4. Update the Component Map section below
+5. Add cross-references from related documentation
+
+---
+
+## Updating Documentation
+
+### Update Triggers
+
+| Code Change | Update These Docs |
+|-------------|-------------------|
+| New protocol command | `Protocol/` relevant file |
+| Parser modified | `Protocol/Parser.md` |
+| Subject matching changed | `Subscriptions/SubjectMatch.md` |
+| SubList trie modified | `Subscriptions/SubList.md` |
+| New subscription type | `Subscriptions/Overview.md` |
+| NatsServer changed | `Server/Overview.md` |
+| NatsClient changed | `Server/Client.md` |
+| Config option added/removed | Component's `Configuration.md` |
+| NatsOptions changed | `Configuration/Overview.md` |
+| Host startup changed | `Operations/Deployment.md` + `Configuration/` |
+| New test patterns | Corresponding component docs |
+| Auth mechanism added | `Authentication/` (create if needed) |
+| Clustering added | `Clustering/` (create if needed) |
+
+### Update Process
+
+1. **Identify affected documentation** — use the Component Map to determine which docs need updating
+2. **Read current documentation** — understand existing structure before making changes
+3. **Make targeted updates** — only modify sections affected by the code change; don't rewrite unaffected sections
+4. **Update code snippets** — if the code change affects documented examples, update them to match
+5. **Update cross-references** — add links to newly related docs, remove links to deleted content
+6. **Add verification comment** — at the bottom: `<!-- Last verified against codebase: YYYY-MM-DD -->`
+
+### Deletion Handling
+
+- When code is removed, remove corresponding doc sections
+- When code is renamed, update all references (docs, snippets, cross-reference links)
+- If an entire feature is removed, delete the doc file and update any index/overview docs
+- Search all docs for links to removed content
+
+### What Not to Update
+
+- Don't reformat documentation that wasn't affected by the code change
+- Don't update examples that still work correctly
+- Don't add new content unrelated to the code change
+- Don't change writing style in unaffected sections
+
+---
+
+## Component Map
+
+### Source to Documentation Mapping
+
+| Source Path | Documentation Folder |
+|-------------|---------------------|
+| `src/NATS.Server/Protocol/NatsParser.cs` | `Protocol/` |
+| `src/NATS.Server/Protocol/NatsProtocol.cs` | `Protocol/` |
+| `src/NATS.Server/Subscriptions/SubList.cs` | `Subscriptions/` |
+| `src/NATS.Server/Subscriptions/SubjectMatch.cs` | `Subscriptions/` |
+| `src/NATS.Server/Subscriptions/Subscription.cs` | `Subscriptions/` |
+| `src/NATS.Server/Subscriptions/SubListResult.cs` | `Subscriptions/` |
+| `src/NATS.Server/NatsServer.cs` | `Server/` |
+| `src/NATS.Server/NatsClient.cs` | `Server/` |
+| `src/NATS.Server/NatsOptions.cs` | `Configuration/` |
+| `src/NATS.Server.Host/Program.cs` | `Operations/` and `Configuration/` |
+| `tests/NATS.Server.Tests/` | Document in corresponding component |
+| `golang/nats-server/server/` | Reference material (not documented separately) |
+
+### Component Details
+
+#### Protocol/
+
+Documents the wire protocol and parser.
+
+**Source paths:**
+- `src/NATS.Server/Protocol/NatsParser.cs` — state machine parser
+- `src/NATS.Server/Protocol/NatsProtocol.cs` — constants, ServerInfo, ClientOptions
+
+**Typical files:**
+- `Overview.md` — NATS protocol format, command types, wire format
+- `Parser.md` — Parser implementation, `TryParse` flow, state machine
+- `Commands.md` — Individual command formats (PUB, SUB, UNSUB, MSG, etc.)
+
+#### Subscriptions/
+
+Documents subject matching and the subscription trie.
+
+**Source paths:**
+- `src/NATS.Server/Subscriptions/SubList.cs` — trie + cache
+- `src/NATS.Server/Subscriptions/SubjectMatch.cs` — validation and wildcard matching
+- `src/NATS.Server/Subscriptions/Subscription.cs` — subscription model
+- `src/NATS.Server/Subscriptions/SubListResult.cs` — match result container
+
+**Typical files:**
+- `Overview.md` — Subject namespace, wildcard rules, queue groups
+- `SubList.md` — Trie internals, cache invalidation, thread safety
+- `SubjectMatch.md` — Validation rules, wildcard matching algorithm
+
+#### Server/
+
+Documents the server orchestrator and client connection handler.
+
+**Source paths:**
+- `src/NATS.Server/NatsServer.cs` — accept loop, message routing
+- `src/NATS.Server/NatsClient.cs` — per-connection read/write, subscription tracking
+
+**Typical files:**
+- `Overview.md` — Server architecture, connection lifecycle, message flow
+- `Client.md` — Client connection handling, command dispatch, write serialization
+- `MessageRouting.md` — How messages flow from PUB to subscribers
+
+#### Configuration/
+
+Documents server configuration options.
+
+**Source paths:**
+- `src/NATS.Server/NatsOptions.cs` — configuration model
+- `src/NATS.Server.Host/Program.cs` — CLI argument parsing, Serilog setup
+
+**Typical files:**
+- `Overview.md` — All options with defaults and descriptions
+- `Logging.md` — Serilog configuration, log levels, LogContext usage
+
+#### Operations/
+
+Documents deployment and operational concerns.
+
+**Source paths:**
+- `src/NATS.Server.Host/` — host application
+
+**Typical files:**
+- `Overview.md` — Running the server, CLI arguments
+- `Deployment.md` — Deployment procedures
+- `Troubleshooting.md` — Common issues and debugging
+
+#### GettingStarted/
+
+Documents onboarding and project overview.
+
+**Typical files:**
+- `Setup.md` — Prerequisites, building, running
+- `Architecture.md` — System overview, Go reference mapping
+- `Development.md` — Development workflow, testing, contributing
+
+### Ambiguous Cases
+
+| Code Type | Document In |
+|-----------|-------------|
+| Logging setup | `Configuration/Logging.md` |
+| Integration tests | `Operations/Testing.md` or corresponding component |
+| Shared interfaces (`IMessageRouter`, `ISubListAccess`) | `Server/Overview.md` |
+| Go reference code | Don't document separately; reference in `.NET` component docs |
+
+### Adding New Components
+
+When a new module is ported (Authentication, Clustering, JetStream, etc.):
+
+1. Create a new folder under `Documentation/`
+2. Add at minimum `Overview.md`
+3. Add this mapping table entry
+4. Update CLAUDE.md documentation index if it has one
+5. Cross-reference from related component docs