@dimensional-innovations/tool-config 1.0.0

package/src/tools/semantic-release/CI_SETUP.md

@@ -0,0 +1,66 @@
+# CI/CD Templates
+
+Ready-to-use CI/CD configuration templates for GitLab CI, GitHub Actions, and Bitbucket Pipelines.
+
+## Available Templates
+
+- **`.gitlab-ci.yml`** - GitLab CI/CD pipeline
+- **`github-workflow.yml`** - GitHub Actions workflow
+- **`bitbucket-pipelines.yml`** - Bitbucket Pipelines configuration
+
+## Usage
+
+Copy the appropriate template to your project:
+
+### GitLab CI
+
+```bash
+cp node_modules/@dimensional-innovations/tool-config/src/tools/semantic-release/templates/.gitlab-ci.yml .gitlab-ci.yml
+```
+
+Then configure these CI/CD variables in GitLab:
+
+- `GL_TOKEN`: GitLab Personal Access Token
+- `NPM_TOKEN`: npm authentication token
+
+### GitHub Actions
+
+```bash
+mkdir -p .github/workflows
+cp node_modules/@dimensional-innovations/tool-config/src/tools/semantic-release/templates/github-workflow.yml .github/workflows/ci.yml
+```
+
+Then configure these secrets in GitHub:
+
+- `GITHUB_TOKEN`: Automatically provided
+- `NPM_TOKEN`: npm authentication token
+
+### Bitbucket Pipelines
+
+```bash
+cp node_modules/@dimensional-innovations/tool-config/src/tools/semantic-release/templates/bitbucket-pipelines.yml bitbucket-pipelines.yml
+```
+
+Then configure these repository variables in Bitbucket:
+
+- `NPM_TOKEN`: npm authentication token
+
+## What's Included
+
+Each template includes:
+
+1. **Lint Stage** - Runs ESLint, Prettier, and Stylelint
+2. **Test Stage** - Runs tests with coverage reporting
+3. **Release Stage** - Automated semantic-release (main branch only)
+
+## Customization
+
+All templates are designed to be customized for your specific needs:
+
+- Adjust Node.js versions
+- Add deployment stages
+- Configure caching strategies
+- Add matrix testing for multiple versions
+- Customize when jobs run
+
+See comments in each template file for optional configurations.

package/src/tools/semantic-release/README.md

