@nutin/cli 2.1.1 → 3.0.0

package/templates/base/tools/builder/core/app/paths.js.hbs

@@ -4,6 +4,7 @@ const SRC_FOLDERNAME = 'src';
 const APP_FOLDERNAME = 'app';
 const TMP_FOLDERNAME = 'dist-build';
 const BLD_FOLDERNAME = 'dist';
+const CHUNKS_FOLDERNAME = 'chunks';
 
 const BASE_PATHS = {
   source: path.resolve(SRC_FOLDERNAME),
@@ -16,4 +17,20 @@ export const PATHS = {
   sourceApp: path.join(BASE_PATHS.source, APP_FOLDERNAME),
   tempSource: path.join(BASE_PATHS.temp, SRC_FOLDERNAME),
   tempApp: path.join(BASE_PATHS.temp, SRC_FOLDERNAME, APP_FOLDERNAME),
+  tempChunks: path.join(BASE_PATHS.temp, SRC_FOLDERNAME, CHUNKS_FOLDERNAME),
 };
+
+// Copied sources that only feed the bundles — finalize-build.js removes them in prod,
+// so hashing/compressing them is wasted work (and renaming them breaks the SSR bundle).
+const BUNDLED_SOURCE_DIRS = [PATHS.tempApp, path.join(PATHS.tempSource, 'core')];
+
+export function isBundledSource(file) {
+  return BUNDLED_SOURCE_DIRS.some((dir) => file.startsWith(dir + path.sep));
+}
+
+// esbuild's code-split chunks (dynamic import()s and the code they share). Already
+// content-hashed by esbuild, and imported by name from bundle.js and from each other,
+// so hash-files.js must not rename them.
+export function isChunk(file) {
+  return file.startsWith(PATHS.tempChunks + path.sep);
+}

package/templates/base/tools/builder/core/app/route-keys.js.hbs

@@ -0,0 +1,47 @@
+import fs from 'fs';
+import path from 'path';
+import esbuild from 'esbuild';
+import { getFilesRecursive } from '../../../utils/index.js';
+
+const DUPLICATE_KEY_TEXT = /^Duplicate key "(.*)" in object literal$/;
+
+// esbuild warns on every duplicate key of an object literal — appRoutes' included — and
+// treats '/x', "/x" and ['/x'] as the same key. Scope is the whole file, not only appRoutes.
+// Rejects (with esbuild's own message) when the source doesn't parse.
+export async function findDuplicateRouteKeys(source, { loader, sourcefile }) {
+  const { warnings } = await esbuild.transform(source, { loader, sourcefile });
+  const duplicates = new Map();
+
+  for (const warning of warnings) {
+    if (warning.id !== 'duplicate-object-key') continue;
+    const key = warning.text.match(DUPLICATE_KEY_TEXT)?.[1] ?? warning.text;
+    if (!duplicates.has(key)) duplicates.set(key, warning.location?.line);
+  }
+
+  return [...duplicates].map(([key, line]) => ({ key, line }));
+}
+
+// Static, bare and dynamic imports: from '…', import '…', import('…').
+const IMPORT_SPECIFIER = /(?:\bfrom\s*|\bimport\s*\(?\s*)(['"`])([^'"`]+)\1/g;
+const CODE_EXTENSION = /\.(ts|js)$/;
+
+// The app files that import the routes module. Without one, the app doesn't use the router
+// (e.g. components mounted into a page), so routes.ts and #app aren't required.
+//   files: [{ path, content }], absolute paths; routesFile: the routes module's absolute path.
+export function findRoutesImporters(files, routesFile) {
+  const routesModule = routesFile.replace(CODE_EXTENSION, '');
+  return files
+    .filter(({ path: file, content }) => file !== routesFile && [...content.matchAll(IMPORT_SPECIFIER)].some(
+      ([, , specifier]) => specifier.startsWith('.') &&
+        path.resolve(path.dirname(file), specifier).replace(CODE_EXTENSION, '') === routesModule
+    ))
+    .map(({ path: file }) => file);
+}
+
+// findRoutesImporters() over the app's code files (tests and .d.ts left out).
+export function readRoutesImporters(appDir, routesFile) {
+  const files = getFilesRecursive(appDir, ['.ts', '.js'])
+    .filter((file) => !/\.test\.(ts|js)$/.test(file) && !file.endsWith('.d.ts'))
+    .map((file) => ({ path: file, content: fs.readFileSync(file, 'utf-8') }));
+  return findRoutesImporters(files, routesFile);
+}

package/templates/base/tools/builder/core/app/route-keys.test.js.hbs

@@ -0,0 +1,97 @@
+import path from 'path';
+import { findDuplicateRouteKeys, findRoutesImporters } from './route-keys.js';
+
+const TS = { loader: 'ts', sourcefile: 'routes.ts' };
+
+describe('findDuplicateRouteKeys', () => {
+  it('returns nothing for distinct keys, TypeScript syntax included', async () => {
+    const source = `
+      export const appRoutes: Nutin.Routes = {
+        '/': () => new HomeView(),
+        '/about': () => new AboutView() as any,
+        '/users/:id': () => new UserView(),
+      };`;
+
+    expect(await findDuplicateRouteKeys(source, TS)).toEqual([]);
+  });
+
+  it('reports a duplicate across quote styles and computed keys, with its line', async () => {
+    const source = [
+      'export const appRoutes: Nutin.Routes = {',
+      "  '/': () => new HomeView(),",
+      '  "/": () => new OtherView(),',
+      "  ['/c']: () => new C(),",
+      "  ['/c']: () => new D(),",
+      '};',
+    ].join('\n');
+
+    expect(await findDuplicateRouteKeys(source, TS)).toEqual([
+      { key: '/', line: 3 },
+      { key: '/c', line: 5 },
+    ]);
+  });
+
+  it('reports a duplicated :param route', async () => {
+    const source = `export const appRoutes = {
+      '/users/:id': () => new A(),
+      '/users/:id': () => new B(),
+    };`;
+
+    expect((await findDuplicateRouteKeys(source, { loader: 'js', sourcefile: 'routes.js' })).map((d) => d.key)).toEqual(['/users/:id']);
+  });
+
+  it('does not flag the view/guards keys shared by several guarded routes', async () => {
+    const source = `export const appRoutes: Nutin.Routes = {
+      '/admin': { view: () => new AdminView(), guards: [() => true] },
+      '/settings': { view: () => new SettingsView(), guards: [() => '/'] },
+    };`;
+
+    expect(await findDuplicateRouteKeys(source, TS)).toEqual([]);
+  });
+
+  it('flags a plain and a guarded route sharing a path', async () => {
+    const source = `export const appRoutes: Nutin.Routes = {
+      '/admin': () => new AdminView(),
+      '/admin': { view: () => new AdminView(), guards: [() => true] },
+    };`;
+
+    expect((await findDuplicateRouteKeys(source, TS)).map((d) => d.key)).toEqual(['/admin']);
+  });
+
+  it('checks the whole file, not only appRoutes', async () => {
+    const source = `const other = { a: 1, a: 2 };
+      export const appRoutes: Nutin.Routes = { '/': () => new HomeView() };`;
+
+    expect(await findDuplicateRouteKeys(source, TS)).toEqual([{ key: 'a', line: 1 }]);
+  });
+
+  it('rejects when the source does not parse', async () => {
+    await expect(() => findDuplicateRouteKeys('export const appRoutes = {', TS)).toThrow();
+  });
+});
+
+describe('findRoutesImporters', () => {
+  const APP = path.resolve('/project/src/app');
+  const ROUTES = path.join(APP, 'routes.ts');
+  const file = (rel, content) => ({ path: path.join(APP, rel), content });
+
+  it('finds static, bare and dynamic imports of the routes module, from any folder', () => {
+    const files = [
+      file('main.ts', "import { appRoutes } from './routes.js';"),
+      file('setup.ts', "import './routes.js';"),
+      file('lazy/boot.ts', "const r = await import('../routes.js');"),
+    ];
+    expect(findRoutesImporters(files, ROUTES)).toEqual(files.map((f) => f.path));
+  });
+
+  it('ignores other modules named routes, packages, and the routes file itself', () => {
+    const files = [
+      file('main.ts', "import { CounterComponent } from './components/counter/counter.component.js';"),
+      file('admin/main.ts', "import { adminRoutes } from './routes.js';"),
+      file('x.ts', "import routes from 'routes.js';"),
+      file('routes.ts', "import { markdownRoutes } from './markdown/markdown-routes.js';"),
+    ];
+    expect(findRoutesImporters(files, ROUTES)).toEqual([]);
+  });
+});
+

package/templates/base/tools/builder/core/app/ts-errors.js.hbs

@@ -0,0 +1,58 @@
+import path from 'path';
+
+// tsc reports errors in dist-build's merged copies. This maps each `file(line,col): …` line
+// back to the project's own file: the .html template when the position falls inside a merged
+// template, the source .ts otherwise (its lines after the template shifted back up).
+//   templateMap: { 'src/…/x.component.ts': { html, line, col, lines } } (see merge-templates)
+//   handlerRefs: { 'src/…/x.component.ts': { className, line, col, segment, handlers } } (see handler-refs):
+//   an error in the injected handler references is reported where the handler is named in the template.
+const LOCATION = /^(.+?)\((\d+),(\d+)\)(: .*)$/;
+
+export function remapTscOutput(output, { cwd, tempDir, templateMap, handlerRefs = {} }) {
+  return output
+    .split('\n')
+    .map((line) => {
+      const match = LOCATION.exec(line);
+      if (!match) return line;
+      const [, file, lineNo, colNo, rest] = match;
+      const absolute = path.resolve(cwd, file);
+      if (!absolute.startsWith(tempDir + path.sep)) return line;
+
+      const relPath = path.relative(tempDir, absolute);
+      const handlerRef = mapHandlerRef(handlerRefs[toPosix(relPath)], Number(lineNo), Number(colNo));
+      const { file: mappedFile, line: mappedLine, col: mappedCol } = mapPosition(relPath, handlerRef.line, handlerRef.col, templateMap);
+      // A private handler declared in a parent class: TS2341 names the parent; say what to do.
+      const hint = handlerRef.note && rest.includes('TS2341') ? ' Declare it protected to use it in a subclass template.' : '';
+      return `${toPosix(mappedFile)}(${mappedLine},${mappedCol})${rest}${handlerRef.note}${hint}`;
+    })
+    .join('\n');
+}
+
+export function mapPosition(relPath, line, col, templateMap) {
+  const entry = templateMap[toPosix(relPath)] ?? templateMap[relPath];
+  if (!entry || line < entry.line) return { file: relPath, line, col };
+
+  const lastTemplateLine = entry.line + entry.lines - 1;
+  if (line > lastTemplateLine) return { file: relPath, line: line - (entry.lines - 1), col };
+
+  // Inside the template: its first line starts where the placeholder was.
+  const htmlLine = line - entry.line + 1;
+  return { file: entry.html, line: htmlLine, col: htmlLine === 1 ? col - entry.col + 1 : col };
+}
+
+// A position on a line where handler references were injected: inside them, the handler's place
+// in the template (or the class, for an error about the injection itself); after them, shifted back.
+export function mapHandlerRef(entry, line, col) {
+  if (!entry || line !== entry.line || col < entry.col) return { line, col, note: '' };
+  if (col >= entry.col + entry.segment.length) return { line, col: col - entry.segment.length, note: '' };
+
+  const handler = entry.handlers.find((h) => col >= h.col && col < h.col + h.name.length);
+  if (!handler) return { line, col: Math.max(entry.col - 1, 1), note: ` (data-event handlers of ${entry.className})` };
+  return {
+    line: handler.templateLine,
+    col: handler.templateCol,
+    note: ` (data-event handler "${handler.name}" of ${entry.className})`,
+  };
+}
+
+const toPosix = (p) => p.split(path.sep).join('/');

package/templates/base/tools/builder/core/app/ts-errors.test.js.hbs

@@ -0,0 +1,84 @@
+import path from 'path';
+import { remapTscOutput, mapPosition, mapHandlerRef } from './ts-errors.js';
+
+// A view whose placeholder sat on line 4, column 33, replaced by a 3-line .html template.
+const MAP = {
+  'src/app/views/home/home.view.ts': { html: 'src/app/views/home/home.view.html', line: 4, col: 33, lines: 3 },
+};
+
+describe('ts-errors', () => {
+  it('maps a position before the template to the same line of the source file', () => {
+    expect(mapPosition('src/app/views/home/home.view.ts', 2, 5, MAP)).toEqual({ file: 'src/app/views/home/home.view.ts', line: 2, col: 5 });
+  });
+
+  it('maps a position inside the template to the .html file, the first line\'s column shifted', () => {
+    expect(mapPosition('src/app/views/home/home.view.ts', 4, 40, MAP)).toEqual({ file: 'src/app/views/home/home.view.html', line: 1, col: 8 });
+    expect(mapPosition('src/app/views/home/home.view.ts', 6, 12, MAP)).toEqual({ file: 'src/app/views/home/home.view.html', line: 3, col: 12 });
+  });
+
+  it('shifts positions after the template back up by the lines it added', () => {
+    expect(mapPosition('src/app/views/home/home.view.ts', 9, 3, MAP)).toEqual({ file: 'src/app/views/home/home.view.ts', line: 7, col: 3 });
+  });
+
+  it('leaves files without a merged template as they are', () => {
+    expect(mapPosition('src/core/index.ts', 9, 3, MAP)).toEqual({ file: 'src/core/index.ts', line: 9, col: 3 });
+  });
+
+  it('rewrites tsc lines from dist-build to the project\'s files and leaves other lines alone', () => {
+    const cwd = path.resolve('/project');
+    const tempDir = path.join(cwd, 'dist-build');
+    const output = [
+      "dist-build/src/app/views/home/home.view.ts(5,9): error TS2339: Property 'nmae' does not exist on type 'ITask'.",
+      'dist-build/src/core/index.ts(1,1): error TS1000: Something.',
+      '  continued message line',
+      "node_modules/x/index.d.ts(3,1): error TS2000: Elsewhere.",
+    ].join('\n');
+
+    expect(remapTscOutput(output, { cwd, tempDir, templateMap: MAP }).split('\n')).toEqual([
+      "src/app/views/home/home.view.html(2,9): error TS2339: Property 'nmae' does not exist on type 'ITask'.",
+      'src/core/index.ts(1,1): error TS1000: Something.',
+      '  continued message line',
+      "node_modules/x/index.d.ts(3,1): error TS2000: Elsewhere.",
+    ]);
+  });
+
+  // Handler references injected on line 9 from column 31 (see handler-refs.js): "_svae" sits at
+  // column 80 of that line, and is written on line 5, column 26 of the merged template.
+  const SEGMENT = ' static { void ((c: InstanceType<typeof HomeView>) => [c._svae]); }';
+  const REFS = {
+    'src/app/views/home/home.view.ts': {
+      className: 'HomeView', line: 9, col: 31, segment: SEGMENT,
+      handlers: [{ name: '_svae', col: 31 + SEGMENT.indexOf('_svae'), templateLine: 5, templateCol: 26 }],
+    },
+  };
+
+  it('maps an error on an injected handler reference to where the template names it', () => {
+    const entry = REFS['src/app/views/home/home.view.ts'];
+    const col = entry.handlers[0].col;
+    expect(mapHandlerRef(entry, 9, col)).toEqual({ line: 5, col: 26, note: ' (data-event handler "_svae" of HomeView)' });
+    expect(mapHandlerRef(entry, 9, col + 4).line).toBe(5);
+  });
+
+  it('shifts positions after the injected references back, and leaves other lines alone', () => {
+    const entry = REFS['src/app/views/home/home.view.ts'];
+    expect(mapHandlerRef(entry, 9, 31 + SEGMENT.length + 2)).toEqual({ line: 9, col: 33, note: '' });
+    expect(mapHandlerRef(entry, 9, 12)).toEqual({ line: 9, col: 12, note: '' });
+    expect(mapHandlerRef(entry, 10, 40)).toEqual({ line: 10, col: 40, note: '' });
+    expect(mapHandlerRef(undefined, 9, 40)).toEqual({ line: 9, col: 40, note: '' });
+  });
+
+  it('reports a handler error at the .html line, with a hint for a parent\'s private handler', () => {
+    const cwd = path.resolve('/project');
+    const tempDir = path.join(cwd, 'dist-build');
+    const col = REFS['src/app/views/home/home.view.ts'].handlers[0].col;
+    const output = [
+      `dist-build/src/app/views/home/home.view.ts(9,${col}): error TS2551: Property '_svae' does not exist on type 'HomeView'. Did you mean '_save'?`,
+      `dist-build/src/app/views/home/home.view.ts(9,${col}): error TS2341: Property '_svae' is private and only accessible within class 'Base'.`,
+    ].join('\n');
+
+    expect(remapTscOutput(output, { cwd, tempDir, templateMap: MAP, handlerRefs: REFS }).split('\n')).toEqual([
+      "src/app/views/home/home.view.html(2,26): error TS2551: Property '_svae' does not exist on type 'HomeView'. Did you mean '_save'? (data-event handler \"_svae\" of HomeView)",
+      "src/app/views/home/home.view.html(2,26): error TS2341: Property '_svae' is private and only accessible within class 'Base'. (data-event handler \"_svae\" of HomeView) Declare it protected to use it in a subclass template.",
+    ]);
+  });
+});

package/templates/base/tools/builder/core/app/validate-routes.js.hbs

@@ -1,77 +1,43 @@
 import { readFileSync } from 'fs';
 import path from 'path';
-import ts from 'typescript';
-import { print, errorExit } from '../../../utils/index.js';
+import { errorExit } from '../../../utils/index.js';
 import { PATHS } from './paths.js';
+import { builderConfig } from '../../builder.config.js';
+import { findDuplicateRouteKeys, readRoutesImporters } from './route-keys.js';
 
-const ROUTES_FILE = path.join(PATHS.sourceApp, 'routes.ts');
+const ROUTES_FILE = path.join(PATHS.sourceApp, 'routes.{{#if (eq lang "js")}}js{{else}}ts{{/if}}');
 
-function findAppRoutesObjectLiteral(sourceFile) {
-  let objectLiteral;
+// Only when the routes are used: imported by app code, or prerendered (generateSEOFiles bundles
+// appRoutes). An app without the router (components mounted into a page) needs no routes file.
+async function validateRoutes() {
+  const importers = readRoutesImporters(PATHS.sourceApp, ROUTES_FILE);
+  if (importers.length === 0 && !builderConfig.generateSEO) return;
 
-  ts.forEachChild(sourceFile, function visit(node) {
-    if (
-      ts.isVariableDeclaration(node) &&
-      ts.isIdentifier(node.name) &&
-      node.name.text === 'appRoutes' &&
-      node.initializer &&
-      ts.isObjectLiteralExpression(node.initializer)
-    ) {
-      objectLiteral = node.initializer;
-      return;
-    }
-    ts.forEachChild(node, visit);
-  });
-
-  return objectLiteral;
-}
-
-function getRouteKeys(objectLiteral) {
-  return objectLiteral.properties
-    .filter((prop) => ts.isPropertyAssignment(prop) && ts.isStringLiteralLike(prop.name))
-    .map((prop) => prop.name.text);
-}
-
-function findDuplicates(keys) {
-  const seen = new Set();
-  const duplicates = new Set();
-
-  for (const key of keys) {
-    if (seen.has(key)) duplicates.add(key);
-    seen.add(key);
-  }
-
-  return [...duplicates];
-}
-
-function validateRoutes() {
   let source;
   try {
     source = readFileSync(ROUTES_FILE, 'utf-8');
   } catch {
-    errorExit(`Failed to read ${ROUTES_FILE}`);
+    const usedBy = importers.length
+      ? `imported by ${importers.map((file) => path.relative(process.cwd(), file)).join(', ')}`
+      : 'needed by generateSEOFiles';
+    errorExit(`Failed to read ${ROUTES_FILE} (${usedBy})`, 'validate-routes');
   }
 
-  const sourceFile = ts.createSourceFile(ROUTES_FILE, source, ts.ScriptTarget.Latest, true);
-  const objectLiteral = findAppRoutesObjectLiteral(sourceFile);
-
-  if (!objectLiteral) {
-    errorExit(`Could not find an "appRoutes" object literal in ${ROUTES_FILE}`);
+  if (!/\bappRoutes\b/.test(source)) {
+    errorExit(`Could not find "appRoutes" in ${ROUTES_FILE}`, 'validate-routes');
   }
 
-  const duplicates = findDuplicates(getRouteKeys(objectLiteral));
+  const duplicates = await findDuplicateRouteKeys(source, { loader: '{{#if (eq lang "js")}}js{{else}}ts{{/if}}', sourcefile: ROUTES_FILE });
 
   if (duplicates.length > 0) {
-    const list = duplicates.map((key) => `"${key}"`).join(', ');
+    const list = duplicates.map(({ key, line }) => `"${key}"${line ? ` (line ${line})` : ''}`).join(', ');
     errorExit(
-      `Duplicate route key(s) in ${ROUTES_FILE}: ${list} — an earlier route with this path is silently unreachable.`
+      `Duplicate route key(s) in ${ROUTES_FILE}: ${list} — an earlier route with this path is silently unreachable.`,
+      'validate-routes'
     );
   }
-
 }
 
-try {
-  validateRoutes();
-} catch(err) {
+validateRoutes().catch((err) => {
   errorExit(err, 'validate-routes');
-}
+});

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

@@ -5,11 +5,17 @@ import { builderConfig } from '../builder.config.js';
 import { print, errorExit } from "../../utils/index.js";
 
 function finalizeBuild() {
+  removeBuildFiles();
   if (builderConfig.isProd) removeFoldersAfterBundle();
   if (builderConfig.isProd) removeNutinConfig();
   replaceDir(PATHS.temp, PATHS.build);
 }
 
+// Only used during the build: compile-ts's tsconfig and merge-templates' template map.
+function removeBuildFiles() {
+  ['tsconfig.json', '.template-map.json'].forEach((file) => fs.rmSync(path.join(PATHS.temp, file), { force: true }));
+}
+
 function removeFoldersAfterBundle() {
   const foldersToRemove = [ 'core', 'app', path.join('..', 'config') ];
   const pathToFolder = (folder) => path.join(PATHS.tempSource, folder);

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));