@aspruyt/json-config-sync 3.0.0 → 3.2.0

package/README.md

@@ -66,6 +66,8 @@ json-config-sync --config ./config.yaml
 - **Environment Variables** - Use `${VAR}` syntax for dynamic values
 - **Merge Strategies** - Control how arrays merge (replace, append, prepend)
 - **Override Mode** - Skip merging entirely for specific repos
+- **Empty Files** - Create files with no content (e.g., `.prettierignore`)
+- **YAML Comments** - Add header comments and schema directives to YAML files
 - **GitHub & Azure DevOps** - Works with both platforms
 - **Dry-Run Mode** - Preview changes without creating PRs
 - **Error Resilience** - Continues processing if individual repos fail
@@ -165,10 +167,13 @@ repos: # List of repositories
 
 ### Per-File Fields
 
-| Field           | Description                                          | Required |
-| --------------- | ---------------------------------------------------- | -------- |
-| `content`       | Base config inherited by all repos                   | Yes      |
-| `mergeStrategy` | Array merge strategy: `replace`, `append`, `prepend` | No       |
+| Field           | Description                                                | Required |
+| --------------- | ---------------------------------------------------------- | -------- |
+| `content`       | Base config inherited by all repos (omit for empty file)   | No       |
+| `mergeStrategy` | Array merge strategy: `replace`, `append`, `prepend`       | No       |
+| `createOnly`    | If `true`, only create file if it doesn't exist            | No       |
+| `header`        | Comment line(s) at top of YAML files (string or array)     | No       |
+| `schemaUrl`     | Adds `# yaml-language-server: $schema=<url>` to YAML files | No       |
 
 ### Per-Repo Fields
 
@@ -179,10 +184,13 @@ repos: # List of repositories
 
 ### Per-Repo File Override Fields
 
-| Field      | Description                                             | Required |
-| ---------- | ------------------------------------------------------- | -------- |
-| `content`  | Content overlay merged onto file's base content         | No       |
-| `override` | If `true`, ignore base content and use only this repo's | No       |
+| Field        | Description                                             | Required |
+| ------------ | ------------------------------------------------------- | -------- |
+| `content`    | Content overlay merged onto file's base content         | No       |
+| `override`   | If `true`, ignore base content and use only this repo's | No       |
+| `createOnly` | Override root-level `createOnly` for this repo          | No       |
+| `header`     | Override root-level `header` for this repo              | No       |
+| `schemaUrl`  | Override root-level `schemaUrl` for this repo           | No       |
 
 **File Exclusion:** Set a file to `false` to exclude it from a specific repo:
 
