@agjs/tsforge 0.1.19 → 0.2.1

package/src/config/profiles.ts

@@ -0,0 +1,150 @@
+import type { ProfileId } from "../rule-packs/rule-catalog.types";
+
+export type { ProfileId };
+
+export interface IProfileDefinition {
+  readonly id: ProfileId;
+  readonly label: string;
+  readonly description: string;
+  /** Extra packs to include beyond stack detection (deduped at resolve time). */
+  readonly extraPacks?: readonly string[];
+  /** Rule severity overrides keyed by bare rule name. */
+  readonly ruleOverrides?: Readonly<Record<string, "error" | "warn" | "off">>;
+  /** Meta-rule ids to elevate to error in this profile. */
+  readonly metaRulesAtError?: readonly string[];
+}
+
+/** Architecture-tier rules enabled only in the opinionated profile. */
+export const ARCHITECTURE_RULES = [
+  "component-folder-structure",
+  "no-state-in-component-body",
+  "no-inline-jsx-functions",
+  "index-must-reexport-default",
+  "forwardref-display-name",
+  "max-hooks-per-file",
+] as const;
+
+const architectureOffOverrides = Object.fromEntries(
+  ARCHITECTURE_RULES.map((rule) => [rule, "off" as const])
+);
+
+export const PROFILE_DEFINITIONS: Readonly<
+  Record<ProfileId, IProfileDefinition>
+> = {
+  recommended: {
+    id: "recommended",
+    label: "Recommended",
+    description:
+      "Safety + framework packs from stack detection; architecture opinions off by default.",
+    ruleOverrides: {
+      ...architectureOffOverrides,
+      "prefer-early-return": "warn",
+    },
+  },
+  strict: {
+    id: "strict",
+    label: "Strict",
+    description:
+      "Recommended plus CI/supply-chain meta-rules at error and type-aware async rules.",
+    extraPacks: ["typescript-core"],
+    ruleOverrides: {
+      ...architectureOffOverrides,
+      "prefer-early-return": "warn",
+    },
+    metaRulesAtError: [
+      "workflow-permissions-explicit",
+      "lockfile-required",
+      "single-package-manager",
+    ],
+  },
+  security: {
+    id: "security",
+    label: "Security",
+    description:
+      "Recommended plus runtime-boundaries and experimental authorization heuristics.",
+    extraPacks: ["runtime-boundaries", "authorization"],
+    ruleOverrides: architectureOffOverrides,
+  },
+  frontend: {
+    id: "frontend",
+    label: "Frontend",
+    description: "Recommended with React/Next architecture rules at warn.",
+    ruleOverrides: {
+      "no-html-img-element": "warn",
+      "no-anonymous-useEffect": "warn",
+      "no-derived-state-in-effect": "warn",
+      ...architectureOffOverrides,
+    },
+  },
+  backend: {
+    id: "backend",
+    label: "Backend",
+    description:
+      "Recommended; stack detection adds Fastify/Elysia/Drizzle/BullMQ packs.",
+    ruleOverrides: architectureOffOverrides,
+  },
+  opinionated: {
+    id: "opinionated",
+    label: "Opinionated",
+    description:
+      "Full house-style architecture rules including component folder structure.",
+    ruleOverrides: {
+      "component-folder-structure": "error",
+      "no-state-in-component-body": "error",
+      "no-inline-jsx-functions": "warn",
+      "index-must-reexport-default": "error",
+      "forwardref-display-name": "error",
+      "max-hooks-per-file": "warn",
+      "prefer-early-return": "error",
+    },
+  },
+};
+
+export const DEFAULT_PROFILE: ProfileId = "recommended";
+
+export function isProfileId(value: string): value is ProfileId {
+  return value in PROFILE_DEFINITIONS;
+}
+
+/** Merge profile overrides with user config overrides (user wins). */
+export function resolveProfileRuleOverrides(
+  profileId: ProfileId | undefined
+): Record<string, "error" | "warn" | "off"> {
+  const id = profileId ?? DEFAULT_PROFILE;
+  const profile = PROFILE_DEFINITIONS[id];
+
+  return { ...(profile.ruleOverrides ?? {}) };
+}
+
+export function resolveProfileExtraPacks(
+  profileId: ProfileId | undefined
+): readonly string[] {
+  const id = profileId ?? DEFAULT_PROFILE;
+  const profile = PROFILE_DEFINITIONS[id];
+
+  return profile.extraPacks ?? [];
+}
+
+export function resolveProfileMetaRuleOverrides(
+  profileId: ProfileId | undefined
+): Record<string, "error"> {
+  const id = profileId ?? DEFAULT_PROFILE;
+  const profile = PROFILE_DEFINITIONS[id];
+  const result: Record<string, "error"> = {};
+
+  for (const ruleId of profile.metaRulesAtError ?? []) {
+    result[ruleId] = "error";
+  }
+
+  return result;
+}
+
+export function mergeRuleOverrides(
+  profileId: ProfileId | undefined,
+  userOverrides: Readonly<Record<string, "error" | "warn" | "off">>
+): Record<string, "error" | "warn" | "off"> {
+  return {
+    ...resolveProfileRuleOverrides(profileId),
+    ...userOverrides,
+  };
+}

