Write header detailing combined file provenance (configurable with --no-header option)

Author: jameswiltshire

src/cli.ts

@@ -15,6 +15,7 @@ interface ParsedArgs {
   backup?: boolean;
   indent?: number;
   arrayMerge?: "replace" | "concat";
+  header?: boolean;
   inputs: string[];
 }
 
@@ -50,6 +51,9 @@ function mergeArgsWithConfig(args: ParsedArgs, config: ConfigOptions): MergeOpti
     backup: args.backup ?? config.backup ?? false,
     indent: args.indent ?? config.indent,
     arrayMerge: args.arrayMerge ?? config.arrayMerge ?? "replace",
+    // header default true
+    // allow CLI to explicitly set header: false via --no-header
+    header: args.header ?? config.header ?? true,
   };
 }
 
@@ -95,6 +99,16 @@ async function run() {
         choices: ["replace", "concat"],
         default: "replace",
       })
+      .option("header", {
+        describe: "Prepend a comment header to JSONC/JSON5 outputs (default: true)",
+        type: "boolean",
+        default: true,
+      })
+      .option("no-header", {
+        describe: "Alias: do not prepend a comment header to JSONC/JSON5 outputs",
+        type: "boolean",
+        default: false,
+      })
       .help("help")
       .alias("help", "h")
       .version(version)
@@ -125,6 +139,16 @@ async function run() {
       })
       .parseAsync();
 
+    // normalize header arg: prefer explicit --header, else respect --no-header negation
+    let headerArg: boolean | undefined;
+    if (typeof argv.header === "boolean") {
+      headerArg = argv.header;
+    } else if (argv["no-header"]) {
+      headerArg = false;
+    } else {
+      headerArg = undefined;
+    }
+
     const args: ParsedArgs = {
       out: argv.out,
       skipMissing: argv["skip-missing"],
@@ -133,6 +157,9 @@ async function run() {
       backup: argv.backup,
       indent: argv.indent,
       arrayMerge: argv["array-merge"] as "replace" | "concat" | undefined,
+      // yargs presents boolean negations as the positive name being false
+      // yargs supports both --header and --no-header; prefer explicit argv.header when present
+      header: headerArg,
       inputs: Array.from(argv._, (value) => String(value)),
     };
 

src/config.ts

@@ -10,6 +10,7 @@ export interface ConfigOptions {
   backup?: boolean;
   indent?: number;
   arrayMerge?: "replace" | "concat";
+  header?: boolean;
 }
 
 type ConfigKey = keyof ConfigOptions;
@@ -59,6 +60,12 @@ const validators: { [K in ConfigKey]-?: ConfigValidator<K> } = {
     }
     return value;
   },
