@design.estate/wcctools 5.1.0 → 6.1.0

package/ts/standards/config.ts

@@ -0,0 +1,160 @@
+import * as plugins from '../plugins.js';
+import { StandardConfigError } from './errors.js';
+import { severityIn } from './rule.js';
+import { standardRules } from './rules/index.js';
+
+type IStandardConfig = plugins.interfaces.IStandardConfig;
+type TStandardProfile = plugins.interfaces.TStandardProfile;
+
+/** The key of wcctools' configuration in `.smartconfig.json`. */
+export const wcctoolsConfigKey = '@design.estate/wcctools';
+
+/** Persists the `standard` configuration of the repository it was read from. */
+export interface IStandardConfigWriter {
+  writeStandardConfig(configArg: IStandardConfig): Promise<void>;
+}
+
+export interface ILoadedStandardConfig {
+  config: IStandardConfig;
+  profile: TStandardProfile;
+}
+
+/** A validated configuration together with the writer bound to the `.smartconfig.json` it was read from. */
+export interface IOpenedStandardConfig {
+  loaded: ILoadedStandardConfig;
+  writer: IStandardConfigWriter;
+}
+
+/**
+ * Writes through the Smartconfig instance that read the configuration, so a write is refused
+ * (SmartconfigChangedError) when `.smartconfig.json` changed in between. Other keys of the
+ * `@design.estate/wcctools` block keep their values.
+ */
+export class SmartconfigStandardConfigWriter implements IStandardConfigWriter {
+  private readonly smartconfig: plugins.smartconfig.Smartconfig;
+
+  constructor(smartconfigArg: plugins.smartconfig.Smartconfig) {
+    this.smartconfig = smartconfigArg;
+  }
+
+  public async writeStandardConfig(configArg: IStandardConfig): Promise<void> {
+    const block = this.smartconfig.dataFor<Record<string, unknown>>(wcctoolsConfigKey, {});
+    await this.smartconfig.writeDataFor(wcctoolsConfigKey, { ...block, standard: configArg });
+  }
+}
+
+const isPlainObject = (valueArg: unknown): valueArg is Record<string, unknown> =>
+  typeof valueArg === 'object' && valueArg !== null && !Array.isArray(valueArg);
+
+const knownKeys = ['profile', 'tagPrefix', 'groupNames', 'allowlist', 'baselines'];
+
+/** Validates the `standard` object; collects every problem into one StandardConfigError. */
+export const validateStandardConfig = (valueArg: unknown): ILoadedStandardConfig => {
+  const problems: string[] = [];
+  if (valueArg === undefined) {
+    throw new StandardConfigError([`"${wcctoolsConfigKey}".standard is missing`]);
+  }
+  if (!isPlainObject(valueArg)) {
+    throw new StandardConfigError([`"${wcctoolsConfigKey}".standard must be an object`]);
+  }
+  for (const key of Object.keys(valueArg)) {
+    if (!knownKeys.includes(key)) {
+      problems.push(`standard.${key} is not a known key (${knownKeys.join(', ')})`);
+    }
+  }
+  const profile = valueArg.profile ?? 'base';
+  if (profile !== 'base' && profile !== 'dees') {
+    problems.push(`standard.profile must be 'base' or 'dees'`);
+  }
+  if (valueArg.tagPrefix === undefined) {
+    problems.push('standard.tagPrefix is missing');
+  } else if (typeof valueArg.tagPrefix !== 'string' || !/^[a-z][a-z0-9]*(-[a-z0-9]+)*$/.test(valueArg.tagPrefix)) {
+    problems.push('standard.tagPrefix must be a lowercase tag prefix without the trailing hyphen, e.g. "dees"');
+  }
+  if (valueArg.groupNames !== undefined) {
+    if (!isPlainObject(valueArg.groupNames)) {
+      problems.push('standard.groupNames must be an object of area → display name');
+    } else {
+      for (const [area, name] of Object.entries(valueArg.groupNames)) {
+        if (typeof name !== 'string' || name.length === 0) {
+          problems.push(`standard.groupNames.${area} must be a non-empty string`);
+        }
+      }
+    }
+  }
+  const rulesById = new Map(standardRules.map((ruleArg) => [ruleArg.id, ruleArg]));
+  if (valueArg.allowlist !== undefined) {
+    if (!isPlainObject(valueArg.allowlist)) {
+      problems.push('standard.allowlist must be an object of rule id → entries');
+    } else {
+      for (const [ruleId, entries] of Object.entries(valueArg.allowlist)) {
+        const rule = rulesById.get(ruleId);
+        if (!rule) {
+          problems.push(`standard.allowlist: unknown rule '${ruleId}'`);
+          continue;
+        }
+        if (!rule.allowlistCategories) {
+          problems.push(`standard.allowlist: rule '${ruleId}' takes no allowlist entries`);
+          continue;
+        }
+        if (!isPlainObject(entries)) {
+          problems.push(`standard.allowlist['${ruleId}'] must be an object of '<file>#<member>' → '<category>: <reason>'`);
+          continue;
+        }
+        for (const [key, value] of Object.entries(entries)) {
+          const match = typeof value === 'string' ? /^([a-z-]+):\s*(\S.*)$/.exec(value) : null;
+          if (!match) {
+            problems.push(`standard.allowlist['${ruleId}']['${key}'] must be '<category>: <reason>'`);
+          } else if (!rule.allowlistCategories.includes(match[1])) {
+            problems.push(`standard.allowlist['${ruleId}']['${key}']: unknown category '${match[1]}' (${rule.allowlistCategories.join(', ')})`);
+          }
+        }
+      }
+    }
+  }
+  if (valueArg.baselines !== undefined) {
+    if (!isPlainObject(valueArg.baselines)) {
+      problems.push('standard.baselines must be an object of rule id → file → count');
+    } else {
+      for (const [ruleId, counts] of Object.entries(valueArg.baselines)) {
+        const rule = rulesById.get(ruleId);
+        if (!rule) {
+          problems.push(`standard.baselines: unknown rule '${ruleId}'`);
+          continue;
+        }
+        if ((profile === 'base' || profile === 'dees') && severityIn(rule, profile) !== 'error') {
+          problems.push(`standard.baselines: '${ruleId}' is not an error rule of the '${profile}' profile; baselines hold error rules only`);
+          continue;
+        }
+        if (!isPlainObject(counts)) {
+          problems.push(`standard.baselines['${ruleId}'] must be an object of file → count`);
+          continue;
+        }
+        for (const [file, count] of Object.entries(counts)) {
+          if (typeof count !== 'number' || !Number.isInteger(count) || count < 1) {
+            problems.push(`standard.baselines['${ruleId}']['${file}'] must be an integer of at least 1`);
+          }
+        }
+      }
+    }
+  }
+  if (problems.length > 0) {
+    throw new StandardConfigError(problems);
+  }
+  return { config: valueArg as unknown as IStandardConfig, profile: profile as TStandardProfile };
+};
+
+/** Reads and validates `.smartconfig.json` → `@design.estate/wcctools` → `standard` of a repository. */
+export const openStandardConfig = (rootDirArg: string): IOpenedStandardConfig => {
+  let smartconfig: plugins.smartconfig.Smartconfig;
+  try {
+    smartconfig = new plugins.smartconfig.Smartconfig(rootDirArg);
+  } catch (error) {
+    throw new StandardConfigError([`.smartconfig.json cannot be read: ${error instanceof Error ? error.message : String(error)}`]);
+  }
+  if (!smartconfig.smartconfigJsonExists) {
+    throw new StandardConfigError([`${rootDirArg} has no .smartconfig.json`]);
+  }
+  const wcctoolsConfig = smartconfig.dataFor<plugins.interfaces.IWccToolsConfig>(wcctoolsConfigKey, {});
+  return { loaded: validateStandardConfig(wcctoolsConfig.standard), writer: new SmartconfigStandardConfigWriter(smartconfig) };
+};

package/ts/standards/errors.ts

@@ -0,0 +1,18 @@
+/** The `standard` configuration is missing or invalid; the CLI exits with code 2. */
+export class StandardConfigError extends Error {
+  public readonly problems: string[];
+
+  constructor(problemsArg: string[]) {
+    super(`Invalid wcctools standard configuration in .smartconfig.json:\n${problemsArg.map((problemArg) => `  - ${problemArg}`).join('\n')}`);
+    this.name = 'StandardConfigError';
+    this.problems = problemsArg;
+  }
+}
+
+/** A precondition or argument of `check`/`fix` is not met; the CLI exits with code 2. */
+export class StandardUsageError extends Error {
+  constructor(messageArg: string) {
+    super(messageArg);
+    this.name = 'StandardUsageError';
+  }
+}

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