@agjs/tsforge 0.1.18 → 0.2.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@agjs/tsforge",
   "type": "module",
-  "version": "0.1.18",
+  "version": "0.2.0",
   "license": "MIT",
   "description": "TypeScript coding harness with a deterministic gate, stack-aware guardrails, and stream-level correction.",
   "repository": {
@@ -34,6 +34,9 @@
     "@stylistic/eslint-plugin": "^5.10.0",
     "@typescript-eslint/utils": "8.60.0",
     "cli-highlight": "2.1.11",
+    "eslint-plugin-react": "^7.37.5",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "eslint-plugin-jsx-a11y": "^6.10.2",
     "eslint": "10.4.0",
     "prettier": "3.8.3",
     "typescript": "6.0.3",

package/scripts/build-rules-md.ts

@@ -1,9 +1,10 @@
-// Generate RULES.md: a catalog of all rule packs and meta-rules.
-// This produces a deterministic, human-readable reference of what gets enforced.
-//   bun run packages/core/scripts/build-rules-md.ts
+// Generate RULES.md grouped by adoption tier, then pack.
 import { join } from "node:path";
 import { RULE_PACKS } from "../src/rule-packs";
 import { META_RULES } from "../src/meta-rules";
+import { getRuleCatalogEntry } from "../src/rule-packs/rule-metadata";
+import type { RuleTier } from "../src/rule-packs/rule-catalog.types";
+import { PROFILE_DEFINITIONS } from "../src/config/profiles";
 
 function getRuleDescription(obj: unknown): string | undefined {
   const isObject = (val: unknown): val is Record<string, unknown> =>
@@ -30,15 +31,28 @@ function getRuleDescription(obj: unknown): string | undefined {
   return typeof description === "string" ? description : undefined;
 }
 
+const TIER_ORDER: readonly RuleTier[] = [
+  "safety",
+  "framework",
+  "architecture",
+  "experimental",
+];
+
 const out: string[] = [
   "# Rules and Meta-Rules Catalog",
   "",
-  "This document lists all rules enforced by tsforge across rule packs and meta-rules.",
+  "Rules are grouped by **adoption tier**. Use `profile` in `tsforge.config.json` to control which tiers are active by default.",
+  "",
+  "## Profiles",
   "",
 ];
 
-// Section: Rule Packs
-out.push("## Rule Packs");
+for (const profile of Object.values(PROFILE_DEFINITIONS)) {
+  out.push(`- **${profile.id}**: ${profile.description}`);
+}
+
+out.push("");
+out.push("## Rule Packs by Tier");
 out.push("");
 
 type PackId = keyof typeof RULE_PACKS;
@@ -47,36 +61,62 @@ function isPackId(id: string): id is PackId {
   return id in RULE_PACKS;
 }
 
-const packIds = Object.keys(RULE_PACKS).sort();
+const entriesByTier = new Map<
+  RuleTier,
+  { packId: string; ruleName: string; severity: string; description: string }[]
+>();
 
-for (const packId of packIds) {
+for (const packId of Object.keys(RULE_PACKS).sort()) {
   if (!isPackId(packId)) {
     continue;
   }
 
   const pack = RULE_PACKS[packId];
 
-  out.push(`### ${packId}`);
-  out.push("");
-  out.push(pack.description);
-  out.push("");
-
-  const ruleNames = Object.keys(pack.rules).sort();
-
-  for (const ruleName of ruleNames) {
+  for (const ruleName of Object.keys(pack.rules).sort()) {
     const rule = pack.rules[ruleName];
     const severity = pack.rulesConfig[ruleName] ?? "warn";
     const description = getRuleDescription(rule) ?? ruleName;
-    const severityUpper = severity.toUpperCase();
-    const line = `- **${ruleName}** [${severityUpper}]: ${description}`;
+    const tier = getRuleCatalogEntry(ruleName, packId).tier;
+    const list = entriesByTier.get(tier) ?? [];
+
+    list.push({
+      packId,
+      ruleName,
+      severity: severity.toUpperCase(),
+      description,
+    });
+    entriesByTier.set(tier, list);
+  }
+}
+
+for (const tier of TIER_ORDER) {
+  const entries = entriesByTier.get(tier) ?? [];
+
+  if (entries.length === 0) {
+    continue;
+  }
 
-    out.push(line);
+  out.push(`### Tier: ${tier}`);
+  out.push("");
+
+  for (const entry of entries.sort((a, b) => {
+    const byPack = a.packId.localeCompare(b.packId);
+
+    if (byPack !== 0) {
+      return byPack;
+    }
+
+    return a.ruleName.localeCompare(b.ruleName);
+  })) {
+    out.push(
+      `- **${entry.packId}/${entry.ruleName}** [${entry.severity}]: ${entry.description}`
+    );
   }
 
   out.push("");
 }
 
-// Section: Meta-Rules
 out.push("## Meta-Rules");
 out.push("");
 out.push(
@@ -103,7 +143,6 @@ for (const rule of META_RULES) {
   rulesByCategory.set(cat, rules);
 }
 
-// Render meta-rules by category.
 for (const category of categoryOrder) {
   const rules = rulesByCategory.get(category) ?? [];
 
@@ -123,6 +162,24 @@ for (const category of categoryOrder) {
   out.push("");
 }
 
+out.push("## Out of scope");
+out.push("");
+out.push(
+  "The following are intentionally deferred — wrong tool for the syntactic ESLint gate, or require cross-file analysis:"
+);
+out.push("");
+out.push(
+  "- GraphQL/WebSocket/OpenAPI contract rules (until OpenAPI dep + parser)"
+);
+out.push(
+  "- Container/Kubernetes YAML hardening (future meta-rules when Dockerfile/k8s detected)"
+);
+out.push("- LLM/MCP security packs (opt-in when AI SDK deps detected)");
+out.push("- FSD layer DAG / full authorization taint tracking");
+out.push("- Lighthouse / bundle-analyzer CI gates");
+out.push("- Violation ratcheting / baseline snapshots (Phase 5)");
+out.push("");
+
 const path = join(import.meta.dir, "..", "RULES.md");
 
 await Bun.write(path, out.join("\n"));

package/scripts/sweep.ts

@@ -11,6 +11,7 @@ import { runSpec, qualityRepair } from "../src/loop";
 import { modelAgent } from "../src/agent";
 import { OpenAICompatibleProvider } from "../src/inference";
 import { resolveActiveModel, resolveApiKey } from "../src/models-config";
+import { providerConfig } from "../src/cli";
 import { summarize, type IRunRecord } from "../src/eval";
 import { renderEvent } from "../src/render";
 import type { ILoopEvent } from "../src/loop";
@@ -109,28 +110,32 @@ const seedFiles = await readdir(seedDir, { recursive: true });
 // unreachable endpoint and hung with an empty run.log.)
 const { entry: activeModel } = await resolveActiveModel();
 
-const provider = new OpenAICompatibleProvider({
-  baseUrl: activeModel.baseUrl,
-  model: activeModel.model,
-  apiKey: resolveApiKey(activeModel),
-  // Thinking tokens count against the limit, so give reasoning + code room.
-  maxTokens: Number(process.env.TSFORGE_MAX_TOKENS ?? "16384"),
-  // Opt-in only: a repetition penalty breaks rare temp-0 loops but DEGRADES
-  // algorithmic code (it made `money` write unsafe/any code that failed the
-  // strict gate). Default off; enable via env if a target genuinely loops.
-  repetitionPenalty:
-    process.env.TSFORGE_REPETITION_PENALTY === undefined
-      ? undefined
-      : Number(process.env.TSFORGE_REPETITION_PENALTY),
-});
+// Build the wire config the SAME way the CLI does (`providerConfig`), so the
+// sweep inherits the active entry's provider dialect — `reasoning`,
+// `reasoningEffort`, `extraBody`, `extraHeaders`. Hand-rolling the config here
+// dropped those fields, so a DeepSeek sweep sent qwen-only params and hit the
+// 400s the interactive path already handles. maxTokens still defaults to
+// PROVIDER_LIMITS (16384) — thinking tokens count against it, so reasoning +
+// code get room. Repetition penalty stays opt-in via TSFORGE_REPETITION_PENALTY.
+const provider = new OpenAICompatibleProvider(providerConfig(activeModel));
 
 // The judge scores quality. Point it at a flagship via TSFORGE_JUDGE_URL/MODEL
-// (+ TSFORGE_JUDGE_KEY) to measure the gap; defaults to the active model judging itself.
-const judgeProvider = new OpenAICompatibleProvider({
-  baseUrl: process.env.TSFORGE_JUDGE_URL ?? activeModel.baseUrl,
-  model: process.env.TSFORGE_JUDGE_MODEL ?? activeModel.model,
-  apiKey: process.env.TSFORGE_JUDGE_KEY ?? resolveApiKey(activeModel),
-});
+// (+ TSFORGE_JUDGE_KEY) to measure the gap. When NOT overridden, the active
+// model judges itself — reuse its full dialect via providerConfig so a
+// self-judge against DeepSeek speaks DeepSeek too. An explicit external judge
+// is a plain generic call (its own endpoint, no inherited reasoning dialect).
+const judgeOverridden =
+  process.env.TSFORGE_JUDGE_URL !== undefined ||
+  process.env.TSFORGE_JUDGE_MODEL !== undefined;
+const judgeProvider = new OpenAICompatibleProvider(
+  judgeOverridden
+    ? {
+        baseUrl: process.env.TSFORGE_JUDGE_URL ?? activeModel.baseUrl,
+        model: process.env.TSFORGE_JUDGE_MODEL ?? activeModel.model,
+        apiKey: process.env.TSFORGE_JUDGE_KEY ?? resolveApiKey(activeModel),
+      }
+    : providerConfig(activeModel)
+);
 
 /** Sortable timestamp `YYYYMMDD-HHMMSS` so run dirs sort newest-last by name. */
 function stamp(): string {

package/scripts/web-sweep.ts

@@ -0,0 +1,292 @@
+// A/B sweep over the REAL thing: full web-app builds from the benchmark catalog,
+// not toy logic seeds. Orchestrates headless-build.ts as a subprocess per
+// (feature-variant x repeat), toggling features via env (TSFORGE_TTSR etc.),
+// then aggregates pass-rate + turns into the same statistical report the logic
+// sweep uses (Wilson intervals + two-proportion z-test vs a baseline variant).
+//
+// Each build is a from-scratch multi-entity app (up to webMaxTurns turns, large
+// token spend), so this is GATED: it prints the plan and exits unless
+// TSFORGE_WEB_CONFIRM=1 is set — a real run can cost hours and significant API
+// credits on a cloud flagship.
+//
+// Run (dry-run plan):  TSFORGE_WEB_APP=saas-crm bun run packages/core/scripts/web-sweep.ts
+// Run (for real):      TSFORGE_WEB_APP=saas-crm TSFORGE_FEATURE_VARIANTS=ttsr \
+//                        TSFORGE_WEB_REPEATS=2 TSFORGE_WEB_CONFIRM=1 \
+//                        bun run packages/core/scripts/web-sweep.ts [react|vanilla]
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { resolveActiveModel } from "../src/models-config";
+import { LOOP_LIMITS } from "../src/loop";
+import {
+  buildSweepReport,
+  renderSweepReportMarkdown,
+  type IRunRecord,
+} from "../src/eval";
+import { BENCHMARK_CATALOG, findBenchmarkApp } from "./benchmark-catalog";
+
+/** A feature variant: dimension name -> "1" (on) | "0" (off). */
+type IFeatureVariant = Record<string, string>;
+
+/** The env var each known feature dimension toggles (mirrors sweep.ts so a web
+ *  A/B reads the same flags the logic A/B does). */
+const DIMENSION_ENV: Record<string, string> = {
+  ttsr: "TSFORGE_TTSR",
+  hashline: "TSFORGE_HASHLINE",
+  lsp_write_feedback: "TSFORGE_LSP_WRITE_FEEDBACK",
+};
+
+/** Parse `TSFORGE_FEATURE_VARIANTS` ("ttsr,hashline") into the cartesian product
+ *  of on/off per dimension. Empty -> a single unnamed baseline variant. */
+function parseVariants(spec: string): IFeatureVariant[] {
+  const dims = spec
+    .split(",")
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+
+  let combos: IFeatureVariant[] = [{}];
+
+  for (const dim of dims) {
+    const next: IFeatureVariant[] = [];
+
+    for (const combo of combos) {
+      next.push({ ...combo, [dim]: "1" }, { ...combo, [dim]: "0" });
+    }
+
+    combos = next;
+  }
+
+  return combos;
+}
+
+/** The env overrides that realize a variant (only known dimensions are mapped). */
+function variantEnv(variant: IFeatureVariant): Record<string, string> {
+  const env: Record<string, string> = {};
+
+  for (const [dim, state] of Object.entries(variant)) {
+    const key = DIMENSION_ENV[dim];
+
+    if (key !== undefined) {
+      env[key] = state === "1" ? "1" : "0";
+    }
+  }
+
+  return env;
+}
+
+/** A stable label like "ttsr=on,hashline=off"; "baseline" when no dimensions. */
+function variantLabel(variant: IFeatureVariant): string {
+  const parts = Object.entries(variant)
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([dim, state]) => `${dim}=${state === "1" ? "on" : "off"}`);
+
+  return parts.length > 0 ? parts.join(",") : "baseline";
+}
+
+/** The baseline label to compare against: the all-off variant when there are
+ *  dimensions (so deltas read as "the feature ON vs OFF"), else "baseline". */
+function baselineLabel(variants: IFeatureVariant[]): string {
+  const allOff = variants.find((v) =>
+    Object.values(v).every((state) => state === "0")
+  );
+
+  return allOff === undefined ? "baseline" : variantLabel(allOff);
+}
+
+interface ISweepConfig {
+  readonly slug: string;
+  readonly framework: string;
+  readonly variants: IFeatureVariant[];
+  readonly repeats: number;
+}
+
+/** Sortable timestamp `YYYYMMDD-HHMMSS`. */
+function stamp(): string {
+  const d = new Date();
+  const p = (n: number): string => String(n).padStart(2, "0");
+
+  return `${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}-${p(d.getHours())}${p(d.getMinutes())}${p(d.getSeconds())}`;
+}
+
+const EVALS_ROOT = join(import.meta.dir, "..", "..", "..", "evals");
+const HEADLESS = join(import.meta.dir, "headless-build.ts");
+
+/** Stream a child's stdout to our terminal while keeping a small tail buffer so
+ *  we can parse its final `[status · N turn(s)]` summary line. */
+async function teeStdout(stream: ReadableStream<Uint8Array>): Promise<string> {
+  const reader = stream.getReader();
+  const decoder = new TextDecoder();
+  let tail = "";
+
+  for (;;) {
+    const chunk = await reader.read();
+
+    if (chunk.done) {
+      break;
+    }
+
+    const text = decoder.decode(chunk.value);
+
+    process.stdout.write(text);
+    tail = `${tail}${text}`.slice(-4096);
+  }
+
+  return tail;
+}
+
+interface IBuildOutcome {
+  readonly passed: boolean;
+  readonly turns: number;
+  readonly ms: number;
+}
+
+/** Run ONE headless web build in its own dir with the variant's feature env. */
+async function runOneBuild(
+  config: ISweepConfig,
+  variant: IFeatureVariant,
+  dir: string
+): Promise<IBuildOutcome> {
+  const started = performance.now();
+  const proc = Bun.spawn(
+    ["bun", HEADLESS, "--app", config.slug, config.framework, dir],
+    {
+      env: { ...process.env, ...variantEnv(variant) },
+      stdout: "pipe",
+      stderr: "inherit",
+    }
+  );
+  const tail = await teeStdout(proc.stdout);
+  const code = await proc.exited;
+  const ms = performance.now() - started;
+  const match = /\[\w+ · (\d+) turn/.exec(tail);
+
+  return {
+    passed: code === 0,
+    turns: match?.[1] === undefined ? 0 : Number(match[1]),
+    ms,
+  };
+}
+
+/** Print the run plan and the cost warning. Returns the total build count. */
+function printPlan(config: ISweepConfig, model: string): number {
+  const total = config.variants.length * config.repeats;
+
+  process.stdout.write(
+    `\nWEB A/B SWEEP — the real thing (full app builds)\n` +
+      `  app:       ${config.slug} (${config.framework})\n` +
+      `  model:     ${model}\n` +
+      `  variants:  ${config.variants.map(variantLabel).join(", ")}\n` +
+      `  repeats:   ${config.repeats}\n` +
+      `  builds:    ${total} total\n\n` +
+      `Each build is a from-scratch multi-entity app: up to ` +
+      `${LOOP_LIMITS.webMaxTurns} model turns, vite build + browser render gate, ` +
+      `large token spend. ${total} of them runs SEQUENTIALLY and can take hours ` +
+      `and significant API credits on a cloud flagship.\n`
+  );
+
+  return total;
+}
+
+/** Run the full sweep, returning one record per build for aggregation. */
+async function runSweep(
+  config: ISweepConfig,
+  runDir: string
+): Promise<IRunRecord[]> {
+  const records: IRunRecord[] = [];
+  let index = 0;
+  const total = config.variants.length * config.repeats;
+
+  for (const variant of config.variants) {
+    const label = variantLabel(variant);
+
+    for (let repeat = 1; repeat <= config.repeats; repeat += 1) {
+      index += 1;
+      const dir = join(runDir, `${label}-${String(repeat)}`);
+
+      mkdirSync(dir, { recursive: true });
+      process.stdout.write(
+        `\n=== build ${String(index)}/${String(total)}: ${config.slug} ${label} #${String(repeat)} ===\n`
+      );
+
+      const outcome = await runOneBuild(config, variant, dir);
+
+      records.push({
+        label,
+        passed: outcome.passed,
+        cycles: outcome.turns,
+        ms: outcome.ms,
+      });
+      process.stdout.write(
+        `  -> ${outcome.passed ? "PASS" : "FAIL"} (${String(outcome.turns)} turns, ${(outcome.ms / 1000).toFixed(0)}s)\n`
+      );
+    }
+  }
+
+  return records;
+}
+
+/** Resolve the sweep config from env/argv, or print the catalog and exit. */
+function resolveConfig(): ISweepConfig | undefined {
+  const slug = process.env.TSFORGE_WEB_APP ?? "";
+  const app = findBenchmarkApp(slug);
+
+  if (app === undefined) {
+    const list = BENCHMARK_CATALOG.map(
+      (a, i) => `  ${String(i + 1)}. ${a.slug} — ${a.name}`
+    ).join("\n");
+
+    process.stderr.write(
+      `set TSFORGE_WEB_APP to a benchmark slug. catalog:\n${list}\n`
+    );
+
+    return undefined;
+  }
+
+  const framework = process.argv[2] === "vanilla" ? "vanilla" : "react";
+  const variants = parseVariants(process.env.TSFORGE_FEATURE_VARIANTS ?? "");
+  const repeats = Math.max(1, Number(process.env.TSFORGE_WEB_REPEATS ?? "1"));
+
+  return { slug: app.slug, framework, variants, repeats };
+}
+
+async function main(): Promise<void> {
+  const config = resolveConfig();
+
+  if (config === undefined) {
+    process.exit(2);
+  }
+
+  const { entry } = await resolveActiveModel();
+
+  printPlan(config, entry.model);
+
+  if (process.env.TSFORGE_WEB_CONFIRM !== "1") {
+    process.stdout.write(
+      `\nDRY RUN — set TSFORGE_WEB_CONFIRM=1 to actually run these builds.\n`
+    );
+    process.exit(0);
+  }
+
+  const runDir = join(
+    EVALS_ROOT,
+    "runs",
+    `web-sweep-${config.slug}-${stamp()}`
+  );
+
+  mkdirSync(runDir, { recursive: true });
+
+  const records = await runSweep(config, runDir);
+  const report = buildSweepReport(records, baselineLabel(config.variants));
+  const markdown = renderSweepReportMarkdown(report);
+
+  process.stdout.write(`\n${markdown}\n`);
+
+  const reportPath = join(runDir, "report.json");
+
+  writeFileSync(
+    reportPath,
+    `${JSON.stringify({ config, records, report }, null, 2)}\n`
+  );
+  process.stdout.write(`\nsaved ${reportPath}\n`);
+}
+
+await main();

package/src/browser/oracle.ts

@@ -1,5 +1,18 @@
 import { resolve, dirname, basename, join } from "node:path";
-import { chromium, type Page } from "playwright";
+// `playwright` is an OPTIONAL peer: bundling it (+ a browser binary) into every
+// install is too heavy, so the import is dynamic and the render-check skips when
+// it's absent. The type-only import is erased at runtime, so it can't crash a
+// playwright-less install.
+import type { Page, chromium as Chromium } from "playwright";
+
+/** Load playwright's chromium lazily; null when it isn't installed. */
+async function loadChromium(): Promise<typeof Chromium | null> {
+  try {
+    return (await import("playwright")).chromium;
+  } catch {
+    return null;
+  }
+}
 
 /**
  * The browser oracle — renders a built web page in headless chromium and reports
@@ -50,12 +63,27 @@ export interface IRenderResult {
   ok: boolean;
   /** Human-readable failures (console errors, page errors, missing content). */
   errors: string[];
+  /** True when the check was skipped because playwright isn't installed. */
+  skipped?: boolean;
 }
 
 export async function renderCheck(
   opts: IRenderOptions
 ): Promise<IRenderResult> {
   const errors: string[] = [];
+  const chromium = await loadChromium();
+
+  // No playwright → skip the render check rather than fail the gate. The build
+  // still ran tsc/eslint/build/stub-check; the browser smoke is an enhancement.
+  if (chromium === null) {
+    process.stderr.write(
+      "browser render-check skipped: playwright not installed " +
+        "(run `bunx playwright install chromium` to enable it)\n"
+    );
+
+    return { ok: true, errors: [], skipped: true };
+  }
+
   const browser = await chromium.launch({ args: ["--no-sandbox"] });
 
   try {

package/src/cli.ts

@@ -795,18 +795,24 @@ async function baseGate(
   }
 
   const { detectStack } = await import("./stack-detection");
-  const { loadTsforgeConfig, resolveActivePacks, normalizeRuleOverrides } =
-    await import("./config/tsforge-config");
+  const {
+    loadTsforgeConfig,
+    resolveActivePacks,
+    normalizeRuleOverrides,
+    resolveProjectProfile,
+  } = await import("./config/tsforge-config");
 
   const stackProfile = await detectStack(args.dir);
   const config = await loadTsforgeConfig(args.dir);
   const activePacks = resolveActivePacks(stackProfile.packs, config);
   const ruleOverrides = normalizeRuleOverrides(config);
+  const profile = resolveProjectProfile(config);
 
   const auto = await buildGate(
     args.dir,
     activePacks,
-    Object.keys(ruleOverrides).length > 0 ? ruleOverrides : undefined
+    Object.keys(ruleOverrides).length > 0 ? ruleOverrides : undefined,
+    { enableTypeAware: profile === "strict" }
   );
 
   return { accept: auto.command, gateLabel: auto.label };

package/src/config/index.ts

@@ -4,5 +4,13 @@ export {
   loadTsforgeConfig,
   resolveActivePacks,
   normalizeRuleOverrides,
+  resolveProjectProfile,
   type ITsforgeProjectConfig,
 } from "./tsforge-config";
+export {
+  PROFILE_DEFINITIONS,
+  DEFAULT_PROFILE,
+  isProfileId,
+  resolveProfileMetaRuleOverrides,
+  type ProfileId,
+} from "./profiles";