microsoft / microsoft/hve-core

docs: update scripts/collections/README.md for new -OutputPath parameter and JSON log output

Open Beginner friendly
#1,514 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

documentation needs-triage
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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.