json5-manifest-sync 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 All notable changes to this project are documented in this file.
 
+## [0.3.0] - 2026-11-02
+
+### Added
+
+- Added bidirectional synchronization with configurable `package.json` or `package.json5` source of truth.
+- Added `JSON5_MANIFEST_SYNC_SOURCE_OF_TRUTH` support in `.env` and the process environment.
+- Added JSON5-only project discovery and generation of a strict-JSON `package.json`.
+
+### Fixed
+
+- Report invalid source-of-truth environment values with a descriptive error.
+- Skip writes when synchronization produces unchanged content.
+
+## [0.2.2] - 2026-05-13
+
+### Changed
+
+- Refined README wording so the npm package page explains sync behavior, blank-comment modes, and current limitations more clearly.
+- Added npm package discoverability improvements, including package metadata fields and a top-of-page npm badge/link.
+
 ## [0.2.1] - 2026-05-06
 
 ### Changed

package/README.md

@@ -1,6 +1,8 @@
 # json5-manifest-sync
 
-Keep a documented `package.json5` in sync with the real `package.json` used by Node and package managers, including `version` updates.
+Keep `package.json` and a documented `package.json5` in sync. Choose either file as the source of truth: maintain comments in `package.json5` and generate strict JSON for tools that require it, or update the JSON5 companion from `package.json`.
+
+pnpm supports `package.json5` natively, but other tools in a project’s scripts, CI/CD, publishing, or deployment workflows may still expect `package.json`. When both files exist, pnpm prefers `package.json`; it reads `package.json5` natively when `package.json` is absent. This tool bridges mixed toolchains by keeping both manifests synchronized in either direction.
 
 ## Quick Start
 
@@ -30,27 +32,31 @@ npm run sync:json5
 
 `package.json` is arguably the most important file in most JavaScript/TypeScript repositories. It drives install behavior, scripts, dependency policy, packaging, and release workflows—so it deserves clear inline documentation.
 
