vize 0.303.0 → 0.310.0

package/src/init/plan-editor.ts

@@ -0,0 +1,98 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { detectJsonIndent, type PlannedFile } from "../setup/config.js";
+import type { ProjectDetection } from "./detect.js";
+import type { FeatureResult } from "./plan-types.js";
+import { renderVscodeExtensions, VSCODE_EXTENSION_ID } from "./templates.js";
+
+const EXTENSIONS_FILE = path.join(".vscode", "extensions.json");
+
+/**
+ * Plans the editor recommendation.
+ *
+ * `.vscode/extensions.json` is preferred over `code --install-extension` because
+ * it is checked in, applies to everyone on the project, and changes nothing on
+ * the machine running `init`. An existing file is merged, never replaced: it
+ * usually carries the team's other recommendations.
+ */
+export function planEditorFile(
+  detection: ProjectDetection,
+  files: PlannedFile[],
+  createdFiles: string[],
+  updatedFiles: string[],
+): FeatureResult {
+  const filename = path.join(detection.root, ".vscode", "extensions.json");
+  let source: string;
+  try {
+    source = fs.readFileSync(filename, "utf8");
+  } catch {
+    files.push({ filename, source: renderVscodeExtensions(2) });
+    createdFiles.push(EXTENSIONS_FILE);
+    return {
+      id: "editor",
+      outcome: "configured",
+      detail: `writes ${EXTENSIONS_FILE} recommending ${VSCODE_EXTENSION_ID}`,
+      snippet: null,
+    };
+  }
+
+  const merged = mergeRecommendation(source);
+  if (merged === null) {
+    return {
+      id: "editor",
+      outcome: "blocked",
+      detail: `${EXTENSIONS_FILE} is not a plain JSON object this tool can extend safely`,
+      snippet: `"recommendations": ["${VSCODE_EXTENSION_ID}"]`,
+    };
+  }
+  if (merged === source) {
+    return {
+      id: "editor",
+      outcome: "unchanged",
+      detail: `${EXTENSIONS_FILE} already recommends ${VSCODE_EXTENSION_ID}`,
+      snippet: null,
+    };
+  }
+  files.push({ filename, source: merged });
+  updatedFiles.push(EXTENSIONS_FILE);
+  return {
+    id: "editor",
+    outcome: "configured",
+    detail: `adds ${VSCODE_EXTENSION_ID} to ${EXTENSIONS_FILE}`,
+    snippet: null,
+  };
+}
+
+/**
+ * Adds the recommendation to an existing file, preserving its other keys and its
+ * indentation. Returns the input unchanged when the id is already listed, and
+ * `null` when the file is not a JSON object with an array of string
+ * recommendations.
+ */
+function mergeRecommendation(source: string): string | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(source);
+  } catch {
+    return null;
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    return null;
+  }
+  const document = parsed as Record<string, unknown>;
+  const existing = document.recommendations;
+  if (existing !== undefined && !isStringArray(existing)) {
+    return null;
+  }
+  const recommendations = existing ?? [];
+  if (recommendations.includes(VSCODE_EXTENSION_ID)) {
+    return source;
+  }
+  document.recommendations = [...recommendations, VSCODE_EXTENSION_ID];
+  return `${JSON.stringify(document, null, detectJsonIndent(source))}\n`;
+}
+
+function isStringArray(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every((entry) => typeof entry === "string");
+}

package/src/init/plan-lint.ts

