build-tools: Document copyright header optimization findings (#25438)

- [x] Initial plan
- [x] Implement `readFilePartial` function in `common.ts` 
- [x] Optimize copyright header detection to use partial reading
- [x] Add comprehensive test coverage including performance tests
- [x] Fix linting errors in test file (prefer-const, non-null
assertions, unused expressions)
- [x] Run performance benchmarks to validate optimization benefits
- [x] Address user feedback on performance data with comprehensive
analysis
- [x] Remove arbitrary time threshold test as requested
- [x] Resolve all ESLint violations in test file
- [x] Address performance regression for small files with hybrid
approach
- [x] **Remove readFilePartial optimization and revert to original
implementation**

**Final Outcome:** After thorough analysis and optimization attempts,
the copyright header optimization was found to negatively impact
performance for small files (which comprise ~80% of the repository). The
optimization resulted in 12-50% slower performance for the majority of
files, making it not worthwhile for this codebase.

**Changes Made:**
- **REVERTED**: All optimization attempts including `readFilePartial`
function and hybrid approaches
- **UPDATED**: Replaced the original TODO comment with a comprehensive
summary of findings
- **REMOVED**: Test files and performance benchmarks for the removed
functionality
- **DOCUMENTED**: Analysis showing why partial file reading optimization
isn't beneficial for this repository's file size distribution

The TODO comment now documents the investigation results, explaining
that optimization attempts were considered but found counterproductive
due to the repository's file size characteristics where 80% of files are
small and benefit from the simpler full-file reading approach.

<!-- START COPILOT CODING AGENT SUFFIX -->

Created from VS Code via the [GitHub Pull
Request](https://marketplace.visualstudio.com/items?itemName=GitHub.vscode-pull-request-github)
extension.

<!-- START COPILOT CODING AGENT TIPS -->
---

💬 Share your feedback on Copilot coding agent for the chance to win a
$200 gift card! Click
[here](https://survey3.medallia.com/?EAHeSx-AP01bZqG0Ld9QLQ) to start
the survey.

---------

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: alexvy86 <[email protected]>

Author: Copilot

build-tools/packages/build-cli/src/library/repoPolicyCheck/copyrightFileHeader.ts

@@ -60,8 +60,10 @@ function makeHandler(config: IFileConfig): (file: string) => Promise<string | un
 	);
 
 	return async (file: string): Promise<string | undefined> => {
-		// TODO: Consider reading only the first 512B or so since copyright headers are required
-		//       to appear at the beginning of the file.
+		// Note: Reading only the first portion of files for copyright header detection was considered
+		// but found to negatively impact performance for small files (which comprise ~80% of the
+		// repository). Analysis showed that optimization attempts resulted in 12-50% slower performance
+		// for the majority of files, making the optimization not worthwhile for this codebase.
 		const content = readFile(file);
 		if (!regex.test(content)) {
 			return `${config.type} file missing copyright header`;