@unrdf/diataxis-kit 26.4.2

package/README.md

@@ -0,0 +1,425 @@
+# @unrdf/diataxis-kit
+
+Diátaxis documentation kit for monorepo package inventory and deterministic doc scaffold generation. Automatically discovers all workspace packages and generates documentation scaffolds using the Diátaxis framework (Tutorials, How-to Guides, Reference, Explanation).
+
+## Features
+
+- **🔍 Workspace Discovery**: Automatically discovers 40+ packages from pnpm/yarn/npm workspaces
+- **📊 Package Inventory**: Generates `inventory.json` with metadata for all packages
+- **🎯 Evidence Collection**: Gathers evidence from README, docs/, examples/, src/, and package.json
+- **📚 Diátaxis Classification**: Classifies documentation into four types based on evidence
+- **🔧 Deterministic Generation**: Produces identical outputs across multiple runs with `DETERMINISTIC=1`
+- **✅ Coverage Verification**: Ensures all packages have required documentation stubs
+- **📈 Coverage Reporting**: Generates detailed coverage and confidence reports
+
+## Quick Start
+
+```bash
+# Generate inventory and scaffolds
+pnpm run run
+
+# Verify all packages have required documentation
+pnpm run verify
+
+# Generate coverage report
+pnpm run report
+
+# Run tests (determinism + inventory + verification)
+pnpm test
+```
+
+## File Structure
+
+```
+packages/diataxis-kit/
+├── src/
+│   ├── index.mjs                 # Main entry point
+│   ├── inventory.mjs             # Workspace package discovery
+│   ├── evidence.mjs              # Evidence collection from package files
+│   ├── classify.mjs              # Diátaxis classification logic
+│   ├── reference-extractor.mjs   # API reference extraction
+│   ├── scaffold.mjs              # Markdown doc generation
+│   ├── diataxis-schema.mjs        # Schema definitions and validation
+│   ├── stable-json.mjs           # Deterministic JSON stringification
+│   └── hash.mjs                  # SHA256 hashing utilities
+├── bin/
+│   ├── run.mjs                   # Main orchestrator (discovery → evidence → classify → scaffold)
+│   ├── verify.mjs                # Verification gate (coverage checker)
+│   └── report.mjs                # Coverage and confidence reporter
+├── test/
+│   ├── determinism.test.mjs      # Determinism verification tests
+│   ├── inventory.test.mjs        # Inventory discovery tests
+│   ├── verify-gate.test.mjs      # Verification gate tests
+│   └── report.test.mjs           # Report generation tests
+├── ARTIFACTS/diataxis/           # Generated inventory and diataxis.json files
+└── OUT/                          # Generated markdown scaffolds
+```
+
+## How It Works
+
+### 1. Discovery Phase (inventory.mjs)
+
+Scans workspace configuration files and discovers all packages:
+
+```javascript
+const packages = await discoverPackages('/path/to/workspace');
+// Returns: [
+//   { name, dir, version, exports, bin, keywords, hasReadme, hasDocs, hasExamples, ... }
+// ]
+```
+
+### 2. Evidence Collection (evidence.mjs)
+
+Gathers evidence from each package:
+
+- **README**: Content and headings
+- **Examples**: Files and snippets
+- **Docs**: Directory listing and snippets
+- **Source**: Top-level export files
+- **Package.json**: Exports, bin entries, keywords
+- **Fingerprint**: SHA256 hash of evidence
+
+### 3. Classification (classify.mjs)
+
+Classifies packages using evidence-based rules:
+
+- **Tutorials**: Generated from examples/ and README "Getting Started" sections
+- **How-tos**: Generated from README "Usage", "Configuration" sections and keywords
+- **Reference**: Extracted from package.json exports/bin and README API sections
+- **Explanation**: Generated from keywords, README intro, and docs/ presence
+
+Each classification item includes:
+- Title and description
+- Confidence score (0-1) based on evidence strength
+- Source tracking (which evidence contributed)
+
+### 4. Scaffold Generation (scaffold.mjs)
+
+Generates markdown files with:
+
+- **Frontmatter**: Package name, version, generated timestamp, confidence score, proof hash
+- **Content**: Sections specific to each Diátaxis type
+- **Proof block**: SHA256 hash of evidence inputs
+- **Directory structure**: `tutorials/`, `how-to/`, `reference/`, `explanation/`
+
+### 5. Verification & Reporting
+
+**Verify** (verify.mjs): Checks all packages have:
+- At least 1 tutorial stub
+- At least 2 how-to stubs
+- Reference documentation
+- Explanation documentation
+
+**Report** (report.mjs): Generates coverage statistics:
+- Total packages and documentation type coverage
+- Confidence metrics (avg, min, max)
+- Lowest confidence packages
+- Missing evidence sources
+- Quick fix suggestions
+
+## Determinism
+
+Run with `DETERMINISTIC=1` to ensure byte-identical outputs:
+
+```bash
+# First run
+DETERMINISTIC=1 pnpm run run
+
+# Second run produces identical artifacts
+DETERMINISTIC=1 pnpm run run
+
+# Hashes match: 100% determinism guaranteed
+sha256sum ARTIFACTS/diataxis/inventory.json
+```
+
+Determinism guarantees:
+- Fixed timestamps: `2000-01-01T00:00:00.000Z`
+- Stable JSON key ordering
+- Lexicographic sorting of packages and documentation
+- Identical SHA256 hashes across runs
+
+## Testing
+
+```bash
+# Run all tests
+pnpm test
+
+# Run determinism tests (2x pipeline execution)
+pnpm run test:determinism
+
+# Run inventory discovery tests
+pnpm run test:inventory
+
+# Run verification gate tests
+pnpm run test:verify
+
+# Clean artifacts before running tests
+pnpm run clean
+```
+
+Test Coverage:
+- **Determinism Tests** (4/4 passing):
+  - Inventory and artifacts hashes match across runs
+  - Timestamps fixed in deterministic mode
+  - Stable ordering verified for all packages
+  - Proof hashes valid and consistent
+
+- **Inventory Tests** (7/7 passing):
+  - 86 packages discovered (>= 42 required)
+  - Required fields present and valid
+  - Unique package names
+  - Directory existence verified
+  - Entry validation working
+
+- **Verification Tests** (13/13 passing):
+  - All packages pass coverage requirements
+  - Missing tutorials detected
+  - Missing how-tos detected
+  - Missing reference detected
+  - Missing explanation detected
+
+## Package Exports
+
+```javascript
+// Import the full kit
+import * as kit from '@unrdf/diataxis-kit';
+
+// Individual exports
+import { discoverPackages } from '@unrdf/diataxis-kit/inventory';
+import { collectEvidence } from '@unrdf/diataxis-kit/evidence';
+import { classifyPackage } from '@unrdf/diataxis-kit/classify';
+import { generateScaffold } from '@unrdf/diataxis-kit/scaffold';
+import { stableStringify } from '@unrdf/diataxis-kit/stable-json';
+import { hashObject } from '@unrdf/diataxis-kit/hash';
+```
+
+## CLI Tools
+
+### diataxis-run (bin/run.mjs)
+
+Full pipeline orchestrator:
+
+```bash
+# Generate inventory, classify packages, and create scaffolds
+pnpm run run
+
+# With deterministic mode
+DETERMINISTIC=1 pnpm run run
+```
+
+Output:
+- `ARTIFACTS/diataxis/inventory.json`: Package metadata
+- `ARTIFACTS/diataxis/<pkgName>/diataxis.json`: Per-package classification
+- `OUT/<pkgName>/`: Markdown scaffolds (tutorials/, how-to/, reference/, explanation/)
+
+### diataxis-verify (bin/verify.mjs)
+
+Coverage verification gate:
+
+```bash
+# Check all packages have required documentation
+pnpm run verify
+
+# With options
+pnpm run verify --json                    # JSON output
+pnpm run verify --fail-fast              # Exit on first failure
+pnpm run verify --threshold 5            # Fail only if >5 packages fail
+pnpm run verify --help                   # Show help
+```
+
+Exit codes:
+- 0: All packages meet requirements
+- 1: One or more packages fail requirements
+
+### diataxis-report (bin/report.mjs)
+
+Coverage and confidence reporting:
+
+```bash
+# Generate coverage report
+pnpm run report
+
+# With options
+pnpm run report --json                          # JSON output
+pnpm run report --csv                          # CSV output
+pnpm run report --top 10                       # Show top 10 packages
+pnpm run report --filter "@unrdf/"            # Filter by keyword
+pnpm run report --sort confidence             # Sort by confidence
+pnpm run report --help                        # Show help
+```
+
+## Example Output
+
+### Inventory (ARTIFACTS/diataxis/inventory.json)
+
+```json
+{
+  "generatedAt": "2000-01-01T00:00:00.000Z",
+  "packageCount": 86,
+  "packages": [
+    {
+      "name": "@unrdf/core",
+      "version": "5.0.0-beta.1",
+      "dir": "/home/user/unrdf/packages/core"
+    }
+  ]
+}
+```
+
+### Diataxis Classification (ARTIFACTS/diataxis/@unrdf/core/diataxis.json)
+
+```json
+{
+  "packageName": "@unrdf/core",
+  "version": "5.0.0-beta.1",
+  "generatedAt": "2000-01-01T00:00:00.000Z",
+  "confidence": {
+    "tutorials": 1.0,
+    "howtos": 0.75,
+    "reference": 0.7,
+    "explanation": 1.0
+  },
+  "tutorials": [
+    {
+      "id": "tutorial-getting-started",
+      "title": "Getting Started with @unrdf/core",
+      "goal": "Learn the basics of RDF and the @unrdf/core library",
+      "prerequisites": ["Node.js knowledge", "RDF fundamentals"],
+      "stepsOutline": ["Installation", "Creating a store", "Loading RDF data"],
+      "confidenceScore": 1.0,
+      "source": ["readme", "examples"]
+    }
+  ],
+  "howtos": [
+    {
+      "id": "howto-handle-errors",
+      "title": "Handle Errors",
+      "task": "Implement error handling for @unrdf/core",
+      "context": "When you need robust error handling in production",
+      "steps": ["Set up try-catch blocks", "Handle common error types"],
+      "confidenceScore": 0.5,
+      "source": ["tests"]
+    }
+  ],
+  "reference": {
+    "id": "reference",
+    "title": "@unrdf/core API Reference",
+    "items": [
+      {
+        "name": "createStore",
+        "type": "export",
+        "description": "Create a new RDF triple store",
+        "example": null
+      }
+    ],
+    "confidenceScore": 0.7,
+    "source": ["exports", "readme"]
+  },
+  "explanation": {
+    "id": "explanation",
+    "title": "Understanding @unrdf/core",
+    "concepts": ["RDF", "SPARQL", "knowledge graphs"],
+    "architecture": "Modular design with pluggable backends...",
+    "tradeoffs": ["Flexibility vs. ease of use"],
+    "confidenceScore": 1.0,
+    "source": ["readme", "docs", "keywords"]
+  },
+  "evidence": {
+    "readmeHeadings": ["Features", "Installation", "Quick Start"],
+    "docsFiles": ["API.md", "CONTRIBUTING.md"],
+    "examplesFiles": ["basic-operations.mjs"],
+    "fingerprint": "6f6e066e6135b49a61da8a2e3004973..."
+  }
+}
+```
+
+### Report Output
+
+```
+Diátaxis Coverage Report
+========================
+
+SUMMARY
+-------
+Total packages:     86
+With tutorials:     86 (100%)
+With 2+ how-tos:    86 (100%)
+With reference:     86 (100%)
+With explanation:   86 (100%)
+
+CONFIDENCE
+----------
+Tutorials   : avg=0.44, min=0.00, max=1.00
+Howtos      : avg=0.52, min=0.00, max=0.75
+Reference   : avg=0.36, min=0.00, max=0.80
+Explanation : avg=0.58, min=0.00, max=1.00
+
+LOWEST CONFIDENCE (5 packages)
+----------------------------
+ 1. @unrdf/docs-site (0.00) - no examples/, no docs/, empty README, no bin entries
+ ...
+```
+
+## Implementation Details
+
+### Stable JSON Stringification
+
+Keys are always sorted lexicographically:
+
+```javascript
+const input = { b: 1, a: 2, arr: [2, 1] };
+const output = stableStringify(input);
+// Result: { "a": 2, "arr": [2, 1], "b": 1 }
+```
+
+### Confidence Scoring
+
+Each documentation type has specific confidence weights:
+
+- **Tutorials**: +0.3 examples/, +0.3 README, +0.1 keywords
+- **How-tos**: +0.25 README sections, +0.25 bin, +0.25 keywords, +0.25 tests
+- **Reference**: +0.5 exports, +0.3 bin, +0.2 README API
+- **Explanation**: +0.3 README, +0.3 docs/, +0.4 keywords
+
+### Evidence Fingerprinting
+
+Each package's evidence is hashed to detect changes:
+
+```javascript
+fingerprint = sha256(
+  readmeHeadings.join('|') +
+  examplesFiles.join('|') +
+  docsFiles.join('|') +
+  srcFiles.join('|') +
+  keywords.join('|')
+)
+```
+
+## Constraints
+
+- **Node.js ESM only** (.mjs files)
+- **No TypeScript** (JSDoc for type hints)
+- **No external dependencies** (except standard library)
+- **< 500 lines per file** (enforced)
+- **100% JSDoc coverage**
+- **Zero entropy** in deterministic mode
+
+## Performance
+
+- Discovery: ~100ms for 86 packages
+- Evidence collection: ~50ms per package
+- Classification: ~30ms per package
+- Scaffold generation: ~20ms per package
+- Total: ~5-10 seconds for full monorepo
+
+## Future Improvements
+
+- [ ] Cross-package relationship detection
+- [ ] API surface diffing between versions
+- [ ] Integration with documentation generators (Nextra, Vitepress)
+- [ ] Custom classification rules per package
+- [ ] Automated fix suggestions with git integration
+
+## License
+
+Part of the UNRDF monorepo. See [LICENSE](../../LICENSE).