pi-formatter 0.1.0

package/extensions/format/dispatch.ts

@@ -0,0 +1,237 @@
+import type { ExtensionAPI, ExecResult } from "@mariozechner/pi-coding-agent";
+import { FormatRunContext } from "./context.js";
+import { detectFileKind } from "./path.js";
+import { FORMAT_PLAN } from "./plan.js";
+import { RUNNERS } from "./runners/index.js";
+import {
+  isDynamicRunner,
+  type ResolvedLauncher,
+  type RunnerDefinition,
+  type RunnerGroup,
+  type RunnerLauncher,
+  type RunnerContext,
+  type SourceTool,
+} from "./types.js";
+
+function summarizeExecResult(result: ExecResult): string {
+  const output = `${result.stderr}\n${result.stdout}`.trim();
+  if (!output) {
+    return "";
+  }
+
+  const firstLine = output.split(/\r?\n/, 1)[0];
+  return `: ${firstLine}`;
+}
+
+async function resolveLauncher(
+  launcher: RunnerLauncher,
+  ctx: RunnerContext,
+): Promise<ResolvedLauncher | undefined> {
+  if (launcher.type === "direct") {
+    if (await ctx.hasCommand(launcher.command)) {
+      return { command: launcher.command, argsPrefix: [] };
+    }
+
+    return undefined;
+  }
+
+  if (launcher.type === "pypi") {
+    if (await ctx.hasCommand(launcher.tool)) {
+      return { command: launcher.tool, argsPrefix: [] };
+    }
+
+    if (await ctx.hasCommand("uv")) {
+      return {
+        command: "uv",
+        argsPrefix: ["tool", "run", launcher.tool],
+      };
+    }
+
+    return undefined;
+  }
+
+  if (await ctx.hasCommand(launcher.tool)) {
+    return { command: launcher.tool, argsPrefix: [] };
+  }
+
+  if (await ctx.hasCommand("go")) {
+    return {
+      command: "go",
+      argsPrefix: ["run", launcher.module],
+    };
+  }
+
+  return undefined;
+}
+
+function defaultVersionCommand(launcher: RunnerLauncher): string {
+  if (launcher.type === "direct") {
+    return launcher.command;
+  }
+
+  return launcher.tool;
+}
+
+async function satisfiesRunnerRequirements(
+  ctx: RunnerContext,
+  runner: RunnerDefinition,
+): Promise<boolean> {
+  const requirement = runner.requires?.majorVersionFromConfig;
+  if (!requirement) {
+    return true;
+  }
+
+  const requiredVersion = await ctx.getRequiredMajorVersionFromConfig(
+    requirement.patterns,
+  );
+
+  if (requiredVersion === undefined) {
+    return true;
+  }
+
+  if (requiredVersion === "invalid") {
+    const onInvalid = requirement.onInvalid ?? "warn-skip";
+    if (onInvalid === "warn-skip") {
+      ctx.warn(
+        `[pi-formatter] ${runner.id} skipped: invalid version requirement in ${requirement.patterns.join(", ")}`,
+      );
+    }
+
+    return false;
+  }
+
+  const versionCommand = requirement.command ?? defaultVersionCommand(runner.launcher);
+  const installedVersion = await ctx.getInstalledToolMajorVersion(versionCommand);
+
+  if (installedVersion === requiredVersion) {
+    return true;
+  }
+
+  const onMismatch = requirement.onMismatch ?? "warn-skip";
+  if (onMismatch === "warn-skip") {
+    ctx.warn(
+      `[pi-formatter] ${runner.id} skipped: ${versionCommand} version mismatch (have ${installedVersion ?? "unknown"}, need ${requiredVersion})`,
+    );
+  }
+
+  return false;
+}
+
+async function resolveRunnerArgs(
+  ctx: RunnerContext,
+  runner: RunnerDefinition,
+): Promise<string[] | undefined> {
+  if (isDynamicRunner(runner)) {
+    return runner.buildArgs(ctx);
+  }
+
+  const args = [...runner.args];
+  if (runner.appendFile !== false) {
+    args.push(ctx.filePath);
+  }
+
+  return args;
+}
+
+type RunnerOutcome = "skipped" | "failed" | "succeeded";
+
+async function runRunner(
+  ctx: RunnerContext,
+  runner: RunnerDefinition,
+): Promise<RunnerOutcome> {
+  const launcher = await resolveLauncher(runner.launcher, ctx);
+  if (!launcher) {
+    return "skipped";
+  }
+
+  if (runner.when && !(await runner.when(ctx))) {
+    return "skipped";
+  }
+
+  if (!(await satisfiesRunnerRequirements(ctx, runner))) {
+    return "skipped";
+  }
+
+  const args = await resolveRunnerArgs(ctx, runner);
+  if (!args) {
+    return "skipped";
+  }
+
+  const result = await ctx.exec(launcher.command, [...launcher.argsPrefix, ...args]);
+  if (!result) {
+    ctx.warn(`[pi-formatter] ${runner.id} failed to execute`);
+    return "failed";
+  }
+
+  if (result.code !== 0) {
+    ctx.warn(
+      `[pi-formatter] ${runner.id} exited with code ${result.code}${summarizeExecResult(result)}`,
+    );
+    return "failed";
+  }
+
+  return "succeeded";
+}
+
+async function runRunnerGroup(
+  ctx: RunnerContext,
+  group: RunnerGroup,
+): Promise<void> {
+  if (group.mode === "all") {
+    for (const runnerId of group.runnerIds) {
+      const runner = RUNNERS.get(runnerId);
+      if (!runner) {
+        ctx.warn(`[pi-formatter] unknown runner in format plan: ${runnerId}`);
+        continue;
+      }
+
+      await runRunner(ctx, runner);
+    }
+
+    return;
+  }
+
+  for (const runnerId of group.runnerIds) {
+    const runner = RUNNERS.get(runnerId);
+    if (!runner) {
+      ctx.warn(`[pi-formatter] unknown runner in format plan: ${runnerId}`);
+      continue;
+    }
+
+    const outcome = await runRunner(ctx, runner);
+    if (outcome === "succeeded") {
+      break;
+    }
+  }
+}
+
+export async function formatFile(
+  pi: ExtensionAPI,
+  cwd: string,
+  sourceTool: SourceTool,
+  filePath: string,
+  timeoutMs: number,
+): Promise<void> {
+  const kind = detectFileKind(filePath);
+  if (!kind) {
+    return;
+  }
+
+  const groups = FORMAT_PLAN[kind];
+  if (!groups || groups.length === 0) {
+    return;
+  }
+
+  const runContext = new FormatRunContext(
+    pi,
+    cwd,
+    filePath,
+    sourceTool,
+    kind,
+    timeoutMs,
+  );
+
+  for (const group of groups) {
+    await runRunnerGroup(runContext, group);
+  }
+}