@@ -0,0 +1,68 @@
+import path from "node:path";
+
+import type { ProjectDetection } from "./detect.js";
+import { injectViteLint } from "./edit-config.js";
+import { INIT_OXLINT_CONFIG_FILE, type LintTarget } from "./lint-target.js";
+import type { PlanDraft } from "./plan-types.js";
+import { INIT_OXLINT_CONFIG } from "./templates.js";
+
+/**
+ * Plans the Oxlint wiring into whichever file the project's lint command reads.
+ *
+ * The single rule this function exists to enforce: never write an Oxlint config
+ * the project's own lint command ignores. `vp lint` and `vp check` read only the
+ * `lint` block of the Vite config; `oxlint` and `oxlint-vize` read only their own
+ * config file. Writing the wrong one produces a project that looks configured,
+ * reports zero `vize/*` diagnostics and exits `0` -- #3389, fixed in #3407.
+ *
+ * When the required file cannot be edited safely this returns a `blocked`
+ * result and writes nothing at all. Falling back to the *other* file would be
+ * the bug: the user would see a success message and get silence from the linter.
+ *
+ * @returns the possibly-edited Vite config source, or the input unchanged.
+ */
+export function planLint(
+  detection: ProjectDetection,
+  lintTarget: LintTarget,
+  viteDraft: string | null,
+  draft: PlanDraft,
+): string | null {
+  if (lintTarget.blockedReason !== null) {
+    draft.features.push({
+      id: "lint",
+      outcome: "blocked",
+      detail:
+        `vp lint reads the \`lint\` block in the Vite config, but ${lintTarget.blockedReason}. ` +
+        "Nothing was written: an unconfigured project fails loudly, while an Oxlint config vp " +
+        "lint never reads reports zero Vize diagnostics and exits 0",
+      snippet: lintTarget.blockedSnippet,
+    });
+    return viteDraft;
+  }
+
+  let source = viteDraft;
+  const wrote: string[] = [];
+  if (lintTarget.viteConfig !== null && !detection.hasVitePlusLintBlock && source !== null) {
+    const injected = injectViteLint(source);
+    if (injected !== null) {
+      source = injected;
+      wrote.push(lintTarget.viteConfig);
+    }
+  }
+  if (lintTarget.oxlintConfig !== null) {
+    draft.files.push({
+      filename: path.join(detection.root, INIT_OXLINT_CONFIG_FILE),
+      source: INIT_OXLINT_CONFIG,
+    });
+    draft.createdFiles.push(INIT_OXLINT_CONFIG_FILE);
+    wrote.push(INIT_OXLINT_CONFIG_FILE);
+  }
+  draft.features.push({
+    id: "lint",
+    outcome: wrote.length > 0 ? "configured" : "unchanged",
+    detail:
+      wrote.length > 0 ? `${lintTarget.reason}; writes ${wrote.join(" and ")}` : lintTarget.reason,
+    snippet: null,
+  });
+  return source;
+}

package/src/init/plan-project.ts

