microsoft/hve-core
Publicmirrored fromhttps://github.com/microsoft/hve-coreAvailable
docs/customization/build-system.md
217lines · modecode
| 1 | --- |
| 2 | title: Build System and Validation |
| 3 | description: Understand the plugin generation pipeline, schema validation system, npm scripts, and CI checks for customizing and extending HVE Core |
| 4 | author: Microsoft |
| 5 | ms.date: 2026-02-24 |
| 6 | ms.topic: how-to |
| 7 | keywords: |
| 8 | - build system |
| 9 | - plugin generation |
| 10 | - schema validation |
| 11 | - linting |
| 12 | - npm scripts |
| 13 | estimated_reading_time: 8 |
| 14 | --- |
| 15 | |
| 16 | ## Plugin Generation Pipeline |
| 17 | |
| 18 | The plugin generation pipeline transforms collection manifests into distributable plugin |
| 19 | output. It runs in three stages: |
| 20 | |
| 21 | 1. `Generate-Plugins.ps1` reads each `collections/*.collection.yml` manifest and produces |
| 22 | output files under `plugins/`. Each collection gets its own subdirectory |
| 23 | (e.g., `plugins/hve-core/`, `plugins/ado/`). |
| 24 | |
| 25 | 2. `lint:md:fix` applies markdownlint auto-fixes to generated markdown files. |
| 26 | |
| 27 | 3. `format:tables` aligns markdown table columns in generated output. |
| 28 | |
| 29 | Run the full pipeline with a single command: |
| 30 | |
| 31 | ```bash |
| 32 | npm run plugin:generate |
| 33 | ``` |
| 34 | |
| 35 | > [!IMPORTANT] |
| 36 | > Files under `plugins/` are generated output. Do not edit them directly. |
| 37 | > Changes made to plugin files are overwritten on the next generation run. |
| 38 | |
| 39 | ## Schema Validation System |
| 40 | |
| 41 | YAML frontmatter in markdown files is validated against JSON schemas stored in |
| 42 | `scripts/linting/schemas/`. The validation system uses glob-based pattern matching to |
| 43 | determine which schema applies to each file. |
| 44 | |
| 45 | ### Schema Files |
| 46 | |
| 47 | | Schema | Applies To | |
| 48 | |------------------------------------------|-----------------------------------| |
| 49 | | `docs-frontmatter.schema.json` | `docs/**/*.md` | |
| 50 | | `instruction-frontmatter.schema.json` | `.github/**/*.instructions.md` | |
| 51 | | `agent-frontmatter.schema.json` | `.github/**/*.agent.md` | |
| 52 | | `prompt-frontmatter.schema.json` | `.github/**/*.prompt.md` | |
| 53 | | `skill-frontmatter.schema.json` | `.github/skills/**/SKILL.md` | |
| 54 | | `chatmode-frontmatter.schema.json` | `.github/**/*.chatmode.md` | |
| 55 | | `collection-manifest.schema.json` | Collection YAML manifests | |
| 56 | | `root-community-frontmatter.schema.json` | Root files (README, CONTRIBUTING) | |
| 57 | | `base-frontmatter.schema.json` | Default fallback | |
| 58 | |
| 59 | ### Pattern Mapping |
| 60 | |
| 61 | The `scripts/linting/schemas/schema-mapping.json` file defines the glob-to-schema mapping. |
| 62 | Patterns are evaluated from most specific to least specific, and the first match determines |
| 63 | the schema. When no pattern matches, `base-frontmatter.schema.json` applies as the default. |
| 64 | |
| 65 | ### Adding Custom Schemas |
| 66 | |
| 67 | To add validation for a new file type: |
| 68 | |
| 69 | 1. Create a JSON schema file in `scripts/linting/schemas/` |
| 70 | 2. Add a mapping entry to `schema-mapping.json` with the glob pattern, scope name, and |
| 71 | schema filename |
| 72 | 3. Run `npm run lint:frontmatter` to verify the new schema validates correctly |
| 73 | |
| 74 | ## npm Scripts Reference |
| 75 | |
| 76 | All validation, formatting, and testing operations run through npm scripts defined in |
| 77 | `package.json`. The table below groups scripts by purpose. |
| 78 | |
| 79 | ### Linting |
| 80 | |
| 81 | | Script | Command | Description | |
| 82 | |-----------------------------|-------------------------------------|------------------------------------------| |
| 83 | | `lint:all` | `npm run lint:all` | Runs all linters in sequence | |
| 84 | | `lint:md` | `npm run lint:md` | Markdown linting via markdownlint-cli2 | |
| 85 | | `lint:md:fix` | `npm run lint:md:fix` | Markdown linting with auto-fix | |
| 86 | | `lint:ps` | `npm run lint:ps` | PowerShell analysis via PSScriptAnalyzer | |
| 87 | | `lint:yaml` | `npm run lint:yaml` | YAML syntax and structure validation | |
| 88 | | `lint:links` | `npm run lint:links` | Link language checking | |
| 89 | | `lint:md-links` | `npm run lint:md-links` | Markdown link target validation | |
| 90 | | `lint:frontmatter` | `npm run lint:frontmatter` | Frontmatter schema validation | |
| 91 | | `lint:collections-metadata` | `npm run lint:collections-metadata` | Collection manifest validation | |
| 92 | | `lint:marketplace` | `npm run lint:marketplace` | Marketplace manifest validation | |
| 93 | | `lint:version-consistency` | `npm run lint:version-consistency` | GitHub Action version consistency | |
| 94 | | `lint:permissions` | `npm run lint:permissions` | Workflow permissions validation | |
| 95 | |
| 96 | ### Validation |
| 97 | |
| 98 | | Script | Command | Description | |
| 99 | |----------------------|------------------------------|--------------------------------------| |
| 100 | | `validate:copyright` | `npm run validate:copyright` | Copyright header presence check | |
| 101 | | `validate:skills` | `npm run validate:skills` | Skill directory structure validation | |
| 102 | |
| 103 | ### Formatting |
| 104 | |
| 105 | | Script | Command | Description | |
| 106 | |-----------------|-------------------------|---------------------------------| |
| 107 | | `format:tables` | `npm run format:tables` | Markdown table column alignment | |
| 108 | |
| 109 | ### Testing |
| 110 | |
| 111 | | Script | Command | Description | |
| 112 | |-----------|-------------------|------------------------------| |
| 113 | | `test:ps` | `npm run test:ps` | PowerShell Pester test suite | |
| 114 | |
| 115 | ### Plugin and Extension |
| 116 | |
| 117 | | Script | Command | Description | |
| 118 | |--------------------------------|----------------------------------------|----------------------------------------------------| |
| 119 | | `plugin:generate` | `npm run plugin:generate` | Generate plugins, auto-fix markdown, format tables | |
| 120 | | `plugin:validate` | `npm run plugin:validate` | Validate collection metadata (alias) | |
| 121 | | `extension:prepare` | `npm run extension:prepare` | Prepare VS Code extension for packaging | |
| 122 | | `extension:prepare:prerelease` | `npm run extension:prepare:prerelease` | Prepare extension for pre-release | |
| 123 | | `extension:package` | `npm run extension:package` | Package VS Code extension | |
| 124 | | `extension:package:prerelease` | `npm run extension:package:prerelease` | Package extension as pre-release | |
| 125 | |
| 126 | ## Linting Pipeline |
| 127 | |
| 128 | The `lint:all` script chains every linter in a fixed sequence: |
| 129 | |
| 130 | 1. `format:tables` aligns markdown table columns |
| 131 | 2. `lint:md` checks markdown style rules (`.markdownlint.json`) |
| 132 | 3. `lint:ps` analyzes PowerShell scripts (`PSScriptAnalyzer.psd1`) |
| 133 | 4. `lint:yaml` validates YAML file syntax |
| 134 | 5. `lint:links` checks link text language patterns |
| 135 | 6. `lint:frontmatter` validates YAML frontmatter against schemas |
| 136 | 7. `lint:collections-metadata` confirms collection manifest integrity |
| 137 | 8. `lint:marketplace` validates marketplace manifest |
| 138 | 9. `lint:version-consistency` checks GitHub Action version alignment |
| 139 | 10. `lint:permissions` validates workflow permissions |
| 140 | 11. `validate:skills` verifies skill directory structure |
| 141 | |
| 142 | Each linter outputs results to `logs/` for inspection. Run individual linters for faster |
| 143 | feedback during development: |
| 144 | |
| 145 | ```bash |
| 146 | npm run lint:md -- docs/customization/collections.md |
| 147 | ``` |
| 148 | |
| 149 | ## CI Validation |
| 150 | |
| 151 | Pull request validation runs linters in parallel CI jobs. Each job executes one or more |
| 152 | npm scripts from the list above. To reproduce CI checks locally, run the same npm scripts |
| 153 | against your changed files. |
| 154 | |
| 155 | Full local validation: |
| 156 | |
| 157 | ```bash |
| 158 | npm run lint:all |
| 159 | ``` |
| 160 | |
| 161 | Targeted validation for specific files: |
| 162 | |
| 163 | ```bash |
| 164 | npm run lint:md -- path/to/changed-file.md |
| 165 | npm run lint:frontmatter |
| 166 | ``` |
| 167 | |
| 168 | > [!TIP] |
| 169 | > Run `lint:all` before pushing to catch issues that CI would flag. Individual linters |
| 170 | > provide faster feedback when you know which validation applies to your changes. |
| 171 | |
| 172 | ## Customizing Validation |
| 173 | |
| 174 | ### Markdown Rules |
| 175 | |
| 176 | Configure markdownlint rules in `.markdownlint.json` at the repository root. Each rule |
| 177 | maps to a markdownlint rule ID (e.g., `MD013` for line length). Disable rules by setting |
| 178 | them to `false`, or customize parameters such as line length limits. |
| 179 | |
| 180 | ### PowerShell Analysis |
| 181 | |
| 182 | PSScriptAnalyzer rules are configured in `scripts/linting/PSScriptAnalyzer.psd1`. Add or |
| 183 | exclude rules to match your team's PowerShell coding standards. Run analysis with: |
| 184 | |
| 185 | ```bash |
| 186 | npm run lint:ps |
| 187 | ``` |
| 188 | |
| 189 | Results appear in `logs/psscriptanalyzer-results.json` and |
| 190 | `logs/psscriptanalyzer-summary.json`. |
| 191 | |
| 192 | ### Custom Validation Scripts |
| 193 | |
| 194 | Add new validation scripts to `scripts/linting/` and register them as npm scripts in |
| 195 | `package.json`. Follow the existing pattern: scripts accept file paths or glob patterns |
| 196 | as input and write structured results to `logs/`. |
| 197 | |
| 198 | To include a new linter in the full pipeline, add it to the `lint:all` chain in |
| 199 | `package.json`. |
| 200 | |
| 201 | ## Role Scenarios |
| 202 | |
| 203 | **Northwind Traders' SRE/Operations lead** runs `npm run lint:all` as a pre-push hook to |
| 204 | catch markdown formatting issues, broken links, and frontmatter schema violations before |
| 205 | they reach CI. When a new deployment instruction file needs custom frontmatter fields, the |
| 206 | lead adds a schema to `scripts/linting/schemas/` and registers the pattern in |
| 207 | `schema-mapping.json`. |
| 208 | |
| 209 | **Adventure Works' security architect** extends the validation pipeline with a custom script |
| 210 | that checks instruction files for required security disclaimer sections. The script follows |
| 211 | the existing pattern of writing JSON results to `logs/` and integrates into the `lint:all` |
| 212 | chain through `package.json`. |
| 213 | |
| 214 | <!-- markdownlint-disable MD036 --> |
| 215 | *🤖 Crafted with precision by ✨Copilot following brilliant human instruction, |
| 216 | then carefully refined by our team of discerning human reviewers.* |
| 217 | <!-- markdownlint-enable MD036 --> |
| 218 | |