@design.estate/wcctools 5.1.0 → 6.1.0

package/ts/standards/rule.ts

@@ -0,0 +1,58 @@
+import * as plugins from '../plugins.js';
+import type { StandardProject } from './classes.standardproject.js';
+
+type TStandardProfile = plugins.interfaces.TStandardProfile;
+type TStandardSeverity = plugins.interfaces.TStandardSeverity;
+
+/** Collects the changes of one fix run of one rule; the fixer applies them to its in-memory tree. */
+export interface IFixBuilder {
+  /** Replaces the span [start, end) of a file's current text. Identical edits are applied once. */
+  edit(fileArg: string, startArg: number, endArg: number, textArg: string): void;
+  /** Creates a file; skipped when the path exists. */
+  create(fileArg: string, textArg: string): void;
+  /** Moves a file (`git mv`) and rewrites every relative module specifier that resolves to it. */
+  move(fromArg: string, toArg: string): void;
+  /**
+   * In this run's moves, `export … from` declarations of barrels (index.ts) that resolve to `targetArg`
+   * point at `barrelTargetArg` instead, e.g. at the new element folder's index.ts.
+   */
+  redirectBarrelExports(targetArg: string, barrelTargetArg: string): void;
+}
+
+export type TFixAction = (builderArg: IFixBuilder) => void;
+
+export interface IRuleFinding {
+  file: string;
+  /** Offset in the file's text; 0 for file-level findings and for files that do not exist. */
+  position: number;
+  message: string;
+  /** Allowlist key: '<file>#<member>' or '<file>'. */
+  key: string;
+  /** Set when `wcctools fix` resolves the finding. */
+  fix?: TFixAction;
+}
+
+export interface IRuleContext {
+  project: StandardProject;
+  config: plugins.interfaces.IStandardConfig;
+  profile: TStandardProfile;
+}
+
+/** One rule of docs/standard.md. */
+export interface IStandardRule {
+  id: string;
+  /** Severity per profile; a rule without a `base` severity belongs to `dees` only. `dees` falls back to `base`. */
+  severity: { base?: TStandardSeverity; dees?: TStandardSeverity };
+  fixMode: plugins.interfaces.TStandardFixMode;
+  /** Categories an allowlist entry may use; absent when the rule takes no allowlist. */
+  allowlistCategories?: readonly string[];
+  detect(contextArg: IRuleContext): IRuleFinding[];
+}
+
+/** The rule's severity in a profile, or null when the rule is not part of it. */
+export const severityIn = (ruleArg: IStandardRule, profileArg: TStandardProfile): TStandardSeverity | null => {
+  if (profileArg === 'dees') {
+    return ruleArg.severity.dees ?? ruleArg.severity.base ?? null;
+  }
+  return ruleArg.severity.base ?? null;
+};

package/ts/standards/rules/barrel.element-index.ts

@@ -0,0 +1,112 @@
+import { baseOf, dirOf, specifierFor } from '../helpers.paths.js';
+import type { IRuleFinding, IStandardRule } from '../rule.js';
+import { addReexport, catalogElements, elementsDir, isInElementFolder } from './shared.js';
+
+/**
+ * An element folder has `index.ts` re-exporting the entry file (and `types.ts`); a group folder's
+ * `index.ts` re-exports each element folder's `index.ts`; `ts_web/elements/index.ts` re-exports each
+ * group or element folder.
+ */
+export const barrelElementIndexRule: IStandardRule = {
+  id: 'barrel/element-index',
+  severity: { base: 'warn' },
+  fixMode: 'auto',
+  detect: ({ project }) => {
+    const findings = new Map<string, IRuleFinding>();
+    const add = (findingArg: IRuleFinding): void => {
+      const id = `${findingArg.file}|${findingArg.message}`;
+      if (!findings.has(id)) {
+        findings.set(id, findingArg);
+      }
+    };
+    const folderElements = catalogElements(project).filter(isInElementFolder);
+    const folders = [...new Set(folderElements.map((elementArg) => dirOf(elementArg.file)))].sort();
+    const groupsWithFolders = new Set<string>();
+
+    for (const element of folderElements) {
+      const folder = dirOf(element.file);
+      const index = `${folder}/index.ts`;
+      const types = `${folder}/types.ts`;
+      if (!project.files.has(index)) {
+        const exported = [element.file, ...(project.files.has(types) ? [types] : [])];
+        add({
+          file: index,
+          position: 0,
+          key: index,
+          message: `${folder}/ has no index.ts`,
+          fix: (builderArg) => builderArg.create(index, exported.map((fileArg) => `export * from '${specifierFor(index, fileArg, 'js')}';\n`).join('')),
+        });
+        continue;
+      }
+      for (const required of [element.file, types]) {
+        if (!project.files.has(required) || project.reexports(index).some((reexportArg) => reexportArg.target === required)) {
+          continue;
+        }
+        add({
+          file: index,
+          position: 0,
+          key: index,
+          message: `${index} does not re-export ./${baseOf(required)}`,
+          fix: (builderArg) => addReexport(builderArg, project, index, required),
+        });
+      }
+
+      const parent = dirOf(folder);
+      const parentIndex = `${parent}/index.ts`;
+      if (parent !== elementsDir) {
+        groupsWithFolders.add(parent);
+      }
+      if (!project.files.has(parentIndex)) {
+        if (parent === elementsDir) {
+          continue;
+        }
+        const groupFolders = folders.filter((folderArg) => dirOf(folderArg) === parent);
+        add({
+          file: parentIndex,
+          position: 0,
+          key: parentIndex,
+          message: `${parent}/ has no index.ts`,
+          fix: (builderArg) => builderArg.create(parentIndex, groupFolders.map((folderArg) =>
+            `export * from '${specifierFor(parentIndex, `${folderArg}/index.ts`, 'js')}';\n`).join('')),
+        });
+        continue;
+      }
+      const parentReexports = project.reexports(parentIndex);
+      if (parentReexports.some((reexportArg) => reexportArg.target === index)) {
+        continue;
+      }
+      const inside = parentReexports.filter((reexportArg) => reexportArg.target?.startsWith(`${folder}/`));
+      const finding: IRuleFinding = {
+        file: parentIndex,
+        position: inside[0]?.statement.getStart() ?? 0,
+        key: parentIndex,
+        message: `${parentIndex} does not re-export ${baseOf(folder)}/index.ts`,
+      };
+      if (inside.length === 0) {
+        finding.fix = (builderArg) => addReexport(builderArg, project, parentIndex, index);
+      } else if (inside.length === 1) {
+        const literal = inside[0].statement.moduleSpecifier!;
+        finding.fix = (builderArg) => builderArg.edit(parentIndex, literal.getStart() + 1, literal.end - 1, specifierFor(parentIndex, index, 'js'));
+      }
+      add(finding);
+    }
+
+    const elementsIndex = `${elementsDir}/index.ts`;
+    if (project.files.has(elementsIndex)) {
+      for (const group of [...groupsWithFolders].sort()) {
+        const groupIndex = `${group}/index.ts`;
+        if (!project.files.has(groupIndex) || project.reexports(elementsIndex).some((reexportArg) => reexportArg.target === groupIndex)) {
+          continue;
+        }
+        add({
+          file: elementsIndex,
+          position: 0,
+          key: elementsIndex,
+          message: `${elementsIndex} does not re-export ${baseOf(group)}/index.ts`,
+          fix: (builderArg) => addReexport(builderArg, project, elementsIndex, groupIndex),
+        });
+      }
+    }
+    return [...findings.values()];
+  },
+};

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;
+  },
+};