@@ -363,6 +371,85 @@ repos:
       # Results in extends: ["@company/base", "plugin:react/recommended"]
 ```
 
+### Create-Only Files (Defaults That Can Be Customized)
+
+Some files should only be created once as defaults, allowing repos to maintain their own versions:
+
+```yaml
+files:
+  .trivyignore.yaml:
+    createOnly: true # Only create if doesn't exist
+    content:
+      vulnerabilities: []
+
+  .prettierignore:
+    createOnly: true
+    content:
+      patterns:
+        - "dist/"
+        - "node_modules/"
+
+  eslint.config.json:
+    content: # Always synced (no createOnly)
+      extends: ["@company/base"]
+
+repos:
+  - git: git@github.com:org/repo.git
+    # .trivyignore.yaml and .prettierignore only created if missing
+    # eslint.config.json always updated
+
+  - git: git@github.com:org/special-repo.git
+    files:
+      .trivyignore.yaml:
+        createOnly: false # Override: always sync this file
+```
+
+### YAML Comments and Empty Files
+
+Add schema directives and comments to YAML files, or create empty files:
+
+```yaml
+files:
+  # YAML file with schema directive and header comment
+  trivy.yaml:
+    schemaUrl: https://trivy.dev/latest/docs/references/configuration/config-file/
+    header: "Trivy security scanner configuration"
+    content:
+      exit-code: 1
+      scan:
+        scanners:
+          - vuln
+
+  # Empty file (content omitted)
+  .prettierignore:
+    createOnly: true
+    # No content = empty file
+
+  # YAML with multi-line header
+  config.yaml:
+    header:
+      - "Auto-generated configuration"
+      - "Do not edit manually"
+    content:
+      version: 1
+
+repos:
+  - git: git@github.com:org/repo.git
+```
+
+**Output for trivy.yaml:**
+
+```yaml
+# yaml-language-server: $schema=https://trivy.dev/latest/docs/references/configuration/config-file/
+# Trivy security scanner configuration
+exit-code: 1
+scan:
+  scanners:
+    - vuln
+```
+
+**Note:** `header` and `schemaUrl` only apply to YAML output files (`.yaml`, `.yml`). They are ignored for JSON files.
+
 ## Supported Git URL Formats
 
 ### GitHub

package/dist/config-formatter.d.ts

@@ -1,9 +1,17 @@
 export type OutputFormat = "json" | "yaml";
+/**
+ * Options for content conversion.
+ */
+export interface ConvertOptions {
+    header?: string[];
+    schemaUrl?: string;
+}
 /**
  * Detects output format from file extension.
  */
 export declare function detectOutputFormat(fileName: string): OutputFormat;
 /**
  * Converts content object to string in the appropriate format.
+ * Handles null content (empty files) and comments (YAML only).
  */
-export declare function convertContentToString(content: Record<string, unknown>, fileName: string): string;
+export declare function convertContentToString(content: Record<string, unknown> | null, fileName: string, options?: ConvertOptions): string;

package/dist/config-formatter.js

@@ -1,4 +1,4 @@
-import { stringify } from "yaml";
+import { Document, stringify } from "yaml";
 /**
  * Detects output format from file extension.
  */
@@ -9,13 +9,71 @@ export function detectOutputFormat(fileName) {
     }
     return "json";
 }
+/**
+ * Builds header comment string from header lines and schemaUrl.
+ * Returns undefined if no comments to add.
+ * Each line gets a space prefix since yaml library adds # directly.
+ */
+function buildHeaderComment(header, schemaUrl) {
+    const lines = [];
+    // Add yaml-language-server schema directive first (if present)
+    if (schemaUrl) {
+        lines.push(` yaml-language-server: $schema=${schemaUrl}`);
+    }
+    // Add custom header lines (with space prefix for proper formatting)
+    if (header && header.length > 0) {
+        lines.push(...header.map((h) => ` ${h}`));
+    }
+    if (lines.length === 0)
+        return undefined;
+    // Join with newlines - the yaml library adds # prefix to each line
+    return lines.join("\n");
+}
+/**
+ * Builds comment-only output for empty YAML files with headers.
+ */
+function buildCommentOnlyYaml(header, schemaUrl) {
+    const lines = [];
+    // Add yaml-language-server schema directive first (if present)
+    if (schemaUrl) {
+        lines.push(`# yaml-language-server: $schema=${schemaUrl}`);
+    }
+    // Add custom header lines
+    if (header && header.length > 0) {
+        lines.push(...header.map((h) => `# ${h}`));
+    }
+    if (lines.length === 0)
+        return undefined;
+    return lines.join("\n") + "\n";
+}
 /**
  * Converts content object to string in the appropriate format.
+ * Handles null content (empty files) and comments (YAML only).
  */
