feat: Implement DeepWiki documentation generation tools

- Added `__init__.py` in `codexlens/tools` for documentation generation. - Created `deepwiki_generator.py` to handle symbol extraction and markdown generation. - Introduced `MockMarkdownGenerator` for testing purposes. - Implemented `DeepWikiGenerator` class for managing documentation generation and file processing. - Added unit tests for `DeepWikiStore` to ensure proper functionality and error handling. - Created tests for DeepWiki TypeScript types matching.
2026-03-07 16:41:06 +08:00 · 2026-03-05 18:30:56 +08:00
parent 0bfae3fd1a
commit fb4f6e718e
62 changed files with 7500 additions and 68 deletions
--- a/.claude/skills/spec-generator/specs/document-standards.md
+++ b/.claude/skills/spec-generator/specs/document-standards.md
@@ -82,6 +82,7 @@ Examples:
 | `spec-config.json` | 1 | Session configuration and state |
 | `discovery-context.json` | 1 | Codebase exploration results (optional) |
 | `refined-requirements.json` | 1.5 | Confirmed requirements after discussion |
+| `glossary.json` | 2 | Terminology glossary for cross-document consistency |
 | `product-brief.md` | 2 | Product brief document |
 | `requirements.md` | 3 | PRD document |
 | `architecture.md` | 4 | Architecture decisions document |
@@ -169,6 +170,17 @@ Derived from [REQ-001](requirements.md#req-001).
    "dimensions": ["string array - 3-5 exploration dimensions"]
  },
  "has_codebase": "boolean",
