diff --git a/docs/roadmap/audit/02-efficiency.md b/docs/roadmap/audit/02-efficiency.md new file mode 100644 index 0000000..6fd8fd0 --- /dev/null +++ b/docs/roadmap/audit/02-efficiency.md @@ -0,0 +1,35 @@ +# Efficiency audit + +Reviewed baseline: `812c24d` on `main`. This review examined the Go facade, +CLI, candidate validation, committed-tree and path inspection, build, +publication, and hosted-delivery paths for correctness and avoidable scaling +costs. Complexity estimates below describe the code, not measured timings. +Previously recorded correctness and security findings remain in their +respective audit documents. + +## File-size exclusions are scanned for every selected file + +**Relevant code:** [checkFileSize and excludedByPath](../../../internal/validation/file_size.go). +The public [file-size settings](../../../check.go) accept literal file and +directory exclusions. + +For each selected blob, `checkFileSize` calls `excludedByPath`, which scans +the normalized exclusions until it finds a match. With N selected blobs and E +exclusions, inputs with no matches require N × E path comparisons; when N and +E grow together, this is quadratic, before Git is asked for any blob sizes. +String comparison also depends on path length. This is a potential scaling +cost for consumers with large repositories and extensive exclusion lists; the +review did not measure its practical impact. + +**Potential refactoring:** Index normalized exclusions once in a hash set, +then test each file path and its directory ancestors, including the special +`.` exclusion. This takes expected O(E) indexing plus O(N × D) lookups for +maximum path depth D, apart from string-processing costs, instead of scanning +all E exclusions for each file. A component trie is another option if path +processing warrants it. Preserve literal component-boundary matching, +module-relative normalization, the order of selected files, and the first +oversized-file result. Existing exclusion cases cover the semantics; add +targeted cases for shared prefixes and nested directories if refactored. + +The [security audit](07-security.md#3-low-remote-content-verification-reads-beyond-the-known-matching-size) +separately records avoidable remote asset reads beyond the expected size.