fluent-transpiler 0.4.1 → 0.6.0

package/README.md

@@ -35,19 +35,21 @@ npm i -D fluent-transpiler
 ## CLI
 
 ```bash
-Usage: ftl [options] <input>
+Usage: ftl [options] <inputs...>
 
 Compile Fluent (.ftl) files to JavaScript (.js or .mjs)
 
 Arguments:
-  input                                   Path to the Fluent file to compile
+  inputs                                  Paths to the Fluent file(s) to compile.
+                                          Multiple files are joined in order;
+                                          ids must be unique across the set.
 
 Options:
   --locale <locale...>                    What locale(s) to be used. Multiple can be set to allow for fallback. i.e. en-CA
   --comments                              Include comments in output file.
   --include-key <keys...>                 Allowed messages to be included. Default to include all.
   --exclude-key <keys...>                 Ignored messages to be excluded. Default to exclude none.
-  --exclude-value <value>                 Set message to an empty string when it contains this value.
+  --exclude-value <value>                 Set message to an empty string when it equals this value.
   --variable-notation <variableNotation>  What variable notation to use with exports (choices: "camelCase", "pascalCase", "constantCase",
                                           "snakeCase", default: "camelCase")
   --disable-minify                        If disabled, all exported messages will have the same interface `(params) => ({value, attributes})`.
@@ -62,15 +64,19 @@ Options:
 | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | locale           | What locale(s) to be used. Multiple can be set to allow for fallback. i.e. `en-CA`                                                                                                                                                                           |
 | comments         | Include comments in output file. Default: `true`                                                                                                                                                                                                             |
-| includeKey       | Array of message keys to include. Default: `[]` (include all)                                                                                                                                                                                                |
-| excludeKey       | Array of message keys to exclude. Default: `[]` (exclude none)                                                                                                                                                                                               |
-| excludeValue     | Set message to an empty string when it contains this value. Default: `undefined`                                                                                                                                                                             |
+| includeKey       | Array of message keys to include; matches the exported name (`msgOne`) or the original FTL id (`msg-one`). Non-included messages remain private consts so references keep working. Default: `[]` (include all)                                                                                                                                                                                                |
+| excludeKey       | Array of message keys to exclude; matches the exported name (`msgOne`) or the original FTL id (`msg-one`). Excluded messages remain private consts so references keep working. Default: `[]` (exclude none)                                                                                                                                                                                               |
+| excludeValue     | Set message to an empty string when it equals this value. Default: `undefined`                                                                                                                                                                             |
 | disableMinify    | If disabled, all exported messages will have the same interface `(params) => ({value, attributes})`. Default: each exported message could be a different type based on what is needed to generate the message (`string`, `object`, `() => ''`, `() => ({})`) |
 | errorOnJunk      | Throw error when `Junk` is parsed. Default: `true`                                                                                                                                                                                                           |
 | variableNotation | What variable notation to use with exports. Choices: `camelCase`, `pascalCase`, `snakeCase`, `constantCase`. Default: `camelCase`                                                                                                                            |
 | useIsolating     | Wrap placeable with \u2068 and \u2069. Default: `false`                                                                                                                                                                                                      |
+| params           | Parameter name used in generated message functions. Default: `params`                                                                                                                                                                                        |
 | exportDefault    | Allows the overwriting of the `export default` to allow for custom uses. Default: See code                                                                                                                                                                   |
 
+Messages and terms must be defined before they are referenced; referencing a
+later definition is a compile error.
+
 ```javascript
 import { readFile, writeFile } from 'node:fs/promises'
 import fluentTranspiler from 'fluent-transpiler'