+  "spec_type": "service|api|library|platform (required) - type of specification",
+  "iteration_count": "number (required, default 0) - number of auto-fix iterations completed",
+  "iteration_history": [
+    {
+      "iteration": "number",
+      "timestamp": "ISO8601",
+      "readiness_score": "number (0-100)",
+      "errors_found": "number",
+      "phases_fixed": ["number array - phase numbers that were re-generated"]
+    }
+  ],
  "refined_requirements_file": "string (optional) - path to refined-requirements.json",
  "phasesCompleted": [
    {
@@ -237,6 +249,34 @@ Derived from [REQ-001](requirements.md#req-001).

 ---

+## glossary.json Schema
+
+```json
+{
+  "session_id": "string (required) - matches spec-config.json",
+  "generated_at": "ISO8601 (required)",
+  "version": "number (required, default 1) - incremented on updates",
+  "terms": [
+    {
+      "term": "string (required) - the canonical term",
+      "definition": "string (required) - concise definition",
+      "aliases": ["string array - acceptable alternative names"],
+      "first_defined_in": "string (required) - source document path",
+      "category": "core|technical|business (required)"
+    }
+  ]
+}
+```
+
+### Glossary Usage Rules
+
+- Terms MUST be defined before first use in any document
+- All documents MUST use the canonical term from glossary; aliases are for reference only
+- Glossary is generated in Phase 2 and injected into all subsequent phase prompts
+- Phase 6 validates glossary compliance across all documents
+
+---
+
 ## Validation Checklist

 - [ ] Every document starts with valid YAML frontmatter
@@ -246,3 +286,7 @@ Derived from [REQ-001](requirements.md#req-001).
 - [ ] Heading hierarchy is correct (no skipped levels)
 - [ ] Technical identifiers use correct prefixes
 - [ ] Output files are in the correct directory
+- [ ] `glossary.json` created with >= 5 terms
+- [ ] `spec_type` field set in spec-config.json
+- [ ] All documents use glossary terms consistently
+- [ ] Non-Goals section present in product brief (if applicable)
--- a/.claude/skills/spec-generator/specs/glossary-template.json
+++ b/.claude/skills/spec-generator/specs/glossary-template.json
@@ -0,0 +1,29 @@
+{
+  "$schema": "glossary-v1",
+  "description": "Template for terminology glossary used across spec-generator documents",
+  "session_id": "",
+  "generated_at": "",
+  "version": 1,
+  "terms": [
+    {
+      "term": "",
+      "definition": "",
+      "aliases": [],
+      "first_defined_in": "product-brief.md",
+      "category": "core"
+    }
+  ],
+  "_usage_notes": {
+    "category_values": {
+      "core": "Domain-specific terms central to the product (e.g., 'Workspace', 'Session')",
+      "technical": "Technical terms specific to the architecture (e.g., 'gRPC', 'event bus')",
+      "business": "Business/process terms (e.g., 'Sprint', 'SLA', 'stakeholder')"
+    },
+    "rules": [
+      "Terms MUST be defined before first use in any document",
+      "All documents MUST use the canonical 'term' field consistently",
+      "Aliases are for reference only - prefer canonical term in all documents",
+      "Phase 6 validates glossary compliance across all documents"
+    ]
+  }
+}
--- a/.claude/skills/spec-generator/specs/quality-gates.md
+++ b/.claude/skills/spec-generator/specs/quality-gates.md
@@ -111,6 +111,9 @@ Content provides sufficient detail for execution teams.
 | Success metrics | >= 2 quantifiable metrics | Warning |
 | Scope boundaries | In-scope and out-of-scope listed | Warning |
 | Multi-perspective | >= 2 CLI perspectives synthesized | Info |
+| Terminology glossary generated | glossary.json created with >= 5 terms | Warning |
+| Non-Goals section present | At least 1 non-goal with rationale | Warning |
+| Concepts section present | Terminology table in product brief | Warning |

 ### Phase 3: Requirements (PRD)

@@ -122,6 +125,8 @@ Content provides sufficient detail for execution teams.
 | Non-functional requirements | >= 1 (performance, security, etc.) | Warning |
 | User stories | >= 1 per Must-have requirement | Warning |
 | Traceability | Requirements trace to product brief goals | Warning |
+| RFC 2119 keywords used | Behavioral requirements use MUST/SHOULD/MAY | Warning |
+| Data model defined | Core entities have field-level definitions | Warning |

 ### Phase 4: Architecture

@@ -134,6 +139,12 @@ Content provides sufficient detail for execution teams.
 | Integration points | External systems/APIs identified | Warning |
 | Data model | Key entities and relationships described | Warning |
 | Codebase mapping | Mapped to existing code (if has_codebase) | Info |
+| State machine defined | >= 1 lifecycle state diagram (if service/platform type) | Warning |
+| Configuration model defined | All config fields with type/default/constraint (if service type) | Warning |
+| Error handling strategy | Per-component error classification and recovery | Warning |
+| Observability metrics | >= 3 metrics defined (if service/platform type) | Warning |
+| Trust model defined | Trust levels documented (if service type) | Info |
+| Implementation guidance | Key decisions for implementers listed | Info |

 ### Phase 5: Epics & Stories

@@ -171,6 +182,8 @@ Product Brief goals  ->  Requirements (each goal has >= 1 requirement)
 Requirements         ->  Architecture (each Must requirement has design coverage)
 Requirements         ->  Epics (each Must requirement appears in >= 1 story)
 Architecture ADRs    ->  Epics (tech choices reflected in implementation stories)
+Glossary terms       ->  All Documents (core terms used consistently)
+Non-Goals (Brief)    ->  Requirements + Epics (no contradictions)
 ```

 ### Consistency Checks
@@ -181,6 +194,9 @@ Architecture ADRs    ->  Epics (tech choices reflected in implementation stories
 | User personas | Brief + PRD + Epics | Same user names/roles throughout |
 | Scope | Brief + PRD | PRD scope does not exceed brief scope |
 | Tech stack | Architecture + Epics | Stories reference correct technologies |
+| Glossary compliance | All | Core terms match glossary.json definitions, no synonym drift |
+| Scope containment | Brief + PRD | PRD requirements do not introduce scope beyond brief boundaries |
+| Non-Goals respected | Brief + PRD + Epics | No requirement/story contradicts explicit Non-Goals |

 ### Traceability Matrix Format

@@ -217,3 +233,23 @@ Architecture ADRs    ->  Epics (tech choices reflected in implementation stories
 - Consider additional ADR alternatives
 - Story estimation hints missing
 - Mermaid diagrams could be more detailed
+
+---
+
+## Iteration Quality Tracking
+
+When Phase 6.5 (Auto-Fix) is triggered:
+
+| Iteration | Expected Improvement | Max Iterations |
+|-----------|---------------------|----------------|
+| 1st | Fix all Error-severity issues | - |
+| 2nd | Fix remaining Warnings, improve scores | Max reached |
+
+### Iteration Exit Criteria
+
+| Condition | Action |
+|-----------|--------|
+| Overall score >= 80% after fix | Pass, proceed to handoff |
+| Overall score 60-79% after 2 iterations | Review, proceed with caveats |
+| Overall score < 60% after 2 iterations | Fail, manual intervention required |
+| No Error-severity issues remaining | Eligible for handoff regardless of score |