@design.estate/wcctools 6.0.0 → 6.1.0

package/ts/standards/helpers.ast.ts

@@ -0,0 +1,208 @@
+import * as plugins from '../plugins.js';
+
+const ts = plugins.typescript;
+
+export type TNode = plugins.typescript.Node;
+export type TSourceFile = plugins.typescript.SourceFile;
+export type TClassDeclaration = plugins.typescript.ClassDeclaration;
+export type TClassElement = plugins.typescript.ClassElement;
+export type TPropertyDeclaration = plugins.typescript.PropertyDeclaration;
+export type TObjectLiteralExpression = plugins.typescript.ObjectLiteralExpression;
+export type TCallExpression = plugins.typescript.CallExpression;
+export type TExpression = plugins.typescript.Expression;
+export type TTypeNode = plugins.typescript.TypeNode;
+export type TStringLiteralLike = plugins.typescript.StringLiteralLike;
+
+export const parseSource = (fileArg: string, textArg: string): TSourceFile =>
+  ts.createSourceFile(fileArg, textArg, ts.ScriptTarget.Latest, true);
+
+/** 1-based line and column of a position. */
+export const lineAndColumn = (sourceFileArg: TSourceFile, positionArg: number): { line: number; column: number } => {
+  const location = sourceFileArg.getLineAndCharacterOfPosition(positionArg);
+  return { line: location.line + 1, column: location.character + 1 };
+};
+
+/** The called name of `name(...)` or `a.b.name(...)`. */
+export const calleeName = (expressionArg: TExpression): string | null => {
+  if (ts.isIdentifier(expressionArg)) {
+    return expressionArg.text;
+  }
+  if (ts.isPropertyAccessExpression(expressionArg)) {
+    return expressionArg.name.text;
+  }
+  return null;
+};
+
+/** The decorator call named `nameArg` on a node, e.g. `@customElement('x')`. */
+export const findDecoratorCall = (nodeArg: TNode, namesArg: readonly string[]): { name: string; call: TCallExpression } | null => {
+  if (!ts.canHaveDecorators(nodeArg)) {
+    return null;
+  }
+  for (const decorator of ts.getDecorators(nodeArg) ?? []) {
+    if (ts.isCallExpression(decorator.expression)) {
+      const name = calleeName(decorator.expression.expression);
+      if (name && namesArg.includes(name)) {
+        return { name, call: decorator.expression };
+      }
+    }
+  }
+  return null;
+};
+
+export const hasModifier = (nodeArg: TNode, kindArg: plugins.typescript.SyntaxKind): boolean =>
+  ts.canHaveModifiers(nodeArg) && (ts.getModifiers(nodeArg) ?? []).some((modifierArg) => modifierArg.kind === kindArg);
+
+/** The text of a member name: identifier, private identifier (with '#'), string or numeric literal. */
+export const memberNameText = (memberArg: TClassElement): string | null => {
+  const name = memberArg.name;
+  if (!name) {
+    return null;
+  }
+  if (ts.isIdentifier(name) || ts.isStringLiteral(name) || ts.isNumericLiteral(name)) {
+    return name.text;
+  }
+  if (ts.isPrivateIdentifier(name)) {
+    return name.text;
+  }
+  return null;
+};
+
+export const isStatic = (memberArg: TNode): boolean => hasModifier(memberArg, ts.SyntaxKind.StaticKeyword);
+
+/** The static property declaration `static <name> = …` of a class. */
+export const findStaticProperty = (classArg: TClassDeclaration, nameArg: string): TPropertyDeclaration | null => {
+  for (const member of classArg.members) {
+    if (ts.isPropertyDeclaration(member) && isStatic(member) && memberNameText(member) === nameArg) {
+      return member;
+    }
+  }
+  return null;
+};
+
+export const isStringLiteralLike = (nodeArg: TNode | undefined): nodeArg is TStringLiteralLike =>
+  !!nodeArg && (ts.isStringLiteral(nodeArg) || ts.isNoSubstitutionTemplateLiteral(nodeArg));
+
+/** A property assignment `key: value` of an object literal, by key. */
+export const objectProperty = (objectArg: TObjectLiteralExpression, keyArg: string): plugins.typescript.PropertyAssignment | null => {
+  for (const property of objectArg.properties) {
+    if (ts.isPropertyAssignment(property)) {
+      const name = property.name;
+      if ((ts.isIdentifier(name) || ts.isStringLiteral(name)) && name.text === keyArg) {
+        return property;
+      }
+    }
+  }
+  return null;
+};
+
+/** The source text of an object literal property's value, or null. */
+export const objectPropertyText = (objectArg: TObjectLiteralExpression, keyArg: string): string | null =>
+  objectProperty(objectArg, keyArg)?.initializer.getText() ?? null;
+
+/** The indentation (leading whitespace) of the line a position is on. */
+export const indentationAt = (textArg: string, positionArg: number): string => {
+  const lineStart = textArg.lastIndexOf('\n', positionArg - 1) + 1;
+  return /^[ \t]*/.exec(textArg.slice(lineStart))![0];
+};
+
+export interface ITextEdit {
+  start: number;
+  end: number;
+  text: string;
+}
+
+/**
+ * The edit that adds `propertyTextArg` (e.g. `reflect: true`) as the last property of an object
+ * literal, following the literal's own layout: inline literals stay on one line, multi-line
+ * literals get a new line with the indentation of their last property.
+ */
+export const appendObjectPropertyEdit = (objectArg: TObjectLiteralExpression, propertyTextArg: string): ITextEdit => {
+  const sourceText = objectArg.getSourceFile().text;
+  const properties = objectArg.properties;
+  if (properties.length === 0) {
+    return { start: objectArg.getStart(), end: objectArg.end, text: `{ ${propertyTextArg} }` };
+  }
+  const last = properties[properties.length - 1];
+  const closeBrace = objectArg.end - 1;
+  const between = sourceText.slice(last.end, closeBrace);
+  const multiLine = sourceText.slice(objectArg.getStart(), objectArg.end).includes('\n');
+  if (multiLine) {
+    const indentation = indentationAt(sourceText, last.getStart());
+    const commaIndex = between.indexOf(',');
+    if (commaIndex !== -1) {
+      const at = last.end + commaIndex + 1;
+      return { start: at, end: at, text: `\n${indentation}${propertyTextArg},` };
+    }
+    return { start: last.end, end: last.end, text: `,\n${indentation}${propertyTextArg}` };
+  }
+  return { start: last.end, end: last.end, text: `, ${propertyTextArg}` };
+};
+
+/** The edit that adds `propertyTextArg` (e.g. `type: String`) as the first property of an object literal. */
+export const prependObjectPropertyEdit = (objectArg: TObjectLiteralExpression, propertyTextArg: string): ITextEdit => {
+  const sourceText = objectArg.getSourceFile().text;
+  const properties = objectArg.properties;
+  if (properties.length === 0) {
+    return { start: objectArg.getStart(), end: objectArg.end, text: `{ ${propertyTextArg} }` };
+  }
+  const first = properties[0];
+  const multiLine = sourceText.slice(objectArg.getStart(), objectArg.end).includes('\n');
+  const start = first.getStart();
+  if (multiLine && sourceText.slice(objectArg.getStart() + 1, start).includes('\n')) {
+    return { start, end: start, text: `${propertyTextArg},\n${indentationAt(sourceText, start)}` };
+  }
+  return { start, end: start, text: `${propertyTextArg}, ` };
+};
+
+/** The position after the last import declaration, at the start of the following line; 0 without imports. */
+export const afterLastImport = (sourceFileArg: TSourceFile): number => {
+  let position = 0;
+  for (const statement of sourceFileArg.statements) {
+    if (ts.isImportDeclaration(statement) || ts.isImportEqualsDeclaration(statement)) {
+      position = statement.end;
+    }
+  }
+  if (position === 0) {
+    return 0;
+  }
+  const newline = sourceFileArg.text.indexOf('\n', position);
+  return newline === -1 ? sourceFileArg.text.length : newline + 1;
+};
+
+/** The module an identifier is imported from in a file, e.g. `html` → `lit`. */
+export const importSourceOf = (sourceFileArg: TSourceFile, identifierArg: string): string | null => {
+  for (const statement of sourceFileArg.statements) {
+    if (!ts.isImportDeclaration(statement) || !statement.importClause || !ts.isStringLiteral(statement.moduleSpecifier)) {
+      continue;
+    }
+    const clause = statement.importClause;
+    if (clause.name?.text === identifierArg) {
+      return statement.moduleSpecifier.text;
+    }
+    const bindings = clause.namedBindings;
+    if (bindings && ts.isNamespaceImport(bindings) && bindings.name.text === identifierArg) {
+      return statement.moduleSpecifier.text;
+    }
+    if (bindings && ts.isNamedImports(bindings) && bindings.elements.some((elementArg) => elementArg.name.text === identifierArg)) {
+      return statement.moduleSpecifier.text;
+    }
+  }
+  return null;
+};
+
+/** Every relative-capable module specifier literal of a file: imports, re-exports, dynamic `import()` and `import('…')` types. */
+export const moduleSpecifierLiterals = (sourceFileArg: TSourceFile): TStringLiteralLike[] => {
+  const found: TStringLiteralLike[] = [];
+  const visit = (nodeArg: TNode): void => {
+    if ((ts.isImportDeclaration(nodeArg) || ts.isExportDeclaration(nodeArg)) && nodeArg.moduleSpecifier && isStringLiteralLike(nodeArg.moduleSpecifier)) {
+      found.push(nodeArg.moduleSpecifier);
+    } else if (ts.isCallExpression(nodeArg) && nodeArg.expression.kind === ts.SyntaxKind.ImportKeyword && isStringLiteralLike(nodeArg.arguments[0])) {
+      found.push(nodeArg.arguments[0]);
+    } else if (ts.isImportTypeNode(nodeArg) && ts.isLiteralTypeNode(nodeArg.argument) && isStringLiteralLike(nodeArg.argument.literal)) {
+      found.push(nodeArg.argument.literal);
+    }
+    ts.forEachChild(nodeArg, visit);
+  };
+  visit(sourceFileArg);
+  return found;
+};

