personal-projects/leo-claude-mktplace
Template
0
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(plugins): implement Sprint 4 commands (#241-#258)

Browse Source 
Sprint 4 - Plugin Commands implementation adding 18 new user-facing
commands across 8 plugins as part of V5.2.0 Plugin Enhancements.

**projman:**
- #241: /sprint-diagram - Mermaid visualization of sprint issues

**pr-review:**
- #242: Confidence threshold config (PR_REVIEW_CONFIDENCE_THRESHOLD)
- #243: /pr-diff - Formatted diff with inline review comments

**data-platform:**
- #244: /data-quality - DataFrame quality checks (nulls, duplicates, outliers)
- #245: /lineage-viz - dbt lineage as Mermaid diagrams
- #246: /dbt-test - Formatted dbt test runner

**viz-platform:**
- #247: /chart-export - Export charts to PNG/SVG/PDF via kaleido
- #248: /accessibility-check - Color blind validation (WCAG contrast)
- #249: /breakpoints - Responsive layout configuration

**contract-validator:**
- #250: /dependency-graph - Plugin dependency visualization

**doc-guardian:**
- #251: /changelog-gen - Generate changelog from conventional commits
- #252: /doc-coverage - Documentation coverage metrics
- #253: /stale-docs - Flag outdated documentation

**claude-config-maintainer:**
- #254: /config-diff - Track CLAUDE.md changes over time
- #255: /config-lint - 31 lint rules for CLAUDE.md best practices

**cmdb-assistant:**
- #256: /cmdb-topology - Infrastructure topology diagrams
- #257: /change-audit - NetBox audit trail queries
- #258: /ip-conflicts - Detect IP conflicts and overlaps

Closes #241, #242, #243, #244, #245, #246, #247, #248, #249,
#250, #251, #252, #253, #254, #255, #256, #257, #258

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Leo Miranda
2026-01-28 12:02:26 -05:00
parent 8a957b1b69
commit 9698e8724d
36 changed files with 4295 additions and 22 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
plugins/doc-guardian/README.md
View File

@@ -22,6 +22,9 @@ doc-guardian monitors your code changes via hooks:
|---------|-------------|
| `/doc-audit` | Full project scan - reports all drift without changing anything |
| `/doc-sync` | Apply all pending documentation updates in one commit |
| `/changelog-gen` | Generate changelog from conventional commits in Keep-a-Changelog format |
| `/doc-coverage` | Calculate documentation coverage percentage for functions and classes |
| `/stale-docs` | Detect documentation files that are stale relative to their associated code |
## Hooks
@@ -33,6 +36,8 @@ doc-guardian monitors your code changes via hooks:
- **Version Drift**: Python 3.9 in docs but 3.11 in pyproject.toml
- **Missing Docs**: Public functions without docstrings
- **Stale Examples**: CLI examples that no longer work
- **Low Coverage**: Undocumented functions and classes
- **Stale Files**: Documentation that hasn't been updated alongside code changes
## Installation

3
plugins/doc-guardian/claude-md-integration.md
View File

@@ -11,6 +11,9 @@ This project uses doc-guardian for automatic documentation synchronization.
- Pending updates are queued silently during work
- Run `/doc-sync` to apply all pending documentation updates
- Run `/doc-audit` for a full project documentation review
- Run `/changelog-gen` to generate changelog from conventional commits
- Run `/doc-coverage` to check documentation coverage metrics
- Run `/stale-docs` to find documentation that may be outdated
### Documentation Files Tracked
- README.md (root and subdirectories)

109
plugins/doc-guardian/commands/changelog-gen.md Normal file
View File

@@ -0,0 +1,109 @@
---
description: Generate changelog from conventional commits in Keep-a-Changelog format
---
# Changelog Generation
Generate a changelog entry from conventional commits.
## Process
1. **Identify Commit Range**
- Default: commits since last tag
- Optional: specify range (e.g., `v1.0.0..HEAD`)
- Detect if this is first release (no previous tags)
2. **Parse Conventional Commits**
Extract from commit messages following the pattern:
```
<type>(<scope>): <description>
[optional body]
[optional footer(s)]
```
**Recognized Types:**
| Type | Changelog Section |
|------|------------------|
| `feat` | Added |
| `fix` | Fixed |
| `docs` | Documentation |
| `perf` | Performance |
| `refactor` | Changed |
| `style` | Changed |
| `test` | Testing |
| `build` | Build |
| `ci` | CI/CD |
| `chore` | Maintenance |
| `BREAKING CHANGE` | Breaking Changes |
3. **Group by Type**
Organize commits into Keep-a-Changelog sections:
- Breaking Changes (if any `!` suffix or `BREAKING CHANGE` footer)
- Added (feat)
- Changed (refactor, style, perf)
- Deprecated
- Removed
- Fixed (fix)
- Security
4. **Format Entries**
For each commit:
- Extract scope (if present) as prefix
- Use description as entry text
- Link to commit hash if repository URL available
- Include PR/issue references from footer
5. **Output Format**
```markdown
## [Unreleased]
### Breaking Changes
- **scope**: Description of breaking change
### Added
- **scope**: New feature description
- Another feature without scope
### Changed
- **scope**: Refactoring description
### Fixed
- **scope**: Bug fix description
### Documentation
- Updated README with new examples
```
## Options
| Flag | Description | Default |
|------|-------------|---------|
| `--from <tag>` | Start from specific tag | Latest tag |
| `--to <ref>` | End at specific ref | HEAD |
| `--version <ver>` | Set version header | [Unreleased] |
| `--include-merge` | Include merge commits | false |
| `--group-by-scope` | Group by scope within sections | false |
## Integration
The generated output is designed to be copied directly into CHANGELOG.md:
- Follows [Keep a Changelog](https://keepachangelog.com) format
- Compatible with semantic versioning
- Excludes non-user-facing commits (chore, ci, test by default)
## Example Usage
```
/changelog-gen
/changelog-gen --from v1.0.0 --version 1.1.0
/changelog-gen --include-merge --group-by-scope
```
## Non-Conventional Commits
Commits not following conventional format are:
- Listed under "Other" section
- Flagged for manual categorization
- Skipped if `--strict` flag is used

128
plugins/doc-guardian/commands/doc-coverage.md Normal file
View File

@@ -0,0 +1,128 @@
---
description: Calculate documentation coverage percentage for functions and classes
---
# Documentation Coverage
Analyze codebase to calculate documentation coverage metrics.
## Process
1. **Scan Source Files**
Identify all documentable items:
**Python:**
- Functions (def)
- Classes
- Methods
- Module-level docstrings
**JavaScript/TypeScript:**
- Functions (function, arrow functions)
- Classes
- Methods
- JSDoc comments
**Other Languages:**
- Adapt patterns for Go, Rust, etc.
2. **Determine Documentation Status**
For each item, check:
- Has docstring/JSDoc comment
- Docstring is non-empty and meaningful (not just `pass` or `TODO`)
- Parameters are documented (for detailed mode)
- Return type is documented (for detailed mode)
3. **Calculate Metrics**
```
Coverage = (Documented Items / Total Items) * 100
```
**Levels:**
- Basic: Item has any docstring
- Standard: Docstring describes purpose
- Complete: All parameters and return documented
4. **Output Format**
```
## Documentation Coverage Report
### Summary
- Total documentable items: 156
- Documented: 142
- Coverage: 91.0%
### By Type
| Type | Total | Documented | Coverage |
|------|-------|------------|----------|
| Functions | 89 | 85 | 95.5% |
| Classes | 23 | 21 | 91.3% |
| Methods | 44 | 36 | 81.8% |
### By Directory
| Path | Total | Documented | Coverage |
|------|-------|------------|----------|
| src/api/ | 34 | 32 | 94.1% |
| src/utils/ | 28 | 28 | 100.0% |
| src/models/ | 45 | 38 | 84.4% |
| tests/ | 49 | 44 | 89.8% |
### Undocumented Items
- [ ] src/api/handlers.py:45 `create_order()`
- [ ] src/api/handlers.py:78 `update_order()`
- [ ] src/models/user.py:23 `UserModel.validate()`
```
## Options
| Flag | Description | Default |
|------|-------------|---------|
| `--path <dir>` | Scan specific directory | Project root |
| `--exclude <glob>` | Exclude files matching pattern | `**/test_*,**/*_test.*` |
| `--include-private` | Include private members (_prefixed) | false |
| `--include-tests` | Include test files | false |
| `--min-coverage <pct>` | Fail if below threshold | none |
| `--format <fmt>` | Output format (table, json, markdown) | table |
| `--detailed` | Check parameter/return docs | false |
## Thresholds
Common coverage targets:
| Level | Coverage | Description |
|-------|----------|-------------|
| Minimal | 60% | Basic documentation exists |
| Good | 80% | Most public APIs documented |
| Excellent | 95% | Comprehensive documentation |
## CI Integration
Use `--min-coverage` to enforce standards:
```bash
# Fail if coverage drops below 80%
claude /doc-coverage --min-coverage 80
```
Exit codes:
- 0: Coverage meets threshold (or no threshold set)
- 1: Coverage below threshold
## Example Usage
```
/doc-coverage
/doc-coverage --path src/
/doc-coverage --min-coverage 85 --exclude "**/generated/**"
/doc-coverage --detailed --include-private
```
## Language Detection
File extensions mapped to documentation patterns:
| Extension | Language | Doc Format |
|-----------|----------|------------|
| .py | Python | Docstrings (""") |
| .js, .ts | JavaScript/TypeScript | JSDoc (/** */) |
| .go | Go | // comments above |
| .rs | Rust | /// doc comments |
| .rb | Ruby | # comments, YARD |
| .java | Java | Javadoc (/** */) |

143
plugins/doc-guardian/commands/stale-docs.md Normal file
View File

@@ -0,0 +1,143 @@
---
description: Detect documentation files that are stale relative to their associated code
---
# Stale Documentation Detection
Identify documentation files that may be outdated based on commit history.
## Process
1. **Map Documentation to Code**
Build relationships between docs and code:
| Doc File | Related Code |
|----------|--------------|
| README.md | All files in same directory |
| API.md | src/api/**/* |
| CLAUDE.md | Configuration files, scripts |
| docs/module.md | src/module/**/* |
| Component.md | Component.tsx, Component.css |
2. **Analyze Commit History**
For each doc file:
- Find last commit that modified the doc
- Find last commit that modified related code
- Count commits to code since doc was updated
3. **Calculate Staleness**
```
Commits Behind = Code Commits Since Doc Update
Days Behind = Days Since Doc Update - Days Since Code Update
```
4. **Apply Threshold**
Default: Flag if documentation is 10+ commits behind related code
**Staleness Levels:**
| Commits Behind | Level | Action |
|----------------|-------|--------|
| 0-5 | Fresh | No action needed |
| 6-10 | Aging | Review recommended |
| 11-20 | Stale | Update needed |
| 20+ | Critical | Immediate attention |
5. **Output Format**
```
## Stale Documentation Report
### Critical (20+ commits behind)
| File | Last Updated | Commits Behind | Related Code |
|------|--------------|----------------|--------------|
| docs/api.md | 2024-01-15 | 34 | src/api/**/* |
### Stale (11-20 commits behind)
| File | Last Updated | Commits Behind | Related Code |
|------|--------------|----------------|--------------|
| README.md | 2024-02-20 | 15 | package.json, src/index.ts |
### Aging (6-10 commits behind)
| File | Last Updated | Commits Behind | Related Code |
|------|--------------|----------------|--------------|
| CONTRIBUTING.md | 2024-03-01 | 8 | .github/*, scripts/* |
### Summary
- Critical: 1 file
- Stale: 1 file
- Aging: 1 file
- Fresh: 12 files
- Total documentation files: 15
```
## Options
| Flag | Description | Default |
|------|-------------|---------|
| `--threshold <n>` | Commits behind to flag as stale | 10 |
| `--days` | Use days instead of commits | false |
| `--path <dir>` | Scan specific directory | Project root |
| `--doc-pattern <glob>` | Pattern for doc files | `**/*.md,**/README*` |
| `--ignore <glob>` | Ignore specific docs | `CHANGELOG.md,LICENSE` |
| `--show-fresh` | Include fresh docs in output | false |
| `--format <fmt>` | Output format (table, json) | table |
## Relationship Detection
How docs are mapped to code:
1. **Same Directory**
- `src/api/README.md` relates to `src/api/**/*`
2. **Name Matching**
- `docs/auth.md` relates to `**/auth.*`, `**/auth/**`
3. **Explicit Links**
- Parse `[link](path)` in docs to find related files
4. **Import Analysis**
- Track which modules are referenced in code examples
## Configuration
Create `.doc-guardian.yml` to customize mappings:
```yaml
stale-docs:
threshold: 10
mappings:
- doc: docs/deployment.md
code:
- Dockerfile
- docker-compose.yml
- .github/workflows/deploy.yml
- doc: ARCHITECTURE.md
code:
- src/**/*
ignore:
- CHANGELOG.md
- LICENSE
- vendor/**
```
## Example Usage
```
/stale-docs
/stale-docs --threshold 5
/stale-docs --days --threshold 30
/stale-docs --path docs/ --show-fresh
```
## Integration with doc-audit
`/stale-docs` focuses specifically on commit-based staleness, while `/doc-audit` checks content accuracy. Use both for comprehensive documentation health:
```
/doc-audit # Check for broken references and content drift
/stale-docs # Check for files that may need review
```
## Exit Codes
- 0: No critical or stale documentation
- 1: Stale documentation found (useful for CI)
- 2: Critical documentation found