ai-check-template 0.2.0-alpha.0

package/src/cli/package-manager.mjs

@@ -0,0 +1,78 @@
+import path from "node:path";
+import fs from "node:fs/promises";
+import { CliError, pathExists } from "./utils.mjs";
+
+export const DEFAULT_PACKAGE_MANAGER = "pnpm";
+
+const VALID_PACKAGE_MANAGERS = new Set(["pnpm", "npm", "yarn", "bun"]);
+
+const LOCKFILE_PACKAGE_MANAGERS = [
+  ["pnpm-lock.yaml", "pnpm"],
+  ["package-lock.json", "npm"],
+  ["npm-shrinkwrap.json", "npm"],
+  ["yarn.lock", "yarn"],
+  ["bun.lock", "bun"],
+  ["bun.lockb", "bun"],
+];
+
+export function validatePackageManager(packageManager) {
+  if (!VALID_PACKAGE_MANAGERS.has(packageManager)) {
+    throw new CliError(
+      `--package-manager must be one of: ${[...VALID_PACKAGE_MANAGERS].join(", ")}`,
+    );
+  }
+
+  return packageManager;
+}
+
+export async function detectPackageManager(targetDir) {
+  const packageManager = await packageManagerFromPackageJson(targetDir);
+  if (packageManager) {
+    return packageManager;
+  }
+
+  for (const [lockfile, detectedPackageManager] of LOCKFILE_PACKAGE_MANAGERS) {
+    if (await pathExists(path.join(targetDir, lockfile))) {
+      return detectedPackageManager;
+    }
+  }
+
+  return DEFAULT_PACKAGE_MANAGER;
+}
+
+export function scriptCommand(packageManager, scriptName) {
+  const validated = validatePackageManager(packageManager);
+
+  if (validated === "npm") {
+    return `npm run ${scriptName}`;
+  }
+
+  if (validated === "bun") {
+    return `bun run ${scriptName}`;
+  }
+
+  return `${validated} ${scriptName}`;
+}
+
+async function packageManagerFromPackageJson(targetDir) {
+  const packageJsonPath = path.join(targetDir, "package.json");
+
+  if (!(await pathExists(packageJsonPath))) {
+    return null;
+  }
+
+  let packageJson;
+  try {
+    packageJson = JSON.parse(await fs.readFile(packageJsonPath, "utf8"));
+  } catch {
+    return null;
+  }
+  const value = packageJson.packageManager;
+
+  if (typeof value !== "string" || value.length === 0) {
+    return null;
+  }
+
+  const [name] = value.split("@");
+  return validatePackageManager(name);
+}

package/src/cli/profile-diagnostics.mjs

