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

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

Start with internal/manifest/json-schema.go to understand BaseFlag and the generated JSON schema. Then trace the existing manifest list and compare commands and each named language generator before planning the manifest usage command. Done means the optional ISO 8601 field, validation, annotations, CLI output, usage reporting, documentation, and tests meet the listed acceptance criteria.