package/ts/standards/helpers.paths.ts

@@ -0,0 +1,119 @@
+import * as plugins from '../plugins.js';
+
+/**
+ * Repository paths in the standard are relative to the repository root with '/' separators.
+ */
+
+const posix = plugins.path.posix;
+
+export const toPosix = (pathArg: string): string => pathArg.split(plugins.path.sep).join('/');
+
+export const dirOf = (fileArg: string): string => posix.dirname(fileArg);
+
+export const baseOf = (fileArg: string): string => posix.basename(fileArg);
+
+export const joinPath = (...partsArg: string[]): string => posix.normalize(posix.join(...partsArg));
+
+/** A demo file: `<name>.demo.ts`, `demo.ts`, `<name>.demodata.ts` (and similar), or any file under `ts_web/demos/`. */
+export const isDemoFile = (fileArg: string): boolean =>
+  /(^|[./-])demo(data)?\.ts$/.test(baseOf(fileArg)) || fileArg.startsWith('ts_web/demos/');
+
+export const isTypeScriptSource = (fileArg: string): boolean =>
+  /\.(ts|tsx|mts|cts)$/.test(fileArg) && !/\.d\.(ts|mts|cts)$/.test(fileArg);
+
+/**
+ * True for a path the fixer may write: relative to the repository root, '/' separators, already
+ * normalised, and without '.' or '..' segments, so it cannot leave the root lexically.
+ */
+export const isRepoPath = (pathArg: string): boolean =>
+  pathArg.length > 0
+  && !pathArg.includes('\\')
+  && !pathArg.includes('\0')
+  && posix.normalize(pathArg) === pathArg
+  && pathArg.split('/').every((segmentArg) => segmentArg !== '' && segmentArg !== '.' && segmentArg !== '..');
+
+/**
+ * How a relative module specifier spells its target: `exact` names the file itself (`./x.ts`,
+ * `./data.json`, `./x.d.ts`), `js` names a TypeScript file by its emitted extension (`./x.js` for
+ * `x.ts` or `x.d.ts`), `none` leaves the extension out (`./x`, or `./folder` for its index file).
+ */
+type TSpecifierStyle = 'exact' | 'js' | 'none';
+
+export interface IResolvedSpecifier {
+  /** The resolved repository path. */
+  target: string;
+  style: TSpecifierStyle;
+  /** True when the specifier names a folder and resolved to its index file. */
+  viaFolder: boolean;
+}
+
+/** The files an emitted extension stands for, in NodeNext resolution order. */
+const sourcesOfEmittedExtension: Record<string, string[]> = {
+  '.js': ['.ts', '.tsx', '.d.ts'],
+  '.jsx': ['.tsx'],
+  '.mjs': ['.mts', '.d.mts'],
+  '.cjs': ['.cts', '.d.cts'],
+};
+
+/** The files an extensionless specifier stands for, in resolution order. */
+const extensionlessSuffixes = ['.ts', '.tsx', '.d.ts'];
+const folderIndexSuffixes = ['/index.ts', '/index.tsx', '/index.d.ts'];
+
+const typeScriptExtension = /(\.d)?\.(ts|tsx|mts|cts)$/;
+
+/**
+ * Resolves a relative module specifier against the importing file the way NodeNext resolution
+ * does: an emitted `.js` specifier maps back to its `.ts`, `.tsx` or `.d.ts` source, any other
+ * specifier that names a known file exactly resolves to it (`.ts`, `.json`, `.css`, `.d.ts`, …), and
+ * an extensionless one to a source or a folder's index file. Returns null for package specifiers
+ * and for targets that are not among the known files.
+ */
+export const resolveSpecifier = (
+  fromFileArg: string,
+  specifierArg: string,
+  existsArg: (fileArg: string) => boolean,
+): IResolvedSpecifier | null => {
+  if (!specifierArg.startsWith('./') && !specifierArg.startsWith('../')) {
+    return null;
+  }
+  const raw = joinPath(dirOf(fromFileArg), specifierArg);
+  const extension = posix.extname(raw);
+  for (const sourceExtension of sourcesOfEmittedExtension[extension] ?? []) {
+    const target = raw.slice(0, -extension.length) + sourceExtension;
+    if (existsArg(target)) {
+      return { target, style: 'js', viaFolder: false };
+    }
+  }
+  if (existsArg(raw)) {
+    return { target: raw, style: 'exact', viaFolder: false };
+  }
+  for (const suffix of extensionlessSuffixes) {
+    if (existsArg(`${raw}${suffix}`)) {
+      return { target: `${raw}${suffix}`, style: 'none', viaFolder: false };
+    }
+  }
+  for (const suffix of folderIndexSuffixes) {
+    if (existsArg(`${raw}${suffix}`)) {
+      return { target: `${raw}${suffix}`, style: 'none', viaFolder: true };
+    }
+  }
+  return null;
+};
+
+/** The relative specifier from a file to a target, spelled in the given style. */
+export const specifierFor = (fromFileArg: string, targetArg: string, styleArg: TSpecifierStyle, viaFolderArg = false): string => {
+  let target = targetArg;
+  if (styleArg === 'none' && viaFolderArg && /^index(\.d)?\.(ts|tsx)$/.test(baseOf(target))) {
+    target = dirOf(target);
+  } else if (styleArg === 'none') {
+    target = target.replace(typeScriptExtension, '');
+  } else if (styleArg === 'js') {
+    const emitted: Record<string, string> = { ts: '.js', tsx: '.jsx', mts: '.mjs', cts: '.cjs' };
+    target = target.replace(typeScriptExtension, (_matchArg, _declarationArg, extensionArg: string) => emitted[extensionArg]);
+  }
+  let relative = posix.relative(dirOf(fromFileArg), target);
+  if (!relative.startsWith('.')) {
+    relative = `./${relative}`;
+  }
+  return relative;
+};

