GitVita
New repositoryImport repositoryNew issue
Your repositories Your dashboard Sign in

microsoft/hve-core

Public

mirrored fromhttps://github.com/microsoft/hve-coreAvailable

Watch0Fork0Star0
CodeCommitsIssuesPull requestsActionsInsightsSecurity
975e862d391b7b0b89b4066927217fa3d327924e

Branches

Tags

  • No tags available.
0Branches0Tags
Go to file
Add file
Code

Clone

HTTPS

Download ZIP

hve-core/scripts

scripts/README.md

163lines · modecode

RawDownload
Latest commit unavailable.
1---
2title: Scripts
3description: PowerShell scripts for linting, validation, and security automation
4author: HVE Core Team
5ms.date: 2025-11-05
6ms.topic: reference
7keywords:
8 - powershell
9 - scripts
10 - automation
11 - linting
12 - security
13estimated_reading_time: 5
14---
15
16This directory contains PowerShell scripts for automating linting, validation, and security checks in the `hve-core` repository.
17
18## Directory Structure
19
20```text
21scripts/
22├── extension/ VS Code extension packaging utilities
23├── lib/ Shared utility modules
24├── linting/ PowerShell linting and validation scripts
25├── plugins/ Copilot CLI plugin generation and validation
26├── security/ Security scanning and SHA pinning scripts
27└── tests/ Pester test organization
28```
29
30## Extension
31
32VS Code extension packaging utilities.
33
34| Script | Purpose |
35|-------------------------|------------------------------------------|
36| `Package-Extension.ps1` | Package the VS Code extension |
37| `Prepare-Extension.ps1` | Prepare extension contents for packaging |
38
39## Library
40
41Shared utility modules used across scripts.
42
43| Script | Purpose |
44|----------------------------|--------------------------------------|
45| `Get-VerifiedDownload.ps1` | Download files with SHA verification |
46
47## Linting Scripts
48
49The `linting/` directory contains scripts for validating code quality and documentation:
50
51* **PSScriptAnalyzer**: Static analysis for PowerShell files
52* **Markdown Frontmatter**: Validate YAML frontmatter in markdown files
53* **Skill Structure**: Validate skill directory structure and frontmatter
54* **Link Language Check**: Detect en-us language paths in URLs
55* **Markdown Link Check**: Validate markdown links
56* **Shared Module**: Common helper functions for GitHub Actions integration
57
58See [linting/README.md](linting/README.md) for detailed documentation.
59
60## Security Scripts
61
62The `security/` directory contains scripts for security scanning and dependency management:
63
64* **Dependency Pinning**: Validate SHA pinning compliance
65* **SHA Staleness**: Check for outdated SHA pins
66* **SHA Updates**: Automate updating GitHub Actions SHA pins
67
68## Tests
69
70Pester test organization matching the scripts structure.
71
72| Directory | Tests For |
73|--------------|---------------------------|
74| `extension/` | Extension packaging tests |
75| `lib/` | Library utility tests |
76| `linting/` | Linting script tests |
77| `security/` | Security validation tests |
78
79Run all tests:
80
81```bash
82npm run test
83```
84
85## Usage
86
87All scripts are designed to run both locally and in GitHub Actions workflows. They support common parameters like `-Verbose` and `-Debug` for troubleshooting.
88
89**Local Testing**:
90
91```powershell
92# Test PSScriptAnalyzer on changed files
93./scripts/linting/Invoke-PSScriptAnalyzer.ps1 -ChangedFilesOnly -Verbose
94
95# Validate markdown frontmatter
96./scripts/linting/Validate-MarkdownFrontmatter.ps1 -Verbose
97
98# Check for language paths in URLs
99./scripts/linting/Invoke-LinkLanguageCheck.ps1 -Verbose
100```
101
102**GitHub Actions Integration**:
103
104All scripts automatically detect GitHub Actions environment and provide appropriate output formatting (annotations, summaries, artifacts).
105
106## Contributing
107
108When adding new scripts:
109
1101. Follow PowerShell best practices (PSScriptAnalyzer compliant)
1112. Include the entry point guard pattern (see below)
1123. Support `-Verbose` and `-Debug` parameters
1134. Add GitHub Actions integration using `LintingHelpers` module functions
1145. Include inline help with `.SYNOPSIS`, `.DESCRIPTION`, `.PARAMETER`, and `.EXAMPLE`
1156. Document in relevant README files
1167. Test locally before creating PR
117
118### Entry Point Guard Pattern
119
120All production scripts use a dot-source guard that enables Pester tests to import functions without executing main logic. Extract main logic into an `Invoke-*` orchestrator function and wrap direct execution in a guard block:
121
122```powershell
123#region Functions
124
125function Invoke-ScriptMain {
126 [CmdletBinding()]
127 param( <# script params #> )
128 # Main logic here
129}
130
131#endregion Functions
132
133#region Main Execution
134if ($MyInvocation.InvocationName -ne '.') {
135 try {
136 Invoke-ScriptMain @PSBoundParameters
137 exit 0
138 }
139 catch {
140 Write-Error -ErrorAction Continue "ScriptName failed: $($_.Exception.Message)"
141 Write-CIAnnotation -Message $_.Exception.Message -Level Error
142 exit 1
143 }
144}
145#endregion Main Execution
146```
147
148Key rules:
149
150* The `if` guard wraps `try`/`catch` (not the reverse)
151* Name the orchestrator `Invoke-*` matching the script noun
152* Use `#region Functions` and `#region Main Execution` markers
153* See [Package-Extension.ps1](extension/Package-Extension.ps1) for a canonical example
154
155## Related Documentation
156
157* [Linting Scripts Documentation](linting/README.md)
158* [GitHub Workflows Documentation](../.github/workflows/README.md)
159* [Contributing Guidelines](../CONTRIBUTING.md)
160
161---
162
163🤖 Crafted with precision by ✨Copilot following brilliant human instruction, then carefully refined by our team of discerning human reviewers.
164