@@ -0,0 +1,114 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { DEFAULT_SCRIPTS, detectJsonIndent, parsePackageJson } from "../setup/config.js";
+import type { ProjectDetection } from "./detect.js";
+import { skipped, type PlanDraft } from "./plan-types.js";
+import type { FeatureId, FeatureSelection } from "./select.js";
+import { renderVizeConfig } from "./templates.js";
+
+/** Scripts each feature contributes, reusing the command strings `setup` ships. */
+const FEATURE_SCRIPTS: Readonly<Record<FeatureId, readonly string[]>> = {
+  lint: ["vize:lint"],
+  bundler: [],
+  fmt: ["vize:fmt", "vize:fmt:fix"],
+  typecheck: ["vize:check"],
+  editor: [],
+};
+
+/**
+ * Plans `vize.config.ts` and the fmt/typecheck feature results.
+ *
+ * Only selected features contribute a block, so asking for the formatter alone
+ * does not hand the project a type checker it never opted into. An existing Vize
+ * config is never rewritten: merging into a user's config is exactly the kind of
+ * guess that loses their settings.
+ */
+export function planVizeConfig(
+  detection: ProjectDetection,
+  selection: FeatureSelection,
+  draft: PlanDraft,
+): void {
+  for (const id of ["fmt", "typecheck"] as const) {
+    if (!selection[id]) {
+      draft.features.push(
+        id === "typecheck" && detection.tsconfig === null
+          ? skipped(id, "no tsconfig.json, so vize check has nothing to check")
+          : skipped(id),
+      );
+      continue;
+    }
+    if (id === "typecheck" && detection.tsconfig === null) {
+      draft.features.push({
+        id,
+        outcome: "blocked",
+        detail: "vize check needs a tsconfig.json; none was found",
+        snippet: null,
+      });
+      continue;
+    }
+    draft.features.push({
+      id,
+      outcome: detection.vizeConfig === null ? "configured" : "unchanged",
+      detail:
+        detection.vizeConfig === null
+          ? "writes vize.config.ts"
+          : `${detection.vizeConfig} already exists and was left unchanged`,
+      snippet: null,
+    });
+  }
+
+  const needsConfig = selection.lint || selection.fmt || selection.typecheck;
+  if (!needsConfig || detection.vizeConfig !== null) {
+    return;
+  }
+  draft.files.push({
+    filename: path.join(detection.root, "vize.config.ts"),
+    source: renderVizeConfig({
+      lint: selection.lint,
+      fmt: selection.fmt,
+      typecheck: selection.typecheck && detection.tsconfig !== null,
+      vite: detection.framework === "vite",
+    }),
+  });
+  draft.createdFiles.push("vize.config.ts");
+}
+
+/**
+ * Adds the scripts the selected features need.
+ *
+ * A script the project already defines is left alone, whatever its value: the
+ * user's version of `vize:lint` outranks the default, and rewriting it would
+ * make a second `init` run destructive.
+ */
+export function planScripts(
+  detection: ProjectDetection,
+  selection: FeatureSelection,
+  draft: PlanDraft,
+): readonly string[] {
+  const wanted: string[] = [];
+  for (const id of ["lint", "fmt", "typecheck"] as const) {
+    if (!selection[id] || (id === "typecheck" && detection.tsconfig === null)) {
+      continue;
+    }
+    wanted.push(...FEATURE_SCRIPTS[id]);
+  }
+  const missing = wanted.filter((name) => !(name in detection.scripts));
+  if (missing.length === 0) {
+    return [];
+  }
+  const packagePath = path.join(detection.root, "package.json");
+  const source = fs.readFileSync(packagePath, "utf8");
+  const packageJson = parsePackageJson(packagePath, source);
+  const scripts = { ...detection.scripts } as Record<string, string>;
+  for (const name of missing) {
+    scripts[name] = DEFAULT_SCRIPTS[name as keyof typeof DEFAULT_SCRIPTS];
+  }
+  packageJson.scripts = scripts;
+  draft.files.push({
+    filename: packagePath,
+    source: `${JSON.stringify(packageJson, null, detectJsonIndent(source))}\n`,
+  });
+  draft.updatedFiles.push("package.json");
+  return missing;
+}

package/src/init/plan-types.ts

@@ -0,0 +1,77 @@
+import type { PlannedFile } from "../setup/config.js";
+import type { ProjectDetection } from "./detect.js";
+import type { LintTarget } from "./lint-target.js";
+import type { FeatureId, FeatureSelection } from "./select.js";
+
+/**
+ * Shared plan vocabulary.
+ *
+ * Lives apart from `plan.ts` so the per-feature planners can name these types
+ * without importing the orchestrator that calls them.
+ */
+
+export type FeatureOutcome =
+  /** The feature was selected and something was written for it. */
+  | "configured"
+  /** The feature was selected and is already wired up. A re-run lands here. */
+  | "unchanged"
+  /** The feature was not selected, or the project cannot support it. */
+  | "skipped"
+  /** Selected, but a user-owned file has to be edited by hand. Nothing written. */
+  | "blocked";
+
+export interface FeatureResult {
+  readonly id: FeatureId;
+  readonly outcome: FeatureOutcome;
+  readonly detail: string;
+  /** Snippet the user must paste when `outcome` is `blocked`. */
+  readonly snippet: string | null;
+}
+
+export interface InitCommand {
+  readonly command: string;
+  readonly args: readonly string[];
+  readonly cwd: string;
+}
+
+export interface InitPlan {
+  readonly root: string;
+  readonly detection: ProjectDetection;
+  readonly lintTarget: LintTarget;
+  readonly features: readonly FeatureResult[];
+  readonly files: readonly PlannedFile[];
+  readonly createdFiles: readonly string[];
+  readonly updatedFiles: readonly string[];
+  readonly addedScripts: readonly string[];
+  readonly commands: readonly InitCommand[];
+}
+
+export interface PlanInitOptions {
+  readonly detection: ProjectDetection;
+  readonly selection: FeatureSelection;
+  readonly install: boolean;
+  readonly packageManager?: string;
+}
+
+/** Mutable accumulators the per-feature planners append to. */
+export interface PlanDraft {
+  readonly files: PlannedFile[];
+  readonly createdFiles: string[];
+  readonly updatedFiles: string[];
+  readonly features: FeatureResult[];
+  readonly dependencies: Set<string>;
+}
+
+export function createPlanDraft(): PlanDraft {
+  return {
+    files: [],
+    createdFiles: [],
+    updatedFiles: [],
+    features: [],
+    dependencies: new Set<string>(),
+  };
+}
+
+export function skipped(id: FeatureId, detail = "not selected"): FeatureResult {
+  return { id, outcome: "skipped", detail, snippet: null };
+}

