@programinglive/commiter 1.1.0 → 1.1.4

package/SECURITY.md

@@ -1,30 +1,30 @@
-# Security Policy
-
-## Reporting a Vulnerability
-
-If you discover a security vulnerability in `@programinglive/commiter`, please report it responsibly.
-
-Send your report to: [security@programinglive.com](mailto:security@programinglive.com).
-
-Please include:
-- A detailed description of the vulnerability
-- Steps to reproduce the issue
-- Any potential impact
-- Optional: Suggested mitigation or patch
-
-We aim to respond within **48 hours** and will keep you informed of our progress.
-
-## Supported Versions
-
-We support the latest released version of the package. Please ensure you are running the most recent version before reporting issues.
-
-## Disclosure Policy
-
-We follow a coordinated disclosure process:
-1. Acknowledge receipt of your report within 48 hours
-2. Assess the vulnerability and determine severity
-3. Fix the issue and prepare a release
-4. Credit the reporter (if desired)
-5. Publish a security advisory detailing the fix
-
-Thank you for helping keep our project secure!
+# Security Policy
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability in `@programinglive/commiter`, please report it responsibly.
+
+Send your report to: [security@programinglive.com](mailto:security@programinglive.com).
+
+Please include:
+- A detailed description of the vulnerability
+- Steps to reproduce the issue
+- Any potential impact
+- Optional: Suggested mitigation or patch
+
+We aim to respond within **48 hours** and will keep you informed of our progress.
+
+## Supported Versions
+
+We support the latest released version of the package. Please ensure you are running the most recent version before reporting issues.
+
+## Disclosure Policy
+
+We follow a coordinated disclosure process:
+1. Acknowledge receipt of your report within 48 hours
+2. Assess the vulnerability and determine severity
+3. Fix the issue and prepare a release
+4. Credit the reporter (if desired)
+5. Publish a security advisory detailing the fix
+
+Thank you for helping keep our project secure!

package/commitlint.config.cjs

@@ -1,4 +1,4 @@
-module.exports = {
-  extends: ['@commitlint/config-conventional'],
-  ignores: [(message) => message.startsWith('chore(release):')]
-};
+module.exports = {
+  extends: ['@commitlint/config-conventional'],
+  ignores: [(message) => message.startsWith('chore(release):')]
+};

package/docs/prd-fs-f-ok-warning.md

@@ -0,0 +1,47 @@
+# PRD: Eliminate `fs.F_OK` Deprecation Warning During Releases
+
+## Overview
+`standard-version@9.5.0` uses the deprecated `fs.F_OK` constant when ensuring the changelog file exists. When `scripts/release.js` executed, Node.js v20+ surfaced `[DEP0176]` warnings, creating noise in CI/CD logs and confusing maintainers about potential breakages.
+
+## Goals
+- Prevent the deprecation warning without forking or manually editing `node_modules`.
+- Keep the mitigation self-contained within the Commiter codebase so dependency upgrades remain safe.
+- Preserve existing release behaviour (tests, standard-version invocation, CLI API).
+
+## Non-Goals
+- Upgrading `standard-version` or other dependencies.
+- Patching unrelated lifecycle scripts that do not trigger the warning.
+- Changing user-facing configuration or CLI commands.
+
+## Target Users
+- Repository maintainers who run `npm run release*` scripts and expect clean logs.
+- CI pipelines that rely on warning-free output to detect regressions.
+
+## Functional Requirements
+1. Release commands must execute without emitting the `fs.F_OK` deprecation warning.
+2. The fix must apply automatically whenever the bundled release helper runs.
+3. Commiter must continue to run project tests prior to executing `standard-version`.
+4. All existing automated tests must remain green.
+
+## Technical Approach
+- Introduce `scripts/preload/fs-f-ok.cjs` that monkey patches Node's module loader for `standard-version/lib/lifecycles/changelog`, rewriting `fs.F_OK` to `fs.constants.F_OK` in-memory before the module executes.
+- Ensure every Commiter-managed release process uses the preload script by appending `--require <preload>` to `NODE_OPTIONS` for the spawned `standard-version` child process.
+- Retain a local require of the preload script in `scripts/release.js` so unit tests that run in-process also benefit.
+
+## Success Metrics
+- Running `node scripts/release.js --help` (or any release command) no longer emits `[DEP0176]`.
+- Automated test suite (`npm test`) passes without new failures.
+
+## Testing Plan
+- Extend test coverage with `test/fs-f-ok-preload.test.js` to verify `fs.F_OK` is aligned with `fs.constants.F_OK` after loading the release helper.
+- Update existing release unit tests to assert the spawn sequence now includes the `--require` preload flag.
+- Execute `node --test` locally and in CI to validate.
+
+## Risks & Mitigations
+- **Upstream Changes**: Future `standard-version` versions may restructure files. Mitigate by scoping the preload to the exact module path and gracefully skipping if no replacement is required.
+- **Environment Variable Collisions**: Appending to `NODE_OPTIONS` could conflict with user-provided values. Mitigate by concatenating (instead of overriding) existing options.
+- **Windows Path Quoting**: Preload flag builder escapes quotes and wraps paths containing spaces to avoid spawn failures on Windows.
+
+## Rollout Plan
+- Ship change in the next patch release (v1.1.x).
+- Communicate via release notes and CHANGELOG updates once published.