@@ -0,0 +1,160 @@
+const CHECK_SCRIPT_NAMES = ["ai:check", "ai:check:fast"];
+
+const SCRIPT_REFERENCE_PATTERNS = [
+  /\b(?:pnpm|yarn)\s+([A-Za-z0-9:_-]+)/g,
+  /\b(?:npm|bun)\s+run\s+([A-Za-z0-9:_-]+)/g,
+];
+
+const PACKAGE_MANAGER_SUBCOMMANDS = new Set([
+  "add",
+  "audit",
+  "cache",
+  "config",
+  "create",
+  "dlx",
+  "exec",
+  "help",
+  "init",
+  "install",
+  "link",
+  "outdated",
+  "pack",
+  "publish",
+  "remove",
+  "run",
+  "store",
+  "unlink",
+  "update",
+  "upgrade",
+  "version",
+  "why",
+]);
+
+export function diagnoseProfileScripts(profile, packageJson) {
+  const scripts = packageJson?.scripts && typeof packageJson.scripts === "object"
+    ? packageJson.scripts
+    : {};
+  const warnings = [];
+  const base = profile?.base;
+  const addons = new Set(profile?.addons ?? []);
+
+  if (base === "react-nextjs") {
+    if (!hasScriptOrCommand(scripts, "doctor")) {
+      warnings.push(profileWarning("React Next.js profile recommends a React Doctor check."));
+    }
+    if (!hasScriptOrCommand(scripts, "test:e2e:smoke")) {
+      warnings.push(profileWarning("React Next.js profile recommends a Playwright smoke E2E script."));
+    }
+  }
+
+  if (base === "react-vanilla" && hasCommandToken(scripts, "next lint")) {
+    warnings.push(profileWarning("React vanilla profile should avoid Next.js-specific lint scripts."));
+  }
+
+  if (base === "expo-rn") {
+    if (hasCommandToken(scripts, "playwright")) {
+      warnings.push(profileWarning("Expo React Native profile recommends Maestro or Detox instead of Playwright."));
+    }
+    if (hasCommandToken(scripts, "react-doctor")) {
+      warnings.push(profileWarning("Expo React Native profile does not support React Doctor as a merge gate."));
+    }
+  }
+
+  if (base === "node-cli") {
+    if (hasScriptOrCommand(scripts, "test:e2e") || hasCommandToken(scripts, "playwright")) {
+      warnings.push(profileWarning("Node CLI profile usually replaces UI E2E checks with CLI integration tests."));
+    }
+  }
+
+  if (addons.has("supabase-rls")) {
+    if (!hasScriptName(scripts, "test:db")) {
+      warnings.push(addonWarning("Supabase RLS addon recommends a test:db script for pgTAP or DB-level tests."));
+    }
+    if (!hasScriptName(scripts, "test:integration:rls")) {
+      warnings.push(addonWarning("Supabase RLS addon recommends a test:integration:rls script."));
+    }
+  }
+
+  warnings.push(...missingReferencedScriptWarnings(scripts));
+
+  return warnings;
+}
+
+function profileWarning(message) {
+  return {
+    code: "profile-advice",
+    path: "package.json",
+    message,
+  };
+}
+
+function addonWarning(message) {
+  return {
+    code: "profile-addon-advice",
+    path: "package.json",
+    message,
+  };
+}
+
+function scriptWarning(message) {
+  return {
+    code: "script-advice",
+    path: "package.json",
+    message,
+  };
+}
+
+function hasScriptName(scripts, name) {
+  return Object.hasOwn(scripts, name);
+}
+
+function hasScriptOrCommand(scripts, token) {
+  return hasScriptName(scripts, token) || hasCommandToken(scripts, token);
+}
+
+function hasCommandToken(scripts, token) {
+  const normalizedToken = token.toLowerCase();
+  return Object.values(scripts).some(
+    (command) => typeof command === "string" && command.toLowerCase().includes(normalizedToken),
+  );
+}
+
+function missingReferencedScriptWarnings(scripts) {
+  return [...missingReferencedScripts(scripts)].map((scriptName) => (
+    scriptWarning(`ai:check references missing package script: ${scriptName}`)
+  ));
+}
+
+function missingReferencedScripts(scripts) {
+  const referenced = new Set();
+
+  for (const scriptName of CHECK_SCRIPT_NAMES) {
+    for (const reference of referencedScriptsInCommand(scripts[scriptName])) {
+      referenced.add(reference);
+    }
+  }
+
+  return new Set([...referenced].filter((scriptName) => !hasScriptName(scripts, scriptName)));
+}
+
+function referencedScriptsInCommand(command) {
+  if (typeof command !== "string") {
+    return [];
+  }
+
+  const references = [];
+  for (const pattern of SCRIPT_REFERENCE_PATTERNS) {
+    for (const match of command.matchAll(pattern)) {
+      const scriptName = match[1];
+      if (!isPackageManagerSubcommand(scriptName)) {
+        references.push(scriptName);
+      }
+    }
+  }
+
+  return references;
+}
+
+function isPackageManagerSubcommand(scriptName) {
+  return PACKAGE_MANAGER_SUBCOMMANDS.has(scriptName);
+}

package/src/cli/profile-docs.mjs

