json5-manifest-sync 0.2.2 → 0.3.1

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 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

package/README.md

@@ -1,15 +1,21 @@
 # json5-manifest-sync
 
-[![npm version](https://img.shields.io/npm/v/json5-manifest-sync)](https://www.npmjs.com/package/json5-manifest-sync)
+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`.
 
-Keep a documented `package.json5` in sync with the real `package.json` used by Node and package managers, including `version` updates.
+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
 
+Install with the package manager your project already uses:
+
 ```bash
 npm install --save-dev json5-manifest-sync
 ```
 
+```bash
+pnpm add --save-dev json5-manifest-sync
+```
+
 Add a script in your project's `package.json`:
 
 ```json
@@ -32,36 +38,45 @@ 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.
 
-There is also a long-running Stack Overflow discussion around the same practical question from the npm side: [How do I add comments to package.json for npm install?](https://stackoverflow.com/questions/14221579/how-do-i-add-comments-to-package-json-for-npm-install/79939348#79939348). It is a useful community reference for why teams keep reaching for comment-friendly manifest workflows even though `package.json` itself must remain strict JSON.
-
 > [!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 for this tool 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.
 
-It synchronizes `package.json5` from the canonical `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`.
+
+**pnpm consideration:** pnpm has no setting or environment variable to prefer `package.json5` when both files exist. The `--source` option and `JSON5_MANIFEST_SYNC_SOURCE_OF_TRUTH` variable configure only this tool; they do not change pnpm's selection. When the two manifests are synchronized, this is straightforward: pnpm reads `package.json`, whose values match `package.json5`. If JSON5 is your source of truth, run this tool with `--source=package.json5` before pnpm operations that need the latest values. Pnpm commands may update `package.json`, so reconcile those changes into `package.json5` before syncing from JSON5 again, or they may be overwritten. Removing `package.json` lets pnpm read `package.json5` directly, but may break Node, npm, or other tools that require `package.json`.
+
+For CI or other automated workflows where `package.json5` is authoritative, run the sync as a separate step before pnpm reads the manifest. A lifecycle hook such as `preinstall` may run too late, after pnpm has already selected `package.json`:
+
+```bash
+pnpm dlx json5-manifest-sync --source=package.json5
+pnpm install
+```
 
 ## 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` to keep blanks, `fill` to generate them, and `remove` to strip them
+- 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
 
 - Per-item comment preservation is most reliable for arrays of strings.
-- Arrays of objects or numbers still serialize correctly, but item-level comments are less reliable and may be dropped during sync.
+- Arrays of objects or numbers still serialize correctly, but item-level comments may be dropped.
 
 Repository: https://github.com/BBaysinger/json5-manifest-sync
 
@@ -71,18 +86,34 @@ Package: https://www.npmjs.com/package/json5-manifest-sync
 
 Bradley Baysinger ([@BBaysinger](https://github.com/BBaysinger))
 
-## Install from npm (recommended)
+## Install from the npm registry (recommended)
+
+Use the package manager already used by your project so its lockfile stays consistent.
+
+With npm:
 
 ```bash
 npm install --save-dev json5-manifest-sync
 ```
 
+With pnpm:
+
+```bash
+pnpm add --save-dev json5-manifest-sync
+```
+
 Global install (optional):
 
 ```bash
 npm install -g json5-manifest-sync
 ```
 
+Or with pnpm:
+
+```bash
+pnpm add --global json5-manifest-sync
+```
+
 ## Install from GitHub (alternative)
 
 Use this if you want an unreleased branch or tag:
@@ -134,6 +165,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`
@@ -142,6 +196,10 @@ 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.
 
+### 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.
+
 ### Formatting note
 
 Recommended: exclude `package.json5` from Prettier (for example via `.prettierignore`).
@@ -166,7 +224,7 @@ Example prompt:
 ```json
 {
   "dependencies": {
-    "json5-manifest-sync": "^0.2.2"
+    "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,7 +1,7 @@
 {
   "name": "json5-manifest-sync",
-  "version": "0.2.2",
-  "description": "Sync package.json5 files from canonical package.json while preserving key comments.",
+  "version": "0.3.1",
+  "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"
@@ -46,13 +46,15 @@
     "node": ">=18"
   },
   "dependencies": {
-    "glob": "^13.0.6",
-    "ignore": "^7.0.5"
+    "dotenv": "^18.0.10",
+    "glob": "^14.0.4",
+    "ignore": "^7.0.14",
+    "json5": "^2.2.3"
   },
   "devDependencies": {
-    "@types/node": "^25.6.0",
-    "prettier": "^3.8.3",
-    "typescript": "^6.0.3",
-    "vitest": "^4.1.5"
+    "@types/node": "^26.6.6",
+    "prettier": "^3.9.10",
+    "typescript": "^7.0.2",
+    "vitest": "^5.1.0"
   }
 }