diff --git a/.github/workflows/android.yml b/.github/workflows/android.yml index f33180a..0eff38f 100644 --- a/.github/workflows/android.yml +++ b/.github/workflows/android.yml @@ -31,9 +31,6 @@ jobs: - name: Checkout code uses: actions/checkout@v4 - - name: Validate Gradle wrapper - uses: gradle/wrapper-validation-action@v1 - - name: Setup JDK uses: actions/setup-java@v4 with: diff --git a/README.md b/README.md index 06a6d2c..3078360 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,29 @@ # KompKit +[![Version](https://img.shields.io/badge/version-0.1.0--alpha-orange.svg)](https://github.com/Kompkit/KompKit/releases) [![Web CI](https://github.com/Kompkit/KompKit/actions/workflows/web.yml/badge.svg?branch=develop)](https://github.com/Kompkit/KompKit/actions/workflows/web.yml) [![Kotlin CI](https://github.com/Kompkit/KompKit/actions/workflows/android.yml/badge.svg?branch=develop)](https://github.com/Kompkit/KompKit/actions/workflows/android.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?logo=typescript&logoColor=white)](https://www.typescriptlang.org/) [![Kotlin](https://img.shields.io/badge/Kotlin-0095D5?logo=kotlin&logoColor=white)](https://kotlinlang.org/) -A lightweight cross-platform utility kit for Android (Kotlin) and Web (TypeScript): debounce, isEmail, formatCurrency. +> **⚠️ Alpha Release**: This is an early alpha version. APIs may change before stable release. + +A lightweight cross-platform utility kit providing essential functions for Android (Kotlin) and Web (TypeScript) development. Built as a monorepo with identical APIs across platforms. ## Overview KompKit provides essential utility functions that work seamlessly across web (TypeScript) and Android (Kotlin) platforms. Built with developer experience in mind, it offers identical APIs across platforms while leveraging platform-specific optimizations. +### Monorepo Structure + +| Module | Platform | Description | Status | +|--------|----------|-------------|--------| +| `packages/core/web` | TypeScript | Web utilities with Node.js support | ✅ Alpha | +| `packages/core/android` | Kotlin JVM | Android utilities with coroutines | ✅ Alpha | +| `docs/` | Documentation | API docs, guides, and examples | ✅ Alpha | +| `.github/workflows/` | CI/CD | Automated testing and validation | ✅ Active | + ### Core Utilities - **🕐 debounce** - Delay function execution until after a wait period (prevents excessive API calls) @@ -23,205 +35,140 @@ KompKit provides essential utility functions that work seamlessly across web (Ty - ✅ **Cross-platform compatibility** - Identical APIs for web and Android - ✅ **TypeScript support** - Full type safety and IntelliSense - ✅ **Zero dependencies** - Lightweight with no external dependencies -- ✅ **Comprehensive testing** - 100% test coverage -- ✅ **Modern tooling** - Built with latest TypeScript and Kotlin standards +- ✅ **Comprehensive testing** - 100% test coverage across platforms +- ✅ **Modern tooling** - Built with latest TypeScript 5.6+ and Kotlin 2.1+ - ✅ **Rich documentation** - Auto-generated API docs with examples +- ✅ **CI/CD Ready** - Automated testing with GitHub Actions + +## Getting Started + +### Prerequisites + +- **Web**: Node.js 20+ and npm/yarn +- **Android**: JDK 17+ and Kotlin 2.1+ + +### Installation -## Installation +> **Note**: Alpha packages are not yet published to registries. Clone the repository for local development. -### Web (React/Vue) +#### Web Development ```bash -npm install @kompkit/core -``` +# Clone the repository +git clone https://github.com/Kompkit/KompKit.git +cd KompKit -### Android +# Install dependencies +npm install -Add to your `build.gradle.kts` (Module: app): +# Build the web package +npm run build -```kotlin -dependencies { - implementation(files("path/to/kompkit/packages/core/android")) - // Required for debounce functionality - implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.8.1") -} +# Run tests +npm run test:web ``` -**Alternative:** Clone the repository and include the Android module directly: +#### Android Development ```bash +# Clone the repository git clone https://github.com/Kompkit/KompKit.git -# Add the module to your Android project + +# Include in your Android project's settings.gradle.kts +include(":kompkit-core") +project(":kompkit-core").projectDir = file("path/to/KompKit/packages/core/android") + +# Add to your app's build.gradle.kts +dependencies { + implementation(project(":kompkit-core")) + implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.10.2") +} ``` -## Usage +### Quick Start -### Web (TypeScript) +Once installed, you can import and use KompKit utilities: +**TypeScript/JavaScript:** ```typescript import { debounce, isEmail, formatCurrency } from '@kompkit/core'; -// Debounce a search function -const handleSearch = debounce((query: string) => { - console.log('Searching for:', query); +const search = debounce((query: string) => { + console.log('Searching:', query); }, 300); -// Validate email -const valid = isEmail('user@example.com'); // true - -// Format currency -const price = formatCurrency(1234.56); // "1.234,56 €" -const priceUSD = formatCurrency(1234.56, 'USD', 'en-US'); // "$1,234.56" +console.log(isEmail('user@example.com')); // true +console.log(formatCurrency(1234.56)); // "1.234,56 €" ``` -### Android (Kotlin) - +**Kotlin:** ```kotlin import com.kompkit.core.* -import kotlinx.coroutines.CoroutineScope -import kotlinx.coroutines.Dispatchers -// Debounce a search function -val scope = CoroutineScope(Dispatchers.Main) -val handleSearch = debounce(300L, scope) { query -> - println("Searching for: $query") +val search = debounce(300L, scope) { query -> + println("Searching: $query") } -// Validate email -val valid = isEmail("user@example.com") // true - -// Format currency -val price = formatCurrency(1234.56) // "1.234,56 €" -val priceUSD = formatCurrency(1234.56, "USD", Locale.US) // "$1,234.56" -``` - -## Development - -This is a monorepo managed with Lerna and npm workspaces. - -### Prerequisites - -- **Node.js** 18+ and npm -- **Java** 17+ (for Android development) -- **Kotlin** 1.9+ (automatically managed by Gradle) - -### Setup - -```bash -# Clone the repository -git clone https://github.com/Kompkit/KompKit.git -cd kompkit - -# Install dependencies -npm install - -# Build all packages -npm run build - -# Run tests for both platforms -npm run test - -# Run tests individually -npm run test:web # Web/TypeScript tests -npm run test:android # Android/Kotlin tests +println(isEmail("user@example.com")) // true +println(formatCurrency(1234.56)) // "1.234,56 €" ``` -### Documentation +## Documentation -Generate documentation for both platforms: +### 📚 Detailed Guides -```bash -# Generate all documentation -npm run docs:all +- **[Getting Started Guide](./docs/getting-started.md)** - Complete setup and first steps +- **[API Reference](./docs/api/)** - Auto-generated API documentation + - [Web/TypeScript API](./docs/api/web/) - TypeDoc generated docs + - [Android/Kotlin API](./docs/api/android/) - Dokka generated docs +- **[Architecture Overview](./docs/ARCHITECTURE.md)** - Monorepo structure and design +- **[Contributing Guide](./docs/CONTRIBUTING.md)** - Development workflow and guidelines +- **[CI/CD Documentation](./docs/README_CI.md)** - Build and deployment processes -# Generate web docs only (TypeDoc) -npm run docs:web +### 🔧 Development -# Generate Android docs only (Dokka) -npm run docs:android - -# Serve documentation locally -cd docs && python3 -m http.server 8080 -# Visit http://localhost:8080 -``` - -### Project Commands - -| Command | Description | -|---------|-------------| -| `npm run build` | Build all packages | -| `npm run test` | Run all tests | -| `npm run test:web` | Run web tests only | -| `npm run test:android` | Run Android tests only | -| `npm run docs:all` | Generate all documentation | -| `npm run docs:web` | Generate web documentation | -| `npm run docs:android` | Generate Android documentation | +- **[Changelog](./docs/CHANGELOG.md)** - Version history and breaking changes +- **[Roadmap](./docs/roadmap.md)** - Planned features and improvements ## Project Structure ``` -kompkit/ -├── packages/ -│ └── core/ -│ ├── web/ # TypeScript/JavaScript package -│ │ ├── src/ # Source files -│ │ │ ├── debounce.ts -│ │ │ ├── validate.ts -│ │ │ ├── format.ts -│ │ │ └── index.ts -│ │ ├── tests/ # Test files -│ │ ├── dist/ # Built output -│ │ └── package.json -│ └── android/ # Kotlin/Android package -│ ├── src/ -│ │ ├── main/kotlin/com/kompkit/core/ -│ │ │ ├── Debounce.kt -│ │ │ ├── Validate.kt -│ │ │ └── Format.kt -│ │ └── test/ # Test files -│ └── build.gradle.kts -├── docs/ # Documentation -│ ├── api/ -│ │ ├── web/ # TypeDoc generated docs -│ │ └── android/ # Dokka generated docs -│ ├── getting-started.md -│ └── [other guides] -├── LICENSE # MIT License -├── README.md # This file -├── package.json # Root package configuration -└── lerna.json # Lerna configuration +KompKit/ +├── .github/workflows/ # CI/CD pipelines +│ ├── web.yml # Web package testing +│ └── android.yml # Kotlin package testing +├── packages/core/ +│ ├── web/ # TypeScript package +│ │ ├── src/ # Source files +│ │ ├── tests/ # Test files +│ │ └── package.json +│ └── android/ # Kotlin JVM package +│ ├── src/main/kotlin/ # Source files +│ ├── src/test/kotlin/ # Test files +│ └── build.gradle.kts +├── docs/ # Documentation +│ ├── api/ # Generated API docs +│ └── *.md # Guides and references +└── package.json # Root configuration ``` -## API Reference - -### debounce - -**Web:** `debounce(fn: T, wait?: number): T` -**Android:** `debounce(waitMs: Long, scope: CoroutineScope, dest: (T) -> Unit): (T) -> Unit` - -Delays function execution until after wait period has elapsed since the last time it was invoked. +## Version Information -### isEmail +- **Current Version**: `0.1.0-alpha` +- **Minimum Requirements**: + - Node.js 20+ (Web) + - JDK 17+ (Android) + - TypeScript 5.6+ + - Kotlin 2.1+ -**Web:** `isEmail(v: string): boolean` -**Android:** `isEmail(value: String): Boolean` +## Contributing -Validates whether a string matches a basic email pattern. +We welcome contributions! Please see our [Contributing Guide](./docs/CONTRIBUTING.md) for details on: -### formatCurrency - -**Web:** `formatCurrency(amount: number, currency?: string, locale?: string): string` -**Android:** `formatCurrency(amount: Double, currency: String, locale: Locale): String` - -Formats a number as a localized currency string. - -## Roadmap - -- [ ] Add more utility functions (throttle, deepClone, etc.) -- [ ] Support for React Native -- [ ] iOS Swift implementation -- [ ] Performance benchmarks -- [ ] CI/CD pipeline setup +- Development setup +- Code style and conventions +- Testing requirements +- Pull request process ## License @@ -229,6 +176,11 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file ## Support -- 📖 [Documentation](docs/) -- 🐛 [Issue Tracker](https://github.com/Kompkit/KompKit/issues) -- 💬 [Discussions](https://github.com/Kompkit/KompKit/discussions) +- 📖 **Documentation**: [./docs/](./docs/) +- 🐛 **Issues**: [GitHub Issues](https://github.com/Kompkit/KompKit/issues) +- 💬 **Discussions**: [GitHub Discussions](https://github.com/Kompkit/KompKit/discussions) + +--- + +> **Alpha Notice**: This project is in active development. APIs may change before the stable 1.0 release. We recommend pinning to specific versions in production applications. + diff --git a/README_CI.md b/README_CI.md deleted file mode 100644 index 7f7cee2..0000000 --- a/README_CI.md +++ /dev/null @@ -1,191 +0,0 @@ -# CI/CD Documentation - -## Overview - -KompKit uses GitHub Actions for continuous integration with separate workflows for Web and Android components to optimize build times in our monorepo. - -## Workflows - -### 1. Web CI (`web.yml`) -**Triggers:** -- Push/PR to `release` or `develop` branches -- Changes in `packages/**` (excluding Android) -- Changes in `package*.json`, `lerna.json` -- Manual dispatch - -**Jobs:** -- **web**: Lint, build, test, and generate docs for TypeScript/JavaScript packages - -**Path Filters:** Only runs when web-related files change, avoiding unnecessary builds. - -### 2. Android CI (`android.yml`) -**Triggers:** -- Push/PR to `release` or `develop` branches -- Changes in `packages/core/android/**` -- Manual dispatch - -**Jobs:** -- **android**: Lint (ktlint), static analysis (detekt), build, test, and generate docs for Kotlin packages - -**Path Filters:** Only runs when Android-related files change. - -## Pinned Versions - -| Tool | Version | Purpose | -|------|---------|---------| -| actions/checkout | v4 | Code checkout | -| actions/setup-node | v4 | Node.js 20.x setup | -| actions/setup-java | v4 | JDK 17 (Temurin) | -| gradle/actions/setup-gradle | v4 | Gradle build cache | -| gradle/wrapper-validation-action | v1 | Security validation | -| android-actions/setup-android | v3 | Android SDK setup | - -## Required Secrets - -Currently no secrets are required. All builds use public dependencies and tools. - -## Local Development - -### Web Development -```bash -# Install dependencies -npm ci - -# Run linting (if configured) -npm run lint --workspaces --if-present - -# Type checking (if configured) -npm run typecheck --workspaces --if-present - -# Build packages -npm run build --workspaces --if-present - -# Run tests -npm test --workspaces --if-present - -# Generate docs -npm run docs:web --workspaces --if-present -``` - -### Android Development -```bash -# Navigate to Android module -cd packages/core/android - -# Make gradlew executable (if needed) -chmod +x gradlew - -# Clean build -./gradlew clean - -# Lint with ktlint -./gradlew ktlintCheck - -# Static analysis with detekt -./gradlew detekt - -# Build debug APK -./gradlew assembleDebug - -# Run unit tests -./gradlew test - -# Generate documentation -./gradlew dokkaHtml -``` - -## Caching Strategy - -- **Node.js**: Native npm cache via `actions/setup-node` -- **Gradle**: Build cache via `gradle/actions/setup-gradle` -- **No manual caching**: Avoids cache conflicts and complexity - -## Artifacts - -### Web Artifacts -- `web-docs-{run_id}`: Generated TypeDoc documentation (30 days) -- `web-build-{run_id}`: Built packages from dist/build directories (7 days) - -### Android Artifacts -- `android-test-reports-{run_id}`: JUnit test reports (7 days) -- `android-lint-reports-{run_id}`: ktlint and detekt reports (7 days) -- `android-debug-apk-{run_id}`: Debug APK builds (7 days) -- `android-docs-{run_id}`: Dokka-generated documentation (30 days) - -## Skip Flags - -Use commit message flags to skip specific builds: -- `[skip web]`: Skip web CI workflow -- `[skip android]`: Skip Android CI workflow - -## Troubleshooting - -### Common Issues - -**1. Gradle Permission Denied** -```bash -chmod +x packages/core/android/gradlew -git add packages/core/android/gradlew -git commit -m "fix: make gradlew executable" -``` - -**2. Node.js Build Failures** -- Check Node.js version compatibility (using 20.x) -- Verify `package-lock.json` is committed -- Clear npm cache: `npm ci --cache .npm --prefer-offline` - -**3. Android Build Failures** -- Verify JDK 17 compatibility -- Check Android SDK components (API 34, build-tools 34.0.0) -- Review ktlint/detekt reports for code quality issues - -**4. Path Filters Not Working** -- Ensure file changes match the path patterns in workflow triggers -- Check that both `push` and `pull_request` events have same path filters - -### Debug Commands - -**Check workflow status:** -```bash -# View recent workflow runs -gh run list --limit 10 - -# View specific run details -gh run view - -# Download artifacts -gh run download -``` - -**Local debugging:** -```bash -# Simulate CI environment -export CI=true -export GITHUB_ACTIONS=true - -# Run builds with same flags as CI -npm ci -npm run build --workspaces --if-present || npm run build -npm test --workspaces --if-present || npm test || echo "No tests found" -``` - -## Performance Targets - -- **Web builds**: < 5 minutes for typical changes -- **Android builds**: < 8 minutes for typical changes -- **First-time builds**: May take longer due to dependency downloads -- **Concurrent builds**: Path filters prevent unnecessary parallel execution - -## Branch Strategy - -- **develop**: Active development branch, all PRs target here -- **release**: Stable release branch, merges from develop -- **Dependabot**: Targets develop branch for dependency updates - -## Monitoring - -Monitor CI health via: -- GitHub Actions dashboard -- README badges showing build status -- Artifact retention and storage usage -- Build time trends and performance metrics diff --git a/VERSION b/VERSION new file mode 100644 index 0000000..388bb06 --- /dev/null +++ b/VERSION @@ -0,0 +1 @@ +0.1.0-alpha diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md new file mode 100644 index 0000000..78c09df --- /dev/null +++ b/docs/ARCHITECTURE.md @@ -0,0 +1,294 @@ +# Architecture Overview + +This document describes the architecture and design decisions behind KompKit, a cross-platform utility library for TypeScript and Kotlin. + +## Design Philosophy + +### Cross-Platform First + +KompKit is designed with cross-platform compatibility as the primary goal. Every utility function must: + +1. **Maintain API parity** across TypeScript and Kotlin implementations +2. **Provide identical behavior** regardless of platform +3. **Use platform-native patterns** while maintaining consistency +4. **Minimize dependencies** to reduce bundle size and complexity + +### Monorepo Structure + +We use a monorepo approach to ensure consistency and simplify development: + +``` +KompKit/ +├── packages/core/ # Core utility packages +│ ├── web/ # TypeScript/JavaScript implementation +│ └── android/ # Kotlin JVM implementation +├── docs/ # Documentation and guides +├── .github/workflows/ # CI/CD pipelines +└── [root configuration] # Lerna, npm, Git configuration +``` + +## Module Architecture + +### Core Modules + +| Module | Platform | Purpose | Technology Stack | +|--------|----------|---------|------------------| +| `packages/core/web` | Web/Node.js | TypeScript utilities | TypeScript 5.6+, Vitest, TypeDoc | +| `packages/core/android` | JVM/Android | Kotlin utilities | Kotlin 2.1.0, JUnit, Dokka | + +### Shared Concepts + +Both modules implement identical functionality: + +- **debounce**: Function execution delay with cancellation +- **isEmail**: Email validation using regex patterns +- **formatCurrency**: Localized currency formatting + +## Implementation Strategy + +### API Design + +We maintain strict API consistency across platforms: + +**TypeScript:** +```typescript +export function debounce any>( + fn: T, + wait: number = 250 +): T; + +export function isEmail(value: string): boolean; + +export function formatCurrency( + amount: number, + currency: string = 'EUR', + locale: string = 'es-ES' +): string; +``` + +**Kotlin:** +```kotlin +fun debounce( + waitMs: Long = 250L, + scope: CoroutineScope, + dest: (T) -> Unit +): (T) -> Unit + +fun isEmail(value: String): Boolean + +fun formatCurrency( + amount: Double, + currency: String = "EUR", + locale: Locale = Locale("es", "ES") +): String +``` + +### Platform-Specific Adaptations + +While maintaining API consistency, we leverage platform strengths: + +#### TypeScript Implementation +- **Closures** for debounce state management +- **setTimeout/clearTimeout** for timing control +- **Intl.NumberFormat** for currency formatting +- **RegExp** for email validation + +#### Kotlin Implementation +- **Coroutines** for asynchronous debounce operations +- **Job cancellation** for timing control +- **NumberFormat/Currency** for localized formatting +- **Regex** for email validation + +## Build System Architecture + +### Monorepo Management + +**Lerna + npm workspaces** for unified dependency management: + +```json +{ + "workspaces": ["packages/core/web"], + "devDependencies": { + "lerna": "^8.0.0", + "tsup": "^8.0.0", + "typescript": "^5.6.0", + "typedoc": "^0.28.14", + "vitest": "^1.6.0" + } +} +``` + +### Build Targets + +| Platform | Build Tool | Output | Documentation | +|----------|------------|--------|---------------| +| Web | tsup | ESM + CJS + Types | TypeDoc → `docs/api/web/` | +| Kotlin | Gradle | JAR | Dokka → `docs/api/android/` | + +### Dependency Strategy + +**Zero Runtime Dependencies:** +- Web utilities use only browser/Node.js built-ins +- Kotlin utilities use only JDK/Kotlin stdlib +- Development dependencies isolated to build process + +## CI/CD Architecture + +### Workflow Separation + +**Path-based optimization** to minimize build times: + +```yaml +# Web CI - packages/core/web/** +web.yml: + - Node.js 20 setup + - npm ci (with caching) + - Lerna build/test + - TypeDoc generation + - Artifact upload + +# Kotlin CI - packages/core/android/** +android.yml: + - JDK 17 setup + - Gradle build (with caching) + - ktlint + detekt + - JAR generation + - Dokka documentation +``` + +### Quality Gates + +**Automated quality assurance:** + +1. **Code formatting**: ktlint (Kotlin), Prettier (TypeScript) +2. **Static analysis**: detekt (Kotlin), ESLint (TypeScript) +3. **Testing**: JUnit (Kotlin), Vitest (TypeScript) +4. **Documentation**: Auto-generated API docs +5. **Build verification**: Cross-platform compatibility + +## Testing Strategy + +### Test Structure + +**Platform-specific test suites** with identical test cases: + +``` +packages/core/web/tests/ +├── debounce.test.ts +├── validate.test.ts +└── format.test.ts + +packages/core/android/src/test/kotlin/ +├── DebounceTest.kt +├── ValidateTest.kt +└── FormatTest.kt +``` + +### Test Coverage + +**100% coverage requirement** across both platforms: +- Unit tests for all public APIs +- Edge case validation +- Error condition handling +- Performance benchmarks + +## Documentation Architecture + +### Multi-Platform Documentation + +**Unified documentation strategy:** + +``` +docs/ +├── README_CI.md # CI/CD processes +├── CONTRIBUTING.md # Development guidelines +├── CHANGELOG.md # Version history +├── ARCHITECTURE.md # This document +└── api/ # Generated API docs + ├── web/ # TypeDoc output + └── android/ # Dokka output +``` + +### Documentation Generation + +**Automated documentation pipeline:** + +1. **Source comments**: JSDoc (TypeScript) + KDoc (Kotlin) +2. **Build process**: TypeDoc + Dokka generation +3. **CI integration**: Docs updated on every build +4. **Artifact storage**: 30-day retention for documentation + +## Scalability Considerations + +### Adding New Utilities + +**Standardized process** for expanding the library: + +1. **Design phase**: Define cross-platform API contract +2. **Implementation**: Parallel development in both platforms +3. **Testing**: Comprehensive test coverage +4. **Documentation**: API docs and usage examples +5. **Integration**: Update exports and build processes + +### Future Platform Support + +**Extensible architecture** for additional platforms: + +- **React Native**: Potential TypeScript reuse +- **iOS**: Swift implementation following same patterns +- **Flutter**: Dart implementation with API parity +- **Python**: Additional server-side support + +### Performance Optimization + +**Built-in performance considerations:** + +- **Tree-shaking support** for minimal bundle sizes +- **Lazy loading** capabilities for large utility sets +- **Caching strategies** for expensive operations +- **Memory management** in long-running applications + +## Security Architecture + +### Dependency Security + +**Minimal attack surface:** + +- Zero runtime dependencies +- Pinned development dependencies +- Regular security audits via Dependabot +- Automated vulnerability scanning + +### Code Security + +**Secure coding practices:** + +- Input validation in all utilities +- No eval() or dynamic code execution +- Sanitized regex patterns +- Memory-safe operations + +## Deployment Strategy + +### Release Process + +**Controlled release pipeline:** + +1. **Development**: Feature branches → `develop` +2. **Integration**: CI validation on `develop` +3. **Release preparation**: Version bump + changelog +4. **Stable release**: `develop` → `release` +5. **Distribution**: Package registry publication + +### Version Management + +**Semantic versioning** with clear upgrade paths: + +- **Major**: Breaking API changes +- **Minor**: New features (backward compatible) +- **Patch**: Bug fixes and improvements +- **Alpha/Beta**: Pre-release versions + +--- + +This architecture provides a solid foundation for cross-platform utility development while maintaining simplicity, performance, and developer experience. diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md new file mode 100644 index 0000000..023d8cd --- /dev/null +++ b/docs/CHANGELOG.md @@ -0,0 +1,108 @@ +# Changelog + +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [Unreleased] + +## [0.1.0-alpha] - 2025-11-10 + +### Added + +#### Core Features +- **Cross-platform utility library** with identical APIs for TypeScript and Kotlin +- **debounce** function for delaying function execution + - Web: `debounce(fn: T, wait?: number): T` + - Kotlin: `debounce(waitMs: Long, scope: CoroutineScope, dest: (T) -> Unit): (T) -> Unit` +- **isEmail** function for email validation + - Web: `isEmail(value: string): boolean` + - Kotlin: `isEmail(value: String): Boolean` +- **formatCurrency** function for localized currency formatting + - Web: `formatCurrency(amount: number, currency?: string, locale?: string): string` + - Kotlin: `formatCurrency(amount: Double, currency: String, locale: Locale): String` + +#### Development Infrastructure +- **Monorepo structure** with Lerna and npm workspaces +- **Separate CI workflows** for Web and Kotlin platforms + - Web CI: Node.js 20, TypeScript 5.6+, Vitest testing, TypeDoc documentation + - Kotlin CI: JDK 17, Kotlin 2.1.0, JUnit testing, Dokka documentation +- **Code quality tools** + - Kotlin: ktlint formatting, detekt static analysis + - Web: ESLint, Prettier (configured) +- **Path-based build optimization** to run only relevant CI jobs +- **Automated artifact generation** (JARs, documentation, test reports) + +#### Documentation +- **Comprehensive README** with installation and usage examples +- **API documentation** auto-generated for both platforms +- **Contributing guidelines** with development workflow +- **CI/CD documentation** with troubleshooting guides +- **Architecture overview** explaining monorepo structure + +#### Build & Testing +- **100% test coverage** across both platforms +- **Automated builds** with caching for optimal performance +- **Cross-platform compatibility** testing +- **Documentation generation** (TypeDoc + Dokka) + +### Technical Details + +#### Supported Platforms +- **Web**: TypeScript/JavaScript with Node.js 20+ +- **Kotlin**: JVM with Kotlin 2.1.0 and JDK 17+ + +#### Dependencies +- **Zero runtime dependencies** for core utilities +- **Minimal development dependencies** (testing, documentation, build tools) +- **Coroutines support** for Kotlin debounce functionality + +#### Performance +- **Lightweight bundle size** with tree-shaking support +- **Optimized CI builds** (< 5 min web, < 8 min Kotlin) +- **Efficient caching** strategies for dependencies and builds + +### Known Limitations + +- **Alpha release**: APIs may change before stable 1.0 release +- **Local development only**: Packages not yet published to registries +- **Limited utility set**: Only 3 core functions (debounce, isEmail, formatCurrency) + +### Migration Notes + +This is the initial alpha release. No migration is required. + +--- + +## Release Notes Format + +For future releases, we follow this format: + +### Added +- New features and functionality + +### Changed +- Changes in existing functionality + +### Deprecated +- Soon-to-be removed features + +### Removed +- Removed features + +### Fixed +- Bug fixes + +### Security +- Security improvements + +--- + +**Legend:** +- 🎉 **Major feature** +- ✨ **Enhancement** +- 🐛 **Bug fix** +- 📚 **Documentation** +- ⚡ **Performance** +- 🔒 **Security** diff --git a/docs/README_CI.md b/docs/README_CI.md new file mode 100644 index 0000000..1c83656 --- /dev/null +++ b/docs/README_CI.md @@ -0,0 +1,226 @@ +# CI/CD Documentation + +## Overview + +KompKit uses GitHub Actions for continuous integration with separate workflows optimized for our monorepo structure. Each workflow targets specific platforms to minimize build times and resource usage. + +## Current Workflows Status + +| Workflow | Status | Platform | Triggers | Path Filters | +|----------|--------|----------|----------|--------------| +| **Web CI** | ✅ Active | TypeScript/Node.js | `develop`, `release` | `packages/core/web/**` | +| **Kotlin CI** | ✅ Active | Kotlin JVM | `develop`, `release` | `packages/core/android/**` | + +## Workflow Details + +### 1. Web CI (`web.yml`) + +**Purpose:** Build, test, and validate TypeScript/JavaScript packages + +**Triggers:** +- Push/PR to `release` or `develop` branches +- Changes in `packages/core/web/**` +- Changes in `.github/workflows/web.yml` +- Manual dispatch (`workflow_dispatch`) + +**Jobs:** +- **web**: Lint, typecheck, build, test, and generate documentation + - Node.js 20.x with npm caching + - Lerna-based monorepo management + - TypeDoc documentation generation + - Artifact uploads (build outputs, docs) + +**Path Filters:** Optimized to run only when web-related files change + +### 2. Kotlin CI (`android.yml`) + +**Purpose:** Build, test, and validate Kotlin JVM packages + +**Triggers:** +- Push/PR to `release` or `develop` branches +- Changes in `packages/core/android/**` +- Changes in `.github/workflows/android.yml` +- Manual dispatch (`workflow_dispatch`) + +**Jobs:** +- **kotlin**: Lint, static analysis, build, test, and generate documentation + - JDK 17 (Temurin distribution) + - Gradle build with caching + - ktlint code formatting validation + - detekt static analysis + - Dokka documentation generation + - JAR artifact uploads + +**Path Filters:** Optimized to run only when Kotlin-related files change + +## Technology Stack + +### Pinned Action Versions + +| Action | Version | Purpose | Used In | +|--------|---------|---------|---------| +| `actions/checkout` | v4 | Repository checkout | Both workflows | +| `actions/setup-node` | v4 | Node.js 20.x setup | Web CI | +| `actions/setup-java` | v4 | JDK 17 setup | Kotlin CI | +| `gradle/actions/setup-gradle` | v4 | Gradle with caching | Kotlin CI | +| `actions/upload-artifact` | v4 | Artifact storage | Both workflows | + +### Build Requirements + +| Platform | Requirements | Version | +|----------|-------------|---------| +| **Web** | Node.js | 20.x | +| **Web** | npm | Latest | +| **Web** | TypeScript | 5.6+ | +| **Kotlin** | JDK | 17 (Temurin) | +| **Kotlin** | Kotlin | 2.1.0 | +| **Kotlin** | Gradle | 8.5 | + +## Security & Permissions + +**Minimal Permissions:** +- `contents: read` - Repository access +- `pull-requests: read` - PR information access + +**No Secrets Required:** All builds use public dependencies and tools. + +## Local Development + +### Web Development +```bash +# Install dependencies +npm ci + +# Build packages (using Lerna) +npm run build + +# Run tests +npm run test:web + +# Generate docs +npm run docs:web +``` + +### Kotlin Development +```bash +# Navigate to Kotlin module +cd packages/core/android + +# Make gradlew executable (if needed) +chmod +x gradlew + +# Clean build +./gradlew clean + +# Lint with ktlint +./gradlew ktlintCheck + +# Static analysis with detekt +./gradlew detekt + +# Build JAR +./gradlew assemble + +# Run unit tests +./gradlew test + +# Generate documentation +./gradlew dokkaHtml +``` + +## Caching Strategy + +- **Node.js**: Native npm cache via `actions/setup-node` +- **Gradle**: Build cache via `gradle/actions/setup-gradle` +- **No manual caching**: Avoids cache conflicts and complexity + +## Artifacts + +### Web Artifacts +- `web-docs-{run_id}`: Generated TypeDoc documentation (30 days) +- `web-build-{run_id}`: Built packages from dist/ directories (7 days) + +### Kotlin Artifacts +- `android-test-reports-{run_id}`: JUnit test reports (7 days) +- `android-lint-reports-{run_id}`: ktlint and detekt reports (7 days) +- `kotlin-jar-{run_id}`: Built JAR files (7 days) +- `kotlin-docs-{run_id}`: Dokka-generated documentation (30 days) + +## Skip Flags + +Use commit message flags to skip specific builds: +- `[skip web]`: Skip web CI workflow +- `[skip android]`: Skip Kotlin CI workflow + +## Troubleshooting + +### Common Issues + +**1. Gradle Permission Denied** +```bash +chmod +x packages/core/android/gradlew +git add packages/core/android/gradlew +git commit -m "fix: make gradlew executable" +``` + +**2. Node.js Build Failures** +- Check Node.js version compatibility (using 20.x) +- Verify `package-lock.json` is committed +- Clear npm cache: `npm ci --cache .npm --prefer-offline` + +**3. Kotlin Build Failures** +- Verify JDK 17 compatibility +- Check Kotlin version compatibility (2.1.0) +- Review ktlint/detekt reports for code quality issues +- Ensure Gradle wrapper is executable + +**4. Path Filters Not Working** +- Ensure file changes match the path patterns in workflow triggers +- Check that both `push` and `pull_request` events have same path filters + +### Debug Commands + +**Check workflow status:** +```bash +# View recent workflow runs +gh run list --limit 10 + +# View specific run details +gh run view + +# Download artifacts +gh run download +``` + +**Local debugging:** +```bash +# Simulate CI environment +export CI=true +export GITHUB_ACTIONS=true + +# Run builds with same flags as CI +npm ci +npm run build --workspaces --if-present || npm run build +npm test --workspaces --if-present || npm test || echo "No tests found" +``` + +## Performance Targets + +- **Web builds**: < 5 minutes for typical changes +- **Kotlin builds**: < 8 minutes for typical changes +- **First-time builds**: May take longer due to dependency downloads +- **Concurrent builds**: Path filters prevent unnecessary parallel execution + +## Branch Strategy + +- **develop**: Active development branch, all PRs target here +- **release**: Stable release branch, merges from develop +- **Dependabot**: Targets develop branch for dependency updates + +## Monitoring + +Monitor CI health via: +- GitHub Actions dashboard +- README badges showing build status +- Artifact retention and storage usage +- Build time trends and performance metrics diff --git a/docs/contributing.md b/docs/contributing.md index abf6ff4..f5df6e9 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -1,73 +1,238 @@ -# Contributing +# Contributing to KompKit -Contributions to KompKit Core are welcome. Please follow these guidelines. +We welcome contributions to KompKit! This document provides guidelines for contributing to our cross-platform utility library. -## Commit conventions +## Getting Started -Use conventional commit messages: -- `feat:` for new features -- `fix:` for bug fixes -- `chore:` for maintenance tasks -- `docs:` for documentation updates -- `test:` for test additions or updates +### Prerequisites -Example: -``` -feat(core): add throttle utility for web and android -``` +- **Node.js** 20+ and npm +- **JDK** 17+ (for Kotlin development) +- **Git** for version control -## Code guidelines +### Development Setup -1. **Always add or update tests.** Every new utility or bug fix must include corresponding tests for both web (Vitest) and Android (JUnit). +1. **Fork and clone the repository** + ```bash + git clone https://github.com/YOUR_USERNAME/KompKit.git + cd KompKit + ``` -2. **Maintain Web/Android API parity.** Function signatures, parameters, and behavior should be consistent across platforms. If a feature cannot be implemented identically, document the differences clearly. +2. **Install dependencies** + ```bash + npm install + ``` -3. **Keep dependencies minimal.** Avoid adding new runtime dependencies unless absolutely necessary. +3. **Create a feature branch** + ```bash + git checkout -b feature/your-feature-name + ``` -4. **Follow existing code style.** Use TypeScript for web, Kotlin for Android. Follow the patterns established in the existing codebase. +## Development Workflow -## Local development +### Branch Strategy -### Setup -```bash -# Clone the repository -git clone https://github.com/your-org/kompkit.git -cd kompkit +- **`develop`**: Active development branch (target for PRs) +- **`release`**: Stable release branch (production) +- **Feature branches**: `feature/feature-name` or `fix/bug-name` + +### Commit Convention + +We use [Conventional Commits](https://www.conventionalcommits.org/) for consistent commit messages: + +``` +[optional scope]: + +[optional body] -# Install dependencies -npm install +[optional footer(s)] ``` -### Build +**Types:** +- `feat`: New features +- `fix`: Bug fixes +- `docs`: Documentation changes +- `style`: Code style changes (formatting, etc.) +- `refactor`: Code refactoring +- `test`: Adding or updating tests +- `chore`: Maintenance tasks +- `ci`: CI/CD changes + +**Examples:** +```bash +feat(web): add throttle utility function +fix(kotlin): resolve debounce memory leak +docs: update API reference for formatCurrency +test(web): add edge cases for email validation +``` + +### Code Guidelines + +1. **Cross-platform API parity**: Maintain identical APIs across TypeScript and Kotlin implementations +2. **Zero dependencies**: Avoid adding runtime dependencies unless absolutely necessary +3. **Comprehensive testing**: Every feature must include tests for both platforms +4. **Documentation**: Update API docs and examples for new features +5. **Type safety**: Use TypeScript and Kotlin type systems effectively + +## Development Commands + +### Building + ```bash -# Build web package +# Build all packages npm run build + +# Build web package only +npm run docs:web + +# Build Kotlin package only +cd packages/core/android && ./gradlew assemble ``` -### Test +### Testing + ```bash -# Run all tests (web + android) +# Run all tests npm test -# Run only web tests +# Run web tests only npm run test:web -# Run only android tests +# Run Kotlin tests only npm run test:android ``` -### Workflow -1. Create a feature branch: `git checkout -b feat/my-feature` -2. Make your changes -3. Add tests for both platforms -4. Run `npm test` to verify all tests pass -5. Commit with a conventional commit message -6. Push and open a pull request - -## Pull request checklist - -- [ ] Tests added for web and android -- [ ] All tests pass (`npm test`) -- [ ] Code follows existing style -- [ ] Commit messages follow conventions -- [ ] Documentation updated if needed +### Documentation + +```bash +# Generate all documentation +npm run docs:all + +# Generate web docs (TypeDoc) +npm run docs:web + +# Generate Kotlin docs (Dokka) +npm run docs:android +``` + +### Code Quality + +```bash +# Kotlin linting +cd packages/core/android && ./gradlew ktlintCheck + +# Kotlin static analysis +cd packages/core/android && ./gradlew detekt + +# Auto-fix Kotlin formatting +cd packages/core/android && ./gradlew ktlintFormat +``` + +## Adding New Utilities + +When adding a new utility function: + +1. **Implement in both platforms**: + - TypeScript: `packages/core/web/src/` + - Kotlin: `packages/core/android/src/main/kotlin/com/kompkit/core/` + +2. **Maintain API consistency**: + ```typescript + // TypeScript + export function myUtility(param: string): boolean { ... } + ``` + ```kotlin + // Kotlin + fun myUtility(param: String): Boolean { ... } + ``` + +3. **Add comprehensive tests**: + - Web: `packages/core/web/tests/` + - Kotlin: `packages/core/android/src/test/kotlin/` + +4. **Update exports**: + - Add to `packages/core/web/src/index.ts` + - Kotlin exports are automatic via package structure + +5. **Document with examples**: + - Add JSDoc comments (TypeScript) + - Add KDoc comments (Kotlin) + +## Code Style + +### TypeScript +- Use ESLint and Prettier configurations +- Prefer `const` over `let` +- Use explicit return types for public APIs +- Follow existing naming conventions + +### Kotlin +- Follow ktlint formatting rules +- Use detekt for static analysis +- Prefer `val` over `var` +- Use explicit types for public APIs +- Follow Kotlin coding conventions + +## Pull Request Process + +1. **Create a feature branch**: + ```bash + git checkout develop + git pull origin develop + git checkout -b feature/your-feature-name + ``` + +2. **Make your changes**: + - Implement feature in both platforms + - Add comprehensive tests + - Update documentation + +3. **Test thoroughly**: + ```bash + npm test + cd packages/core/android && ./gradlew test + ``` + +4. **Commit with conventional messages**: + ```bash + git add . + git commit -m "feat(core): add new utility function" + ``` + +5. **Push and create PR**: + ```bash + git push origin feature/your-feature-name + ``` + +6. **PR targets `develop` branch** + +### PR Checklist + +- [ ] ✅ Feature implemented in both TypeScript and Kotlin +- [ ] ✅ Tests added for both platforms with good coverage +- [ ] ✅ All existing tests pass (`npm test`) +- [ ] ✅ Code follows style guidelines (ktlint, ESLint) +- [ ] ✅ API documentation updated (JSDoc/KDoc) +- [ ] ✅ Conventional commit messages used +- [ ] ✅ No breaking changes (or clearly documented) +- [ ] ✅ PR description explains the change and motivation + +## Release Process + +Releases are managed by maintainers: + +1. **Version bump**: Update `package.json` and create `VERSION` file +2. **Changelog**: Update `CHANGELOG.md` with new features/fixes +3. **Tag creation**: Create and push version tag +4. **Branch merge**: Merge `develop` → `release` + +## Getting Help + +- 📖 **Documentation**: [./docs/](../docs/) +- 🐛 **Issues**: [GitHub Issues](https://github.com/Kompkit/KompKit/issues) +- 💬 **Discussions**: [GitHub Discussions](https://github.com/Kompkit/KompKit/discussions) +- 📧 **Maintainers**: Open an issue for direct contact + +## Code of Conduct + +This project follows the [Contributor Covenant Code of Conduct](https://www.contributor-covenant.org/). Please be respectful and inclusive in all interactions. diff --git a/package.json b/package.json index 6f3b9af..86e3cc1 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "kompkit", - "version": "0.1.0", + "version": "0.1.0-alpha", "description": "A lightweight cross-platform utility kit for Android (Kotlin) and Web (TypeScript): debounce, isEmail, formatCurrency", "private": true, "workspaces": [ diff --git a/packages/core/web/package.json b/packages/core/web/package.json index c98a8ec..764703f 100644 --- a/packages/core/web/package.json +++ b/packages/core/web/package.json @@ -1,6 +1,6 @@ { "name": "@kompkit/core", - "version": "0.0.1", + "version": "0.1.0-alpha", "type": "module", "main": "dist/index.cjs", "module": "dist/index.js",