@design.estate/wcctools 5.1.0 → 6.1.0

package/ts/standards/classes.standardproject.ts

@@ -0,0 +1,250 @@
+import * as plugins from '../plugins.js';
+import * as ast from './helpers.ast.js';
+import { isDemoFile, isTypeScriptSource, resolveSpecifier, toPosix } from './helpers.paths.js';
+
+const ts = plugins.typescript;
+
+/** A class decorated with `@customElement(…)`. */
+export interface IStandardElement {
+  file: string;
+  sourceFile: ast.TSourceFile;
+  classNode: ast.TClassDeclaration;
+  className: string | null;
+  decoratorCall: ast.TCallExpression;
+  /** The literal tag, or null when the decorator argument is not a string literal. */
+  tag: string | null;
+  exported: boolean;
+  inDemoFile: boolean;
+}
+
+/** A class member decorated with `@property(…)` or `@state(…)`. */
+export interface IStandardProperty {
+  file: string;
+  sourceFile: ast.TSourceFile;
+  classNode: ast.TClassDeclaration;
+  member: ast.TClassElement;
+  name: string;
+  decorator: 'property' | 'state';
+  call: ast.TCallExpression;
+  /** The options object literal; null when the decorator has no argument or a non-literal one. */
+  options: ast.TObjectLiteralExpression | null;
+  /** True when the decorator has an argument that is not an object literal. */
+  dynamicOptions: boolean;
+  isPublic: boolean;
+  inDemoFile: boolean;
+}
+
+/** An `export … from '<relative>'` declaration. */
+export interface IStandardReexport {
+  file: string;
+  statement: plugins.typescript.ExportDeclaration;
+  specifier: string;
+  /** The resolved repository path, or null when it does not resolve to a known file. */
+  target: string | null;
+}
+
+export type TParseCache = Map<string, { text: string; sourceFile: ast.TSourceFile }>;
+
+/** The root barrel every reachability check starts from. */
+export const rootBarrel = 'ts_web/index.ts';
+export const elementsBarrel = 'ts_web/elements/index.ts';
+
+/**
+ * The syntax-only model of a catalog the rules read: its files, elements, reactive properties and
+ * barrel graph. Built from a map of repository paths to file texts, so the same model serves a
+ * repository on disk and the fixer's in-memory tree.
+ */
+export class StandardProject {
+  public readonly files: ReadonlyMap<string, string>;
+  private readonly existsOnDisk: (fileArg: string) => boolean;
+  private readonly parseCache: TParseCache;
+  private elementsCache: IStandardElement[] | null = null;
+  private propertiesCache: IStandardProperty[] | null = null;
+  private reexportsCache = new Map<string, IStandardReexport[]>();
+
+  constructor(filesArg: ReadonlyMap<string, string>, existsOnDiskArg: (fileArg: string) => boolean, parseCacheArg: TParseCache = new Map()) {
+    this.files = filesArg;
+    this.existsOnDisk = existsOnDiskArg;
+    this.parseCache = parseCacheArg;
+  }
+
+  /** True when the file is part of the model or exists in the repository. */
+  public exists(fileArg: string): boolean {
+    return this.files.has(fileArg) || this.existsOnDisk(fileArg);
+  }
+
+  /** The `ts_web/**\/*.ts` sources, sorted. */
+  public get webFiles(): string[] {
+    return [...this.files.keys()].filter((fileArg) => fileArg.startsWith('ts_web/') && fileArg.endsWith('.ts') && isTypeScriptSource(fileArg)).sort();
+  }
+
+  public sourceFile(fileArg: string): ast.TSourceFile {
+    const text = this.files.get(fileArg);
+    if (text === undefined) {
+      throw new Error(`Not a known file: ${fileArg}`);
+    }
+    const cached = this.parseCache.get(fileArg);
+    if (cached && cached.text === text) {
+      return cached.sourceFile;
+    }
+    const sourceFile = ast.parseSource(fileArg, text);
+    this.parseCache.set(fileArg, { text, sourceFile });
+    return sourceFile;
+  }
+
+  /** `compilerOptions.experimentalDecorators` of tsconfig.json (its `extends` chain is not followed). */
+  public get experimentalDecorators(): boolean {
+    const text = this.files.get('tsconfig.json');
+    if (!text) {
+      return false;
+    }
+    const parsed = ts.parseConfigFileTextToJson('tsconfig.json', text);
+    return parsed.config?.compilerOptions?.experimentalDecorators === true;
+  }
+
+  public get elements(): IStandardElement[] {
+    if (!this.elementsCache) {
+      this.elementsCache = [];
+      for (const file of this.webFiles) {
+        const sourceFile = this.sourceFile(file);
+        const visit = (nodeArg: ast.TNode): void => {
+          if (ts.isClassDeclaration(nodeArg)) {
+            const decorator = ast.findDecoratorCall(nodeArg, ['customElement']);
+            if (decorator) {
+              const tagArgument = decorator.call.arguments[0];
+              this.elementsCache!.push({
+                file,
+                sourceFile,
+                classNode: nodeArg,
+                className: nodeArg.name?.text ?? null,
+                decoratorCall: decorator.call,
+                tag: decorator.call.arguments.length === 1 && ast.isStringLiteralLike(tagArgument) ? tagArgument.text : null,
+                exported: ast.hasModifier(nodeArg, ts.SyntaxKind.ExportKeyword),
+                inDemoFile: isDemoFile(file),
+              });
+            }
+          }
+          ts.forEachChild(nodeArg, visit);
+        };
+        visit(sourceFile);
+      }
+    }
+    return this.elementsCache;
+  }
+
+  public get properties(): IStandardProperty[] {
+    if (!this.propertiesCache) {
+      this.propertiesCache = [];
+      for (const file of this.webFiles) {
+        const sourceFile = this.sourceFile(file);
+        const visit = (nodeArg: ast.TNode): void => {
+          if (ts.isClassDeclaration(nodeArg) || ts.isClassExpression(nodeArg)) {
+            for (const member of nodeArg.members) {
+              const decorator = ast.findDecoratorCall(member, ['property', 'state']);
+              const name = ast.memberNameText(member);
+              if (!decorator || name === null) {
+                continue;
+              }
+              const firstArgument = decorator.call.arguments[0];
+              const isPrivateName = !!member.name && ts.isPrivateIdentifier(member.name);
+              this.propertiesCache!.push({
+                file,
+                sourceFile,
+                classNode: nodeArg as ast.TClassDeclaration,
+                member,
+                name: isPrivateName && !name.startsWith('#') ? `#${name}` : name,
+                decorator: decorator.name as 'property' | 'state',
+                call: decorator.call,
+                options: firstArgument && ts.isObjectLiteralExpression(firstArgument) ? firstArgument : null,
+                dynamicOptions: !!firstArgument && !ts.isObjectLiteralExpression(firstArgument),
+                isPublic: !isPrivateName
+                  && !ast.hasModifier(member, ts.SyntaxKind.PrivateKeyword)
+                  && !ast.hasModifier(member, ts.SyntaxKind.ProtectedKeyword),
+                inDemoFile: isDemoFile(file),
+              });
+            }
+          }
+          ts.forEachChild(nodeArg, visit);
+        };
+        visit(sourceFile);
+      }
+    }
+    return this.propertiesCache;
+  }
+
+  /** The `export … from` declarations of a file with relative specifiers. */
+  public reexports(fileArg: string): IStandardReexport[] {
+    let reexports = this.reexportsCache.get(fileArg);
+    if (!reexports) {
+      reexports = [];
+      if (this.files.has(fileArg)) {
+        for (const statement of this.sourceFile(fileArg).statements) {
+          if (ts.isExportDeclaration(statement) && statement.moduleSpecifier && ast.isStringLiteralLike(statement.moduleSpecifier)) {
+            const specifier = statement.moduleSpecifier.text;
+            if (!specifier.startsWith('.')) {
+              continue;
+            }
+            const resolved = resolveSpecifier(fileArg, specifier, (candidateArg) => this.files.has(candidateArg));
+            reexports.push({ file: fileArg, statement, specifier, target: resolved?.target ?? null });
+          }
+        }
+      }
+      this.reexportsCache.set(fileArg, reexports);
+    }
+    return reexports;
+  }
+
+  /** Every file reached from a barrel by following `export … from` declarations. */
+  public reachableFrom(fileArg: string): Set<string> {
+    const reached = new Set<string>();
+    const queue = this.files.has(fileArg) ? [fileArg] : [];
+    while (queue.length > 0) {
+      const file = queue.shift()!;
+      if (reached.has(file)) {
+        continue;
+      }
+      reached.add(file);
+      for (const reexport of this.reexports(file)) {
+        if (reexport.target && !reached.has(reexport.target)) {
+          queue.push(reexport.target);
+        }
+      }
+    }
+    return reached;
+  }
+
+  public lineAndColumn(fileArg: string, positionArg: number): { line: number; column: number } {
+    return ast.lineAndColumn(this.sourceFile(fileArg), positionArg);
+  }
+}
+
+/** The files besides `ts_web/**` a check reads. */
+export const standardSideFiles = ['html/index.ts', 'html/index.html', 'tsconfig.json', 'readme.md'];
+
+/** Reads the files the standard covers from a repository on disk. */
+export const loadStandardProject = async (rootDirArg: string): Promise<StandardProject> => {
+  const files = new Map<string, string>();
+  const webDir = plugins.path.join(rootDirArg, 'ts_web');
+  if (plugins.fsSync.existsSync(webDir)) {
+    const entries = await plugins.fs.readdir(webDir, { recursive: true, withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isFile()) {
+        continue;
+      }
+      const relative = toPosix(plugins.path.relative(rootDirArg, plugins.path.join(entry.parentPath, entry.name)));
+      if (relative.split('/').some((segmentArg) => segmentArg === 'node_modules')) {
+        continue;
+      }
+      if (relative.endsWith('.ts') && isTypeScriptSource(relative)) {
+        files.set(relative, await plugins.fs.readFile(plugins.path.join(rootDirArg, relative), 'utf8'));
+      }
+    }
+  }
+  for (const sideFile of standardSideFiles) {
+    const absolute = plugins.path.join(rootDirArg, sideFile);
+    if (plugins.fsSync.existsSync(absolute)) {
+      files.set(sideFile, await plugins.fs.readFile(absolute, 'utf8'));
+    }
+  }
+  return new StandardProject(files, (fileArg) => plugins.fsSync.existsSync(plugins.path.join(rootDirArg, fileArg)));
+};

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