package/ts/standards/index.ts

@@ -0,0 +1,22 @@
+export { initialBaselines, rekeyStandardConfig, updatedBaselines, type IBaselineRaise } from './baselines.js';
+export { checkStandard, describeStandardRules, detectFindings, rulesOfProfile, type IDetectedFinding } from './checker.js';
+export { GitRepo } from './classes.gitrepo.js';
+export { SourceEdits } from './classes.sourceedits.js';
+export { StandardFixer, type IStandardFixOptions } from './classes.standardfixer.js';
+export { StandardProject, loadStandardProject, type IStandardElement, type IStandardProperty } from './classes.standardproject.js';
+export { FixBatch, StandardTree } from './classes.standardtree.js';
+export {
+  SmartconfigStandardConfigWriter,
+  openStandardConfig,
+  validateStandardConfig,
+  wcctoolsConfigKey,
+  type ILoadedStandardConfig,
+  type IOpenedStandardConfig,
+  type IStandardConfigWriter,
+} from './config.js';
+export { StandardConfigError, StandardUsageError } from './errors.js';
+export { isDemoFile, resolveSpecifier, specifierFor } from './helpers.paths.js';
+export { registerStandardCommands } from './cli.js';
+export { renderFixResult, renderStandardReport } from './output.js';
+export { initBaselines, updateBaselines, type IBaselineRunResult } from './ratchet.js';
+export { allowlistStaleRuleId, fixOrder, standardRules } from './rules/index.js';

