@design.estate/wcctools 6.0.0 → 6.2.0

package/ts/standards/rules/barrel.no-demo-export.ts

@@ -0,0 +1,30 @@
+import { baseOf, isDemoFile } from '../helpers.paths.js';
+import type { IRuleFinding, IStandardRule } from '../rule.js';
+import { removeStatement } from './shared.js';
+
+/** No barrel exports a demo file. */
+export const barrelNoDemoExportRule: IStandardRule = {
+  id: 'barrel/no-demo-export',
+  severity: { base: 'error' },
+  fixMode: 'auto',
+  detect: ({ project }) => {
+    const findings: IRuleFinding[] = [];
+    for (const file of project.webFiles) {
+      if (baseOf(file) !== 'index.ts') {
+        continue;
+      }
+      for (const reexport of project.reexports(file)) {
+        if (reexport.target && isDemoFile(reexport.target)) {
+          findings.push({
+            file,
+            position: reexport.statement.getStart(),
+            key: file,
+            message: `${file} exports the demo file ${reexport.target}`,
+            fix: (builderArg) => removeStatement(builderArg, file, reexport.statement),
+          });
+        }
+      }
+    }
+    return findings;
+  },
+};

package/ts/standards/rules/demo.fixture-not-exported.ts

@@ -0,0 +1,30 @@
+import { elementsBarrel } from '../classes.standardproject.js';
+import type { IRuleFinding, IStandardRule } from '../rule.js';
+import { elementKey, removeStatement } from './shared.js';
+
+/** Elements declared in demo files are not reachable from `ts_web/elements/index.ts`. */
+export const demoFixtureNotExportedRule: IStandardRule = {
+  id: 'demo/fixture-not-exported',
+  severity: { base: 'warn' },
+  fixMode: 'auto',
+  detect: ({ project }) => {
+    const findings: IRuleFinding[] = [];
+    const reached = project.reachableFrom(elementsBarrel);
+    for (const element of project.elements) {
+      if (!element.inDemoFile || !reached.has(element.file)) {
+        continue;
+      }
+      const exporters = [...reached].flatMap((fileArg) => project.reexports(fileArg)).filter((reexportArg) => reexportArg.target === element.file);
+      findings.push({
+        file: element.file,
+        position: element.decoratorCall.getStart(),
+        key: elementKey(element),
+        message: `fixture element <${element.tag ?? '?'}> in a demo file is reachable from ${elementsBarrel}`,
+        fix: exporters.length > 0
+          ? (builderArg) => exporters.forEach((reexportArg) => removeStatement(builderArg, reexportArg.file, reexportArg.statement))
+          : undefined,
+      });
+    }
+    return findings;
+  },
+};

package/ts/standards/rules/demo.groups.ts