-export function convertContentToString(content, fileName) {
+export function convertContentToString(content, fileName, options) {
     const format = detectOutputFormat(fileName);
+    // Handle empty file case
+    if (content === null) {
+        if (format === "yaml" && options) {
+            const commentOnly = buildCommentOnlyYaml(options.header, options.schemaUrl);
+            if (commentOnly) {
+                return commentOnly;
+            }
+        }
+        return "";
+    }
     if (format === "yaml") {
-        return stringify(content, { indent: 2 });
+        // Use Document API for YAML to support comments
+        const doc = new Document(content);
+        // Add header comment if present
+        if (options) {
+            const headerComment = buildHeaderComment(options.header, options.schemaUrl);
+            if (headerComment) {
+                doc.commentBefore = headerComment;
+            }
+        }
+        return stringify(doc, { indent: 2 });
     }
+    // JSON format - comments not supported, ignore header/schemaUrl
     return JSON.stringify(content, null, 2);
 }

package/dist/config-normalizer.js

@@ -1,5 +1,15 @@
 import { deepMerge, stripMergeDirectives, createMergeContext, } from "./merge.js";
 import { interpolateEnvVars } from "./env.js";
+/**
+ * Normalizes header to array format.
+ */
+function normalizeHeader(header) {
+    if (header === undefined)
+        return undefined;
+    if (typeof header === "string")
+        return [header];
+    return header;
+}
 /**
  * Normalizes raw config into expanded, merged config.
  * Pipeline: expand git arrays -> merge content -> interpolate env vars
@@ -20,29 +30,51 @@ export function normalizeConfig(raw) {
                     continue;
                 }
                 const fileConfig = raw.files[fileName];
-                const baseContent = fileConfig.content ?? {};
                 const fileStrategy = fileConfig.mergeStrategy ?? "replace";
                 // Step 3: Compute merged content for this file
                 let mergedContent;
                 if (repoOverride?.override) {
-                    // Override mode: use only repo file content
-                    mergedContent = stripMergeDirectives(structuredClone(repoOverride.content));
+                    // Override mode: use only repo file content (may be undefined for empty file)
+                    if (repoOverride.content === undefined) {
+                        mergedContent = null;
+                    }
+                    else {
+                        mergedContent = stripMergeDirectives(structuredClone(repoOverride.content));
+                    }
+                }
+                else if (fileConfig.content === undefined) {
+                    // Root file has no content = empty file (unless repo provides content)
+                    if (repoOverride?.content) {
+                        mergedContent = stripMergeDirectives(structuredClone(repoOverride.content));
+                    }
+                    else {
+                        mergedContent = null;
+                    }
                 }
                 else if (!repoOverride?.content) {
                     // No repo override: use file base content as-is
-                    mergedContent = structuredClone(baseContent);
+                    mergedContent = structuredClone(fileConfig.content);
                 }
                 else {
                     // Merge mode: deep merge file base + repo overlay
                     const ctx = createMergeContext(fileStrategy);
-                    mergedContent = deepMerge(structuredClone(baseContent), repoOverride.content, ctx);
+                    mergedContent = deepMerge(structuredClone(fileConfig.content), repoOverride.content, ctx);
                     mergedContent = stripMergeDirectives(mergedContent);
                 }
-                // Step 4: Interpolate env vars
-                mergedContent = interpolateEnvVars(mergedContent, { strict: true });
+                // Step 4: Interpolate env vars (only if content exists)
+                if (mergedContent !== null) {
+                    mergedContent = interpolateEnvVars(mergedContent, { strict: true });
+                }
+                // Resolve fields: per-repo overrides root level
+                const createOnly = repoOverride?.createOnly ?? fileConfig.createOnly;
+                const header = normalizeHeader(repoOverride?.header ?? fileConfig.header);
+                const schemaUrl = repoOverride?.schemaUrl ?? fileConfig.schemaUrl;
                 files.push({
                     fileName,
                     content: mergedContent,
+                    createOnly,
+                    header,
+                    schemaUrl,
                 });
             }
             expandedRepos.push({

package/dist/config-validator.js

@@ -29,6 +29,21 @@ export function validateRawConfig(config) {
             !VALID_STRATEGIES.includes(fileConfig.mergeStrategy)) {
             throw new Error(`File '${fileName}' has invalid mergeStrategy: ${fileConfig.mergeStrategy}. Must be one of: ${VALID_STRATEGIES.join(", ")}`);
         }
+        if (fileConfig.createOnly !== undefined &&
+            typeof fileConfig.createOnly !== "boolean") {
+            throw new Error(`File '${fileName}' createOnly must be a boolean`);
+        }
+        if (fileConfig.header !== undefined) {
+            if (typeof fileConfig.header !== "string" &&
+                (!Array.isArray(fileConfig.header) ||
+                    !fileConfig.header.every((h) => typeof h === "string"))) {
+                throw new Error(`File '${fileName}' header must be a string or array of strings`);
+            }
+        }
+        if (fileConfig.schemaUrl !== undefined &&
+            typeof fileConfig.schemaUrl !== "string") {
+            throw new Error(`File '${fileName}' schemaUrl must be a string`);
+        }
     }
     if (!config.repos || !Array.isArray(config.repos)) {
         throw new Error("Config missing required field: repos (must be an array)");
@@ -66,6 +81,21 @@ export function validateRawConfig(config) {
                         Array.isArray(fileOverride.content))) {
                     throw new Error(`Repo at index ${i}: file '${fileName}' content must be an object`);
                 }
+                if (fileOverride.createOnly !== undefined &&
+                    typeof fileOverride.createOnly !== "boolean") {
+                    throw new Error(`Repo ${getGitDisplayName(repo.git)}: file '${fileName}' createOnly must be a boolean`);
+                }
+                if (fileOverride.header !== undefined) {
+                    if (typeof fileOverride.header !== "string" &&
+                        (!Array.isArray(fileOverride.header) ||
+                            !fileOverride.header.every((h) => typeof h === "string"))) {
+                        throw new Error(`Repo ${getGitDisplayName(repo.git)}: file '${fileName}' header must be a string or array of strings`);
+                    }
+                }
+                if (fileOverride.schemaUrl !== undefined &&
+                    typeof fileOverride.schemaUrl !== "string") {
+                    throw new Error(`Repo ${getGitDisplayName(repo.git)}: file '${fileName}' schemaUrl must be a string`);
+                }
             }
         }
     }

package/dist/config.d.ts

@@ -1,12 +1,18 @@
 import type { ArrayMergeStrategy } from "./merge.js";
 export { convertContentToString } from "./config-formatter.js";
 export interface RawFileConfig {
-    content: Record<string, unknown>;
+    content?: Record<string, unknown>;
     mergeStrategy?: ArrayMergeStrategy;
+    createOnly?: boolean;
+    header?: string | string[];
+    schemaUrl?: string;
 }
 export interface RawRepoFileOverride {
     content?: Record<string, unknown>;
     override?: boolean;
+    createOnly?: boolean;
+    header?: string | string[];
+    schemaUrl?: string;
 }
 export interface RawRepoConfig {
     git: string | string[];
@@ -18,7 +24,10 @@ export interface RawConfig {
 }
 export interface FileContent {
     fileName: string;
-    content: Record<string, unknown>;
+    content: Record<string, unknown> | null;
+    createOnly?: boolean;
+    header?: string[];
+    schemaUrl?: string;
 }
 export interface RepoConfig {
     git: string;

package/dist/pr-creator.d.ts

@@ -2,7 +2,7 @@ import { RepoInfo } from "./repo-detector.js";
 export { escapeShellArg } from "./shell-utils.js";
 export interface FileAction {
     fileName: string;
-    action: "create" | "update";
+    action: "create" | "update" | "skip";
 }
 export interface PROptions {
     repoInfo: RepoInfo;
@@ -24,7 +24,7 @@ export interface PRResult {
  */
 export declare function formatPRBody(files: FileAction[]): string;
 /**
- * Generate PR title based on files changed
+ * Generate PR title based on files changed (excludes skipped files)
  */
 export declare function formatPRTitle(files: FileAction[]): string;
 export declare function createPR(options: PROptions): Promise<PRResult>;

package/dist/pr-creator.js

@@ -25,36 +25,37 @@ Configuration synced using [json-config-sync](https://github.com/anthony-spruyt/
 ---
 _This PR was automatically generated by [json-config-sync](https://github.com/anthony-spruyt/json-config-sync)_`;
 }
+/**
+ * Format file changes list, excluding skipped files
+ */
+function formatFileChanges(files) {
+    const changedFiles = files.filter((f) => f.action !== "skip");
+    return changedFiles
+        .map((f) => {
+        const actionText = f.action === "create" ? "Created" : "Updated";
+        return `- ${actionText} \`${f.fileName}\``;
+    })
+        .join("\n");
+}
 /**
  * Format PR body for multiple files
  */
 export function formatPRBody(files) {
     const template = loadPRTemplate();
+    const fileChanges = formatFileChanges(files);
     // Check if template supports multi-file format
     if (template.includes("{{FILE_CHANGES}}")) {
-        // Multi-file template
-        const fileChanges = files
-            .map((f) => {
-            const actionText = f.action === "create" ? "Created" : "Updated";
-            return `- ${actionText} \`${f.fileName}\``;
-        })
-            .join("\n");
         return template.replace(/\{\{FILE_CHANGES\}\}/g, fileChanges);
     }
     // Legacy single-file template - adapt it for multiple files
-    if (files.length === 1) {
-        const actionText = files[0].action === "create" ? "Created" : "Updated";
+    const changedFiles = files.filter((f) => f.action !== "skip");
+    if (changedFiles.length === 1) {
+        const actionText = changedFiles[0].action === "create" ? "Created" : "Updated";
         return template
-            .replace(/\{\{FILE_NAME\}\}/g, files[0].fileName)
+            .replace(/\{\{FILE_NAME\}\}/g, changedFiles[0].fileName)
             .replace(/\{\{ACTION\}\}/g, actionText);
     }
     // Multiple files with legacy template - generate custom body
-    const fileChanges = files
-        .map((f) => {
-        const actionText = f.action === "create" ? "Created" : "Updated";
-        return `- ${actionText} \`${f.fileName}\``;
-    })
-        .join("\n");
     return `## Summary
 Automated sync of configuration files.
 
@@ -68,17 +69,18 @@ Configuration synced using [json-config-sync](https://github.com/anthony-spruyt/
 _This PR was automatically generated by [json-config-sync](https://github.com/anthony-spruyt/json-config-sync)_`;
 }
 /**
- * Generate PR title based on files changed
+ * Generate PR title based on files changed (excludes skipped files)
  */
 export function formatPRTitle(files) {
-    if (files.length === 1) {
-        return `chore: sync ${files[0].fileName}`;
+    const changedFiles = files.filter((f) => f.action !== "skip");
+    if (changedFiles.length === 1) {
+        return `chore: sync ${changedFiles[0].fileName}`;
     }
-    if (files.length <= 3) {
-        const fileNames = files.map((f) => f.fileName).join(", ");
+    if (changedFiles.length <= 3) {
+        const fileNames = changedFiles.map((f) => f.fileName).join(", ");
         return `chore: sync ${fileNames}`;
     }
-    return `chore: sync ${files.length} config files`;
+    return `chore: sync ${changedFiles.length} config files`;
 }
 export async function createPR(options) {
     const { repoInfo, branchName, baseBranch, files, workDir, dryRun, retries } = options;

package/dist/repository-processor.d.ts

@@ -33,7 +33,7 @@ export declare class RepositoryProcessor {
     constructor(gitOpsFactory?: GitOpsFactory, log?: ILogger);
     process(repoConfig: RepoConfig, repoInfo: RepoInfo, options: ProcessorOptions): Promise<ProcessorResult>;
     /**
-     * Format commit message based on files changed
+     * Format commit message based on files changed (excludes skipped files)
      */
     private formatCommitMessage;
 }

package/dist/repository-processor.js

@@ -38,13 +38,21 @@ export class RepositoryProcessor {
             // Step 5: Write all config files and track changes
             const changedFiles = [];
             for (const file of repoConfig.files) {
-                this.log.info(`Writing ${file.fileName}...`);
-                const fileContent = convertContentToString(file.content, file.fileName);
                 const filePath = join(workDir, file.fileName);
+                const fileExists = existsSync(filePath);
+                // Handle createOnly - skip if file already exists
+                if (file.createOnly && fileExists) {
+                    this.log.info(`Skipping ${file.fileName} (createOnly: already exists)`);
+                    changedFiles.push({ fileName: file.fileName, action: "skip" });
+                    continue;
+                }
+                this.log.info(`Writing ${file.fileName}...`);
+                const fileContent = convertContentToString(file.content, file.fileName, {
+                    header: file.header,
+                    schemaUrl: file.schemaUrl,
+                });
                 // Determine action type (create vs update)
-                const action = existsSync(filePath)
-                    ? "update"
-                    : "create";
+                const action = fileExists ? "update" : "create";
                 if (dryRun) {
                     // In dry-run, check if file would change without writing
                     if (this.gitOps.wouldChange(file.fileName, fileContent)) {
@@ -56,23 +64,25 @@ export class RepositoryProcessor {
                     this.gitOps.writeFile(file.fileName, fileContent);
                 }
             }
-            // Step 6: Check for changes
+            // Step 6: Check for changes (exclude skipped files)
             let hasChanges;
             if (dryRun) {
-                hasChanges = changedFiles.length > 0;
+                hasChanges = changedFiles.filter((f) => f.action !== "skip").length > 0;
             }
             else {
                 hasChanges = await this.gitOps.hasChanges();
                 // If there are changes, determine which files changed
                 if (hasChanges) {
                     // Rebuild the changed files list by checking git status
-                    // For simplicity, we include all files with their detected actions
+                    // Skip files that were already marked as skipped (createOnly)
+                    const skippedFiles = new Set(changedFiles
+                        .filter((f) => f.action === "skip")
+                        .map((f) => f.fileName));
                     for (const file of repoConfig.files) {
+                        if (skippedFiles.has(file.fileName)) {
+                            continue; // Already tracked as skipped
+                        }
                         const filePath = join(workDir, file.fileName);
-                        // We check if file existed before writing (action was determined above)
-                        // Since we don't have pre-write state, we'll mark all files that are in the commit
-                        // A more accurate approach would track this before writing, but for now
-                        // we'll assume all files are being synced and include them all
                         const action = existsSync(filePath)
                             ? "update"
                             : "create";
@@ -126,16 +136,17 @@ export class RepositoryProcessor {
         }
     }
     /**
-     * Format commit message based on files changed
+     * Format commit message based on files changed (excludes skipped files)
      */
     formatCommitMessage(files) {
-        if (files.length === 1) {
-            return `chore: sync ${files[0].fileName}`;
+        const changedFiles = files.filter((f) => f.action !== "skip");
+        if (changedFiles.length === 1) {
+            return `chore: sync ${changedFiles[0].fileName}`;
         }
-        if (files.length <= 3) {
-            const fileNames = files.map((f) => f.fileName).join(", ");
+        if (changedFiles.length <= 3) {
+            const fileNames = changedFiles.map((f) => f.fileName).join(", ");
             return `chore: sync ${fileNames}`;
         }
-        return `chore: sync ${files.length} config files`;
+        return `chore: sync ${changedFiles.length} config files`;
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aspruyt/json-config-sync",
-  "version": "3.0.0",
+  "version": "3.2.0",
   "description": "CLI tool to sync JSON or YAML configuration files across multiple GitHub and Azure DevOps repositories",
   "type": "module",
   "main": "dist/index.js",