Next/v0.5.0

[djradon]

Summary by CodeRabbit

• New Features

  • Added the @semantic-flow/weave-lib npm package with ESM/CommonJS support and TypeScript declarations for programmatic API access.
  • npm library builds now include automated compatibility and filesystem validation.

• Bug Fixes

  • Improved weave mesh create diagnostics when a mesh path is outside the workspace, including clearer guidance.

• Documentation

  • Added v0.5.0 release notes and updated library usage and release guidance.
  • Existing consumers remain compatible; no breaking changes are introduced.

[coderabbitai]

Warning

Review limit reached

@djradon, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 47 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 33024c77-5a3b-406f-b73e-0b50d60f7e0d

📥 Commits

Reviewing files that changed from the base of the PR and between 1793857 and b1b8456.

📒 Files selected for processing (8)

• .github/workflows/ci.yml
• .github/workflows/release-manual.yml
• documentation/notes/wd.release-runbook.md
• documentation/notes/wd.todo.md
• documentation/notes/wu.api-reference.md
• documentation/notes/wu.md
• src/runtime/operational/local_path_policy_test.ts
• src/runtime/operational/repository_source_git.ts

📝 Walkthrough

Walkthrough

The change adds the @semantic-flow/weave-lib npm package, embeds default configuration resources, separates git-backed repository resolution from the API module graph, adds off-tree Node smoke validation, and wires library builds and publication into CI and release workflows.

Changes

npm library distribution and validation

