json5-manifest-sync 0.3.5 → 0.3.7

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to this project are documented in this file.
 
+## [0.3.7] - 2026-11-09
+
+### Added
+
+- Added a read-only `--check` mode for validating manifest synchronization in CI.
+
+## [0.3.6] - 2026-11-09
+
+### Changed
+
+- Reframed the README introduction around the documented companion-manifest use case.
+
 ## [0.3.5] - 2026-11-09
 
 ### Changed

package/README.md

@@ -1,8 +1,8 @@
 # json5-manifest-sync
 
-Document your npm package manifest with comments in a companion `package.json5`, then sync it with the standard `package.json` expected by npm and other tools. Choose either file as the source of truth for manifest values; `package.json` always remains valid strict JSON.
+Add comments to your package manifest in a companion `package.json5`, then sync it with the standard `package.json` expected by npm and other tools. This works whether you use pnpm, which supports `package.json5` natively, or simply want a documented manifest while retaining compatibility with tools that require `package.json`. Choose either file as the source of truth for manifest values; `package.json` remains valid strict JSON.
 
-For example, document dependencies in `package.json5` and generate `package.json` from it:
+For example, document dependencies in `package.json5` and generate `package.json` for npm or other tools that require it:
 
 <!-- prettier-ignore -->
 ```json5
@@ -157,6 +157,14 @@ Choose a blank-comment mode with one of the following:
 
 To warn after sync when blank `//` placeholders remain, add `--warn-blank-comments`. That warning applies to `preserve` and `fill`; `remove` strips those lines.
 
+Use `--check` to compare each selected source manifest's generated output with its counterpart without writing files. It exits with status `1` if an output is missing or differs, and `0` if all checked outputs are current. It respects `--source` and `--blank-comments`; in the default `package.json` source direction, packages without a `package.json5` companion are skipped, as they are during sync.
+
+For CI, run the check directly:
+
+```bash
+npx --yes --package=json5-manifest-sync json5-manifest-sync --check
+```
+
 ### Pre-commit synchronization
 
 To keep both manifests aligned in each commit, run `json5-manifest-sync` from a Git pre-commit hook after manifest changes. It uses `JSON5_MANIFEST_SYNC_SOURCE_OF_TRUTH` or the `--source` option to choose the authoritative file. Make sure the hook stages the generated counterpart as well; if you use partial staging, stage only the file generated by the sync rather than blindly adding both manifests.

package/dist/json5-manifest-sync.d.ts

@@ -66,7 +66,7 @@ export declare function syncJson5(raw: string, source: Record<string, unknown>,
  *
  * @param args - Optional CLI arguments (defaults to process argv slice)
  */
-export declare function runCli(args?: string[]): void;
+export declare function runCli(args?: string[]): number;
 /**
  * Determines whether this module is being executed as a CLI entrypoint.
  *

package/dist/json5-manifest-sync.js

@@ -369,6 +369,7 @@ export function runCli(args = process.argv.slice(2)) {
     // Parse CLI flags for options
     let blankCommentMode = "preserve";
     let warnOnBlankComments = false;
+    let checkOnly = false;
     const dotenvPath = path.join(rootDir, ".env");
     const dotenvValues = fs.existsSync(dotenvPath)
         ? parseDotenv(fs.readFileSync(dotenvPath))
@@ -405,19 +406,23 @@ export function runCli(args = process.argv.slice(2)) {
             }
             else {
                 console.error(`Invalid source "${v}". Use --source=${manifestSourceOptions.join(" or --source=")}.`);
-                return;
+                return 2;
             }
         }
         else if (arg === "--warn-blank-comments") {
             warnOnBlankComments = true;
         }
+        else if (arg === "--check") {
+            checkOnly = true;
+        }
     }
     const configuredSourceValue = sourceOverride ?? configuredSource;
     if (!isManifestSource(configuredSourceValue)) {
         console.error(`Invalid JSON5_MANIFEST_SYNC_SOURCE_OF_TRUTH "${configuredSourceValue}". Use ${manifestSourceOptions.join(" or ")}.`);
-        return;
+        return 2;
     }
     const source = configuredSourceValue;
+    let hasOutOfSyncManifest = false;
     const sourcePattern = source === "package.json" ? "**/package.json" : "**/package.json5";
     const sourcePaths = globSync(sourcePattern, {
         cwd: rootDir,
@@ -446,10 +451,20 @@ export function runCli(args = process.argv.slice(2)) {
             const updated = syncJson5(rawJson5, sourceJson, {
                 blankCommentMode,
             });
-            const changed = writeFileIfChanged(json5Path, updated);
-            console.info(changed
-                ? `✅ Synced ${relPath} → ${path.basename(json5Path)}`
-                : `⏭️ Unchanged ${relPath} → ${path.basename(json5Path)}`);
+            if (checkOnly) {
+                const inSync = rawJson5 === updated;
+                if (!inSync)
+                    hasOutOfSyncManifest = true;
+                console.info(inSync
+                    ? `✅ In sync ${relPath} → ${path.basename(json5Path)}`
+                    : `❌ Out of sync ${relPath} → ${path.basename(json5Path)}`);
+            }
+            else {
+                const changed = writeFileIfChanged(json5Path, updated);
+                console.info(changed
+                    ? `✅ Synced ${relPath} → ${path.basename(json5Path)}`
+                    : `⏭️ Unchanged ${relPath} → ${path.basename(json5Path)}`);
+            }
             if (warnOnBlankComments && blankCommentMode !== "remove") {
                 warnAboutBlankComments(json5Path, collectBlankCommentLineNumbers(updated));
             }
@@ -457,12 +472,26 @@ export function runCli(args = process.argv.slice(2)) {
         else {
             const sourceJson5 = JSON5.parse(fs.readFileSync(json5Path, "utf8"));
             const updated = `${JSON.stringify(sourceJson5, null, 2)}\n`;
-            const changed = writeFileIfChanged(packageJsonPath, updated);
-            console.info(changed
-                ? `✅ Synced ${path.basename(json5Path)} → ${relPath}`
-                : `⏭️ Unchanged ${path.basename(json5Path)} → ${relPath}`);
+            const current = fs.existsSync(packageJsonPath)
+                ? fs.readFileSync(packageJsonPath, "utf8")
+                : undefined;
+            if (checkOnly) {
+                const inSync = current === updated;
+                if (!inSync)
+                    hasOutOfSyncManifest = true;
+                console.info(inSync
+                    ? `✅ In sync ${path.basename(json5Path)} → ${relPath}`
+                    : `❌ Out of sync ${path.basename(json5Path)} → ${relPath}`);
+            }
+            else {
+                const changed = writeFileIfChanged(packageJsonPath, updated);
+                console.info(changed
+                    ? `✅ Synced ${path.basename(json5Path)} → ${relPath}`
+                    : `⏭️ Unchanged ${path.basename(json5Path)} → ${relPath}`);
+            }
         }
     }
+    return checkOnly && hasOutOfSyncManifest ? 1 : 0;
 }
 /**
  * Determines whether this module is being executed as a CLI entrypoint.
@@ -488,5 +517,5 @@ export function isCliInvocation(argv1 = process.argv[1], moduleUrl = import.meta
     }
 }
 if (isCliInvocation()) {
-    runCli();
+    process.exitCode = runCli();
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "json5-manifest-sync",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "description": "Sync package.json and package.json5 manifests in either direction, preserving JSON5 comments where possible.",
   "author": {
     "name": "Bradley Baysinger",