feat: programmatic validateMesh v1 with structured findings - #25
Merged
Conversation
Tag refusal emission sites with MeshValidationFindingCode, replace the plain inventory errors with InventoryResolutionError, and catch the config/policy error families that previously escaped executeValidate uncaught. CLI validate output and exit behavior are unchanged; strict mode (API) rethrows untagged domain refusals raw. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
v1 per wd.programmatic-validate-api: exact-shape admission, the 14-code finding registry, coverage counts, optional meshBase, additive read-failure WeaveApiErrorCode, pre-resolution unsupported-source refusal for floating repository sources, raw propagation of unclassified errors. Deno.errors.NotADirectory/IsADirectory are looked up feature-tolerantly because the dnt Node shim omits them. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
npm description/README gain the validateMesh example with the source-capability and planner-coverage caveats; the off-tree Node smoke gains settled and seeded-defect validateMesh legs. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
wd.programmatic-validate-api carries the ratified v1 contract (14-code finding registry, family mapping, thrown taxonomy, coverage and fail-fast semantics). wu.api-reference gains the validateMesh section and the weave vs weave-lib consumption-model ruling; the CLI validate reference points at the programmatic surface; the wd.todo backlog line now tracks landing the built slice. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Boarding stub only — unreleased; finalize artifacts and wording at release time. Names the CLI strict improvement (malformed inventory/ config now findings, not crashes) per the behavioral-changelog rule. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (3)
🚧 Files skipped from review as they are similar to previous changes (2)
📝 WalkthroughWalkthroughThis PR adds a public ChangesvalidateMesh feature
Estimated code review effort: 4 (Complex) | ~75 minutes Sequence Diagram(s)sequenceDiagram
participant Client
participant validateMesh
participant executeValidate
participant prepareVersionExecution
participant loadMeshState
Client->>validateMesh: ValidateMeshRequest
validateMesh->>validateMesh: Admit request and preflight mesh root
validateMesh->>executeValidate: Targets and mesh-local source capability
executeValidate->>prepareVersionExecution: Prepare validation execution
prepareVersionExecution->>loadMeshState: Load mesh state and inventory
loadMeshState-->>prepareVersionExecution: Mesh metadata and designator paths
prepareVersionExecution-->>executeValidate: Coverage and classified findings
executeValidate-->>validateMesh: Validation result
validateMesh-->>Client: ValidateMeshResult
Possibly related PRs
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches 💡 1📝 Generate docstrings 💡
🧪 Generate unit tests (beta)
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. Comment |
Codecov Report❌ Patch coverage is 📢 Thoughts on this report? Let us know! |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (3)
src/runtime/weave/artifact_loaders.ts (3)
418-437: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick winMissing
designatorPathattribution on mesh-path boundary errors.
requireObservedMeshPaththrowsWeaveRuntimeErrorwith the"unresolvable-extraction-source"code but no attribution object. Its only caller,resolveSelectedExtractionSource, already hasdesignatorPathin scope when it buildserrorMessage. Otherunresolvable-extraction-sourcesites in this file (lines 267-271, 288-299, 391-392, 408-412) all attachdesignatorPath. Pass it here too, so structured findings consistently carry attribution instead of only embedding it in the free-text message.🔧 Proposed fix to attach designatorPath
function requireObservedMeshPath( meshBase: string, iri: string, errorMessage: string, + designatorPath?: string, ): string { if (!iri.startsWith(meshBase)) { - throw new WeaveRuntimeError( - errorMessage, - "unresolvable-extraction-source", - ); + throw new WeaveRuntimeError( + errorMessage, + "unresolvable-extraction-source", + designatorPath === undefined ? {} : { designatorPath }, + ); } const meshPath = iri.slice(meshBase.length); if (meshPath.includes("#") || meshPath.includes("?")) { - throw new WeaveRuntimeError( - errorMessage, - "unresolvable-extraction-source", - ); + throw new WeaveRuntimeError( + errorMessage, + "unresolvable-extraction-source", + designatorPath === undefined ? {} : { designatorPath }, + ); } return meshPath; }🤖 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 `@src/runtime/weave/artifact_loaders.ts` around lines 418 - 437, Update requireObservedMeshPath and its call from resolveSelectedExtractionSource to accept and pass through designatorPath, then include that attribution object in both WeaveRuntimeError constructions for mesh-base and fragment/query boundary failures. Preserve the existing error message and "unresolvable-extraction-source" code.
212-284: 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick winThread
sourceCapabilitythrough the extraction-source payload loader. UndersourceCapability: "mesh-local-only",loadReferenceTargetSourcePayloadArtifactbypasses the repository/floating source rejection because it does not pass this option intoloadPayloadWorkingArtifact. Add the option to this loader and passoptions?.sourceCapabilityfrom the candidate loader.🤖 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 `@src/runtime/weave/artifact_loaders.ts` around lines 212 - 284, The extraction-source payload path must preserve sourceCapability enforcement. In src/runtime/weave/artifact_loaders.ts lines 212-284, add an options parameter to loadReferenceTargetSourcePayloadArtifact and pass options?.sourceCapability into loadPayloadWorkingArtifact; in src/runtime/weave/candidate_loader.ts lines 284-298, pass the candidate loader’s sourceCapability option into loadReferenceTargetSourcePayloadArtifact.
212-219: 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick winThread
sourceCapabilitythrough extraction-source payload loading.
loadPayloadWorkingArtifactrejectsrepositorySourceFloatingLocatorundersourceCapability: "mesh-local-only", butloadReferenceTargetSourcePayloadArtifactalways defaults the nestedloadPayloadWorkingArtifactcall to"all". SincefirstExtractedKnopWeavecandidates use this path directly withoptions?.sourceCapability, passsourceCapabilityintoloadReferenceTargetSourcePayloadArtifactand forward it toloadPayloadWorkingArtifactat lines 277-284.🤖 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 `@src/runtime/weave/artifact_loaders.ts` around lines 212 - 219, Add a sourceCapability parameter to loadReferenceTargetSourcePayloadArtifact, pass options?.sourceCapability from firstExtractedKnopWeave, and forward it to the nested loadPayloadWorkingArtifact call instead of defaulting to "all". Preserve existing behavior when no capability is provided.
🧹 Nitpick comments (1)
src/api/validate_mesh.ts (1)
264-298: 🗄️ Data Integrity & Integration | 🔵 Trivial | ⚡ Quick winUnclassified errors escape the structured
WeaveApiErrorcontract.
mapCannotValidateErrorreturns unrecognized errors unchanged at line 297. Every other branch normalizes failures into aWeaveApiErrorwith a stablecode/stage. A consumer catching onlyWeaveApiError(the documented public error type) can still receive an arbitrary internal error type for any failure not covered by the listed classes. Wrap unrecognized errors in a fallbackWeaveApiError(e.g., a generic"internal-error"code) so every rejection fromvalidateMeshcarries the structured shape the rest of the API promises.♻️ Proposed fallback wrapping
return error; + // Consider instead: + // return new WeaveApiError( + // error instanceof Error ? error.message : "Could not validate the mesh.", + // { code: "internal-error", stage: "load", cause: error }, + // ); }🤖 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 `@src/api/validate_mesh.ts` around lines 264 - 298, Update mapCannotValidateError so unrecognized errors are wrapped in a fallback WeaveApiError instead of returned unchanged, using a stable generic code such as "internal-error", stage "load", and the original error as cause. Preserve the existing mappings for all recognized error types.
🤖 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 `@src/api/validate_mesh.ts`:
- Around line 117-129: In admitValidateMeshRequest, validate that
request.targets is an array whenever it is provided before calling map. Reject
truthy non-array values with the admission path’s existing clear validation
error mechanism, while preserving the optional behavior for omitted targets and
the existing normalization flow for valid arrays.
In `@src/api/version_payloads.ts`:
- Line 87: Update the filesystem error handling in the target inventory read,
working-file Deno.readFile, and current-file stat paths in version_payloads.ts
to construct the new "read-failure" code for newly thrown read errors. Preserve
existing WeaveApiError codes, including "malformed-mesh", and replace only
UnknownTargetError or unsupported-source fallbacks used for these filesystem
failures.
In `@src/core/weave/shape_assertions.ts`:
- Around line 45-58: Update the progression parsing flow in
progression_resolvers.ts to import and call the classified parseWeaveShapeQuads
wrapper from shape_assertions.ts instead of the raw rdf_helpers.ts parser.
Preserve the existing progression shape finding-code handling so malformed
inventory Turtle is surfaced as WeaveInputError.
In `@src/runtime/mesh/inventory.ts`:
- Around line 1690-1707: In the path validation logic within
normalizeWorkingLocalRelativePath, add a check after the normalized path is
computed to reject any path that starts with "../". This check should be placed
alongside the existing check for exact "." and ".." values to prevent directory
traversal paths like `a/../../secret` (which normalize to `../secret`) from
passing validation when they should be rejected as pointing outside the allowed
directory.
---
Outside diff comments:
In `@src/runtime/weave/artifact_loaders.ts`:
- Around line 418-437: Update requireObservedMeshPath and its call from
resolveSelectedExtractionSource to accept and pass through designatorPath, then
include that attribution object in both WeaveRuntimeError constructions for
mesh-base and fragment/query boundary failures. Preserve the existing error
message and "unresolvable-extraction-source" code.
- Around line 212-284: The extraction-source payload path must preserve
sourceCapability enforcement. In src/runtime/weave/artifact_loaders.ts lines
212-284, add an options parameter to loadReferenceTargetSourcePayloadArtifact
and pass options?.sourceCapability into loadPayloadWorkingArtifact; in
src/runtime/weave/candidate_loader.ts lines 284-298, pass the candidate loader’s
sourceCapability option into loadReferenceTargetSourcePayloadArtifact.
- Around line 212-219: Add a sourceCapability parameter to
loadReferenceTargetSourcePayloadArtifact, pass options?.sourceCapability from
firstExtractedKnopWeave, and forward it to the nested loadPayloadWorkingArtifact
call instead of defaulting to "all". Preserve existing behavior when no
capability is provided.
---
Nitpick comments:
In `@src/api/validate_mesh.ts`:
- Around line 264-298: Update mapCannotValidateError so unrecognized errors are
wrapped in a fallback WeaveApiError instead of returned unchanged, using a
stable generic code such as "internal-error", stage "load", and the original
error as cause. Preserve the existing mappings for all recognized error types.
🪄 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: ba515434-20fc-41ef-93a5-306aee90eaa3
📒 Files selected for processing (31)
documentation/notes/release-notes.v0.6.0.mddocumentation/notes/wd.programmatic-validate-api.mddocumentation/notes/wd.todo.mddocumentation/notes/wu.api-reference.mddocumentation/notes/wu.cli-reference.validate.mdscripts/build-npm-lib.tsscripts/smoke-npm-lib.tssrc/api/mod.tssrc/api/validate_mesh.tssrc/api/validate_mesh_test.tssrc/api/version_payloads.tssrc/core/weave/errors.tssrc/core/weave/mesh_support_pages.tssrc/core/weave/payload_version_layout.tssrc/core/weave/payload_weave_read_model.tssrc/core/weave/progression_resolvers.tssrc/core/weave/shape_assertions.tssrc/core/weave/weave.tssrc/mod.tssrc/runtime/mesh/inventory.tssrc/runtime/publication/presets.tssrc/runtime/weave/artifact_loaders.tssrc/runtime/weave/candidate_loader.tssrc/runtime/weave/errors.tssrc/runtime/weave/mesh_state.tssrc/runtime/weave/version_execution.tssrc/runtime/weave/weave.tstests/integration/validate_mesh_test.tstests/integration/validate_version_generate_test.tstests/integration/version_payloads_test.tstests/support/payload_mesh_fixture.ts
Non-array request.targets now refuses with a clear invalid-request message instead of surfacing a TypeError text, and shape-parse failures in rdf_helpers carry the unsupported-mesh-shape finding code so raw-importing callers (progression resolvers, read models) classify identically in strict mode. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Delivers the v0.6.0 headline:
validateMeshinsrc/api/@semantic-flow/weave-lib, returning structured findings with a stable 14-code registry instead of formatted CLI text — the adoption-deciding ask from the Stagecraft consumer reviews (wd.consumer-feedback-0.5.1 §8, re-raised 2026-07-29 §1).Built against the ratified contract note
documentation/notes/wd.programmatic-validate-api.md(spec review r1 rulings + build receipts live in the weave-dev-archive task notewa.task.2026.2026-07-29_1219-programmatic-validate-mesh-api).295c530feat(validate): classify runtime findings with stable codes — finding-code slots onWeaveInputError/WeaveRuntimeErrortagged at family emission sites;InventoryResolutionErrorreplaces plain inventoryErrors; previously-escaping config/policy error families are caught and classified. CLI text/exit behavior unchanged; strict mode (API) rethrows untagged domain refusals raw.4d89b5afeat(api): add validateMesh with structured findings — exact-shape admission, 14-code registry, planner-coverage counts, optionalmeshBase, additiveread-failurecode on the sharedWeaveApiErrorCodeunion, pre-resolutionunsupported-sourcerefusal for floating repository sources (threadedmesh-local-onlycapability; the git seam is never reached), raw propagation of unclassified errors. Includes a feature-tolerant lookup forDeno.errors.NotADirectory/IsADirectory, which the dnt Node shim omits.310bc40feat(lib): package validateMesh in weave-lib — npm description/README + settled and seeded-defectvalidateMeshlegs in the off-tree Node smoke.fe3a0d7docs — the normative contract note,wu.api-referencevalidateMesh section + weave/weave-lib consumption-model ruling, CLI validate pointer,wd.todoswap.8f9d742docs —release-notes.v0.6.0DRAFT boarding stub.Behavioral change (named per the changelog rule)
CLI
weave validatenow reports findings for malformed inventory Turtle and config-resolution failures (exit 1 with a message, like other findings) instead of letting them escape as uncaught crashes. All other CLI output and exit semantics are byte-covered unchanged.Test evidence
deno task ci: 733 passed / 0 failed (independently re-earned by the reviewing seat).deno task build:npm-lib+ off-tree Node smoke green: "2 payloads versioned and validateMesh returned settled/defect contract results under Node".src/api/fs_purity_test.tsgreen over the enlarged API graph; admission/parity/repository-refusal suites added.🤖 Generated with Claude Code
Summary by CodeRabbit
New Features
validateMeshAPI with structured findings, stable error codes, target filtering, and coverage metrics.Documentation
Tests