Skip to content

fix(docs): separate mermaid node declarations and add dynamic diagram generation with tests#1215

Merged
WilliamBerryiii merged 14 commits intomainfrom
fix/docs/mermaid-diagram-parse-error
Mar 30, 2026
Merged

fix(docs): separate mermaid node declarations and add dynamic diagram generation with tests#1215
WilliamBerryiii merged 14 commits intomainfrom
fix/docs/mermaid-diagram-parse-error

Conversation

@WilliamBerryiii
Copy link
Copy Markdown
Member

@WilliamBerryiii WilliamBerryiii commented Mar 26, 2026

fix(docs): separate mermaid node declarations and add dynamic diagram generation with tests

Description

Fixed a Mermaid diagram parse error in the Docusaurus homepage caused by node declarations sharing lines. Replaced the hardcoded 15-line Mermaid diagram string with a dynamic buildCollectionDiagram() function that generates graph TD syntax from collectionCards data, placing each node declaration on its own line. Synced 6 stale artifact counts across 9 collections against authoritative .collection.yml manifests and added a metaCollections export for hve-core-all and installer meta-collection counts.

Test Coverage

Added tests to reach 107 tests across 8 suites covering diagram structure, Mermaid syntax validation, data integrity, and artifact count cross-validation against YAML manifests. Switched the test environment from jsdom to happy-dom to resolve Jest hang issues and removed the --passWithNoTests flag.

CI and Tooling

Added a root-level docs:test convenience script and created tsconfig.json for TypeScript language server type resolution, eliminating @types/jest linting errors.

Review Comment Fixes

Addressed code review feedback:

  • Disconnected INS node — Removed the standalone INS (installer) node from buildCollectionDiagram() since installer is a meta-collection and should not appear as an unconnected graph node.
  • Untyped meta parameter — Added a MetaCollections interface to collectionCards.ts and applied it to the meta parameter in buildCollectionDiagram(), replacing the implicit any type.
  • Dependency pinning — Pinned @happy-dom/jest-environment from ^20.8.8 to exact 20.8.8 in docs/docusaurus/package.json to resolve a CodeQL dependency-pinning alert.

Dependency Review Workflow Fix

Fixed the "Review Dependencies" CI check, which was permanently failing on all PRs due to a snapshot bootstrapping problem:

  • Root cause: component-detection-dependency-submission-action only ran on pull_request events, so the base branch (main) never had a dependency snapshot. The action retried indefinitely waiting for a base snapshot that could never exist.
  • Fix: Added a push trigger on main and develop branches so merged commits create dependency snapshots. Scoped the Dependency Review step to pull_request events only with an if conditional. Enabled retry-on-snapshot-warnings: true with a 120-second timeout for transient snapshot delays.
  • Bootstrapping: The first base snapshot will be created when this PR merges to main, unblocking future PRs.
  • Pre-existing vulnerabilities: path-to-regexp v0.1.12 (high) and serialize-javascript v7.0.4 (moderate) are Docusaurus transitive dependencies, not introduced by this PR.

Related Issue(s)

None

Type of Change

Select all that apply:

Code & Documentation:

  • Bug fix (non-breaking change fixing an issue)
  • New feature (non-breaking change adding functionality)
  • Breaking change (fix or feature causing existing functionality to change)
  • Documentation update

Infrastructure & Configuration:

  • GitHub Actions workflow
  • Linting configuration (markdown, PowerShell, etc.)
  • Security configuration
  • DevContainer configuration
  • Dependency update

AI Artifacts:

  • Reviewed contribution with prompt-builder agent and addressed all feedback
  • Copilot instructions (.github/instructions/*.instructions.md)
  • Copilot prompt (.github/prompts/*.prompt.md)
  • Copilot agent (.github/agents/*.agent.md)
  • Copilot skill (.github/skills/*/SKILL.md)

> Note for AI Artifact Contributors:
>
> - Agents: Research, indexing/referencing other project (using standard VS Code GitHub Copilot/MCP tools), planning, and general implementation agents likely already exist. Review .github/agents/ before creating new ones.
> - Skills: Must include both bash and PowerShell scripts. See Skills.
> - Model Versions: Only contributions targeting the latest Anthropic and OpenAI models will be accepted. Older model versions (e.g., GPT-3.5, Claude 3) will be rejected.
> - See Agents Not Accepted and Model Version Requirements.

