@design.estate/wcctools 6.0.0 → 6.1.0

package/ts/standards/classes.standardtree.ts

@@ -0,0 +1,220 @@
+import * as plugins from '../plugins.js';
+import * as ast from './helpers.ast.js';
+import { baseOf, isRepoPath, isTypeScriptSource, resolveSpecifier, specifierFor } from './helpers.paths.js';
+import { SourceEdits } from './classes.sourceedits.js';
+import { StandardProject, type TParseCache } from './classes.standardproject.js';
+import type { IFixBuilder } from './rule.js';
+
+const ts = plugins.typescript;
+
+/** The changes one rule run collected. */
+export class FixBatch implements IFixBuilder {
+  public readonly edits = new Map<string, Array<ast.ITextEdit>>();
+  public readonly creates = new Map<string, string>();
+  public readonly moves = new Map<string, string>();
+  public readonly redirects = new Map<string, string>();
+
+  public edit(fileArg: string, startArg: number, endArg: number, textArg: string): void {
+    this.edits.set(fileArg, [...(this.edits.get(fileArg) ?? []), { start: startArg, end: endArg, text: textArg }]);
+  }
+
+  public create(fileArg: string, textArg: string): void {
+    if (!this.creates.has(fileArg)) {
+      this.creates.set(fileArg, textArg);
+    }
+  }
+
+  public move(fromArg: string, toArg: string): void {
+    if (!this.moves.has(fromArg)) {
+      this.moves.set(fromArg, toArg);
+    }
+  }
+
+  public redirectBarrelExports(targetArg: string, barrelTargetArg: string): void {
+    this.redirects.set(targetArg, barrelTargetArg);
+  }
+}
+
+/**
+ * The fixer's in-memory copy of a repository: the tracked TypeScript sources and the side files the
+ * standard reads, with the moves and edits applied so far. Nothing touches the disk until the
+ * fixer commits the tree. Every path a batch names must be a repository path (see isRepoPath);
+ * a batch with any other path is rejected before it changes the tree.
+ */
+export class StandardTree {
+  public readonly files: Map<string, string>;
+  private readonly originalTexts = new Map<string, string>();
+  /** Current path → original path, for moved files. */
+  private readonly originOf = new Map<string, string>();
+  /** Original paths that were moved away. */
+  private readonly vacated = new Set<string>();
+  public readonly created = new Set<string>();
+  /** Current path → ids of the rules that changed the file. */
+  private readonly changedBy = new Map<string, Set<string>>();
+  private readonly parseCache: TParseCache = new Map();
+  /** Every tracked file of the repository, including those the tree holds no text for (`.json`, `.css`, `.d.ts`, …). */
+  private readonly trackedFiles: ReadonlySet<string>;
+  private readonly existsOnDisk: (fileArg: string) => boolean;
+
+  constructor(filesArg: Map<string, string>, trackedFilesArg: Iterable<string>, existsOnDiskArg: (fileArg: string) => boolean) {
+    this.files = new Map(filesArg);
+    for (const [file, text] of filesArg) {
+      this.originalTexts.set(file, text);
+    }
+    this.trackedFiles = new Set(trackedFilesArg);
+    this.existsOnDisk = existsOnDiskArg;
+  }
+
+  public exists(fileArg: string): boolean {
+    return this.files.has(fileArg) || (!this.vacated.has(fileArg) && this.existsOnDisk(fileArg));
+  }
+
+  /** The model of the tree's current state. */
+  public project(): StandardProject {
+    return new StandardProject(this.files, (fileArg) => this.exists(fileArg), this.parseCache);
+  }
+
+  private markChanged(fileArg: string, ruleIdArg: string): void {
+    this.changedBy.set(fileArg, new Set([...(this.changedBy.get(fileArg) ?? []), ruleIdArg]));
+  }
+
+  /**
+   * Applies a batch: edits, then new files, then moves with import rewriting. Returns the number of
+   * applied changes. Throws without changing the tree when the batch names a path that is not a
+   * repository path.
+   */
+  public apply(ruleIdArg: string, batchArg: FixBatch): number {
+    const outside = [
+      ...batchArg.edits.keys(),
+      ...batchArg.creates.keys(),
+      ...[...batchArg.moves].flat(),
+      ...[...batchArg.redirects].flat(),
+    ].filter((pathArg) => !isRepoPath(pathArg));
+    if (outside.length > 0) {
+      throw new Error(`The fix of ${ruleIdArg} names paths outside the repository root: ${[...new Set(outside)].join(', ')}`);
+    }
+    let applied = 0;
+    for (const [file, edits] of batchArg.edits) {
+      const text = this.files.get(file);
+      if (text === undefined) {
+        continue;
+      }
+      const sourceEdits = new SourceEdits();
+      edits.forEach((editArg) => sourceEdits.add(editArg));
+      const next = sourceEdits.apply(text);
+      if (next !== text) {
+        this.files.set(file, next);
+        this.markChanged(file, ruleIdArg);
+        applied += sourceEdits.size;
+      }
+    }
+    for (const [file, text] of batchArg.creates) {
+      if (this.exists(file)) {
+        continue;
+      }
+      this.files.set(file, text);
+      this.created.add(file);
+      this.markChanged(file, ruleIdArg);
+      applied++;
+    }
+    const moves = new Map<string, string>();
+    const targets = new Set<string>();
+    for (const [from, to] of batchArg.moves) {
+      if (from === to || !this.files.has(from) || targets.has(to) || (this.exists(to) && !batchArg.moves.has(to))) {
+        continue;
+      }
+      moves.set(from, to);
+      targets.add(to);
+    }
+    if (moves.size > 0) {
+      this.rewriteSpecifiers(ruleIdArg, moves, batchArg.redirects);
+      const texts = new Map([...moves.keys()].map((fromArg) => [fromArg, this.files.get(fromArg)!]));
+      for (const [from, to] of moves) {
+        this.files.delete(from);
+        if (this.created.delete(from)) {
+          this.created.add(to);
+        } else {
+          const origin = this.originOf.get(from) ?? from;
+          this.originOf.delete(from);
+          if (origin !== to) {
+            this.originOf.set(to, origin);
+          }
+          if (origin === from) {
+            this.vacated.add(from);
+          }
+        }
+        const changed = this.changedBy.get(from);
+        this.changedBy.delete(from);
+        if (changed) {
+          this.changedBy.set(to, changed);
+        }
+      }
+      for (const [from, to] of moves) {
+        this.files.set(to, texts.get(from)!);
+        this.vacated.delete(to);
+      }
+      applied += moves.size;
+    }
+    return applied;
+  }
+
+  /**
+   * Rewrites every relative module specifier whose importing file or target moves, keeping its
+   * extension style. A specifier resolves to any tracked file (sources, `.d.ts`, `.json`, `.css`, …),
+   * so a moved file's imports of files that stay keep pointing at them. Barrel re-exports of a
+   * redirected target point at the redirect instead.
+   */
+  private rewriteSpecifiers(ruleIdArg: string, movesArg: Map<string, string>, redirectsArg: Map<string, string>): void {
+    const known = (fileArg: string): boolean => this.files.has(fileArg) || (this.trackedFiles.has(fileArg) && !this.vacated.has(fileArg));
+    const project = this.project();
+    for (const [file, text] of [...this.files]) {
+      if (!isTypeScriptSource(file)) {
+        continue;
+      }
+      const newFile = movesArg.get(file) ?? file;
+      const sourceFile = project.sourceFile(file);
+      const edits = new SourceEdits();
+      for (const literal of ast.moduleSpecifierLiterals(sourceFile)) {
+        const resolved = resolveSpecifier(file, literal.text, known);
+        if (!resolved) {
+          continue;
+        }
+        let target = movesArg.get(resolved.target) ?? resolved.target;
+        let viaFolder = resolved.viaFolder;
+        const redirect = redirectsArg.get(resolved.target);
+        if (redirect && redirect !== newFile && ts.isExportDeclaration(literal.parent) && baseOf(newFile) === 'index.ts') {
+          target = redirect;
+          viaFolder = true;
+        }
+        if (newFile === file && target === resolved.target) {
+          continue;
+        }
+        const specifier = specifierFor(newFile, target, resolved.style, viaFolder);
+        if (specifier !== literal.text) {
+          edits.add({ start: literal.getStart() + 1, end: literal.end - 1, text: specifier });
+        }
+      }
+      if (edits.size > 0) {
+        this.files.set(file, edits.apply(text));
+        this.markChanged(file, ruleIdArg);
+      }
+    }
+  }
+
+  /** The tree's changes against the repository it was read from. */
+  public plan(): plugins.interfaces.IStandardFixPlan {
+    const moves = [...this.originOf].map(([to, from]) => ({ from, to })).sort((a, b) => a.from.localeCompare(b.from));
+    const created = [...this.created].sort();
+    const edited: plugins.interfaces.IStandardFixPlan['edited'] = [];
+    for (const [file, ruleIds] of [...this.changedBy].sort(([a], [b]) => a.localeCompare(b))) {
+      if (this.created.has(file)) {
+        continue;
+      }
+      const origin = this.originOf.get(file) ?? file;
+      if (this.files.get(file) !== this.originalTexts.get(origin)) {
+        edited.push({ file, ruleIds: [...ruleIds].sort() });
+      }
+    }
+    return { moves, created, edited };
+  }
+}

