@design.estate/wcctools 5.1.0 → 6.1.0

package/ts/standards/checker.ts

@@ -0,0 +1,114 @@
+import * as plugins from '../plugins.js';
+import type { StandardProject } from './classes.standardproject.js';
+import type { ILoadedStandardConfig } from './config.js';
+import { severityIn, type IRuleFinding, type IStandardRule } from './rule.js';
+import { allowlistStaleRuleId, standardRules } from './rules/index.js';
+
+type IStandardFinding = plugins.interfaces.IStandardFinding;
+type IStandardReport = plugins.interfaces.IStandardReport;
+type TStandardProfile = plugins.interfaces.TStandardProfile;
+
+/** The rules of a profile, in the order of docs/standard.md. */
+export const rulesOfProfile = (profileArg: TStandardProfile): IStandardRule[] =>
+  standardRules.filter((ruleArg) => severityIn(ruleArg, profileArg) !== null);
+
+/** The rules of a profile as the shell and the AI agent see them. */
+export const describeStandardRules = (profileArg: TStandardProfile): plugins.interfaces.IStandardRuleInfo[] =>
+  rulesOfProfile(profileArg).map((ruleArg) => ({
+    id: ruleArg.id,
+    severity: severityIn(ruleArg, profileArg)!,
+    fixMode: ruleArg.fixMode,
+    allowlistCategories: [...(ruleArg.allowlistCategories ?? [])],
+  }));
+
+/** A finding of one rule with its allowlist state. */
+export interface IDetectedFinding {
+  rule: IStandardRule;
+  finding: IRuleFinding;
+  allowlisted: boolean;
+}
+
+/** Runs the rules of the configured profile; findings carry their fix actions. */
+export const detectFindings = (
+  projectArg: StandardProject,
+  loadedArg: ILoadedStandardConfig,
+  rulesArg: readonly IStandardRule[] = rulesOfProfile(loadedArg.profile),
+): IDetectedFinding[] => {
+  const context = { project: projectArg, config: loadedArg.config, profile: loadedArg.profile };
+  const detected: IDetectedFinding[] = [];
+  for (const rule of rulesArg) {
+    const allowlist = loadedArg.config.allowlist?.[rule.id] ?? {};
+    for (const finding of rule.detect(context)) {
+      detected.push({ rule, finding, allowlisted: Object.hasOwn(allowlist, finding.key) });
+    }
+  }
+  return detected;
+};
+
+const locate = (projectArg: StandardProject, fileArg: string, positionArg: number): { line: number; column: number } => {
+  const text = projectArg.files.get(fileArg);
+  if (text === undefined) {
+    return { line: 1, column: 1 };
+  }
+  if (/\.(ts|tsx|mts|cts)$/.test(fileArg)) {
+    return projectArg.lineAndColumn(fileArg, positionArg);
+  }
+  const before = text.slice(0, positionArg);
+  return { line: before.split('\n').length, column: positionArg - before.lastIndexOf('\n') };
+};
+
+/** Checks a repository against the standard: findings, allowlist, baselines. */
+export const checkStandard = (projectArg: StandardProject, loadedArg: ILoadedStandardConfig): IStandardReport => {
+  const { config, profile } = loadedArg;
+  const detected = detectFindings(projectArg, loadedArg);
+  const findings: IStandardFinding[] = detected.map(({ rule, finding, allowlisted }) => ({
+    ruleId: rule.id,
+    severity: severityIn(rule, profile)!,
+    file: finding.file,
+    ...locate(projectArg, finding.file, finding.position),
+    message: finding.message,
+    fixable: !!finding.fix,
+    ...(allowlisted ? { covered: 'allowlist' as const } : {}),
+  }));
+
+  // An allowlist entry without its finding is stale: the list only shrinks.
+  for (const [ruleId, entries] of Object.entries(config.allowlist ?? {})) {
+    for (const key of Object.keys(entries)) {
+      if (!detected.some(({ rule, finding }) => rule.id === ruleId && finding.key === key)) {
+        findings.push({
+          ruleId: allowlistStaleRuleId,
+          severity: 'error',
+          file: '.smartconfig.json',
+          line: 1,
+          column: 1,
+          message: `the ${ruleId} allowlist entry '${key}' matches no finding; remove it`,
+          fixable: false,
+        });
+      }
+    }
+  }
+
+  // Baselines: per rule and file, a count at or below the baseline is covered; above it nothing is.
+  const baselineSlack: plugins.interfaces.IStandardBaselineSlack[] = [];
+  for (const [ruleId, counts] of Object.entries(config.baselines ?? {})) {
+    for (const [file, baseline] of Object.entries(counts)) {
+      const inFile = findings.filter((findingArg) => findingArg.ruleId === ruleId && findingArg.file === file && !findingArg.covered);
+      if (inFile.length <= baseline) {
+        inFile.forEach((findingArg) => {
+          findingArg.covered = 'baseline';
+        });
+      }
+      if (inFile.length < baseline) {
+        baselineSlack.push({ ruleId, file, baseline, current: inFile.length });
+      }
+    }
+  }
+
+  findings.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line || a.column - b.column || a.ruleId.localeCompare(b.ruleId));
+  return {
+    profile,
+    findings,
+    baselineSlack,
+    ok: !findings.some((findingArg) => findingArg.severity === 'error' && !findingArg.covered),
+  };
+};

