chore(build): normalize PlatyPS-generated doc line endings to LF

[tablackburn]

Summary

PowerShellBuild's BUILDHELP task invokes PlatyPS, which writes docs/en-US/*.md with CRLF on Windows. That contradicts the repo's .gitattributes (* text=auto eol=lf, pinned in #34) and dirties git status after every local build with 28 phantom "modifications" — line-ending only, zero content change.

This PR adds two-layer prevention.

Changes

Layer 1 — build-time fix (build.psake.ps1)

New NormalizeDocsLineEndings psake task that runs after Build:

• Walks docs/**/*.md, rewrites any CRLF to LF using UTF-8 without BOM.
• Only writes files that actually changed (avoids touching mtimes unnecessarily).
• UnitTest and ScriptAnalysis now depend on NormalizeDocsLineEndings instead of Build directly, so it always runs in the standard chain.

Layer 2 — pre-commit safety net (.pre-commit-config.yaml)

Adds mixed-line-ending --fix=lf from pre-commit/pre-commit-hooks:

• Catches CRLF from any other source — editors, ad-hoc tooling, future tasks — before it reaches the index.
• .gitattributes alone only acts at git operations and can't stop a tool from writing CRLF into the working tree between operations. This is the safety net.

Verification

Layer 1 — local ./build.ps1 UnitTest run:

Task: BUILDHELP
Task: NORMALIZEDOCSLINEENDINGS
  Normalized 28 doc file(s) to LF
Task: UNITTEST
...
Tests Passed: 1423, Failed: 0, Skipped: 4

Post-build check: 28 files LF-only, 0 with CRLF, git status docs/ clean.

Layer 2 — verified live on this PR's commit:
The pre-commit hook ran during the commit itself:

[INFO] Initializing environment for https://github.com/pre-commit/pre-commit-hooks.
[INFO] Installing environment for https://github.com/pre-commit/pre-commit-hooks.
mixed line ending........................................................Passed

Test plan

• ./build.ps1 -Task UnitTest — 1423 pass, 0 fail, NormalizeDocsLineEndings reports Normalized 28 doc file(s) to LF
• git status clean after build (no phantom doc modifications)
• Pre-commit hook runs and passes on commit
• CI: PSScriptAnalyzer + Unit Tests pass
• CI: pre-commit.ci confirms mixed-line-ending hook is valid

Notes

• Surfaced as a side-effect of debugging fix(cluster): surface named-task lookup failures as errors instead of silent partial results #42 — every ./build.ps1 run during that work re-dirtied 28 docs in git status.
• The integration test failure that triggered this discovery is fixed in fix(cluster): surface named-task lookup failures as errors instead of silent partial results #42 (separate root cause); this PR is purely about preventing the recurring git-status noise.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Chores
  • Configured pre-commit hooks to automatically enforce consistent line endings across the repository.
  • Added automated line ending normalization for documentation to the build system, running before unit tests and script analysis to ensure consistency.

[coderabbitai]

Warning

Rate limit exceeded

@tablackburn has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 10 minutes and 40 seconds before requesting another review.

You’ve run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 3606bb53-537b-4266-a6db-8beaac466050

📥 Commits

Reviewing files that changed from the base of the PR and between a3d0e0e and a670c0f.

📒 Files selected for processing (1)

• build.psake.ps1

📝 Walkthrough

Walkthrough

Pre-commit hook and build task are added to enforce consistent LF line endings. The pre-commit hook auto-fixes mixed line endings during commits, while a new build task normalizes documentation markdown files from CRLF to LF before tests and analysis execute.

Changes

Line Ending Normalization

Layer / File(s)	Summary
Pre-commit hook configuration .pre-commit-config.yaml	Mixed-line-ending hook from pre-commit/pre-commit-hooks at v5.0.0 is added with --fix=lf to auto-correct line endings to LF before commits land.
Build task integration build.psake.ps1	New NormalizeDocsLineEndings task scans and rewrites docs/**/*.md files from CRLF to LF (UTF-8 without BOM); UnitTest and ScriptAnalysis tasks are rewired to depend on this normalization task instead of Build.

🎯 2 (Simple) | ⏱️ ~8 minutes

🐰 Line endings dance in files so fair,
LF rules now everywhere,
Pre-commit and build align,
Consistency— a rabbit's design! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main objective: adding build-time and pre-commit normalization of PlatyPS-generated doc line endings from CRLF to LF.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch chore/normalize-doc-line-endings

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Pull request overview

Adds two-layer protection against CRLF line endings being introduced into the repo by PlatyPS doc generation: a psake build task that normalizes docs/**/*.md to LF after Build, and a pre-commit hook as a safety net.

Changes:

• New NormalizeDocsLineEndings psake task runs after Build and rewrites CRLF to LF (UTF-8 no BOM), only touching files that actually changed.
• Reroutes UnitTest and ScriptAnalysis to depend on the new task instead of Build directly.
• Adds pre-commit/pre-commit-hooks mixed-line-ending --fix=lf hook at v5.0.0.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
build.psake.ps1	Adds NormalizeDocsLineEndings task and re-points UnitTest/ScriptAnalysis dependencies to it.
.pre-commit-config.yaml	Adds mixed-line-ending hook from pre-commit-hooks v5.0.0 as a safety net.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[tablackburn]

Style nit (non-blocking): Test-Path -Path $docsPath in the new NormalizeDocsLineEndings task should be Test-Path $docsPath per the named-parameter rule — that rule scopes to 2+ args, and the single-arg variant is the over-application we agreed to revert across the JsmOps#9 / YTMP#23 / Plex#55 / ReScene#18 propagation. Worth fixing here before this pattern lands in the template and gets copied to the other 5 PowerShellBuild + PlatyPS consumers. The other named-param uses in the task (Join-Path -Path … -ChildPath …, Get-ChildItem -Path … -Filter … -Recurse -File) are correctly multi-arg.