@@ -0,0 +1,74 @@
+import * as plugins from '../../plugins.js';
+import * as ast from '../helpers.ast.js';
+import type { IRuleFinding, IStandardRule } from '../rule.js';
+import { catalogElements, elementKey, groupAreaOf, nextLineStart } from './shared.js';
+
+const ts = plugins.typescript;
+
+const quote = (textArg: string): string => `'${textArg.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
+
+/**
+ * An element with a demo declares `static demoGroups`, a non-empty string or array of non-empty strings.
+ * dees: the first entry is `standard.groupNames[<area>]` of the element's `00group-<area>`.
+ */
+export const demoGroupsRule: IStandardRule = {
+  id: 'demo/groups',
+  severity: { base: 'warn' },
+  fixMode: 'auto',
+  detect: ({ project, config, profile }) => {
+    const findings: IRuleFinding[] = [];
+    for (const element of catalogElements(project)) {
+      const demo = ast.findStaticProperty(element.classNode, 'demo');
+      if (!demo) {
+        continue;
+      }
+      const area = profile === 'dees' ? groupAreaOf(element.file) : null;
+      const expected = area ? config.groupNames?.[area] ?? null : null;
+      const base = { file: element.file, key: elementKey(element) };
+      const member = ast.findStaticProperty(element.classNode, 'demoGroups');
+      const text = element.sourceFile.text;
+
+      if (!member) {
+        const finding: IRuleFinding = { ...base, position: demo.getStart(), message: `${element.className ?? '?'} has a demo but no static demoGroups` };
+        if (expected) {
+          const at = nextLineStart(text, demo.end);
+          finding.fix = (builderArg) => builderArg.edit(element.file, at, at, `${ast.indentationAt(text, demo.getStart())}public static demoGroups = [${quote(expected)}];\n`);
+        }
+        findings.push(finding);
+        continue;
+      }
+      const initializer = member.initializer;
+      let entries: string[] | null = null;
+      if (initializer && ast.isStringLiteralLike(initializer)) {
+        entries = [initializer.text];
+      } else if (initializer && ts.isArrayLiteralExpression(initializer) && initializer.elements.every(ast.isStringLiteralLike)) {
+        entries = initializer.elements.map((entryArg) => (entryArg as ast.TStringLiteralLike).text);
+      } else if (!initializer || ts.isArrayLiteralExpression(initializer) || ts.isLiteralExpression(initializer)) {
+        findings.push({ ...base, position: member.getStart(), message: `static demoGroups of ${element.className ?? '?'} is not a string or an array of strings` });
+        continue;
+      }
+      if (entries && (entries.length === 0 || entries.some((entryArg) => entryArg.length === 0))) {
+        findings.push({ ...base, position: member.getStart(), message: `static demoGroups of ${element.className ?? '?'} is empty or has an empty entry` });
+        continue;
+      }
+      if (profile !== 'dees' || !area || !entries) {
+        continue;
+      }
+      if (!expected) {
+        findings.push({ ...base, position: member.getStart(), message: `standard.groupNames has no display name for the area '${area}'` });
+        continue;
+      }
+      if (entries[0] !== expected) {
+        const target = initializer!;
+        const reordered = [expected, ...entries.filter((entryArg) => entryArg !== expected)];
+        findings.push({
+          ...base,
+          position: member.getStart(),
+          message: `the first demo group of ${element.className ?? '?'} is ${quote(entries[0])}; expected ${quote(expected)} (00group-${area})`,
+          fix: (builderArg) => builderArg.edit(element.file, target.getStart(), target.end, `[${reordered.map(quote).join(', ')}]`),
+        });
+      }
+    }
+    return findings;
+  },
+};

package/ts/standards/rules/demo.required.ts

@@ -0,0 +1,49 @@
+import * as ast from '../helpers.ast.js';
+import { dirOf } from '../helpers.paths.js';
+import type { IRuleFinding, IStandardRule } from '../rule.js';
+import { catalogElements, elementKey, isCustomElementName } from './shared.js';
+
+/** Every exported element has `static demo`. The opt-in fix writes a stub that renders the bare tag. */
+export const demoRequiredRule: IStandardRule = {
+  id: 'demo/required',
+  severity: { base: 'warn' },
+  fixMode: 'opt-in',
+  allowlistCategories: ['subcomponent', 'base'],
+  detect: ({ project }) => {
+    const findings: IRuleFinding[] = [];
+    const elements = catalogElements(project);
+    for (const element of elements) {
+      if (!element.exported || ast.findStaticProperty(element.classNode, 'demo')) {
+        continue;
+      }
+      const finding: IRuleFinding = {
+        file: element.file,
+        position: element.decoratorCall.getStart(),
+        key: elementKey(element),
+        message: `${element.className ?? '?'} (<${element.tag ?? '?'}>) has no static demo`,
+      };
+      const sourceFile = element.sourceFile;
+      // The stub's file name and markup come from the tag: only a valid custom element name is usable.
+      const usableTag = element.tag && isCustomElementName(element.tag) ? element.tag : null;
+      const demoFile = usableTag ? `${dirOf(element.file)}/${usableTag}.demo.ts` : null;
+      const firstMember = element.classNode.members[0];
+      const alone = elements.filter((otherArg) => otherArg.file === element.file).length === 1;
+      if (usableTag && demoFile && element.className && firstMember && alone && !project.exists(demoFile) && !/\bdemoFunc\b/.test(sourceFile.text)) {
+        const tag = usableTag;
+        const customElementSource = ast.importSourceOf(sourceFile, 'customElement');
+        const htmlSource = ast.importSourceOf(sourceFile, 'html')
+          ?? (customElementSource && customElementSource !== 'lit/decorators.js' ? customElementSource : 'lit');
+        const text = sourceFile.text;
+        const importAt = ast.afterLastImport(sourceFile);
+        finding.fix = (builderArg) => {
+          builderArg.create(demoFile, `import { html } from '${htmlSource}';\n\nexport const demoFunc = () => html\`<${tag}></${tag}>\`;\n`);
+          builderArg.edit(element.file, importAt, importAt, `import { demoFunc } from './${tag}.demo.js';\n`);
+          const lineStart = text.lastIndexOf('\n', firstMember.getStart() - 1) + 1;
+          builderArg.edit(element.file, lineStart, lineStart, `${ast.indentationAt(text, firstMember.getStart())}public static demo = demoFunc;\n`);
+        };
+      }
+      findings.push(finding);
+    }
+    return findings;
+  },
+};

