@gotgenes/pi-autoformat 0.1.0 → 4.0.3

package/src/format-scope.ts

@@ -0,0 +1,118 @@
+import { execFileSync } from "node:child_process";
+import { realpathSync } from "node:fs";
+import path from "node:path";
+
+export type FormatScopeSetting = "repoRoot" | "cwd" | string[];
+
+export type FormatScope = {
+  /** Absolute, normalized roots. A path is in scope if it falls under any root. */
+  roots: string[];
+  /** Whether comparisons should be case-insensitive (darwin/win32). */
+  caseInsensitive: boolean;
+};
+
+export type ResolveFormatScopeOptions = {
+  cwd: string;
+  setting?: FormatScopeSetting;
+  /** Override for tests. Default: detect via `git rev-parse --show-toplevel`. */
+  detectGitRoot?: (cwd: string) => string | undefined;
+  platform?: NodeJS.Platform;
+};
+
+function defaultDetectGitRoot(cwd: string): string | undefined {
+  try {
+    const stdout = execFileSync("git", ["rev-parse", "--show-toplevel"], {
+      cwd,
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    const trimmed = stdout.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function safeRealpath(absPath: string): string {
+  try {
+    return realpathSync(absPath);
+  } catch {
+    return absPath;
+  }
+}
+
+export function resolveFormatScope(
+  options: ResolveFormatScopeOptions,
+): FormatScope {
+  const setting: FormatScopeSetting = options.setting ?? "repoRoot";
+  const platform = options.platform ?? process.platform;
+  const caseInsensitive = platform === "darwin" || platform === "win32";
+
+  const detectGitRoot = options.detectGitRoot ?? defaultDetectGitRoot;
+
+  const rawRoots: string[] = (() => {
+    if (setting === "cwd") {
+      return [options.cwd];
+    }
+    if (setting === "repoRoot") {
+      const gitRoot = detectGitRoot(options.cwd);
+      return [gitRoot ?? options.cwd];
+    }
+    if (Array.isArray(setting)) {
+      if (setting.length === 0) {
+        return [options.cwd];
+      }
+      return setting.map((entry) =>
+        path.isAbsolute(entry) ? entry : path.resolve(options.cwd, entry),
+      );
+    }
+    return [options.cwd];
+  })();
+
+  const roots = rawRoots
+    .map((root) => safeRealpath(path.normalize(root)))
+    .filter((root, index, arr) => arr.indexOf(root) === index);
+
+  return { roots, caseInsensitive };
+}
+
+function caseFold(value: string, caseInsensitive: boolean): string {
+  return caseInsensitive ? value.toLowerCase() : value;
+}
+
+function isUnder(
+  candidate: string,
+  root: string,
+  caseInsensitive: boolean,
+): boolean {
+  const rel = path.relative(
+    caseFold(root, caseInsensitive),
+    caseFold(candidate, caseInsensitive),
+  );
+  if (rel === "" || rel.startsWith("..") || path.isAbsolute(rel)) {
+    return false;
+  }
+  return true;
+}
+
+/**
+ * Returns true if `absCandidate` is inside any scope root.
+ *
+ * The candidate is realpath'd so that symlinked workspace deps that escape
+ * the root are correctly excluded, and intentional symlinks within the root
+ * are correctly included. If the candidate does not exist (e.g., a `mv`
+ * source after a move), `safeRealpath` returns the normalized absolute form,
+ * so the same check handles both cases.
+ */
+export function isInFormatScope(
+  absCandidate: string,
+  scope: FormatScope,
+): boolean {
+  const resolvedCandidate = safeRealpath(path.normalize(absCandidate));
+  for (const root of scope.roots) {
+    if (isUnder(resolvedCandidate, root, scope.caseInsensitive)) {
+      return true;
+    }
+  }
+  return false;
+}

package/src/formatter-config.ts

@@ -1,80 +1,117 @@
+import type { CustomMutationToolSpec } from "./custom-mutation-tools.js";
+import type { FormatScopeSetting } from "./format-scope.js";
 import type {
+  ChainStep,
   FormatterConfig,
   FormatterDefinition,
 } from "./formatter-registry.js";
+import {
+  DEFAULT_SHELL_MUTATION_DETECTION,
+  type ShellMutationDetectionConfig,
+} from "./shell-mutation-detector.js";
 
-export type FormatMode = "tool" | "prompt" | "session";
+export type FormatterOutputOnFailure = "none" | "stderr" | "both";
+
+export type FormatterOutputReportingConfig = {
+  /** Which streams to include for *failed* runs. Default: "none". */
+  onFailure: FormatterOutputOnFailure;
+  /** Hard byte cap per stream per run (UTF-8 byte length). */
+  maxBytes: number;
+  /** Hard line cap per stream per run, applied after byte trimming. */
+  maxLines: number;
+};
+
+export const DEFAULT_FORMATTER_OUTPUT_REPORTING: FormatterOutputReportingConfig =
+  {
+    onFailure: "none",
+    maxBytes: 4096,
+    maxLines: 40,
+  };
+
+export type EventBusMutationChannelConfig = {
+  enabled: boolean;
+  channel: string;
+};
+
+export const DEFAULT_EVENT_BUS_MUTATION_CHANNEL: EventBusMutationChannelConfig =
+  {
+    enabled: true,
+    channel: "autoformat:touched",
+  };
 
 export type UserFormatterConfig = {
-  formatMode?: FormatMode;
   commandTimeoutMs?: number;
   hideSummariesInTui?: boolean;
+  formatScope?: FormatScopeSetting;
+  shellMutationDetection?: Partial<ShellMutationDetectionConfig>;
+  customMutationTools?: CustomMutationToolSpec[];
+  eventBusMutationChannel?: Partial<EventBusMutationChannelConfig>;
   formatters?: Record<string, FormatterDefinition>;
-  chains?: Record<string, string[]>;
+  chains?: Record<string, ChainStep[]>;
+  formatterOutput?: Partial<FormatterOutputReportingConfig>;
 };
 
 export type AutoformatConfig = FormatterConfig & {
-  formatMode: FormatMode;
   commandTimeoutMs: number;
   hideSummariesInTui: boolean;
+  formatScope: FormatScopeSetting;
+  shellMutationDetection: ShellMutationDetectionConfig;
+  customMutationTools: CustomMutationToolSpec[];
+  eventBusMutationChannel: EventBusMutationChannelConfig;
+  formatters: Record<string, FormatterDefinition>;
+  chains: Record<string, ChainStep[]>;
+  formatterOutput: FormatterOutputReportingConfig;
 };
 
 export const DEFAULT_FORMATTER_CONFIG: AutoformatConfig = {
-  formatMode: "prompt",
   commandTimeoutMs: 10000,
   hideSummariesInTui: false,
+  formatScope: "repoRoot",
+  shellMutationDetection: DEFAULT_SHELL_MUTATION_DETECTION,
+  customMutationTools: [],
+  eventBusMutationChannel: DEFAULT_EVENT_BUS_MUTATION_CHANNEL,
   formatters: {
     prettier: {
-      command: ["prettier", "--write", "$FILE"],
-      extensions: [
-        ".js",
-        ".cjs",
-        ".mjs",
-        ".jsx",
-        ".ts",
-        ".tsx",
-        ".json",
-        ".md",
-        ".yaml",
-        ".yml",
-      ],
+      command: ["prettier", "--write"],
     },
     "markdownlint-cli2": {
-      command: ["markdownlint-cli2", "--fix", "$FILE"],
-      extensions: [".md"],
+      command: ["markdownlint-cli2", "--fix"],
     },
   },
-  chains: {
-    ".md": ["prettier", "markdownlint-cli2"],
-    ".js": ["prettier"],
-    ".cjs": ["prettier"],
-    ".mjs": ["prettier"],
-    ".jsx": ["prettier"],
-    ".ts": ["prettier"],
-    ".tsx": ["prettier"],
-    ".json": ["prettier"],
-    ".yaml": ["prettier"],
-    ".yml": ["prettier"],
-  },
+  formatterOutput: DEFAULT_FORMATTER_OUTPUT_REPORTING,
+  chains: {},
 };
 
 export function createFormatterConfig(
   userConfig?: UserFormatterConfig,
 ): AutoformatConfig {
   return {
-    formatMode: userConfig?.formatMode ?? DEFAULT_FORMATTER_CONFIG.formatMode,
     commandTimeoutMs:
       userConfig?.commandTimeoutMs ?? DEFAULT_FORMATTER_CONFIG.commandTimeoutMs,
     hideSummariesInTui:
       userConfig?.hideSummariesInTui ??
       DEFAULT_FORMATTER_CONFIG.hideSummariesInTui,
+    formatScope:
+      userConfig?.formatScope ?? DEFAULT_FORMATTER_CONFIG.formatScope,
+    shellMutationDetection: {
+      ...DEFAULT_FORMATTER_CONFIG.shellMutationDetection,
+      ...userConfig?.shellMutationDetection,
+    },
+    customMutationTools:
+      userConfig?.customMutationTools ??
+      DEFAULT_FORMATTER_CONFIG.customMutationTools,
+    eventBusMutationChannel: {
+      ...DEFAULT_FORMATTER_CONFIG.eventBusMutationChannel,
+      ...userConfig?.eventBusMutationChannel,
+    },
     formatters: {
       ...DEFAULT_FORMATTER_CONFIG.formatters,
       ...userConfig?.formatters,
     },
-    chains: {
-      ...DEFAULT_FORMATTER_CONFIG.chains,
-      ...userConfig?.chains,
+    chains: userConfig?.chains ?? {},
+    formatterOutput: {
+      ...DEFAULT_FORMATTER_CONFIG.formatterOutput,
+      ...userConfig?.formatterOutput,
     },
   };
 }

package/src/formatter-executor.ts

@@ -1,4 +1,10 @@
-import type { ResolvedFormatter } from "./formatter-registry.js";
+import type { BuiltinFormatter } from "./builtin-formatters.js";
+import type { CommandProbe } from "./command-probe.js";
+import { defaultCommandProbe } from "./command-probe.js";
+import type {
+  ResolvedChainStep,
+  ResolvedFormatter,
+} from "./formatter-registry.js";
 
 export type CommandRunResult = {
   exitCode: number;
@@ -17,52 +23,242 @@ export type CommandRunner = (
   options?: CommandRunnerOptions,
 ) => Promise<CommandRunResult>;
 
-export type FormatterExecutionResult = {
+export type FallbackContext = {
+  skipped: string[];
+};
+
+export type BatchRun = {
   formatterName: string;
   command: string[];
+  files: string[];
   success: boolean;
   exitCode: number;
   stdout?: string;
   stderr?: string;
+  fallbackContext?: FallbackContext;
+};
+
+export type ChainGroupInput = {
+  chain: ResolvedChainStep[];
+  files: string[];
 };
 
-export async function executeFormatterChain(
-  chain: ResolvedFormatter[],
+export type ExecuteChainGroupOptions = {
+  cwd?: string;
+  commandProbe?: CommandProbe;
+  /** Optional discovery context passed to built-in formatters. */
+  builtinContext?: { cache?: Map<string, string | null> };
+};
+
+export type ChainGroupExecution = {
+  runs: BatchRun[];
+  /** Files not yet handled by any built-in step in this chain. */
+  unhandled: string[];
+};
+
+async function runOrdinaryFormatter(
+  formatter: ResolvedFormatter,
+  files: string[],
+  runner: CommandRunner,
+  cwd: string | undefined,
+  fallbackContext?: FallbackContext,
+): Promise<BatchRun> {
+  const [command, ...args] = formatter.command;
+
+  if (!command) {
+    return {
+      formatterName: formatter.name,
+      command: [...formatter.command],
+      files: [...files],
+      success: false,
+      exitCode: 1,
+      stderr: "Formatter command is empty",
+      ...(fallbackContext ? { fallbackContext } : {}),
+    };
+  }
+
+  const fullArgs = [...args, ...files];
+  const runResult = await runner(command, fullArgs, {
+    cwd,
+    env: formatter.environment,
+  });
+
+  return {
+    formatterName: formatter.name,
+    command: [command, ...fullArgs],
+    files: [...files],
+    success: runResult.exitCode === 0,
+    exitCode: runResult.exitCode,
+    stdout: runResult.stdout,
+    stderr: runResult.stderr,
+    ...(fallbackContext ? { fallbackContext } : {}),
+  };
+}
+
+type BuiltinRunResult = {
+  /** undefined when the built-in is skipped entirely (no root, treatAsSkip). */
+  run?: BatchRun;
+  handled: string[];
+  unhandled: string[];
+};
+
+async function runBuiltinFormatter(
+  formatter: ResolvedFormatter,
+  builtin: BuiltinFormatter,
+  files: string[],
+  runner: CommandRunner,
+  options: ExecuteChainGroupOptions | undefined,
+  fallbackContext?: FallbackContext,
+): Promise<BuiltinRunResult> {
+  const root = await builtin.discoverRoot(files, options?.builtinContext);
+  if (!root) {
+    // No applicable config; treat as a clean no-op so the entire batch falls
+    // through to subsequent steps / per-extension chains.
+    return { handled: [], unhandled: [...files] };
+  }
+  const built = builtin.buildCommand(root, files);
+  const [command, ...args] = built.command;
+  if (!command) {
+    return { handled: [], unhandled: [...files] };
+  }
+  const runResult = await runner(command, args, {
+    cwd: built.cwd,
+    env: formatter.environment,
+  });
+  const run: BatchRun = {
+    formatterName: formatter.name,
+    command: [command, ...args],
+    files: [...files],
+    success: runResult.exitCode === 0,
+    exitCode: runResult.exitCode,
+    stdout: runResult.stdout,
+    stderr: runResult.stderr,
+    ...(fallbackContext ? { fallbackContext } : {}),
+  };
+  const partition = builtin.partitionUnhandled(run, files);
+  if (partition.treatAsSkip) {
+    return { handled: [], unhandled: [...files] };
+  }
+  return {
+    run,
+    handled: partition.handled,
+    unhandled: partition.unhandled,
+  };
+}
+
+export async function executeChainGroupWithPartition(
+  group: ChainGroupInput,
   runner: CommandRunner,
-  options?: {
-    cwd?: string;
-  },
-): Promise<FormatterExecutionResult[]> {
-  const results: FormatterExecutionResult[] = [];
-
-  for (const formatter of chain) {
-    const [command, ...args] = formatter.command;
-
-    if (!command) {
-      results.push({
-        formatterName: formatter.name,
-        command: formatter.command,
-        success: false,
-        exitCode: 1,
-        stderr: "Formatter command is empty",
-      });
+  options?: ExecuteChainGroupOptions,
+): Promise<ChainGroupExecution> {
+  if (group.files.length === 0) {
+    return { runs: [], unhandled: [] };
+  }
+
+  const probe = options?.commandProbe ?? defaultCommandProbe;
+  const runs: BatchRun[] = [];
+  // Working set: files that have not yet been claimed by a built-in step.
+  let working: string[] = [...group.files];
+
+  for (const step of group.chain) {
+    if (working.length === 0) {
+      break;
+    }
+
+    if (step.kind === "single") {
+      const formatter = step.formatter;
+      if (formatter.builtin) {
+        const result = await runBuiltinFormatter(
+          formatter,
+          formatter.builtin,
+          working,
+          runner,
+          options,
+        );
+        if (result.run) runs.push(result.run);
+        working = result.unhandled;
+        continue;
+      }
+      runs.push(
+        await runOrdinaryFormatter(formatter, working, runner, options?.cwd),
+      );
       continue;
     }
 
-    const runResult = await runner(command, args, {
-      cwd: options?.cwd,
-      env: formatter.environment,
-    });
+    const skipped: string[] = [];
+    let chosen: ResolvedFormatter | undefined;
+    for (const alternative of step.alternatives) {
+      const command = alternative.command[0];
+      if (command && probe(command)) {
+        chosen = alternative;
+        break;
+      }
+      skipped.push(alternative.name);
+    }
 
-    results.push({
-      formatterName: formatter.name,
-      command: formatter.command,
-      success: runResult.exitCode === 0,
-      exitCode: runResult.exitCode,
-      stdout: runResult.stdout,
-      stderr: runResult.stderr,
-    });
+    if (!chosen) {
+      // All alternatives missing from PATH — group is a no-op as specified.
+      continue;
+    }
+
+    // Precedence rule: when treefmt would win and treefmt-nix is also viable
+    // and resolves to a config at the same root, prefer treefmt-nix.
+    if (chosen.builtin?.name === "treefmt") {
+      const nixAlt = step.alternatives.find(
+        (a) => a.builtin?.name === "treefmt-nix" && probe(a.command[0] ?? ""),
+      );
+      if (nixAlt && chosen.builtin && nixAlt.builtin) {
+        const treefmtRoot = await chosen.builtin.discoverRoot(
+          working,
+          options?.builtinContext,
+        );
+        const nixRoot = await nixAlt.builtin.discoverRoot(
+          working,
+          options?.builtinContext,
+        );
+        if (treefmtRoot && nixRoot && treefmtRoot === nixRoot) {
+          // Bump treefmt into skipped (so the user sees fallback annotation)
+          // and switch to treefmt-nix.
+          skipped.push(chosen.name);
+          chosen = nixAlt;
+        }
+      }
+    }
+
+    const fallbackContext: FallbackContext | undefined =
+      skipped.length > 0 ? { skipped } : undefined;
+    if (chosen.builtin) {
+      const result = await runBuiltinFormatter(
+        chosen,
+        chosen.builtin,
+        working,
+        runner,
+        options,
+        fallbackContext,
+      );
+      if (result.run) runs.push(result.run);
+      working = result.unhandled;
+      continue;
+    }
+    runs.push(
+      await runOrdinaryFormatter(
+        chosen,
+        working,
+        runner,
+        options?.cwd,
+        fallbackContext,
+      ),
+    );
   }
 
-  return results;
+  return { runs, unhandled: working };
+}
+
+export async function executeChainGroup(
+  group: ChainGroupInput,
+  runner: CommandRunner,
+  options?: ExecuteChainGroupOptions,
+): Promise<BatchRun[]> {
+  const result = await executeChainGroupWithPartition(group, runner, options);
+  return result.runs;
 }

package/src/formatter-output-report.ts

@@ -0,0 +1,149 @@
+import type { FormatterOutputReportingConfig } from "./formatter-config.js";
+import type { BatchRun } from "./formatter-executor.js";
+
+const HEADER_INDENT = "  ";
+const BODY_INDENT = "    ";
+
+type TrimmedStream = {
+  /** Lines to render (already byte-trimmed and line-trimmed). */
+  lines: string[];
+  /** Truncation marker prefix line, or undefined if no truncation happened. */
+  marker?: string;
+};
+
+function rstripWhitespace(text: string): string {
+  // Strip trailing whitespace, including blank trailing lines, but preserve
+  // interior empty lines that the formatter intentionally emitted.
+  return text.replace(/[\s\uFEFF\xA0]+$/u, "");
+}
+
+function snapToNewlineBoundary(buffer: Buffer): Buffer {
+  // After tail-slicing on a byte boundary we may sit mid-line and (on
+  // multibyte input) mid-character. Advance forward to the first newline so
+  // we always start cleanly. If there is no newline, decode-and-cleanup will
+  // strip any U+FFFD replacements introduced by a partial UTF-8 sequence at
+  // the head.
+  const newlineIndex = buffer.indexOf(0x0a);
+  if (newlineIndex >= 0) {
+    return buffer.subarray(newlineIndex + 1);
+  }
+  return buffer;
+}
+
+function decodeAndCleanup(buffer: Buffer): string {
+  const decoded = buffer.toString("utf8");
+  // Drop any replacement characters at the head caused by a bisected
+  // multibyte sequence. Interior replacements (rare but possible from the
+  // formatter itself) are left intact.
+  return decoded.replace(/^\uFFFD+/u, "");
+}
+
+function trimByBytes(
+  text: string,
+  maxBytes: number,
+): { text: string; droppedBytes: number } {
+  const buffer = Buffer.from(text, "utf8");
+  if (buffer.byteLength <= maxBytes) {
+    return { text, droppedBytes: 0 };
+  }
+  const tail = buffer.subarray(buffer.byteLength - maxBytes);
+  const snapped = snapToNewlineBoundary(tail);
+  const droppedBytes = buffer.byteLength - snapped.byteLength;
+  return { text: decodeAndCleanup(snapped), droppedBytes };
+}
+
+function trimByLines(
+  text: string,
+  maxLines: number,
+): { lines: string[]; droppedLines: number } {
+  const allLines = text.split("\n");
+  if (allLines.length <= maxLines) {
+    return { lines: allLines, droppedLines: 0 };
+  }
+  const kept = allLines.slice(allLines.length - maxLines);
+  const droppedLines = allLines.length - kept.length;
+  return { lines: kept, droppedLines };
+}
+
+function trimStream(
+  raw: string,
+  config: FormatterOutputReportingConfig,
+): TrimmedStream | undefined {
+  const stripped = rstripWhitespace(raw);
+  if (stripped.length === 0) {
+    return undefined;
+  }
+
+  const byteResult = trimByBytes(stripped, config.maxBytes);
+  const lineResult = trimByLines(byteResult.text, config.maxLines);
+
+  let marker: string | undefined;
+  if (lineResult.droppedLines > 0) {
+    marker = `... (truncated, ${lineResult.droppedLines} earlier lines)`;
+  } else if (byteResult.droppedBytes > 0) {
+    marker = `... (truncated, ${byteResult.droppedBytes} earlier bytes)`;
+  }
+
+  // Lines may include leading empties if the byte-trimmed prefix was a
+  // newline. Drop a single leading empty for tidiness.
+  const lines =
+    lineResult.lines.length > 0 && lineResult.lines[0] === ""
+      ? lineResult.lines.slice(1)
+      : lineResult.lines;
+
+  if (lines.length === 0 && !marker) {
+    return undefined;
+  }
+
+  if (marker) {
+    return { lines, marker };
+  }
+  return { lines };
+}
+
+function renderBlock(
+  label: "stdout" | "stderr",
+  stream: TrimmedStream,
+): string {
+  const lines = [`${HEADER_INDENT}${label}:`];
+  if (stream.marker) {
+    lines.push(`${BODY_INDENT}${stream.marker}`);
+  }
+  for (const line of stream.lines) {
+    lines.push(`${BODY_INDENT}${line}`);
+  }
+  return lines.join("\n");
+}
+
+export function formatRunOutputBlock(
+  run: Pick<BatchRun, "success" | "stdout" | "stderr">,
+  config: FormatterOutputReportingConfig,
+): string | undefined {
+  if (config.onFailure === "none") {
+    return undefined;
+  }
+  if (run.success) {
+    return undefined;
+  }
+
+  const blocks: string[] = [];
+
+  if (config.onFailure === "both" && run.stdout !== undefined) {
+    const trimmed = trimStream(run.stdout, config);
+    if (trimmed) {
+      blocks.push(renderBlock("stdout", trimmed));
+    }
+  }
+
+  if (run.stderr !== undefined) {
+    const trimmed = trimStream(run.stderr, config);
+    if (trimmed) {
+      blocks.push(renderBlock("stderr", trimmed));
+    }
+  }
+
+  if (blocks.length === 0) {
+    return undefined;
+  }
+  return blocks.join("\n");
+}