json5-manifest-sync 0.1.4 → 0.2.0

package/CHANGELOG.md

@@ -2,12 +2,17 @@
 
 All notable changes to this project are documented in this file.
 
-## [0.1.4] - 2026-05-05
+## [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
 
-- Renamed the CLI option for suppressing generated blank `//` spacer comments to clearer `--remove-empty-comments` and `--remove-blank-comments` forms.
-- Kept legacy `--no-empty-comment` and `--no-empty-comments` aliases working for compatibility.
+- 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
 

package/README.md

@@ -49,14 +49,16 @@ When values like `version`, `scripts`, or dependency versions change in `package
 - 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)
 - Preserves/migrates mapped `//` comments for keys and supported array items
-- Inserts a blank `//` comment line before keys with no mapped comment (enabled by default)
+- 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 or replaced by an empty `//` spacer on sync.
-- If you prefer to avoid regenerated blank spacer comments in those cases, run the CLI with `--remove-empty-comments`.
+- 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
 
@@ -125,13 +127,15 @@ For the current full output style, see this repo's live example: [`package.json5
 
 ### Options
 
-By default, the tool inserts an empty `//` line before keys that do not already have a mapped comment. Disable that behavior with one of the following:
+By default, the tool runs with `--blank-comments=preserve`.
 
-- `--remove-empty-comments` or `--remove-blank-comments`
-- `--empty-comment=false`
-- env var: `SYNC_JSON5_ADD_EMPTY_COMMENT=false`
+Choose a blank-comment mode with one of the following:
 
-Legacy aliases `--no-empty-comment` and `--no-empty-comments` are still accepted for compatibility.
+- `--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
 

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

@@ -26,21 +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 flags like
-     * `--remove-empty-comments` 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,29 +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: --remove-empty-comments, --remove-blank-comments
+    // Parse CLI flags for options
+    let blankCommentMode = "preserve";
+    let warnOnBlankComments = false;
     for (const arg of args) {
-        if (arg === "--remove-empty-comment" ||
-            arg === "--remove-empty-comments" ||
-            arg === "--remove-blank-comment" ||
-            arg === "--remove-blank-comments" ||
-            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) {
@@ -369,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.4",
+  "version": "0.2.0",
   "description": "Sync package.json5 files from canonical package.json while preserving key comments.",
   "author": {
     "name": "Bradley Baysinger",