package/ts/standards/output.ts

@@ -0,0 +1,65 @@
+import * as plugins from '../plugins.js';
+
+type IStandardReport = plugins.interfaces.IStandardReport;
+type IStandardFinding = plugins.interfaces.IStandardFinding;
+
+const isShown = (findingArg: IStandardFinding, verboseArg: boolean): boolean =>
+  verboseArg || (!findingArg.covered && findingArg.severity !== 'info');
+
+/** The text form of a check report: findings grouped by file, then a summary. */
+export const renderStandardReport = (reportArg: IStandardReport, verboseArg: boolean): string[] => {
+  const lines: string[] = [];
+  let currentFile: string | null = null;
+  for (const finding of reportArg.findings.filter((findingArg) => isShown(findingArg, verboseArg))) {
+    if (finding.file !== currentFile) {
+      if (currentFile !== null) {
+        lines.push('');
+      }
+      lines.push(finding.file);
+      currentFile = finding.file;
+    }
+    const notes = [finding.fixable ? 'fixable' : '', finding.covered ? `covered by the ${finding.covered}` : ''].filter(Boolean);
+    lines.push(`  ${finding.line}:${finding.column}  ${finding.severity}  ${finding.ruleId}  ${finding.message}${notes.length ? ` (${notes.join(', ')})` : ''}`);
+  }
+  if (verboseArg && reportArg.baselineSlack.length > 0) {
+    lines.push('', 'Below their baseline:');
+    for (const slack of reportArg.baselineSlack) {
+      lines.push(`  ${slack.ruleId}  ${slack.file}  ${slack.baseline} → ${slack.current}`);
+    }
+  }
+  const count = (predicateArg: (findingArg: IStandardFinding) => boolean): number => reportArg.findings.filter(predicateArg).length;
+  const failing = count((findingArg) => findingArg.severity === 'error' && !findingArg.covered);
+  const warnings = count((findingArg) => findingArg.severity === 'warn' && !findingArg.covered);
+  const infos = count((findingArg) => findingArg.severity === 'info' && !findingArg.covered);
+  const allowlisted = count((findingArg) => findingArg.covered === 'allowlist');
+  const baselined = count((findingArg) => findingArg.covered === 'baseline');
+  if (lines.length > 0) {
+    lines.push('');
+  }
+  lines.push(
+    `wcctools check (${reportArg.profile}): ${failing} error(s), ${warnings} warning(s), ${infos} info; `
+    + `${allowlisted} allowlisted, ${baselined} within baselines, ${reportArg.baselineSlack.length} file(s) below their baseline — ${reportArg.ok ? 'ok' : 'failed'}`,
+  );
+  return lines;
+};
+
+/** The text form of a fix result: the changes, then the check that remains. */
+export const renderFixResult = (resultArg: plugins.interfaces.IStandardFixResult, verboseArg: boolean): string[] => {
+  const { plan } = resultArg;
+  const lines: string[] = [resultArg.dryRun ? 'wcctools fix --dry-run would make these changes:' : 'wcctools fix made these changes:'];
+  for (const move of plan.moves) {
+    lines.push(`  git mv ${move.from} ${move.to}`);
+  }
+  for (const file of plan.created) {
+    lines.push(`  create ${file}`);
+  }
+  for (const edited of plan.edited) {
+    lines.push(`  edit ${edited.file} (${edited.ruleIds.join(', ')})`);
+  }
+  if (plan.moves.length + plan.created.length + plan.edited.length === 0) {
+    lines.push('  nothing to fix');
+  }
+  lines.push('', resultArg.dryRun ? 'Remaining after the fix:' : 'Remaining:');
+  lines.push(...renderStandardReport(resultArg.remaining, verboseArg));
+  return lines;
+};

