@menapo/vi18n 0.0.0-stage → 0.1.0

package/dist/init-BecCTvKi.js

@@ -0,0 +1,792 @@
+import { o as isDiagnosticError, t as CONFIG_FILE } from "./types-D3QGM8XO.js";
+import { i as idScheme } from "./validate-BxpupdAf.js";
+import { b as emptyCatalog, o as catalogLayout, p as serializeCatalog, s as catalogPath } from "./library-D5CWvTQs.js";
+import { n as loadConfig, r as resolveConfig } from "./load-gW-oJt1Q.js";
+import { t as VERSION } from "./version-BlyLGlOa.js";
+import { l as langFromId, u as parseModule } from "./worker-84U6uYB3.js";
+import { a as writeGenFile, r as GEN_FILE } from "./sync-CcVzger_.js";
+import { t as EXIT } from "./types-wSh9fCBY.js";
+import { t as CliExit } from "./project-Dwx7iPm6.js";
+import { createRequire } from "node:module";
+import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { randomBytes } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+//#region src/cli/scaffold.ts
+/**
+* The `<T>` components `vi18n init --rich` copies into a project (PLAN §4.1,
+* §5.16; INTERNALS §6 D213): Vue (one scoped slot per tag) and Svelte 5
+* (one snippet per tag). They are the user's code from then on, so nothing
+* framework-specific is published; listing the file in
+* `extraction.importSources` makes the scanner extract `<T message="…">`
+* (§2.4 "Rich-text components"). Both call `rich*()` while they render, so
+* the generated framework tracker re-renders them on a locale switch.
+*/
+const VUE_IMPORTS = [`import { rich, type MessageKey } from "@menapo/vi18n";`, `import { Fragment, h, useSlots, type VNode, type VNodeArrayChildren } from "vue";`].join("\n");
+const SVELTE_IMPORTS = [`  import { richParts, type MessageKey, type RichPart, type Values } from "@menapo/vi18n";`, `  import type { Snippet } from "svelte";`].join("\n");
+/** Vue 3.5: `<T message="Read the <link>docs</link>"><template #link="{ children }">…`. */
+const T_VUE = `<script setup lang="ts">
+// Scaffolded by \`vi18n init --rich\` (@menapo/vi18n). It is your code now: edit it freely.
+// A named slot renders each tag; render its children with <component :is="children" />:
+//
+//   <T message="Read the <link>docs</link>">
+//     <template #link="{ children }"><a href="/docs"><component :is="children" /></a></template>
+//   </T>
+//
+// The file is listed in extraction.importSources, so \`message\` (a literal) is extracted
+// like a rich() call; \`id\`, \`context\` and \`maxLength\` are read at build time only.
+${VUE_IMPORTS}
+
+// Vue checks props at runtime, so their types stay ones it can read: a message is the
+// text you write, or the id or dev descriptor the plugin puts in its place.
+const props = defineProps<{
+  message: string | object;
+  values?: Record<string, unknown>;
+  id?: string;
+  context?: string;
+  maxLength?: number;
+}>();
+const slots = useSlots();
+
+// A component declared once: rich() runs in its render, which the plugin's Vue tracker
+// re-runs on a locale switch, and an inline \`:is="() => …"\` would remount every render.
+const Message = () =>
+  rich<VNode | VNode[] | undefined>(props.message as MessageKey, {
+    ...props.values,
+    ...Object.fromEntries(
+      Object.entries(slots).map(([tag, slot]) => [
+        tag,
+        (children: VNodeArrayChildren) => slot?.({ children: h(Fragment, children) }),
+      ]),
+    ),
+  });
+<\/script>
+
+<template><Message /></template>
+`;
+/** Svelte 5 (runes): \`<T message="…">{#snippet link(children)}…{/snippet}</T>\`. */
+const T_SVELTE = `<script lang="ts">
+  // Scaffolded by \`vi18n init --rich\` (@menapo/vi18n). It is your code now: edit it freely.
+  // A snippet renders each tag and receives the tag's children as a snippet:
+  //
+  //   <T message="Read the <link>docs</link>">
+  //     {#snippet link(children)}<a href="/docs">{@render children()}</a>{/snippet}
+  //   </T>
+  //
+  // The file is listed in extraction.importSources, so \`message\` (a literal) is extracted
+  // like a rich() call. In Svelte markup \`{\` starts an expression: write a message with
+  // arguments as a string, message={"Hello {name}"}, and pass values={{ name }}.
+${SVELTE_IMPORTS}
+
+  let {
+    message,
+    values,
+    ...tags
+  }: {
+    message: MessageKey;
+    values?: Values;
+    id?: string;
+    context?: string;
+    maxLength?: number;
+    [tag: string]: unknown;
+  } = $props();
+<\/script>
+
+<!-- richParts() runs in the template, so the plugin's Svelte tracker re-renders on a switch. -->
+{#snippet render(parts: RichPart[])}
+  {#each parts as part}
+    {#if typeof part === "string"}{part}{:else}
+      {@const tag = tags[part.tag] as Snippet<[Snippet]> | undefined}
+      {#snippet children()}{@render render(part.children)}{/snippet}
+      {#if tag}{@render tag(children)}{:else}{@render children()}{/if}
+    {/if}
+  {/each}
+{/snippet}
+
+{@render render(richParts(message, values))}
+`;
+//#endregion
+//#region src/cli/commands/init.ts
+/**
+* `vi18n init [--yes] [--format po|json] [--locales a,b] [--source-locale a] [--rich]`
+* (INTERNALS §2.14, PLAN §5.19): the way into a project. Writes
+* `vi18n.config.ts` (never over an existing one), adds the plugin to the
+* exported config's `plugins` in `vite.config.*`, creates every locale's
+* empty catalog, writes `vi18n.gen.ts` and lists it in the tsconfig that
+* compiles the sources. `--rich` copies the `<T>` components for the
+* project's Vue and Svelte and lists them in `extraction.importSources`
+* (§6 D213); in a configured project it does only that. Each step
+* that cannot edit a file safely prints the snippet instead.
+*/
+const VITE_CONFIGS = [
+	"vite.config.ts",
+	"vite.config.mts",
+	"vite.config.js",
+	"vite.config.mjs",
+	"vite.config.cts",
+	"vite.config.cjs"
+];
+const PLUGIN_IMPORT = "import vi18n from \"@menapo/vi18n/vite\";";
+/** Source directories of the supported frameworks, in the order `init` looks for them. */
+const SOURCE_DIRS = ["src", "app"];
+/** Markers `findConfigFile` stops at; `init` does not look for a tsconfig above them either. */
+const WORKSPACE_MARKERS = ["pnpm-workspace.yaml", ".git"];
+async function init(ctx, flags) {
+	const dir = resolve(ctx.global.cwd);
+	const configFile = ctx.global.config === null ? join(dir, CONFIG_FILE) : resolve(dir, ctx.global.config);
+	const root = dirname(configFile);
+	if (flags.rich && existsSync(configFile)) return scaffoldOnly(ctx, root, configFile);
+	const input = configInput(await ask(ctx, flags), root);
+	const components = flags.rich ? richComponents(root) : [];
+	if (flags.rich && components.length === 0) throw noRichFramework();
+	if (components.length > 0) input.extraction = { importSources: components.map((c) => c.specifier) };
+	let config;
+	try {
+		config = resolveConfig(input, root, configFile);
+	} catch (error) {
+		if (isDiagnosticError(error)) throw new CliExit(EXIT.usage, [error.diagnostic]);
+		throw error;
+	}
+	const data = {
+		wrote: [],
+		skipped: [],
+		manual: [],
+		sourceLocale: config.sourceLocale,
+		locales: config.locales,
+		format: config.catalogs.format
+	};
+	const rel = (file) => relative(root, file).split(sep).join("/") || ".";
+	if (existsSync(configFile)) {
+		ctx.out.report([{
+			code: "config-invalid",
+			severity: "error",
+			message: `${rel(configFile)} already exists; vi18n init never overwrites it (edit it, or run vi18n extract)`,
+			file: configFile
+		}]);
+		return {
+			exitCode: EXIT.failure,
+			data
+		};
+	}
+	await atomicWrite(configFile, configSource(input));
+	data.wrote.push(rel(configFile));
+	if (flags.rich) await writeComponents(root, components, data, rel);
+	await addPlugin(root, data, rel);
+	const layout = catalogLayout(config);
+	const header = {
+		idScheme: idScheme(config.ids.length),
+		sourceLocale: config.sourceLocale
+	};
+	for (const locale of config.locales) {
+		const path = catalogPath(config, locale);
+		if (existsSync(path)) {
+			data.skipped.push(rel(path));
+			continue;
+		}
+		const isSourceLocale = locale === config.sourceLocale;
+		const text = serializeCatalog(emptyCatalog(locale, layout, header), {
+			isSourceLocale,
+			version: VERSION
+		});
+		await mkdir(dirname(path), { recursive: true });
+		await atomicWrite(path, text);
+		data.wrote.push(rel(path));
+	}
+	const gen = join(root, GEN_FILE);
+	if (await writeGenFile(config)) data.wrote.push(rel(gen));
+	await addToTsconfig(root, gen, data, rel);
+	printSummary(ctx, data);
+	ctx.out.result(`\nNext: wrap strings in t("…") and run vi18n extract.`);
+	return {
+		exitCode: EXIT.ok,
+		data
+	};
+}
+function printSummary(ctx, data) {
+	for (const file of data.wrote) ctx.out.result(`created ${file}`);
+	for (const file of data.skipped) ctx.out.result(`kept ${file}`);
+	for (const { file, snippet } of data.manual) ctx.out.result(`\nAdd to ${file} by hand:\n${snippet}`);
+}
+/**
+* One component per framework the root `package.json` depends on, beside
+* the project's other shared components: `<src>/lib` (SvelteKit's `$lib`)
+* when it exists, else `<src>/components`. React, Preact and Solid get
+* none: `rich()` returns what JSX renders, and the `<T>` macro is compiled
+* away (§6 D213).
+*/
+function richComponents(root) {
+	let deps = {};
+	try {
+		const pkg = JSON.parse(readFileSyncSafe(join(root, "package.json")));
+		deps = {
+			...pkg.dependencies,
+			...pkg.devDependencies
+		};
+	} catch {}
+	const sourceDir = SOURCE_DIRS.find((name) => existsSync(join(root, name)));
+	const base = sourceDir === void 0 ? "" : sourceDir + "/";
+	const dir = existsSync(join(root, base + "lib")) ? base + "lib" : base + "components";
+	const out = [];
+	if ("vue" in deps) out.push({
+		file: `${dir}/T.vue`,
+		specifier: `./${dir}/T.vue`,
+		source: T_VUE
+	});
+	if ("svelte" in deps) out.push({
+		file: `${dir}/T.svelte`,
+		specifier: `./${dir}/T.svelte`,
+		source: T_SVELTE
+	});
+	return out;
+}
+function noRichFramework() {
+	return usage("--rich copies a <T> component for Vue and Svelte, and package.json depends on neither; in JSX, rich() and the <T> macro need no component");
+}
+function readFileSyncSafe(file) {
+	return existsSync(file) ? readFileSync(file, "utf8") : "";
+}
+/** Copies the components, never over a file that exists. */
+async function writeComponents(root, components, data, rel) {
+	for (const component of components) {
+		const path = join(root, component.file);
+		if (existsSync(path)) {
+			data.skipped.push(rel(path));
+			continue;
+		}
+		await mkdir(dirname(path), { recursive: true });
+		await atomicWrite(path, component.source);
+		data.wrote.push(rel(path));
+	}
+}
+/**
+* `--rich` in a configured project: copy the components and, unless the
+* config already names them, print the `importSources` entry to add (the
+* config is the user's code, and `init` edits only what it can parse safely).
+*/
+async function scaffoldOnly(ctx, root, configFile) {
+	const rel = (file) => relative(root, file).split(sep).join("/") || ".";
+	let config;
+	try {
+		config = await loadConfig({
+			cwd: root,
+			configFile
+		});
+	} catch (error) {
+		if (isDiagnosticError(error)) throw new CliExit(EXIT.usage, [error.diagnostic]);
+		throw error;
+	}
+	const data = {
+		wrote: [],
+		skipped: [],
+		manual: [],
+		sourceLocale: config.sourceLocale,
+		locales: config.locales,
+		format: config.catalogs.format
+	};
+	const components = richComponents(root);
+	if (components.length === 0) throw noRichFramework();
+	await writeComponents(root, components, data, rel);
+	const text = readFileSyncSafe(configFile);
+	const missing = components.filter((c) => !text.includes(c.specifier.slice(2)));
+	if (missing.length > 0) data.manual.push({
+		file: rel(configFile),
+		snippet: `extraction: { importSources: [${missing.map((c) => JSON.stringify(c.specifier)).join(", ")}] },`
+	});
+	printSummary(ctx, data);
+	return {
+		exitCode: EXIT.ok,
+		data
+	};
+}
+/**
+* Flags first; questions only for what they leave open, only on a terminal,
+* and never with `--yes` or `--json` (an agent or CI must not hang).
+*/
+async function ask(ctx, flags) {
+	const prompt = flags.yes || ctx.global.json ? void 0 : ctx.io.prompt;
+	let locales = flags.locales;
+	let sourceLocale = flags.sourceLocale;
+	let format = flags.format;
+	if (prompt !== void 0) {
+		if (sourceLocale === null) sourceLocale = (await prompt("Source locale (the language of the strings in your code)", locales[0] ?? "en")).trim();
+		if (locales.length === 0) locales = (await prompt("Locales, comma-separated", sourceLocale || "en")).split(",").map((l) => l.trim()).filter((l) => l !== "");
+		if (format === null) {
+			const answer = (await prompt("Catalog format (po or json)", "po")).trim().toLowerCase();
+			if (answer !== "po" && answer !== "json") throw usage(`catalog format must be po or json, not "${answer}"`);
+			format = answer;
+		}
+	}
+	sourceLocale = sourceLocale || locales[0] || "en";
+	if (!locales.includes(sourceLocale)) locales = [sourceLocale, ...locales];
+	for (const locale of locales) {
+		let canonical;
+		try {
+			canonical = Intl.getCanonicalLocales(locale)[0];
+		} catch {
+			canonical = void 0;
+		}
+		if (canonical !== locale) throw usage(canonical === void 0 ? `"${locale}" is not a BCP 47 locale` : `"${locale}" is not in canonical form; use "${canonical}"`);
+	}
+	return {
+		sourceLocale,
+		locales: [...new Set(locales)],
+		format: format ?? "po"
+	};
+}
+function usage(message) {
+	return new CliExit(EXIT.usage, [{
+		code: "config-invalid",
+		severity: "error",
+		message
+	}]);
+}
+/** Only what differs from the defaults, so the file stays a short starting point. */
+function configInput(answers, root) {
+	const input = {
+		sourceLocale: answers.sourceLocale,
+		locales: answers.locales
+	};
+	if (answers.format === "json") input.catalogs = { format: "json" };
+	const sourceDir = SOURCE_DIRS.find((name) => existsSync(join(root, name)));
+	if (sourceDir === void 0) input.project = { include: ["."] };
+	else if (sourceDir !== "src") input.project = { include: [sourceDir] };
+	return input;
+}
+function configSource(input) {
+	const lines = [
+		"import { defineConfig } from \"@menapo/vi18n/config\";",
+		"",
+		"export default defineConfig({",
+		`  sourceLocale: ${JSON.stringify(input.sourceLocale)},`,
+		`  locales: [${(input.locales ?? []).map((l) => JSON.stringify(l)).join(", ")}],`
+	];
+	if (input.catalogs?.format === "json") lines.push("  catalogs: { format: \"json\" },");
+	if (input.project?.include !== void 0) lines.push(`  project: { include: [${input.project.include.map((p) => JSON.stringify(p)).join(", ")}] },`);
+	const sources = input.extraction?.importSources;
+	if (sources !== void 0) lines.push(`  extraction: { importSources: [${sources.map((p) => JSON.stringify(p)).join(", ")}] },`);
+	lines.push("});", "");
+	return lines.join("\n");
+}
+/**
+* Adds the import after the last top-level import and `vi18n()` as the first
+* element of the exported config's `plugins` array. Anything less certain
+* (no array, a config built by a helper, CommonJS) prints the snippet
+* instead of guessing.
+*/
+async function addPlugin(root, data, rel) {
+	const file = VITE_CONFIGS.map((name) => join(root, name)).find((path) => existsSync(path));
+	const snippet = `${PLUGIN_IMPORT}\n\n// in defineConfig({ … }):\nplugins: [vi18n(), /* … */],`;
+	if (file === void 0) {
+		data.manual.push({
+			file: "vite.config.ts",
+			snippet
+		});
+		return;
+	}
+	const text = await readFile(file, "utf8");
+	if (text.includes("@menapo/vi18n/vite")) {
+		data.skipped.push(rel(file));
+		return;
+	}
+	const edited = withPlugin(text, file);
+	if (edited === null) {
+		data.manual.push({
+			file: rel(file),
+			snippet
+		});
+		return;
+	}
+	await atomicWrite(file, edited);
+	data.wrote.push(rel(file));
+}
+function unwrap(node) {
+	let current = node;
+	while (current.type === "TSAsExpression" || current.type === "TSSatisfiesExpression" || current.type === "TSNonNullExpression" || current.type === "ParenthesizedExpression") current = current.expression;
+	return current;
+}
+/**
+* The object literal a config module exports: `export default {…}`,
+* `defineConfig({…})`, `defineConfig(() => ({…}))`, a function returning
+* one, or a top-level `const` holding any of these. Null for anything else.
+*/
+function exportedConfig(body) {
+	const declared = (name) => {
+		for (const statement of body) {
+			const declaration = statement.type === "ExportNamedDeclaration" ? statement.declaration : statement;
+			if (declaration?.type !== "VariableDeclaration") continue;
+			for (const declarator of declaration.declarations) {
+				const id = declarator.id;
+				if (id.type === "Identifier" && id.name === name && declarator.init != null) return declarator.init;
+			}
+		}
+		return null;
+	};
+	const returned = (block) => {
+		let found = null;
+		for (const statement of block.body) if (statement.type === "ReturnStatement" && statement.argument != null) found = statement.argument;
+		return found;
+	};
+	const resolveNode = (node, depth) => {
+		if (node === null || depth > 6) return null;
+		const n = unwrap(node);
+		switch (n.type) {
+			case "ObjectExpression": return n;
+			case "CallExpression": {
+				const first = n.arguments[0];
+				return first === void 0 || first.type === "SpreadElement" ? null : resolveNode(first, depth + 1);
+			}
+			case "ArrowFunctionExpression":
+			case "FunctionExpression":
+			case "FunctionDeclaration": {
+				const fnBody = n.body;
+				return fnBody.type === "BlockStatement" ? resolveNode(returned(fnBody), depth + 1) : resolveNode(fnBody, depth + 1);
+			}
+			case "Identifier": return resolveNode(declared(n.name), depth + 1);
+			default: return null;
+		}
+	};
+	for (const statement of body) if (statement.type === "ExportDefaultDeclaration") return resolveNode(statement.declaration, 0);
+	return null;
+}
+/** Where an import goes in a module without one: after a hashbang and leading comments. */
+function leadingEnd(text) {
+	let at = text.startsWith("#!") ? text.indexOf("\n") + 1 || text.length : 0;
+	for (;;) {
+		const space = /^\s*/.exec(text.slice(at))?.[0].length ?? 0;
+		const next = at + space;
+		if (text.startsWith("//", next)) {
+			const end = text.indexOf("\n", next);
+			if (end === -1) return text.length;
+			at = end + 1;
+		} else if (text.startsWith("/*", next)) {
+			const end = text.indexOf("*/", next + 2);
+			if (end === -1) return at;
+			at = end + 2;
+			if (text[at] === "\r") at++;
+			if (text[at] === "\n") at++;
+		} else return at;
+	}
+}
+/**
+* The edited `vite.config.*` text, or null when the exported config has no
+* `plugins` array to extend. Parsed, so a `plugins: [` in a comment, a string
+* or a nested object (`build.rollupOptions.plugins`) is never the one edited;
+* CommonJS configs are left alone, since an `import` would not run there.
+*/
+function withPlugin(text, file = "vite.config.ts") {
+	const ext = extname(file);
+	if (ext === ".cjs" || ext === ".cts") return null;
+	let program;
+	try {
+		program = parseModule(text, langFromId(file), basename(file)).program;
+	} catch (error) {
+		if (isDiagnosticError(error)) return null;
+		throw error;
+	}
+	const body = program.body;
+	const config = exportedConfig(body);
+	if (config === null) return null;
+	const property = config.properties.find((p) => {
+		if (p.type !== "Property" || p.computed === true) return false;
+		const key = p.key;
+		return (key.type === "Identifier" ? key.name : key.value) === "plugins";
+	});
+	if (property === void 0) return null;
+	const array = unwrap(property.value);
+	if (array.type !== "ArrayExpression") return null;
+	const at = array.start + 1;
+	const rest = text.slice(at);
+	let plugin;
+	if (array.elements.length === 0 && text.slice(at, array.end - 1).trim() === "") plugin = {
+		at,
+		text: "vi18n()"
+	};
+	else {
+		const multiline = /^[ \t]*\r?\n([ \t]*)/.exec(rest);
+		plugin = multiline === null ? {
+			at,
+			text: "vi18n(), "
+		} : {
+			at,
+			text: "\n" + multiline[1] + "vi18n(),"
+		};
+	}
+	let out = text.slice(0, plugin.at) + plugin.text;
+	out += plugin.text === "vi18n()" ? text.slice(array.end - 1) : rest;
+	let lastImport = null;
+	for (const statement of body) if (statement.type === "ImportDeclaration") lastImport = statement;
+	if (lastImport !== null && lastImport.end <= plugin.at) return `${out.slice(0, lastImport.end)}\n${PLUGIN_IMPORT}${out.slice(lastImport.end)}`;
+	if (lastImport !== null) return null;
+	const insertAt = leadingEnd(text);
+	return `${out.slice(0, insertAt)}${PLUGIN_IMPORT}\n${out.slice(insertAt)}`;
+}
+/**
+* Lists `vi18n.gen.ts` in the `include` of the tsconfig that compiles the
+* sources, when that file is plain JSON (a JSONC file with comments is left
+* alone: rewriting it would drop them). Without `include` or `files` of its
+* own or through `extends`, TypeScript already sees every file; with only
+* inherited ones, the snippet to add is printed. A config that has `files` but no
+* `include` never gets an `include` added (the snippet is printed), and a
+* solution-style config (`references` and nothing of its own to compile, as
+* create-vite's) is never edited: adding `include` there would make it a
+* project of its own, which breaks `tsc -b`. Its reference whose `include`
+* covers the source directory is the one edited instead.
+*/
+async function addToTsconfig(root, gen, data, rel) {
+	const file = await nearestTsconfig(root);
+	if (file === null) return;
+	const read = await readTsconfig(file);
+	if (read === null) return;
+	const sourceDir = SOURCE_DIRS.map((name) => join(root, name)).find((dir) => existsSync(dir)) ?? root;
+	const json = read.json;
+	if (json === null) {
+		const entry = relative(dirname(file), gen).split(sep).join("/");
+		data.manual.push({
+			file: rel(file),
+			snippet: `"include": [/* … */ ${JSON.stringify(entry)}]`
+		});
+		return;
+	}
+	if (typeof json !== "object" || Array.isArray(json)) return;
+	const references = Array.isArray(json.references) ? json.references : [];
+	const ownFiles = Array.isArray(json.files) ? json.files : null;
+	if (!(references.length > 0 && json.include === void 0 && (json.files === void 0 || ownFiles?.length === 0))) {
+		await listGenFile(file, read, gen, data, rel);
+		return;
+	}
+	let first = null;
+	for (const reference of references) {
+		const path = reference?.path;
+		if (typeof path !== "string") continue;
+		let target = resolve(dirname(file), path);
+		try {
+			if ((await stat(target)).isDirectory()) target = join(target, "tsconfig.json");
+		} catch {
+			continue;
+		}
+		const referenced = await readTsconfig(target);
+		if (referenced === null) continue;
+		first ??= target;
+		const include = referenced.json?.include;
+		if (Array.isArray(include) && covers(include, dirname(target), sourceDir)) {
+			await listGenFile(target, referenced, gen, data, rel);
+			return;
+		}
+	}
+	const entry = relative(dirname(first ?? file), gen).split(sep).join("/");
+	data.manual.push({
+		file: rel(first ?? file),
+		snippet: `"include": [/* … */ ${JSON.stringify(entry)}]`
+	});
+}
+/** Adds the entry to one config's `include`, or prints the snippet when that cannot be done safely. */
+async function listGenFile(file, read, gen, data, rel) {
+	const entry = relative(dirname(file), gen).split(sep).join("/");
+	const json = read.json;
+	if (typeof json !== "object" || json === null || Array.isArray(json)) return;
+	if (json.include === void 0 && json.files === void 0) {
+		const snippet = await inheritedSnippet(file, json, gen, entry);
+		if (snippet !== null) data.manual.push({
+			file: rel(file),
+			snippet
+		});
+		return;
+	}
+	if (json.include === void 0) {
+		data.manual.push({
+			file: rel(file),
+			snippet: `"files": [/* … */ ${JSON.stringify(entry)}]`
+		});
+		return;
+	}
+	const include = Array.isArray(json.include) ? json.include : [];
+	if (include.includes(entry) || include.includes("./" + entry)) {
+		data.skipped.push(rel(file));
+		return;
+	}
+	if (!read.plain) {
+		data.manual.push({
+			file: rel(file),
+			snippet: `"include": [/* … */ ${JSON.stringify(entry)}]`
+		});
+		return;
+	}
+	json.include = [...include, entry];
+	const text = read.text;
+	const indent = /\n([ \t]+)\S/.exec(text.slice(text.indexOf("{") + 1))?.[1] ?? "  ";
+	await atomicWrite(file, JSON.stringify(json, null, indent) + (text.endsWith("\n") ? "\n" : ""));
+	data.wrote.push(rel(file));
+}
+/**
+* The `include` snippet for a tsconfig with no `include` or `files` of its
+* own, or null when TypeScript already compiles the generated file. Such a
+* config takes both from `extends` (SvelteKit's `.svelte-kit/tsconfig.json`
+* lists globs under `../src` and a few files), and an `include` written here
+* replaces the inherited one, so the snippet repeats its entries, rebased to
+* this file. Inherited `files` stay: TypeScript adds an own `include` to them.
+*/
+async function inheritedSnippet(file, json, gen, entry) {
+	if (json.extends === void 0) return null;
+	const include = await inherited(file, json, "include", /* @__PURE__ */ new Set([file]));
+	const files = await inherited(file, json, "files", /* @__PURE__ */ new Set([file]));
+	if (include === void 0 || files === void 0) return `"include": [/* every entry "extends" gives it (none given: nothing to add) */ ${JSON.stringify(entry)}]`;
+	if (include === null && files === null) return null;
+	const target = toSlash(gen);
+	if (files !== null && files.list.some((f) => toSlash(resolve(files.base, f)) === target)) return null;
+	if (include !== null && include.list.some((p) => matchesInclude(p, include.base, target))) return null;
+	return `"include": [${[...include === null ? [] : include.list.map((p) => toSlash(relative(dirname(file), resolve(include.base, p))) || "."), entry].map((p) => JSON.stringify(p)).join(", ")}]`;
+}
+/**
+* `key` as `file` inherits it through `extends` (later bases override
+* earlier ones, as in TypeScript), with the directory its paths are relative
+* to; null when no base has it; undefined when a base cannot be read.
+*/
+async function inherited(file, json, key, seen) {
+	const bases = typeof json.extends === "string" ? [json.extends] : Array.isArray(json.extends) ? json.extends : [];
+	let found = null;
+	for (const spec of bases) {
+		const target = typeof spec === "string" ? resolveExtends(file, spec) : null;
+		if (target === null || seen.has(target)) return void 0;
+		const base = (await readTsconfig(target))?.json;
+		if (typeof base !== "object" || base === null || Array.isArray(base)) return void 0;
+		const value = base[key];
+		let result;
+		if (value === void 0) result = await inherited(target, base, key, /* @__PURE__ */ new Set([...seen, target]));
+		else if (Array.isArray(value) && value.every((v) => typeof v === "string")) result = {
+			list: value,
+			base: dirname(target)
+		};
+		else return void 0;
+		if (result === void 0) return void 0;
+		if (result !== null) found = result;
+	}
+	return found;
+}
+/** The file an `extends` entry names, as TypeScript finds it; null when it cannot be found. */
+function resolveExtends(file, spec) {
+	if (spec.startsWith("./") || spec.startsWith("../") || isAbsolute(spec)) {
+		const path = resolve(dirname(file), spec);
+		if (existsSync(path)) return path;
+		return !path.endsWith(".json") && existsSync(path + ".json") ? path + ".json" : null;
+	}
+	const require = createRequire(file);
+	const candidates = spec.endsWith(".json") ? [spec] : [`${spec}.json`, `${spec}/tsconfig.json`];
+	for (const candidate of candidates) try {
+		return require.resolve(candidate);
+	} catch {}
+	return null;
+}
+function toSlash(path) {
+	return path.split(sep).join("/");
+}
+/**
+* Whether a tsconfig `include` pattern (relative to `base`) takes `file`
+* (absolute, `/`-separated): `*` and `?` within a segment, `**` across
+* directories, and a pattern without wildcards as a file or a directory.
+*/
+function matchesInclude(pattern, base, file) {
+	const absolute = toSlash(resolve(base, pattern));
+	if (!/[*?]/.test(pattern)) return file === absolute || file.startsWith(absolute + "/");
+	let regex = "";
+	for (let i = 0; i < absolute.length; i++) {
+		const c = absolute[i];
+		if (c === "*" && absolute[i + 1] === "*") {
+			const slash = absolute[i + 2] === "/";
+			regex += slash ? "(?:[^/]*/)*" : ".*";
+			i += slash ? 2 : 1;
+		} else if (c === "*") regex += "[^/]*";
+		else if (c === "?") regex += "[^/]";
+		else regex += /[\\^$.+()[\]{}|]/.test(c) ? "\\" + c : c;
+	}
+	return new RegExp(`^${regex}$`).test(file);
+}
+/**
+* A tsconfig as JSON when it is plain JSON (`plain`: safe to rewrite), else
+* read leniently past comments and trailing commas (only to look at it);
+* null when it cannot be read at all.
+*/
+async function readTsconfig(file) {
+	let text;
+	try {
+		text = await readFile(file, "utf8");
+	} catch {
+		return null;
+	}
+	try {
+		return {
+			json: JSON.parse(text),
+			text,
+			plain: true
+		};
+	} catch {}
+	try {
+		return {
+			json: JSON.parse(stripJsonc(text)),
+			text,
+			plain: false
+		};
+	} catch {
+		return {
+			json: null,
+			text,
+			plain: false
+		};
+	}
+}
+/** JSONC → JSON: comments and trailing commas outside strings removed. */
+function stripJsonc(text) {
+	let out = "";
+	for (let i = 0; i < text.length; i++) {
+		const c = text[i];
+		if (c === "\"") {
+			let j = i + 1;
+			while (j < text.length && text[j] !== "\"") j += text[j] === "\\" ? 2 : 1;
+			out += text.slice(i, j + 1);
+			i = j;
+		} else if (c === "/" && text[i + 1] === "/") {
+			while (i < text.length && text[i] !== "\n") i++;
+			out += "\n";
+		} else if (c === "/" && text[i + 1] === "*") {
+			const end = text.indexOf("*/", i + 2);
+			i = end === -1 ? text.length : end + 1;
+		} else out += c;
+	}
+	return out.replace(/,(\s*[}\]])/g, "$1");
+}
+/** Whether an `include` list reaches `dir`: a pattern's static prefix contains it. */
+function covers(include, base, dir) {
+	for (const pattern of include) {
+		if (typeof pattern !== "string") continue;
+		const segments = [];
+		for (const segment of pattern.split("/")) {
+			if (/[*?[{]/.test(segment)) break;
+			segments.push(segment);
+		}
+		const prefix = resolve(base, ...segments);
+		const rel = relative(prefix, dir);
+		if (rel === "" || !rel.startsWith("..") && !isAbsolute(rel)) return true;
+	}
+	return false;
+}
+async function nearestTsconfig(from) {
+	for (let dir = from;; dir = dirname(dir)) {
+		const file = join(dir, "tsconfig.json");
+		try {
+			if ((await stat(file)).isFile()) return file;
+		} catch {}
+		if (WORKSPACE_MARKERS.some((marker) => existsSync(join(dir, marker)))) return null;
+		if (dirname(dir) === dir) return null;
+	}
+}
+async function atomicWrite(path, content) {
+	const temp = `${path}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`;
+	try {
+		await writeFile(temp, content);
+		await rename(temp, path);
+	} catch (error) {
+		await rm(temp, { force: true });
+		throw error;
+	}
+}
+//#endregion
+export { init };