Layer / File(s)	Summary
Build, smoke test, and release wiring .github/workflows/*, deno.json, scripts/build-npm-lib.ts, scripts/smoke-npm-lib.ts, tests/support/*, tests/integration/*, documentation/notes/*	The programmatic API is built as @semantic-flow/weave-lib, installed into an off-tree Node consumer, compared with the Deno result, and integrated into CI, release publication, documentation, and release runbooks.
Embedded defaults and API purity checks scripts/embed-defaults.ts, src/runtime/config/*, src/api/fs_purity_test.ts, src/core/rdf/namespaces.ts	Default Turtle resources are generated into TypeScript and loaded without a checkout root; the API dependency graph is checked for forbidden subprocess and network APIs.
Lazy git-backed repository resolution src/runtime/operational/*, src/runtime/artifact_resolution/*, src/runtime/extract/*, src/runtime/weave/*, tests/runtime/operational/*	Repository-source lookup moves to a lazy git-backed module with path and URL validation, while runtime consumers update their imports.
CLI diagnostics and regression updates src/cli/run.ts, tests/e2e/mesh_create_cli_test.ts	The out-of-workspace mesh-root error now explains path resolution and recommends omitting --mesh-root; the CLI test checks the updated wording.

Estimated code review effort: 4 (Complex) | ~60 minutes

Sequence Diagram(s)

sequenceDiagram
  participant CI
  participant BuildNpmLib
  participant SmokeNpmLib
  participant ReleaseWorkflow
  CI->>BuildNpmLib: deno task build:npm-lib
  BuildNpmLib->>SmokeNpmLib: produce dist/npm-lib
  SmokeNpmLib->>SmokeNpmLib: pack and install tarball
  SmokeNpmLib->>SmokeNpmLib: compare Node and Deno results
  ReleaseWorkflow->>BuildNpmLib: build and upload weave-npm-lib
  ReleaseWorkflow->>ReleaseWorkflow: npm publish with tag or dry-run

Loading

Possibly related PRs

• semantic-flow/weave#13: Introduced the release workflow extended here with npm library build and publication jobs.
• semantic-flow/weave#16: Also changes repository-source floating local path resolution.
• semantic-flow/weave#18: Changes the default content consumed by the embedded-default generation flow.

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (1 warning, 1 inconclusive)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 1.82% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.
Title check	❓ Inconclusive	The title is just the branch/version name and does not describe the actual changes in the PR.	Use a concise descriptive title that highlights the main change, e.g. "Add npm library packaging and release workflow for v0.5.0".

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch next/v0.5.0

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[codecov]

Codecov Report

❌ Patch coverage is 71.30802% with 68 lines in your changes missing coverage. Please review.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
src/runtime/operational/repository_source_git.ts	65.36%	44 Missing and 18 partials ⚠️
src/runtime/config/effective_config.ts	80.00%	4 Missing and 2 partials ⚠️

📢 Thoughts on this report? Let us know!

[coderabbitai]

Actionable comments posted: 4

🧹 Nitpick comments (2)

scripts/smoke-npm-lib.ts (1)

256-262: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Prefer @std/encoding/base64 over a hand-rolled encoder.

encodeBase64 here reimplements what @std/encoding/base64's encodeBase64 already provides for Uint8Array input.

♻️ Proposed refactor

-import { fromFileUrl, join } from "`@std/path`";
+import { fromFileUrl, join } from "`@std/path`";
+import { encodeBase64 } from "`@std/encoding/base64`";

-function encodeBase64(bytes: Uint8Array): string {
-  let binary = "";
-  for (const byte of bytes) {
-    binary += String.fromCharCode(byte);
-  }
-  return btoa(binary);
-}

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@scripts/smoke-npm-lib.ts` around lines 256 - 262, Replace the hand-rolled
encodeBase64 implementation with the existing encodeBase64 export from
`@std/encoding/base64`, passing the Uint8Array directly. Remove the local
binary-construction loop and update imports and call sites as needed while
preserving the current encoded output.

scripts/build-npm-lib.ts (1)

144-149: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Duplicate requireArgumentValue helper across the two new npm-lib scripts. Both scripts define the identical argument-validation helper (and near-identical --flag/--flag=value parsing scaffolding), which will drift if one copy is updated without the other.

• scripts/build-npm-lib.ts#L144-L149: extract requireArgumentValue (and ideally the shared parseArgs pattern) into a small scripts/lib/cli_args.ts helper and import it here.
• scripts/smoke-npm-lib.ts#L264-L269: import the same shared helper instead of redefining it.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@scripts/build-npm-lib.ts` around lines 144 - 149, Extract the duplicated
requireArgumentValue helper, and shared --flag/--flag=value parsing where
practical, into scripts/lib/cli_args.ts. Update scripts/build-npm-lib.ts lines
144-149 and scripts/smoke-npm-lib.ts lines 264-269 to import and reuse the
shared helper, removing their local definitions while preserving existing
argument-validation behavior.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.github/workflows/ci.yml:
- Around line 16-17: Update the actions/checkout step in the CI workflow to set
persist-credentials to false, ensuring the checkout does not retain the
GITHUB_TOKEN in local git configuration while leaving the existing checkout
behavior unchanged.

In @.github/workflows/release-manual.yml:
- Line 360: Update the release workflow’s publish argument construction so the
npm_tag input is passed through an environment variable and quoted at execution
time, rather than interpolated into the Bash array assignment. Add the required
id-token write permission and enable GitHub Releases provenance for npm
publishing, while preserving the selected tag behavior.

In `@documentation/notes/wd.todo.md`:
- Line 51: Update the unchecked packaging entry in the notes backlog to reflect
that the task is completed, or remove it if completion history is recorded
elsewhere. Align its version/status with v0.5.0 and the completed handoff
documented in wd.library-packaging, and ensure it no longer appears as active
deferred work.

In `@src/runtime/operational/repository_source_git.ts`:
- Around line 169-184: Update tryRunGit to catch subprocess construction and
output failures, including missing-git and permission-denied errors, and return
undefined for those failures. Preserve the existing undefined result for
unsuccessful command output so resolveRepositorySourceFloatingLocalPath can
continue its intended no-match fallback.

---

Nitpick comments:
In `@scripts/build-npm-lib.ts`:
- Around line 144-149: Extract the duplicated requireArgumentValue helper, and
shared --flag/--flag=value parsing where practical, into
scripts/lib/cli_args.ts. Update scripts/build-npm-lib.ts lines 144-149 and
scripts/smoke-npm-lib.ts lines 264-269 to import and reuse the shared helper,
removing their local definitions while preserving existing argument-validation
behavior.

In `@scripts/smoke-npm-lib.ts`:
- Around line 256-262: Replace the hand-rolled encodeBase64 implementation with
the existing encodeBase64 export from `@std/encoding/base64`, passing the
Uint8Array directly. Remove the local binary-construction loop and update
imports and call sites as needed while preserving the current encoded output.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 28c9057b-54fa-4819-a386-886cf9ed6f26

📥 Commits

Reviewing files that changed from the base of the PR and between 37f4b8f and 1793857.

⛔ Files ignored due to path filters (3)

• deno.lock is excluded by !**/*.lock
• src/runtime/config/generated/weave_defaults.ts is excluded by !**/generated/**
• src/runtime/config/generated/weave_defaults_test.ts is excluded by !**/generated/**

📒 Files selected for processing (27)

• .github/workflows/ci.yml
• .github/workflows/release-manual.yml
• deno.json
• documentation/notes/release-notes.v0.5.0.md
• documentation/notes/wd.library-packaging.md
• documentation/notes/wd.programmatic-version-api.md
• documentation/notes/wd.release-runbook.md
• documentation/notes/wd.todo.md
• scripts/build-npm-lib.ts
• scripts/embed-defaults.ts
• scripts/smoke-npm-lib.ts
• src/api/fs_purity_test.ts
• src/cli/run.ts
• src/core/rdf/namespaces.ts
• src/runtime/artifact_resolution/resolver.ts
• src/runtime/config/effective_config.ts
• src/runtime/extract/extract.ts
• src/runtime/operational/local_path_policy.ts
• src/runtime/operational/local_path_policy_test.ts
• src/runtime/operational/repository_source.ts
• src/runtime/operational/repository_source_git.ts
• src/runtime/weave/artifact_loaders.ts
• src/runtime/weave/raw_source_panels.ts
• src/runtime/weave/version_execution.ts
• tests/e2e/mesh_create_cli_test.ts
• tests/integration/version_payloads_test.ts
• tests/support/payload_mesh_fixture.ts