@design.estate/wcctools 6.0.0 → 6.1.0

package/ts/standards/classes.standardfixer.ts

@@ -0,0 +1,234 @@
+import * as plugins from '../plugins.js';
+import { rekeyStandardConfig } from './baselines.js';
+import { checkStandard, detectFindings, rulesOfProfile } from './checker.js';
+import { GitRepo } from './classes.gitrepo.js';
+import { loadStandardProject, standardSideFiles } from './classes.standardproject.js';
+import { FixBatch, StandardTree } from './classes.standardtree.js';
+import type { ILoadedStandardConfig, IStandardConfigWriter } from './config.js';
+import { StandardUsageError } from './errors.js';
+import { dirOf, isRepoPath, isTypeScriptSource } from './helpers.paths.js';
+import { fixOrder, standardRules } from './rules/index.js';
+
+export interface IStandardFixOptions {
+  rootDir: string;
+  loaded: ILoadedStandardConfig;
+  /** Rules to fix; opt-in rules run only when named here. Default: every `auto` rule of the profile. */
+  rules?: readonly string[];
+  dryRun?: boolean;
+  /** Persists the configuration when moves rename files the allowlist or baselines name; without it such moves are refused. */
+  configWriter?: IStandardConfigWriter;
+}
+
+/** How often one rule is re-run on the edited tree to apply edits that overlapped in an earlier run. */
+const maxRunsPerRule = 5;
+
+/**
+ * `wcctools fix`: applies the fixes of the selected rules to an in-memory copy of the repository,
+ * one rule after another on the re-parsed result, validates that every path of the resulting plan
+ * stays inside the repository root, then writes the configuration, moves files with `git mv`, writes
+ * the edited files and checks again. Refuses to run on a dirty work tree and never commits, so a
+ * failure part-way through the writes is undone with `git reset --hard` and `git clean -fd`.
+ */
+export class StandardFixer {
+  private readonly options: IStandardFixOptions;
+
+  constructor(optionsArg: IStandardFixOptions) {
+    this.options = optionsArg;
+  }
+
+  private selectRules(): string[] {
+    const { profile } = this.options.loaded;
+    const inProfile = new Set(rulesOfProfile(profile).map((ruleArg) => ruleArg.id));
+    if (!this.options.rules || this.options.rules.length === 0) {
+      return fixOrder.filter((idArg) => inProfile.has(idArg) && standardRules.find((ruleArg) => ruleArg.id === idArg)!.fixMode === 'auto');
+    }
+    for (const id of this.options.rules) {
+      const rule = standardRules.find((ruleArg) => ruleArg.id === id);
+      if (!rule) {
+        throw new StandardUsageError(`Unknown rule '${id}'`);
+      }
+      if (!inProfile.has(id)) {
+        throw new StandardUsageError(`Rule '${id}' is not part of the '${profile}' profile`);
+      }
+      if (rule.fixMode === 'none') {
+        throw new StandardUsageError(`Rule '${id}' has no fix`);
+      }
+    }
+    return fixOrder.filter((idArg) => this.options.rules!.includes(idArg));
+  }
+
+  public async run(): Promise<plugins.interfaces.IStandardFixResult> {
+    const { rootDir, loaded } = this.options;
+    const selected = this.selectRules();
+    const git = new GitRepo(rootDir);
+    const topLevel = await git.topLevel();
+    if (!topLevel || plugins.fsSync.realpathSync(topLevel) !== plugins.fsSync.realpathSync(rootDir)) {
+      throw new StandardUsageError(`wcctools fix runs at the root of a git repository; ${rootDir} is not one`);
+    }
+    const status = await git.statusLines();
+    if (status.length > 0) {
+      throw new StandardUsageError(`wcctools fix needs a clean work tree; git status reports ${status.length} change(s). Commit or stash them first.`);
+    }
+
+    const trackedFiles = await git.trackedFiles();
+    const files = new Map<string, string>();
+    for (const file of trackedFiles) {
+      if (isTypeScriptSource(file) || standardSideFiles.includes(file)) {
+        files.set(file, await plugins.fs.readFile(plugins.path.join(rootDir, file), 'utf8'));
+      }
+    }
+    const tree = new StandardTree(files, trackedFiles, (fileArg) => plugins.fsSync.existsSync(plugins.path.join(rootDir, fileArg)));
+
+    for (const ruleId of selected) {
+      const rule = standardRules.find((ruleArg) => ruleArg.id === ruleId)!;
+      for (let run = 0; run < maxRunsPerRule; run++) {
+        const fixable = detectFindings(tree.project(), loaded, [rule]).filter((detectedArg) => !detectedArg.allowlisted && detectedArg.finding.fix);
+        if (fixable.length === 0) {
+          break;
+        }
+        const batch = new FixBatch();
+        fixable.forEach((detectedArg) => detectedArg.finding.fix!(batch));
+        if (tree.apply(rule.id, batch) === 0) {
+          break;
+        }
+      }
+    }
+
+    const plan = tree.plan();
+    await this.assertInsideRoot(plan);
+    const rekeyed = rekeyStandardConfig(loaded.config, plan.moves);
+    if (rekeyed.changed.length > 0 && !this.options.configWriter) {
+      throw new StandardUsageError(
+        `wcctools fix would move files that the standard configuration names (${rekeyed.changed.join(', ')}) but has no configuration writer`,
+      );
+    }
+    const loadedAfter: ILoadedStandardConfig = { ...loaded, config: rekeyed.config };
+
+    if (this.options.dryRun) {
+      return { dryRun: true, plan, remaining: checkStandard(tree.project(), loadedAfter) };
+    }
+
+    // Every path is validated above. The configuration goes first: a refused write (the file changed
+    // since it was read) leaves the tree untouched. A failure after it leaves a partial result that the
+    // clean work tree fix started from restores (`git reset --hard`, `git clean -fd`).
+    if (rekeyed.changed.length > 0) {
+      await this.options.configWriter!.writeStandardConfig(rekeyed.config);
+    }
+    await this.commitMoves(git, plan.moves);
+    for (const file of [...plan.created, ...plan.edited.map((editedArg) => editedArg.file)]) {
+      await this.ensureDir(dirOf(file));
+      await plugins.fs.writeFile(plugins.path.join(rootDir, file), tree.files.get(file)!, 'utf8');
+    }
+    await this.removeEmptyDirs(plan.moves.map((moveArg) => dirOf(moveArg.from)));
+    return { dryRun: false, plan, remaining: checkStandard(await loadStandardProject(rootDir), loadedAfter) };
+  }
+
+  /**
+   * Refuses a plan with a path that leaves the repository root, lexically (an absolute path or a `..`
+   * segment) or physically (through a symbolic link that resolves outside the root or dangles).
+   * Runs before anything is written, so a refused plan leaves the repository and its surroundings as
+   * they were.
+   */
+  private async assertInsideRoot(planArg: plugins.interfaces.IStandardFixPlan): Promise<void> {
+    const realRoot = await plugins.fs.realpath(this.options.rootDir);
+    const paths = [
+      ...planArg.moves.flatMap((moveArg) => [moveArg.from, moveArg.to]),
+      ...planArg.created,
+      ...planArg.edited.map((editedArg) => editedArg.file),
+    ];
+    const outside: string[] = [];
+    for (const file of new Set(paths)) {
+      if (!isRepoPath(file) || !(await this.resolvesInside(realRoot, file))) {
+        outside.push(file);
+      }
+    }
+    if (outside.length > 0) {
+      throw new StandardUsageError(`wcctools fix refuses to write outside the repository root: ${outside.join(', ')}`);
+    }
+  }
+
+  /** True when the file, or its nearest existing ancestor, resolves to a path inside the real root. */
+  private async resolvesInside(realRootArg: string, fileArg: string): Promise<boolean> {
+    let current = plugins.path.join(realRootArg, fileArg);
+    while (true) {
+      try {
+        const real = await plugins.fs.realpath(current);
+        return real === realRootArg || real.startsWith(`${realRootArg}${plugins.path.sep}`);
+      } catch (error) {
+        const code = (error as NodeJS.ErrnoException).code;
+        if (code !== 'ENOENT' && code !== 'ENOTDIR') {
+          throw error;
+        }
+      }
+      if (await this.isSymbolicLink(current)) {
+        // A dangling link: writing through it would create its target, wherever that is.
+        return false;
+      }
+      const parent = plugins.path.dirname(current);
+      if (parent === current) {
+        return false;
+      }
+      current = parent;
+    }
+  }
+
+  private async isSymbolicLink(pathArg: string): Promise<boolean> {
+    try {
+      return (await plugins.fs.lstat(pathArg)).isSymbolicLink();
+    } catch (error) {
+      const code = (error as NodeJS.ErrnoException).code;
+      if (code === 'ENOENT' || code === 'ENOTDIR') {
+        return false;
+      }
+      throw error;
+    }
+  }
+
+  /** `git mv` in an order where no move overwrites a file that has not moved away yet. */
+  private async commitMoves(gitArg: GitRepo, movesArg: plugins.interfaces.IStandardFileMove[]): Promise<void> {
+    const pending = [...movesArg];
+    while (pending.length > 0) {
+      const index = pending.findIndex((moveArg) => !plugins.fsSync.existsSync(plugins.path.join(this.options.rootDir, moveArg.to)));
+      if (index === -1) {
+        throw new Error(`Cannot order the moves ${pending.map((moveArg) => `${moveArg.from} → ${moveArg.to}`).join(', ')}`);
+      }
+      const [move] = pending.splice(index, 1);
+      await this.ensureDir(dirOf(move.to));
+      await gitArg.move(move.from, move.to);
+    }
+  }
+
+  /** Creates a directory one path component at a time. */
+  private async ensureDir(dirArg: string): Promise<void> {
+    let current = this.options.rootDir;
+    for (const segment of dirArg.split('/').filter((segmentArg) => segmentArg && segmentArg !== '.')) {
+      current = plugins.path.join(current, segment);
+      try {
+        await plugins.fs.mkdir(current);
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== 'EEXIST') {
+          throw error;
+        }
+      }
+    }
+  }
+
+  /** Removes directories that moves left empty, walking up towards the repository root. */
+  private async removeEmptyDirs(dirsArg: string[]): Promise<void> {
+    for (const start of [...new Set(dirsArg)].sort((a, b) => b.length - a.length)) {
+      let dir = start;
+      while (dir && dir !== '.') {
+        try {
+          await plugins.fs.rmdir(plugins.path.join(this.options.rootDir, dir));
+        } catch (error) {
+          const code = (error as NodeJS.ErrnoException).code;
+          if (code === 'ENOTEMPTY' || code === 'EEXIST' || code === 'ENOENT') {
+            break;
+          }
+          throw error;
+        }
+        dir = dirOf(dir);
+      }
+    }
+  }
+}

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