@@ -79,3 +85,20 @@ const ftl = await readFile('./path/to/en.ftl', { encoding: 'utf8' })
 const js = fluentTranspiler(ftl, { locale: 'en-CA' })
 await writeFile('./path/to/en.mjs', js, 'utf8')
 ```
+
+### Joining multiple files
+
+`compile` also accepts an array of source strings, and `compileFiles` reads and
+joins files from disk. Sources are concatenated in the order supplied; top-level
+message and term ids must be unique across the set.
+
+```javascript
+import { writeFile } from 'node:fs/promises'
+import { compileFiles } from 'fluent-transpiler'
+
+const js = await compileFiles(
+  ['./common.ftl', './brand.ftl', './app.ftl'],
+  { locale: 'en-CA' },
+)
+await writeFile('./en.mjs', js, 'utf8')
+```

package/cli.js

@@ -2,88 +2,11 @@
 // Copyright 2026 will Farrell, and fluent-transpiler contributors.
 // SPDX-License-Identifier: MIT
 
-import { readFile, stat, writeFile } from "node:fs/promises";
-import { Command, Option } from "commander";
-import compile from "./index.js";
-
-const fileExists = async (filepath) => {
-	const stats = await stat(filepath);
-	if (!stats.isFile()) {
-		throw new Error(`${filepath} is not a file`);
-	}
-};
-
-new Command()
-	.name("ftl")
-	.description("Compile Fluent (.ftl) files to JavaScript (.js or .mjs)")
-	.argument("<input>", "Path to the Fluent file to compile")
-	.requiredOption(
-		"--locale <locale...>",
-		"What locale(s) to be used. Multiple can be set to allow for fallback. i.e. en-CA",
-	)
-	.addOption(
-		new Option("--comments", "Include comments in output file.").preset(true),
-	)
-	.addOption(
-		new Option(
-			"--include-key <includeMessageKey...>",
-			"Allowed messages to be included. Default to include all.",
-		),
-	)
-	.addOption(
-		new Option(
-			"--exclude-key <excludeMessageKey...>",
-			"Ignored messages to be excluded. Default to exclude none.",
-		),
-	)
-	.addOption(
-		new Option(
-			"--exclude-value <excludeMessageValue>",
-			"Set message to an empty string when it contains this value. Default to not allowing empty strings.",
-		),
-	)
-	.addOption(
-		new Option(
-			"--variable-notation <variableNotation>",
-			"What variable notation to use with exports",
-		)
-			.choices(["camelCase", "pascalCase", "constantCase", "snakeCase"])
-			.default("camelCase"),
-	)
-	.addOption(
-		new Option(
-			"--disable-minify",
-			"If disabled, all exported messages will have the same interface `(params) => ({value, attributes})`.",
-		).preset(true),
-	)
-	.addOption(
-		new Option(
-			"--use-isolating",
-			"Wrap placeable with \\u2068 and \\u2069.",
-		).preset(true),
-	)
-	.addOption(
-		new Option(
-			"-o, --output <output>",
-			"Path to store the resulting JavaScript file. Will be in ESM.",
-		),
-	)
-	.action(async (input, options) => {
-		options.comments = options.comments ?? false;
-		try {
-			await fileExists(input);
-
-			const ftl = await readFile(input, { encoding: "utf8" });
-
-			const js = compile(ftl, options);
-			if (options.output) {
-				await writeFile(options.output, js, "utf8");
-			} else {
-				console.log(js);
-			}
-		} catch (e) {
-			console.error(`Error: ${e.message}`);
-			process.exit(1);
-		}
-	})
-	.parse();
+import { createProgram } from "./program.js";
+
+createProgram()
+	.parseAsync()
+	.catch((e) => {
+		console.error(`Error: ${e.message}`);
+		process.exit(1);
+	});

package/index.d.ts

@@ -3,7 +3,7 @@
 
 export interface CompileOptions {
 	/** What locale(s) to be used. Multiple can be set to allow for fallback. */
-	locale?: string | string[];
+	locale: string | string[];
 	/** Include comments in output file. Default: `true` */
 	comments?: boolean;
 	/** Throw error when `Junk` is parsed. Default: `true` */
@@ -12,7 +12,7 @@ export interface CompileOptions {
 	includeKey?: string | string[];
 	/** Array of message keys to exclude. Default: `[]` (exclude none) */
 	excludeKey?: string | string[];
-	/** Set message to an empty string when it contains this value. */
+	/** Set message to an empty string when it equals this value. */
 	excludeValue?: string;
 	/** What variable notation to use with exports. Default: `"camelCase"` */
 	variableNotation?: "camelCase" | "pascalCase" | "snakeCase" | "constantCase";
@@ -28,7 +28,22 @@ export interface CompileOptions {
 
 /**
  * Compile Fluent (.ftl) source into a JavaScript ESM string.
+ * Pass an array of source strings to join multiple files into one module;
+ * top-level message/term ids must be unique across the set.
  */
-export declare function compile(src: string, opts?: CompileOptions): string;
+export declare function compile(
+	src: string | string[],
+	opts?: CompileOptions,
+): string;
+
+/**
+ * Read and compile one or more Fluent (.ftl) files into a single JavaScript
+ * ESM string. Files are joined in the order supplied. Top-level message/term
+ * ids must be unique across the set.
+ */
+export declare function compileFiles(
+	paths: string[],
+	opts?: CompileOptions,
+): Promise<string>;
 
 export default compile;

package/index.js

@@ -1,9 +1,42 @@
 // Copyright 2026 will Farrell, and fluent-transpiler contributors.
 // SPDX-License-Identifier: MIT
 
+import { readFile } from "node:fs/promises";
 import { parse } from "@fluent/syntax";
 import { camelCase, constantCase, pascalCase, snakeCase } from "change-case";
 
+const collectTopLevelIds = (src) => {
+	const { body } = parse(src);
+	const ids = [];
+	for (const node of body) {
+		if (node.type === "Message" || node.type === "Term") {
+			ids.push(node.id.name);
+		}
+	}
+	return ids;
+};
+
+const checkDuplicates = (sources) => {
+	const seen = new Map();
+	const duplicates = [];
+	for (const { label, src } of sources) {
+		for (const id of collectTopLevelIds(src)) {
+			const prior = seen.get(id);
+			if (prior === undefined) {
+				seen.set(id, label);
+			} else if (prior !== label) {
+				duplicates.push({ id, a: prior, b: label });
+			}
+		}
+	}
+	if (duplicates.length) {
+		const lines = duplicates.map(
+			(d) => `  - "${d.id}" defined in ${d.a} and ${d.b}`,
+		);
+		throw new Error(`Duplicate id(s) found:\n${lines.join("\n")}`);
+	}
+};
+
 const reservedWords = new Set([
 	"abstract",
 	"arguments",
@@ -74,17 +107,25 @@ const reservedWords = new Set([
 ]);
 
 const exportDefault = `(id, params) => {
-  const source = __exports[id] ?? __exports['_'+id]
+  const source = __exports[id]
   if (typeof source === 'undefined') return '*** '+id+' ***'
   if (typeof source === 'function') return source(params)
   return source
 }
 `;
 export const compile = (src, opts) => {
+	if (Array.isArray(src)) {
+		const sources = src.map((s, i) => ({ label: `source[${i}]`, src: s }));
+		checkDuplicates(sources);
+		src = src.join("\n\n");
+	}
 	const options = {
 		comments: true,
 		errorOnJunk: true,
 		includeKey: [],
+		// Stryker disable next-line ArrayDeclaration: equivalent mutant — a bogus
+		// exclude key can never match a generated message id, so seeding the
+		// default with an entry produces identical output.
 		excludeKey: [],
 		excludeValue: undefined,
 		variableNotation: "camelCase",
@@ -111,9 +152,16 @@ export const compile = (src, opts) => {
 
 	const compileAssignment = (data) => {
 		variable = compileType(data);
+		if (metadata[variable] !== undefined) {
+			// Two declarations of one name (repeated id, term/message overlap, or
+			// ids that merge under the notation transform) would emit duplicate
+			// `const` declarations — an unloadable module.
+			throw new Error(`Duplicate identifier "${variable}"`, {
+				cause: { id: data.name },
+			});
+		}
 		metadata[variable] = {
 			id: data.name,
-			term: false,
 			params: false,
 		};
 		return variable;
@@ -121,12 +169,11 @@ export const compile = (src, opts) => {
 
 	const compileFunctionArguments = (data) => {
 		const positional = data.arguments?.positional.map((data) => {
-			return types[data.type](data);
+			return compileType(data);
 		});
 		const named = data.arguments?.named.reduce((obj, data) => {
-			const entry = compileType(data);
-			const [key, value] = entry.split(": ");
-			obj[key] = value;
+			// `NamedArgument` uses `name` instead of `id`; never transform it
+			obj[data.name.name] = compileType(data.value, data.type);
 			return obj;
 		}, {});
 		return { positional, named };
@@ -162,11 +209,18 @@ export const compile = (src, opts) => {
 			return `  ${key}: ${value}`;
 		},
 		Pattern: (data, parent) => {
+			// Parity with @fluent/bundle: placeables are only isolated when the
+			// pattern mixes them with other elements.
+			const isolate = options.useIsolating && data.elements.length > 1;
 			return (
 				"`" +
 				data.elements
 					.map((data) => {
-						return compileType(data, parent);
+						const value = compileType(data, parent);
+						if (isolate && data.type === "Placeable") {
+							return `\u2068${value}\u2069`;
+						}
+						return value;
 					})
 					.join("") +
 				"`"
