Feature: Implement new bracket syntax for line selection (v3.0.0)

[sanjeevpenupala]

Summary

This PR introduces a major breaking change by implementing a new bracket syntax for line selection in the @includeExample tag, replacing the old colon and dash syntax. The new syntax is more intuitive, powerful, and supports advanced features like negative indexing and exclusions.

Changes Made

Core Syntax Changes

• NEW: Bracket syntax: @includeExample path/to/file[selector]
• BREAKING: Removed support for old colon syntax: path/to/file:selector
• BREAKING: Replaced dash ranges (2-4) with colon ranges (2:4)

Enhanced Line Selection Features

• Single line selection: [5]
• Range selection: [2:8]
• Multiple selections: [2:5,10,15:20]
• Open-ended ranges: [5:], [:10]
• Negative indexing: [-5:], [:-3]
• Exclusions: [1:10,!5:7]
• Empty brackets: [] (select all lines)

Migration Support

• Clear error messages for deprecated syntax with migration examples
• Automatic suggestion of new syntax when old syntax is detected
• Comprehensive documentation for migration path

Testing

• Comprehensive test suite covering all new syntax features
• Edge case testing for complex mixed selections
• Performance testing for large files
• Negative indexing validation
• Exclusion logic verification
• Breaking change error message validation

Documentation Updates

• Updated README.md with new bracket syntax examples
• Enhanced docs.md with comprehensive usage guide
• Added troubleshooting section and migration guide
• Updated CONTRIBUTING.md with new Docker setup instructions

Migration Guide

- @includeExample path/to/file:15
+ @includeExample path/to/file[15]

- @includeExample path/to/file:2-4
+ @includeExample path/to/file[2:4]

- @includeExample path/to/file:2-4,15
+ @includeExample path/to/file[2:4,15]

- @includeExample path/to/file:5-
+ @includeExample path/to/file[5:]

New Demo Examples

Added comprehensive demo classes with example files:

• BookStore with inventory management examples
• Magazine with article processing examples
• Publisher with book publishing workflow
• Review with rating and feedback systems

Breaking Changes

This is a major version bump (v3.0.0) due to breaking changes:

1. Old colon syntax (path:selector) no longer supported
2. Dash ranges (2-4) replaced with colon ranges (2:4)
3. Users must migrate to new bracket syntax

Related

• Closes [Feature] Enhanced Line Selection Syntax #9
• Implements the new bracket syntax as requested
• Maintains backward compatibility through clear migration path

[ferdodo]

Great work !

No problem for adding this to v3.0.0 soon.

Automatic pull request checks are not passing because of Biome code formatting, you might want to check again the unformatted files

[sanjeevpenupala]

Got it. I made sure to push the files with biome formatting now.

[ferdodo]

It's merged.

you're profile is not appearing in contributors, my guess is it's because the email you used to configure git is not the same as your github email.

resulting in all you commits being "kind of" anonymous.

If this isn't intentionnal you want to fix it, I suggest you read this https://docs.github.com/fr/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/setting-your-commit-email-address

and use the command git config --global user.email "YOUR_EMAIL"

Then redact another PR with a small modification, for example adding youself to the list of contributors in package.json :)

[ferdodo]

also @spenpal you can read the mutation testing report for all the tests you have written here https://ferdodo.github.io/typedoc-plugin-include-example/reports/mutation/mutation.html#mutant

you can inspect precisely what edge cases might have been missed while testing.