Skip to content

Commit f52352d

Browse files
WilliamBerryiiiWilliamBerryiii
authored
feat(workflows): add validation reusable workflows (#27)
* feat(workflows): add validation reusable workflows Add seven reusable GitHub Actions workflows for code quality validation: - spell-check.yml: CSpell dictionary-based spell checking for markdown and code - markdown-lint.yml: Markdown formatting and style validation - table-format.yml: Validates markdown table formatting and consistency - psscriptanalyzer.yml: PowerShell static code analysis with custom rules - frontmatter-validation.yml: Validates YAML frontmatter in markdown files - link-lang-check.yml: Checks markdown links and language consistency - markdown-link-check.yml: Comprehensive markdown link validation All workflows are reusable (workflow_call) and designed to be called from orchestration workflows. Each workflow includes proper error handling, caching, and artifact uploads. Resolves: #14 🔧 - Generated by Copilot * fix(workflows): ensure logs directory exists and set failure env vars Fixed validation workflow issues identified by Copilot review: - Added logs directory creation in link-lang-check.yml before script execution - Set LINK_LANG_FAILED environment variable on failure in link-lang-check.yml - Added logs directory creation in psscriptanalyzer.yml before script execution - Set PSSCRIPTANALYZER_FAILED environment variable on failure in psscriptanalyzer.yml These changes ensure artifact upload works correctly and failure detection is reliable. 🔒 - Generated by Copilot * refactor(workflows): rename psscriptanalyzer.yml to ps-script-analyzer.yml for kebab-case consistency * fix(workflows): correct script path to Invoke-PSScriptAnalyzer.ps1 * fix(scripts): resolve issues #31-33 and enhance validation workflows - fix critical extension matching bug in LintingHelpers (issue #31) - move help blocks inside functions for Get-Help (issue #32) - enhance regex patterns for multiline content (issue #33) - implement XML junit parsing for markdown-link-check - add structured JSON output to link-language check - create comprehensive workflows documentation - update link-lang-check workflow to use wrapper script 🔧 - Generated by Copilot * fix(scripts): resolve logging errors, workflow corruption, and update SHA pins - fix Write-Error in Test-SHAStaleness preventing script publication - fix pipeline pollution in Update-ActionSHAPinning corrupting workflows - update harden-runner SHA from 92c522aa to 95d9a5de across 4 workflows - complete all 13 PR #27 feedback items (actions, error handling, code quality) 🔒 - Generated by Copilot * fix(scripts): address PR review comments - correct artifact name reference in spell-check warning - remove ineffective Out-Null pipes from Write-SecurityLog calls - add blank line after #Requires for readability - update ms.date to current date 🔧 - Generated by Copilot
1 parent 66be136 commit f52352d

16 files changed

Lines changed: 1294 additions & 69 deletions

‎.github/workflows/README.md‎

Lines changed: 321 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,321 @@
1+
---
2+
title: GitHub Workflows
3+
description: Documentation for GitHub Actions workflows in the HVE Core project
4+
author: HVE Core Team
5+
ms.date: 2025-11-12
6+
ms.topic: reference
7+
keywords:
8+
- github actions
9+
- workflows
10+
- ci/cd
11+
- automation
12+
- validation
13+
estimated_reading_time: 12
14+
---
15+
16+
# GitHub Actions Workflows
17+
18+
This directory contains GitHub Actions workflow definitions for continuous integration, code quality validation, and automated checks in the HVE Core project.
19+
20+
## Overview
21+
22+
All workflows run automatically on pull requests and pushes to protected branches. They enforce code quality standards, validate documentation, and ensure consistency across the codebase.
23+
24+
## Workflows
25+
26+
### Code Quality
27+
28+
#### `ps-script-analyzer.yml`
29+
30+
**Purpose**: Static analysis of PowerShell scripts using PSScriptAnalyzer
31+
32+
**Triggers**:
33+
34+
* Pull requests modifying `*.ps1` or `*.psm1` files
35+
* Manual workflow dispatch
36+
37+
**Features**:
38+
39+
* Analyzes only changed PowerShell files
40+
* Creates GitHub annotations for violations
41+
* Exports JSON results and markdown summary
42+
* Uploads artifacts with 30-day retention
43+
44+
**Configuration**: `scripts/linting/PSScriptAnalyzer.psd1`
45+
46+
**Exit Behavior**: Fails on Error or Warning severity issues
47+
48+
### Documentation Validation
49+
50+
#### `markdown-lint.yml`
51+
52+
**Purpose**: Enforces markdown formatting standards using markdownlint
53+
54+
**Triggers**:
55+
56+
* Pull requests modifying `*.md` files
57+
* Manual workflow dispatch
58+
59+
**Configuration**: `.markdownlint.json`
60+
61+
**Features**:
62+
63+
* Validates markdown syntax and style
64+
* Checks heading hierarchy
65+
* Enforces consistent list formatting
66+
67+
#### `frontmatter-validation.yml`
68+
69+
**Purpose**: Validates YAML frontmatter and footer format in markdown files
70+
71+
**Triggers**:
72+
73+
* Pull requests modifying `*.md` files
74+
* Manual workflow dispatch
75+
76+
**Features**:
77+
78+
* Validates required frontmatter fields
79+
* Checks footer format and copyright notice
80+
* Creates GitHub annotations for violations
81+
* Exports JSON results with statistics
82+
* Uploads artifacts with 30-day retention
83+
84+
**Configuration**: Hardcoded in `scripts/linting/Validate-MarkdownFrontmatter.ps1`
85+
86+
**Required Frontmatter Fields**:
87+
88+
* `title`
89+
* `description`
90+
* `author`
91+
* `ms.date`
92+
* `ms.topic`
93+
* `keywords`
94+
* `estimated_reading_time`
95+
96+
**Exit Behavior**: Fails if validation errors found
97+
98+
#### `markdown-link-check.yml`
99+
100+
**Purpose**: Validates all links in markdown files using markdown-link-check
101+
102+
**Triggers**:
103+
104+
* Pull requests modifying `*.md` files
105+
* Manual workflow dispatch
106+
107+
**Features**:
108+
109+
* Checks internal and external links
110+
* Retries failed links
111+
* Creates GitHub annotations for broken links
112+
* Exports JSON results with link statistics
113+
* Generates detailed step summary
114+
* Uploads artifacts with 30-day retention
115+
116+
**Configuration**: `scripts/linting/markdown-link-check.config.json`
117+
118+
**Exit Behavior**: Soft-fail (continues workflow but sets failure status)
119+
120+
#### `link-lang-check.yml`
121+
122+
**Purpose**: Detects URLs with language paths that should be removed
123+
124+
**Triggers**:
125+
126+
* Pull requests modifying `*.md` files
127+
* Manual workflow dispatch
128+
129+
**Features**:
130+
131+
* Scans for `/en-us/` and similar patterns
132+
* Creates GitHub warning annotations
133+
* Provides fix instructions in summary
134+
* Uploads artifacts with 30-day retention
135+
136+
**Configuration**: Regex patterns in `scripts/linting/Link-Lang-Check.ps1`
137+
138+
**Exit Behavior**: Warning only (does not fail workflow)
139+
140+
### Content Quality
141+
142+
#### `spell-check.yml`
143+
144+
**Purpose**: Spell checking across all file types using cspell
145+
146+
**Triggers**:
147+
148+
* Pull requests
149+
* Manual workflow dispatch
150+
151+
**Configuration**: `.cspell.json`
152+
153+
**Features**:
154+
155+
* Supports multiple languages
156+
* Custom dictionary support
157+
* Ignores code blocks and technical terms
158+
159+
**Exit Behavior**: Fails on spelling errors
160+
161+
#### `table-format.yml`
162+
163+
**Purpose**: Ensures consistent markdown table formatting
164+
165+
**Triggers**:
166+
167+
* Pull requests modifying `*.md` files
168+
* Manual workflow dispatch
169+
170+
**Features**:
171+
172+
* Aligns table columns
173+
* Validates table structure
174+
* Checks for consistent pipe usage
175+
176+
**Exit Behavior**: Fails on formatting issues
177+
178+
## Common Patterns
179+
180+
### Workflow Structure
181+
182+
All validation workflows follow a consistent pattern:
183+
184+
```yaml
185+
name: Workflow Name
186+
on:
187+
pull_request:
188+
paths:
189+
- '**/*.ext'
190+
workflow_dispatch:
191+
192+
jobs:
193+
validate:
194+
runs-on: ubuntu-latest
195+
steps:
196+
- uses: actions/[email protected]
197+
- name: Setup environment
198+
# Install dependencies
199+
- name: Run validation
200+
# Execute validation script
201+
- name: Upload artifacts
202+
if: always()
203+
uses: actions/upload-artifact@v4
204+
```
205+
206+
### Artifact Handling
207+
208+
* **Retention**: 30 days for all artifacts
209+
* **Naming**: `{workflow-name}-results`
210+
* **Contents**: JSON results, markdown summaries, logs
211+
* **Condition**: `if: always()` to upload even on failure
212+
213+
### GitHub Annotations
214+
215+
All workflows create annotations in the format:
216+
217+
```text
218+
::error file={file},line={line}::{message}
219+
::warning file={file},line={line}::{message}
220+
```
221+
222+
These appear in:
223+
224+
* PR files changed view
225+
* Workflow run summary
226+
* Checks tab
227+
228+
### Step Summaries
229+
230+
Workflows generate markdown summaries displayed in the workflow run:
231+
232+
* Overall status (passed/failed)
233+
* Statistics (files checked, issues found)
234+
* Tables of violations with file paths
235+
* Links to artifacts
236+
237+
## Local Testing
238+
239+
All validation scripts can be tested locally before pushing:
240+
241+
```powershell
242+
# PowerShell analysis
243+
.\scripts\linting\Invoke-PSScriptAnalyzer.ps1 -ChangedFilesOnly
244+
245+
# Frontmatter validation
246+
.\scripts\linting\Validate-MarkdownFrontmatter.ps1 -ChangedFilesOnly
247+
248+
# Link validation
249+
.\scripts\linting\Markdown-Link-Check.ps1
250+
251+
# Language path check
252+
.\scripts\linting\Invoke-LinkLanguageCheck.ps1
253+
```
254+
255+
```bash
256+
# Markdown linting
257+
npm run lint:md
258+
259+
# Spell checking
260+
npm run spell-check
261+
262+
# Table formatting
263+
npm run format:tables
264+
```
265+
266+
## Configuration Files
267+
268+
| File | Purpose | Used By |
269+
|------------------------------------------------------|---------------------------------|-----------------------------|
270+
| `scripts/linting/PSScriptAnalyzer.psd1` | PowerShell linting rules | ps-script-analyzer.yml |
271+
| `.markdownlint.json` | Markdown formatting rules | markdown-lint.yml |
272+
| `scripts/linting/markdown-link-check.config.json` | Link checking configuration | markdown-link-check.yml |
273+
| `.cspell.json` | Spell checking configuration | spell-check.yml |
274+
| `.github/instructions/markdown.instructions.md` | Markdown style guide | All markdown workflows |
275+
| `.github/instructions/commit-message.instructions.md` | Commit message standards | All workflows (informative) |
276+
277+
## Adding New Workflows
278+
279+
To add a new validation workflow:
280+
281+
1. **Create workflow file** in `.github/workflows/` using consistent naming
282+
2. **Follow common patterns** from existing workflows
283+
3. **Add appropriate triggers** (pull_request paths, workflow_dispatch)
284+
4. **Implement artifact uploads** with 30-day retention
285+
5. **Create GitHub annotations** for violations
286+
6. **Generate step summary** with results
287+
7. **Support local testing** with corresponding script
288+
8. **Document** in this README
289+
9. **Test thoroughly** before merging
290+
291+
## Troubleshooting
292+
293+
### Workflow Fails But Local Test Passes
294+
295+
* Check environment differences (Node.js version, PowerShell version)
296+
* Verify all dependencies are installed in workflow
297+
* Review workflow logs for specific error messages
298+
299+
### Artifacts Not Uploading
300+
301+
* Ensure `if: always()` condition is present
302+
* Verify artifact path exists before upload
303+
* Check for file permission issues
304+
305+
### Annotations Not Appearing
306+
307+
* Verify annotation format: `::error file={file},line={line}::{message}`
308+
* Ensure file paths are relative to repository root
309+
* Check that workflow has write permissions
310+
311+
## Related Documentation
312+
313+
* [Linting Scripts Documentation](../../scripts/linting/README.md)
314+
* [Scripts Documentation](../../scripts/README.md)
315+
* [Contributing Guidelines](../../CONTRIBUTING.md)
316+
317+
---
318+
319+
<!-- markdownlint-disable MD036 -->
320+
*🤖 Crafted with precision by ✨Copilot following brilliant human instruction, then carefully refined by our team of discerning human reviewers.*
321+
<!-- markdownlint-enable MD036 -->

0 commit comments

Comments
 (0)