package/ts/standards/cli.ts

@@ -0,0 +1,86 @@
+import * as plugins from '../plugins.js';
+import { checkStandard } from './checker.js';
+import { loadStandardProject } from './classes.standardproject.js';
+import { StandardFixer } from './classes.standardfixer.js';
+import { openStandardConfig } from './config.js';
+import { StandardUsageError } from './errors.js';
+import { renderFixResult, renderStandardReport } from './output.js';
+import { initBaselines, updateBaselines } from './ratchet.js';
+
+/**
+ * Registers `wcctools check` and `wcctools fix`. Both work on the current directory, the
+ * repository root that holds `.smartconfig.json`. Exit codes: 0 ok, 1 failing findings or a
+ * refused baseline update, 2 configuration or usage error (StandardConfigError/StandardUsageError).
+ */
+export const registerStandardCommands = (out: plugins.smartconsole.SmartConsole): void => {
+  out.cli.command({
+    name: 'check',
+    description: 'Check the catalog against the wcctools component standard (https://code.foss.global/design.estate/wcctools/src/branch/main/docs/standard.md)',
+    options: {
+      json: { type: 'boolean', description: 'Print the report as one JSON document (IStandardReport) and nothing else' },
+      verbose: { type: 'boolean', description: 'Also list info findings, findings covered by the allowlist or baselines, and baseline slack' },
+      initBaseline: { type: 'boolean', description: 'Record the current error counts as standard.baselines (only while none exist)' },
+      updateBaseline: { type: 'boolean', description: 'Lower standard.baselines to the current counts; refuses to raise any count' },
+    },
+  }, async ({ options }) => {
+    if (options.initBaseline && options.updateBaseline) {
+      throw new StandardUsageError('--init-baseline and --update-baseline exclude each other');
+    }
+    const rootDir = process.cwd();
+    const opened = openStandardConfig(rootDir);
+    const notes: string[] = [];
+    let report: plugins.interfaces.IStandardReport;
+    let refused = false;
+    if (options.initBaseline || options.updateBaseline) {
+      const result = options.initBaseline ? await initBaselines(rootDir, opened) : await updateBaselines(rootDir, opened);
+      report = result.report;
+      if (result.raised.length > 0) {
+        refused = true;
+        for (const raise of result.raised) {
+          await out.error(`refusing to raise the ${raise.ruleId} baseline of ${raise.file}: ${raise.baseline} → ${raise.current}`);
+        }
+      } else {
+        notes.push(`standard.baselines written: ${result.writtenFiles} file(s)`);
+      }
+    } else {
+      report = checkStandard(await loadStandardProject(rootDir), opened.loaded);
+    }
+    if (options.json) {
+      await out.log(JSON.stringify(report));
+    } else {
+      for (const line of [...renderStandardReport(report, !!options.verbose), ...notes]) {
+        await out.log(line);
+      }
+    }
+    process.exitCode = report.ok && !refused ? 0 : 1;
+  });
+
+  out.cli.command({
+    name: 'fix',
+    description: 'Fix findings of the wcctools component standard with span edits and git mv; needs a clean work tree, never commits',
+    options: {
+      rule: { type: 'strings', description: 'Fix only this rule (repeatable); opt-in rules run only when named' },
+      dryRun: { type: 'boolean', description: 'Show the changes without writing anything' },
+      json: { type: 'boolean', description: 'Print the result as one JSON document (IStandardFixResult) and nothing else' },
+      verbose: { type: 'boolean', description: 'Also list info and covered findings of the remaining check' },
+    },
+  }, async ({ options }) => {
+    const rootDir = process.cwd();
+    const opened = openStandardConfig(rootDir);
+    const result = await new StandardFixer({
+      rootDir,
+      loaded: opened.loaded,
+      rules: options.rule,
+      dryRun: !!options.dryRun,
+      configWriter: opened.writer,
+    }).run();
+    if (options.json) {
+      await out.log(JSON.stringify(result));
+    } else {
+      for (const line of renderFixResult(result, !!options.verbose)) {
+        await out.log(line);
+      }
+    }
+    process.exitCode = result.remaining.ok ? 0 : 1;
+  });
+};

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