@nutin/cli 2.1.0 → 3.0.0

package/templates/base/tools/builder/core/html-index/add-tags.test.js.hbs

@@ -22,7 +22,7 @@ describe('addTags', () => {
     const result = await addTags(html, filePath);
 
     expect(result).toBe(
-      '<html><head><title>T</title><link rel="stylesheet" href="/main.css"></head><body><script type="module" src="/app/main.js"></script></body></html>'
+      '<html><head><title>T</title><link rel="stylesheet" href="/main.css"></head><body><script type="module" src="/bundle.js"></script></body></html>'
     );
   });
 
@@ -32,7 +32,7 @@ describe('addTags', () => {
     const result = await addTags(html, filePath);
 
     expect(result).toBe(
-      '<html><link rel="stylesheet" href="/main.css"><title>T</title><body><script type="module" src="/app/main.js"></script></body></html>'
+      '<html><link rel="stylesheet" href="/main.css"><title>T</title><body><script type="module" src="/bundle.js"></script></body></html>'
     );
   });
 
@@ -42,7 +42,7 @@ describe('addTags', () => {
     const result = await addTags(html, filePath);
 
     expect(result).toBe(
-      '<html></html><link rel="stylesheet" href="/main.css"><script type="module" src="/app/main.js"></script>'
+      '<html></html><link rel="stylesheet" href="/main.css"><script type="module" src="/bundle.js"></script>'
     );
   });
 

package/templates/base/tools/builder/core/html-index/validate-html.js.hbs

@@ -2,8 +2,12 @@ import { readFile } from 'fs/promises';
 import path from 'path';
 import { print, errorExit } from '../../../utils/index.js';
 import { PATHS } from '../app/paths.js';
+import { readRoutesImporters } from '../app/route-keys.js';
+import { builderConfig } from '../../builder.config.js';
 import { addTags } from './add-tags.js';
 
