@aspruyt/json-config-sync 3.1.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,11 +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       |
-| `createOnly`    | If `true`, only create file if it doesn't exist      | 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
 
@@ -185,6 +189,8 @@ repos: # List of repositories
 | `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:
 
@@ -398,6 +404,52 @@ repos:
         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,32 +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 });
-                // Resolve createOnly: per-repo overrides root level
+                // 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

@@ -33,6 +33,17 @@ export function validateRawConfig(config) {
             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)");
@@ -74,6 +85,17 @@ export function validateRawConfig(config) {
                     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,14 +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[];
@@ -20,8 +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/repository-processor.js

@@ -47,7 +47,10 @@ export class RepositoryProcessor {
                     continue;
                 }
                 this.log.info(`Writing ${file.fileName}...`);
-                const fileContent = convertContentToString(file.content, file.fileName);
+                const fileContent = convertContentToString(file.content, file.fileName, {
+                    header: file.header,
+                    schemaUrl: file.schemaUrl,
+                });
                 // Determine action type (create vs update)
                 const action = fileExists ? "update" : "create";
                 if (dryRun) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aspruyt/json-config-sync",
-  "version": "3.1.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",