Skip to content

Commit bc18c01

Browse files
author
RECTOR
committed
docs: Comprehensive documentation audit and gap fill (#84)
- Add 12 missing CLI commands to cli-commands.md: - check-size: Account size analysis - security analyze: Vulnerability detection - audit generate: Security checklist generation - fuzz generate/run/corpus: Fuzz testing commands - anchor generate/idl/space: Anchor integration - metaplex validate/generate/types: Metaplex integration - Update generate command options: - Add --lang, --target, --watch, --dry-run, --backup, --show-diff - Document multi-language generation (Python, Go, Ruby) - Fix watch mode documentation (was marked as coming soon) - Create new editor documentation: - editors/vscode.md: Full VSCode extension guide - editors/neovim.md: Neovim plugin with Tree-sitter/LSP - editors/emacs.md: Emacs major mode with lsp-mode - editors/sublime.md: Sublime Text package - Create new framework guides: - frameworks/anchor.md: Complete Anchor integration guide - frameworks/metaplex.md: Metaplex Token Metadata validation - Update sidebar navigation with Frameworks section - Add DOCUMENTATION_GAP_ANALYSIS.md report Documentation coverage improved from 37% to 100% for CLI commands.
1 parent 26b620d commit bc18c01

File tree

9 files changed

+2811
-14
lines changed

9 files changed

+2811
-14
lines changed

‎DOCUMENTATION_GAP_ANALYSIS.md‎

Lines changed: 313 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,313 @@
1+
# LUMOS Documentation Gap Analysis Report
2+
3+
**Date:** 2025-12-08
4+
**Status:** Issue #84 - Documentation Audit & Gap Analysis
5+
6+
---
7+
8+
## Executive Summary
9+
10+
Comprehensive audit of LUMOS documentation reveals **significant gaps** in CLI command coverage and missing dedicated pages for editor integrations and framework guides. Current coverage is approximately **40%** of CLI features documented.
11+
12+
---
13+
14+
## Feature Inventory
15+
16+
### CLI Commands (19 total commands/subcommands)
17+
18+
| Command | Documented | Priority |
19+
|---------|------------|----------|
20+
| `generate` | Partial (missing --watch, --backup, --show-diff) | HIGH |
21+
| `validate` | Yes | - |
22+
| `init` | Yes | - |
23+
| `check` | Yes | - |
24+
| `check-size` | **NO** | HIGH |
25+
| `diff` | Yes | - |
26+
| `migrate` | Yes | - |
27+
| `check-compat` | Yes | - |
28+
| `security analyze` | **NO** | HIGH |
29+
| `audit generate` | **NO** | HIGH |
30+
| `fuzz generate` | **NO** | MEDIUM |
31+
| `fuzz run` | **NO** | MEDIUM |
32+
| `fuzz corpus` | **NO** | MEDIUM |
33+
| `anchor generate` | **NO** | CRITICAL |
34+
| `anchor idl` | **NO** | CRITICAL |
35+
| `anchor space` | **NO** | CRITICAL |
36+
| `metaplex validate` | **NO** | MEDIUM |
37+
| `metaplex generate` | **NO** | MEDIUM |
38+
| `metaplex types` | **NO** | MEDIUM |
39+
40+
**Documented: 7/19 (37%)**
41+
42+
### LSP Features
43+
44+
| Feature | Documented | Priority |
45+
|---------|------------|----------|
46+
| Diagnostics (real-time errors) | Mentioned in FAQ | HIGH |
47+
| Auto-completion | Mentioned | HIGH |
48+
| Hover documentation | Not documented | MEDIUM |
49+
| Editor installation | Partial | HIGH |
50+
51+
### Editor Integrations
52+
53+
| Editor | Dedicated Page | Priority |
54+
|--------|----------------|----------|
55+
| VSCode | **NO** (mentioned only) | CRITICAL |
56+
| IntelliJ IDEA | Yes | - |
57+
| Neovim | **NO** | HIGH |
58+
| Emacs | **NO** | MEDIUM |
59+
| Sublime Text | **NO** | MEDIUM |
60+
61+
### Framework Guides
62+
63+
| Framework | Page Exists | Priority |
64+
|-----------|-------------|----------|
65+
| Native Solana | Yes | - |
66+
| Seahorse | Yes (stub) | LOW |
67+
| Anchor | **NO** | CRITICAL |
68+
| Metaplex | **NO** | HIGH |
69+
70+
### Multi-Language Generation
71+
72+
| Language | Type Mapping Docs | Generator Guide | Priority |
73+
|----------|-------------------|-----------------|----------|
74+
| Rust | Yes | Yes | - |
75+
| TypeScript | Yes | Yes | - |
76+
| Python | Yes (api/python-types.md) | Partial | MEDIUM |
77+
| Go | Yes (api/go-types.md) | Partial | MEDIUM |
78+
| Ruby | Yes (api/ruby-types.md) | Partial | MEDIUM |
79+
80+
---
81+
82+
## Critical Gaps (Must Fix)
83+
84+
### 1. Anchor Framework Commands (CRITICAL)
85+
86+
The `anchor` subcommands are completely undocumented despite being a core feature:
87+
88+
```bash
89+
lumos anchor generate <schema> # Generate complete Anchor program
90+
lumos anchor idl <schema> # Generate Anchor IDL JSON
91+
lumos anchor space <schema> # Calculate account space constants
92+
```
93+
94+
**Impact:** Users cannot discover Anchor integration capabilities.
95+
96+
### 2. VSCode Editor Page (CRITICAL)
97+
98+
No dedicated documentation page for VSCode extension despite:
99+
- Being the most popular editor
100+
- Extension published on marketplace
101+
- Features: syntax highlighting, IntelliSense, diagnostics, snippets
102+
103+
**Files mentioning but not documenting:**
104+
- `faq.md` - brief mention
105+
- `installation.md` - no VSCode setup
106+
- `changelog/v010.md` - release notes only
107+
108+
### 3. Security Analysis Command (HIGH)
109+
110+
`lumos security analyze` is undocumented:
111+
112+
```bash
113+
lumos security analyze <schema> [--format text|json] [--strict]
114+
```
115+
116+
**Detects:**
117+
- Missing signer checks
118+
- Potential integer overflow
119+
- Unchecked owner validation
120+
- PDA seed security issues
121+
122+
### 4. Account Size Analysis (HIGH)
123+
124+
`lumos check-size` is undocumented:
125+
126+
```bash
127+
lumos check-size <schema> [--format text|json]
128+
```
129+
130+
**Features:**
131+
- Calculate exact Borsh serialization size
132+
- Warn about Solana account limits (10KB)
133+
- Show per-field breakdown
134+
135+
### 5. Audit Checklist Generation (HIGH)
136+
137+
`lumos audit generate` is undocumented:
138+
139+
```bash
140+
lumos audit generate <schema> [--output FILE] [--format markdown|json]
141+
```
142+
143+
**Generates:** Security audit checklist based on schema patterns.
144+
145+
---
146+
147+
## Medium Priority Gaps
148+
149+
### 6. Fuzz Testing Commands
150+
151+
Three fuzz testing commands undocumented:
152+
153+
```bash
154+
lumos fuzz generate <schema> # Generate fuzz targets
155+
lumos fuzz run <schema> --type-name <type> # Run fuzzing
156+
lumos fuzz corpus <schema> # Generate test corpus
157+
```
158+
159+
### 7. Metaplex Integration
160+
161+
Three Metaplex commands undocumented:
162+
163+
```bash
164+
lumos metaplex validate <schema> # Validate against Metaplex standards
165+
lumos metaplex generate <schema> # Generate Metaplex-compatible code
166+
lumos metaplex types # Show standard Metaplex types
167+
```
168+
169+
### 8. Neovim Editor Page
170+
171+
nvim-lumos exists but no documentation:
172+
- Tree-sitter integration
173+
- LSP configuration
174+
- Keybinding setup
175+
176+
### 9. Generate Command Options
177+
178+
Missing documentation for:
179+
- `--watch` - Watch mode for auto-regeneration
180+
- `--backup` - Backup before overwriting
181+
- `--show-diff` - Preview changes before writing
182+
- `--target` - Target framework selection (auto/native/anchor)
183+
184+
---
185+
186+
## Low Priority Gaps
187+
188+
### 10. Emacs & Sublime Text Pages
189+
190+
Both plugins exist but no dedicated docs.
191+
192+
### 11. Seahorse Integration
193+
194+
Stub page exists - needs full content.
195+
196+
---
197+
198+
## Current Documentation Structure (35 files)
199+
200+
```
201+
docs/
202+
├── api/
203+
│ ├── attributes.md ✓
204+
│ ├── cli-commands.md ⚠️ (37% coverage)
205+
│ ├── generated-code.md ✓
206+
│ ├── go-types.md ✓
207+
│ ├── python-types.md ✓
208+
│ ├── ruby-types.md ✓
209+
│ └── types.md ✓
210+
├── changelog/
211+
│ ├── v010.md ✓
212+
│ ├── v011.md ✓
213+
│ └── v020.md ✓
214+
├── editors/
215+
│ └── intellij.md ✓
216+
├── examples/versioning/
217+
│ ├── adding-optional-field.md ✓
218+
│ ├── changing-field-type.md ✓
219+
│ └── deprecating-field.md ✓
220+
├── frameworks/
221+
│ ├── native-solana.md ✓
222+
│ └── seahorse.md ⚠️ (stub)
223+
├── getting-started/
224+
│ ├── installation.md ✓
225+
│ ├── introduction.md ✓
226+
│ └── quick-start.md ✓
227+
├── guides/
228+
│ ├── borsh-internals.md ✓
229+
│ ├── client-interaction.md ✓
230+
│ ├── debugging.md ✓
231+
│ ├── error-handling.md ✓
232+
│ ├── future.md ✓
233+
│ ├── lumos-vs-codama.md ✓
234+
│ ├── migration-guide.md ✓
235+
│ ├── multi-file-schemas.md ✓
236+
│ ├── npm-package.md ✓
237+
│ ├── schema-migrations.md ✓
238+
│ ├── versioning.md ✓
239+
│ └── vision.md ✓
240+
├── reference/
241+
│ └── example.md (placeholder)
242+
├── faq.md ✓
243+
└── index.mdx ✓
244+
```
245+
246+
---
247+
248+
## Recommended Actions
249+
250+
### Phase 1: Critical Fixes (Immediate)
251+
252+
1. **Add Anchor Commands to cli-commands.md** (~200 lines)
253+
- `anchor generate`, `anchor idl`, `anchor space`
254+
- Full options, examples, use cases
255+
256+
2. **Create editors/vscode.md** (~150 lines)
257+
- Installation from marketplace
258+
- Features overview
259+
- Configuration options
260+
- Troubleshooting
261+
262+
3. **Add Security & Audit Commands** (~150 lines)
263+
- `security analyze` documentation
264+
- `audit generate` documentation
265+
- Example outputs
266+
267+
4. **Add check-size Command** (~80 lines)
268+
- Usage, options, examples
269+
- Size calculation details
270+
271+
### Phase 2: High Priority
272+
273+
5. **Create frameworks/anchor.md** (~300 lines)
274+
- Complete Anchor workflow
275+
- IDL generation
276+
- Account contexts
277+
- Client generation
278+
279+
6. **Create editors/neovim.md** (~100 lines)
280+
281+
7. **Add Fuzz Testing Commands** (~100 lines)
282+
283+
### Phase 3: Medium Priority
284+
285+
8. **Create frameworks/metaplex.md** (~200 lines)
286+
9. **Create editors/emacs.md** (~80 lines)
287+
10. **Create editors/sublime.md** (~80 lines)
288+
11. **Document generate command options** (~50 lines)
289+
290+
---
291+
292+
## Success Metrics
293+
294+
| Metric | Current | Target |
295+
|--------|---------|--------|
296+
| CLI Command Coverage | 37% | 100% |
297+
| Editor Pages | 1/5 | 5/5 |
298+
| Framework Guides | 1/4 | 4/4 |
299+
| LSP Feature Docs | 0% | 100% |
300+
301+
---
302+
303+
## Next Steps
304+
305+
1. Start with Phase 1 Critical Fixes
306+
2. Add missing CLI commands to `api/cli-commands.md`
307+
3. Create `editors/vscode.md`
308+
4. Create `frameworks/anchor.md`
309+
5. Update sidebar in `astro.config.mjs`
310+
311+
---
312+
313+
*Generated as part of Issue #84 Documentation Audit*

‎astro.config.mjs‎

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -85,7 +85,19 @@ export default defineConfig({
8585
{
8686
label: 'Editors',
8787
items: [
88-
{ label: 'IntelliJ IDEA', slug: 'editors/intellij', badge: { text: 'New', variant: 'success' } },
88+
{ label: 'VS Code', slug: 'editors/vscode', badge: { text: 'New', variant: 'success' } },
89+
{ label: 'IntelliJ IDEA', slug: 'editors/intellij' },
90+
{ label: 'Neovim', slug: 'editors/neovim', badge: { text: 'New', variant: 'success' } },
91+
{ label: 'Emacs', slug: 'editors/emacs', badge: { text: 'New', variant: 'success' } },
92+
{ label: 'Sublime Text', slug: 'editors/sublime', badge: { text: 'New', variant: 'success' } },
93+
],
94+
},
95+
{
96+
label: 'Frameworks',
97+
items: [
98+
{ label: 'Anchor', slug: 'frameworks/anchor', badge: { text: 'New', variant: 'success' } },
99+
{ label: 'Native Solana', slug: 'frameworks/native-solana' },
100+
{ label: 'Metaplex', slug: 'frameworks/metaplex', badge: { text: 'New', variant: 'success' } },
89101
],
90102
},
91103
{

0 commit comments

Comments
 (0)