package/ts/standards/classes.gitrepo.ts

@@ -0,0 +1,48 @@
+import * as plugins from '../plugins.js';
+
+/** The git operations `wcctools fix` needs, run with an argument vector and no shell. */
+export class GitRepo {
+  public readonly rootDir: string;
+
+  constructor(rootDirArg: string) {
+    this.rootDir = rootDirArg;
+  }
+
+  public run(argsArg: string[]): Promise<string> {
+    return new Promise((resolve, reject) => {
+      plugins.childProcess.execFile('git', argsArg, { cwd: this.rootDir, maxBuffer: 64 * 1024 * 1024, encoding: 'utf8' }, (error, stdout, stderr) => {
+        if (error) {
+          reject(new Error(`git ${argsArg.join(' ')} failed: ${stderr.trim() || error.message}`));
+          return;
+        }
+        resolve(stdout);
+      });
+    });
+  }
+
+  /** The repository's top-level directory, or null when the directory is not inside a git work tree. */
+  public async topLevel(): Promise<string | null> {
+    try {
+      return (await this.run(['rev-parse', '--show-toplevel'])).trim();
+    } catch (error) {
+      if (error instanceof Error && /not a git repository/i.test(error.message)) {
+        return null;
+      }
+      throw error;
+    }
+  }
+
+  /** `git status --porcelain` lines; empty for a clean tree (untracked files count as changes). */
+  public async statusLines(): Promise<string[]> {
+    return (await this.run(['status', '--porcelain'])).split('\n').filter((lineArg) => lineArg.length > 0);
+  }
+
+  /** Tracked files, relative to the repository root. */
+  public async trackedFiles(): Promise<string[]> {
+    return (await this.run(['ls-files', '-z'])).split('\0').filter((fileArg) => fileArg.length > 0);
+  }
+
+  public async move(fromArg: string, toArg: string): Promise<void> {
+    await this.run(['mv', '--', fromArg, toArg]);
+  }
+}

package/ts/standards/classes.sourceedits.ts

@@ -0,0 +1,58 @@
+import type { ITextEdit } from './helpers.ast.js';
+
+/**
+ * Span edits of one file's text. Edits never re-print the file: each replaces [start, end) of the
+ * original text. Identical edits count once; an edit overlapping an earlier accepted one is
+ * dropped (the fixer retries it on the edited text). Insertions at the same offset keep the order
+ * they were added in.
+ */
+export class SourceEdits {
+  private readonly accepted: Array<ITextEdit & { order: number }> = [];
+  public dropped = 0;
+
+  public add(editArg: ITextEdit): boolean {
+    if (editArg.start > editArg.end) {
+      throw new Error(`Invalid edit span ${editArg.start}-${editArg.end}`);
+    }
+    if (this.accepted.some((otherArg) => otherArg.start === editArg.start && otherArg.end === editArg.end && otherArg.text === editArg.text)) {
+      return true;
+    }
+    const overlaps = this.accepted.some((otherArg) => {
+      const otherIsInsert = otherArg.start === otherArg.end;
+      const isInsert = editArg.start === editArg.end;
+      if (otherIsInsert && isInsert) {
+        return false;
+      }
+      if (isInsert) {
+        return editArg.start > otherArg.start && editArg.start < otherArg.end;
+      }
+      if (otherIsInsert) {
+        return otherArg.start > editArg.start && otherArg.start < editArg.end;
+      }
+      return editArg.start < otherArg.end && otherArg.start < editArg.end;
+    });
+    if (overlaps) {
+      this.dropped++;
+      return false;
+    }
+    this.accepted.push({ ...editArg, order: this.accepted.length });
+    return true;
+  }
+
+  public get size(): number {
+    return this.accepted.length;
+  }
+
+  /** Applies the accepted edits from the end of the text backwards. */
+  public apply(textArg: string): string {
+    const ordered = [...this.accepted].sort((a, b) => b.start - a.start || b.end - a.end || b.order - a.order);
+    let text = textArg;
+    for (const edit of ordered) {
+      if (edit.end > text.length) {
+        throw new Error(`Edit span ${edit.start}-${edit.end} exceeds the text length ${text.length}`);
+      }
+      text = text.slice(0, edit.start) + edit.text + text.slice(edit.end);
+    }
+    return text;
+  }
+}

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