Other:

  • Script/automation (.ps1, .sh, .py)
  • Other (please describe):

Testing

Automated Test Results

  • 107 tests passed across 8 suites with no failures.
  • buildCollectionDiagram.test.ts — 12 tests validating graph structure (starts with graph TD, HCA node, card nodes, edges, hyphen replacement, empty cards, meta values, line count) and 4 Mermaid syntax validation tests (node IDs declared before use, node declaration pattern, edge declaration pattern, no duplicate nodes).
  • collectionCards.test.ts — Data integrity tests (expected collection names, uniqueness, descriptions, positive counts, maturity values, hrefs), metaCollections tests, and artifact count cross-validation against .collection.yml YAML manifests using countYamlPaths().

Security Analysis

  • No sensitive data, API keys, or credentials detected in changes.
  • Dependency change: jest-environment-jsdom removed, @happy-dom/jest-environment added and pinned to exact version — both well-known test environment packages with no known vulnerabilities.
  • No privilege escalation or security script modifications.
  • No customer data handling changes.
  • Workflow change: Added push trigger to dependency-review.yml — scoped to main/develop branches only, no new permissions or secrets introduced.

Manual Testing

Manual testing was not performed. Validation relied on automated test suites and lint checks.

Checklist

Required Checks

  • Documentation is updated (if applicable)
  • Files follow existing naming conventions
  • Changes are backwards compatible (if applicable)
  • Tests added for new functionality (if applicable)

AI Artifact Contributions

  • Used /prompt-analyze to review contribution
  • Addressed all feedback from prompt-builder review
  • Verified contribution follows common standards and type-specific requirements

Required Automated Checks

The following validation commands must pass before merging:

  • Markdown linting: npm run lint:md
  • Spell checking: npm run spell-check
  • Frontmatter validation: npm run lint:frontmatter — Skipped (hung; pre-existing environment issue, no .md files changed in this PR)
  • Skill structure validation: npm run validate:skills — Skipped (pre-existing jira .venv warning; no skill files changed in this PR)
  • Link validation: npm run lint:md-links — Skipped (timeout; pre-existing slow network checks, no .md files changed in this PR)
  • PowerShell analysis: npm run lint:ps
  • Plugin freshness: npm run plugin:generate

Security Considerations

  • This PR does not contain any sensitive or NDA information
  • Any new dependencies have been reviewed for security issues
  • (N/A — no security scripts modified) Security-related scripts follow the principle of least privilege

Additional Notes

All commits follow conventional commit format. No non-compliant language, unintended file changes, or missing referenced files detected. No GHCP artifacts changed, so GHCP Maturity section is not applicable.

- split multi-node lines in collection diagram to fix parser error

🔧 - Generated by Copilot
…rds data

- replace hardcoded diagram string with buildCollectionDiagram function
- compute hve-core-all artifact total from child collection data
- node declarations and edges driven by collectionCards array

♻️ - Generated by Copilot
- sync 6 stale artifact counts in collectionCards to collection YAML sources
- export buildCollectionDiagram and add metaCollections for dynamic nodes
- switch test environment from jsdom to happy-dom
- add Mermaid theme mock and test suites (93 tests across 9 suites)

🧪 - Generated by Copilot
…lidation

- add Mermaid node declaration, edge syntax, and duplicate detection tests

- add artifact count cross-validation against YAML collection manifests

- remove --passWithNoTests from docusaurus test script

- add docs:test convenience script to root package.json

- add tsconfig.json for TypeScript language server test type resolution

🧪 - Generated by Copilot
@WilliamBerryiii WilliamBerryiii requested a review from a team as a code owner March 26, 2026 21:43
Comment thread docs/docusaurus/package.json Fixed
@codecov-commenter
Copy link
Copy Markdown

codecov-commenter commented Mar 26, 2026

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 87.64%. Comparing base (cd6f7ed) to head (6e70757).

Additional details and impacted files

Impacted file tree graph