@@ -0,0 +1,31 @@
+import { parseProfiles } from "./profile.mjs";
+import { fromTemplates } from "./utils.mjs";
+
+const TARGET_ROOT = "docs/ai-check-template";
+
+const COMMON_DOC_FILES = [
+  ["docs/test-design-template.md", `${TARGET_ROOT}/docs/test-design-template.md`],
+  ["docs/philosophy/formal-name-match.md", `${TARGET_ROOT}/docs/philosophy/formal-name-match.md`],
+  ["docs/philosophy/given-when-then.md", `${TARGET_ROOT}/docs/philosophy/given-when-then.md`],
+  ["docs/philosophy/qa-techniques.md", `${TARGET_ROOT}/docs/philosophy/qa-techniques.md`],
+  ["docs/philosophy/test-pyramid.md", `${TARGET_ROOT}/docs/philosophy/test-pyramid.md`],
+  ["prompts/diagnostic-repair.md", `${TARGET_ROOT}/prompts/diagnostic-repair.md`],
+  ["profiles/README.md", `${TARGET_ROOT}/profiles/README.md`],
+];
+
+export function getProfileDocFiles(input = "react-nextjs") {
+  const profile = typeof input === "string" ? parseProfiles(input) : input;
+  const files = [...COMMON_DOC_FILES];
+
+  for (const profileName of [profile.base, ...(profile.addons ?? [])]) {
+    files.push([
+      `profiles/${profileName}/README.md`,
+      `${TARGET_ROOT}/profiles/${profileName}/README.md`,
+    ]);
+  }
+
+  return files.map(([sourceRelativePath, targetRelativePath]) => ({
+    sourcePath: fromTemplates(...sourceRelativePath.split("/")),
+    relativePath: targetRelativePath,
+  }));
+}

package/src/cli/profile-scripts.mjs

@@ -0,0 +1,96 @@
+import { parseProfiles } from "./profile.mjs";
+import { DEFAULT_PACKAGE_MANAGER, scriptCommand } from "./package-manager.mjs";
+
+const BASE_PROFILE_SCRIPTS = {
+  "react-nextjs": {
+    "ai:check": "pnpm typecheck && pnpm lint && pnpm doctor && pnpm deadcode && pnpm test && pnpm test:e2e:smoke",
+    "ai:check:fast": "pnpm typecheck && pnpm lint && pnpm test:unit",
+    doctor: "npx -y react-doctor@latest . --fail-on warning",
+    deadcode: "knip",
+  },
+  "react-vanilla": {
+    "ai:check": "pnpm typecheck && pnpm lint && pnpm deadcode && pnpm test",
+    "ai:check:fast": "pnpm typecheck && pnpm lint && pnpm test:unit",
+    deadcode: "knip",
+  },
+  "expo-rn": {
+    "ai:check": "pnpm typecheck && pnpm lint && pnpm deadcode && pnpm test && pnpm test:e2e:smoke",
+    "ai:check:fast": "pnpm typecheck && pnpm lint && pnpm test:unit",
+    deadcode: "knip",
+    "test:e2e:smoke": "maestro test .maestro/smoke.yaml",
+  },
+  "node-cli": {
+    "ai:check": "pnpm typecheck && pnpm lint && pnpm deadcode && pnpm test",
+    "ai:check:fast": "pnpm typecheck && pnpm lint && pnpm test:unit",
+    deadcode: "knip",
+  },
+};
+
+const ADDON_PROFILE_SCRIPTS = {
+  "supabase-rls": {
+    "test:db": "supabase test db",
+    "test:integration:rls": "vitest run --dir tests/rls",
+  },
+};
+
+const ADDON_CHECK_STEPS = {
+  "supabase-rls": ["test:db", "test:integration:rls"],
+};
+
+const COMMON_SUPPORT_SCRIPTS = {
+  typecheck: "tsc --noEmit",
+  lint: "eslint .",
+  test: "vitest run",
+  "test:unit": "vitest run --dir tests/unit",
+};
+
+const BASE_PROFILE_SUPPORT_SCRIPTS = {
+  "react-nextjs": {
+    ...COMMON_SUPPORT_SCRIPTS,
+    "test:e2e:smoke": "playwright test --grep smoke",
+  },
+  "react-vanilla": COMMON_SUPPORT_SCRIPTS,
+  "expo-rn": COMMON_SUPPORT_SCRIPTS,
+  "node-cli": COMMON_SUPPORT_SCRIPTS,
+};
+
+export function getProfileScripts(input = "react-nextjs", options = {}) {
+  const profile = typeof input === "string" ? parseProfiles(input) : input;
+  const packageManager = options.packageManager ?? DEFAULT_PACKAGE_MANAGER;
+  const scripts = { ...BASE_PROFILE_SCRIPTS[profile.base] };
+
+  for (const addon of profile.addons) {
+    Object.assign(scripts, ADDON_PROFILE_SCRIPTS[addon] ?? {});
+    for (const step of ADDON_CHECK_STEPS[addon] ?? []) {
+      scripts["ai:check"] = appendScriptStep(scripts["ai:check"], scriptCommand(packageManager, step));
+    }
+  }
+
+  return renderPackageManagerScripts(scripts, packageManager);
+}
+
+export function getProfileSupportScripts(input = "react-nextjs") {
+  const profile = typeof input === "string" ? parseProfiles(input) : input;
+  return { ...BASE_PROFILE_SUPPORT_SCRIPTS[profile.base] };
+}
+
+function appendScriptStep(command, step) {
+  const parts = command.split(" && ").map((part) => part.trim());
+  if (parts.includes(step)) {
+    return command;
+  }
+
+  return [...parts, step].join(" && ");
+}
+
+function renderPackageManagerScripts(scripts, packageManager) {
+  return Object.fromEntries(
+    Object.entries(scripts).map(([name, command]) => [name, renderScriptCommand(command, packageManager)]),
+  );
+}
+
+function renderScriptCommand(command, packageManager) {
+  return command.replace(/\bpnpm ([a-zA-Z0-9:_-]+)/g, (_, scriptName) => (
+    scriptCommand(packageManager, scriptName)
+  ));
+}