package/ts/standards/rules/demo.separate-file.ts

@@ -0,0 +1,40 @@
+import * as plugins from '../../plugins.js';
+import * as ast from '../helpers.ast.js';
+import { isDemoFile, resolveSpecifier } from '../helpers.paths.js';
+import type { IRuleFinding, IStandardRule } from '../rule.js';
+import { catalogElements, elementKey, rootIdentifier } from './shared.js';
+
+const ts = plugins.typescript;
+
+/** `static demo` refers to an export of the element's demo file. Report-only in 6.1. */
+export const demoSeparateFileRule: IStandardRule = {
+  id: 'demo/separate-file',
+  severity: { base: 'warn', dees: 'error' },
+  fixMode: 'none',
+  detect: ({ project }) => {
+    const findings: IRuleFinding[] = [];
+    for (const element of catalogElements(project)) {
+      const member = ast.findStaticProperty(element.classNode, 'demo');
+      if (!member?.initializer) {
+        continue;
+      }
+      const initializer = member.initializer;
+      const references = ts.isArrayLiteralExpression(initializer) ? [...initializer.elements] : [initializer];
+      const separate = references.length > 0 && references.every((referenceArg) => {
+        const identifier = rootIdentifier(referenceArg);
+        const source = identifier ? ast.importSourceOf(element.sourceFile, identifier) : null;
+        const resolved = source ? resolveSpecifier(element.file, source, (fileArg) => project.files.has(fileArg)) : null;
+        return !!resolved && isDemoFile(resolved.target);
+      });
+      if (!separate) {
+        findings.push({
+          file: element.file,
+          position: member.getStart(),
+          key: elementKey(element),
+          message: `static demo of ${element.className ?? '?'} is not imported from its demo file (${element.tag ?? '<tag>'}.demo.ts)`,
+        });
+      }
+    }
+    return findings;
+  },
+};

package/ts/standards/rules/demo.shape.ts

@@ -0,0 +1,42 @@
+import * as plugins from '../../plugins.js';
+import * as ast from '../helpers.ast.js';
+import type { IRuleFinding, IStandardRule } from '../rule.js';
+import { catalogElements, elementKey } from './shared.js';
+
+const ts = plugins.typescript;
+
+/** A demo factory: a function, or a reference to one (identifier or property access). */
+const isFactory = (expressionArg: ast.TExpression): boolean =>
+  ts.isArrowFunction(expressionArg)
+  || ts.isFunctionExpression(expressionArg)
+  || ts.isIdentifier(expressionArg)
+  || ts.isPropertyAccessExpression(expressionArg);
+
+/** `static demo` is a function or a non-empty array of functions. */
+export const demoShapeRule: IStandardRule = {
+  id: 'demo/shape',
+  severity: { base: 'error' },
+  fixMode: 'none',
+  detect: ({ project }) => {
+    const findings: IRuleFinding[] = [];
+    for (const element of catalogElements(project)) {
+      const member = ast.findStaticProperty(element.classNode, 'demo');
+      if (!member) {
+        continue;
+      }
+      const initializer = member.initializer;
+      const valid = !!initializer && (ts.isArrayLiteralExpression(initializer)
+        ? initializer.elements.length > 0 && initializer.elements.every(isFactory)
+        : isFactory(initializer));
+      if (!valid) {
+        findings.push({
+          file: element.file,
+          position: member.getStart(),
+          key: elementKey(element),
+          message: `static demo of ${element.className ?? '?'} is not a function or a non-empty array of functions`,
+        });
+      }
+    }
+    return findings;
+  },
+};

package/ts/standards/rules/docs.component-index.ts