-At the same time, Node/npm/pnpm/yarn do not treat `package.json5` as a package manifest source. A JSON5 file can be great for human-readable documentation, but tooling still requires `package.json`.
+Some tooling does not treat `package.json5` as a package manifest source. While pnpm supports it in supported workflows, npm, Node-based tooling, legacy CI/CD environments, deployment systems, release tooling, and other ecosystem integrations may still require the conventional `package.json` filename. A companion `package.json5` approach provides documented manifests without giving up broad compatibility.
+
+This is also why the long-running Yarn Berry discussion about comment-friendly manifests is relevant here: [yarnpkg/berry#241](https://github.com/yarnpkg/berry/issues/241) describes the same underlying need, along with the ecosystem compatibility constraints that make a companion `package.json5` approach useful today.
 
 > [!NOTE]
-> It would be great to see first-class support for JSON5-style manifests in npm/tooling over time, but today this project provides a practical bridge.
+> pnpm's native `package.json5` support is useful when pnpm controls the workflow, but it does not make `package.json5` universally recognized across npm, CI/CD, deployment, release, and other JavaScript tooling. This project keeps `package.json` available for compatibility while providing a documented companion file.
 
-This tool solves that gap by letting you maintain both:
+The source of truth is configurable. By default:
 
-- `package.json` as the canonical, machine-consumed manifest
-- `package.json5` as the human-documented companion file
+- `package.json` is authoritative for manifest values.
+- `package.json5` is authoritative for comments; values are synchronized from `package.json` while mapped `//` comments are preserved where possible.
 
-Then it synchronizes `package.json5` from `package.json` while preserving mapped `//` comments where possible.
-When values like `version`, `scripts`, or dependency versions change in `package.json`, those updates are propagated into `package.json5`.
+Alternatively, make `package.json5` authoritative for values and generate a strict `package.json` for tools that need it. In this direction, comments remain in `package.json5`; they are not copied to `package.json`.
 
 ## What it does
 
 - Finds `package.json` files recursively (excluding `node_modules`)
 - Skips paths ignored by your root `.gitignore`
-- For each matching `package.json5`, rewrites values from canonical `package.json` (including `version`, scripts, dependencies, and other manifest fields)
+- Synchronizes each matching `package.json` / `package.json5` pair in either direction
+- By default, rewrites `package.json5` values from `package.json` (including `version`, scripts, dependencies, and other manifest fields)
+- With `--source=package.json5`, parses JSON5 and creates or updates a strict-JSON `package.json`
 - Preserves/migrates mapped `//` comments for keys and supported array items
 - Supports three blank-comment modes: `preserve`, `fill`, and `remove`
 - Writes stable JSON5 formatting with trailing commas for cleaner diffs
+- Keeps a documented `package.json5` synchronized while retaining `package.json` compatibility for npm, legacy CI/CD, and other tooling that requires it
 
 ### Current limitations
 
@@ -129,6 +135,29 @@ For the current full output style, see this repo's live example: [`package.json5
 
 By default, the tool runs with `--blank-comments=preserve`.
 
+Choose which manifest is authoritative with:
+
+- `--source=package.json` (default): update `package.json5` from `package.json`, preserving mapped JSON5 comments.
+- `--source=package.json5`: create or update `package.json` from `package.json5`; comments remain only in the JSON5 file.
+
+To retain the choice across runs, set `JSON5_MANIFEST_SYNC_SOURCE_OF_TRUTH` in the project-root `.env` file:
+
+```dotenv
+JSON5_MANIFEST_SYNC_SOURCE_OF_TRUTH=package.json5
+```
+
+An existing shell environment variable takes precedence over `.env`, and `--source=...` takes precedence over both. If the setting is omitted, the default remains `package.json`.
+
+For a project that has only `package.json5`, run the tool through `npx` (or install it globally) to generate the initial `package.json`—no pnpm installation is needed:
+
+```bash
+npx --yes --package=json5-manifest-sync json5-manifest-sync --source=package.json5
+```
+
+You cannot use a local `npm run` script or install this tool as a local dev dependency until `package.json` exists. Once generated, npm and other strict-JSON tools can use it. Note that commands such as `npm install` update `package.json`; reconcile those changes back into `package.json5` with the default `--source=package.json` mode before regenerating JSON from the JSON5 source, or those updates could be overwritten.
+
+Because pnpm prefers `package.json` when both files exist, it will read the generated JSON copy in that setup; it reads `package.json5` directly only when `package.json` is absent.
+
 Choose a blank-comment mode with one of the following:
 
 - `--blank-comments=preserve`
@@ -161,7 +190,7 @@ Example prompt:
 ```json
 {
   "dependencies": {
-    "json5-manifest-sync": "^0.1.3"
+    "json5-manifest-sync": "^0.3.0"
   }
 }
 ```

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

@@ -2,11 +2,11 @@
 /**
  * JSON5 Package Synchronization Tool
  *
- * Synchronizes package.json5 files with their canonical package.json counterparts.
+ * Synchronizes paired package.json and package.json5 manifests in either direction.
  *
- * Source of truth: package.json (parsed as strict JSON).
- * Output: package.json5 rewritten with stable formatting and with *some* `//` comments
- * preserved/migrated onto the corresponding keys/items.
+ * By default, package.json is the source of manifest values and package.json5 is
+ * rewritten with stable formatting and with *some* `//` comments preserved/migrated.
+ * The CLI can instead use package.json5 as the source and generate package.json.
  *
  * Important: this script does NOT attempt to preserve arbitrary formatting (blank
  * lines, exact indentation, key ordering, etc.). It regenerates the JSON5 structure
@@ -27,6 +27,8 @@
  *   objects/numbers will serialize correctly but per-item comment preservation is limited.
  */
 export type BlankCommentMode = "preserve" | "fill" | "remove";
+export declare const manifestSourceOptions: readonly ["package.json", "package.json5"];
+export type ManifestSource = (typeof manifestSourceOptions)[number];
 export type SyncOptions = {
     /**
      * Controls how blank comment lines (`//`) are handled.
@@ -59,8 +61,8 @@ export declare function syncJson5(raw: string, source: Record<string, unknown>,
 /**
  * CLI entrypoint.
  *
- * Scans from the current working directory and synchronizes any
- * `package.json5` files that have a sibling `package.json`.
+ * Scans from the current working directory and synchronizes paired
+ * `package.json` and `package.json5` files in the selected direction.
  *
  * @param args - Optional CLI arguments (defaults to process argv slice)
  */

package/dist/json5-manifest-sync.js

@@ -2,8 +2,25 @@
 import fs from "fs";
 import path from "path";
 import { fileURLToPath } from "url";
+import JSON5 from "json5";
+import { parse as parseDotenv } from "dotenv";
 import { sync as globSync } from "glob";
 import ignore from "ignore";
+export const manifestSourceOptions = ["package.json", "package.json5"];
+function isManifestSource(value) {
+    return manifestSourceOptions.includes(value);
+}
+function describeManifestSources() {
+    return manifestSourceOptions.map((source) => `"${source}"`).join(" or ");
+}
+function writeFileIfChanged(filePath, content) {
+    if (fs.existsSync(filePath) &&
+        fs.readFileSync(filePath, "utf8") === content) {
+        return false;
+    }
+    fs.writeFileSync(filePath, content);
+    return true;
+}
 function isBlankCommentLine(line) {
     return /^\s*\/\/\s*$/.test(line);
 }
@@ -328,16 +345,16 @@ export function syncJson5(raw, source, options = { blankCommentMode: "preserve"
 }
 // 🔁 Main Execution Runner
 //
-// This section handles the file discovery and processing logic:
-// - Finds all package.json files in the project (excluding node_modules)
-// - Checks for corresponding package.json5 files
+// This section handles source-specific file discovery and processing:
+// - Finds the selected manifest type in the project (excluding node_modules)
+// - Checks for the counterpart when package.json is the source
 // - Applies root .gitignore rules to skip excluded files
 // - Performs synchronization for each valid pair
 /**
  * CLI entrypoint.
  *
- * Scans from the current working directory and synchronizes any
- * `package.json5` files that have a sibling `package.json`.
+ * Scans from the current working directory and synchronizes paired
+ * `package.json` and `package.json5` files in the selected direction.
  *
  * @param args - Optional CLI arguments (defaults to process argv slice)
  */
@@ -349,15 +366,31 @@ export function runCli(args = process.argv.slice(2)) {
     if (fs.existsSync(gitignorePath)) {
         ig.add(fs.readFileSync(gitignorePath, "utf8"));
     }
-    // Find all package.json files recursively, excluding node_modules
-    const packageJsonPaths = globSync("**/package.json", {
-        cwd: rootDir,
-        ignore: ["**/node_modules/**"],
-        absolute: true,
-    });
     // Parse CLI flags for options
     let blankCommentMode = "preserve";
     let warnOnBlankComments = false;
+    const dotenvPath = path.join(rootDir, ".env");
+    const dotenvValues = fs.existsSync(dotenvPath)
+        ? parseDotenv(fs.readFileSync(dotenvPath))
+        : {};
+    const sourceSettings = [
+        {
+            value: dotenvValues.JSON5_MANIFEST_SYNC_SOURCE_OF_TRUTH,
+            location: ".env",
+        },
+        {
+            value: process.env.JSON5_MANIFEST_SYNC_SOURCE_OF_TRUTH,
+            location: "the process environment",
+        },
+    ];
+    const invalidSourceSetting = sourceSettings.find(({ value }) => value !== undefined && !isManifestSource(value));
+    if (invalidSourceSetting) {
+        throw new Error(`Invalid JSON5_MANIFEST_SYNC_SOURCE_OF_TRUTH in ${invalidSourceSetting.location}: "${invalidSourceSetting.value}". Expected ${describeManifestSources()}.`);
+    }
+    const configuredSource = process.env.JSON5_MANIFEST_SYNC_SOURCE_OF_TRUTH ??
+        dotenvValues.JSON5_MANIFEST_SYNC_SOURCE_OF_TRUTH ??
+        "package.json";
+    let sourceOverride;
     for (const arg of args) {
         if (arg.startsWith("--blank-comments=")) {
             const v = arg.split("=", 2)[1]?.toLowerCase();
@@ -365,33 +398,69 @@ export function runCli(args = process.argv.slice(2)) {
                 blankCommentMode = v;
             }
         }
+        else if (arg.startsWith("--source=")) {
+            const v = arg.slice("--source=".length);
+            if (isManifestSource(v)) {
+                sourceOverride = v;
+            }
+            else {
+                console.error(`Invalid source "${v}". Use --source=${manifestSourceOptions.join(" or --source=")}.`);
+                return;
+            }
+        }
         else if (arg === "--warn-blank-comments") {
             warnOnBlankComments = true;
         }
     }
-    // Process each package.json to sync with its package.json5 counterpart
-    for (const packageJsonPath of packageJsonPaths) {
-        const relPath = path.relative(rootDir, packageJsonPath);
+    const configuredSourceValue = sourceOverride ?? configuredSource;
+    if (!isManifestSource(configuredSourceValue)) {
+        console.error(`Invalid JSON5_MANIFEST_SYNC_SOURCE_OF_TRUTH "${configuredSourceValue}". Use ${manifestSourceOptions.join(" or ")}.`);
+        return;
+    }
+    const source = configuredSourceValue;
+    const sourcePattern = source === "package.json" ? "**/package.json" : "**/package.json5";
+    const sourcePaths = globSync(sourcePattern, {
+        cwd: rootDir,
+        ignore: ["**/node_modules/**"],
+        absolute: true,
+    });
+    // Process each manifest using the selected source of truth.
+    for (const sourcePath of sourcePaths) {
+        const relPath = path.relative(rootDir, sourcePath);
         // Skip files that match gitignore patterns
         if (ig.ignores(relPath))
             continue;
-        const json5Path = packageJsonPath + "5"; // package.json5
-        // Skip if no corresponding package.json5 exists
-        if (!fs.existsSync(json5Path)) {
+        const packageJsonPath = source === "package.json"
+            ? sourcePath
+            : path.join(path.dirname(sourcePath), "package.json");
+        const json5Path = source === "package.json" ? `${sourcePath}5` : sourcePath;
+        // The default direction requires an existing JSON5 companion. In the
+        // reverse direction, package.json is created when it does not exist.
+        if (source === "package.json" && !fs.existsSync(json5Path)) {
             console.info(`⏩ Skipping ${relPath} — no package.json5 found`);
             continue;
         }
-        // Perform the synchronization
-        const rawJson5 = fs.readFileSync(json5Path, "utf8");
-        const sourceJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
-        const updated = syncJson5(rawJson5, sourceJson, {
-            blankCommentMode,
-        });
-        // Write the synchronized result
-        fs.writeFileSync(json5Path, updated);
-        console.info(`✅ Synced ${relPath} → ${path.basename(json5Path)}`);
-        if (warnOnBlankComments && blankCommentMode !== "remove") {
-            warnAboutBlankComments(json5Path, collectBlankCommentLineNumbers(updated));
+        if (source === "package.json") {
+            const rawJson5 = fs.readFileSync(json5Path, "utf8");
+            const sourceJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+            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 (warnOnBlankComments && blankCommentMode !== "remove") {
+                warnAboutBlankComments(json5Path, collectBlankCommentLineNumbers(updated));
+            }
+        }
+        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}`);
         }
     }
 }

package/package.json

@@ -1,11 +1,19 @@
 {
   "name": "json5-manifest-sync",
-  "version": "0.2.1",
-  "description": "Sync package.json5 files from canonical package.json while preserving key comments.",
+  "version": "0.3.0",
+  "description": "Sync package.json and package.json5 manifests in either direction, preserving JSON5 comments where possible.",
   "author": {
     "name": "Bradley Baysinger",
     "url": "https://github.com/BBaysinger"
   },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BBaysinger/json5-manifest-sync.git"
+  },
+  "homepage": "https://github.com/BBaysinger/json5-manifest-sync#readme",
+  "bugs": {
+    "url": "https://github.com/BBaysinger/json5-manifest-sync/issues"
+  },
   "type": "module",
   "main": "./dist/json5-manifest-sync.js",
   "types": "./dist/json5-manifest-sync.d.ts",
@@ -38,8 +46,10 @@
     "node": ">=18"
   },
   "dependencies": {
+    "dotenv": "^18.0.10",
     "glob": "^13.0.6",
-    "ignore": "^7.0.5"
+    "ignore": "^7.0.5",
+    "json5": "^2.2.3"
   },
   "devDependencies": {
     "@types/node": "^25.6.0",