@savvy-web/silk-effects 3.0.1 → 3.0.3

package/changesets/utils/jsonpath.js

@@ -69,23 +69,46 @@ function parseJsonPath(path) {
 * @internal
 */
 function jsonPathGet(obj, path) {
+	return walkJsonPath(obj, path).map((entry) => entry.node);
+}
+/**
+* Shared breadth-first traversal behind {@link jsonPathGet} and
+* {@link jsonPathResolve}: each segment fans out the current set of matched
+* entries, carrying both the node and the concrete path taken to reach it.
+* The two public functions differ only in which half of the entry they keep.
+*/
+function walkJsonPath(obj, path) {
 	const segments = parseJsonPath(path);
-	let current = [obj];
+	let current = [{
+		node: obj,
+		path: []
+	}];
 	for (const segment of segments) {
 		const next = [];
-		for (const node of current) {
+		for (const { node, path: nodePath } of current) {
 			if (node === null || node === void 0 || typeof node !== "object") continue;
 			switch (segment.type) {
 				case "property": {
 					const value = node[segment.key];
-					if (value !== void 0) next.push(value);
+					if (value !== void 0) next.push({
+						node: value,
+						path: [...nodePath, segment.key]
+					});
 					break;
 				}
 				case "index":
-					if (Array.isArray(node) && segment.index < node.length) next.push(node[segment.index]);
+					if (Array.isArray(node) && segment.index < node.length) next.push({
+						node: node[segment.index],
+						path: [...nodePath, segment.index]
+					});
 					break;
 				case "wildcard":
-					if (Array.isArray(node)) next.push(...node);
+					if (Array.isArray(node)) node.forEach((element, index) => {
+						next.push({
+							node: element,
+							path: [...nodePath, index]
+						});
+					});
 					break;
 			}
 		}
@@ -94,82 +117,38 @@ function jsonPathGet(obj, path) {
 	return current;
 }
 /**
-* Mutate all matching locations in an object in-place.
+* Resolve a JSONPath expression to the concrete paths of every existing match.
 *
 * @remarks
-* Walks to the parent(s) of the final segment, then sets the value
-* at each matching location. Only updates existing keys/indices;
-* does not create new properties or extend arrays. Returns the count
-* of locations actually updated.
+* Uses the same breadth-first expansion as {@link jsonPathGet}, but instead of
+* collecting the matched *values* it records the concrete `(string | number)[]`
+* path taken to reach each one. Wildcards and indices are materialized into the
+* numeric array index actually traversed, so the returned paths are directly
+* consumable by structural editors such as `jsonc-effect`'s `modify`, which
+* require a fully concrete path (no wildcards).
+*
+* Only existing locations are returned; nothing is created. A path with no
+* matches yields an empty array, and the empty path (`"$."`) yields a single
+* empty concrete path (the document root).
 *
-* @param obj - The object to modify in-place
+* @param obj - The object to query
 * @param path - JSONPath string (e.g., `"$.packages[*].version"`)
-* @param value - The value to set at each matching location
-* @returns The number of locations updated (0 if no matches or empty path)
+* @returns Array of concrete paths, each an array of string keys / numeric indices
 *
 * @example
 * ```typescript
-* import { jsonPathSet } from "../utils/jsonpath.js";
+* import { jsonPathResolve } from "../utils/jsonpath.js";
 *
-* const obj = { version: "1.0.0" };
-* const count = jsonPathSet(obj, "$.version", "2.0.0");
-* // count === 1, obj.version === "2.0.0"
+* const obj = { packages: [{ version: "1.0.0" }, { version: "2.0.0" }] };
+* const paths = jsonPathResolve(obj, "$.packages[*].version");
+* // [["packages", 0, "version"], ["packages", 1, "version"]]
 * ```
 *
 * @internal
 */
-function jsonPathSet(obj, path, value) {
-	const segments = parseJsonPath(path);
-	if (segments.length === 0) return 0;
-	const lastSegment = segments[segments.length - 1];
-	const parentSegments = segments.slice(0, -1);
-	let parents = [obj];
-	for (const segment of parentSegments) {
-		const next = [];
-		for (const node of parents) {
-			if (node === null || node === void 0 || typeof node !== "object") continue;
-			switch (segment.type) {
-				case "property": {
-					const child = node[segment.key];
-					if (child !== void 0) next.push(child);
-					break;
-				}
-				case "index":
-					if (Array.isArray(node) && segment.index < node.length) next.push(node[segment.index]);
-					break;
-				case "wildcard":
-					if (Array.isArray(node)) next.push(...node);
-					break;
-			}
-		}
-		parents = next;
-	}
-	let count = 0;
-	for (const parent of parents) {
-		if (parent === null || parent === void 0 || typeof parent !== "object") continue;
-		switch (lastSegment.type) {
-			case "property":
-				if (lastSegment.key in parent) {
-					parent[lastSegment.key] = value;
-					count++;
-				}
-				break;
-			case "index":
-				if (Array.isArray(parent) && lastSegment.index < parent.length) {
-					parent[lastSegment.index] = value;
-					count++;
-				}
-				break;
-			case "wildcard":
-				if (Array.isArray(parent)) for (let i = 0; i < parent.length; i++) {
-					parent[i] = value;
-					count++;
-				}
-				break;
-		}
-	}
-	return count;
+function jsonPathResolve(obj, path) {
+	return walkJsonPath(obj, path).map((entry) => entry.path);
 }
 
 //#endregion
-export { jsonPathGet, jsonPathSet, parseJsonPath };
+export { jsonPathGet, jsonPathResolve, parseJsonPath };

package/changesets/utils/version-files.js

@@ -1,9 +1,10 @@
 import { LegacyVersionFilesSchema } from "../schemas/version-files.js";
-import { jsonPathGet, jsonPathSet } from "./jsonpath.js";
-import { Schema } from "effect";
+import { jsonPathGet, jsonPathResolve, parseJsonPath } from "./jsonpath.js";
+import { Effect, Schema } from "effect";
 import { readFileSync, writeFileSync } from "node:fs";
 import { join, relative, resolve } from "node:path";
 import { globSync } from "tinyglobby";
+import { applyEdits, modify, parse } from "jsonc-effect";
 
 //#region src/changesets/utils/version-files.ts
 /**
@@ -193,31 +194,39 @@ var VersionFiles = class VersionFiles {
 		return content.match(/^(\s+)"/m)?.[1] ?? "  ";
 	}
 	/**
-	* Update JSON file at specified JSONPath locations.
+	* Update a JSON (or JSONC) file at specified JSONPath locations,
+	* preserving the original formatting byte-for-byte.
 	*
 	* @remarks
-	* Reads the file, detects its indentation style and trailing newline
-	* preference, applies all JSONPath updates via {@link jsonPathSet},
-	* and writes the result back preserving the original formatting.
-	* Returns `undefined` if no JSONPath locations matched (no write occurs).
+	* The write is performed with `jsonc-effect`'s format-preserving
+	* `modify`/`applyEdits` rather than a `JSON.parse`/`JSON.stringify`
+	* round-trip (which always explodes inline arrays one-element-per-line and
+	* drops comments). Each JSONPath expression is resolved to concrete
+	* `(string | number)[]` paths against the parsed document, and each
+	* concrete path becomes a minimal text edit that touches only the target
+	* value's span — so inline arrays, comments,
+	* indentation, and the trailing-newline preference all survive; a one-line
+	* version bump produces a one-line diff.
+	*
+	* Insertion semantics: a concrete, wildcard-free JSONPath whose leaf
+	* property does not exist yet is inserted after the last sibling using the
+	* document's detected indent (the one case where indent detection still
+	* matters). Wildcard expressions only ever update existing matches. Returns
+	* `undefined` (no write) when nothing was updated or inserted.
 	*
 	* @param filePath - Absolute path to the JSON file
 	* @param jsonPaths - JSONPath expressions to update
 	* @param version - New version string
 	* @returns Update result, or `undefined` if no changes were made
+	*
+	* @see {@link jsonPathResolve} for concrete-path enumeration
+	* @see {@link VersionFiles.applyVersionEdit} for the per-path edit
 	*/
 	static updateFile(filePath, jsonPaths, version) {
-		const content = readFileSync(filePath, "utf-8");
-		const indent = VersionFiles.detectIndent(content);
-		const trailingNewline = content.endsWith("\n");
-		const obj = JSON.parse(content);
-		const previousValues = jsonPaths.flatMap((jp) => jsonPathGet(obj, jp));
-		let totalUpdated = 0;
-		for (const jp of jsonPaths) totalUpdated += jsonPathSet(obj, jp, version);
-		if (totalUpdated === 0) return;
-		let output = JSON.stringify(obj, null, indent);
-		if (trailingNewline) output += "\n";
-		writeFileSync(filePath, output, "utf-8");
+		const original = readFileSync(filePath, "utf-8");
+		const { content, previousValues, totalChanged } = VersionFiles.computeUpdate(original, jsonPaths, version);
+		if (totalChanged === 0) return;
+		writeFileSync(filePath, content, "utf-8");
 		return {
 			filePath,
 			jsonPaths,
@@ -226,6 +235,83 @@ var VersionFiles = class VersionFiles {
 		};
 	}
 	/**
+	* Compute the full update for a document without touching the filesystem:
+	* the edited content, the previous values at every matched path, and how
+	* many locations actually changed.
+	*
+	* @remarks
+	* This is the single decision path shared by {@link VersionFiles.updateFile}
+	* and the dry-run branches of the two process methods, so a preview reports
+	* exactly the files a real run would write — including pending inserts of a
+	* not-yet-existing wildcard-free leaf, and excluding same-value no-ops.
+	*
+	* @param original - Document text as read from disk
+	* @param jsonPaths - JSONPath expressions to update
+	* @param version - New version string
+	* @returns The updated content, previous values, and changed-location count
+	*/
+	static computeUpdate(original, jsonPaths, version) {
+		let content = original;
+		const obj = Effect.runSync(parse(content));
+		const previousValues = jsonPaths.flatMap((jp) => jsonPathGet(obj, jp));
+		const indent = VersionFiles.detectIndent(content);
+		const eol = content.includes("\r\n") ? "\r\n" : "\n";
+		let totalChanged = 0;
+		for (const jp of jsonPaths) {
+			const segments = parseJsonPath(jp);
+			if (segments.length === 0) continue;
+			const hasWildcard = segments.some((segment) => segment.type === "wildcard");
+			let concretePaths;
+			if (hasWildcard) concretePaths = jsonPathResolve(obj, jp);
+			else {
+				const direct = segments.map((segment) => segment.type === "property" ? segment.key : segment.index);
+				concretePaths = jsonPathResolve(obj, jp).length > 0 || typeof direct[direct.length - 1] === "string" ? [direct] : [];
+			}
+			for (const concretePath of concretePaths) {
+				const updated = VersionFiles.applyVersionEdit(content, concretePath, version, indent, eol);
+				if (updated !== void 0) {
+					content = updated;
+					totalChanged += 1;
+				}
+			}
+		}
+		return {
+			content,
+			previousValues,
+			totalChanged
+		};
+	}
+	/**
+	* Compute the format-preserving edit for a single concrete path, returning
+	* the updated document, or `undefined` when nothing changed.
+	*
+	* @remarks
+	* Delegates to `jsonc-effect`'s {@link modify} + {@link applyEdits}
+	* (requires `jsonc-effect >= 0.3.1`, whose edit spans touch only the target
+	* value), so every other byte of the document is preserved. When the leaf
+	* of a wildcard-free path does not exist, `modify` inserts the property
+	* after the last sibling using the supplied formatting options — the only
+	* case where the detected indent matters. A path whose parent is missing or
+	* not an object cannot be navigated; the resulting modification error is
+	* caught and reported as "no change" so the file is left alone.
+	*
+	* @param content - Current document text
+	* @param concretePath - A wildcard-free `(string | number)[]` path
+	* @param version - New version string
+	* @param indentUnit - One indentation level, for inserted text
+	* @param eol - End-of-line sequence, for inserted text
+	* @returns The updated document, or `undefined` if the path was unchanged
+	*/
+	static applyVersionEdit(content, concretePath, version, indentUnit, eol) {
+		const insertSpaces = !indentUnit.includes("	");
+		const program = modify(content, [...concretePath], version, { formattingOptions: {
+			insertSpaces,
+			tabSize: insertSpaces ? indentUnit.length : 1,
+			eol
+		} }).pipe(Effect.flatMap((edits) => applyEdits(content, edits)), Effect.map((updated) => updated === content ? void 0 : updated), Effect.catchTag("JsoncModificationError", () => Effect.succeed(void 0)));
+		return Effect.runSync(program);
+	}
+	/**
 	* Orchestrate the full version file update flow.
 	*
 	* @remarks
@@ -251,9 +337,8 @@ var VersionFiles = class VersionFiles {
 			try {
 				if (dryRun) {
 					const content = readFileSync(filePath, "utf-8");
-					const obj = JSON.parse(content);
-					const previousValues = jsonPaths.flatMap((jp) => jsonPathGet(obj, jp));
-					if (previousValues.length > 0) updates.push({
+					const { previousValues, totalChanged } = VersionFiles.computeUpdate(content, jsonPaths, version);
+					if (totalChanged > 0) updates.push({
 						filePath,
 						jsonPaths,
 						version,
@@ -297,9 +382,8 @@ var VersionFiles = class VersionFiles {
 			for (const filePath of vf.matchedFiles) try {
 				if (dryRun) {
 					const content = readFileSync(filePath, "utf-8");
-					const obj = JSON.parse(content);
-					const previousValues = jsonPaths.flatMap((jp) => jsonPathGet(obj, jp));
-					if (previousValues.length > 0) updates.push({
+					const { previousValues, totalChanged } = VersionFiles.computeUpdate(content, jsonPaths, scope.version);
+					if (totalChanged > 0) updates.push({
 						filePath,
 						jsonPaths,
 						version: scope.version,

package/index.d.ts

@@ -4848,20 +4848,74 @@ declare class VersionFiles {
    */
   static detectIndent(content: string): string;
   /**
-   * Update JSON file at specified JSONPath locations.
+   * Update a JSON (or JSONC) file at specified JSONPath locations,
+   * preserving the original formatting byte-for-byte.
    *
    * @remarks
-   * Reads the file, detects its indentation style and trailing newline
-   * preference, applies all JSONPath updates via {@link jsonPathSet},
-   * and writes the result back preserving the original formatting.
-   * Returns `undefined` if no JSONPath locations matched (no write occurs).
+   * The write is performed with `jsonc-effect`'s format-preserving
+   * `modify`/`applyEdits` rather than a `JSON.parse`/`JSON.stringify`
+   * round-trip (which always explodes inline arrays one-element-per-line and
+   * drops comments). Each JSONPath expression is resolved to concrete
+   * `(string | number)[]` paths against the parsed document, and each
+   * concrete path becomes a minimal text edit that touches only the target
+   * value's span — so inline arrays, comments,
+   * indentation, and the trailing-newline preference all survive; a one-line
+   * version bump produces a one-line diff.
+   *
+   * Insertion semantics: a concrete, wildcard-free JSONPath whose leaf
+   * property does not exist yet is inserted after the last sibling using the
+   * document's detected indent (the one case where indent detection still
+   * matters). Wildcard expressions only ever update existing matches. Returns
+   * `undefined` (no write) when nothing was updated or inserted.
    *
    * @param filePath - Absolute path to the JSON file
    * @param jsonPaths - JSONPath expressions to update
    * @param version - New version string
    * @returns Update result, or `undefined` if no changes were made
+   *
+   * @see {@link jsonPathResolve} for concrete-path enumeration
+   * @see {@link VersionFiles.applyVersionEdit} for the per-path edit
    */
   static updateFile(filePath: string, jsonPaths: readonly string[], version: string): VersionFileUpdate | undefined;
+  /**
+   * Compute the full update for a document without touching the filesystem:
+   * the edited content, the previous values at every matched path, and how
+   * many locations actually changed.
+   *
+   * @remarks
+   * This is the single decision path shared by {@link VersionFiles.updateFile}
+   * and the dry-run branches of the two process methods, so a preview reports
+   * exactly the files a real run would write — including pending inserts of a
+   * not-yet-existing wildcard-free leaf, and excluding same-value no-ops.
+   *
+   * @param original - Document text as read from disk
+   * @param jsonPaths - JSONPath expressions to update
+   * @param version - New version string
+   * @returns The updated content, previous values, and changed-location count
+   */
+  private static computeUpdate;
+  /**
+   * Compute the format-preserving edit for a single concrete path, returning
+   * the updated document, or `undefined` when nothing changed.
+   *
+   * @remarks
+   * Delegates to `jsonc-effect`'s {@link modify} + {@link applyEdits}
+   * (requires `jsonc-effect >= 0.3.1`, whose edit spans touch only the target
+   * value), so every other byte of the document is preserved. When the leaf
+   * of a wildcard-free path does not exist, `modify` inserts the property
+   * after the last sibling using the supplied formatting options — the only
+   * case where the detected indent matters. A path whose parent is missing or
+   * not an object cannot be navigated; the resulting modification error is
+   * caught and reported as "no change" so the file is left alone.
+   *
+   * @param content - Current document text
+   * @param concretePath - A wildcard-free `(string | number)[]` path
+   * @param version - New version string
+   * @param indentUnit - One indentation level, for inserted text
+   * @param eol - End-of-line sequence, for inserted text
+   * @returns The updated document, or `undefined` if the path was unchanged
+   */
+  private static applyVersionEdit;
   /**
    * Orchestrate the full version file update flow.
    *

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@savvy-web/silk-effects",
-	"version": "3.0.1",
+	"version": "3.0.3",
 	"private": false,
 	"description": "Shared Effect library for Silk Suite conventions",
 	"homepage": "https://github.com/savvy-web/systems/tree/main/packages/silk-effects",
@@ -33,10 +33,10 @@
 		"@changesets/get-github-info": "^1.0.0-next.3",
 		"@changesets/get-release-plan": "^5.0.0-next.7",
 		"@manypkg/get-packages": "^3.1.0",
-		"jsonc-effect": "^0.3.0",
+		"jsonc-effect": "^0.3.1",
 		"mdast-util-heading-range": "^4.0.0",
 		"mdast-util-to-string": "^4.0.0",
-		"prettier": "^3.8.4",
+		"prettier": "^3.9.4",
 		"remark-gfm": "^4.0.1",
 		"remark-parse": "^11.0.0",
 		"remark-stringify": "^11.0.0",
@@ -47,9 +47,9 @@
 		"unified": "^11.0.5",
 		"unified-lint-rule": "^3.0.1",
 		"unist-util-visit": "^5.1.0",
-		"workspaces-effect": "^2.0.1",
+		"workspaces-effect": "^2.0.2",
 		"yaml": "^2.9.0",
-		"yaml-effect": "^0.7.0",
+		"yaml-effect": "^0.7.2",
 		"yaml-lint": "^1.7.0"
 	},
 	"peerDependencies": {