package/extensions/format/path.ts

@@ -0,0 +1,89 @@
+import { access } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, isAbsolute, join, relative, resolve } from "node:path";
+import type { FileKind } from "./types.js";
+
+export function normalizeToolPath(filePath: string): string {
+  const normalizedAt = filePath.startsWith("@") ? filePath.slice(1) : filePath;
+
+  if (normalizedAt === "~") {
+    return homedir();
+  }
+
+  if (normalizedAt.startsWith("~/")) {
+    return join(homedir(), normalizedAt.slice(2));
+  }
+
+  return normalizedAt;
+}
+
+export function resolveToolPath(filePath: string, cwd: string): string {
+  const normalizedPath = normalizeToolPath(filePath);
+  return isAbsolute(normalizedPath)
+    ? normalizedPath
+    : resolve(cwd, normalizedPath);
+}
+
+export async function pathExists(path: string): Promise<boolean> {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function isWithinDirectory(pathToCheck: string, directory: string): boolean {
+  const relPath = relative(directory, pathToCheck);
+  return (
+    relPath === "" ||
+    relPath === "." ||
+    (!relPath.startsWith("..") && !isAbsolute(relPath))
+  );
+}
+
+export function getPathForGit(filePath: string, cwd: string): string {
+  const relPath = relative(cwd, filePath);
+  if (
+    !relPath ||
+    relPath === "." ||
+    relPath.startsWith("..") ||
+    isAbsolute(relPath)
+  ) {
+    return filePath;
+  }
+
+  return relPath;
+}
+
+export function detectFileKind(filePath: string): FileKind | undefined {
+  if (/\.(cpp|hpp|cpp\.in|hpp\.in)$/.test(filePath)) {
+    return "cxx";
+  }
+
+  if (/\.cmake$/.test(filePath) || basename(filePath) === "CMakeLists.txt") {
+    return "cmake";
+  }
+
+  if (/\.(md|mdx)$/.test(filePath)) {
+    return "markdown";
+  }
+
+  if (/\.json$/.test(filePath)) {
+    return "json";
+  }
+
+  if (/\.(sh|bash)$/.test(filePath)) {
+    return "shell";
+  }
+
+  if (/\.py$/.test(filePath)) {
+    return "python";
+  }
+
+  if (/\.(js|jsx|ts|tsx|mjs|cjs)$/.test(filePath)) {
+    return "jsts";
+  }
+
+  return undefined;
+}

package/extensions/format/plan.ts

@@ -0,0 +1,26 @@
+import type { FileKind, RunnerGroup } from "./types.js";
+
+export const FORMAT_PLAN: Record<FileKind, RunnerGroup[]> = {
+  cxx: [{ mode: "all", runnerIds: ["clang-format"] }],
+  cmake: [{ mode: "all", runnerIds: ["cmake-format"] }],
+  markdown: [
+    {
+      mode: "all",
+      runnerIds: ["markdownlint-fix", "prettier-markdown"],
+    },
+  ],
+  json: [
+    {
+      mode: "fallback",
+      runnerIds: ["biome-check-write", "prettier-config-write"],
+    },
+  ],
+  shell: [{ mode: "all", runnerIds: ["shfmt"] }],
+  python: [{ mode: "all", runnerIds: ["ruff-format", "ruff-check-fix"] }],
+  jsts: [
+    {
+      mode: "fallback",
+      runnerIds: ["biome-check-write", "eslint-fix", "prettier-config-write"],
+    },
+  ],
+};

package/extensions/format/runners/biome-check-write.ts

@@ -0,0 +1,11 @@
+import { defineRunner, direct } from "./helpers.js";
+import { BIOME_CONFIG_PATTERNS } from "./config-patterns.js";
+
+const biomeCheckWriteRunner = defineRunner({
+  id: "biome-check-write",
+  launcher: direct("biome"),
+  when: (ctx) => ctx.hasConfig(BIOME_CONFIG_PATTERNS),
+  args: ["check", "--write"],
+});
+
+export default biomeCheckWriteRunner;

package/extensions/format/runners/clang-format.ts

@@ -0,0 +1,27 @@
+import { defineRunner, direct } from "./helpers.js";
+
+const clangFormatRunner = defineRunner({
+  id: "clang-format",
+  launcher: direct("clang-format"),
+  requires: {
+    majorVersionFromConfig: {
+      patterns: [".clang-format-version"],
+      onInvalid: "warn-skip",
+      onMismatch: "warn-skip",
+    },
+  },
+  async buildArgs(ctx) {
+    const changedLines = await ctx.getChangedLines();
+    if (changedLines.length > 0) {
+      return [
+        ...changedLines.map((line) => `--lines=${line}`),
+        "-i",
+        ctx.filePath,
+      ];
+    }
+
+    return ["-i", ctx.filePath];
+  },
+});
+
+export default clangFormatRunner;

package/extensions/format/runners/cmake-format.ts

@@ -0,0 +1,9 @@
+import { defineRunner, pypi } from "./helpers.js";
+
+const cmakeFormatRunner = defineRunner({
+  id: "cmake-format",
+  launcher: pypi("cmake-format"),
+  args: ["--in-place"],
+});
+
+export default cmakeFormatRunner;

package/extensions/format/runners/config-patterns.ts

@@ -0,0 +1,6 @@
+export const BIOME_CONFIG_PATTERNS = ["biome.json", "biome.jsonc"] as const;
+export const ESLINT_CONFIG_PATTERNS = ["eslint.config.*", ".eslintrc*"] as const;
+export const PRETTIER_CONFIG_PATTERNS = [
+  ".prettierrc*",
+  "prettier.config.*",
+] as const;

package/extensions/format/runners/eslint-fix.ts

@@ -0,0 +1,11 @@
+import { ESLINT_CONFIG_PATTERNS } from "./config-patterns.js";
+import { defineRunner, direct } from "./helpers.js";
+
+const eslintFixRunner = defineRunner({
+  id: "eslint-fix",
+  launcher: direct("eslint"),
+  when: (ctx) => ctx.hasConfig(ESLINT_CONFIG_PATTERNS),
+  args: ["--fix"],
+});
+
+export default eslintFixRunner;

package/extensions/format/runners/helpers.ts

@@ -0,0 +1,22 @@
+import type {
+  DirectLauncher,
+  GoLauncher,
+  PypiLauncher,
+  RunnerDefinition,
+} from "../types.js";
+
+export function direct(command: string): DirectLauncher {
+  return { type: "direct", command };
+}
+
+export function pypi(tool: string): PypiLauncher {
+  return { type: "pypi", tool };
+}
+
+export function goTool(tool: string, module: string): GoLauncher {
+  return { type: "go", tool, module };
+}
+
+export function defineRunner<T extends RunnerDefinition>(runner: T): T {
+  return runner;
+}

package/extensions/format/runners/index.ts

@@ -0,0 +1,42 @@
+import type { RunnerDefinition } from "../types.js";
+import biomeCheckWriteRunner from "./biome-check-write.js";
+import clangFormatRunner from "./clang-format.js";
+import cmakeFormatRunner from "./cmake-format.js";
+import eslintFixRunner from "./eslint-fix.js";
+import markdownlintFixRunner from "./markdownlint-fix.js";
+import prettierConfigWriteRunner from "./prettier-config-write.js";
+import prettierMarkdownRunner from "./prettier-markdown.js";
+import ruffCheckFixRunner from "./ruff-check-fix.js";
+import ruffFormatRunner from "./ruff-format.js";
+import shfmtRunner from "./shfmt.js";
+
+export const RUNNER_DEFINITIONS: RunnerDefinition[] = [
+  clangFormatRunner,
+  cmakeFormatRunner,
+  markdownlintFixRunner,
+  prettierMarkdownRunner,
+  biomeCheckWriteRunner,
+  eslintFixRunner,
+  prettierConfigWriteRunner,
+  shfmtRunner,
+  ruffFormatRunner,
+  ruffCheckFixRunner,
+];
+
+function buildRunnerRegistry(
+  definitions: RunnerDefinition[],
+): Map<string, RunnerDefinition> {
+  const registry = new Map<string, RunnerDefinition>();
+
+  for (const runner of definitions) {
+    if (registry.has(runner.id)) {
+      throw new Error(`Duplicate runner registration: ${runner.id}`);
+    }
+
+    registry.set(runner.id, runner);
+  }
+
+  return registry;
+}
+
+export const RUNNERS = buildRunnerRegistry(RUNNER_DEFINITIONS);

package/extensions/format/runners/markdownlint-fix.ts

@@ -0,0 +1,9 @@
+import { defineRunner, direct } from "./helpers.js";
+
+const markdownlintFixRunner = defineRunner({
+  id: "markdownlint-fix",
+  launcher: direct("markdownlint"),
+  args: ["--fix"],
+});
+
+export default markdownlintFixRunner;

package/extensions/format/runners/prettier-config-write.ts

@@ -0,0 +1,11 @@
+import { PRETTIER_CONFIG_PATTERNS } from "./config-patterns.js";
+import { defineRunner, direct } from "./helpers.js";
+
+const prettierConfigWriteRunner = defineRunner({
+  id: "prettier-config-write",
+  launcher: direct("prettier"),
+  when: (ctx) => ctx.hasConfig(PRETTIER_CONFIG_PATTERNS),
+  args: ["--write"],
+});
+
+export default prettierConfigWriteRunner;

package/extensions/format/runners/prettier-markdown.ts

@@ -0,0 +1,9 @@
+import { defineRunner, direct } from "./helpers.js";
+
+const prettierMarkdownRunner = defineRunner({
+  id: "prettier-markdown",
+  launcher: direct("prettier"),
+  args: ["--write"],
+});
+
+export default prettierMarkdownRunner;

package/extensions/format/runners/ruff-check-fix.ts

@@ -0,0 +1,9 @@
+import { defineRunner, pypi } from "./helpers.js";
+
+const ruffCheckFixRunner = defineRunner({
+  id: "ruff-check-fix",
+  launcher: pypi("ruff"),
+  args: ["check", "--fix"],
+});
+
+export default ruffCheckFixRunner;

package/extensions/format/runners/ruff-format.ts

@@ -0,0 +1,9 @@
+import { defineRunner, pypi } from "./helpers.js";
+
+const ruffFormatRunner = defineRunner({
+  id: "ruff-format",
+  launcher: pypi("ruff"),
+  args: ["format"],
+});
+
+export default ruffFormatRunner;

package/extensions/format/runners/shfmt.ts

@@ -0,0 +1,19 @@
+import { defineRunner, goTool } from "./helpers.js";
+
+const SHFMT_MODULE = "mvdan.cc/sh/v3/cmd/shfmt@v3.10.0";
+
+const shfmtRunner = defineRunner({
+  id: "shfmt",
+  launcher: goTool("shfmt", SHFMT_MODULE),
+  async buildArgs(ctx) {
+    const hasEditorConfig = await ctx.hasEditorConfigInCwd();
+
+    if (hasEditorConfig) {
+      return ["-w", ctx.filePath];
+    }
+
+    return ["-i", "2", "-ci", "-bn", "-w", ctx.filePath];
+  },
+});
+
+export default shfmtRunner;

package/extensions/format/system.ts

@@ -0,0 +1,57 @@
+import { constants } from "node:fs";
+import { access } from "node:fs/promises";
+import { delimiter, join } from "node:path";
+
+const commandAvailability = new Map<string, boolean>();
+
+function getExecutableCandidates(command: string): string[] {
+  if (process.platform !== "win32") {
+    return [command];
+  }
+
+  const pathExt = process.env.PATHEXT ?? ".EXE;.CMD;.BAT;.COM";
+  const extensions = pathExt
+    .split(";")
+    .map((ext) => ext.trim())
+    .filter((ext) => ext.length > 0);
+
+  const hasExtension = extensions.some((ext) =>
+    command.toLowerCase().endsWith(ext.toLowerCase()),
+  );
+
+  if (hasExtension) {
+    return [command];
+  }
+
+  return [command, ...extensions.map((ext) => `${command}${ext}`)];
+}
+
+export async function hasCommand(command: string): Promise<boolean> {
+  const cached = commandAvailability.get(command);
+  if (cached !== undefined) {
+    return cached;
+  }
+
+  const pathValue = process.env.PATH ?? "";
+  const pathDirs = pathValue
+    .split(delimiter)
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0);
+
+  const candidates = getExecutableCandidates(command);
+
+  for (const directory of pathDirs) {
+    for (const candidate of candidates) {
+      try {
+        await access(join(directory, candidate), constants.X_OK);
+        commandAvailability.set(command, true);
+        return true;
+      } catch {
+        // Try next candidate.
+      }
+    }
+  }
+
+  commandAvailability.set(command, false);
+  return false;
+}