@@ -0,0 +1,88 @@
+import type { StandardProject } from '../classes.standardproject.js';
+import { joinPath } from '../helpers.paths.js';
+import type { IRuleFinding, IStandardRule } from '../rule.js';
+import { catalogElements } from './shared.js';
+
+export const componentIndexStart = '<!-- component-index:start -->';
+export const componentIndexEnd = '<!-- component-index:end -->';
+const readme = 'readme.md';
+
+/** GitHub-style heading anchor. */
+const slug = (headingArg: string): string => headingArg.toLowerCase().replace(/[^\p{L}\p{N}\s_-]/gu, '').replace(/ /g, '-');
+
+const headingsOf = (textArg: string): Set<string> => new Set([...textArg.matchAll(/^#{1,6}\s+(.+)$/gm)].map((matchArg) => slug(matchArg[1])));
+
+/** The generated component index block: one row per element under `ts_web/elements`, sorted by tag. */
+export const renderComponentIndex = (projectArg: StandardProject, readmeTextArg: string): string => {
+  const headings = headingsOf(readmeTextArg);
+  const rows = catalogElements(projectArg)
+    .filter((elementArg) => elementArg.tag && elementArg.className && elementArg.file.startsWith('ts_web/elements/'))
+    .map((elementArg) => {
+      const family = elementArg.file.split('/')[2].replace(/^00group-/, '').replace(/-/g, ' ');
+      const name = elementArg.className!;
+      const api = headings.has(name.toLowerCase()) ? `[${name}](#${name.toLowerCase()})` : '—';
+      return { tag: elementArg.tag!, row: `| \`${elementArg.tag}\` | ${family} | ${api} | [Source](${elementArg.file}) |` };
+    })
+    .sort((a, b) => a.tag.localeCompare(b.tag, 'en'));
+  return `${componentIndexStart}\n| Element | Family | API | Source |\n| --- | --- | --- | --- |\n${rows.map((rowArg) => rowArg.row).join('\n')}\n${componentIndexEnd}`;
+};
+
+/** dees: the readme's generated component index is current and its relative links resolve. */
+export const docsComponentIndexRule: IStandardRule = {
+  id: 'docs/component-index',
+  severity: { dees: 'error' },
+  fixMode: 'auto',
+  detect: ({ project }) => {
+    const findings: IRuleFinding[] = [];
+    const text = project.files.get(readme);
+    if (text === undefined) {
+      return [{ file: readme, position: 0, key: readme, message: 'readme.md is missing' }];
+    }
+    const first = text.indexOf(componentIndexStart);
+    const last = text.indexOf(componentIndexEnd);
+    if (first < 0 || last < first) {
+      findings.push({ file: readme, position: 0, key: readme, message: `readme.md has no ${componentIndexStart} … ${componentIndexEnd} block` });
+    } else {
+      const generated = renderComponentIndex(project, text);
+      const end = last + componentIndexEnd.length;
+      if (text.slice(first, end) !== generated) {
+        findings.push({
+          file: readme,
+          position: first,
+          key: readme,
+          message: 'the component index is stale',
+          fix: (builderArg) => builderArg.edit(readme, first, end, generated),
+        });
+      }
+    }
+    const headings = headingsOf(text);
+    const withoutCode = text.replace(/^```[^\n]*\n[\s\S]*?^```/gm, (blockArg) => blockArg.replace(/[^\n]/g, ' '));
+    for (const match of withoutCode.matchAll(/\[[^\]]*\]\(([^\s)]+)\)/g)) {
+      const target = match[1];
+      if (/^[a-z]+:/i.test(target)) {
+        continue;
+      }
+      if (target.startsWith('#')) {
+        if (!headings.has(target.slice(1))) {
+          findings.push({ file: readme, position: match.index, key: readme, message: `link to a missing section: ${target}` });
+        }
+        continue;
+      }
+      const file = target.split('#')[0];
+      if (!file) {
+        continue;
+      }
+      let decoded: string;
+      try {
+        decoded = decodeURIComponent(file);
+      } catch {
+        findings.push({ file: readme, position: match.index, key: readme, message: `malformed link: ${target}` });
+        continue;
+      }
+      if (!project.exists(joinPath(decoded))) {
+        findings.push({ file: readme, position: match.index, key: readme, message: `link to a missing file: ${target}` });
+      }
+    }
+    return findings;
+  },
+};

package/ts/standards/rules/element.exported.ts

@@ -0,0 +1,35 @@
+import * as plugins from '../../plugins.js';
+import type { IRuleFinding, IStandardRule } from '../rule.js';
+import { catalogElements, elementKey } from './shared.js';
+
+const ts = plugins.typescript;
+
+/** The element class is exported. */
+export const elementExportedRule: IStandardRule = {
+  id: 'element/exported',
+  severity: { base: 'error' },
+  fixMode: 'auto',
+  detect: ({ project }) => {
+    const findings: IRuleFinding[] = [];
+    for (const element of catalogElements(project)) {
+      if (element.exported) {
+        continue;
+      }
+      const finding: IRuleFinding = {
+        file: element.file,
+        position: element.decoratorCall.getStart(),
+        key: elementKey(element),
+        message: `class ${element.className ?? '?'} (<${element.tag ?? '?'}>) is not exported`,
+      };
+      // `export` goes before the first keyword modifier (e.g. `abstract`) or the `class` keyword, after the decorators.
+      const firstModifier = (ts.getModifiers(element.classNode) ?? [])[0];
+      const classKeyword = element.classNode.getChildren().find((childArg) => childArg.kind === ts.SyntaxKind.ClassKeyword);
+      const position = firstModifier?.getStart() ?? classKeyword?.getStart();
+      if (position !== undefined && element.classNode.parent === element.sourceFile) {
+        finding.fix = (builderArg) => builderArg.edit(element.file, position, position, 'export ');
+      }
+      findings.push(finding);
+    }
+    return findings;
+  },
+};

package/ts/standards/rules/element.literal-tag.ts

@@ -0,0 +1,30 @@
+import type { IRuleFinding, IStandardRule } from '../rule.js';
+import { elementKey, isCustomElementName } from './shared.js';
+
+/** `@customElement` takes a single string literal that is a valid custom element name. */
+export const elementLiteralTagRule: IStandardRule = {
+  id: 'element/literal-tag',
+  severity: { base: 'error' },
+  fixMode: 'none',
+  detect: ({ project }) => {
+    const findings: IRuleFinding[] = [];
+    for (const element of project.elements) {
+      if (element.tag === null) {
+        findings.push({
+          file: element.file,
+          position: element.decoratorCall.getStart(),
+          key: elementKey(element),
+          message: `@customElement of ${element.className ?? 'an anonymous class'} does not take a single string literal`,
+        });
+      } else if (!isCustomElementName(element.tag)) {
+        findings.push({
+          file: element.file,
+          position: element.decoratorCall.getStart(),
+          key: elementKey(element),
+          message: `'${element.tag}' is not a valid custom element name (a lowercase letter, then lowercase letters, digits, '-', '.' or '_', with at least one '-')`,
+        });
+      }
+    }
+    return findings;
+  },
+};

package/ts/standards/rules/element.reachable.ts

@@ -0,0 +1,49 @@
+import { rootBarrel } from '../classes.standardproject.js';
+import { dirOf } from '../helpers.paths.js';
+import type { IRuleFinding, IStandardRule } from '../rule.js';
+import { addReexport, catalogElements, elementKey } from './shared.js';
+
+/** Every entry file outside demo files is reachable from `ts_web/index.ts`. */
+export const elementReachableRule: IStandardRule = {
+  id: 'element/reachable',
+  severity: { base: 'error' },
+  fixMode: 'auto',
+  allowlistCategories: ['internal'],
+  detect: ({ project }) => {
+    const findings: IRuleFinding[] = [];
+    const reached = project.reachableFrom(rootBarrel);
+    for (const element of catalogElements(project)) {
+      if (reached.has(element.file)) {
+        continue;
+      }
+      const finding: IRuleFinding = {
+        file: element.file,
+        position: element.decoratorCall.getStart(),
+        key: elementKey(element),
+        message: `<${element.tag ?? '?'}> in ${element.file} is not reachable from ${rootBarrel}`,
+      };
+      // Walk up to the nearest reachable barrel; an unreachable barrel that already re-exports the file is exported instead.
+      let candidate = element.file;
+      let dir = dirOf(element.file);
+      while (dir.startsWith('ts_web')) {
+        const barrel = `${dir}/index.ts`;
+        if (barrel !== candidate && project.files.has(barrel)) {
+          if (reached.has(barrel)) {
+            const target = candidate;
+            finding.fix = (builderArg) => addReexport(builderArg, project, barrel, target);
+            break;
+          }
+          if (project.reexports(barrel).some((reexportArg) => reexportArg.target === candidate)) {
+            candidate = barrel;
+          }
+        }
+        if (dir === 'ts_web') {
+          break;
+        }
+        dir = dirOf(dir);
+      }
+      findings.push(finding);
+    }
+    return findings;
+  },
+};

package/ts/standards/rules/element.tag-map.ts

@@ -0,0 +1,87 @@
+import * as plugins from '../../plugins.js';
+import * as ast from '../helpers.ast.js';
+import type { IStandardElement } from '../classes.standardproject.js';
+import type { IRuleFinding, IStandardRule, TFixAction } from '../rule.js';
+import { catalogElements, elementKey, isCustomElementName } from './shared.js';
+
+const ts = plugins.typescript;
+
+/** The tags of a file's `declare global { interface HTMLElementTagNameMap { … } }` and the first such interface. */
+const tagMapOf = (sourceFileArg: ast.TSourceFile): { tags: Set<string>; declaration: plugins.typescript.InterfaceDeclaration | null } => {
+  const tags = new Set<string>();
+  let declaration: plugins.typescript.InterfaceDeclaration | null = null;
+  for (const statement of sourceFileArg.statements) {
+    if (!ts.isModuleDeclaration(statement) || !ts.isIdentifier(statement.name) || statement.name.text !== 'global'
+      || !statement.body || !ts.isModuleBlock(statement.body)) {
+      continue;
+    }
+    for (const inner of statement.body.statements) {
+      if (ts.isInterfaceDeclaration(inner) && inner.name.text === 'HTMLElementTagNameMap') {
+        declaration ??= inner;
+        for (const member of inner.members) {
+          if (ts.isPropertySignature(member) && member.name && (ts.isStringLiteral(member.name) || ts.isIdentifier(member.name))) {
+            tags.add(member.name.text);
+          }
+        }
+      }
+    }
+  }
+  return { tags, declaration };
+};
+
+/** Adds every missing element of one file to its tag map, or appends a tag map block to the file. */
+const tagMapFix = (missingArg: IStandardElement[]): TFixAction => (builderArg) => {
+  const sourceFile = missingArg[0].sourceFile;
+  const file = missingArg[0].file;
+  const text = sourceFile.text;
+  const { declaration } = tagMapOf(sourceFile);
+  if (declaration) {
+    const closeBrace = declaration.end - 1;
+    const lineStart = text.lastIndexOf('\n', closeBrace - 1) + 1;
+    const firstMember = declaration.members[0];
+    const indentation = firstMember
+      ? ast.indentationAt(text, firstMember.getStart())
+      : `${ast.indentationAt(text, declaration.getStart())}  `;
+    const lines = missingArg.map((elementArg) => `${indentation}'${elementArg.tag}': ${elementArg.className};\n`).join('');
+    if (/^[ \t]*$/.test(text.slice(lineStart, closeBrace))) {
+      builderArg.edit(file, lineStart, lineStart, lines);
+    } else {
+      builderArg.edit(file, closeBrace, closeBrace, `\n${lines}`);
+    }
+    return;
+  }
+  const members = missingArg.map((elementArg) => `    '${elementArg.tag}': ${elementArg.className};\n`).join('');
+  const prefix = text.length === 0 || text.endsWith('\n') ? '' : '\n';
+  builderArg.edit(file, text.length, text.length, `${prefix}\ndeclare global {\n  interface HTMLElementTagNameMap {\n${members}  }\n}\n`);
+};
+
+/** The entry file declares `declare global { interface HTMLElementTagNameMap { '<tag>': <Class> } }`. */
+export const elementTagMapRule: IStandardRule = {
+  id: 'element/tag-map',
+  severity: { base: 'warn' },
+  fixMode: 'auto',
+  detect: ({ project }) => {
+    const findings: IRuleFinding[] = [];
+    const byFile = new Map<string, IStandardElement[]>();
+    for (const element of catalogElements(project)) {
+      if (element.tag && !tagMapOf(element.sourceFile).tags.has(element.tag)) {
+        byFile.set(element.file, [...(byFile.get(element.file) ?? []), element]);
+      }
+    }
+    for (const missing of byFile.values()) {
+      // The tag is written into the source: only valid custom element names are.
+      const fixable = missing.every((elementArg) => elementArg.className && isCustomElementName(elementArg.tag!));
+      const fix = fixable ? tagMapFix(missing) : undefined;
+      for (const element of missing) {
+        findings.push({
+          file: element.file,
+          position: element.decoratorCall.getStart(),
+          key: elementKey(element),
+          message: `HTMLElementTagNameMap of ${element.file} does not declare '${element.tag}'`,
+          fix,
+        });
+      }
+    }
+    return findings;
+  },
+};

package/ts/standards/rules/i18n.literals.ts

@@ -0,0 +1,58 @@
+import * as plugins from '../../plugins.js';
+import * as ast from '../helpers.ast.js';
+import { isDemoFile } from '../helpers.paths.js';
+import type { IRuleFinding, IStandardRule } from '../rule.js';
+
+const ts = plugins.typescript;
+
+/** The words belong to the catalog; demos, demo data, the i18n catalog and the demo pages show sample content. */
+const isExempt = (fileArg: string): boolean =>
+  isDemoFile(fileArg)
+  || fileArg.startsWith('ts_web/i18n/')
+  || fileArg.startsWith('ts_web/demos/')
+  || fileArg.startsWith('ts_web/pages/');
+
+const wordAttributes = 'aria-label|aria-description|aria-valuetext|title|placeholder|label|text|heading|subheading|alt';
+const wordProperties = new Set(['name', 'label', 'text', 'heading', 'subheading', 'title', 'placeholder', 'message', 'description', 'confirmLabel', 'cancelLabel', 'emptyText', 'tooltip', 'hint']);
+const word = /^[A-Z][a-z]+(?:[ '’,.?!…-]+[A-Za-z]+)*[.?!…]?$/;
+
+/** The patterns of dees-catalog's scripts/check-literal-ratchet.cjs that apply to template and string text. */
+const textPatterns = (): RegExp[] => [
+  // aria-label="Progress"
+  new RegExp(`\\s(?:${wordAttributes})="([A-Za-z][^"$]*[a-z][^"$]*)"`, 'g'),
+  // >Cancel< and > Back <
+  /(?<![=-])>\s*([A-Z][a-z]+(?:[ '’,.?!…-]+[A-Za-z]+)*[.?!…]?)\s*</g,
+];
+
+/** dees: no English literal a reader sees outside demo files, `ts_web/i18n/`, `ts_web/demos/` and `ts_web/pages/`. A ratchet. */
+export const i18nLiteralsRule: IStandardRule = {
+  id: 'i18n/literals',
+  severity: { dees: 'error' },
+  fixMode: 'none',
+  detect: ({ project }) => {
+    const findings: IRuleFinding[] = [];
+    for (const file of project.webFiles) {
+      if (isExempt(file)) {
+        continue;
+      }
+      const visit = (nodeArg: ast.TNode): void => {
+        if (ts.isStringLiteral(nodeArg) || ts.isNoSubstitutionTemplateLiteral(nodeArg)
+          || ts.isTemplateHead(nodeArg) || ts.isTemplateMiddle(nodeArg) || ts.isTemplateTail(nodeArg)) {
+          const text = nodeArg.getText();
+          for (const pattern of textPatterns()) {
+            for (const match of text.matchAll(pattern)) {
+              findings.push({ file, position: nodeArg.getStart() + match.index, key: file, message: `English literal ${match[0].trim()}` });
+            }
+          }
+        }
+        if (ts.isPropertyAssignment(nodeArg) && (ts.isIdentifier(nodeArg.name) || ts.isStringLiteral(nodeArg.name))
+          && wordProperties.has(nodeArg.name.text) && ts.isStringLiteral(nodeArg.initializer) && word.test(nodeArg.initializer.text)) {
+          findings.push({ file, position: nodeArg.getStart(), key: file, message: `English literal ${nodeArg.getText()}` });
+        }
+        ts.forEachChild(nodeArg, visit);
+      };
+      visit(project.sourceFile(file));
+    }
+    return findings;
+  },
+};