[31] Balanced Search Strategy

[TomStrepsil]

Issue

resolves #31

Details

Added a BalancedPairSearchStrategy for matching two string anchors, but respecting nesting levels so only matching where "balanced"

Scout rule

Added [!CAUTION] to README.md re: utf8

Semantic Version Impact

• PATCH - Bug fixes and minor changes (backwards compatible)
• MINOR - New features (backwards compatible)
• MAJOR - Breaking changes (not backwards compatible)

Checklist

• I have added an entry to the [Unreleased] section in CHANGELOG.md
• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes

[Copilot]

Pull request overview

Adds a new nesting-aware “balanced pair” string-anchor search strategy to support matching outer delimiter pairs while respecting nested inner pairs (issue #31), plus documentation and benchmark harness updates to exercise/compare the behavior.

Changes:

• Introduces BalancedPairSearchStrategy (and extensive unit tests) to match balanced opening/closing delimiter pairs across chunks.
• Adds a benchmark-only BalancedPairRegexCountSearchStrategy variant and corresponding harnesses for algorithm comparisons.
• Updates docs (main README, search-strategies README, changelog) and the benchmark validation tests to support skipping scenarios per-harness.

Reviewed changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
test/harnesses/types.ts	Adds optional skipScenario hook to conditionally skip scenarios by harness capabilities.
test/harnesses/index.ts	Exports the new balanced-pair harnesses.
test/harnesses/balanced-pair.ts	Adds a harness wiring the new BalancedPairSearchStrategy into the sync engine.
test/harnesses/balanced-pair-regex-count.ts	Adds a harness for the benchmark-only regex-count balanced-pair variant.
test/benchmarks/algorithm/validate-functionality.test.ts	Adds per-harness conditional skipping for scenarios not applicable to balanced matching.
src/search-strategies/README.md	Documents the new balanced-pair strategy in the search-strategies overview.
src/search-strategies/benchmarking/balanced-pair-regex-count/search-strategy.ts	Implements a benchmark-only balanced-pair variant that counts openings via regex.
src/search-strategies/benchmarking/balanced-pair-regex-count/README.md	Documents the benchmark-only regex-count variant and findings.
src/search-strategies/balanced-pair/search-strategy.ts	Implements the new public balanced-pair search strategy.
src/search-strategies/balanced-pair/search-strategy.test.ts	Adds comprehensive unit tests for balanced matching and stream indices across chunks.
src/search-strategies/balanced-pair/README.md	Adds detailed documentation for the balanced-pair strategy behavior and implementation.
README.md	Adds usage docs for balanced-pair replacement and a UTF-8 encoding caution note for Node adapters.
docs/CHANGELOG.md	Adds changelog entries for the new strategy and README caution update.

---

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

[Copilot]

Pull request overview

Copilot reviewed 16 out of 16 changed files in this pull request and generated 1 comment.