@@            Coverage Diff             @@
##             main    #1215      +/-   ##
==========================================
- Coverage   87.65%   87.64%   -0.02%     
==========================================
  Files          61       61              
  Lines        9315     9315              
==========================================
- Hits         8165     8164       -1     
- Misses       1150     1151       +1     
Flag Coverage Δ
pester 85.30% <ø> (-0.02%) ⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.
see 1 file with indirect coverage changes

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@github-actions
Copy link
Copy Markdown
Contributor

github-actions Bot commented Mar 26, 2026

Dependency Review Summary

The full dependency review summary was too large to display here (6144KB, limit is 1024KB).

Please download the artifact named "dependency-review-summary" to view the complete report.

View full job summary

Copy link
Copy Markdown
Member

@bindsi bindsi left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Like that one!!!

@auyidi1
Copy link
Copy Markdown
Contributor

auyidi1 commented Mar 27, 2026

The PR description says "107 tests across 8 suites" but examining the two test files: buildCollectionDiagram.test.ts has ~17 tests (13 + 4 syntax validation) and collectionCards.test.ts has ~48 tests (9 parameterized x 4 properties + collection checks + meta + cross-validation). The remaining tests to reach 107 must come from pre-existing test files — the description could clarify this distinction between new and pre-existing tests.

Comment thread docs/docusaurus/package.json Outdated
Comment thread docs/docusaurus/src/pages/index.tsx Outdated
Comment thread docs/docusaurus/src/pages/index.tsx
Comment thread docs/docusaurus/src/pages/index.tsx Outdated
Comment thread docs/docusaurus/src/pages/__tests__/buildCollectionDiagram.test.ts
Comment thread docs/docusaurus/src/data/__tests__/collectionCards.test.ts
Comment thread docs/docusaurus/src/data/__tests__/collectionCards.test.ts
Comment thread docs/docusaurus/tsconfig.json
WilliamBerryiii and others added 2 commits March 27, 2026 14:37
Remove the orphaned INS (installer) node from the Mermaid collection diagram
and replace the untyped Record<string, number> meta parameter with a
typed MetaCollections interface. Remove installer-related test assertions.
@WilliamBerryiii
Copy link
Copy Markdown
Member Author

@auyidi1 - comments addressed ... some fixes applied, others not because of either scope creep or "by design"

- add push trigger on main/develop for pyproject.toml and uv.lock paths
- scope dependency review step to pull_request events only
- update fork check to allow push-triggered snapshot submissions

🔧 - Generated by Copilot
@WilliamBerryiii
Copy link
Copy Markdown
Member Author

Dependency Review Check — Known Failure

The Review Dependencies check is expected to fail on this PR due to a snapshot mismatch between the base and head SHAs. Root cause: the dependency-review.yml workflow previously only triggered on pull_request events, so the Submit uv.lock dependencies step never ran on push to main — meaning the base commit has 0 submitted snapshots while the PR head has 1.

What we fixed (commit 453c31c)

  • Added a push trigger on main/develop scoped to **/pyproject.toml and **/uv.lock so that merged commits create base snapshots via the Dependency Submission API.
  • Scoped the Dependency Review step to pull_request events only (if: github.event_name == 'pull_request').

Why it still fails on this PR

The fix is in this PR. The push trigger will only fire once this change merges to main and a subsequent push touching uv.lock or pyproject.toml creates the first base snapshot. After that, future PRs will have matching snapshots and the check will pass.

Merging with this known failure. The flagged vulnerabilities (path-to-regexp, serialize-javascript) are pre-existing Docusaurus transitive dependencies — not introduced by this PR.

…snapshots

- ensure every push to main/develop creates a base snapshot
- resolve bootstrapping issue where first merge would not trigger snapshot

🔧 - Generated by Copilot
@WilliamBerryiii
Copy link
Copy Markdown
Member Author

Update: Paths filter removed (commit c6f9b2c)

The push trigger's paths filter has been removed so that every push to main/develop creates a base snapshot — not just pushes touching pyproject.toml or uv.lock. This means the snapshot will be created as soon as this PR merges, and the dependency review check will pass for the next PR without any manual intervention.

