@rblabs-dev/axiom 0.0.0-stage → 1.2.0

package/cli/project.mjs

@@ -0,0 +1,105 @@
+// What every `axiom` command needs to know about the app it runs on (docs/design-system.md,
+// section 14): the Angular project's folders, read from angular.json in the current directory,
+// and the kit files shipped next to this CLI.
+
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// The package root: dist/axiom (or node_modules/@rblabs-dev/axiom) when installed, projects/axiom
+// in the Axiom workspace.
+export const kitDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+export const kitInventoryPath = path.join(kitDir, 'material-symbols-icons.txt');
+export const brandDir = path.join(kitDir, 'brand');
+
+// Parses `--name value` pairs. Options listed in `repeatable` collect every value in an array.
+export function parseOptions(argv, { repeatable = [] } = {}) {
+  const options = Object.fromEntries(repeatable.map((name) => [name, []]));
+  for (let index = 0; index < argv.length; index += 2) {
+    const flag = argv[index];
+    const value = argv[index + 1];
+    if (!flag.startsWith('--') || value === undefined || value.startsWith('--')) {
+      throw new Error(`Expected "--<option> <value>", got "${flag}".`);
+    }
+    const name = flag.slice(2);
+    if (repeatable.includes(name)) options[name].push(value);
+    else options[name] = value;
+  }
+  return options;
+}
+
+// The Angular application in ./angular.json: `--project <name>`, or the only application there.
+export function resolveProject(projectName, cwd = process.cwd()) {
+  const angularPath = path.join(cwd, 'angular.json');
+  if (!existsSync(angularPath)) {
+    throw new Error(`No angular.json in ${cwd}. Run axiom from the folder that holds it.`);
+  }
+  const projects = JSON.parse(readFileSync(angularPath, 'utf8')).projects ?? {};
+  let name = projectName;
+  if (!name) {
+    const applications = Object.keys(projects).filter(
+      (key) => projects[key].projectType === 'application',
+    );
+    if (applications.length !== 1) {
+      throw new Error(
+        `angular.json has ${applications.length} applications; pass --project <name>.`,
+      );
+    }
+    [name] = applications;
+  }
+  const config = projects[name];
+  if (!config) throw new Error(`angular.json has no project "${name}".`);
+
+  const root = config.root ?? '';
+  const buildOptions = (config.architect ?? config.targets)?.build?.options ?? {};
+  const { outputPath } = buildOptions;
+  const outputBase =
+    typeof outputPath === 'string' ? outputPath : (outputPath?.base ?? `dist/${name}`);
+  const browser =
+    typeof outputPath === 'object' && outputPath?.browser !== undefined
+      ? outputPath.browser
+      : 'browser';
+  // The folder served at the site root, as in `{ "glob": "**/*", "input": "public" }`.
+  const publicAsset = (buildOptions.assets ?? []).find(
+    (asset) => typeof asset === 'object' && asset.glob === '**/*' && !asset.output,
+  );
+
+  return {
+    name,
+    rootDir: path.join(cwd, root),
+    sourceDir: path.join(cwd, config.sourceRoot ?? path.join(root, 'src')),
+    publicDir: path.join(cwd, publicAsset?.input ?? path.join(root, 'public')),
+    browserDir: path.join(cwd, outputBase, browser),
+    // The app's own icons; the kit's icons come from kitInventoryPath.
+    iconInventoryPath: path.join(cwd, root, 'scripts/material-symbols-icons.txt'),
+    allowlistPath: path.join(cwd, root, 'style-literals.allowlist.json'),
+  };
+}
+
+export function readInventory(file) {
+  const names = readFileSync(file, 'utf8')
+    .split(/\r?\n/u)
+    .map((line) => line.trim())
+    .filter(Boolean);
+  const invalid = names.filter((name) => !/^[a-z0-9_]+$/u.test(name));
+  if (invalid.length > 0) {
+    throw new Error(`Invalid icon names in ${file}: ${invalid.join(', ')}`);
+  }
+  if (new Set(names).size !== names.length) {
+    throw new Error(`${file} contains duplicate icon names.`);
+  }
+  return names;
+}
+
+// Every icon the app's font must hold: the kit's inventory plus the app's own, when it has one. An
+// app may also list kit icons; they are counted once.
+export function readIconInventories(project) {
+  const files = [kitInventoryPath];
+  if (existsSync(project.iconInventoryPath)) files.push(project.iconInventoryPath);
+  const names = new Set(files.flatMap((file) => readInventory(file)));
+  return { files, names: [...names].sort() };
+}
+
+export function relativeToCwd(file) {
+  return path.relative(process.cwd(), file) || '.';
+}