@@ -175,8 +229,7 @@ export const compile = (src, opts) => {
 		// resources
 		Term: (data) => {
 			const assignment = compileAssignment(data.id);
-			const templateStringLiteral = compileType(data.value);
-			metadata[assignment].term = true;
+			const templateStringLiteral = compileType(data.value, data.type);
 			if (metadata[assignment].params) {
 				return `const ${assignment} = (${options.params}) => ${templateStringLiteral}\n`;
 			}
@@ -185,20 +238,6 @@ export const compile = (src, opts) => {
 		Message: (data) => {
 			const assignment = compileAssignment(data.id);
 
-			if (
-				options.includeKey.length &&
-				!options.includeKey.includes(assignment)
-			) {
-				return "";
-			}
-
-			if (
-				options.excludeKey.length &&
-				options.excludeKey.includes(assignment)
-			) {
-				return "";
-			}
-
 			let templateStringLiteral =
 				data.value && compileType(data.value, data.type);
 
@@ -207,7 +246,7 @@ export const compile = (src, opts) => {
 			}
 
 			metadata[assignment].attributes = data.attributes.length;
-			let attributes = {};
+			let attributes = "{}";
 			if (metadata[assignment].attributes) {
 				attributes = `{\n${data.attributes
 					.map((data) => {
@@ -216,7 +255,7 @@ export const compile = (src, opts) => {
 					.join(",\n")}\n  }`;
 			}
 
-			let message = "";
+			let message;
 			if (!options.disableMinify) {
 				if (metadata[assignment].attributes) {
 					if (metadata[assignment].params) {
@@ -243,10 +282,25 @@ export const compile = (src, opts) => {
 })\n`;
 			}
 
-			if (assignment === metadata[assignment].id) {
+			// Filters match the exported name or the original FTL id.
+			const id = metadata[assignment].id;
+			if (
+				(options.includeKey.length &&
+					!options.includeKey.includes(assignment) &&
+					!options.includeKey.includes(id)) ||
+				options.excludeKey.includes(assignment) ||
+				options.excludeKey.includes(id)
+			) {
+				// Filtered messages stay as private consts: other messages may
+				// reference them, so dropping the declaration entirely would
+				// break the generated module.
+				return `const ${assignment} = ${message}`;
+			}
+
+			if (assignment === id) {
 				exports.push(`${assignment}`);
 			} else {
-				exports.push(`'${metadata[assignment].id}': ${assignment}`);
+				exports.push(`'${id}': ${assignment}`);
 			}
 			return `export const ${assignment} = ${message}`;
 		},
@@ -270,13 +324,12 @@ export const compile = (src, opts) => {
 		},
 		// Element
 		TextElement: (data) => {
-			return data.value.replaceAll("`", "\\`"); // escape string literal
+			// escape for template literal; backslashes first so the escapes
+			// added for backticks are not themselves escaped
+			return data.value.replaceAll("\\", "\\\\").replaceAll("`", "\\`");
 		},
 		Placeable: (data, parent) => {
-			return `${options.useIsolating ? "\u2068" : ""}\${${compileType(
-				data.expression,
-				parent,
-			)}}${options.useIsolating ? "\u2069" : ""}`;
+			return `\${${compileType(data.expression, parent)}}`;
 		},
 		// Expression
 		StringLiteral: (data, parent) => {
@@ -286,24 +339,36 @@ export const compile = (src, opts) => {
 			}
 			return `"${data.value}"`;
 		},
-		NumberLiteral: (data) => {
-			const decimal = Number.parseFloat(data.value);
-			const number = Number.isInteger(decimal)
-				? Number.parseInt(data.value, 10)
-				: decimal;
-			return Intl.NumberFormat(options.locale).format(number);
+		NumberLiteral: (data, parent) => {
+			const number = Number.parseFloat(data.value);
+			// Pattern text positions display the locale-formatted number (as a
+			// string literal: bare `1,000` inside `${}` is a comma expression).
+			// Argument, selector, and variant-key positions need the raw value
+			// for Intl options and variant matching.
+			if (["Message", "Term", "Variant", "Attribute"].includes(parent)) {
+				return JSON.stringify(Intl.NumberFormat(options.locale).format(number));
+			}
+			return number;
 		},
 		VariableReference: (data, parent) => {
 			functions.__formatVariable = true;
 			metadata[variable].params = true;
-			const value = `${options.params}?.${data.id.name}`;
+			// Fluent identifiers allow dashes; those need bracket access in JS
+			const value = data.id.name.includes("-")
+				? `${options.params}?.[${JSON.stringify(data.id.name)}]`
+				: `${options.params}?.${data.id.name}`;
 			if (["Message", "Variant", "Attribute"].includes(parent)) {
-				return `__formatVariable(${value})`;
+				return `__formatVariable(${value}, ${JSON.stringify(data.id.name)})`;
 			}
 			return value;
 		},
 		MessageReference: (data) => {
 			const messageName = compileType(data.id);
+			if (metadata[messageName] === undefined) {
+				throw new Error(
+					`Unknown reference "${data.id.name}" (messages and terms must be defined before they are referenced)`,
+				);
+			}
 			metadata[variable].params ||= metadata[messageName].params;
 			if (!options.disableMinify) {
 				if (metadata[messageName].params) {
@@ -317,6 +382,11 @@ export const compile = (src, opts) => {
 		},
 		TermReference: (data) => {
 			const termName = compileType(data.id);
+			if (metadata[termName] === undefined) {
+				throw new Error(
+					`Unknown reference "${data.id.name}" (messages and terms must be defined before they are referenced)`,
+				);
+			}
 			metadata[variable].params ||= metadata[termName].params;
 
 			let params;
@@ -340,12 +410,6 @@ export const compile = (src, opts) => {
 			}
 			return `${termName}(${params ? params : ""})`;
 		},
-		NamedArgument: (data) => {
-			// Inconsistent: `NamedArgument` uses `name` instead of `id` for Identifier
-			const key = data.name.name; // Don't transform value
-			const value = compileType(data.value, data.type);
-			return `${key}: ${value}`;
-		},
 		SelectExpression: (data) => {
 			functions.__select = true;
 			metadata[variable].params = true;
@@ -363,16 +427,29 @@ export const compile = (src, opts) => {
 				})
 				.join(",\n")}\n    },\n    ${fallback}\n  )`;
 		},
-		Variant: (data, parent) => {
-			// Inconsistent: `Variant` uses `key` instead of `id` for Identifier
-			const key = compileType(data.key);
+		Variant: (data) => {
+			// Variant keys are runtime match keys (plural categories, selector
+			// values), never identifiers — emit them verbatim. Numeric keys use
+			// the raw value so `cases[1000]` can match (`'1,000'` never would).
+			const key =
+				data.key.type === "Identifier"
+					? data.key.name
+					: Number.parseFloat(data.key.value);
 			const value = compileType(data.value, data.type);
 			return `    '${key}': ${value}`;
 		},
 		FunctionReference: (data) => {
-			return `${types[data.id.name](compileFunctionArguments(data))}`;
+			const fn = functionTypes[data.id.name];
+			if (fn === undefined) {
+				throw new Error(
+					`Unknown function "${data.id.name}" (supported: DATETIME, NUMBER, RELATIVETIME)`,
+				);
+			}
+			return fn(compileFunctionArguments(data));
 		},
-		// Functions
+	};
+
+	const functionTypes = {
 		DATETIME: (data) => {
 			functions.__formatDateTime = true;
 			const { positional, named } = data;
@@ -393,9 +470,7 @@ export const compile = (src, opts) => {
 		},
 	};
 
-	if (/\t/.test(src)) {
-		src = src.replace(/\t/g, "    ");
-	}
+	src = src.replace(/\t/g, "    ");
 
 	const { body } = parse(src);
 	let translations = ``;
@@ -403,7 +478,7 @@ export const compile = (src, opts) => {
 		translations += compileType(data);
 	}
 
-	let output = ``;
+	let output = `// Generated by fluent-transpiler. Do not edit.\n`;
 	if (
 		functions.__formatVariable ||
 		functions.__formatDateTime ||
@@ -445,7 +520,7 @@ const __relativeTimeDiff = (d) => {
   return [Math.round(elapsed / msPerYear), 'year']
 }
 const __formatRelativeTime = (value, options) => {
-  if (typeof value === 'string') value = new Date(value)
+  if (!(value instanceof Date)) value = new Date(value)
   if (isNaN(value.getTime())) return value
   try {
     const [duration, unit] = __relativeTimeDiff(value)
@@ -462,7 +537,7 @@ const __formatRelativeTime = (value, options) => {
 	if (functions.__formatDateTime) {
 		output += `
 const __formatDateTime = (value, options) => {
-  if (typeof value === 'string') value = new Date(value)
+  if (!(value instanceof Date)) value = new Date(value)
   if (isNaN(value.getTime())) return value
   const k = JSON.stringify(options) ?? ''
   return (__intlCache['D'+k] ??= new Intl.DateTimeFormat(__locales, options)).format(value)
@@ -479,8 +554,9 @@ const __formatNumber = (value, options) => {
 	}
 	if (functions.__formatVariable) {
 		output += `
-const __formatVariable = (value) => {
+const __formatVariable = (value, name) => {
   if (typeof value === 'string') return value
+  if (value === undefined || value === null) return '{$'+name+'}'
   const decimal = Number.parseFloat(value)
   const number = Number.isInteger(decimal) ? Number.parseInt(value, 10) : decimal
   return __formatNumber(number)
@@ -489,9 +565,8 @@ const __formatVariable = (value) => {
 	}
 	if (functions.__select) {
 		output += `
-const __select = (value, cases, fallback, options) => {
-  const k = JSON.stringify(options) ?? ''
-  const rule = (__intlCache['P'+k] ??= new Intl.PluralRules(__locales, options)).select(value)
+const __select = (value, cases, fallback) => {
+  const rule = (__intlCache.P ??= new Intl.PluralRules(__locales)).select(value)
   return cases[value] ?? cases[rule] ?? fallback
 }
 `;
@@ -510,4 +585,15 @@ const variableNotation = {
 	constantCase,
 };
 
+export const compileFiles = async (paths, opts) => {
+	const sources = await Promise.all(
+		paths.map(async (path) => ({
+			label: path,
+			src: await readFile(path, { encoding: "utf8" }),
+		})),
+	);
+	checkDuplicates(sources);
+	return compile(sources.map((s) => s.src).join("\n\n"), opts);
+};
+
 export default compile;

package/package.json

@@ -3,7 +3,7 @@
 		".github"
 	],
 	"name": "fluent-transpiler",
-	"version": "0.4.1",
+	"version": "0.6.0",
 	"description": "Transpile Fluent (ftl) files into optimized, tree-shakable, JavaScript EcmaScript Modules (esm).",
 	"main": "index.js",
 	"types": "index.d.ts",
@@ -24,6 +24,7 @@
 	},
 	"files": [
 		"cli.js",
+		"program.js",
 		"index.js",
 		"index.d.ts"
 	],
@@ -35,21 +36,31 @@
 		"git:unit-staged": "node --test",
 		"git:test-staged": "npm run git:unit-staged",
 		"lint": "biome check --write --no-errors-on-unmatched",
-		"test": "npm run test:lint && npm run test:unit && npm run test:types && npm run test:sast && npm run test:perf && npm run test:dast",
+		"test": "npm run test:lint && npm run test:unit && npm run test:mutation && npm run test:types && npm run test:sast && npm run test:perf && npm run test:dast",
 		"test:lint": "biome check --staged --no-errors-on-unmatched",
 		"test:unit": "node --test --test-force-exit --experimental-test-coverage --test-coverage-lines=100 --test-coverage-branches=100 --test-coverage-functions=100 ./**/*.test.js",
+		"test:mutation": "stryker run",
 		"test:types": "tstyche",
 		"test:perf": "node --test --test-concurrency=1 ./**/*.perf.js",
-		"test:sast": "npm run test:sast:license && npm run test:sast:lockfile && npm run test:sast:semgrep && npm run test:sast:trufflehog && npm run test:sast:trivy",
-		"test:sast:license": "license-check-and-add check -f license.json",
+		"test:sast": "npm run test:sast:license && npm run test:sast:lockfile && npm run test:sast:semgrep && npm run test:sast:trufflehog && npm run test:sast:gitleaks && npm run test:sast:actionlint && npm run test:sast:zizmor && npm run test:sast:trivy",
+		"test:sast:actionlint": "actionlint",
+		"test:sast:gitleaks": "npm run test:sast:gitleaks:dir && npm run test:sast:gitleaks:git",
+		"test:sast:gitleaks:dir": "gitleaks dir . --redact --no-banner",
+		"test:sast:gitleaks:git": "gitleaks git . --redact --no-banner",
+		"test:sast:license": "license-check-and-add check -f .license.config.json",
 		"test:sast:lockfile": "lockfile-lint --path package-lock.json --type npm --allowed-schemes \"https:\" --allowed-hosts npm --validate-integrity --validate-package-names",
-		"test:sast:semgrep": "semgrep scan --config auto",
-		"test:sast:trivy": "trivy fs --scanners vuln,license --include-dev-deps --ignored-licenses 0BSD,Apache-2.0,BSD-1-Clause,BSD-2-Clause,BSD-3-Clause,CC0-1.0,CC-BY-4.0,ISC,MIT,Python-2.0 --exit-code 1 --disable-telemetry .",
+		"test:sast:semgrep": "semgrep scan --config auto --error",
+		"test:sast:trivy": "trivy fs --scanners vuln,license --include-dev-deps --ignored-licenses 0BSD,Apache-2.0,BSD-1-Clause,BSD-2-Clause,BSD-3-Clause,CC0-1.0,CC-BY-4.0,ISC,MIT,Python-2.0,LGPL-3.0-or-later,MPL-2.0,BlueOak-1.0.0,Unlicense --exit-code 1 --skip-files '**/bun.lock' --disable-telemetry .",
 		"test:sast:trufflehog": "trufflehog filesystem --only-verified --log-level=-1 ./",
+		"test:sast:zizmor": "zizmor .github/workflows/",
 		"test:dast": "npm run test:dast:fuzz",
 		"test:dast:fuzz": "node --test ./**/*.fuzz.js",
-		"release:license:add": "license-check-and-add add -f license.json",
-		"release:license:remove": "license-check-and-add remove -f license.json"
+		"rm": "npm run rm:macos && npm run rm:node_modules && npm run rm:lock",
+		"rm:macos": "find . -name '.DS_Store' -type f -delete",
+		"rm:lock": "find . -name 'package-lock.json' -type f -delete",
+		"rm:node_modules": "find . -name 'node_modules' -type d -prune -exec rm -rf '{}' +",
+		"release:license:add": "license-check-and-add add -f .license.config.json",
+		"release:license:remove": "license-check-and-add remove -f .license.config.json"
 	},
 	"repository": {
 		"type": "git",
@@ -76,18 +87,22 @@
 	"dependencies": {
 		"@fluent/syntax": "0.19.0",
 		"change-case": "5.4.4",
-		"commander": "14.0.3"
+		"commander": "15.0.0"
+	},
+	"overrides": {
+		"qs": "^6.15.2"
 	},
 	"devDependencies": {
 		"@biomejs/biome": "^2.0.0",
-		"@commitlint/cli": "^20.0.0",
-		"@commitlint/config-conventional": "^20.0.0",
+		"@commitlint/cli": "^21.0.0",
+		"@commitlint/config-conventional": "^21.0.0",
 		"@fluent/bundle": "^0.19.0",
+		"@stryker-mutator/core": "^9.0.0",
 		"fast-check": "^4.0.0",
 		"husky": "^9.0.0",
 		"license-check-and-add": "4.0.5",
 		"tinybench": "^6.0.0",
-		"tstyche": "^6.0.0"
+		"tstyche": "^7.0.0"
 	},
 	"funding": {
 		"type": "github",

package/program.js

@@ -0,0 +1,89 @@
+// Copyright 2026 will Farrell, and fluent-transpiler contributors.
+// SPDX-License-Identifier: MIT
+
+import { stat, writeFile } from "node:fs/promises";
+import { Command, Option } from "commander";
+import { compileFiles } from "./index.js";
+
+const fileExists = async (filepath) => {
+	const stats = await stat(filepath);
+	if (!stats.isFile()) {
+		throw new Error(`${filepath} is not a file`);
+	}
+};
+
+export const createProgram = () =>
+	new Command()
+		.name("ftl")
+		.description("Compile Fluent (.ftl) files to JavaScript (.js or .mjs)")
+		.argument(
+			"<inputs...>",
+			"Paths to the Fluent file(s) to compile. Multiple files are joined in order; ids must be unique across the set.",
+		)
+		.requiredOption(
+			"--locale <locale...>",
+			"What locale(s) to be used. Multiple can be set to allow for fallback. i.e. en-CA",
+		)
+		.addOption(
+			new Option("--comments", "Include comments in output file.").preset(true),
+		)
+		.addOption(
+			new Option(
+				"--include-key <includeMessageKey...>",
+				"Allowed messages to be included. Default to include all.",
+			),
+		)
+		.addOption(
+			new Option(
+				"--exclude-key <excludeMessageKey...>",
+				"Ignored messages to be excluded. Default to exclude none.",
+			),
+		)
+		.addOption(
+			new Option(
+				"--exclude-value <excludeMessageValue>",
+				"Set message to an empty string when it equals this value. Default to not allowing empty strings.",
+			),
+		)
+		.addOption(
+			new Option(
+				"--variable-notation <variableNotation>",
+				"What variable notation to use with exports",
+			)
+				.choices(["camelCase", "pascalCase", "constantCase", "snakeCase"])
+				.default("camelCase"),
+		)
+		.addOption(
+			new Option(
+				"--disable-minify",
+				"If disabled, all exported messages will have the same interface `(params) => ({value, attributes})`.",
+			).preset(true),
+		)
+		.addOption(
+			new Option(
+				"--use-isolating",
+				"Wrap placeable with \\u2068 and \\u2069.",
+			).preset(true),
+		)
+		.addOption(
+			new Option(
+				"-o, --output <output>",
+				"Path to store the resulting JavaScript file. Will be in ESM.",
+			),
+		)
+		.action(async (inputs, options) => {
+			options.comments = options.comments ?? false;
+
+			for (const input of inputs) {
+				await fileExists(input);
+			}
+
+			const js = await compileFiles(inputs, options);
+			if (options.output) {
+				await writeFile(options.output, js);
+			} else {
+				console.log(js);
+			}
+		});
+
+export default createProgram;

package/license.json

@@ -1,28 +0,0 @@
-{
-	"license": "license.template",
-	"licenseFormats": {
-		"js|ts": {
-			"eachLine": {
-				"prepend": "// "
-			}
-		}
-	},
-	"ignoreFile": ".gitignore",
-	"ignore": [
-		".github/**/*",
-		".husky/**/*",
-		"fixtures/*",
-		"commitlint.config.cjs",
-		"LICENSE",
-		"license.template",
-		"**/.gitignore",
-		"**/*.fuzz.js",
-		"**/*.perf.js",
-		"**/*.test.js",
-		"**/*.md",
-		"**/*.yml",
-		"**/.DS_Store",
-		"**/*.ftl",
-		"**/*.mjs"
-	]
-}

package/license.template

@@ -1,2 +0,0 @@
-Copyright 2026 will Farrell, and fluent-transpiler contributors.
-SPDX-License-Identifier: MIT