@WilliamBerryiii WilliamBerryiii requested a review from auyidi1 March 28, 2026 00:15
@WilliamBerryiii WilliamBerryiii merged commit 934c30b into main Mar 30, 2026
40 of 41 checks passed
WilliamBerryiii pushed a commit that referenced this pull request Mar 30, 2026
## Pre-Release 3.3.27

### ✨ Features

- standardize pytest-mock as Python mocking framework (#1170)
- add Jira backlog workflows and Jira/GitLab skills (#978)
- add centralized version bump script and supply-chain attestation
(#1183)

### 🐛 Bug Fixes

- sync package-lock.json after pre-release version bump (#1236)
- separate mermaid node declarations and add dynamic diagram generation
with tests (#1215)
- replace anchor links in meeting-analyst with bold text references
(#1201)
- remove recursive symlinks in jira and gitlab skill directories (#1233)
- validate-installation scripts now check .github/skills directory
(#1010) (#1206)
- resolve npm audit vulnerabilities via dependency overrides (#1200)
- add post-release triggers to scorecard workflow (#1186)
- add missing .md extensions to relative links in agent documentation
(#1180)

### ♻️ Refactoring

- align agent and prompt folder names to collection identifier (#1210)

### 🔧 Maintenance

- bump pygments from 2.19.2 to 2.20.0 in /.github/skills/gitlab/gitlab
(#1234)
- bump path-to-regexp from 0.1.12 to 0.1.13 in /docs/docusaurus (#1226)
- bump the github-actions group with 4 updates (#1231)
- add missing folders and alphabetize location lists (#1193)
- bump brace-expansion (#1224)
- bump handlebars from 4.7.8 to 4.7.9 in /docs/docusaurus (#1217)
- bump brace-expansion from 5.0.3 to 5.0.5 in /docs/docusaurus (#1213)
- pre-release 3.3.10 (#1187)
- bump markdownlint-cli2 from 0.21.0 to 0.22.0 in the npm-dependencies
group (#1175)
- bump the github-actions group with 3 updates (#1176)
- pre-release 3.3.1 (#1165)

---
*Managed automatically by pre-release workflow.*

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
WilliamBerryiii pushed a commit that referenced this pull request Apr 2, 2026
## Pre-Release 3.3.41

### ✨ Features

- add agentic workflows for automated issue triage, implementation, PR
review, dependency review, and doc-staleness detection (#1219)
- consolidate package-lock.json version sync into
Update-VersionFiles.ps1 (#1240)
- add standards code review agent and full review orchestrator (#1174)
- standardize pytest-mock as Python mocking framework (#1170)
- add Jira backlog workflows and Jira/GitLab skills (#978)
- add centralized version bump script and supply-chain attestation
(#1183)

### 🐛 Bug Fixes

- replace invalid bare tool names with official tool identifiers (#1198)
- fix broken links and remove orphaned reference in code review docs
(#1257)
- exclude Python env dirs from skill validation warnings (#1255)
- pin happy-dom and serialize-javascript to resolve Dependabot
vulnerabilities (#1253)
- remove Mermaid diagram and add missing collection cards (#1247)
- disable MCP servers by default to prevent token limit errors (#1144)
- sync package-lock.json after pre-release version bump (#1236)
- separate mermaid node declarations and add dynamic diagram generation
with tests (#1215)
- replace anchor links in meeting-analyst with bold text references
(#1201)
- remove recursive symlinks in jira and gitlab skill directories (#1233)
- validate-installation scripts now check .github/skills directory
(#1010) (#1206)
- resolve npm audit vulnerabilities via dependency overrides (#1200)
- add post-release triggers to scorecard workflow (#1186)
- add missing .md extensions to relative links in agent documentation
(#1180)

### 📚 Documentation

- CLI getting-started: clarify plugin install commands as alternatives
(-all vs base) (#1251)

### ♻️ Refactoring

- align agent and prompt folder names to collection identifier (#1210)

### 🔧 Maintenance

- streamline RAI Planner phase structure and documentation (#1273)
- bump happy-dom from 20.8.8 to 20.8.9 in /docs/docusaurus (#1237)
- pre-release 3.3.27 (#1191)
- bump pygments from 2.19.2 to 2.20.0 in /.github/skills/gitlab/gitlab
(#1234)
- bump path-to-regexp from 0.1.12 to 0.1.13 in /docs/docusaurus (#1226)
- bump the github-actions group with 4 updates (#1231)
- add missing folders and alphabetize location lists (#1193)
- bump brace-expansion (#1224)
- bump handlebars from 4.7.8 to 4.7.9 in /docs/docusaurus (#1217)
- bump brace-expansion from 5.0.3 to 5.0.5 in /docs/docusaurus (#1213)
- pre-release 3.3.10 (#1187)
- bump markdownlint-cli2 from 0.21.0 to 0.22.0 in the npm-dependencies
group (#1175)
- bump the github-actions group with 3 updates (#1176)
- pre-release 3.3.1 (#1165)

---
*Managed automatically by pre-release workflow.*

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
WilliamBerryiii pushed a commit that referenced this pull request Apr 24, 2026
## Pre-Release 3.3.101

### ✨ Features

- add removed maturity tier and retire owasp-docker (#1444)
- add evaluation dataset creator (#1279)
- align RAI planner with guide, remove scoring, improve UX (#1287)
- add PSGallery staleness check and BOM cleanup (#1379)
- ISA-95 network planner agent (#1177)
- auto-generate collection.md with maturity filtering (#1316)
- add folder-consistency check and standardize WARN outp… (#1350)
- add synth-data-generate prompt to data-science collection (#1419)
- add canonical deck workflow and customer-card rendering for design
thinking (#1413)
- add Figma MCP integration for DT artifact export (#1222)
- introduce `owasp-docker` (#1245)
- replace hve-core-specific references with portable discovery-based
language (#1335)
- introduce `owasp-cicd` (#1246)
- add secure-by-design knowledge skill (#1223)
- introduce `owasp-infrastructure` (#1244)
- introduce `owasp-mcp` (#1207)
- add OutputPath parameter to Invoke-LinkLanguageCheck.ps1 (#1229)
- add -OutputPath parameter to Validate-SkillStructure.ps1 (#1225)
- add maintainer-only skip-review label guard (#1293)
- add extension collections overview and integrate into getting started
flow (#950)
- add agentic workflows for automated issue triage, implementation, PR
review, dependency review, and doc-staleness detection (#1219)
- consolidate package-lock.json version sync into
Update-VersionFiles.ps1 (#1240)
- add standards code review agent and full review orchestrator (#1174)
- standardize pytest-mock as Python mocking framework (#1170)
- add Jira backlog workflows and Jira/GitLab skills (#978)
- add centralized version bump script and supply-chain attestation
(#1183)

### 🐛 Bug Fixes

- pin PowerShell-Yaml to 0.4.7 across all install sites (#1378)
- close fork-PR/workflow-file-PR secret-strip gap and normalize
upload-artifact version (#1421)
- replace stream-based lookahead with array indexing in
list-changed-files.sh (#1376)
- centralize ISO 8601 timestamp regex in CIHelpers (#1343)
- update stale documentation date in release-process.md (#1363)
- pin basic-ftp to 5.3.0 to resolve GHSA-rp42-5vxx-qpwr (#1374)
- add bot filter to dependency PR review workflow (#1362)
- resolve pip-audit findings in powerpoint, gitlab, and jira skill lock
files (#1360)
- standardize Timestamp JSON key casing across all lint result files
(#1314)
- add synchronize trigger to PR Review workflow (#1323)
- standardize timestamp in Validate-SkillStructure.ps1 to use
Get-StandardTimestamp (#1280)
- add parallel subagent dispatch and structured JSON contracts to
code-review-full (#1304)
- standardize timestamp in SecurityHelpers.psm1 to use
Get-StandardTimestamp (#1284)
- standardize timestamps in Test-DependencyPinning.ps1 and
SecurityClasses.psm1 (#1282)
- derive collection artifact counts from YAML at build time (#1275)
- standardize timestamp in FrontmatterValidation.psm1 to use
Get-StandardTimestamp (#1285)
- standardize timestamp in Markdown-Link-Check.ps1 to use
Get-StandardTimestamp (#1283)
- escape hyphens in Mermaid diagram on Collections page (#1262)
- add summary timestamp to PSScriptAnalyzer output (#1211)
- fix plugin compatibility and robustness for coding-standards code
review agents (#1289)
- standardize timestamp in Test-CopyrightHeaders.ps1 to use
Get-StandardTimestamp (#1278)
- standardize timestamp in Invoke-YamlLint.ps1 to use
Get-StandardTimestamp (#1270)
- standardize timestamp in Invoke-LinkLanguageCheck.ps1 to use
Get-StandardTimestamp (#1264)
- fix dependency-review path filters and sparse-checkout cone mode
(#1259)
- replace invalid bare tool names with official tool identifiers (#1198)
- fix broken links and remove orphaned reference in code review docs
(#1257)
- exclude Python env dirs from skill validation warnings (#1255)
- pin happy-dom and serialize-javascript to resolve Dependabot
vulnerabilities (#1253)
- remove Mermaid diagram and add missing collection cards (#1247)
- disable MCP servers by default to prevent token limit errors (#1144)
- sync package-lock.json after pre-release version bump (#1236)
- separate mermaid node declarations and add dynamic diagram generation
with tests (#1215)
- replace anchor links in meeting-analyst with bold text references
(#1201)
- remove recursive symlinks in jira and gitlab skill directories (#1233)
- validate-installation scripts now check .github/skills directory
(#1010) (#1206)
- resolve npm audit vulnerabilities via dependency overrides (#1200)
- add post-release triggers to scorecard workflow (#1186)
- add missing .md extensions to relative links in agent documentation
(#1180)

### 📚 Documentation

- broaden Security Review description beyond OWASP (#1385)
- document maintainer advisory mode and skip-review label guard (#1386)
- document ExcludePaths/OutputPath for Invoke-LinkLanguageCheck (#1383)
- CLI getting-started: clarify plugin install commands as alternatives
(-all vs base) (#1251)

### ♻️ Refactoring

- align agent and prompt folder names to collection identifier (#1210)

### 🔧 Maintenance

- pin PSScriptAnalyzer to 1.25.0 and sync stale workflow version
comments (#1389)
- bump lxml from 6.0.2 to 6.1.0 in
/.github/skills/experimental/powerpoint (#1424)
- bump @vscode/vsce from 3.7.1 to 3.9.1 in the npm-dependencies group
(#1390)
- bump the github-actions group across 1 directory with 7 updates
(#1391)
- bump follow-redirects from 1.15.11 to 1.16.0 in /docs/docusaurus
(#1356)
- upgrade Node.js from 20 to 24 and bump cspell to v10 (#1353)
- bump basic-ftp from 5.2.0 to 5.2.1 (#1324)
- update github/gh-aw-actions requirement to
536ea1bad8c6715d098a9dc1afea8d403733acfe in the github-actions group
across 1 directory (#1298)
- update security instruction attributions and compliance (#1294)
- bump the npm-dependencies group with 2 updates (#1297)
- pre-release 3.3.41 (#1252)
- streamline RAI Planner phase structure and documentation (#1273)
- bump happy-dom from 20.8.8 to 20.8.9 in /docs/docusaurus (#1237)
- pre-release 3.3.27 (#1191)
- bump pygments from 2.19.2 to 2.20.0 in /.github/skills/gitlab/gitlab
(#1234)
- bump path-to-regexp from 0.1.12 to 0.1.13 in /docs/docusaurus (#1226)
- bump the github-actions group with 4 updates (#1231)
- add missing folders and alphabetize location lists (#1193)
- bump brace-expansion (#1224)
- bump handlebars from 4.7.8 to 4.7.9 in /docs/docusaurus (#1217)
- bump brace-expansion from 5.0.3 to 5.0.5 in /docs/docusaurus (#1213)
- pre-release 3.3.10 (#1187)
- bump markdownlint-cli2 from 0.21.0 to 0.22.0 in the npm-dependencies
group (#1175)
- bump the github-actions group with 3 updates (#1176)
- pre-release 3.3.1 (#1165)

---
*Managed automatically by pre-release workflow.*

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants