json5-manifest-sync 0.1.3 → 0.2.0

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 All notable changes to this project are documented in this file.
 
+## [0.2.0] - 2026-05-06
+
+### Breaking Changes
+
+- The default blank-comment mode is now `preserve` instead of the previous placeholder-generating behavior. Existing users who want generated blank `//` lines must now pass `--blank-comments=fill`.
+
+### Changed
+
+- Replaced the old blank-comment toggle with `--blank-comments=preserve|fill|remove`.
+- Changed the default blank-comment mode to `preserve` so sync no longer introduces placeholder `//` lines unless requested.
+- Added `--warn-blank-comments` to warn after sync when blank `//` placeholders remain.
+
+## [0.1.3] - 2026-02-27
+
+### Added
+
+- Published `json5-manifest-sync` to the npm registry for direct install and global CLI usage.
+- Added npm-first installation guidance in the README, including optional global install instructions.
+
+### Changed
+
+- Updated README examples to use npm semver dependency references instead of GitHub-only install URLs.
+- Kept GitHub install instructions as an alternative path for unreleased branch/tag consumption.
+
 ## [0.1.2] - 2026-02-25
 
 ### Fixed

package/README.md

@@ -1,11 +1,11 @@
 # json5-manifest-sync
 
-Keep a documented `package.json5` in sync with the real `package.json` used by Node and package managers.
+Keep a documented `package.json5` in sync with the real `package.json` used by Node and package managers, including `version` updates.
 
 ## Quick Start
 
 ```bash
-npm install github:BBaysinger/json5-manifest-sync#v0.1.3
+npm install --save-dev json5-manifest-sync
 ```
 
 Add a script in your project's `package.json`:
@@ -41,37 +41,51 @@ This tool solves that gap by letting you maintain both:
 - `package.json5` as the human-documented companion file
 
 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`.
 
 ## 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`
+- For each matching `package.json5`, rewrites values from canonical `package.json` (including `version`, scripts, dependencies, and other manifest fields)
 - 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
 