package/src/init/plan.ts

@@ -0,0 +1,167 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import type { ProjectDetection } from "./detect.js";
+import { resolveLintTarget } from "./lint-target.js";
+import { planBundler } from "./plan-bundler.js";
+import { planEditorFile } from "./plan-editor.js";
+import { planLint } from "./plan-lint.js";
+import { planScripts, planVizeConfig } from "./plan-project.js";
+import {
+  createPlanDraft,
+  skipped,
+  type FeatureResult,
+  type InitCommand,
+  type InitPlan,
+  type PlanInitOptions,
+} from "./plan-types.js";
+import type { FeatureId } from "./select.js";
+
+export type {
+  FeatureOutcome,
+  FeatureResult,
+  InitCommand,
+  InitPlan,
+  PlanInitOptions,
+} from "./plan-types.js";
+
+/** Dev dependencies each feature needs. */
+const FEATURE_DEPENDENCIES: Readonly<Record<FeatureId, readonly string[]>> = {
+  lint: ["oxlint", "oxlint-plugin-vize"],
+  bundler: [],
+  fmt: ["vize"],
+  typecheck: ["vize"],
+  editor: [],
+};
+
+const INSTALL_ARGS: Readonly<Record<string, readonly string[]>> = {
+  pnpm: ["add", "-D"],
+  yarn: ["add", "-D"],
+  bun: ["add", "-D"],
+  npm: ["install", "-D"],
+  vp: ["add", "-D"],
+};
+
+const FEATURE_ORDER: readonly FeatureId[] = ["lint", "bundler", "fmt", "typecheck", "editor"];
+
+/**
+ * Builds the full plan without touching the filesystem.
+ *
+ * Planning is separated from execution so `--dry-run`, the interactive
+ * confirmation and the tests all inspect the same object the writer consumes;
+ * a plan that is correct in `--dry-run` and wrong on disk is not possible.
+ */
+export function planInit(options: PlanInitOptions): InitPlan {
+  const { detection, selection } = options;
+  const draft = createPlanDraft();
+
+  const viteSource = readSingleViteConfig(detection);
+  const lintTarget = resolveLintTarget({ detection, viteSource });
+
+  let viteDraft = viteSource;
+  if (selection.lint) {
+    viteDraft = planLint(detection, lintTarget, viteDraft, draft);
+    addAll(draft.dependencies, FEATURE_DEPENDENCIES.lint);
+  } else {
+    draft.features.push(skipped("lint"));
+  }
+
+  if (selection.bundler) {
+    viteDraft = planBundler(detection, viteDraft, draft);
+  } else {
+    draft.features.push(skipped("bundler"));
+  }
+
+  // One write for the Vite config, however many features touched it, so the
+  // plugin edit and the lint edit cannot overwrite one another.
+  if (viteSource !== null && viteDraft !== null && viteDraft !== viteSource) {
+    const filename = detection.viteConfigs[0]!;
+    draft.files.push({ filename: path.join(detection.root, filename), source: viteDraft });
+    draft.updatedFiles.push(filename);
+  }
+
+  planVizeConfig(detection, selection, draft);
+  for (const id of ["fmt", "typecheck"] as const) {
+    if (selection[id]) {
+      addAll(draft.dependencies, FEATURE_DEPENDENCIES[id]);
+    }
+  }
+
+  draft.features.push(
+    selection.editor
+      ? planEditorFile(detection, draft.files, draft.createdFiles, draft.updatedFiles)
+      : skipped("editor"),
+  );
+
+  const addedScripts = planScripts(detection, selection, draft);
+  return {
+    root: detection.root,
+    detection,
+    lintTarget,
+    features: sortFeatures(draft.features),
+    files: draft.files,
+    createdFiles: draft.createdFiles,
+    updatedFiles: draft.updatedFiles,
+    addedScripts,
+    commands: planCommands(detection, draft.dependencies, options),
+  };
+}
+
+/**
+ * The install commands, as a list so callers can assert on them.
+ *
+ * Exactly one command is emitted, or none when every dependency is already
+ * declared -- which is what makes a second `init` run a no-op.
+ */
+function planCommands(
+  detection: ProjectDetection,
+  dependencies: ReadonlySet<string>,
+  options: PlanInitOptions,
+): readonly InitCommand[] {
+  if (!options.install) {
+    return [];
+  }
+  const missing = [...dependencies].filter((name) => !detection.dependencies.has(name)).sort();
+  if (missing.length === 0) {
+    return [];
+  }
+  const command = resolveInstaller(detection, options.packageManager);
+  return [{ command, args: [...INSTALL_ARGS[command]!, ...missing], cwd: detection.root }];
+}
+
+/**
+ * Installer used for the one install command.
+ *
+ * A Vite+ project gets `vp add`, matching `setup` and the project's own
+ * workflow. Otherwise the package manager comes from the same lockfile rules
+ * `detect_package_manager` uses on the Rust side, defaulting to npm when
+ * nothing identifies one.
+ */
+export function resolveInstaller(detection: ProjectDetection, override?: string): string {
+  if (override !== undefined) {
+    return override;
+  }
+  if (detection.usesVitePlus) {
+    return "vp";
+  }
+  return detection.packageManager ?? "npm";
+}
+
+function readSingleViteConfig(detection: ProjectDetection): string | null {
+  if (detection.viteConfigs.length !== 1) {
+    return null;
+  }
+  return fs.readFileSync(path.join(detection.root, detection.viteConfigs[0]!), "utf8");
+}
+
+function addAll(target: Set<string>, values: readonly string[]): void {
+  for (const value of values) {
+    target.add(value);
+  }
+}
+
+function sortFeatures(features: readonly FeatureResult[]): readonly FeatureResult[] {
+  return [...features].sort(
+    (left, right) => FEATURE_ORDER.indexOf(left.id) - FEATURE_ORDER.indexOf(right.id),
+  );
+}

