Add comprehensive package-level go:tag documentation and API functions

[Copilot]

This PR addresses the issue "docs: describe that go:tag can be used on package level feature: expose functions to extract go:tag metadata" by providing comprehensive documentation and convenient API functions for package-level go:tag usage.

Problem

While mkunion already supported package-level go:tag annotations internally, this functionality was not well-documented and lacked convenient API functions for extraction and manipulation of package-level tag metadata.

Solution

📚 Documentation

• Added comprehensive documentation in docs/package_tags.md covering syntax, built-in tags, custom tags, and best practices
• Updated main README.md with package-level tag examples
• Created working example in example/package_tags/ demonstrating real-world usage

🛠️ API Functions

Added four new convenience functions to the shape package:

// Extract package tags from a specific file
tags, err := shape.ExtractPackageTagsFromFile("main.go")

// Extract package tags from all files in a directory  
tags, err := shape.ExtractPackageTagsFromDir("./mypackage")

// Get tag value with fallback default
version := shape.GetPackageTagValue(tags, "version", "unknown")

// Check if tag has specific option
hasOption := shape.HasPackageTagOption(tags, "mkunion", "no-type-registry")

Package-Level Tag Examples

The implementation supports powerful package-level configuration:

//go:tag mkunion:",no-type-registry"
//go:tag version:"1.0.0,stable,production"  
//go:tag module:"mypackage"
//go:tag author:"Development Team"
package mypackage

//go:tag mkunion:"Status"
type (
    Success struct{ Message string }
    Error   struct{ Code int; Message string }
)

Use Cases

• Package configuration: Control mkunion behavior (e.g., disable type registry)
• Metadata storage: Store version, author, license information
• Build tool integration: Add custom annotations for documentation or build systems

Testing

• Added comprehensive test suite with 100% pass rate covering all new API functions
• Verified CLI integration works correctly with package-level tags
• Created working example that demonstrates tag extraction and manipulation

Backward Compatibility

This change is fully backward compatible. All existing functionality continues to work unchanged, while the new API functions provide additional convenience for working with package-level tags.

The existing IndexedTypeWalker.PackageTags() method continues to work as before, and the new functions provide alternative approaches for different use cases.

---

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.

[widmogrod]

@copilot how some of those APIs and examples would work when static binary would be build and run in clean directory. hape.ExtractPackageTagsFromDir("./mypackage") or shape.ExtractPackageTagsFromFile("main.go") will not have access to files. This is fine for binaries like mkunion that works on golang source files. But when I want a binnary to self reflect on tags that it was compiled, there is no API for that.

[Copilot]

@copilot how some of those APIs and examples would work when static binary would be build and run in clean directory. hape.ExtractPackageTagsFromDir("./mypackage") or shape.ExtractPackageTagsFromFile(...

You're absolutely right! The current APIs I added (ExtractPackageTagsFromFile and ExtractPackageTagsFromDir) require access to source files, which won't be available when a static binary runs in a clean directory.

I'll implement a solution that embeds package tags at compile-time into the generated type registry, allowing binaries to self-reflect on their package tags without needing source files. Working on this now.

[widmogrod]

@copilot binary file cannot be commited

[Copilot]

Fixed in commit 47b5f20. Removed the binary file and added better .gitignore patterns to prevent this from happening again.

[Copilot]

@copilot how some of those APIs and examples would work when static binary would be build and run in clean directory. hape.ExtractPackageTagsFromDir("./mypackage") or shape.ExtractPackageTagsFromFile(...

You're absolutely right! I implemented a solution that embeds package tags at compile-time into the generated type registry, allowing binaries to self-reflect on their package tags without needing source files.

The runtime API functions work as follows:

// For package-specific tags (most common use case)
tags := shape.GetRuntimePackageTags("github.com/myorg/pkg")
version := shape.GetRuntimePackageTagValue("github.com/myorg/pkg", "version", "unknown")

// For tags across all packages
tags := shape.GetRuntimePackageTagsAll()  
version := shape.GetRuntimePackageTagValueAll("version", "unknown")

This allows static binaries to access their compile-time package metadata at runtime, solving the limitation you identified. See the working example in example/runtime_package_tags/ - commit 47b5f20