package/src/cli/profile.mjs

@@ -0,0 +1,59 @@
+import { CliError } from "./utils.mjs";
+
+const BASE_PROFILES = new Set([
+  "react-nextjs",
+  "react-vanilla",
+  "expo-rn",
+  "node-cli",
+]);
+
+const ADDON_PROFILES = new Set(["supabase-rls"]);
+
+export const supportedProfiles = [
+  ...BASE_PROFILES,
+  ...ADDON_PROFILES,
+];
+
+export function parseProfiles(input = "react-nextjs") {
+  const names = input
+    .split(/[,+]/)
+    .map((value) => value.trim())
+    .filter(Boolean);
+
+  if (names.length === 0) {
+    throw invalidProfile(input);
+  }
+
+  const uniqueNames = new Set(names);
+  if (uniqueNames.size !== names.length) {
+    throw new CliError(`Duplicate profile in --profile: ${input}`);
+  }
+
+  const unknown = names.filter(
+    (name) => !BASE_PROFILES.has(name) && !ADDON_PROFILES.has(name),
+  );
+  if (unknown.length > 0) {
+    throw invalidProfile(unknown.join(", "));
+  }
+
+  const baseProfiles = names.filter((name) => BASE_PROFILES.has(name));
+  if (baseProfiles.length !== 1) {
+    throw new CliError(
+      `--profile must include exactly one base profile. Supported base profiles: ${[
+        ...BASE_PROFILES,
+      ].join(", ")}`,
+    );
+  }
+
+  return {
+    base: baseProfiles[0],
+    addons: names.filter((name) => ADDON_PROFILES.has(name)),
+    all: names,
+  };
+}
+
+function invalidProfile(value) {
+  return new CliError(
+    `Invalid profile: ${value}. Supported profiles: ${supportedProfiles.join(", ")}`,
+  );
+}