package/src/config/tsforge-config.ts

@@ -3,6 +3,14 @@ import { isRecord } from "../lib/guards";
 import { PACK_REGISTRY } from "../stack-detection";
 import { parseMcpServers, type IMcpServerConfig } from "../mcp";
 import { parsePlugins, type IExternalPlugin } from "./external-plugins";
+import {
+  DEFAULT_PROFILE,
+  isProfileId,
+  mergeRuleOverrides,
+  resolveProfileExtraPacks,
+  resolveProfileMetaRuleOverrides,
+  type ProfileId,
+} from "./profiles";
 
 /**
  * User-defined configuration from tsforge.config.json
@@ -10,6 +18,9 @@ import { parsePlugins, type IExternalPlugin } from "./external-plugins";
  * include/exclude packs, and tune rule severities (eslint packs + meta-rules).
  */
 export interface ITsforgeProjectConfig {
+  /** Rule profile: recommended (default), strict, security, frontend, backend, opinionated. */
+  readonly profile?: ProfileId;
+
   /** Force-enable a stack by name (skip detection heuristics, force-add its packs). */
   readonly stack?: string;
 
@@ -100,6 +111,31 @@ function warnUnknownPackInInclude(packId: string): void {
   warnConfig(msg);
 }
 
+function warnInvalidProfile(profileValue: unknown): void {
+  warnConfig(
+    `tsforge.config.json: "profile" must be one of recommended, strict, security, frontend, backend, opinionated — got "${String(profileValue)}"`
+  );
+}
+
+/** Validate and extract profile field. */
+function validateProfile(parsed: unknown): ProfileId | undefined {
+  if (typeof parsed !== "string") {
+    if (parsed !== undefined) {
+      warnInvalidProfile(parsed);
+    }
+
+    return undefined;
+  }
+
+  if (isProfileId(parsed)) {
+    return parsed;
+  }
+
+  warnInvalidProfile(parsed);
+
+  return undefined;
+}
+
 /** Validate and extract stack field. */
 function validateStack(parsed: unknown): string | undefined {
   if (typeof parsed === "string") {
@@ -181,6 +217,7 @@ function buildConfigFields(
   parsed: Record<string, unknown>
 ): ITsforgeProjectConfig {
   const configFields: {
+    profile?: ProfileId;
     stack?: string;
     packs?: { include?: readonly string[]; exclude?: readonly string[] };
     rules?: Record<string, "error" | "warn" | "off">;
@@ -188,6 +225,14 @@ function buildConfigFields(
     plugins?: readonly IExternalPlugin[];
   } = {};
 
+  if (parsed.profile !== undefined) {
+    const profile = validateProfile(parsed.profile);
+
+    if (profile !== undefined) {
+      configFields.profile = profile;
+    }
+  }
+
   if (parsed.stack !== undefined) {
     const stack = validateStack(parsed.stack);
 
@@ -290,6 +335,13 @@ export function resolveActivePacks(
     packs.add(config.stack);
   }
 
+  // Profile extra packs (runtime-boundaries, authorization, typescript-core, …)
+  for (const packId of resolveProfileExtraPacks(config.profile)) {
+    if (packId in PACK_REGISTRY) {
+      packs.add(packId);
+    }
+  }
+
   // Include: add packs (unknown ids are kept out of the registry lookup warning only)
   for (const packId of config.packs?.include ?? []) {
     if (packId.length === 0) {
@@ -324,11 +376,9 @@ function isSeverityOverride(value: unknown): value is "error" | "warn" | "off" {
 export function normalizeRuleOverrides(
   config: ITsforgeProjectConfig
 ): Record<string, "error" | "warn" | "off"> {
-  const normalized: Record<string, "error" | "warn" | "off"> = {};
+  const userOverrides: Record<string, "error" | "warn" | "off"> = {};
 
   for (const [key, severity] of Object.entries(config.rules ?? {})) {
-    // Runtime data can violate the declared union (hand-built configs in tests,
-    // partially validated JSON) — re-check before trusting it.
     if (!isSeverityOverride(severity)) {
       continue;
     }
@@ -336,9 +386,18 @@ export function normalizeRuleOverrides(
     const bareKey = key.startsWith("tsforge/") ? key.slice(8) : key;
 
     if (bareKey.length > 0) {
-      normalized[bareKey] = severity;
+      userOverrides[bareKey] = severity;
     }
   }
 
-  return normalized;
+  return {
+    ...resolveProfileMetaRuleOverrides(config.profile),
+    ...mergeRuleOverrides(config.profile, userOverrides),
+  };
+}
+
+export function resolveProjectProfile(
+  config: ITsforgeProjectConfig
+): ProfileId {
+  return config.profile ?? DEFAULT_PROFILE;
 }

package/src/detect-gate.ts

@@ -2,6 +2,7 @@ import { join, dirname } from "node:path";
 import { existsSync } from "node:fs";
 import { ESLint } from "eslint";
 import { WEB_TEMPLATES, type WebFramework } from "./web-templates";
+import { isRecord } from "./lib/guards";
 
 /**
  * Build the gate that confirms "done" — and makes tsforge a TypeScript-SPECIALIZED
@@ -63,6 +64,11 @@ const ESLINT_BIN = resolveToolBin("eslint");
 const TSC_BIN = resolveToolBin("tsc");
 const PRETTIER_BIN = resolveToolBin("prettier");
 const STRICT_CONFIG = join(import.meta.dir, "..", "strict.eslint.config.mjs");
+const TYPE_AWARE_CONFIG = join(
+  import.meta.dir,
+  "..",
+  "strict.type-aware.eslint.config.mjs"
+);
 const BROWSER_CHECK = join(
   import.meta.dir,
   "..",
@@ -86,6 +92,8 @@ const STRICT_TSCONFIG = `{
     "noUncheckedIndexedAccess": true,
     "noImplicitOverride": true,
     "noFallthroughCasesInSwitch": true,
+    "useUnknownInCatchVariables": true,
+    "erasableSyntaxOnly": true,
     "esModuleInterop": true,
     "forceConsistentCasingInFileNames": true,
     "skipLibCheck": true,
@@ -99,21 +107,35 @@ const STRICT_TSCONFIG = `{
 /** Strict overlay for a project that ALREADY has a tsconfig: extend it (so the
  *  project's paths/jsx/module/lib still resolve — a bare strict config would
  *  mis-compile a real app) but FORCE every strictness flag on top, so a loosely-
- *  configured repo still gets tsforge's strict-TS floor. Written as a sibling
- *  `tsforge.tsconfig.json` and gated with `tsc -p`. */
-const STRICT_TSCONFIG_OVERRIDE = `{
-  "extends": "./tsconfig.json",
+ *  configured repo still gets tsforge's strict-TS floor.
+ *
+ *  PERSISTENCE POLICY: written under `.tsforge/` (tsforge's cache namespace), NOT
+ *  as a sibling in the project root — so the gate never litters the user's repo
+ *  with a `tsforge.tsconfig.json`. `extends` points one level up to the project's
+ *  own config, and `include`/`exclude` are re-stated relative to the subdir
+ *  because `extends` does not inherit them (they default to the config's own
+ *  directory otherwise — which under `.tsforge/` would compile nothing). */
+const STRICT_TSCONFIG_OVERLAY = `{
+  "extends": "../tsconfig.json",
   "compilerOptions": {
     "strict": true,
     "noUncheckedIndexedAccess": true,
     "noImplicitOverride": true,
     "noFallthroughCasesInSwitch": true,
+    "useUnknownInCatchVariables": true,
+    "erasableSyntaxOnly": true,
     "skipLibCheck": true,
     "noEmit": true
-  }
+  },
+  "include": ["../**/*.ts", "../**/*.tsx"],
+  "exclude": ["../node_modules", "../dist", "../build", "../scratch", "../.tsforge"]
 }
 `;
 
+/** The gate overlay's home: tsforge's cache dir + the overlay filename. */
+const GATE_TSCONFIG_DIR = ".tsforge";
+const GATE_TSCONFIG_FILE = "tsconfig.gate.json";
+
 // The web-stack scaffolds (Vite + React full-kit, or Vite vanilla) live in the
 // registry; this module just lays them down and builds their gate. shadcn/TanStack
 // boilerplate is held to a web-tailored strict config (no `I`-prefix — React names
@@ -364,7 +386,12 @@ export function buildWebGate(framework: WebFramework): IGate {
   // HARNESS-authored and app-agnostic: we deliberately do NOT run a model-authored
   // checks.json — the 27b writes over-strict interaction assertions (exact
   // placeholders/fill flows) it then can't satisfy and spirals on (iter3/4).
-  const render = `bun "${BROWSER_CHECK}" dist/index.html --smoke --crawl`;
+  // OPT-IN quality oracles (default OFF so existing web runs are unchanged):
+  // TSFORGE_A11Y=1 adds axe (serious/critical fail), TSFORGE_SCREENSHOTS=1 writes
+  // per-route PNGs. A "frontend"/"strict" profile can set these.
+  const a11y = process.env.TSFORGE_A11Y === "1" ? " --a11y" : "";
+  const shots = process.env.TSFORGE_SCREENSHOTS === "1" ? " --screenshots" : "";
+  const render = `bun "${BROWSER_CHECK}" dist/index.html --smoke --crawl${a11y}${shots}`;
   // Prettier enforces formatting (the fix step runs `prettier --write` first, so
   // this passes without the model ever hand-formatting). Respects .prettierignore
   // (vendored ui/ + lib/ skipped). Runs after lint so a parse error fails there.
@@ -458,7 +485,8 @@ export function prettierWriteCommand(): string {
 export async function buildGate(
   cwd: string,
   packs?: readonly string[],
-  ruleOverrides?: Readonly<Record<string, "error" | "warn" | "off">>
+  ruleOverrides?: Readonly<Record<string, "error" | "warn" | "off">>,
+  options?: { enableTypeAware?: boolean; includeTests?: boolean }
 ): Promise<IGate> {
   const parts: string[] = [];
   const labels: string[] = [];
@@ -475,29 +503,104 @@ export async function buildGate(
   parts.push(lint.command);
   labels.push(lint.label);
 
+  if (options?.enableTypeAware === true) {
+    const typeAware = await typeAwareLintPart(cwd);
+
+    if (typeAware !== null) {
+      parts.push(typeAware.command);
+      labels.push(typeAware.label);
+    }
+  }
+
+  // Tests run LAST (after the cheap static floor) so a type/lint error fails
+  // fast without paying for a test run. Only appended when the project actually
+  // has tests to run — a strict-floor-only run, or a project with none, skips it.
+  if (options?.includeTests === true) {
+    const test = await discoverTestCommand(cwd);
+
+    if (test !== null) {
+      parts.push(test);
+      labels.push("tests");
+    }
+  }
+
   return { command: parts.join(" && "), label: labels.join(" + ") };
 }
 
+/** The npm-init placeholder test script — running it always fails, so it must
+ *  NOT count as "the project has tests". */
+const PLACEHOLDER_TEST = /no test specified/i;
+
+/**
+ * The project's test command for the gate, or null when there's nothing to run.
+ * Prefers an explicit, real package.json `test` script (run via `bun run test`);
+ * else falls back to `bun test` when the project has test files; else null — so
+ * a greenfield app with no tests yet stays at the strict floor instead of
+ * failing a gate that runs a placeholder/absent test command.
+ */
+export async function discoverTestCommand(cwd: string): Promise<string | null> {
+  const pkgFile = Bun.file(join(cwd, "package.json"));
+
+  if (await pkgFile.exists()) {
+    try {
+      const pkg: unknown = await pkgFile.json();
+      const scripts = isRecord(pkg) ? pkg.scripts : undefined;
+      const script = isRecord(scripts) ? scripts.test : undefined;
+
+      if (
+        typeof script === "string" &&
+        script.trim().length > 0 &&
+        !PLACEHOLDER_TEST.test(script)
+      ) {
+        return "bun run test";
+      }
+    } catch {
+      // Malformed package.json — fall through to file detection.
+    }
+  }
+
+  return (await hasTestFiles(cwd)) ? "bun test" : null;
+}
+
+/** True when the project has at least one *.test.* / *.spec.* file (outside
+ *  node_modules) — the signal that a bare `bun test` has something to run. */
+async function hasTestFiles(cwd: string): Promise<boolean> {
+  const glob = new Bun.Glob("**/*.{test,spec}.{ts,tsx,js,jsx}");
+
+  for await (const path of glob.scan({ cwd, onlyFiles: true })) {
+    if (!path.includes("node_modules")) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
 /**
  * The type-aware floor — ALWAYS tsforge-strict (user policy: a repo's own config
- * is never trusted to be strict enough). With a project tsconfig, extend it but
- * force the strict flags; greenfield, bring the full strict one. null when not a
- * TS project. (The strict override / bundled config win over whatever the repo set.)
+ * is never trusted to be strict enough). With a project tsconfig, extend it under
+ * `.tsforge/` but force the strict flags; greenfield, bring the full strict one.
+ * null when not a TS project. (The strict overlay / bundled config win over
+ * whatever the repo set.)
  */
 async function tscPart(cwd: string): Promise<string | null> {
   const hasTsconfig = await Bun.file(join(cwd, "tsconfig.json")).exists();
 
   if (hasTsconfig) {
+    // EPHEMERAL gate artifact: lives in .tsforge/ (Bun.write makes the dir), so
+    // we never drop a tsforge.tsconfig.json in the user's project root.
     await Bun.write(
-      join(cwd, "tsforge.tsconfig.json"),
-      STRICT_TSCONFIG_OVERRIDE
+      join(cwd, GATE_TSCONFIG_DIR, GATE_TSCONFIG_FILE),
+      STRICT_TSCONFIG_OVERLAY
     );
+    await ignoreGateArtifact(cwd);
 
-    return `"${TSC_BIN}" --noEmit -p tsforge.tsconfig.json`;
+    return `"${TSC_BIN}" --noEmit -p ${GATE_TSCONFIG_DIR}/${GATE_TSCONFIG_FILE}`;
   }
 
   // Greenfield: bring a strict tsconfig so tsc can gate — but only when this is
   // actually a TS project (has a package.json), so we never litter a random dir.
+  // Unlike the overlay, a greenfield tsconfig.json is a DURABLE project file.
   if (await Bun.file(join(cwd, "package.json")).exists()) {
     await Bun.write(join(cwd, "tsconfig.json"), STRICT_TSCONFIG);
 
@@ -507,6 +610,20 @@ async function tscPart(cwd: string): Promise<string | null> {
   return null;
 }
 
+/** Keep the ephemeral gate overlay out of git WITHOUT touching the user's root
+ *  .gitignore: drop a scoped `.tsforge/.gitignore` ignoring just the overlay.
+ *  Created only when absent, so a user-authored `.tsforge/.gitignore` (e.g. one
+ *  that intentionally tracks rules.json) is never clobbered. */
+async function ignoreGateArtifact(cwd: string): Promise<void> {
+  const ignore = join(cwd, GATE_TSCONFIG_DIR, ".gitignore");
+
+  if (await Bun.file(ignore).exists()) {
+    return;
+  }
+
+  await Bun.write(ignore, `${GATE_TSCONFIG_FILE}\n`);
+}
+
 /** The syntactic idiom layer — ALWAYS tsforge's bundled strict eslint config
  *  (user policy). We deliberately do NOT defer to the project's own `lint`
  *  script: that's exactly how a weak repo would dodge the strict-TS floor. The
@@ -538,3 +655,17 @@ function lintPart(
     label: "strict TypeScript (tsforge)",
   };
 }
+
+/** Optional type-aware async rules — only when target has tsconfig.json. */
+async function typeAwareLintPart(cwd: string): Promise<IGate | null> {
+  const hasTsconfig = await Bun.file(join(cwd, "tsconfig.json")).exists();
+
+  if (!hasTsconfig) {
+    return null;
+  }
+
+  return {
+    command: `bun "${ESLINT_BIN}" --no-config-lookup -c "${TYPE_AWARE_CONFIG}" --format json .`,
+    label: "type-aware async (tsforge)",
+  };
+}

package/src/eval/eval.types.ts

@@ -1,3 +1,5 @@
+import type { FailureClass } from "./failure-class";
+
 export interface IJudgeInput {
   goal: string;
   criteria: string;
@@ -21,6 +23,9 @@ export interface IRunRecord {
   ms: number;
   /** LLM-judge quality score (1–5), when available. */
   quality?: number;
+  /** Structured reason a failed run failed (from classifyRun); omitted/`none`
+   *  for a passing run. The substrate for turning failures into interventions. */
+  failureClass?: FailureClass;
 }
 
 /** Aggregated metrics for a variant across its runs. */
@@ -33,4 +38,8 @@ export interface IVariantSummary {
   avgMs: number;
   /** Average quality across runs that were scored (0 if none). */
   avgQuality: number;
+  /** Count of failed runs by failure class (e.g. {"type-error": 2}); empty when
+   *  no run carried a class. Lets a sweep show WHY a variant failed, not just how
+   *  often. */
+  failureClasses: Record<string, number>;
 }