package/docs/release-notes/RELEASE_NOTES.md

@@ -0,0 +1,60 @@
+# Commiter Release Notes
+
+This document summarizes every published version of `@programinglive/commiter`. Refer to the generated [CHANGELOG](../../CHANGELOG.md) for commit-level details.
+
+| Version | Date | Highlights |
+|---------|------|------------|
+| 1.1.4 | 2025-11-05 | simplify release notes staging to avoid git ref conflicts (d4077aa) |
+| 1.1.3 | 2025-11-05 | See CHANGELOG for details. |
+| 1.1.2 | 2025-11-05 | auto-update release notes during release (99d1043) |
+| 1.1.1 | 2025-11-05 | 🐛 Bug Fix – removed the fs.F_OK deprecation warning from release runs. |
+| 1.1.0 | 2025-10-29 | 📝 Documentation – clarified release automation flow. |
+| 1.0.12 | 2025-10-29 | ✨ Feature – autodetects project test command before releasing. |
+| 1.0.11 | 2025-10-29 | 📝 Documentation – added project status and download badges. |
+| 1.0.10 | 2025-10-29 | Maintenance release; no additional notes provided. |
+| 1.0.9 | 2025-10-29 | ✨ Feature – introduced a new capability (see changelog commit `e1603c1`). |
+| 1.0.8 | 2025-10-29 | ✨ Feature – added release helper script and tests. |
+| 1.0.7 | 2025-10-29 | ✨ Feature – added release helper script and tests. |
+| 1.0.6 | 2025-10-19 | Maintenance release; no additional notes provided. |
+| 1.0.5 | 2025-10-19 | 🐛 Bug Fix – allowed release commits to include emoji. |
+| 1.0.4 | 2025-10-19 | 🐛 Bug Fix – ensured safe default test script for initial release. |
+| 1.0.3 | 2025-10-19 | Maintenance release; no additional notes provided. |
+| 1.0.2 | 2025-10-19 | Maintenance release; no additional notes provided. |
+| 1.0.1 | 2025-10-18 | 🐛 Bug Fix – aligned commitlint config with project module type. |
+| 1.0.0 | 2025-10-17 | ✨ Initial release – bootstrapped conventional release tooling; added community docs and metadata. |
+
+
+
+
+## 1.1.4 – 🐛 Bug Fixes
+
+Released on **2025-11-05**.
+
+- simplify release notes staging to avoid git ref conflicts (d4077aa)
+
+## 1.1.3
+
+Released on **2025-11-05**.
+
+- See CHANGELOG for details.
+
+## 1.1.2 – 🧹 Chores
+
+Released on **2025-11-05**.
+
+- auto-update release notes during release (99d1043)
+
+## 1.1.1 – fs.F_OK Deprecation Warning Fix
+
+Released on **2025-11-05**.
+- Eliminated the `[DEP0176] fs.F_OK` warning emitted during release commands by injecting a preload script that transparently rewrites `fs.F_OK` usage inside `standard-version`.
+- Ensured the preload script runs for both in-process unit tests and the child process that executes `standard-version` by appending a `--require` flag to `NODE_OPTIONS`.
+- Updated the test suite to cover the preload behaviour and the adjusted release workflow, switching the project to Node’s built-in test runner (`node --test`).
+
+### Impact
+- Release logs are now warning-free, reducing CI noise and operator confusion.
+- Future dependency updates remain safe because no files under `node_modules` are modified.
+- The new tests guard against regressions in the preload integration.
+
+### Testing
+- `node --test`

package/docs/release-notes/fs-f-ok-warning.md

