From e6b8b9b0482cbe26edd8f277ccf330fa1832b132 Mon Sep 17 00:00:00 2001 From: "Bruno R. Morillo" <111511828+brmorillo@users.noreply.github.com> Date: Wed, 17 Jun 2026 18:26:05 -0300 Subject: [PATCH 1/2] docs: add CI badge, CONTRIBUTING.md, PR template and issue templates README: - Replace static npm badge with shields.io dynamic badge (shows live version) - Add CI status badge (GitHub Actions) - Add bundle size badge (bundlephobia minzipped) - Add Node.js minimum version badge (from engines field) - Add links to CONTRIBUTING.md and SECURITY.md in Documentation section .github/: - pull_request_template.md: type-of-change checklist + full contribution checklist - ISSUE_TEMPLATE/bug_report.md: structured bug report with env details - ISSUE_TEMPLATE/feature_request.md: API proposal with scope/compat notes CONTRIBUTING.md: - Quick-start (clone, bun install, build, test) - All conventions: single-object arg, non-mutating, typed errors, TSDoc, English - Step-by-step for adding a method and a new module - Commit/branch naming reference table - PR process and dependency policy summary Co-Authored-By: Claude Sonnet 4.6 --- .github/ISSUE_TEMPLATE/bug_report.md | 42 ++++++ .github/ISSUE_TEMPLATE/feature_request.md | 34 +++++ .github/pull_request_template.md | 35 +++++ CONTRIBUTING.md | 160 ++++++++++++++++++++++ README.md | 11 +- 5 files changed, 279 insertions(+), 3 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md create mode 100644 .github/ISSUE_TEMPLATE/feature_request.md create mode 100644 .github/pull_request_template.md create mode 100644 CONTRIBUTING.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..d3af6f1 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,42 @@ +--- +name: Bug report +about: Something isn't working as documented +title: 'fix: ' +labels: bug +assignees: brmorillo +--- + +## Describe the bug + + + +## Module / method + + + +## Steps to reproduce + +```ts +// Minimal reproduction +import { } from '@brmorillo/utils'; + +``` + +## Expected behavior + + + +## Actual behavior + + + +## Environment + +- `@brmorillo/utils` version: +- Node.js version: +- Runtime (Node / Bun / browser): +- Module format used (`require` / `import`): + +## Additional context + + diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..c6518e9 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,34 @@ +--- +name: Feature request +about: Propose a new method, module, or additive improvement +title: 'feat: ' +labels: enhancement +assignees: brmorillo +--- + +## Problem / motivation + + + +## Proposed API + +```ts +// Show how the new method / module would be called. +// Follow the single-object-argument convention used by the rest of the library. +import { } from '@brmorillo/utils'; + +``` + +## Alternatives considered + + + +## Scope and compatibility notes + + + +## Additional context + + diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..6022adb --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,35 @@ +## Summary + + + +- +- + +## Type of change + +- [ ] Bug fix (`fix:`) +- [ ] New feature / additive change (`feat:`) +- [ ] Documentation (`docs:`) +- [ ] Refactor — no behavior change (`refactor:`) +- [ ] Tests (`test:`) +- [ ] CI / tooling (`chore:`, `ci:`) +- [ ] Performance (`perf:`) +- [ ] Breaking change (`feat!:` / `fix!:` + `BREAKING CHANGE:` footer) + +## Checklist + +- [ ] Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, `docs:`, …) +- [ ] `bun run type-check` passes +- [ ] `bun run lint` passes (0 warnings) +- [ ] `CI=true bun run test:ci` passes (coverage thresholds met) +- [ ] `bun run build` passes with 0 warnings +- [ ] New public methods have TSDoc (`/** */` with at least a summary line) +- [ ] No `throw new Error(…)` — typed errors from `src/errors` only +- [ ] Data-transforming methods are non-mutating by default (add `inPlace?` if mutation is needed) +- [ ] No ESM-only runtime dependencies added (check `require` export before bumping a major) + +## Test plan + + + +- diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..66a7760 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,160 @@ +# Contributing to @brmorillo/utils + +Thank you for taking the time to contribute! This document is a quick-start guide. For the full architecture and convention reference, read [CLAUDE.md](./CLAUDE.md). + +## Table of contents + +- [Getting started](#getting-started) +- [Development workflow](#development-workflow) +- [Conventions](#conventions) +- [Adding a new method](#adding-a-new-method) +- [Adding a new module](#adding-a-new-module) +- [Commit and branch naming](#commit-and-branch-naming) +- [Pull request process](#pull-request-process) +- [Dependency policy](#dependency-policy) + +--- + +## Getting started + +```bash +git clone https://github.com/brmorillo/utils.git +cd utils +bun install # npm install fails here — use bun +bun run build # typecheck + CJS + ESM + .d.ts +CI=true bun run test:ci # full suite with coverage gate +``` + +> **Node.js >= 18** and **[Bun](https://bun.sh)** are required. + +--- + +## Development workflow + +```bash +bun run type-check # tsc --noEmit +bun run lint # eslint (0 warnings expected) +bun run test # jest unit + integration +bun run test:coverage +bun run build # must finish with 0 warnings +bun run format # prettier --write src/ +``` + +All five commands must pass before opening a PR. + +--- + +## Conventions + +These are enforced by CI and the invariant test suites — a PR that breaks them will not be merged. + +### Single object argument + +Every static utility method takes **one destructured object**: + +```ts +// ✅ +StringUtils.toCamelCase({ input: 'hello world' }) + +// ❌ +StringUtils.toCamelCase('hello world') +``` + +Singleton services (`HttpService`, `LogService`, `StorageService`) use a method-style API instead — that is intentional. + +### Non-mutating by default + +Data-transforming methods must return a **new value** and leave the input untouched. Where in-place mutation makes sense, expose it as `inPlace?: boolean` (default `false`). See `immutability.spec.ts` and `inplace-invariant.spec.ts`. + +### Typed errors only + +**Never** `throw new Error(…)` in library code. Use the typed errors from `src/errors`: + +```ts +import { ValidationError, BaseError, StorageError, HttpError, QueueFullError } from '../errors'; + +throw new ValidationError('Input must be a string', 'input'); +throw new BaseError('Something went wrong', 'MY_ERROR_CODE', 500, details, { cause: err }); +``` + +### TSDoc on every public member + +All exported classes, methods, constructors, and helpers need a `/** */` block with at least a summary line. + +### Predicate naming + +- Property predicates: `is*` (`isEven`, `isPrime`, `isPalindrome`) +- Format validators in `ValidationUtils`: `isValid*` (`isValidEmail`, `isValidCPF`) + +### English only + +All identifiers, comments, doc strings, and test descriptions must be in English. + +--- + +## Adding a new method + +1. Add the static method to the appropriate service in `src/services/`. +2. Write a TSDoc block for it. +3. Add unit tests in `tests/unit/.service.spec.ts`. +4. Add an integration test in `tests/integration/.service.int-spec.ts`. +5. If the method is data-transforming, add it to `immutability.spec.ts`. If it supports `inPlace`, add it to `inplace-invariant.spec.ts`. +6. Update the module docs in `docs//README.md`. + +--- + +## Adding a new module + +1. Create `src/services/.service.ts` with a static utility class. +2. Export it from `src/index.ts`. +3. Add unit + integration tests. +4. Add it to `tests/unit/public-surface.spec.ts` and `tests/integration/contract.int-spec.ts`. +5. Create `docs//README.md` and link it from `docs/README.md` and `README.md`. + +--- + +## Commit and branch naming + +This project uses [Conventional Commits](https://www.conventionalcommits.org/): + +| Type | When to use | +| --- | --- | +| `feat:` | New method, module, or additive export | +| `fix:` | Bug fix | +| `docs:` | Documentation only | +| `refactor:` | Internal restructure, no behavior change | +| `test:` | Adding or fixing tests | +| `chore:` | Build, config, tooling | +| `ci:` | CI workflow changes | +| `perf:` | Performance improvement | + +Breaking changes: add `!` suffix (`feat!:`) and include a `BREAKING CHANGE:` footer. + +Branch naming: `feature/`, `fix/`, `docs/`, `chore/`. + +--- + +## Pull request process + +1. Open a PR against `main`. +2. The `pr-version` workflow automatically commits a `chore(release): vX.Y.Z` bump to your branch — **do not edit it manually**. +3. The CI pipeline (type-check → lint → test with coverage → build → secret scan) must pass. +4. A maintainer reviews and merges. After merge, the `release` workflow tags and publishes to npm automatically. + +--- + +## Dependency policy + +- All dependencies are pinned to **exact versions** (no `^` or `~`). +- Updates happen **once a month**, staying **at least 3 months behind** the latest release (supply-chain safety buffer). +- Before bumping a runtime dependency to a new major, verify it ships a CommonJS build: + ```bash + node -e "require('')" + ``` +- `uuid` is permanently pinned to `^11` and `@paralleldrive/cuid2` to `^2` (v3+ are ESM-only and would break CJS consumers). + +--- + +## Questions? + +Open a [GitHub Discussion](https://github.com/brmorillo/utils/issues) or reach out via [bruno@rmorillo.com](mailto:bruno@rmorillo.com). diff --git a/README.md b/README.md index 89e4c32..5358568 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,12 @@ # @brmorillo/utils -[![npm version](https://badge.fury.io/js/@brmorillo%2Futils.svg)](https://www.npmjs.com/package/@brmorillo/utils) -[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue.svg)](https://www.typescriptlang.org/) -[![License: LGPL-3.0](https://img.shields.io/badge/License-LGPL%20v3-blue.svg)](https://www.gnu.org/licenses/lgpl-3.0) +[![npm version](https://img.shields.io/npm/v/@brmorillo/utils?label=npm&color=cb3837)](https://www.npmjs.com/package/@brmorillo/utils) +[![CI](https://github.com/brmorillo/utils/actions/workflows/ci.yml/badge.svg)](https://github.com/brmorillo/utils/actions/workflows/ci.yml) [![Downloads](https://img.shields.io/npm/dm/@brmorillo/utils.svg)](https://www.npmjs.com/package/@brmorillo/utils) +[![Bundle size](https://img.shields.io/bundlephobia/minzip/@brmorillo/utils?label=minzipped)](https://bundlephobia.com/package/@brmorillo/utils) +[![Node.js](https://img.shields.io/node/v/@brmorillo/utils?color=339933)](https://nodejs.org) +[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-3178c6.svg)](https://www.typescriptlang.org/) +[![License: LGPL-3.0](https://img.shields.io/badge/License-LGPL%20v3-blue.svg)](https://www.gnu.org/licenses/lgpl-3.0) > If you have a problem, it's probably already solved here. @@ -179,6 +182,8 @@ guarantees, see the [Security Policy](./SECURITY.md). - 📚 **[Module reference](./docs/README.md)** — one page per module - 🧪 **[Examples](./examples)** — runnable usage examples - 🤖 **[CLAUDE.md](./CLAUDE.md)** — architecture & conventions for contributors and AI assistants +- 🤝 **[CONTRIBUTING.md](./CONTRIBUTING.md)** — how to contribute +- 🔒 **[SECURITY.md](./SECURITY.md)** — vulnerability reporting & security policy ## Development From 66a5e8d5c91ec96b4d8a593453beac5f92900ed5 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Wed, 17 Jun 2026 21:28:54 +0000 Subject: [PATCH 2/2] chore(release): 14.1.1 --- CHANGELOG.md | 7 +++++++ package.json | 2 +- 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index e74144e..aedddd6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,13 @@ All notable changes to this project will be documented in this file. See [commit-and-tag-version](https://github.com/absolute-version/commit-and-tag-version) for commit guidelines. +## [14.1.1](https://github.com/brmorillo/util/compare/v14.1.0...v14.1.1) (2026-06-17) + + +### Documentation + +* add CI badge, CONTRIBUTING.md, PR template and issue templates ([e6b8b9b](https://github.com/brmorillo/util/commit/e6b8b9b0482cbe26edd8f277ccf330fa1832b132)) + ## [14.1.0](https://github.com/brmorillo/util/compare/v14.0.2...v14.1.0) (2026-06-17) diff --git a/package.json b/package.json index 3d93d9c..60b7b65 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@brmorillo/utils", - "version": "14.1.0", + "version": "14.1.1", "description": "Production-ready utility library for JS/TS — 27 modules behind one type-safe API: arrays, objects, strings, crypto, JWT, UUID, sorting, queues, caches, HTTP, logging, storage and more.", "main": "dist/index.js", "module": "dist/index.mjs",