+### 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 may be dropped.
+- Use `--blank-comments=preserve` to keep existing blank `//` lines without adding new ones.
+- Use `--blank-comments=fill` to add blank `//` placeholders where comments are omitted.
+- Use `--blank-comments=remove` to strip blank `//` lines from the output.
+
 Repository: https://github.com/BBaysinger/json5-manifest-sync
 
 ## Author
 
 Bradley Baysinger ([@BBaysinger](https://github.com/BBaysinger))
 
-## Install from GitHub
+## Install from npm (recommended)
+
+```bash
+npm install --save-dev json5-manifest-sync
+```
 
-Install from a tag (recommended):
+Global install (optional):
 
 ```bash
-npm install github:BBaysinger/json5-manifest-sync#v0.1.3
+npm install -g json5-manifest-sync
 ```
 
-Or from a branch during iteration:
+## Install from GitHub (alternative)
+
+Use this if you want an unreleased branch or tag:
 
 ```bash
 npm install github:BBaysinger/json5-manifest-sync#main
 ```
 
-Because this repo defines a `prepare` script, npm will build TypeScript during git-based install.
-
 ## Use in a project
 
 Add a script in your consuming project's `package.json`:
@@ -113,9 +127,15 @@ For the current full output style, see this repo's live example: [`package.json5
 
 ### Options
 
-- `--no-empty-comment` or `--no-empty-comments`
-- `--empty-comment=false`
-- env var: `SYNC_JSON5_ADD_EMPTY_COMMENT=false`
+By default, the tool runs with `--blank-comments=preserve`.
+
+Choose a blank-comment mode with one of the following:
+
+- `--blank-comments=preserve`
+- `--blank-comments=fill`
+- `--blank-comments=remove`
+
+To warn after sync when blank `//` placeholders remain, add `--warn-blank-comments`. That warning applies to `preserve` and `fill`; `remove` strips those lines.
 
 ### Formatting note
 
@@ -126,12 +146,22 @@ Prettier's JSON5 formatter can remove quotes from valid keys, which makes `packa
 > [!NOTE]
 > It would be nice if Prettier provided an option to preserve quoted keys in JSON5.
 
+### AI assist tip
+
+After running `sync:json5`, you can ask an AI coding assistant to fill placeholder comment lines.
+
+If you use this repo's `precommit` workflow, it warns when `package.json5` still contains blank `//` placeholder comments. Suppress just that warning for a given run with `npm run precommit -- --suppress-blank-comment-warning`.
+
+Example prompt:
+
+> "Complete empty `//` comment lines in `package.json5` with concise, field-specific comments."
+
 ## Example dependency block in consumer
 
 ```json
 {
   "dependencies": {
-    "json5-manifest-sync": "github:BBaysinger/json5-manifest-sync#v0.1.3"
+    "json5-manifest-sync": "^0.1.3"
   }
 }
 ```

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

@@ -26,20 +26,18 @@
  * - Array item comment mapping is primarily intended for arrays of strings; arrays of
  *   objects/numbers will serialize correctly but per-item comment preservation is limited.
  */
+export type BlankCommentMode = "preserve" | "fill" | "remove";
 export type SyncOptions = {
     /**
-     * When true, insert a blank comment line (`//`) before any key that has no
-     * preceding comment captured from the existing JSON5. This helps visually
-     * separate entries like:
+     * Controls how blank comment lines (`//`) are handled.
      *
-     *   "private": true,
-     *   //
-     *   "type": "module",
+     * - `preserve`: keep existing blank comment lines, but do not add new ones
+     * - `fill`: keep existing blank comment lines and add them where comments are omitted
+     * - `remove`: remove blank comment lines from the output
      *
-     * Defaults to true. Can be disabled via CLI flag `--no-empty-comment` or the
-     * environment variable `SYNC_JSON5_ADD_EMPTY_COMMENT=false`.
+     * Defaults to `preserve`.
      */
-    addEmptyCommentIfMissing?: boolean;
+    blankCommentMode?: BlankCommentMode;
 };
 /**
  * Synchronizes a JSON5 file with its canonical JSON source while preserving formatting.

package/dist/json5-manifest-sync.js

@@ -4,6 +4,32 @@ import path from "path";
 import { fileURLToPath } from "url";
 import { sync as globSync } from "glob";
 import ignore from "ignore";
+function isBlankCommentLine(line) {
+    return /^\s*\/\/\s*$/.test(line);
+}
+function normalizePrecedingComments(preceding, blankCommentMode) {
+    const comments = preceding ?? [];
+    if (blankCommentMode !== "remove") {
+        return comments;
+    }
+    return comments.filter((line) => !isBlankCommentLine(line));
+}
+function collectBlankCommentLineNumbers(raw) {
+    return raw
+        .split("\n")
+        .map((line, index) => ({ line, lineNumber: index + 1 }))
+        .filter(({ line }) => isBlankCommentLine(line))
+        .map(({ lineNumber }) => lineNumber);
+}
+function warnAboutBlankComments(filePath, blankCommentLines) {
+    if (blankCommentLines.length === 0) {
+        return;
+    }
+    const preview = blankCommentLines.slice(0, 8).join(", ");
+    const remainder = blankCommentLines.length > 8 ? ", ..." : "";
+    const plural = blankCommentLines.length === 1 ? "placeholder" : "placeholders";
+    console.warn(`[warn:blank-comments] ${path.basename(filePath)} contains ${blankCommentLines.length} blank comment ${plural} at line${blankCommentLines.length === 1 ? "" : "s"} ${preview}${remainder}. Fill them in with real notes, or rerun with --blank-comments=remove if you do not want placeholders.`);
+}
 /**
  * Quotes an object key for consistent JSON5 formatting.
  * Always returns a quoted key to maintain consistency across all properties.
@@ -202,12 +228,10 @@ function generateScriptComment() {
  * @param source - Parsed JSON object from the canonical package.json
  * @returns The updated JSON5 content as a formatted string
  */
-export function syncJson5(raw, source, options = { addEmptyCommentIfMissing: true }) {
+export function syncJson5(raw, source, options = { blankCommentMode: "preserve" }) {
     const lines = raw.split("\n");
     const comments = buildCommentMap(lines);
-    const addEmptyCommentIfMissing = options.addEmptyCommentIfMissing !== undefined
-        ? options.addEmptyCommentIfMissing
-        : true;
+    const blankCommentMode = options.blankCommentMode ?? "preserve";
     /**
      * Recursively writes an object in normalized JSON5 style with mapped comments.
      *
@@ -230,13 +254,14 @@ export function syncJson5(raw, source, options = { addEmptyCommentIfMissing: tru
             const val = obj[key];
             const comma = ","; // Always add trailing comma for version control benefits
             const commentInfo = comments[fullPath];
+            const precedingComments = normalizePrecedingComments(commentInfo?.preceding, blankCommentMode);
             // Add any preceding comments above this key
-            if (commentInfo?.preceding && commentInfo.preceding.length > 0) {
-                for (const c of commentInfo.preceding) {
+            if (precedingComments.length > 0) {
+                for (const c of precedingComments) {
                     result.push(indent(c, level));
                 }
             }
-            else if (addEmptyCommentIfMissing &&
+            else if (blankCommentMode === "fill" &&
                 !comments.hasOwnProperty(fullPath)) {
                 // No preceding comment captured — optionally add a blank one for spacing
                 // Applies to any section, not just scripts
@@ -265,13 +290,14 @@ export function syncJson5(raw, source, options = { addEmptyCommentIfMissing: tru
                 for (let j = 0; j < val.length; j++) {
                     const itemPath = [...path, key, j.toString()].join(".");
                     const itemCommentInfo = comments[itemPath];
+                    const itemPrecedingComments = normalizePrecedingComments(itemCommentInfo?.preceding, blankCommentMode);
                     // Add preceding comments for this array item
-                    if (itemCommentInfo?.preceding) {
-                        for (const c of itemCommentInfo.preceding) {
+                    if (itemPrecedingComments.length > 0) {
+                        for (const c of itemPrecedingComments) {
                             result.push(indent(c, level + indentSize));
                         }
                     }
-                    else if (addEmptyCommentIfMissing &&
+                    else if (blankCommentMode === "fill" &&
                         !comments.hasOwnProperty(itemPath)) {
                         const autoComment = generateScriptComment();
                         result.push(indent(autoComment, level + indentSize));
@@ -329,24 +355,19 @@ export function runCli(args = process.argv.slice(2)) {
         ignore: ["**/node_modules/**"],
         absolute: true,
     });
-    // Parse simple CLI flags / env for options
-    let addEmptyCommentIfMissing = true;
-    // Env toggle: SYNC_JSON5_ADD_EMPTY_COMMENT=false
-    if (typeof process.env.SYNC_JSON5_ADD_EMPTY_COMMENT === "string" &&
-        process.env.SYNC_JSON5_ADD_EMPTY_COMMENT.toLowerCase() === "false") {
-        addEmptyCommentIfMissing = false;
-    }
-    // CLI toggles: --no-empty-comment, --empty-comment=false
+    // Parse CLI flags for options
+    let blankCommentMode = "preserve";
+    let warnOnBlankComments = false;
     for (const arg of args) {
-        if (arg === "--no-empty-comment" || arg === "--no-empty-comments") {
-            addEmptyCommentIfMissing = false;
-        }
-        else if (arg.startsWith("--empty-comment=")) {
+        if (arg.startsWith("--blank-comments=")) {
             const v = arg.split("=", 2)[1]?.toLowerCase();
-            if (v === "false" || v === "0" || v === "no") {
-                addEmptyCommentIfMissing = false;
+            if (v === "preserve" || v === "fill" || v === "remove") {
+                blankCommentMode = v;
             }
         }
+        else if (arg === "--warn-blank-comments") {
+            warnOnBlankComments = true;
+        }
     }
     // Process each package.json to sync with its package.json5 counterpart
     for (const packageJsonPath of packageJsonPaths) {
@@ -364,11 +385,14 @@ export function runCli(args = process.argv.slice(2)) {
         const rawJson5 = fs.readFileSync(json5Path, "utf8");
         const sourceJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
         const updated = syncJson5(rawJson5, sourceJson, {
-            addEmptyCommentIfMissing,
+            blankCommentMode,
         });
         // Write the synchronized result
         fs.writeFileSync(json5Path, updated);
         console.info(`✅ Synced ${relPath} → ${path.basename(json5Path)}`);
+        if (warnOnBlankComments && blankCommentMode !== "remove") {
+            warnAboutBlankComments(json5Path, collectBlankCommentLineNumbers(updated));
+        }
     }
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "json5-manifest-sync",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "Sync package.json5 files from canonical package.json while preserving key comments.",
   "author": {
     "name": "Bradley Baysinger",
@@ -16,7 +16,7 @@
     }
   },
   "bin": {
-    "json5-manifest-sync": "./dist/json5-manifest-sync.js"
+    "json5-manifest-sync": "dist/json5-manifest-sync.js"
   },
   "files": [
     "dist",
@@ -25,8 +25,11 @@
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
+    "sync:json5": "node ./dist/json5-manifest-sync.js",
+    "warn:blank-comments": "node ./scripts/warn-blank-comments.mjs",
     "format": "prettier . --write",
     "format:check": "prettier . --check",
+    "precommit": "node ./scripts/precommit.mjs",
     "test": "vitest run",
     "test:watch": "vitest",
     "prepare": "npm run build"
@@ -35,13 +38,13 @@
     "node": ">=18"
   },
   "dependencies": {
-    "glob": "^11.0.1",
-    "ignore": "^7.0.4"
+    "glob": "^13.0.6",
+    "ignore": "^7.0.5"
   },
   "devDependencies": {
-    "@types/node": "^22.13.10",
-    "prettier": "^3.8.1",
-    "typescript": "^5.8.2",
-    "vitest": "^2.1.9"
+    "@types/node": "^25.6.0",
+    "prettier": "^3.8.3",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.5"
   }
 }