@@ -0,0 +1,14 @@
+# Release Notes: Fix fs.F_OK Deprecation Warning
+
+## Summary
+- Eliminated the `[DEP0176] fs.F_OK` warning emitted during release commands by injecting a preload script that transparently rewrites `fs.F_OK` usage inside `standard-version`.
+- Ensured the preload script runs for both in-process unit tests and the child process that executes `standard-version` by appending a `--require` flag to `NODE_OPTIONS`.
+- Updated the test suite to cover the preload behaviour and the adjusted release workflow, switching the project to Node’s built-in test runner (`node --test`).
+
+## Impact
+- Release logs are now warning-free, reducing CI noise and operator confusion.
+- Future dependency updates remain safe because no files under `node_modules` are modified.
+- The new tests guard against regressions in the preload integration.
+
+## Testing
+- `node --test`

package/index.js

@@ -1,148 +1,148 @@
-#!/usr/bin/env node
-
-/**
- * Commiter - Commit convention tooling for standard-version releases
- * 
- * This package helps enforce conventional commits and automate releases
- * with beautiful changelogs featuring icons for each commit type.
- */
-
-const { execSync } = require('child_process');
-const fs = require('fs');
-const path = require('path');
-
-function ensureSafeTestScript(scripts = {}) {
-  const defaultFailingTestScript = 'echo "Error: no test specified" && exit 1';
-  if (!scripts.test || scripts.test === defaultFailingTestScript) {
-    scripts.test = 'echo "No tests specified"';
-  }
-  return scripts;
-}
-
-function setupCommiter() {
-  console.log('🚀 Setting up Commiter...\n');
-
-  // Check if package.json exists
-  if (!fs.existsSync('package.json')) {
-    console.error('❌ Error: package.json not found. Please run this in a Node.js project directory.');
-    process.exit(1);
-  }
-
-  try {
-    // Install dependencies
-    console.log('📦 Installing dependencies...');
-    execSync('npm install --save-dev standard-version @commitlint/cli @commitlint/config-conventional husky', {
-      stdio: 'inherit'
-    });
-
-    // Read package.json
-    const packageJsonPath = path.join(process.cwd(), 'package.json');
-    const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
-
-    packageJson.scripts = ensureSafeTestScript(packageJson.scripts || {});
-    // Add scripts
-    packageJson.scripts.prepare = 'husky';
-    packageJson.scripts.release = 'node scripts/release.js';
-    packageJson.scripts['release:major'] = 'node scripts/release.js major';
-    packageJson.scripts['release:minor'] = 'node scripts/release.js minor';
-    packageJson.scripts['release:patch'] = 'node scripts/release.js patch';
-
-    // Add standard-version config
-    packageJson['standard-version'] = {
-      releaseCommitMessageFormat: 'chore(release): {{currentTag}} 🚀',
-      types: [
-        { type: 'feat', section: '✨ Features' },
-        { type: 'fix', section: '🐛 Bug Fixes' },
-        { type: 'perf', section: '⚡ Performance' },
-        { type: 'refactor', section: '♻️ Refactors' },
-        { type: 'docs', section: '📝 Documentation' },
-        { type: 'style', section: '💄 Styles' },
-        { type: 'test', section: '✅ Tests' },
-        { type: 'build', section: '🏗️ Build System' },
-        { type: 'ci', section: '👷 Continuous Integration' },
-        { type: 'chore', section: '🧹 Chores' },
-        { type: 'revert', section: '⏪ Reverts' }
-      ]
-    };
-
-    // Write updated package.json
-    fs.writeFileSync(packageJsonPath, JSON.stringify(packageJson, null, 2) + '\n');
-
-    // Create release helper script
-    console.log('🛠️  Creating release helper script...');
-    const releaseScriptDir = path.join(process.cwd(), 'scripts');
-    if (!fs.existsSync(releaseScriptDir)) {
-      fs.mkdirSync(releaseScriptDir, { recursive: true });
-    }
-
-    const releaseScriptPath = path.join(releaseScriptDir, 'release.js');
-    const releaseScriptSource = path.join(__dirname, 'scripts', 'release.js');
-    const releaseScriptContent = fs.readFileSync(releaseScriptSource, 'utf8');
-
-    fs.writeFileSync(releaseScriptPath, releaseScriptContent + '\n');
-    try {
-      fs.chmodSync(releaseScriptPath, 0o755);
-    } catch (error) {
-      // Ignore chmod errors on non-POSIX systems
-    }
-
-    // Determine commitlint config format based on project module type
-    const isEsmProject = packageJson.type === 'module';
-    const commitlintConfigFile = isEsmProject ? 'commitlint.config.js' : 'commitlint.config.cjs';
-    const commitlintConfigContent = isEsmProject
-      ? `export default {
-  extends: ['@commitlint/config-conventional'],
-  ignores: [(message) => message.startsWith('chore(release):')]
-}\n`
-      : `module.exports = {
-  extends: ['@commitlint/config-conventional'],
-  ignores: [(message) => message.startsWith('chore(release):')]
-}\n`;
-
-    const legacyCommitlintConfigFile = isEsmProject ? 'commitlint.config.cjs' : 'commitlint.config.js';
-    if (fs.existsSync(legacyCommitlintConfigFile)) {
-      fs.rmSync(legacyCommitlintConfigFile);
-    }
-
-    console.log(`⚙️  Creating commitlint config (${commitlintConfigFile})...`);
-    fs.writeFileSync(commitlintConfigFile, commitlintConfigContent);
-
-    // Initialize Husky
-    console.log('🐶 Setting up Husky...');
-    execSync('npx husky init', { stdio: 'inherit' });
-
-    // Create commit-msg hook
-    const huskyDir = path.join(process.cwd(), '.husky');
-    if (!fs.existsSync(huskyDir)) {
-      fs.mkdirSync(huskyDir, { recursive: true });
-    }
-
-    const commitMsgHook = `#!/usr/bin/env sh
-
-npx --no -- commitlint --edit "$1"
-`;
-    fs.writeFileSync(path.join(huskyDir, 'commit-msg'), commitMsgHook);
-    fs.chmodSync(path.join(huskyDir, 'commit-msg'), 0o755);
-
-    console.log('\n✅ Commiter setup complete!\n');
-    console.log('📚 Available commands:');
-    console.log('  npm run release major  - Create a major release (1.0.0 → 2.0.0)');
-    console.log('  npm run release minor  - Create a minor release (1.0.0 → 1.1.0)');
-    console.log('  npm run release patch  - Create a patch release (1.0.0 → 1.0.1)');
-    console.log('  npm run release        - Auto-detect version bump');
-    console.log('  npm run release -- --prerelease beta  - Create a beta prerelease\n');
-    console.log('🎯 Commit format: type(scope): subject');
-    console.log('   Example: feat(auth): add user login\n');
-
-  } catch (error) {
-    console.error('❌ Error during setup:', error.message);
-    process.exit(1);
-  }
-}
-
-// Run setup if called directly
-if (require.main === module) {
-  setupCommiter();
-}
-
-module.exports = { setupCommiter, ensureSafeTestScript };
+#!/usr/bin/env node
+
+/**
+ * Commiter - Commit convention tooling for standard-version releases
+ * 
+ * This package helps enforce conventional commits and automate releases
+ * with beautiful changelogs featuring icons for each commit type.
+ */
+
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+function ensureSafeTestScript(scripts = {}) {
+  const defaultFailingTestScript = 'echo "Error: no test specified" && exit 1';
+  if (!scripts.test || scripts.test === defaultFailingTestScript) {
+    scripts.test = 'echo "No tests specified"';
+  }
+  return scripts;
+}
+
+function setupCommiter() {
+  console.log('🚀 Setting up Commiter...\n');
+
+  // Check if package.json exists
+  if (!fs.existsSync('package.json')) {
+    console.error('❌ Error: package.json not found. Please run this in a Node.js project directory.');
+    process.exit(1);
+  }
+
+  try {
+    // Install dependencies
+    console.log('📦 Installing dependencies...');
+    execSync('npm install --save-dev standard-version @commitlint/cli @commitlint/config-conventional husky', {
+      stdio: 'inherit'
+    });
+
+    // Read package.json
+    const packageJsonPath = path.join(process.cwd(), 'package.json');
+    const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+
+    packageJson.scripts = ensureSafeTestScript(packageJson.scripts || {});
+    // Add scripts
+    packageJson.scripts.prepare = 'husky';
+    packageJson.scripts.release = 'node scripts/release.js';
+    packageJson.scripts['release:major'] = 'node scripts/release.js major';
+    packageJson.scripts['release:minor'] = 'node scripts/release.js minor';
+    packageJson.scripts['release:patch'] = 'node scripts/release.js patch';
+
+    // Add standard-version config
+    packageJson['standard-version'] = {
+      releaseCommitMessageFormat: 'chore(release): {{currentTag}} 🚀',
+      types: [
+        { type: 'feat', section: '✨ Features' },
+        { type: 'fix', section: '🐛 Bug Fixes' },
+        { type: 'perf', section: '⚡ Performance' },
+        { type: 'refactor', section: '♻️ Refactors' },
+        { type: 'docs', section: '📝 Documentation' },
+        { type: 'style', section: '💄 Styles' },
+        { type: 'test', section: '✅ Tests' },
+        { type: 'build', section: '🏗️ Build System' },
+        { type: 'ci', section: '👷 Continuous Integration' },
+        { type: 'chore', section: '🧹 Chores' },
+        { type: 'revert', section: '⏪ Reverts' }
+      ]
+    };
+
+    // Write updated package.json
+    fs.writeFileSync(packageJsonPath, JSON.stringify(packageJson, null, 2) + '\n');
+
+    // Create release helper script
+    console.log('🛠️  Creating release helper script...');
+    const releaseScriptDir = path.join(process.cwd(), 'scripts');
+    if (!fs.existsSync(releaseScriptDir)) {
+      fs.mkdirSync(releaseScriptDir, { recursive: true });
+    }
+
+    const releaseScriptPath = path.join(releaseScriptDir, 'release.js');
+    const releaseScriptSource = path.join(__dirname, 'scripts', 'release.js');
+    const releaseScriptContent = fs.readFileSync(releaseScriptSource, 'utf8');
+
+    fs.writeFileSync(releaseScriptPath, releaseScriptContent + '\n');
+    try {
+      fs.chmodSync(releaseScriptPath, 0o755);
+    } catch (error) {
+      // Ignore chmod errors on non-POSIX systems
+    }
+
+    // Determine commitlint config format based on project module type
+    const isEsmProject = packageJson.type === 'module';
+    const commitlintConfigFile = isEsmProject ? 'commitlint.config.js' : 'commitlint.config.cjs';
+    const commitlintConfigContent = isEsmProject
+      ? `export default {
+  extends: ['@commitlint/config-conventional'],
+  ignores: [(message) => message.startsWith('chore(release):')]
+}\n`
+      : `module.exports = {
+  extends: ['@commitlint/config-conventional'],
+  ignores: [(message) => message.startsWith('chore(release):')]
+}\n`;
+
+    const legacyCommitlintConfigFile = isEsmProject ? 'commitlint.config.cjs' : 'commitlint.config.js';
+    if (fs.existsSync(legacyCommitlintConfigFile)) {
+      fs.rmSync(legacyCommitlintConfigFile);
+    }
+
+    console.log(`⚙️  Creating commitlint config (${commitlintConfigFile})...`);
+    fs.writeFileSync(commitlintConfigFile, commitlintConfigContent);
+
+    // Initialize Husky
+    console.log('🐶 Setting up Husky...');
+    execSync('npx husky init', { stdio: 'inherit' });
+
+    // Create commit-msg hook
+    const huskyDir = path.join(process.cwd(), '.husky');
+    if (!fs.existsSync(huskyDir)) {
+      fs.mkdirSync(huskyDir, { recursive: true });
+    }
+
+    const commitMsgHook = `#!/usr/bin/env sh
+
+npx --no -- commitlint --edit "$1"
+`;
+    fs.writeFileSync(path.join(huskyDir, 'commit-msg'), commitMsgHook);
+    fs.chmodSync(path.join(huskyDir, 'commit-msg'), 0o755);
+
+    console.log('\n✅ Commiter setup complete!\n');
+    console.log('📚 Available commands:');
+    console.log('  npm run release major  - Create a major release (1.0.0 → 2.0.0)');
+    console.log('  npm run release minor  - Create a minor release (1.0.0 → 1.1.0)');
+    console.log('  npm run release patch  - Create a patch release (1.0.0 → 1.0.1)');
+    console.log('  npm run release        - Auto-detect version bump');
+    console.log('  npm run release -- --prerelease beta  - Create a beta prerelease\n');
+    console.log('🎯 Commit format: type(scope): subject');
+    console.log('   Example: feat(auth): add user login\n');
+
+  } catch (error) {
+    console.error('❌ Error during setup:', error.message);
+    process.exit(1);
+  }
+}
+
+// Run setup if called directly
+if (require.main === module) {
+  setupCommiter();
+}
+
+module.exports = { setupCommiter, ensureSafeTestScript };