Project: lacus-utils - The Ruby Toolbox

Brazilian data utilities (CPF, CNPJ, etc.) as a multi-gem monorepo, publishable to RubyGems with independent versioning and GitHub Actions (Trusted Publishing / OIDC).

Structure

Root: Tooling (Rake, RuboCop), shared config in config/gems.yml, no app code.
Packages: Under packages/ — each is a gem (e.g. cpf-dv, cpf-utilities, br-utilities). Internal dependencies use path in development and version constraints when published.

See CONTRIBUTING.md for folder layout, tagging, dependency resolution, and development workflow.

Local setup

bundle install
rake hooks:install          # enable the git hooks (pre-commit, pre-push, commit-msg)
rake monorepo:check_cycles
cd packages/cpf-dv && bundle install && rake test

Git hooks

rake hooks:install points core.hooksPath at .githooks/, enabling:

pre-commit: RuboCop auto-corrects the staged Ruby files and re-stages only the linting changes (unstaged edits in the same files are preserved, never committed). Aborts if offenses remain that safe auto-correction can't fix.
pre-push: runs the repository specs and every package's tests in build order, aborting the push if any test fails.
commit-msg: rejects commit messages that don't follow Conventional Commits.

Undo with rake hooks:uninstall. See CONTRIBUTING.md for details.

Commit messages

Commits follow Conventional Commits. A pure-Ruby linter (bin/commit-lint) enforces this in two places:

Locally: rake hooks:install sets core.hooksPath to .githooks, so the commit-msg hook rejects non-conforming messages. Undo with rake hooks:uninstall.
CI: the Commit Lint workflow validates every commit in a push/PR.

Allowed types: build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test. The (scope) is optional; when present it must be one of the per-package scopes below (a few differ from the gem name). Example: feat(cpf-gen): add batch generator.

Scope	Package
`utils`	`lacus-utils`
`cnpj-dv`	`cnpj-dv`
`cnpj-fmt`	`cnpj-fmt`
`cnpj-gen`	`cnpj-gen`
`cnpj-val`	`cnpj-val`
`cnpj-utils`	`cnpj-utilities`
`cpf-dv`	`cpf-dv`
`cpf-fmt`	`cpf-fmt`
`cpf-gen`	`cpf-gen`
`cpf-val`	`cpf-val`
`cpf-utils`	`cpf-utilities`
`br-utils`	`br-utilities`

Lint a range manually with rake lint:commits (defaults to origin/main..HEAD, override with COMMIT_RANGE).

Releasing (one gem at a time)

Bump version in packages/<dir>/src/<gem_name>/version.rb, commit.
Push tag: git tag <gem_name>@<version> (e.g. cpf-dv@1.0.1), then git push origin <tag>.
Configure RubyGems Trusted Publishing for this repo and the release environment.
The Release workflow runs: tests the package, builds the gem, publishes to RubyGems via OIDC. No secrets required.

Release leaves first (e.g. cpf-dv, cpf-fmt), then dependents (cpf-utilities, cnpj-utilities), then br-utilities.

License

MIT. See LICENSE.