feat: add random services

[nfroidure]

No description provided.

[coveralls]

coverage: 84.028% (-0.03%) from 84.058% — feat/random_services into main

[Copilot]

Pull request overview

Adds new “random” utility services to the common-services module to encapsulate additional sources of nondeterminism (UUID and cryptographic bytes) behind easily injectable/mocked Knifecycle services, while also refreshing docs/architecture notes and upgrading tooling dependencies.

Changes:

• Add initRandomUUID and initRandomBytes Knifecycle services with Jest coverage and export them from the package entrypoint.
• Update various architecture/doc strings from “stubbable” to “mockable” and fix a few spelling/wording issues in generated docs.
• Update dev tooling dependencies and changelog generation configuration.

Reviewed changes

Copilot reviewed 16 out of 17 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
src/utils/crypto.ts	Minor naming tweak in the async randomBytes wrapper.
src/services/time.ts	Doc wording update (“stubbable” → “mockable”).
src/services/resolve.ts	Doc wording update (“stubbable” → “mockable”).
src/services/randomUUID.ts	New Random UUID service wrapping Node’s crypto.randomUUID.
src/services/randomUUID.test.ts	New Jest tests for Random UUID service.
src/services/randomBytes.ts	New Random Bytes service wrapping the project’s crypto helper.
src/services/randomBytes.test.ts	New Jest tests for Random Bytes service.
src/services/random.ts	Doc wording update (“stubbable” → “mockable”).
src/services/importer.ts	Doc wording update (“stubbable” → “mockable”).
src/services/counter.ts	Doc wording update (“stubbable” → “mockable”).
src/index.ts	Export the new services/types from the public module surface.
README.md	Document the new services in the generated README API section.
API.md	Document the new services in the generated API reference.
ARCHITECTURE.md	Add new architecture notes and refresh wording/spelling.
package.json	Upgrade tooling/deps and update changelog/precommit scripts.
commitlint.config.mjs	Fix the @ts-check directive comment.

Suppressed comments (2)

src/services/randomBytes.test.ts:41

• The randomBytes test only checks logging; it doesn’t validate that the returned Buffer has the requested length (the core behavior of this service).

      await randomBytes(16);

      expect(log.mock.calls).toEqual([
        ['debug', '🎲 - Created random bytes (length: 16).'],
      ]);

src/services/randomUUID.test.ts:41

• The randomUUID test only checks logging; it doesn’t validate that the returned value is a UUID (the core behavior of this service).

      const uuid = randomUUID();

      expect(log.mock.calls).toEqual([
        ['debug', '🎲 - Created a random UUID:', uuid],
      ]);

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 23 out of 24 changed files in this pull request and generated 1 comment.

Suppressed comments (3)

src/services/randomBytes.ts:43

• The JSDoc example calls await randomBytes() with no length argument, but randomBytes(length: number) requires one. This propagates into generated docs (README/API) and is misleading.

   * @example
   * await randomBytes()
   * // Prints: <buffer>

src/services/randomUUID.ts:28

• The init example assigns the returned service to random, but the service is named randomUUID throughout the module. This is confusing in generated docs and examples.

 * const random = await initRandomUUID({
 *   log,
 * });

src/services/randomUUID.ts:52

• Logging the generated UUID value ('🎲 - Created a random UUID:', uuid) can leak identifiers into logs. Consider logging only that a UUID was generated (or a redacted value), especially if consumers use UUIDs as secrets/tokens.

    const uuid = _randomUUID(options);

    log('debug', '🎲 - Created a random UUID:', uuid);

    return uuid;

[Copilot]

Pull request overview

Copilot reviewed 24 out of 25 changed files in this pull request and generated no new comments.

Suppressed comments (1)

src/services/randomBytes.ts:51

• This logs "Created random bytes" before the underlying async generation completes. If _randomBytes(length) rejects, logs will still claim bytes were created successfully.

  function randomBytes(length: number): ReturnType<RandomBytesService> {
    const bytes = _randomBytes(length);

    log('debug', `🎲 - Created random bytes (length: ${length}).`);