@programinglive/commiter 1.0.12 → 1.1.1

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+### [1.1.1](https://github.com/programinglive/commiter/compare/v1.1.0...v1.1.1) (2025-11-05)
+
+
+### 🐛 Bug Fixes
+
+* remove fs.F_OK deprecation warning ([1b0652b](https://github.com/programinglive/commiter/commit/1b0652b88d1b095e1045994948f75ce8194f9d3a))
+
+## [1.1.0](https://github.com/programinglive/commiter/compare/v1.0.12...v1.1.0) (2025-10-29)
+
+
+### 📝 Documentation
+
+* clarify release automation flow ([1cf7aa2](https://github.com/programinglive/commiter/commit/1cf7aa2432f371eac69d6931c8a497991686bfc6))
+
 ### [1.0.12](https://github.com/programinglive/commiter/compare/v1.0.11...v1.0.12) (2025-10-29)
 
 

package/PRD.md

@@ -0,0 +1,86 @@
+# Commiter Product Requirements Document (PRD)
+
+## 1. Overview
+Commiter is a CLI utility that bootstraps and automates conventional release workflows for JavaScript/TypeScript projects. It enforces commit conventions, orchestrates semantic version bumps, keeps release tooling configured, and surfaces feedback during release execution so teams can ship confidently.
+
+## 2. Problem Statement
+Growing teams often struggle to keep release processes consistent: commit messages drift from convention, changelogs become stale, and release scripts accumulate manual steps. Commiter removes this friction by installing opinionated tooling, providing curated scripts, and running guard rails (tests, linters) before invoking `standard-version` to publish a release.
+
+## 3. Goals & Success Metrics
+- **Consistent releases**: Every release run through Commiter formats commits, updates changelogs, tags, and version bumps without manual editing.
+- **Low ceremony onboarding**: A single `npx commiter` command prepares repositories (Husky, commitlint, release scripts).
+- **Signal-rich automation**: Release logs clearly show which steps ran, including any warnings (e.g., tests skipped). Zero noisy deprecation warnings.
+- **Reliability**: New releases do not regress existing behavior; the automated test suite passes (`node --test`).
+- **Adoption Metric**: Track installations (npm downloads) and successful release script exits.
+
+## 4. Personas
+1. **Solo Maintainer** – wants painless semantic releases without memorizing commands.
+2. **Team Lead** – enforces commit standards across contributors and ensures releases produce accurate changelogs.
+3. **DevOps/CI Engineer** – integrates Commiter’s release command into CI pipelines and expects deterministic, machine-readable output.
+
+## 5. Key Features
+- **Setup CLI (`index.js`)**
+  - Installs dev dependencies (`standard-version`, `commitlint`, `husky`).
+  - Configures package scripts (`npm run release`, `release:major/minor/patch`).
+  - Creates Husky hooks and commitlint configuration.
+  - Generates release helper script and ensures executable permissions (POSIX-friendly).
+- **Release Helper (`scripts/release.js`)**
+  - Detects release type from CLI args or npm context.
+  - Runs project tests via detected package manager before releasing.
+  - Invokes `standard-version` with additional flags (e.g., preload patch for deprecated APIs).
+- **Preload Patching (`scripts/preload/fs-f-ok.cjs`)**
+  - Hooks Node’s module loader to transparently replace deprecated `fs.F_OK` usages in `standard-version` without altering `node_modules`.
+- **Testing**
+  - Suite executed via `node --test` covers setup utilities, release argument parsing, and the preload patch.
+
+## 6. Functional Requirements
+1. Running `npx @programinglive/commiter` inside a Node project should configure release tooling without manual edits.
+2. `npm run release` must:
+   - Run the project’s tests (if defined) with the correct package manager.
+   - Execute `standard-version`, passing the preload script via `NODE_OPTIONS`.
+   - Exit with non-zero status if tests or standard-version commands fail.
+3. CLI should provide friendly console output (status icons, instructions).
+4. The preload script must eliminate `[DEP0176] fs.F_OK` warnings on supported Node versions.
+5. Documentation (README, PRD, release notes) remains shipped with the package.
+
+## 7. Non-Functional Requirements
+- **Compatibility**: Supports Node.js 18+ (aligning with dependencies); tested on Windows/macOS/Linux.
+- **Maintainability**: Avoid direct edits to dependencies; wrap behavior in Commiter-controlled modules.
+- **Performance**: Release command overhead minimal (<1s additional startup time) beyond running tests and standard-version.
+- **Security**: No network requests during CLI execution beyond npm installs triggered by the user.
+
+## 8. User Journeys
+1. **Initial Setup**
+   - Run `npx @programinglive/commiter`.
+   - Tool installs dependencies, updates `package.json`, and scaffolds Husky hooks.
+   - Maintainer confirms success message and new scripts.
+2. **Standard Release**
+   - Developer runs `npm run release minor`.
+   - Commiter runs tests, ensures preload patch prevents deprecation warnings, executes `standard-version`.
+   - Release completes with updated changelog and git tag.
+3. **CI Pipeline**
+   - CI job executes `npm run release -- --prerelease beta`.
+   - Logs show tests executed, no deprecation warnings, and release artifacts generated.
+
+## 9. Milestones & Roadmap
+- **v1.1.x** (current)
+  - Deprecation warning mitigation, enhanced tests, PRD + release documentation.
+- **Future Considerations**
+  - Support for monorepo detection (Lerna/Nx) to run scoped releases.
+  - Optional lint/test command customization via config file.
+  - Telemetry opt-in for release statistics (downloads, success rates).
+
+## 10. Risks & Mitigations
+- **Dependency API Changes**: Upstream packages may alter file paths. Mitigate with targeted module resolution and tests.
+- **User Customization Conflicts**: Custom scripts might skip tests. Provide documentation for overriding behavior.
+- **Platform Differences**: Windows path quoting; addressed via `buildPreloadFlag` helper.
+
+## 11. Release & QA Checklist
+- [x] `npm test` (alias for `node --test`) passes.
+- [x] Manual run of `node scripts/release.js --help` shows no `[DEP0176]` warning.
+- [ ] Update `CHANGELOG.md` (handled by standard-version during actual release).
+- [ ] Verify README reflects latest setup instructions before shipping.
+
+## 12. Appendices
+- **Release Notes**: See `docs/release-notes/` for per-change summaries.
+- **Testing Artifacts**: `test/` directory contains Node test runner suites.

package/README.md

@@ -116,11 +116,12 @@ npm run release
 
 ## What Happens During Release?
 
-1. 📊 Analyzes commits since last release
-2. 🔢 Bumps version in `package.json`
-3. 📝 Updates `CHANGELOG.md` with icons
-4. 🏷️ Creates a git tag
-5. 💾 Commits changes with format: `chore(release): v1.2.3 🚀`
+1. 🧪 Detects your package manager and runs the `test` script automatically
+2. 📊 Analyzes commits since last release
+3. 🔢 Bumps version in `package.json`
+4. 📝 Updates `CHANGELOG.md` with icons
+5. 🏷️ Creates a git tag
+6. 💾 Commits changes with format: `chore(release): v1.2.3 🚀`
 
 ## Push Your 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,33 @@
+# 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.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. |
+
+## fs.F_OK Deprecation Warning Fix (Unreleased)
+- 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/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@programinglive/commiter",
-  "version": "1.0.12",
+  "version": "1.1.1",
   "description": "Commiter keeps repositories release-ready by enforcing conventional commits, generating icon-rich changelog entries, and orchestrating semantic version bumps without manual toil. It bootstraps Husky hooks, commitlint rules, and release scripts that inspect history, detect framework-specific test commands, run them automatically, tag git releases, coordinate npm publishing, surface release metrics, enforce project-specific checks, and give maintainers observability across distributed teams. Plus!",
   "main": "index.js",
   "bin": {
     "commiter": "./index.js"
   },
   "scripts": {
-    "test": "node test/ensureSafeTestScript.test.js",
+    "test": "node --test",
     "prepare": "husky",
     "release": "node scripts/release.js",
     "release:major": "node scripts/release.js major",

package/scripts/preload/fs-f-ok.cjs

@@ -0,0 +1,23 @@
+const fs = require('fs');
+const Module = require('module');
+
+const targetPath = require.resolve('standard-version/lib/lifecycles/changelog');
+
+if (!Module._commiterPatchedFsFok) {
+  const originalLoader = Module._extensions['.js'];
+
+  Module._extensions['.js'] = function patchedLoader(module, filename) {
+    if (filename === targetPath) {
+      let source = fs.readFileSync(filename, 'utf8');
+      if (source.includes('fs.F_OK')) {
+        source = source.replace(/fs\.F_OK/g, 'fs.constants.F_OK');
+      }
+      module._compile(source, filename);
+      return;
+    }
+
+    return originalLoader(module, filename);
+  };
+
+  Module._commiterPatchedFsFok = true;
+}

package/scripts/release.js

@@ -4,6 +4,11 @@ const { spawnSync } = require('child_process');
 const fs = require('fs');
 const path = require('path');
 
+const fsFokPreloadPath = path.join(__dirname, 'preload', 'fs-f-ok.cjs');
+const FS_FOK_PRELOAD_FLAG = buildPreloadFlag(fsFokPreloadPath);
+
+require('./preload/fs-f-ok.cjs');
+
 const VALID_RELEASE_TYPES = new Set([
   'major',
   'minor',
@@ -141,8 +146,10 @@ function runRelease({ argv = process.argv, env = process.env, spawn = spawnSync
   }
 
   const standardVersionBin = require.resolve('standard-version/bin/cli.js');
+  const childEnv = appendPreloadToNodeOptions(env, FS_FOK_PRELOAD_FLAG);
   return spawn(process.execPath, [standardVersionBin, ...standardVersionArgs], {
-    stdio: 'inherit'
+    stdio: 'inherit',
+    env: childEnv
   });
 }
 
@@ -169,3 +176,18 @@ module.exports = {
   runProjectTests,
   runRelease
 };
+
+function buildPreloadFlag(filePath) {
+  const resolved = path.resolve(filePath);
+  const escaped = resolved.includes(' ')
+    ? `"${resolved.replace(/"/g, '\"')}"`
+    : resolved;
+  return `--require ${escaped}`;
+}
+
+function appendPreloadToNodeOptions(env, preloadFlag) {
+  const nextEnv = { ...env };
+  const existing = typeof nextEnv.NODE_OPTIONS === 'string' ? nextEnv.NODE_OPTIONS.trim() : '';
+  nextEnv.NODE_OPTIONS = existing ? `${existing} ${preloadFlag}` : preloadFlag;
+  return nextEnv;
+}