package/ts/standards/ratchet.ts

@@ -0,0 +1,63 @@
+import * as plugins from '../plugins.js';
+import { initialBaselines, updatedBaselines, type IBaselineRaise } from './baselines.js';
+import { checkStandard } from './checker.js';
+import { loadStandardProject } from './classes.standardproject.js';
+import type { IOpenedStandardConfig } from './config.js';
+import { StandardUsageError } from './errors.js';
+
+type IStandardConfig = plugins.interfaces.IStandardConfig;
+
+export interface IBaselineRunResult {
+  /** The check with the configuration as it is after the run. */
+  report: plugins.interfaces.IStandardReport;
+  /** Files per rule written to the baselines; 0 when nothing was written. */
+  writtenFiles: number;
+  /** For --update-baseline: counts that would have to grow; the update was refused when not empty. */
+  raised: IBaselineRaise[];
+}
+
+const hasBaselines = (configArg: IStandardConfig): boolean =>
+  Object.values(configArg.baselines ?? {}).some((countsArg) => Object.keys(countsArg).length > 0);
+
+const withBaselines = (configArg: IStandardConfig, baselinesArg: NonNullable<IStandardConfig['baselines']>): IStandardConfig => {
+  const config: IStandardConfig = { ...configArg };
+  delete config.baselines;
+  return Object.keys(baselinesArg).length > 0 ? { ...config, baselines: baselinesArg } : config;
+};
+
+const countFiles = (baselinesArg: NonNullable<IStandardConfig['baselines']>): number =>
+  Object.values(baselinesArg).reduce((sumArg, countsArg) => sumArg + Object.keys(countsArg).length, 0);
+
+/** `wcctools check --init-baseline`: records the current error counts; only while no baseline exists. */
+export const initBaselines = async (rootDirArg: string, openedArg: IOpenedStandardConfig): Promise<IBaselineRunResult> => {
+  const { loaded, writer } = openedArg;
+  if (hasBaselines(loaded.config)) {
+    throw new StandardUsageError('standard.baselines already exist; lower them with --update-baseline');
+  }
+  const project = await loadStandardProject(rootDirArg);
+  const baselines = initialBaselines(checkStandard(project, loaded));
+  const config = withBaselines(loaded.config, baselines);
+  if (countFiles(baselines) > 0) {
+    await writer.writeStandardConfig(config);
+  }
+  return { report: checkStandard(project, { ...loaded, config }), writtenFiles: countFiles(baselines), raised: [] };
+};
+
+/** `wcctools check --update-baseline`: lowers counts to the current ones, removes zeros, refuses to raise any. */
+export const updateBaselines = async (rootDirArg: string, openedArg: IOpenedStandardConfig): Promise<IBaselineRunResult> => {
+  const { loaded, writer } = openedArg;
+  if (!hasBaselines(loaded.config)) {
+    throw new StandardUsageError('standard.baselines do not exist; record them with --init-baseline');
+  }
+  const project = await loadStandardProject(rootDirArg);
+  const report = checkStandard(project, loaded);
+  const { baselines, raised } = updatedBaselines(report, loaded.config.baselines!);
+  if (raised.length > 0) {
+    return { report, writtenFiles: 0, raised };
+  }
+  const config = withBaselines(loaded.config, baselines);
+  if (JSON.stringify(config) !== JSON.stringify(loaded.config)) {
+    await writer.writeStandardConfig(config);
+  }
+  return { report: checkStandard(project, { ...loaded, config }), writtenFiles: countFiles(baselines), raised };
+};

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