feat(manifest): add expiry field and deprecation workflow support

[kriscoleman]

Add an optional expiry field to the flag manifest schema to indicate flag deprecation/removal dates. This enables a complete lifecycle management workflow for feature flags, including:

• Manifest schema enhancement: Add expiry field to BaseFlag struct supporting ISO 8601 date format
• Code generation updates: Modify all language generators (Go, Node.js, React, Python, Java, C#, NestJS) to emit deprecation annotations when flags have expiry dates
• Enhanced CLI commands: Update compare and manifest list commands to visually highlight deprecated flags
• New usage analysis command: Add manifest usage command to search codebase for flag references, reporting file paths, line numbers, and occurrence counts

This feature addresses a common pain point in feature flag management: understanding when flags are no longer needed and measuring the scope of work required to safely remove them.

Acceptance Criteria

Schema and Core Changes

• Add optional expiry field to BaseFlag struct in internal/manifest/json-schema.go
• Field should accept ISO 8601 date strings (e.g., "2025-12-31")
• Update JSON schema generation to include the new field
• Add validation to ensure expiry dates are properly formatted
• Ensure backward compatibility (field is optional)

Generator Updates

• Update Go generator to add // Deprecated: expires on YYYY-MM-DD comments for expired flags
• Update Node.js generator to add @deprecated expires on YYYY-MM-DD JSDoc tags
• Update React generator to add deprecation comments/JSDoc
• Update Python generator to add deprecation warnings/docstrings
• Update Java generator to add @Deprecated annotations with comments
• Update C# generator to add [Obsolete("expires on YYYY-MM-DD")] attributes
• Update NestJS generator to add deprecation JSDoc tags

CLI Command Enhancements

• Update manifest list command to visually indicate deprecated flags (e.g., with warning icon or color)
• Show expiry date in the flag list table output
• Update compare command to highlight when deprecation status changes between manifests
• Add special notation for flags that have already expired vs. future expiry

New Usage Analysis Command

• Create new manifest usage command with flag key parameter
• Implement file search functionality to find flag usage patterns across codebase
• Support common flag access patterns for each supported language:
  • Go: flags.MyFlag()
  • JavaScript/TypeScript: flags.myFlag(), getStringValue('my-flag')
  • Python: flags.my_flag()
  • Java: flags.getMyFlag()
  • C#: flags.MyFlag
• Output format should include:
  • Total occurrence count
  • File paths with line numbers
  • Context line showing the usage
• Add --format flag supporting table, JSON, and YAML output
• Add --path flag to limit search scope to specific directories

Documentation and Testing

• Update manifest schema documentation/examples with expiry field
• Add tests for expiry field parsing and validation
• Add tests for deprecated flag handling in generators
• Add integration tests for usage analysis command
• Update CLI documentation to explain deprecation workflow

Notes

• The expiry field should be purely informational and not affect runtime behavior
• Consider adding a future enhancement for warning users about flags that are past their expiry date
• The usage analysis command will help teams estimate the effort required to remove deprecated flags
• Deprecation annotations will provide IDE warnings to developers using deprecated flags
• Consider adding --include-expired and --exclude-expired filters to manifest list command