@design.estate/wcctools 6.0.0 → 6.2.0

package/ts/classes.devserver.ts

@@ -7,6 +7,11 @@ import { loadShellContent, shellPathPrefix } from './shellcontent.js';
 export interface IWccDevServerOptions {
   /** Port to listen on; overrides the tswatch configuration. 0 picks a free port. */
   port?: number;
+  /**
+   * The project directory: its tswatch configuration, package.json and catalog are served, and
+   * tswatch bundles and watches in it (default: `process.cwd()` when the server is constructed).
+   */
+  cwd?: string;
 }
 
 export interface IWccDevServerAddress {
@@ -28,84 +33,159 @@ const securityHeaders: plugins.typedserver.ISecurityHeaders = {
 const acceptAnyHostname = () => true;
 
 /**
- * `wcctools dev`: bundles the catalog of the current project with tswatch, as its
- * `@git.zone/tswatch` configuration (or the `element` preset) describes, and serves on one port:
+ * `wcctools dev`: bundles the catalog of a project with tswatch, as its `@git.zone/tswatch`
+ * configuration (or the `element` preset) describes, and serves on one port:
  *
  * - the shell on `/wcctools/` (`/` redirects there) and its routes `/wcctools-route/...`,
- * - the typed API on `/wcctools/typedrequest`,
+ * - the typed API on `/wcctools/typedrequest`, including the bundles' status,
  * - the catalog's preview document and bundle from the tswatch serve directory on every other
  *   path, with live reload that reloads only the preview document.
  *
- * tswatch resolves its paths against the process's working directory, so the server serves the
- * project the process runs in.
+ * The server owns no process lifecycle: while it runs, a process shutdown through smartexit's
+ * `ProcessLifecycle` stops it. The entry point installs that lifecycle with
+ * `getShutdownTimeoutMs()`.
  */
 export class WccDevServer {
   /** The typed API on `/wcctools/typedrequest`; register further handlers before `start()`. */
   public readonly api = new WccDevApi();
-  private tsWatch: plugins.tswatch.TsWatch | null = null;
+  /** The project directory everything resolves against. */
+  public readonly cwd: string;
+  /** The project's tswatch configuration, or the `element` preset; read once, on construction. */
+  private readonly config: plugins.tswatch.ITswatchConfig;
+  /** Bundling and watching stay tswatch's; its own server stays off. */
+  private readonly tsWatch: plugins.tswatch.TsWatch;
   private typedServer: plugins.typedserver.TypedServer | null = null;
-  private readonly smartExit = new plugins.smartexit.SmartExit({ silent: true });
+  /** Stops the server on a process shutdown; registered by start(), released by stop(). */
+  private smartExit: plugins.smartexit.SmartExit | null = null;
+  private unsubscribeBundleEvents: (() => void) | null = null;
+  private running = false;
+  private starting: Promise<IWccDevServerAddress> | null = null;
+  private stopping: Promise<void> | null = null;
 
   constructor(private readonly options: IWccDevServerOptions = {}) {
-    this.smartExit.addCleanupFunction(() => this.stop());
+    this.cwd = plugins.path.resolve(options.cwd ?? process.cwd());
+    const configHandler = new plugins.tswatch.ConfigHandler(this.cwd);
+    this.config = configHandler.loadConfig() ?? this.getElementPreset(configHandler);
+    this.tsWatch = new plugins.tswatch.TsWatch({ ...this.config, server: { enabled: false } }, { cwd: this.cwd });
   }
 
+  /**
+   * The shutdown deadline the server needs, tswatch's: the entry point installs smartexit's
+   * `ProcessLifecycle` with it, so every watcher command keeps its full grace period.
+   */
+  public getShutdownTimeoutMs(): number {
+    return this.tsWatch.getShutdownTimeoutMs();
+  }
+
+  /**
+   * Bundles the catalog, starts the watchers and serves. Refused while the server runs or stops;
+   * the server starts again after stop().
+   */
   public async start(): Promise<IWccDevServerAddress> {
-    if (this.typedServer) {
-      throw new Error('wcctools: the dev server is already started.');
+    if (this.running || this.stopping) {
+      throw new Error('wcctools: the dev server is already started or still stopping.');
+    }
+    this.running = true;
+    // A process shutdown stops the server from here on, also while it is still starting
+    const smartExit = new plugins.smartexit.SmartExit({ silent: true });
+    smartExit.addCleanupFunction(() => this.stop());
+    this.smartExit = smartExit;
+    const starting = this.startServing();
+    this.starting = starting;
+    try {
+      const address = await starting;
+      if (this.stopping) {
+        throw new Error('wcctools: the dev server was stopped while starting.');
+      }
+      return address;
+    } catch (error) {
+      // A start that failed halfway releases what it opened
+      await this.stop();
+      throw error;
+    } finally {
+      if (this.starting === starting) {
+        this.starting = null;
+      }
     }
-    const cwd = process.cwd();
-    const configHandler = new plugins.tswatch.ConfigHandler(cwd);
-    const config = configHandler.loadConfig() ?? configHandler.getPreset('element');
-    const serveDir = plugins.path.resolve(cwd, config.server?.serveDir ?? defaultServeDir);
-    const port = this.options.port ?? config.server?.port ?? defaultPort;
+  }
+
+  /**
+   * Stops the server and tswatch's bundling and watching, and releases everything start()
+   * registered. A stop during start() waits for the start to settle first; concurrent and
+   * repeated calls share one stop.
+   */
+  public stop(): Promise<void> {
+    this.stopping ??= this.release().finally(() => {
+      this.stopping = null;
+    });
+    return this.stopping;
+  }
+
+  private async release(): Promise<void> {
+    await this.starting?.catch(() => undefined);
+    const smartExit = this.smartExit;
+    const typedServer = this.typedServer;
+    const unsubscribeBundleEvents = this.unsubscribeBundleEvents;
+    this.smartExit = null;
+    this.typedServer = null;
+    this.unsubscribeBundleEvents = null;
+    smartExit?.deregister();
+    // Status requests waiting for a change are refused now, so none holds the server's stop, and
+    // requests until the server stops listening are refused too: the shell backs off
+    this.api.bundleStatus.close();
+    try {
+      await typedServer?.stop();
+    } finally {
+      try {
+        await this.tsWatch.stop();
+      } finally {
+        unsubscribeBundleEvents?.();
+        this.running = false;
+      }
+    }
+  }
+
+  private async startServing(): Promise<IWccDevServerAddress> {
+    const serveDir = plugins.path.resolve(this.cwd, this.config.server?.serveDir ?? defaultServeDir);
+    const port = this.options.port ?? this.config.server?.port ?? defaultPort;
 
     // The preview surface watches the serve directory, which must exist before the first bundle
     await plugins.fs.mkdir(serveDir, { recursive: true });
     this.api.setServerInfo({
       wcctoolsVersion: commitinfo.version,
-      projectName: await this.readProjectName(cwd),
-    });
-    const typedServer = new plugins.typedserver.TypedServer({
-      cors: false,
-      port,
-      surfaces: [
-        await this.createShellSurface(),
-        this.createPreviewSurface(serveDir),
-      ],
+      projectName: await this.readProjectName(),
     });
+    const surfaces = [await this.createShellSurface(), this.createPreviewSurface(serveDir)];
+    const typedServer = new plugins.typedserver.TypedServer({ cors: false, port, surfaces });
     this.typedServer = typedServer;
 
-    // Bundling and watching stay tswatch's; its own server stays off
-    this.tsWatch = new plugins.tswatch.TsWatch({ ...config, server: { enabled: false } });
-    try {
-      await this.tsWatch.start();
-      await typedServer.start();
-    } catch (error) {
-      await this.stop();
-      throw error;
-    }
+    this.api.bundleStatus.open();
+    const bundleStatus = this.api.bundleStatus;
+    this.unsubscribeBundleEvents = this.tsWatch.onBundleEvent((eventArg) => bundleStatus.record(eventArg));
+    // The initial bundles run here; a failed one is reported in the bundle status
+    await this.tsWatch.start();
+    await typedServer.start();
     const boundPort = typedServer.listeningPort ?? port;
     return { port: boundPort, url: `http://localhost:${boundPort}${shellPathPrefix}/` };
   }
 
-  /** Stops the server, then tswatch's bundling and watching. */
-  public async stop(): Promise<void> {
-    const typedServer = this.typedServer;
-    const tsWatch = this.tsWatch;
-    this.typedServer = null;
-    this.tsWatch = null;
-    this.smartExit.deregister();
-    await typedServer?.stop();
-    await tsWatch?.stop();
+  private getElementPreset(configHandlerArg: plugins.tswatch.ConfigHandler): plugins.tswatch.ITswatchConfig {
+    const preset = configHandlerArg.getPreset('element');
+    if (!preset) {
+      throw new Error('wcctools: tswatch provides no `element` preset.');
+    }
+    return preset;
   }
 
   /**
    * The shell: the prebuilt shell bundle and the typed API.
    *
    * Seam for side-effecting APIs (assistant, capture, standards fixes): before any handler with
-   * side effects is registered here, add a `websocketAdmission`/`requestAdmission` that accepts
-   * only the shell's own origin, and keep surface mode's strict authority validation.
+   * side effects is registered here, the server binds to localhost by default (another interface
+   * only on explicit request), validates the Host header against the addresses it serves instead
+   * of accepting any hostname, and admits typedsocket connections and typed requests only from the
+   * shell's own origin (a `websocketAdmission`/`requestAdmission`), keeping surface mode's strict
+   * authority validation. Until then every handler here is read-only.
    */
   private async createShellSurface(): Promise<plugins.typedserver.ITypedServerSurface> {
     return {
@@ -154,8 +234,8 @@ export class WccDevServer {
     };
   }
 
-  private async readProjectName(cwdArg: string): Promise<string> {
-    const packageJson = JSON.parse(await plugins.fs.readFile(plugins.path.join(cwdArg, 'package.json'), 'utf8')) as { name?: string };
-    return packageJson.name ?? plugins.path.basename(cwdArg);
+  private async readProjectName(): Promise<string> {
+    const packageJson = JSON.parse(await plugins.fs.readFile(plugins.path.join(this.cwd, 'package.json'), 'utf8')) as { name?: string };
+    return packageJson.name ?? plugins.path.basename(this.cwd);
   }
 }

package/ts/cli.ts

@@ -1,6 +1,7 @@
 import * as plugins from './plugins.js';
 import { commitinfo } from './00_commitinfo_data.js';
 import { WccDevServer } from './classes.devserver.js';
+import { StandardConfigError, StandardUsageError, registerStandardCommands } from './standards/index.js';
 
 /**
  * Registers the wcctools commands on the given console.
@@ -22,11 +23,16 @@ export const registerCommands = (out: plugins.smartconsole.SmartConsole): void =
       },
     },
   }, async ({ options }) => {
-    const devServer = new WccDevServer({ port: options.port });
+    const devServer = new WccDevServer({ port: options.port, cwd: process.cwd() });
+    // The entry point owns process signals: SIGINT and SIGTERM run every registered cleanup, the
+    // dev server's stop among them, once within tswatch's shutdown deadline, then exit.
+    plugins.smartexit.ProcessLifecycle.install({ shutdownTimeoutMs: devServer.getShutdownTimeoutMs() });
     const address = await devServer.start();
     await out.log(`wcctools dev: ${address.url}`);
   });
 
+  registerStandardCommands(out);
+
   out.cli.default({}, async () => {
     await out.log(out.cli.renderHelp());
   });
@@ -39,7 +45,11 @@ export const runCli = async () => {
     await out.cli.run();
   } catch (error) {
     await out.error(error instanceof Error ? error.message : String(error));
-    process.exitCode = 1;
+    // Configuration and usage errors exit with 2, every other failure with 1.
+    const usageError = error instanceof plugins.smartconsole.CliUsageError
+      || error instanceof StandardConfigError
+      || error instanceof StandardUsageError;
+    process.exitCode = usageError ? 2 : 1;
   } finally {
     await out.dispose();
   }

package/ts/index.ts

@@ -1,3 +1 @@
 export { runCli } from './cli.js';
-export { WccDevServer, type IWccDevServerOptions, type IWccDevServerAddress } from './classes.devserver.js';
-export { WccDevApi } from './classes.devapi.js';

package/ts/plugins.ts

@@ -1,9 +1,11 @@
 // node native scope
+import * as childProcess from 'node:child_process';
 import * as fs from 'node:fs/promises';
+import * as fsSync from 'node:fs';
 import * as path from 'node:path';
 import * as url from 'node:url';
 
-export { fs, path, url };
+export { childProcess, fs, fsSync, path, url };
 
 // @api.global scope
 import * as typedrequest from '@api.global/typedrequest';
@@ -17,10 +19,16 @@ import * as tswatch from '@git.zone/tswatch';
 export { tswatch };
 
 // @push.rocks scope
+import * as smartconfig from '@push.rocks/smartconfig';
 import * as smartconsole from '@push.rocks/smartconsole';
 import * as smartexit from '@push.rocks/smartexit';
 
-export { smartconsole, smartexit };
+export { smartconfig, smartconsole, smartexit };
+
+// third party scope
+import typescript from 'typescript';
+
+export { typescript };
 
 // project scope
 import * as interfaces from '../ts_interfaces/index.js';

package/ts/standards/baselines.ts

@@ -0,0 +1,100 @@
+import * as plugins from '../plugins.js';
+import { allowlistStaleRuleId } from './rules/index.js';
+
+type IStandardConfig = plugins.interfaces.IStandardConfig;
+type IStandardReport = plugins.interfaces.IStandardReport;
+type TBaselines = NonNullable<IStandardConfig['baselines']>;
+
+/**
+ * Baseline arithmetic of the ratchet. Pure functions: persisting the result goes through
+ * IStandardConfigWriter (see config.ts).
+ */
+
+/** Per rule and file, the error findings a baseline would have to accept (allowlisted findings excluded). */
+const errorCounts = (reportArg: IStandardReport): TBaselines => {
+  const counts: TBaselines = {};
+  for (const finding of reportArg.findings) {
+    if (finding.severity !== 'error' || finding.covered === 'allowlist' || finding.ruleId === allowlistStaleRuleId) {
+      continue;
+    }
+    counts[finding.ruleId] ??= {};
+    counts[finding.ruleId][finding.file] = (counts[finding.ruleId][finding.file] ?? 0) + 1;
+  }
+  return counts;
+};
+
+const sortBaselines = (baselinesArg: TBaselines): TBaselines => {
+  const sorted: TBaselines = {};
+  for (const ruleId of Object.keys(baselinesArg).sort()) {
+    const files = Object.keys(baselinesArg[ruleId]).sort();
+    if (files.length > 0) {
+      sorted[ruleId] = Object.fromEntries(files.map((fileArg) => [fileArg, baselinesArg[ruleId][fileArg]]));
+    }
+  }
+  return sorted;
+};
+
+/** `--init-baseline`: the current error counts of every rule. Only valid while the configuration has no baselines. */
+export const initialBaselines = (reportArg: IStandardReport): TBaselines => sortBaselines(errorCounts(reportArg));
+
+export interface IBaselineRaise {
+  ruleId: string;
+  file: string;
+  baseline: number;
+  current: number;
+}
+
+/**
+ * `--update-baseline`: lowers every count to the current one and removes entries that reach 0.
+ * `raised` lists every file whose count would have to grow, including files without an entry;
+ * when it is not empty the update is refused.
+ */
+export const updatedBaselines = (reportArg: IStandardReport, baselinesArg: TBaselines): { baselines: TBaselines; raised: IBaselineRaise[] } => {
+  const current = errorCounts(reportArg);
+  const raised: IBaselineRaise[] = [];
+  const baselines: TBaselines = {};
+  for (const [ruleId, counts] of Object.entries(baselinesArg)) {
+    baselines[ruleId] = {};
+    for (const [file, baseline] of Object.entries(counts)) {
+      const count = current[ruleId]?.[file] ?? 0;
+      if (count > baseline) {
+        raised.push({ ruleId, file, baseline, current: count });
+      } else if (count > 0) {
+        baselines[ruleId][file] = count;
+      }
+    }
+  }
+  for (const [ruleId, counts] of Object.entries(current)) {
+    for (const [file, count] of Object.entries(counts)) {
+      if (baselinesArg[ruleId]?.[file] === undefined) {
+        raised.push({ ruleId, file, baseline: 0, current: count });
+      }
+    }
+  }
+  return { baselines: sortBaselines(baselines), raised };
+};
+
+/** The configuration with allowlist and baseline file paths moved along with `wcctools fix` moves. */
+export const rekeyStandardConfig = (configArg: IStandardConfig, movesArg: readonly plugins.interfaces.IStandardFileMove[]): { config: IStandardConfig; changed: string[] } => {
+  const moved = new Map(movesArg.map((moveArg) => [moveArg.from, moveArg.to]));
+  const changed: string[] = [];
+  const rekey = (keyArg: string): string => {
+    const [file, ...member] = keyArg.split('#');
+    const target = moved.get(file);
+    if (!target) {
+      return keyArg;
+    }
+    changed.push(keyArg);
+    return [target, ...member].join('#');
+  };
+  const config: IStandardConfig = { ...configArg };
+  if (configArg.allowlist) {
+    config.allowlist = Object.fromEntries(Object.entries(configArg.allowlist).map(([ruleId, entries]) =>
+      [ruleId, Object.fromEntries(Object.entries(entries).map(([key, value]) => [rekey(key), value]))]));
+  }
+  if (configArg.baselines) {
+    config.baselines = Object.fromEntries(Object.entries(configArg.baselines).map(([ruleId, counts]) =>
+      [ruleId, Object.fromEntries(Object.entries(counts).map(([file, count]) => [rekey(file), count]))]));
+  }
+  return { config, changed };
+};

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