+  header: (value, source) => {
+    if (typeof value !== "boolean") {
+      throw new Error(`Invalid 'header' value in '${source}'. Expected boolean.`);
+    }
+    return value;
+  },
 };
 
 function setConfigValue<K extends ConfigKey>(

src/core.ts

@@ -13,6 +13,7 @@ export interface MergeOptions {
   backup?: boolean; // create .bak file before overwriting
   indent?: number; // custom indentation (overrides pretty)
   arrayMerge?: "replace" | "concat"; // array merge strategy (default: replace)
+  header?: boolean; // whether to prepend comment header for JSONC/JSON5 outputs (default: true)
 }
 
 export type MergeResult =
@@ -122,6 +123,7 @@ export function mergeJsonc(opts: MergeOptions): MergeResult {
     backup = false,
     indent,
     arrayMerge = "replace",
+    header,
   } = opts;
 
   const inputAbs = resolveInputPaths(inputs, skipMissing);
@@ -136,6 +138,20 @@ export function mergeJsonc(opts: MergeOptions): MergeResult {
   const spaces = calculateIndentation(indent, pretty);
   const text = JSON.stringify(combined, null, spaces);
 
+  // For JSONC and JSON5 outputs, prefix a two-line comment header with timestamp
+  // and list of source files. Use '//' comments which are valid in JSONC/JSON5.
+  const outExt = outAbs.toLowerCase().split(".").pop();
+  let finalText = text;
+  const shouldHeader = header !== false;
+
+  if (shouldHeader && (outExt === "jsonc" || outExt === "json5")) {
+    const timestamp = new Date().toISOString();
+    // Use original input paths (as provided by the caller) for the header
+    const inputList = inputs.join(" ");
+    const header = `// Generated by merge-jsonc on ${timestamp}\n// Result of combining ${inputList}\n`;
+    finalText = header + text;
+  }
+
   if (!checkContentChanged(outAbs, text)) {
     return { wrote: false, reason: "no_content_change" };
   }
@@ -148,7 +164,7 @@ export function mergeJsonc(opts: MergeOptions): MergeResult {
     return { wrote: false, reason: "dry_run", preview: text };
   }
 
-  const backupPath = atomicWrite(outAbs, text, backup);
+  const backupPath = atomicWrite(outAbs, finalText, backup);
 
   return {
     wrote: true,

test/cli-module.test.ts

@@ -72,6 +72,7 @@ describe("CLI module", () => {
       backup: true,
       indent: 4,
       arrayMerge: "replace",
+      header: true,
     });
     expect(logSpy).toHaveBeenCalledWith(
       expect.stringContaining("DRY RUN - would write to result.json")

test/cli.test.ts

@@ -2,6 +2,7 @@ import { describe, test, expect, beforeEach, afterEach } from "vitest";
 import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process";
 import { existsSync, rmSync, mkdirSync, writeFileSync, readFileSync } from "node:fs";
 import { join } from "node:path";
+import JSON5 from "json5";
 
 const TEST_DIR = join(process.cwd(), "test-tmp-cli");
 const CLI_PATH = join(process.cwd(), "dist/cli.js");
@@ -72,7 +73,16 @@ describe("CLI integration tests", () => {
 
   const readJsonFile = (name: string): Record<string, unknown> => {
     const text = readTestFile(name);
-    const parsed: unknown = JSON.parse(text);
+    // Strip leading comment header lines (// or #) that may be prepended for JSONC/JSON5 outputs
+    const lines = text.split(/\r?\n/);
+    let first = 0;
+    while (first < lines.length) {
+      const ln = lines[first];
+      if (typeof ln !== "string" || !/^\s*(\/\/|#)/.test(ln)) break;
+      first++;
+    }
+    const payload = lines.slice(first).join("\n");
+    const parsed: unknown = JSON5.parse(payload);
     if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
       throw new Error(`Expected '${name}' to contain a JSON object.`);
     }

test/core.test.ts

@@ -2,6 +2,7 @@ import { describe, test, expect, beforeEach, afterEach } from "vitest";
 import { existsSync, rmSync, mkdirSync, writeFileSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { mergeJsonc } from "../src/core.js";
+import JSON5 from "json5";
 
 const TEST_DIR = join(process.cwd(), "test-tmp");
 
@@ -29,7 +30,16 @@ describe("mergeJsonc core functionality", () => {
 
   const readJsonObject = (name: string): Record<string, unknown> => {
     const text = readTestFile(name);
-    const parsed: unknown = JSON.parse(text);
+    // Strip leading comment header lines (// or #) that may be prepended for JSONC/JSON5 outputs
+    const lines = text.split(/\r?\n/);
+    let first = 0;
+    while (first < lines.length) {
+      const ln = lines[first];
+      if (typeof ln !== "string" || !/^\s*(\/\/|#)/.test(ln)) break;
+      first++;
+    }
+    const payload = lines.slice(first).join("\n");
+    const parsed: unknown = JSON5.parse(payload);
     if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
       throw new Error(`Expected '${name}' to contain a JSON object.`);
     }

test/timing-and-backup.test.ts

@@ -2,6 +2,7 @@ import { describe, test, expect, beforeEach, afterEach } from "vitest";
 import { existsSync, rmSync, mkdirSync, writeFileSync, readFileSync, utimesSync } from "node:fs";
 import { join } from "node:path";
 import { mergeJsonc } from "../src/core.js";
+import JSON5 from "json5";
 import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process";
 
 const TEST_DIR = join(process.cwd(), "test-tmp-timing");
@@ -62,7 +63,15 @@ describe("Timing and backup functionality", () => {
 
   const readJsonObject = (name: string): Record<string, unknown> => {
     const text = readTestFile(name);
-    const parsed: unknown = JSON.parse(text);
+    const lines = text.split(/\r?\n/);
+    let first = 0;
+    while (first < lines.length) {
+      const ln = lines[first];
+      if (typeof ln !== "string" || !/^\s*(\/\/|#)/.test(ln)) break;
+      first++;
+    }
+    const payload = lines.slice(first).join("\n");
+    const parsed: unknown = JSON5.parse(payload);
     if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
       throw new Error(`Expected '${name}' to contain a JSON object.`);
     }