@@ -0,0 +1,533 @@
+# semantic-release Configuration
+
+Automated versioning and package publishing using semantic-release with preset-based configuration.
+
+## Philosophy
+
+This semantic-release configuration follows semantic versioning principles with conventional commits:
+
+- **Automated versioning** - Version numbers determined by commit messages
+- **Changelog generation** - Automatic changelog from conventional commits
+- **Release automation** - Publish to NPM and create Git provider releases (GitLab, GitHub)
+- **Branch-based releases** - Support for production, pre-release, and maintenance branches
+- **Preset-based** - Choose the right configuration for your project type
+- **Git provider detection** - Automatically detects GitLab, GitHub, or Bitbucket from repository URL
+
+## Git Provider Detection
+
+This package **automatically detects** your Git hosting provider (GitLab, GitHub, or Bitbucket) from:
+
+1. **package.json `repository` field** - Checked first
+2. **Git remote URL** - Fallback if package.json doesn't specify
+
+**Supported providers:**
+
+- **GitLab** - Uses `@semantic-release/gitlab` plugin
+- **GitHub** - Uses `@semantic-release/github` plugin
+- **Bitbucket** - No official plugin (uses core features only)
+- **Other/None** - No provider plugin added (core features only)
+
+**You can override auto-detection:**
+
+```javascript
+// Force GitLab even if detected as GitHub
+export default createConfig('semantic-release', {
+  gitProvider: 'gitlab'
+})
+
+// Force GitHub even if detected as GitLab
+export default createConfig('semantic-release', {
+  gitProvider: 'github'
+})
+
+// Disable provider plugin entirely
+export default createConfig('semantic-release', {
+  gitProvider: null
+})
+```
+
+## Installation
+
+```bash
+npm install --save-dev @dimensional-innovations/tool-config semantic-release
+```
+
+### Optional Peer Dependencies
+
+Install the semantic-release plugins you need based on your Git provider:
+
+```bash
+# For GitLab projects
+npm install --save-dev @semantic-release/changelog @semantic-release/git @semantic-release/gitlab
+
+# For GitHub projects
+npm install --save-dev @semantic-release/changelog @semantic-release/git @semantic-release/github
+
+# For Bitbucket or other providers (no provider-specific plugin)
+npm install --save-dev @semantic-release/changelog @semantic-release/git
+```
+
+## Usage
+
+### Basic Usage (Auto-Detect)
+
+Create a `release.config.js` file in your project root:
+
+```javascript
+import { createConfig } from '@dimensional-innovations/tool-config'
+
+export default createConfig('semantic-release')
+```
+
+This uses the **default preset** which works for most projects.
+
+### Preset Selection
+
+#### Default Preset
+
+Standard configuration for applications and general projects:
+
+```javascript
+import { createConfig } from '@dimensional-innovations/tool-config'
+
+export default createConfig('semantic-release', {
+  preset: 'default'
+})
+```
+
+**Includes:**
+
+- Commit analyzer
+- Release notes generator
+- Changelog generation
+- NPM publishing
+- Git provider releases (auto-detected: GitLab, GitHub, or none)
+- Git tagging
+
+#### Library Preset
+
+Optimized for published NPM libraries with reduced noise:
+
+```javascript
+import { createConfig } from '@dimensional-innovations/tool-config'
+
+export default createConfig('semantic-release', {
+  preset: 'library'
+})
+```
+
+**Differences from default:**
+
+- Explicit `pkgRoot: '.'` configuration
+- Disabled Git provider success comments (less noise)
+- Disabled released labels (library-specific optimization)
+- Cleaner release process for libraries
+
+#### Monorepo Preset
+
+For monorepo structures with multiple packages:
+
+```javascript
+import { createConfig } from '@dimensional-innovations/tool-config'
+
+export default createConfig('semantic-release', {
+  preset: 'monorepo'
+})
+```
+
+**Configuration:**
+
+- `pkgRoot: 'packages/*'` for workspace structure
+- Suitable for lerna, pnpm workspaces, npm workspaces
+- Per-package versioning support
+
+**Note**: For advanced monorepo scenarios, you may need to run semantic-release separately for each package or use additional plugins like `semantic-release-monorepo`.
+
+### Custom Configuration
+
+#### Override Branches
+
+```javascript
+import { createConfig } from '@dimensional-innovations/tool-config'
+
+export default createConfig('semantic-release', {
+  preset: 'default',
+  branches: [
+    'main',
+    'next',
+    { name: 'beta', prerelease: true },
+    { name: 'alpha', prerelease: true }
+  ]
+})
+```
+
+#### Override Plugins
+
+```javascript
+import { createConfig } from '@dimensional-innovations/tool-config'
+
+export default createConfig('semantic-release', {
+  preset: 'library',
+  plugins: [
+    '@semantic-release/commit-analyzer',
+    '@semantic-release/release-notes-generator',
+    '@semantic-release/npm'
+    // Removed changelog, gitlab, git for minimal setup
+  ]
+})
+```
+
+#### Additional Options
+
+```javascript
+import { createConfig } from '@dimensional-innovations/tool-config'
+
+export default createConfig('semantic-release', {
+  preset: 'library',
+  repositoryUrl: 'https://gitlab.com/org/repo.git',
+  tagFormat: 'v${version}',
+  dryRun: false
+})
+```
+
+## Conventional Commits
+
+semantic-release determines version bumps based on commit message conventions:
+
+### Commit Types
+
+| Type              | Description             | Version Bump  |
+| ----------------- | ----------------------- | ------------- |
+| `feat`            | New feature             | Minor (0.x.0) |
+| `fix`             | Bug fix                 | Patch (0.0.x) |
+| `perf`            | Performance improvement | Patch (0.0.x) |
+| `BREAKING CHANGE` | Breaking change footer  | Major (x.0.0) |
+| `feat!`           | Breaking feature        | Major (x.0.0) |
+| `fix!`            | Breaking fix            | Major (x.0.0) |
+| `docs`            | Documentation only      | No release    |
+| `style`           | Code style changes      | No release    |
+| `refactor`        | Code refactoring        | No release    |
+| `test`            | Test additions          | No release    |
+| `chore`           | Maintenance tasks       | No release    |
+
+### Examples
+
+```bash
+# Patch release (0.0.1)
+git commit -m "fix: resolve authentication bug"
+
+# Minor release (0.1.0)
+git commit -m "feat: add user profile management"
+
+# Major release (1.0.0)
+git commit -m "feat!: redesign API with breaking changes"
+
+# Major release with footer (1.0.0)
+git commit -m "feat: redesign authentication
+
+BREAKING CHANGE: JWT tokens now required, session cookies removed"
+
+# No release
+git commit -m "docs: update README installation steps"
+```
+
+## Preset Comparison
+
+| Feature         | Default      | Library           | Monorepo                    |
+| --------------- | ------------ | ----------------- | --------------------------- |
+| Commit Analyzer | ✅           | ✅                | ✅                          |
+| Release Notes   | ✅           | ✅                | ✅                          |
+| Changelog       | ✅           | ✅                | ✅                          |
+| NPM Publish     | ✅           | ✅ (pkgRoot: '.') | ✅ (pkgRoot: 'packages/\*') |
+| GitLab Releases | ✅           | ✅ (no comments)  | ✅                          |
+| Git Tagging     | ✅           | ✅                | ✅                          |
+| Best For        | Applications | Libraries         | Workspaces                  |
+
+## Integration
+
+### With GitLab CI
+
+Add to your `.gitlab-ci.yml`:
+
+```yaml
+release:
+  stage: deploy
+  only:
+    - main
+  script:
+    - npm install
+    - npx semantic-release
+  variables:
+    GL_TOKEN: $GL_TOKEN
+    NPM_TOKEN: $NPM_TOKEN
+```
+
+### With GitHub Actions
+
+Add to `.github/workflows/release.yml`:
+
+```yaml
+name: Release
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: '20'
+      - run: npm install
+      - run: npx semantic-release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+```
+
+### Local Testing
+
+Test your configuration without publishing:
+
+```bash
+npx semantic-release --dry-run
+```
+
+## Workflow
+
+### 1. Make Changes
+
+Develop features and fixes following conventional commit messages.
+
+### 2. Create Commits
+
+Write commits following conventional commit format:
+
+```bash
+git commit -m "feat(scope): add new feature"
+git commit -m "fix(scope): fix bug"
+git commit -m "docs: update documentation"
+```
+
+**Commit types:**
+
+- `feat:` - New feature (triggers minor release)
+- `fix:` - Bug fix (triggers patch release)
+- `docs:`, `chore:`, `test:`, `refactor:` - No release
+
+### 3. Push to Main Branch
+
+```bash
+git push origin main
+```
+
+### 4. Automatic Release
+
+semantic-release analyzes commits and:
+
+1. Determines next version number
+2. Generates changelog
+3. Creates git tag
+4. Publishes to NPM
+5. Creates GitLab/GitHub release
+
+## Troubleshooting
+
+### "No new version to release"
+
+**Cause**: No commits with release-triggering types (feat, fix, perf, BREAKING CHANGE) since last release.
+
+**Solution**: Ensure commits use conventional commit format. Use `feat:` or `fix:` prefixes.
+
+### NPM Publish Fails
+
+**Cause**: Missing `NPM_TOKEN` environment variable or incorrect permissions.
+
+**Solution**:
+
+1. Generate NPM access token from npmjs.com
+2. Add to CI/CD environment variables as `NPM_TOKEN`
+3. Ensure token has publish permissions
+
+### GitLab Release Fails
+
+**Cause**: Missing `GL_TOKEN` or insufficient permissions.
+
+**Solution**:
+
+1. Generate GitLab personal access token with `api` scope
+2. Add to CI/CD environment variables as `GL_TOKEN`
+3. Ensure token has project access
+
+### Version Conflicts
+
+**Cause**: Multiple simultaneous releases or manual version changes.
+
+**Solution**:
+
+1. Only release from CI/CD, never manually
+2. Protect main branch to prevent direct pushes
+3. Use `npm run release --dry-run` to test locally
+
+### Monorepo Issues
+
+**Cause**: semantic-release trying to publish all packages at once.
+
+**Solution**:
+
+1. Run semantic-release separately for each package
+2. Use `semantic-release-monorepo` plugin
+3. Configure `pkgRoot` correctly per package
+
+## Advanced Configuration
+
+### Multiple Branches
+
+Support production, pre-release, and maintenance:
+
+```javascript
+export default createConfig('semantic-release', {
+  branches: [
+    'main',
+    'next',
+    { name: 'beta', prerelease: true },
+    { name: 'alpha', prerelease: true },
+    { name: '+([0-9])?(.{+([0-9]),x}).x', prerelease: true }
+  ]
+})
+```
+
+### Custom Tag Format
+
+```javascript
+export default createConfig('semantic-release', {
+  tagFormat: 'v${version}' // Creates tags like v1.0.0
+})
+```
+
+### Changelog Customization
+
+```javascript
+export default createConfig('semantic-release', {
+  preset: 'default',
+  plugins: [
+    '@semantic-release/commit-analyzer',
+    '@semantic-release/release-notes-generator',
+    [
+      '@semantic-release/changelog',
+      {
+        changelogFile: 'HISTORY.md',
+        changelogTitle: '# Release History'
+      }
+    ],
+    '@semantic-release/npm',
+    '@semantic-release/gitlab',
+    [
+      '@semantic-release/git',
+      {
+        assets: ['HISTORY.md', 'package.json'],
+        message: 'chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}'
+      }
+    ]
+  ]
+})
+```
+
+## API Reference
+
+### `createConfig(tool, options)`
+
+Create a semantic-release configuration.
+
+**Parameters:**
+
+- `tool` (string): Must be `'semantic-release'`
+- `options` (object): Configuration options
+  - `preset` (string): Preset to use (`'default'`, `'library'`, `'monorepo'`). Default: `'default'`
+  - `gitProvider` (string | null): Git provider (`'gitlab'`, `'github'`, `'bitbucket'`, `'auto'`, or `null`). Default: `'auto'` (auto-detect)
+  - `cwd` (string): Working directory for auto-detection. Default: `process.cwd()`
+  - `branches` (string[] | object[]): Branches to release from. Overrides preset.
+  - `plugins` (array): Plugins to use. Overrides preset.
+  - `repositoryUrl` (string): Repository URL. Auto-detected from package.json.
+  - `tagFormat` (string): Git tag format. Default: `'v${version}'`
+  - `dryRun` (boolean): Test without publishing. Default: `false`
+  - ...any other semantic-release options
+
+**Returns:** semantic-release configuration object
+
+### Named Export
+
+```javascript
+import { createReleaseConfig } from '@dimensional-innovations/tool-config'
+
+export default createReleaseConfig({ preset: 'library' })
+```
+
+## Examples
+
+### Standard Library
+
+```javascript
+import { createConfig } from '@dimensional-innovations/tool-config'
+
+export default createConfig('semantic-release', {
+  preset: 'library'
+})
+```
+
+### Application with Beta Releases
+
+```javascript
+import { createConfig } from '@dimensional-innovations/tool-config'
+
+export default createConfig('semantic-release', {
+  preset: 'default',
+  branches: ['main', { name: 'beta', prerelease: true }]
+})
+```
+
+### Minimal Configuration
+
+```javascript
+import { createConfig } from '@dimensional-innovations/tool-config'
+
+export default createConfig('semantic-release', {
+  preset: 'default',
+  plugins: [
+    '@semantic-release/commit-analyzer',
+    '@semantic-release/release-notes-generator',
+    '@semantic-release/npm'
+  ]
+})
+```
+
+### Monorepo Package
+
+```javascript
+import { createConfig } from '@dimensional-innovations/tool-config'
+
+export default createConfig('semantic-release', {
+  preset: 'monorepo'
+})
+```
+
+## Resources
+
+- [semantic-release Documentation](https://semantic-release.gitbook.io/)
+- [Conventional Commits](https://www.conventionalcommits.org/)
+- [Semantic Versioning](https://semver.org/)
+- [GitLab CI/CD](https://docs.gitlab.com/ee/ci/)
+- [GitHub Actions](https://docs.github.com/en/actions)
+
+## Related Tools
+
+This package also provides configurations for:
+
+- **ESLint** - JavaScript/TypeScript linting
+- **Prettier** - Code formatting
+- **Stylelint** - CSS/style linting
+
+See the main [README](../../../README.md) for full package documentation.