json-tree-merge 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sedlukha
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,255 @@
+# json-tree-merge
+
+[![npm version](https://img.shields.io/npm/v/json-tree-merge.svg)](https://www.npmjs.com/package/json-tree-merge)
+[![license](https://img.shields.io/npm/l/json-tree-merge.svg)](LICENSE)
+[![node](https://img.shields.io/node/v/json-tree-merge.svg)](https://nodejs.org)
+
+> Scan a directory tree for `<group>.json` files and fold them into a single
+> nested-object JSON per `<group>`. Framework- and domain-agnostic — great for
+> [next-intl](https://next-intl.dev) locale merging, but the engine knows
+> nothing about locales or messages.
+
+- **Zero runtime dependencies** — only `node:fs` and `node:path`.
+- **Atomic writes** — uses the `tmp + rename` pattern so a crash never leaves
+  half-written files.
+- **Works via CLI and as a library** — same engine either way.
+- **Runs through `npx`** — no global install needed.
+- **TypeScript types included.**
+
+---
+
+## Quick start
+
+### Via `npx` (no install)
+
+```bash
+npx json-tree-merge \
+  --input ./packages \
+  --output ./messages \
+  --groups en,ru \
+  --exclude messages,src
+```
+
+### Install locally
+
+```bash
+npm install --save-dev json-tree-merge
+# or: pnpm add -D json-tree-merge / yarn add -D json-tree-merge
+```
+
+Then in `package.json`:
+
+```jsonc
+{
+  "scripts": {
+    "merge:i18n": "json-tree-merge --input ./packages --output ./messages --groups en,ru"
+  }
+}
+```
+
+---
+
+## What it does
+
+For each input directory, the engine recursively finds files whose basename
+matches one of the supplied `groupNames` (`en.json`, `ru.json`, …), reads
+them, and merges the contents into a single output JSON per group. Each
+directory segment between an input path and the file becomes a nested key,
+minus anything in `excludePathSegments`.
+
+### Example
+
+Given this tree:
+
+```
+packages/
+├── auth/
+│   └── messages/
+│       ├── en.json   {"login": "Log in"}
+│       └── ru.json   {"login": "Войти"}
+└── billing/
+    └── messages/
+        └── en.json   {"checkout": "Checkout"}
+```
+
+Running:
+
+```bash
+npx json-tree-merge \
+  --input ./packages \
+  --output ./messages \
+  --groups en,ru \
+  --exclude messages
+```
+
+Produces:
+
+```jsonc
+// messages/en.json
+{
+  "auth": { "login": "Log in" },
+  "billing": { "checkout": "Checkout" }
+}
+
+// messages/ru.json
+{
+  "auth": { "login": "Войти" }
+}
+```
+
+The `messages` segment is stripped because it was passed to `--exclude`.
+
+---
+
+## CLI
+
+```
+json-tree-merge [options]
+```
+
+| Flag                  | Alias | Description                                                              |
+| --------------------- | ----- | ------------------------------------------------------------------------ |
+| `--input <dir>`       | `-i`  | Directory to scan recursively. Repeatable, or comma-separated.           |
+| `--output <dir>`      | `-o`  | Directory where merged `<group>.json` files are written.                 |
+| `--groups <names>`    | `-g`  | Comma-separated allowed basenames (e.g. `en,ru`).                        |
+| `--exclude <names>`   | `-e`  | Comma-separated path segments to strip from the nested keys.             |
+| `--config <file>`     | `-c`  | Load options from a JSON config file. Flags override file values.        |
+| `--debug`             |       | Print verbose progress to stderr.                                        |
+| `--help`              | `-h`  | Show help.                                                               |
+| `--version`           | `-v`  | Print version.                                                           |
+
+Repeating flags is equivalent to a comma-separated list:
+
+```bash
+json-tree-merge -i ./apps -i ./packages -o ./out -g en,ru
+# same as
+json-tree-merge -i ./apps,./packages -o ./out -g en,ru
+```
+
+### Config file
+
+If `--config <file>` is not specified, the CLI looks for
+`json-tree-merge.config.json` (then `.json-tree-merge.json`) in the current
+working directory. CLI flags always override config values.
+
+```jsonc
+// json-tree-merge.config.json
+{
+  "input": ["./packages", "./apps"],
+  "output": "./messages",
+  "groups": ["en", "ru"],
+  "exclude": ["messages", "src"],
+  "debug": false
+}
+```
+
+Run with just:
+
+```bash
+npx json-tree-merge
+```
+
+### Exit codes
+
+| Code | Meaning                                                |
+| ---- | ------------------------------------------------------ |
+| `0`  | Success.                                               |
+| `1`  | Runtime error (I/O, invalid JSON, etc).                |
+| `2`  | Invalid CLI usage or missing/invalid configuration.    |
+
+---
+
+## Programmatic API
+
+```ts
+import { mergeJsonTree, createLogger } from "json-tree-merge"
+
+const { sourceFiles, written } = mergeJsonTree({
+  inputPaths: ["/abs/path/to/packages", "/abs/path/to/apps"],
+  outputDir: "/abs/path/to/messages",
+  groupNames: ["en", "ru"] as const,
+  excludePathSegments: ["messages", "src"],
+  logger: createLogger(true),     // optional — defaults to no-op
+  isShuttingDown: () => false,    // optional — defaults to () => false
+})
+
+console.log(`Wrote ${written.length} groups from ${sourceFiles} files`)
+```
+
+### `mergeJsonTree(options)`
+
+The primary entry point. Scans, merges, and writes one file per group.
+
+| Option                | Type                | Default       | Description                                                              |
+| --------------------- | ------------------- | ------------- | ------------------------------------------------------------------------ |
+| `inputPaths`          | `string[]`          | —             | Absolute directories to scan recursively.                                |
+| `outputDir`           | `string`            | —             | Absolute directory where merged `<group>.json` files are written.        |
+| `groupNames`          | `readonly string[]` | —             | Allowed file basenames. `de.json` is ignored unless `"de"` is listed.    |
+| `excludePathSegments` | `string[]`          | `[]`          | Path segments stripped when computing the nested key path.               |
+| `logger`              | `Logger`            | no-op         | `(...args) => void`. Use `createLogger(true)` for verbose output.        |
+| `isShuttingDown`      | `() => boolean`     | `() => false` | Hook to abort writes during graceful shutdown (e.g. SIGTERM handlers).   |
+| `relevantChanges`     | `string[]`          | `[]`          | Files that triggered this merge (used only for log output).              |
+
+Returns:
+
+```ts
+{ sourceFiles: number; written: string[] }
+```
+
+### Primitives
+
+For advanced consumers that want to compose differently:
+
+| Export                  | Purpose                                              |
+| ----------------------- | ---------------------------------------------------- |
+| `scanDirectory`         | Recursive scanner.                                   |
+| `mergeFilesIntoTree`    | Pure transform (no I/O).                             |
+| `writeTree`             | Atomic write of the merged tree.                     |
+| `findGroupFiles`        | Scan wrapper across multiple input paths.            |
+| `isGroupJsonFile`       | Basename predicate.                                  |
+| `isGroupFileInScope`    | Full predicate (in input, not in output, allowed).   |
+| `createLogger(debug)`   | Debug-gated logger factory.                          |
+
+---
+
+## Behavior details
+
+### Atomic writes
+
+Files are written via the `tmp + rename` pattern, so a SIGTERM during the
+write cannot leave the destination truncated. `rename` is atomic on POSIX
+within the same filesystem.
+
+### Shutdown gating
+
+Pass `isShuttingDown` so the engine can skip writes once your host process
+starts shutting down. The library itself doesn't install signal handlers —
+that's the integration's responsibility.
+
+### Logging
+
+The library emits unprefixed messages via the injected `logger`. Integrations
+typically wrap `createLogger` with their own prefix:
+
+```ts
+const baseLogger = createLogger(debug)
+const logger: Logger = (...args) => baseLogger("[MyPlugin]", ...args)
+```
+
+### Skipped directories
+
+The recursive scan skips `node_modules`, `.next`, `.turbo`, `.git`, and `dist`
+by default. The output directory is also skipped automatically, so re-running
+the CLI never re-ingests its own output.
+
+---
+
+## Requirements
+
+- Node.js **18** or newer.
+
+---
+
+## License
+
+[MIT](LICENSE)

package/dist/cli/help.d.ts

@@ -0,0 +1 @@
+export declare const HELP_TEXT = "json-tree-merge \u2014 fold per-group JSON files in a directory tree into one file per group.\n\nUsage:\n  json-tree-merge --input <dir> [--input <dir> ...] --output <dir> --groups <names> [options]\n  json-tree-merge --config <file>\n  json-tree-merge                  # uses ./json-tree-merge.config.json if present\n\nOptions:\n  -i, --input <dir>        Directory to scan recursively. Repeatable, or comma-separated.\n  -o, --output <dir>       Directory where merged <group>.json files are written.\n  -g, --groups <names>     Comma-separated allowed basenames (e.g. \"en,ru\").\n  -e, --exclude <names>    Comma-separated path segments to strip from nested keys.\n  -c, --config <file>      Load options from a JSON file. Flags override file values.\n      --debug              Print verbose progress to stderr.\n  -h, --help               Show this help.\n  -v, --version            Print package version.\n\nConfig file format (JSON):\n  {\n    \"input\": [\"./packages\", \"./apps\"],\n    \"output\": \"./messages\",\n    \"groups\": [\"en\", \"ru\"],\n    \"exclude\": [\"messages\", \"src\"],\n    \"debug\": false\n  }\n\nExamples:\n  json-tree-merge --input ./packages --output ./messages --groups en,ru\n  json-tree-merge -i ./apps -i ./packages -o ./out -g en,ru -e messages,src\n  json-tree-merge --config ./i18n.config.json\n";

package/dist/cli/help.js

@@ -0,0 +1,31 @@
+export const HELP_TEXT = `json-tree-merge — fold per-group JSON files in a directory tree into one file per group.
+
+Usage:
+  json-tree-merge --input <dir> [--input <dir> ...] --output <dir> --groups <names> [options]
+  json-tree-merge --config <file>
+  json-tree-merge                  # uses ./json-tree-merge.config.json if present
+
+Options:
+  -i, --input <dir>        Directory to scan recursively. Repeatable, or comma-separated.
+  -o, --output <dir>       Directory where merged <group>.json files are written.
+  -g, --groups <names>     Comma-separated allowed basenames (e.g. "en,ru").
+  -e, --exclude <names>    Comma-separated path segments to strip from nested keys.
+  -c, --config <file>      Load options from a JSON file. Flags override file values.
+      --debug              Print verbose progress to stderr.
+  -h, --help               Show this help.
+  -v, --version            Print package version.
+
+Config file format (JSON):
+  {
+    "input": ["./packages", "./apps"],
+    "output": "./messages",
+    "groups": ["en", "ru"],
+    "exclude": ["messages", "src"],
+    "debug": false
+  }
+
+Examples:
+  json-tree-merge --input ./packages --output ./messages --groups en,ru
+  json-tree-merge -i ./apps -i ./packages -o ./out -g en,ru -e messages,src
+  json-tree-merge --config ./i18n.config.json
+`;

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/index.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { runCli } from "./main.js";
+const exitCode = runCli({
+    argv: process.argv.slice(2),
+    cwd: process.cwd(),
+    stderr: process.stderr,
+    stdout: process.stdout,
+});
+process.exit(exitCode);

package/dist/cli/load-config.d.ts

@@ -0,0 +1,9 @@
+export interface FileConfig {
+    debug?: boolean;
+    exclude?: string[];
+    groups?: string[];
+    input?: string[];
+    output?: string;
+}
+export declare const findConfigFile: (explicitPath: string | undefined, cwd: string) => string | null;
+export declare const loadConfig: (configPath: string) => FileConfig;

package/dist/cli/load-config.js

@@ -0,0 +1,83 @@
+import fs from "node:fs";
+import path from "node:path";
+const DEFAULT_CONFIG_NAMES = [
+    "json-tree-merge.config.json",
+    ".json-tree-merge.json",
+];
+// Locates a config file: explicit path wins; otherwise probes well-known names
+// in `cwd`. Returns `null` (not throws) when nothing is found so the CLI can
+// fall back to pure-flag mode.
+export const findConfigFile = (explicitPath, cwd) => {
+    if (explicitPath) {
+        const absolute = path.isAbsolute(explicitPath)
+            ? explicitPath
+            : path.resolve(cwd, explicitPath);
+        if (!fs.existsSync(absolute)) {
+            throw new Error(`Config file not found: ${absolute}`);
+        }
+        return absolute;
+    }
+    for (const name of DEFAULT_CONFIG_NAMES) {
+        const candidate = path.resolve(cwd, name);
+        if (fs.existsSync(candidate)) {
+            return candidate;
+        }
+    }
+    return null;
+};
+const isStringArray = (value) => Array.isArray(value) && value.every((item) => typeof item === "string");
+const validate = (raw, source) => {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new Error(`${source}: config must be a JSON object`);
+    }
+    const obj = raw;
+    const result = {};
+    if (obj.input !== undefined) {
+        if (!isStringArray(obj.input)) {
+            throw new Error(`${source}: "input" must be an array of strings`);
+        }
+        result.input = obj.input;
+    }
+    if (obj.output !== undefined) {
+        if (typeof obj.output !== "string") {
+            throw new Error(`${source}: "output" must be a string`);
+        }
+        result.output = obj.output;
+    }
+    if (obj.groups !== undefined) {
+        if (!isStringArray(obj.groups)) {
+            throw new Error(`${source}: "groups" must be an array of strings`);
+        }
+        result.groups = obj.groups;
+    }
+    if (obj.exclude !== undefined) {
+        if (!isStringArray(obj.exclude)) {
+            throw new Error(`${source}: "exclude" must be an array of strings`);
+        }
+        result.exclude = obj.exclude;
+    }
+    if (obj.debug !== undefined) {
+        if (typeof obj.debug !== "boolean") {
+            throw new Error(`${source}: "debug" must be a boolean`);
+        }
+        result.debug = obj.debug;
+    }
+    return result;
+};
+export const loadConfig = (configPath) => {
+    let raw;
+    try {
+        raw = fs.readFileSync(configPath, "utf-8");
+    }
+    catch (error) {
+        throw new Error(`Failed to read config ${configPath}`, { cause: error });
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`Failed to parse config ${configPath}`, { cause: error });
+    }
+    return validate(parsed, configPath);
+};

package/dist/cli/main.d.ts

@@ -0,0 +1,6 @@
+export declare const runCli: ({ argv, cwd, stderr, stdout, }: {
+    argv: string[];
+    cwd: string;
+    stderr: NodeJS.WritableStream;
+    stdout: NodeJS.WritableStream;
+}) => number;

package/dist/cli/main.js

@@ -0,0 +1,73 @@
+import fs from "node:fs";
+import { createLogger } from "../lib/create-logger.js";
+import { mergeJsonTree } from "../lib/merge-json-tree.js";
+import { HELP_TEXT } from "./help.js";
+import { findConfigFile, loadConfig } from "./load-config.js";
+import { parseArgs } from "./parse-args.js";
+import { resolveOptions } from "./resolve-options.js";
+const readVersion = () => {
+    // Resolved relative to the compiled file in dist/cli/main.js — climb to the
+    // package root. For npx, this is the unpacked tarball.
+    const url = new URL("../../package.json", import.meta.url);
+    const raw = fs.readFileSync(url, "utf-8");
+    return JSON.parse(raw).version;
+};
+export const runCli = ({ argv, cwd, stderr, stdout, }) => {
+    let args;
+    try {
+        args = parseArgs(argv);
+    }
+    catch (error) {
+        stderr.write(`${error.message}\n`);
+        return 2;
+    }
+    if (args.help) {
+        stdout.write(HELP_TEXT);
+        return 0;
+    }
+    if (args.version) {
+        try {
+            stdout.write(`${readVersion()}\n`);
+            return 0;
+        }
+        catch {
+            stdout.write("0.0.0\n");
+            return 0;
+        }
+    }
+    let config = null;
+    try {
+        const configPath = findConfigFile(args.config, cwd);
+        if (configPath) {
+            config = loadConfig(configPath);
+        }
+    }
+    catch (error) {
+        stderr.write(`${error.message}\n`);
+        return 2;
+    }
+    let options;
+    try {
+        options = resolveOptions({ args, config, cwd });
+    }
+    catch (error) {
+        stderr.write(`${error.message}\n`);
+        return 2;
+    }
+    const logger = createLogger(options.debug);
+    try {
+        const { sourceFiles, written } = mergeJsonTree({
+            excludePathSegments: options.excludePathSegments,
+            groupNames: options.groupNames,
+            inputPaths: options.inputPaths,
+            logger,
+            outputDir: options.outputDir,
+        });
+        stdout.write(`Merged ${sourceFiles} file(s) into ${written.length} group(s): ${written.join(", ") || "none"}\n`);
+        return 0;
+    }
+    catch (error) {
+        stderr.write(`Error: ${error.message}\n`);
+        return 1;
+    }
+};

package/dist/cli/parse-args.d.ts

@@ -0,0 +1,11 @@
+export interface ParsedArgs {
+    config?: string;
+    debug?: boolean;
+    exclude?: string[];
+    groups?: string[];
+    help?: boolean;
+    input?: string[];
+    output?: string;
+    version?: boolean;
+}
+export declare const parseArgs: (argv: string[]) => ParsedArgs;

package/dist/cli/parse-args.js

@@ -0,0 +1,101 @@
+const splitList = (value) => value
+    .split(",")
+    .map((item) => item.trim())
+    .filter(Boolean);
+// Tiny argv parser: supports `--flag value`, `--flag=value`, repeated flags
+// (e.g. `--input a --input b`), and boolean flags (`--debug`, `--help`).
+// Avoids pulling in `yargs`/`commander` for a ~6-flag CLI.
+export const parseArgs = (argv) => {
+    const result = {};
+    const inputs = [];
+    const groups = [];
+    const excludes = [];
+    let i = 0;
+    while (i < argv.length) {
+        const token = argv[i];
+        let key;
+        let value;
+        if (token === undefined) {
+            break;
+        }
+        if (token.startsWith("--")) {
+            const eq = token.indexOf("=");
+            if (eq >= 0) {
+                key = token.slice(2, eq);
+                value = token.slice(eq + 1);
+            }
+            else {
+                key = token.slice(2);
+                const next = argv[i + 1];
+                if (next !== undefined && !next.startsWith("--")) {
+                    value = next;
+                    i += 1;
+                }
+            }
+        }
+        else {
+            throw new Error(`Unexpected positional argument: ${token}`);
+        }
+        switch (key) {
+            case "input":
+            case "i":
+                if (value === undefined) {
+                    throw new Error("--input requires a directory path");
+                }
+                inputs.push(...splitList(value));
+                break;
+            case "output":
+            case "o":
+                if (value === undefined) {
+                    throw new Error("--output requires a directory path");
+                }
+                result.output = value;
+                break;
+            case "groups":
+            case "g":
+                if (value === undefined) {
+                    throw new Error("--groups requires a comma-separated list");
+                }
+                groups.push(...splitList(value));
+                break;
+            case "exclude":
+            case "e":
+                if (value === undefined) {
+                    throw new Error("--exclude requires a comma-separated list");
+                }
+                excludes.push(...splitList(value));
+                break;
+            case "config":
+            case "c":
+                if (value === undefined) {
+                    throw new Error("--config requires a file path");
+                }
+                result.config = value;
+                break;
+            case "debug":
+                result.debug = value === undefined ? true : value !== "false";
+                break;
+            case "help":
+            case "h":
+                result.help = true;
+                break;
+            case "version":
+            case "v":
+                result.version = true;
+                break;
+            default:
+                throw new Error(`Unknown flag: --${key}`);
+        }
+        i += 1;
+    }
+    if (inputs.length > 0) {
+        result.input = inputs;
+    }
+    if (groups.length > 0) {
+        result.groups = groups;
+    }
+    if (excludes.length > 0) {
+        result.exclude = excludes;
+    }
+    return result;
+};

package/dist/cli/resolve-options.d.ts

@@ -0,0 +1,14 @@
+import type { FileConfig } from "./load-config.js";
+import type { ParsedArgs } from "./parse-args.js";
+export interface ResolvedOptions {
+    debug: boolean;
+    excludePathSegments: string[];
+    groupNames: string[];
+    inputPaths: string[];
+    outputDir: string;
+}
+export declare const resolveOptions: ({ args, config, cwd, }: {
+    args: ParsedArgs;
+    config: FileConfig | null;
+    cwd: string;
+}) => ResolvedOptions;

package/dist/cli/resolve-options.js

@@ -0,0 +1,31 @@
+import path from "node:path";
+const resolveDir = (cwd, value) => path.isAbsolute(value) ? value : path.resolve(cwd, value);
+// Merge precedence: CLI flags > config file > defaults. Required fields are
+// surfaced via a single error so users see everything that's missing at once.
+export const resolveOptions = ({ args, config, cwd, }) => {
+    const inputRaw = args.input ?? config?.input;
+    const outputRaw = args.output ?? config?.output;
+    const groupsRaw = args.groups ?? config?.groups;
+    const excludeRaw = args.exclude ?? config?.exclude ?? [];
+    const debug = args.debug ?? config?.debug ?? false;
+    const missing = [];
+    if (!inputRaw || inputRaw.length === 0) {
+        missing.push("input");
+    }
+    if (!outputRaw) {
+        missing.push("output");
+    }
+    if (!groupsRaw || groupsRaw.length === 0) {
+        missing.push("groups");
+    }
+    if (missing.length > 0) {
+        throw new Error(`Missing required option(s): ${missing.join(", ")}. Run with --help.`);
+    }
+    return {
+        debug,
+        excludePathSegments: excludeRaw,
+        groupNames: groupsRaw,
+        inputPaths: inputRaw.map((dir) => resolveDir(cwd, dir)),
+        outputDir: resolveDir(cwd, outputRaw),
+    };
+};

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { createLogger, type Logger } from "./lib/create-logger.js";
+export { findGroupFiles } from "./lib/find-group-files.js";
+export { isGroupFileInScope } from "./lib/is-group-file-in-scope.js";
+export { isGroupJsonFile } from "./lib/is-group-json-file.js";
+export { mergeFilesIntoTree } from "./lib/merge-files-into-tree.js";
+export { mergeJsonTree } from "./lib/merge-json-tree.js";
+export { scanDirectory } from "./lib/scan-directory.js";
+export { writeTree } from "./lib/write-tree.js";

package/dist/index.js

@@ -0,0 +1,8 @@
+export { createLogger } from "./lib/create-logger.js";
+export { findGroupFiles } from "./lib/find-group-files.js";
+export { isGroupFileInScope } from "./lib/is-group-file-in-scope.js";
+export { isGroupJsonFile } from "./lib/is-group-json-file.js";
+export { mergeFilesIntoTree } from "./lib/merge-files-into-tree.js";
+export { mergeJsonTree } from "./lib/merge-json-tree.js";
+export { scanDirectory } from "./lib/scan-directory.js";
+export { writeTree } from "./lib/write-tree.js";

package/dist/lib/create-logger.d.ts

@@ -0,0 +1,2 @@
+export type Logger = (...args: unknown[]) => void;
+export declare const createLogger: (debug: boolean) => Logger;

package/dist/lib/create-logger.js

@@ -0,0 +1,8 @@
+export const createLogger = (debug) => {
+    if (!debug) {
+        return () => { };
+    }
+    return (...args) => {
+        console.info(...args);
+    };
+};

package/dist/lib/find-group-files.d.ts

@@ -0,0 +1,7 @@
+import type { Logger } from "./create-logger.js";
+export declare const findGroupFiles: ({ groupNames, inputPaths, logger, outputDir, }: {
+    groupNames: readonly string[];
+    inputPaths: string[];
+    logger: Logger;
+    outputDir: string;
+}) => string[];

package/dist/lib/find-group-files.js

@@ -0,0 +1,19 @@
+import { scanDirectory } from "./scan-directory.js";
+// `inputPaths` and `outputDir` are expected to be absolute. The library does
+// not re-resolve them — callers are responsible for normalization.
+export const findGroupFiles = ({ groupNames, inputPaths, logger, outputDir, }) => {
+    logger("Starting file scan...");
+    logger("Input paths:", inputPaths);
+    logger("Output dir:", outputDir);
+    logger("Looking for groups:", groupNames);
+    const results = inputPaths.flatMap((directory) => {
+        logger("Scanning directory:", directory);
+        return scanDirectory({
+            directory,
+            groupNames,
+            outputPath: outputDir,
+        });
+    });
+    logger("Total files found:", results.length);
+    return results;
+};

package/dist/lib/is-group-file-in-scope.d.ts

@@ -0,0 +1,6 @@
+export declare const isGroupFileInScope: ({ filePath, groupNames, inputPaths, outputDir, }: {
+    filePath: string;
+    groupNames: readonly string[];
+    inputPaths: string[];
+    outputDir: string;
+}) => boolean;

package/dist/lib/is-group-file-in-scope.js

@@ -0,0 +1,15 @@
+import path from "node:path";
+import { isGroupJsonFile } from "./is-group-json-file.js";
+// `path.relative` returns a non-`..` path only when `filePath` is inside `dir`,
+// which is safer than a substring check.
+const isInside = (filePath, dir) => {
+    const relative = path.relative(dir, filePath);
+    return (Boolean(relative) &&
+        !relative.startsWith("..") &&
+        !path.isAbsolute(relative));
+};
+export const isGroupFileInScope = ({ filePath, groupNames, inputPaths, outputDir, }) => {
+    const isInInputPath = inputPaths.some((inputPath) => isInside(filePath, inputPath));
+    const isInOutputPath = isInside(filePath, outputDir);
+    return (isInInputPath && !isInOutputPath && isGroupJsonFile(filePath, groupNames));
+};

package/dist/lib/is-group-json-file.d.ts

@@ -0,0 +1 @@
+export declare const isGroupJsonFile: (fileName: string, groupNames: readonly string[]) => boolean;

package/dist/lib/is-group-json-file.js

@@ -0,0 +1,6 @@
+import path from "node:path";
+export const isGroupJsonFile = (fileName, groupNames) => {
+    const ext = path.extname(fileName);
+    const name = path.basename(fileName, ext);
+    return ext === ".json" && groupNames.includes(name);
+};

package/dist/lib/merge-files-into-tree.d.ts

@@ -0,0 +1,9 @@
+interface NestedTree {
+    [key: string]: NestedTree | unknown;
+}
+export declare const mergeFilesIntoTree: ({ excludePathSegments, files, inputPaths, }: {
+    excludePathSegments: string[];
+    files: string[];
+    inputPaths: string[];
+}) => Record<string, NestedTree>;
+export {};

package/dist/lib/merge-files-into-tree.js

@@ -0,0 +1,44 @@
+import fs from "node:fs";
+import path from "node:path";
+const readJsonFile = (filePath) => {
+    let raw;
+    try {
+        raw = fs.readFileSync(filePath, "utf-8");
+    }
+    catch (error) {
+        throw new Error(`Failed to read ${filePath}`, { cause: error });
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`Failed to parse JSON in ${filePath}`, { cause: error });
+    }
+};
+export const mergeFilesIntoTree = ({ excludePathSegments, files, inputPaths, }) => files.reduce((tree, filePath) => {
+    const fileName = path.basename(filePath);
+    const groupName = path.basename(fileName, ".json");
+    // `inputPaths` are expected to be absolute. Pick the longest matching
+    // parent so nested input paths resolve to the deepest match.
+    const matchingInputPath = inputPaths
+        .filter((inputPath) => {
+        const relative = path.relative(inputPath, filePath);
+        return !(relative.startsWith("..") || path.isAbsolute(relative));
+    })
+        .sort((a, b) => b.length - a.length)[0];
+    if (!matchingInputPath) {
+        throw new Error(`File path ${filePath} does not match any input paths.`);
+    }
+    const relativeDir = path.relative(matchingInputPath, path.dirname(filePath));
+    const pathParts = relativeDir
+        .split(path.sep)
+        .filter((part) => part && !excludePathSegments.includes(part));
+    const fileContents = readJsonFile(filePath);
+    tree[groupName] ??= {};
+    const branch = pathParts.reduce((current, part) => {
+        current[part] ??= {};
+        return current[part];
+    }, tree[groupName]);
+    Object.assign(branch, fileContents);
+    return tree;
+}, {});

package/dist/lib/merge-json-tree.d.ts

@@ -0,0 +1,13 @@
+import type { Logger } from "./create-logger.js";
+export declare const mergeJsonTree: ({ excludePathSegments, groupNames, inputPaths, isShuttingDown, logger, outputDir, relevantChanges, }: {
+    excludePathSegments?: string[];
+    groupNames: readonly string[];
+    inputPaths: string[];
+    isShuttingDown?: () => boolean;
+    logger?: Logger;
+    outputDir: string;
+    relevantChanges?: string[];
+}) => {
+    sourceFiles: number;
+    written: string[];
+};

package/dist/lib/merge-json-tree.js

@@ -0,0 +1,39 @@
+import path from "node:path";
+import { findGroupFiles } from "./find-group-files.js";
+import { mergeFilesIntoTree } from "./merge-files-into-tree.js";
+import { writeTree } from "./write-tree.js";
+const noop = () => { };
+const alwaysFalse = () => false;
+export const mergeJsonTree = ({ excludePathSegments, groupNames, inputPaths, isShuttingDown = alwaysFalse, logger = noop, outputDir, relevantChanges = [], }) => {
+    if (relevantChanges.length > 0) {
+        const fileNames = relevantChanges.map((f) => path.basename(f)).join(", ");
+        logger(`Merging: ${fileNames}`);
+    }
+    logger("Getting group files from:", inputPaths);
+    const groupFiles = findGroupFiles({
+        groupNames,
+        inputPaths,
+        logger,
+        outputDir,
+    });
+    logger("Found group files count:", groupFiles.length);
+    if (groupFiles.length === 0) {
+        logger("No group files found!");
+        return { sourceFiles: 0, written: [] };
+    }
+    logger("Merging files into tree...");
+    const tree = mergeFilesIntoTree({
+        excludePathSegments: excludePathSegments ?? [],
+        files: groupFiles,
+        inputPaths,
+    });
+    logger("Tree top-level keys:", Object.keys(tree));
+    const { written } = writeTree({
+        isShuttingDown,
+        logger,
+        outputDir,
+        tree,
+    });
+    logger("Merge completed");
+    return { sourceFiles: groupFiles.length, written };
+};

package/dist/lib/scan-directory.d.ts

@@ -0,0 +1,5 @@
+export declare const scanDirectory: ({ directory, groupNames, outputPath, }: {
+    directory: string;
+    groupNames: readonly string[];
+    outputPath: string;
+}) => string[];

package/dist/lib/scan-directory.js

@@ -0,0 +1,33 @@
+import fs from "node:fs";
+import path from "node:path";
+import { isGroupJsonFile } from "./is-group-json-file.js";
+const SKIP_DIRS = new Set(["node_modules", ".next", ".turbo", ".git", "dist"]);
+const isInside = (childAbs, parentAbs) => {
+    const relative = path.relative(parentAbs, childAbs);
+    return (relative === "" || !(relative.startsWith("..") || path.isAbsolute(relative)));
+};
+// Recursively scan a directory for group JSON files. Skips well-known
+// build/output folders so we never re-ingest our own output.
+export const scanDirectory = ({ directory, groupNames, outputPath, }) => {
+    if (isInside(path.resolve(directory), path.resolve(outputPath))) {
+        return [];
+    }
+    const items = fs.readdirSync(directory, { withFileTypes: true });
+    return items.flatMap((item) => {
+        const fullPath = path.join(directory, item.name);
+        if (item.isDirectory()) {
+            if (SKIP_DIRS.has(item.name)) {
+                return [];
+            }
+            return scanDirectory({
+                directory: fullPath,
+                groupNames,
+                outputPath,
+            });
+        }
+        if (item.isFile() && isGroupJsonFile(item.name, groupNames)) {
+            return [fullPath];
+        }
+        return [];
+    });
+};

package/dist/lib/write-tree.d.ts

@@ -0,0 +1,9 @@
+import type { Logger } from "./create-logger.js";
+export declare const writeTree: ({ isShuttingDown, logger, outputDir, tree, }: {
+    isShuttingDown: () => boolean;
+    logger: Logger;
+    outputDir: string;
+    tree: Record<string, unknown>;
+}) => {
+    written: string[];
+};

package/dist/lib/write-tree.js

@@ -0,0 +1,49 @@
+import { renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+// Atomic write: stage to a temp file then rename over the destination.
+// POSIX `rename` is atomic on the same filesystem, so a reader (or a
+// SIGTERM mid-write) can never observe a truncated file.
+const atomicWrite = (destination, content) => {
+    const tempPath = `${destination}.${process.pid}.tmp`;
+    try {
+        writeFileSync(tempPath, content, "utf-8");
+        renameSync(tempPath, destination);
+    }
+    catch (error) {
+        try {
+            unlinkSync(tempPath);
+        }
+        catch {
+            // Temp may not exist if writeFileSync failed before creating it.
+        }
+        throw error;
+    }
+};
+export const writeTree = ({ isShuttingDown, logger, outputDir, tree, }) => {
+    const written = [];
+    if (isShuttingDown()) {
+        logger("Skipping write — process is shutting down");
+        return { written };
+    }
+    logger("Writing tree to disk...");
+    logger("Output dir:", outputDir);
+    for (const [groupName, branch] of Object.entries(tree)) {
+        if (isShuttingDown()) {
+            logger(`Aborting before ${groupName}.json — shutting down`);
+            return { written };
+        }
+        try {
+            const destination = resolve(outputDir, `${groupName}.json`);
+            const content = JSON.stringify(branch, null, 2);
+            logger(`Writing ${groupName}.json (${content.length} bytes)`);
+            atomicWrite(destination, content);
+            written.push(groupName);
+            logger(`Wrote ${groupName}.json`);
+        }
+        catch (error) {
+            logger(`Error writing ${groupName}.json:`, error);
+        }
+    }
+    logger("All files written");
+    return { written };
+};

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "json-tree-merge",
+  "version": "0.1.0",
+  "description": "Scan a directory tree for <group>.json files and merge them into one nested-object JSON per group. Framework-agnostic; great for next-intl locale folding.",
+  "keywords": [
+    "json",
+    "merge",
+    "tree",
+    "i18n",
+    "next-intl",
+    "locale",
+    "messages",
+    "cli"
+  ],
+  "license": "MIT",
+  "author": "sedlukha",
+  "homepage": "https://github.com/sedlukha/json-tree-merge#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sedlukha/json-tree-merge.git"
+  },
+  "bugs": {
+    "url": "https://github.com/sedlukha/json-tree-merge/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "json-tree-merge": "./dist/cli/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "rimraf dist && tsc -p tsconfig.build.json && node scripts/post-build.js",
+    "dev": "tsx src/cli/index.ts",
+    "start": "node dist/cli/index.js",
+    "test": "tsx --test test/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "rimraf": "^6.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.5.0"
+  }
+}