package/src/init/prompt.ts

@@ -0,0 +1,161 @@
+import readline from "node:readline";
+
+import type { FeatureId, FeatureOffer, FeatureSelection } from "./select.js";
+
+/**
+ * Interactive multi-select for the five features.
+ *
+ * Implemented on `node:readline` rather than a prompt package: `vize` is a
+ * published CLI whose install cost every user pays, and a numbered toggle list
+ * needs no raw-mode handling, no terminal restore path, and no dependency in the
+ * runtime path. It is a real multi-select -- numbers toggle, Enter accepts.
+ */
+
+export interface PromptIo {
+  readonly input: NodeJS.ReadableStream;
+  readonly output: NodeJS.WritableStream;
+}
+
+export interface PromptDeps extends PromptIo {
+  /** Resolves to `null` when the input ended before an answer arrived. */
+  readonly question: (query: string) => Promise<string | null>;
+  /**
+   * Releases the terminal. Required for readline-backed deps: an open interface
+   * keeps stdin referenced and the process never exits.
+   */
+  readonly close?: () => void;
+}
+
+/** True when stdin cannot answer a prompt, so `init` must not ask one. */
+export function isNonInteractive(stream: NodeJS.ReadableStream): boolean {
+  return (stream as NodeJS.ReadStream).isTTY !== true;
+}
+
+/**
+ * Wraps `node:readline` so a closed input resolves instead of hanging.
+ *
+ * `rl.question` never invokes its callback when stdin reaches EOF first. Left
+ * alone that leaves `init`'s promise permanently pending, and the process exits
+ * `0` having written nothing -- a silent no-op that looks like success. Resolving
+ * to `null` on close turns that into an explicit cancellation.
+ */
+export function createPromptDeps(io: PromptIo): PromptDeps {
+  const rl = readline.createInterface({ input: io.input, output: io.output });
+  let closed = false;
+  rl.on("close", () => {
+    closed = true;
+  });
+  return {
+    ...io,
+    question: (query) =>
+      new Promise<string | null>((resolve) => {
+        if (closed) {
+          resolve(null);
+          return;
+        }
+        let settled = false;
+        const onClose = (): void => {
+          if (!settled) {
+            settled = true;
+            resolve(null);
+          }
+        };
+        rl.once("close", onClose);
+        rl.question(query, (answer) => {
+          if (settled) {
+            return;
+          }
+          settled = true;
+          rl.removeListener("close", onClose);
+          resolve(answer);
+        });
+      }),
+    close: () => {
+      rl.close();
+    },
+  };
+}
+
+/** Runs the checklist. Returns `null` when the input ended before confirmation. */
+export async function selectFeatures(
+  offers: readonly FeatureOffer[],
+  initial: FeatureSelection,
+  deps: PromptDeps,
+): Promise<FeatureSelection | null> {
+  const selection: Record<FeatureId, boolean> = { ...initial };
+  const toggleable = offers.filter((offer) => offer.available);
+  for (;;) {
+    deps.output.write(renderChecklist(offers, selection));
+    const raw = await deps.question("> ");
+    if (raw === null) {
+      return null;
+    }
+    const answer = raw.trim();
+    if (answer === "") {
+      return selection;
+    }
+    const indexes = parseIndexes(answer, toggleable.length);
+    if (indexes === null) {
+      deps.output.write(
+        `Enter numbers between 1 and ${toggleable.length}, or press Enter to accept.\n`,
+      );
+      continue;
+    }
+    for (const index of indexes) {
+      const offer = toggleable[index]!;
+      selection[offer.id] = !selection[offer.id];
+    }
+  }
+}
+
+/** Yes/no confirmation. A closed input counts as "no", never as "yes". */
+export async function confirm(query: string, deps: PromptDeps): Promise<boolean> {
+  const raw = await deps.question(`${query} [Y/n] `);
+  if (raw === null) {
+    return false;
+  }
+  const answer = raw.trim().toLowerCase();
+  return answer === "" || answer === "y" || answer === "yes";
+}
+
+function renderChecklist(
+  offers: readonly FeatureOffer[],
+  selection: Readonly<Record<FeatureId, boolean>>,
+): string {
+  const lines = [
+    "",
+    "Select the features to configure.",
+    "Type the numbers to toggle (space or comma separated), then press Enter.",
+    "",
+  ];
+  let position = 0;
+  for (const offer of offers) {
+    if (!offer.available) {
+      lines.push(`     -  ${offer.label}${offer.note === "" ? "" : ` (${offer.note})`}`);
+      continue;
+    }
+    position += 1;
+    const mark = selection[offer.id] ? "x" : " ";
+    const note = offer.note === "" ? "" : ` (${offer.note})`;
+    lines.push(`  ${position}. [${mark}] ${offer.label}${note}`);
+  }
+  lines.push("");
+  return `${lines.join("\n")}\n`;
+}
+
+/** Parses a toggle answer into zero-based indexes, or `null` when any entry is out of range. */
+function parseIndexes(answer: string, count: number): readonly number[] | null {
+  const tokens = answer.split(/[\s,]+/u).filter((token) => token !== "");
+  const indexes: number[] = [];
+  for (const token of tokens) {
+    if (!/^\d+$/u.test(token)) {
+      return null;
+    }
+    const value = Number.parseInt(token, 10);
+    if (value < 1 || value > count) {
+      return null;
+    }
+    indexes.push(value - 1);
+  }
+  return indexes.length === 0 ? null : indexes;
+}