package/cli/verify-production-assets.mjs

@@ -0,0 +1,146 @@
+// Post-build check of an app's self-hosted assets (docs/design-system.md, sections 10 and 12).
+//
+//   axiom verify-production-assets [--project <name>] [--scan <dir>]...
+//       (npm run verify:production-assets, after the production build)
+//
+// Fails the build when:
+//
+// - the built index.html references Google Fonts;
+// - the favicon is missing or not referenced;
+// - the app's public/fonts/ does not hold exactly one Material Symbols subset, the built
+//   stylesheet does not reference it, its name's content hash does not match its bytes, or it
+//   exceeds 16 KB;
+// - a template or component under the app's source root (src/), or under a `--scan` folder, uses
+//   an icon missing from both the kit's inventory and the app's scripts/material-symbols-icons.txt.
+//
+// Icon names are read from `icon="…"` attributes, `icon: '…'` properties and `<mat-icon>` content:
+// a literal name, or the quoted results of a conditional or fallback in an interpolation
+// (`{{ starred ? 'star' : 'star_border' }}`). Names computed any other way (a method call, a
+// property) are not detected and must be added to the inventory by hand.
+
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import path from 'node:path';
+
+import { parseOptions, readIconInventories, relativeToCwd, resolveProject } from './project.mjs';
+
+const fontPattern = /^material-symbols-outlined-.+\.woff2$/u;
+const hashedFontPattern = /\.([0-9a-f]{8})\.woff2$/u;
+const maxFontBytes = 16_000;
+
+const iconNamePattern = /^[a-z][a-z0-9_]*$/u;
+const iconAttributePatterns = [/icon="([a-z][a-z0-9_]*)"/gu, /icon:\s*'([a-z][a-z0-9_]*)'/gu];
+// Prettier may split the closing tag of a long element across lines (`</mat-icon\n>`).
+const matIconPattern = /<mat-icon\b[^>]*>([^<]*)<\/mat-icon\s*>/gu;
+const interpolationPattern = /\{\{([\s\S]*?)\}\}/gu;
+// A quoted name that is a result of `?:`, `??` or `||`: it follows one of those operators and ends
+// the expression or a ternary branch. Function arguments such as `sortIcon('status')` are skipped.
+const resultNamePattern = /(?:\?\??|:|\|\|)\s*(['"])([a-z][a-z0-9_]*)\1(?=\s*(?::|$))/gu;
+
+function fail(message) {
+  throw new Error(message);
+}
+
+function listFiles(directory, predicate) {
+  const files = [];
+  for (const entry of readdirSync(directory, { withFileTypes: true })) {
+    const entryPath = path.join(directory, entry.name);
+    if (entry.isDirectory()) files.push(...listFiles(entryPath, predicate));
+    else if (entry.isFile() && predicate(entry.name)) files.push(entryPath);
+  }
+  return files;
+}
+
+// Icon names used by one template or component source.
+export function iconNamesInSource(source) {
+  const names = new Set();
+  for (const pattern of iconAttributePatterns) {
+    for (const match of source.matchAll(pattern)) names.add(match[1]);
+  }
+  for (const [, content] of source.matchAll(matIconPattern)) {
+    const text = content.trim();
+    if (iconNamePattern.test(text)) names.add(text);
+    for (const [, interpolation] of text.matchAll(interpolationPattern)) {
+      // Pipe arguments (`value | pipe: 'arg'`) are not results; drop everything after a pipe.
+      const [expression] = interpolation.split(/(?<!\|)\|(?!\|)/u);
+      for (const match of expression.trim().matchAll(resultNamePattern)) names.add(match[2]);
+    }
+  }
+  return names;
+}
+
+function usedIconNames(directories) {
+  const names = new Set();
+  const sources = directories.flatMap((directory) =>
+    listFiles(directory, (name) => /\.(html|ts)$/u.test(name) && !name.endsWith('.spec.ts')),
+  );
+  for (const file of sources) {
+    for (const name of iconNamesInSource(readFileSync(file, 'utf8'))) names.add(name);
+  }
+  return names;
+}
+
+export function run(argv) {
+  const options = parseOptions(argv, { repeatable: ['scan'] });
+  const project = resolveProject(options.project);
+  const { browserDir } = project;
+  const indexPath = path.join(browserDir, 'index.html');
+  if (!existsSync(indexPath))
+    fail(`Missing production index: ${relativeToCwd(indexPath)}; build the app first.`);
+  const indexHtml = readFileSync(indexPath, 'utf8');
+
+  for (const host of ['fonts.googleapis.com', 'fonts.gstatic.com']) {
+    if (indexHtml.includes(host)) fail(`Production index still references ${host}.`);
+  }
+
+  if (!indexHtml.includes('favicon.svg')) fail('Production index does not reference favicon.svg.');
+  if (!existsSync(path.join(browserDir, 'favicon.svg')))
+    fail(`Missing favicon asset in ${relativeToCwd(browserDir)}.`);
+
+  const publicFontsDir = path.join(project.publicDir, 'fonts');
+  if (!existsSync(publicFontsDir))
+    fail(`Missing ${relativeToCwd(publicFontsDir)}; run axiom build-icon-font.`);
+  const fonts = readdirSync(publicFontsDir).filter((name) => fontPattern.test(name));
+  if (fonts.length !== 1) {
+    fail(
+      `Expected exactly one Material Symbols subset in ${relativeToCwd(publicFontsDir)}, found ${fonts.length}: ${fonts.join(', ')}`,
+    );
+  }
+  const [fontName] = fonts;
+  const fontPath = path.join(browserDir, 'fonts', fontName);
+  if (!existsSync(fontPath)) fail(`Missing self-hosted icon font: ${relativeToCwd(fontPath)}`);
+
+  const fontBytes = readFileSync(fontPath);
+  const declaredHash = hashedFontPattern.exec(fontName)?.[1];
+  if (declaredHash) {
+    const actualHash = createHash('sha256').update(fontBytes).digest('hex').slice(0, 8);
+    if (actualHash !== declaredHash) {
+      fail(
+        `${fontName} was edited after it was built (content hash ${actualHash}). Rebuild it with axiom build-icon-font.`,
+      );
+    }
+  }
+  if (fontBytes.length > maxFontBytes) fail(`Icon font is too large: ${fontBytes.length} bytes.`);
+
+  const stylesheets = readdirSync(browserDir).filter((name) => /^styles-[^/]+\.css$/u.test(name));
+  if (stylesheets.length === 0) fail('Missing hashed production stylesheet.');
+  const referenced = stylesheets.some((name) =>
+    readFileSync(path.join(browserDir, name), 'utf8').includes(`/fonts/${fontName}`),
+  );
+  if (!referenced) fail(`Production stylesheet does not reference /fonts/${fontName}.`);
+
+  const inventory = new Set(readIconInventories(project).names);
+  const scanned = [project.sourceDir, ...options.scan.map((directory) => path.resolve(directory))];
+  const missing = [...usedIconNames(scanned)].filter((name) => !inventory.has(name));
+  if (missing.length > 0) {
+    fail(
+      `Material Symbols missing from the inventory: ${missing.join(', ')}. Add them to ` +
+        `${relativeToCwd(project.iconInventoryPath)} and run axiom build-icon-font.`,
+    );
+  }
+
+  console.log(
+    `Production asset verification passed: favicon present, ${inventory.size} icon names tracked, ` +
+      `icon font ${fontName} is ${statSync(fontPath).size} bytes.`,
+  );
+}