microsoft / microsoft/hve-core
docs: update scripts/collections/README.md for new -OutputPath parameter and JSON log output
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 1.5k
- Forks
- 301
- Avg merge
- 3d 3h
- Merged PRs (30d)
- 92
Description
## Component
Documentation
## Bug Description
`scripts/collections/README.md` does not document the `-OutputPath` parameter or the structured JSON log output introduced to `Validate-Collections.ps1` in commit 57ea279 (`feat(scripts): add structured JSON log output to Validate-Collections.ps1`).
The README currently describes the script only as:
```
| Validate-Collections.ps1 | npm run lint:collections-metadata | Validate collection manifests |
```
It does not mention:
- The `-OutputPath` parameter (default: `logs/collection-validation-results.json`)
- That the script writes a structured JSON report to `logs/` after each run
- The output schema (`Timestamp`, `TotalCollections`, `ErrorCount`, `Results[]` with `Collection`, `Severity`, `ErrorType`, `Message` fields)
This creates an inconsistency with `scripts/security/README.md` and `scripts/linting/README.md`, which both document equivalent `-OutputPath` parameters and JSON output paths for every script in those directories.
## Expected Behavior
`scripts/collections/README.md` should document `Validate-Collections.ps1` consistently with peer READMEs:
- A **Parameters** section listing `-OutputPath` with its default value (`logs/collection-validation-results.json`)
- A note that the script writes a JSON report to `logs/` after each run, consumed by CI steps and tooling
- The JSON output schema (or a reference to it from the commit message)
- A usage example showing how to override the output path, e.g.:
```powershell
./scripts/collections/Validate-Collections.ps1 -OutputPath custom/results.json
```
## Steps to Reproduce
Read the commit that introduced the change:
- Commit: [57ea279](https://github.com/microsoft/hve-core/commit/57ea279d17424d8fabc4bafe13d793432242e31c)
- File changed: `scripts/collections/Validate-Collections.ps1`
Compare `scripts/collections/README.md` against `scripts/security/README.md` (e.g., lines 55–56, 96, 131, 237) or `scripts/linting/README.md` (e.g., lines 110, 200, 325) to see the documentation pattern that is missing.
## Additional Context
- Documentation file that needs updating: [`scripts/collections/README.md`](https://github.com/microsoft/hve-core/blob/main/scripts/collections/README.md)
- Script that was updated: [`scripts/collections/Validate-Collections.ps1`](https://github.com/microsoft/hve-core/blob/main/scripts/collections/Validate-Collections.ps1)
- Reference examples for documentation style: [`scripts/security/README.md`](https://github.com/microsoft/hve-core/blob/main/scripts/security/README.md), [`scripts/linting/README.md`](https://github.com/microsoft/hve-core/blob/main/scripts/linting/README.md)
- Triggered by push of commit `57ea279` to `main`
> Generated by [Documentation Update Check](https://github.com/microsoft/hve-core/actions/runs/25277998574/agentic_workflow) · ● 1.2M · [◷](https://github.com/search?q=repo%3Amicrosoft%2Fhve-core+is%3Aissue+%22gh-aw-workflow-call-id%3A+microsoft%2Fhve-core%2Fdoc-update-check%22&type=issues)
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with scripts/collections/README.md, then inspect scripts/collections/Validate-Collections.ps1 and the matching sections in scripts/security/README.md and scripts/linting/README.md. Document -OutputPath, its default, the JSON report and schema, and an override example; the README should match the script's current behavior and peer documentation.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- powershell
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 1/5
- Estimated time
- Under an hour
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 68/100