feat: Add stack metadata construct for repository and pipeline information

[hoegertn]

Summary

This PR introduces a new stack metadata construct that automatically captures and adds repository and CI/CD pipeline information to CDK stacks, following the same architectural pattern as the existing versioning feature.

Features Implemented

Repository Metadata

• Provider Detection: Automatically detects GitHub, GitLab, or AWS CodeBuild environments
• Repository Information: Captures owner, repository name, branch name, and commit hash
• Multi-Provider Support: Works seamlessly across GitHub Actions, GitLab CI, and AWS CodeBuild

Pipeline Metadata

• Job Information: Captures job ID, job URL, and triggering user
• CI/CD Context: Records relevant pipeline execution information
• Environment-Based: Extracts data from CI/CD environment variables

Environment Variable Support

• ✅ GitHub Actions environment variables (GITHUB_*)
• ✅ GitLab CI environment variables (CI_*, GITLAB_*)
• ✅ AWS CodeBuild environment variables (CODEBUILD_*)
• ✅ Custom environment variable name overrides via configuration

Implementation Details

Architecture

Follows the same pattern as src/versioning/:

• Helper Classes: RepoInfoHelper and PipelineInfoHelper for environment variable extraction
• Type Definitions: Comprehensive TypeScript interfaces for RepoInfo and PipelineInfo
• Construct Class: StackMetadata construct that uses Stack.of(this).addMetadata()
• Factory Methods: Both fromEnvironment() and manual configuration support

File Structure

src/metadata/
├── index.ts              # Public API exports
├── types.ts              # TypeScript interfaces
├── repo-info.ts          # Repository information helper
├── pipeline-info.ts      # Pipeline information helper
└── stack-metadata.ts     # Main construct class

Usage Example

import { StackMetadata } from '@open-constructs/cdk-devops';

// Automatic detection from environment
new StackMetadata(stack, 'Metadata');

// Or with custom configuration
new StackMetadata(stack, 'Metadata', {
  repoInfo: {
    provider: 'github',
    owner: 'my-org',
    repository: 'my-repo',
    branch: 'main',
    commitHash: 'abc123'
  }
});

Testing

Comprehensive unit tests covering:

• ✅ Environment variable extraction for all three providers (GitHub, GitLab, CodeBuild)
• ✅ Custom environment variable configuration
• ✅ Metadata addition to CDK stacks
• ✅ Different provider scenarios and edge cases
• ✅ Missing environment variable handling

Documentation

• API Documentation: Updated API.md with complete API reference
• Usage Guide: New METADATA_USAGE.md with examples and best practices
• Example Code: Provided in examples/metadata-example.ts

Breaking Changes

None. This is a purely additive feature.

Checklist

• Implementation follows versioning feature pattern
• TypeScript interfaces defined for all types
• Helper classes for environment variable extraction
• Support for GitHub, GitLab, and CodeBuild
• Custom environment variable override support
• fromEnvironment() factory method implemented
• Exported through src/index.ts
• Comprehensive unit tests
• Documentation updated
• Example code provided