fix(uuid): make v5/v3/version/validate work on the native shim (#5197)

[proggeramlug]

Fixes #5197.

Problem

uuid's v5() (and friends) were non-functional on the native shim path — i.e. when uuid resolves from node_modules and is not in perry.compilePackages:

API	shim before	cause
v5 / v3	undefined	no runtime fn, no dispatch-table entry
version	undefined	runtime fn existed but was never wired into the table
validate	0	wired as NA_F64, but runtime takes *const StringHeader → arg passed in the wrong register
v4 / v1 / v7	[object Object]	boxed as NR_PTR (generic native handle) instead of a string

The perry.compilePackages (real-source) path already produced the correct id on current main — both paths now agree.

Fix

• Add js_uuid_v5 (SHA-1) and js_uuid_v3 (MD5) to both perry-ext-uuid and perry-stdlib; enable the uuid crate's v3/v5 features.
• Dispatch table (utils_crypto.rs): add v5/v3/version rows, fix validate's arg to NA_STR, box all string generators as NR_STR.
• New NR_BOOL return kind boxes the FFI bool-as-f64 (1.0/0.0) result as a real JS boolean so validate(...) prints true/false, not 1/0. Used for uuid.validate.
• Add matching API_MANIFEST entries (+ regenerated docs/) so the api-docs-drift and manifest_consistency gates stay green.

The shim supports the string-UUID namespace form (covers the repro + the v5.DNS/v5.URL constants); the array/Uint8Array namespace form remains reachable via perry.compilePackages.

Verification

Both paths now match Node exactly:

$ ./repro            # v5('perry', '6ba7b810-9dad-11d1-80b4-00c04fd430c8')
6cb3836f-339d-52d8-acc6-8751229b61cf true 5

• New perry-ext-uuid reference-vector tests for v5/v3 (verified against Node) — 7/7 pass.
• The one manifest_consistency failure (commander::args) is pre-existing and unrelated — it fails identically on main with this change stashed out.

Note: no version bump or CHANGELOG entry per request — left for the maintainer to fold in at merge time. The Cargo.lock diff is cargo syncing the workspace version (already set in Cargo.toml) and adding md-5/sha1_smol for the uuid features.

Summary by CodeRabbit

• New Features
  • Added uuid.v3() and uuid.v5() for name-based UUID generation.
  • Added uuid.version() to retrieve the numeric UUID version.
• Bug Fixes
  • Replaced uuid.validate() with uuid.version(), changing the result from boolean to a number.
  • Improved UUID string argument handling and corrected native calling/boxing for UUID-related returns.
• Documentation
  • Updated TypeScript definitions and the API reference to include uuid.v3, uuid.v5, and uuid.version.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: b49c6276-c387-4bcb-9dc8-61865704aa1d

📥 Commits

Reviewing files that changed from the base of the PR and between c75d372 and 8924fca.

📒 Files selected for processing (2)

• crates/perry-api-manifest/src/entries.rs
• docs/src/api/reference.md

✅ Files skipped from review due to trivial changes (1)

• docs/src/api/reference.md

🚧 Files skipped from review as they are similar to previous changes (1)

• crates/perry-api-manifest/src/entries.rs

---

📝 Walkthrough

Walkthrough

Adds uuid.v3 (MD5) and uuid.v5 (SHA-1) name-based UUID generation across the full Perry stack: Cargo feature flags, Rust FFI implementations in both perry-ext-uuid and perry-stdlib, native dispatch table ABI fixes (correcting NR_PTR→NR_STR for v1/v4/v7, adding v3/v5, fixing validate to return NR_BOOL), a new NativeRetKind::Bool LLVM lowering path, API manifest registration, and updated TypeScript declarations and reference docs. Also adds commander.args as a method-style manifest entry.

Changes

UUID v3/v5 support and NativeRetKind::Bool ABI fixes

Layer / File(s)	Summary
NativeRetKind::Bool variant and LLVM lowering crates/perry-codegen/src/lower_call/native_table/mod.rs, crates/perry-codegen/src/lower_call/native_module_dispatch.rs	NativeRetKind::Bool is introduced with its NR_BOOL shorthand and ret_kind_tag mapping. The LLVM codegen is updated to declare Bool-returning natives as DOUBLE and lower the f64 1.0/0.0 result into NaN-boxed TAG_TRUE/TAG_FALSE JS boolean values.
Native call signature table ABI corrections crates/perry-codegen/src/lower_call/native_table/utils_crypto.rs	UTILS_CRYPTO_ROWS uuid entries are corrected: v1/v4/v7 switch return from NR_PTR to NR_STR; v5/v3 entries are added with NA_STR inputs and NR_STR return; uuid.validate is corrected to NA_STR input and NR_BOOL return with expanded string-header coercion comments.
FFI uuid.v5 and uuid.v3 implementations crates/perry-ext-uuid/Cargo.toml, crates/perry-stdlib/Cargo.toml, crates/perry-ext-uuid/src/lib.rs, crates/perry-stdlib/src/uuid.rs	Enables v3/v5 uuid crate features in both crates. Implements parse_namespace helpers and js_uuid_v5/js_uuid_v3 extern C functions in both runtime crates, with reference-vector unit tests in perry-ext-uuid asserting exact UUID outputs and version digits.
API manifest and public TypeScript/documentation surface crates/perry-api-manifest/src/entries.rs, docs/api/perry.d.ts, docs/src/api/reference.md	Registers uuid.v5, uuid.v3, and uuid.version (replacing validate's Bool→Number return) in API_MANIFEST. Updates perry.d.ts declarations with the three new uuid exports and updates entry counts and the uuid methods list in the API reference.

Commander module method entry

Layer / File(s)	Summary
Commander.args method manifest entry and documentation crates/perry-api-manifest/src/entries.rs, docs/src/api/reference.md	Adds commander.args as a receiver-style method entry in API_MANIFEST to parallel the program.args member-read dispatch-table row. Updates the API reference markdown to document the entry in the commander module's Methods list.

Sequence Diagram(s)

sequenceDiagram
  participant Client as Perry Application
  participant Codegen as lower_native_module_dispatch
  participant LLVM as LLVM IR
  participant Runtime as Native Runtime

  Client->>Codegen: compile native Bool return
  Codegen->>LLVM: declare as DOUBLE type
  LLVM-->>Runtime: prepare invocation
  Runtime-->>LLVM: return f64 (1.0 or 0.0)
  Codegen->>Codegen: compare f64 != 0.0
  Codegen->>LLVM: select TAG_TRUE or TAG_FALSE
  LLVM-->>Client: JS boolean value

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• PerryTS/perry#5183: Updates commander module's args surface entry in API_MANIFEST and API reference docs, similar to the commander.args method entry added in this PR.

Poem

🐇 Hop, hop, through namespaces we go,
SHA-1 and MD5 join the show!
NR_BOOL boxes true from one,
The nil UUID when parsing's done.
v3 and v5 now compile and shine —
The rabbit says, these UUIDs are fine! 🎉

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main change: fixing uuid v5/v3/version/validate functionality in the native shim path.
Description check	✅ Passed	The description provides a clear problem statement, detailed fix explanation, and verification results, following the template structure with summary, changes, related issue, and test plan sections.
Linked Issues check	✅ Passed	The PR directly addresses all objectives from issue #5197: adds v5/v3 runtime functions, fixes version/validate dispatch entries, introduces NR_BOOL return type, and makes native shim output match Node.js behavior.
Out of Scope Changes check	✅ Passed	All changes are directly related to fixing UUID API functionality: FFI bindings for v5/v3, dispatch table updates, return-type handling, manifest entries, and documentation regeneration—no unrelated modifications detected.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch worktree-fix-uuid-v5-5197

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}