+const ROUTES_FILE = path.join(PATHS.sourceApp, 'routes.{{#if (eq lang "js")}}js{{else}}ts{{/if}}');
+
 async function validateHtml() {
   const filePath = path.join(PATHS.tempSource, 'index.html');
 
@@ -14,8 +18,12 @@ async function validateHtml() {
     errorExit(`Failed to read ${filePath}`);
   }
 
-  if (!htmlContent.includes('id="app"')) {
-    errorExit('Missing #app container in HTML');
+  // The router mounts views into #app, and generateSEOFiles prerenders into it. An app without
+  // the router mounts its components wherever it wants: a missing target is reported at runtime.
+  const needsApp = builderConfig.generateSEO || readRoutesImporters(PATHS.sourceApp, ROUTES_FILE).length > 0;
+  if (needsApp && !htmlContent.includes('id="app"')) {
+    const reason = builderConfig.generateSEO ? 'generateSEOFiles prerenders pages into it' : 'the router mounts views into it';
+    errorExit(`Missing #app container in index.html: ${reason}.`);
   }
 
   htmlContent = await addTags(htmlContent, filePath).catch(err => errorExit(err.message));

package/templates/base/tools/builder/core/html-templates/merge-templates.js.hbs

@@ -1,41 +1,70 @@
 import fs from 'fs/promises';
 import path from 'path';
+import esbuild from 'esbuild';
 import { getFilesRecursive, print, pascalCased, capitalized } from '../../../utils/index.js';
 import { PATHS } from '../app/paths.js';
-import { minifyHTML } from './minify-html.js';
+import { findInlineTemplate, minifyTemplateBody } from './template-literal.js';
 
 const PLACEHOLDER = '__TEMPLATE_PLACEHOLDER__';
 const TARGET_EXTENSIONS = ['.ts', '.js'];
-const TEMPLATE_REGEX = /const\s+(?:template|templateFn)\s*=?\s*(?:\(.*?\)\s*=>\s*)?`([\s\S]*?)`/;
+
+// Where each merged .html template sits in its code file (merge-templates writes it,
+// compile-ts reads it to report type errors at the .html line). Keyed by path relative to
+// dist-build (`src/app/...`), which is also the path of the source file in the project.
+export const TEMPLATE_MAP_FILE = path.join(PATHS.temp, '.template-map.json');
 
 // A component/view's template can live inline in its .ts/.js file or in a
 // colocated .html sibling merged in via `__TEMPLATE_PLACEHOLDER__` — resolved
 // automatically per file rather than through a global config flag:
 //   external + placeholder -> merge external in
 //   external + real inline markup -> conflict, fail
-//   no external + real inline markup -> minify inline
+//   no external + real inline markup -> keep inline
 //   no external + still the placeholder -> nothing to use, fail
-export async function resolveTemplates() {
+// Templates are merged as written, so tsc type-checks them with readable line numbers
+// (see compile-ts); minifyTemplates() minifies every template afterwards.
+export async function mergeTemplates() {
   const htmlFiles = await getFilesRecursive(PATHS.tempApp, 'html');
   const resolvedPaths = new Set();
   const failures = [];
+  const templateMap = {};
 
   for (const htmlPath of htmlFiles) {
-    await resolveExternalTemplate(htmlPath, resolvedPaths, failures);
+    await mergeExternalTemplate(htmlPath, resolvedPaths, failures, templateMap);
   }
 
-  await resolveRemainingTemplates(resolvedPaths, failures);
+  await checkRemainingTemplates(resolvedPaths, failures);
+  await fs.writeFile(TEMPLATE_MAP_FILE, JSON.stringify(templateMap));
 
   if (failures.length) {
     throw new Error(`Failed to resolve ${failures.length} template(s).`);
   }
 }
 
-// Normally a view/component has exactly one sibling here — `.js` in dev (tsc
-// output), `.ts` in prod (esbuild bundles straight from source, tsc runs
-// --noEmit there). Checking whichever exist(s) rather than assuming one, so
-// this can't silently regress again if that dev/prod split ever changes.
-async function resolveExternalTemplate(htmlPath, resolvedPaths, failures) {
+// Minifies the template of every code file, merged or inline. Anything that can't be
+// minified safely is kept as written.
+export async function minifyTemplates() {
+  const templateMap = await readTemplateMap();
+  const codeFiles = await getFilesRecursive(PATHS.tempApp, TARGET_EXTENSIONS);
+
+  for (const codePath of codeFiles) {
+    const content = await fs.readFile(codePath, 'utf-8');
+    const template = findMergedTemplate(content, codePath, templateMap) ?? findInlineTemplate(content);
+    if (!template || template.body === null || template.body === PLACEHOLDER) continue;
+
+    const minified = await minifyTemplateBody(template.body);
+    if (minified === null) {
+      print.gray(describeUnminified(codePath));
+      continue;
+    }
+    const updated = content.slice(0, template.open) + minified + content.slice(template.end);
+    await fs.writeFile(codePath, await keepIfValid(codePath, updated, content));
+  }
+}
+
+// Normally a view/component has exactly one sibling here: its copied `.ts` (TypeScript
+// projects; tsc compiles it once merged) or `.js` (JS-only projects). Checking whichever
+// exist(s) rather than assuming one, so this can't silently regress if that ever changes.
+async function mergeExternalTemplate(htmlPath, resolvedPaths, failures, templateMap) {
   const htmlFilename = path.basename(htmlPath);
 
   let htmlContent;
@@ -47,7 +76,6 @@ async function resolveExternalTemplate(htmlPath, resolvedPaths, failures) {
     return;
   }
 
-  const minifiedHtml = await minifyHTML(htmlContent);
   let mergedCount = 0;
   let conflictCount = 0;
 
@@ -66,9 +94,18 @@ async function resolveExternalTemplate(htmlPath, resolvedPaths, failures) {
     }
 
     resolvedPaths.add(codePath);
+    warnIfUntagged(codePath, content, htmlContent);
 
     if (content.includes(PLACEHOLDER)) {
-      await fs.writeFile(codePath, content.replace(PLACEHOLDER, minifiedHtml));
+      templateMap[path.relative(PATHS.temp, codePath)] = {
+        html: path.relative(PATHS.temp, htmlPath),
+        ...placeholderPosition(content),
+        lines: htmlContent.split('\n').length,
+        template: htmlContent,
+      };
+      // Replacements go through functions: a replacement *string* expands `$$`, `$&`,
+      // `$'`… found in the markup (e.g. `$${price}` would lose its `$`).
+      await fs.writeFile(codePath, content.replace(PLACEHOLDER, () => htmlContent));
       mergedCount++;
       continue;
     }
@@ -86,29 +123,69 @@ async function resolveExternalTemplate(htmlPath, resolvedPaths, failures) {
   }
 }
 
-async function resolveRemainingTemplates(resolvedPaths, failures) {
+// Inline templates: a placeholder with no .html to fill it fails; untagged ones warn.
+async function checkRemainingTemplates(resolvedPaths, failures) {
   const codeFiles = await getFilesRecursive(PATHS.tempApp, TARGET_EXTENSIONS);
 
   for (const codePath of codeFiles) {
     if (resolvedPaths.has(codePath)) continue;
 
     const content = await fs.readFile(codePath, 'utf-8');
-    const match = content.match(TEMPLATE_REGEX);
-    if (!match) continue;
-
-    const [full, body] = match;
+    const template = findInlineTemplate(content);
+    if (!template || template.body === null) continue;
+    warnIfUntagged(codePath, content, template.body);
 
-    if (body === PLACEHOLDER) {
+    if (template.body === PLACEHOLDER) {
       print.warn(describeMissingTemplate(codePath));
       failures.push(path.basename(codePath));
-      continue;
     }
+  }
+}
 
-    const minified = await minifyHTML(body);
-    await fs.writeFile(codePath, content.replace(full, full.replace(body, minified)));
+export async function readTemplateMap() {
+  try {
+    return JSON.parse(await fs.readFile(TEMPLATE_MAP_FILE, 'utf-8'));
+  } catch {
+    return {};
   }
 }
 
+// A merged template, found by its markup: it's wherever the placeholder was, whatever the
+// variable holding it is called, in the copied .ts or in tsc's .js emitted from it.
+function findMergedTemplate(content, codePath, templateMap) {
+  const relPath = path.relative(PATHS.temp, codePath);
+  const entry = templateMap[relPath] ?? templateMap[relPath.replace(/\.js$/, '.ts')];
+  if (!entry) return null;
+  const open = content.indexOf(entry.template);
+  if (open === -1) return null;
+  return { open, end: open + entry.template.length, body: entry.template };
+}
+
+// 1-based line and column of the placeholder in a code file.
+export function placeholderPosition(content) {
+  const index = content.indexOf(PLACEHOLDER);
+  const before = content.slice(0, index);
+  return { line: before.split('\n').length, col: index - before.lastIndexOf('\n') };
+}
+
+// Last safety net: minified code that no longer parses is replaced by the code as written.
+async function keepIfValid(codePath, minified, asWritten) {
+  if (minified === asWritten) return minified;
+  try {
+    await esbuild.transform(minified, { loader: codePath.endsWith('.ts') ? 'ts' : 'js' });
+    return minified;
+  } catch {
+    print.gray(describeUnminified(codePath));
+    return asWritten;
+  }
+}
+
+// Templates are escaped by the html`` tag; an untagged literal with ${} interpolates raw.
+function warnIfUntagged(codePath, content, markup) {
+  const template = findInlineTemplate(content);
+  if (template && !template.tagged && markup.includes('${')) print.warn(describeUntagged(codePath));
+}
+
 function describeCodeFile(codePath) {
   const filename = path.basename(codePath);
   const basename = filename.replace(/\.(ts|js)$/, '');
@@ -143,10 +220,21 @@ Expected:
 Add ${basename}.html, or replace the placeholder in ${filename} with inline markup.`;
 }
 
+function describeUnminified(filePath) {
+  return `Kept the template of ${path.basename(filePath)} unminified: its markup couldn't be minified safely.`;
+}
+
+function describeUntagged(codePath) {
+  const { filename, kind, className } = describeCodeFile(codePath);
+
+  return `${kind} "${className}" has an untagged template: its \${} values are inserted unescaped.
+Tag it in ${filename}: html\`...\` (import html from core), and wrap trusted markup in raw().`;
+}
+
 function describeOrphanHtml(htmlPath) {
   const htmlFilename = path.basename(htmlPath);
   const basename = htmlFilename.replace(/\.html$/, '');
 
   return `"${htmlFilename}" has no matching component or view (expected ${basename}.ts or ${basename}.js).
-Remove ${htmlFilename}, or add ${basename}.ts with a template placeholder to merge it into.`;
+Remove ${htmlFilename}, or add ${basename}.{{#if (eq lang "js")}}js{{else}}ts{{/if}} with a template placeholder to merge it into.`;
 }

package/templates/base/tools/builder/core/html-templates/minify-templates.js.hbs

@@ -0,0 +1,8 @@
+import { errorExit } from '../../../utils/index.js';
+import { minifyTemplates } from './merge-templates.js';
+
+try {
+  await minifyTemplates();
+} catch (err) {
+  errorExit(err, 'minify-templates');
+}

package/templates/base/tools/builder/core/html-templates/process-html-templates.js.hbs

@@ -1,8 +1,10 @@
 import { errorExit } from '../../../utils/index.js';
-import { resolveTemplates } from './merge-templates.js';
+import { mergeTemplates } from './merge-templates.js';
 
+// Merges each .html template into its code file, as written: TypeScript projects type-check
+// them next (compile-ts), and minify-templates.js minifies them after that.
 try {
-  await resolveTemplates();
+  await mergeTemplates();
 } catch (err) {
-  errorExit(err);
+  errorExit(err, 'process-html-templates');
 }

package/templates/base/tools/builder/core/html-templates/template-literal.js.hbs

@@ -0,0 +1,193 @@
+import { minifyHTML } from './minify-html.js';
+
+// Minifies the markup of html`` template literals without ever handing JavaScript to the
+// HTML minifier: each ${…} is swapped for a token, the markup is minified, and the
+// expressions are put back as written (html`` templates nested inside them are minified
+// the same way). Anything the scanner can't follow, or a token the minifier drops or
+// duplicates (e.g. a whole style="${…}" emptied as invalid CSS), leaves the template as
+// written: the worst case is an unminified template, never a broken one.
+
+const TOKEN_PREFIX = '__nutin_expr_';
+const token = (n) => `${TOKEN_PREFIX}${n}__`;
+
+// After these, a "/" starts a regex literal rather than a division.
+const REGEX_PRECEDING_WORDS = new Set([
+  'return', 'typeof', 'instanceof', 'in', 'of', 'new', 'delete', 'void',
+  'throw', 'case', 'do', 'else', 'yield', 'await',
+]);
+const REGEX_PRECEDING_PUNCTUATION = new Set('(,=:[!&|?{};+-*%<>~^'.split(''));
+
+const isIdentifierChar = (ch) => /[\w$]/.test(ch);
+
+// Index just past the closing quote of the string starting at `i`, or -1.
+function skipString(src, i) {
+  const quote = src[i];
+  for (i++; i < src.length; i++) {
+    if (src[i] === '\\') i++;
+    else if (src[i] === quote) return i + 1;
+    else if (src[i] === '\n') return -1;
+  }
+  return -1;
+}
+
+// Index just past the regex literal (and its flags) starting at `i`, or -1.
+function skipRegex(src, i) {
+  let inClass = false;
+  for (i++; i < src.length; i++) {
+    const ch = src[i];
+    if (ch === '\\') i++;
+    else if (ch === '\n') return -1;
+    else if (inClass) inClass = ch !== ']';
+    else if (ch === '[') inClass = true;
+    else if (ch === '/') {
+      i++;
+      while (i < src.length && isIdentifierChar(src[i])) i++;
+      return i;
+    }
+  }
+  return -1;
+}
+
+/**
+ * Scans a template literal from `start`, the index just past its opening backtick.
+ * Returns `{ end, expressions, nested }`: `end` is the index of the closing backtick,
+ * `expressions` the top-level `${…}` spans (`start` at "$", `end` past "}"), `nested` the
+ * html``-tagged literals inside those expressions (`open` past their opening backtick,
+ * `end` at their closing one). null when the literal isn't closed or can't be followed.
+ */
+export function scanTemplate(src, start) {
+  const expressions = [];
+  const nested = [];
+
+  for (let i = start; i < src.length; i++) {
+    const ch = src[i];
+    if (ch === '\\') {
+      i++;
+    } else if (ch === '`') {
+      return { end: i, expressions, nested };
+    } else if (ch === '$' && src[i + 1] === '{') {
+      const end = scanExpression(src, i + 2, nested);
+      if (end === -1) return null;
+      expressions.push({ start: i, end });
+      i = end - 1;
+    }
+  }
+  return null;
+}
+
+// Index just past the "}" closing the expression that starts at `i`, or -1.
+function scanExpression(src, i, nested) {
+  let depth = 0;
+  let previous = '('; // the expression start behaves like an opening parenthesis
+
+  while (i < src.length) {
+    const ch = src[i];
+
+    if (/\s/.test(ch)) {
+      i++;
+    } else if (ch === '/' && src[i + 1] === '/') {
+      const newline = src.indexOf('\n', i);
+      if (newline === -1) return -1;
+      i = newline + 1;
+    } else if (ch === '/' && src[i + 1] === '*') {
+      const close = src.indexOf('*/', i + 2);
+      if (close === -1) return -1;
+      i = close + 2;
+    } else if (ch === '"' || ch === "'") {
+      i = skipString(src, i);
+      if (i === -1) return -1;
+      previous = 'value';
+    } else if (ch === '`') {
+      const inner = scanTemplate(src, i + 1);
+      if (!inner) return -1;
+      if (previous === 'html') nested.push({ open: i + 1, end: inner.end });
+      i = inner.end + 1;
+      previous = 'value';
+    } else if (ch === '/' && (REGEX_PRECEDING_PUNCTUATION.has(previous) || REGEX_PRECEDING_WORDS.has(previous))) {
+      i = skipRegex(src, i);
+      if (i === -1) return -1;
+      previous = 'value';
+    } else if (isIdentifierChar(ch)) {
+      let end = i;
+      while (end < src.length && isIdentifierChar(src[end])) end++;
+      previous = src.slice(i, end);
+      i = end;
+    } else {
+      if (ch === '{') depth++;
+      if (ch === '}') {
+        if (depth === 0) return i + 1;
+        depth--;
+      }
+      previous = ch;
+      i++;
+    }
+  }
+  return -1;
+}
+
+/**
+ * Minifies a template body (the text between the backticks, or an external .html file).
+ * Returns the minified body, or null when it is left as written.
+ */
+export async function minifyTemplateBody(body) {
+  const scan = scanTemplate(`${body}\``, 0);
+  if (!scan || scan.end !== body.length || body.includes(TOKEN_PREFIX)) return null;
+
+  // Expressions (with their own nested html`` minified first), in source order.
+  const expressions = [];
+  for (const { start, end } of scan.expressions) {
+    const nestedInside = scan.nested.filter((n) => n.open > start && n.end < end);
+    expressions.push(await minifyNested(body, start, end, nestedInside));
+  }
+
+  let markup = '';
+  let last = 0;
+  scan.expressions.forEach(({ start, end }, n) => {
+    markup += body.slice(last, start) + token(n);
+    last = end;
+  });
+  markup += body.slice(last);
+
+  let minified;
+  try {
+    minified = await minifyHTML(markup);
+  } catch {
+    return null;
+  }
+
+  for (let n = 0; n < expressions.length; n++) {
+    if (minified.split(token(n)).length !== 2) return null;
+  }
+  return minified.replace(/__nutin_expr_(\d+)__/g, (_match, n) => expressions[Number(n)]);
+}
+
+// The source of body[start, end) with each nested html`` body minified (kept when it can't be).
+async function minifyNested(body, start, end, nested) {
+  let out = '';
+  let last = start;
+  for (const { open, end: close } of nested) {
+    const inner = body.slice(open, close);
+    out += body.slice(last, open) + ((await minifyTemplateBody(inner)) ?? inner);
+    last = close;
+  }
+  return out + body.slice(last, end);
+}
+
+// Up to the opening backtick; scanTemplate() finds the closing one, past any nested html``.
+const TEMPLATE_START = /const\s+(?:template|templateFn)\s*=?\s*(?:\(.*?\)\s*=>\s*)?(html\s*)?`/;
+
+// The first `const template`/`templateFn` literal: whether it is html``-tagged, where its
+// body starts and ends, and the body (null when its closing backtick can't be found).
+export function findInlineTemplate(content) {
+  const match = TEMPLATE_START.exec(content);
+  if (!match) return null;
+
+  const open = match.index + match[0].length;
+  const scan = scanTemplate(content, open);
+  return {
+    tagged: Boolean(match[1]),
+    open,
+    end: scan?.end ?? null,
+    body: scan ? content.slice(open, scan.end) : null,
+  };
+}

package/templates/base/tools/builder/core/html-templates/template-literal.test.js.hbs

@@ -0,0 +1,69 @@
+import { scanTemplate, minifyTemplateBody } from './template-literal.js';
+
+// Scans `source` from just past its first backtick and returns the literal's body.
+function bodyOf(source) {
+  const open = source.indexOf('`') + 1;
+  const scan = scanTemplate(source, open);
+  return scan && source.slice(open, scan.end);
+}
+
+describe('template-literal', () => {
+  it('scanTemplate finds the closing backtick past a nested html`` in a .map()', () => {
+    const source = 'const t = html`<ul>${items.map((i) => html`<li>${i}</li>`)}</ul>`; after();';
+    expect(bodyOf(source)).toBe('<ul>${items.map((i) => html`<li>${i}</li>`)}</ul>');
+  });
+
+  it('scanTemplate is not fooled by backticks or braces in strings, comments and regex literals', () => {
+    const body = "<p>${s.replace(/`/g, '')}${'}`'}${x /* ` } */}${\"{\"}${y // `}\n}</p>";
+    expect(bodyOf('html`' + body + '`; x;')).toBe(body);
+  });
+
+  it('scanTemplate reads a "/" after a value as a division, not a regex', () => {
+    const body = '<p>${total / count} of ${(a) / 2} / ${b[0] / 3}</p>';
+    expect(bodyOf('html`' + body + '`; x;')).toBe(body);
+  });
+
+  it('scanTemplate skips escaped backticks and escaped ${', () => {
+    const body = '<p>\\` and \\${not} and ${real}</p>';
+    const scan = scanTemplate('html`' + body + '`', 5);
+    expect(scan.end).toBe(5 + body.length);
+    expect(scan.expressions.length).toBe(1);
+  });
+
+  it('scanTemplate returns null for an unclosed literal or expression', () => {
+    expect(scanTemplate('html`<p>${a</p>', 5)).toBe(null);
+    expect(scanTemplate('html`<p>', 5)).toBe(null);
+  });
+
+  it('minifyTemplateBody minifies the markup and the nested html`` bodies', async () => {
+    const body = '\n<ul class="list">\n  ${items.map((i) => html`\n    <li>\n      ${i}\n    </li>\n  `)}\n</ul>\n<p>\n  after   nested\n</p>\n';
+    expect(await minifyTemplateBody(body)).toBe('<ul class="list">${items.map((i) => html`<li>${i}</li>`)}</ul><p>after nested</p>');
+  });
+
+  it('minifyTemplateBody puts every expression back exactly as written', async () => {
+    const body = '<p title="${t}">  ${\'a   b\'}  ${a < b ? x : y}  </p>';
+    expect(await minifyTemplateBody(body)).toBe('<p title="${t}">${\'a   b\'} ${a < b ? x : y}</p>');
+  });
+
+  it('minifyTemplateBody keeps expressions in attribute-name position', async () => {
+    expect(await minifyTemplateBody('<input ${attrs}  ${more}>  <b>  x  </b>')).toBe('<input ${attrs} ${more}> <b>x</b>');
+  });
+
+  it('minifyTemplateBody leaves a template with a dynamic tag name as written', async () => {
+    expect(await minifyTemplateBody('<${tag}>  x  </${tag}>')).toBe(null);
+  });
+
+  it('minifyTemplateBody leaves a template as written when the minifier would drop an expression', async () => {
+    expect(await minifyTemplateBody('<div style="${css}">x</div>')).toBe(null);
+  });
+
+  it('minifyTemplateBody leaves a template as written when the scanner cannot follow it', async () => {
+    expect(await minifyTemplateBody('<p>${a</p>')).toBe(null);
+    expect(await minifyTemplateBody('<p>__nutin_expr_0__ ${a}</p>')).toBe(null);
+  });
+
+  it('minifyTemplateBody keeps a nested html`` it cannot minify as written', async () => {
+    const body = '<ul>  ${items.map((i) => html`<li style="${i}">x</li>`)}  </ul>';
+    expect(await minifyTemplateBody(body)).toBe('<ul>${items.map((i) => html`<li style="${i}">x</li>`)}</ul>');
+  });
+});

package/templates/base/tools/builder/core/i18n/build-i18n.js.hbs

@@ -33,13 +33,21 @@ function getKeyForFile(filePath) {
   }
 }
 
-function combineJsonFiles(files) {
+function combineJsonFiles(locale, files) {
   const combined = {};
+  const sources = {};
 
   files.forEach(file => {
     const key = getKeyForFile(file);
-    const content = JSON.parse(fs.readFileSync(file, 'utf8'));
-    combined[key] = content;
+    // Keys are folder names, so e.g. admin/user/ and public/user/ would share "user".
+    if (sources[key]) {
+      throw new Error(
+        `Translation key "${key}" (${locale}) is defined by two folders:\n  ${path.relative(process.cwd(), sources[key])}\n  ${path.relative(process.cwd(), file)}\n` +
+        `One would silently overwrite the other — rename one of the folders.`
+      );
+    }
+    sources[key] = file;
+    combined[key] = JSON.parse(fs.readFileSync(file, 'utf8'));
   });
 
   return combined;
@@ -107,9 +115,9 @@ async function mergeJson() {
 
   const localeFilesMap = findLocaleFiles();
   for (const [locale, files] of Object.entries(localeFilesMap)) {
-    const combined = combineJsonFiles(files);
+    const combined = combineJsonFiles(locale, files);
     fs.writeFileSync(
-      `${destDir}/${locale}.json`,
+      path.join(destDir, `${locale}.json`),
       JSON.stringify(combined, null, 2)
     );
   }
@@ -117,5 +125,5 @@ async function mergeJson() {
 }
 
 mergeJson().catch((err) => {
-  errorExit(err)
+  errorExit(err, 'build-i18n');
 });