@agjs/tsforge 0.4.0 → 0.5.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@agjs/tsforge",
   "type": "module",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "license": "MIT",
   "description": "TypeScript coding harness with a deterministic gate, stack-aware guardrails, and stream-level correction.",
   "repository": {

package/scripts/boot-check.ts

@@ -0,0 +1,106 @@
+// Gate-runnable BOOT oracle: actually start the built server and confirm it comes
+// up and answers a request without a 5xx. This is "does it RUN", a class of
+// failure tsc/eslint/unit-tests never catch — a server that throws on boot
+// (bad env wiring, a port clash, a top-level await that rejects) still type-checks
+// and lints clean. Mirrors the web browser smoke, for backends.
+//
+// OPT-IN: wired into the gate only when TSFORGE_BOOT is set to the start command
+// (e.g. `TSFORGE_BOOT="bun run start"`). TSFORGE_BOOT_URL (default
+// http://localhost:3000/) and TSFORGE_BOOT_TIMEOUT (ms, default 15000) tune it.
+//
+//   TSFORGE_BOOT="bun run start" TSFORGE_BOOT_URL=http://localhost:3000/health bun boot-check.ts
+
+export interface IBootConfig {
+  readonly command: string;
+  readonly url: string;
+  readonly timeoutMs: number;
+}
+
+/** Read the boot config from env; null when TSFORGE_BOOT is not set. */
+export function bootConfig(
+  env: Record<string, string | undefined>
+): IBootConfig | null {
+  const command = env.TSFORGE_BOOT;
+
+  if (command === undefined || command.trim().length === 0) {
+    return null;
+  }
+
+  const timeoutRaw = Number(env.TSFORGE_BOOT_TIMEOUT);
+
+  return {
+    command,
+    url: env.TSFORGE_BOOT_URL ?? "http://localhost:3000/",
+    timeoutMs:
+      Number.isFinite(timeoutRaw) && timeoutRaw > 0 ? timeoutRaw : 15000,
+  };
+}
+
+/** Poll `url` until it answers with status < 500, or the deadline passes.
+ *  Returns the status code on success, or null on timeout. */
+export async function pollUntilReady(
+  url: string,
+  timeoutMs: number,
+  now: () => number = () => performance.now(),
+  sleep: (ms: number) => Promise<void> = (ms) =>
+    new Promise((r) => setTimeout(r, ms))
+): Promise<number | null> {
+  const deadline = now() + timeoutMs;
+
+  while (now() < deadline) {
+    try {
+      const res = await fetch(url, { signal: AbortSignal.timeout(2000) });
+
+      if (res.status < 500) {
+        return res.status;
+      }
+    } catch {
+      // not up yet
+    }
+
+    await sleep(250);
+  }
+
+  return null;
+}
+
+async function main(): Promise<number> {
+  const cfg = bootConfig(process.env);
+
+  if (cfg === null) {
+    return 0; // not configured — nothing to do
+  }
+
+  const child = Bun.spawn(["sh", "-c", cfg.command], {
+    cwd: process.cwd(),
+    stdout: "pipe",
+    stderr: "pipe",
+    env: process.env,
+  });
+
+  try {
+    const status = await pollUntilReady(cfg.url, cfg.timeoutMs);
+
+    if (status === null) {
+      const err = await new Response(child.stderr).text();
+
+      process.stderr.write(
+        `boot-check: server did not answer ${cfg.url} within ${cfg.timeoutMs}ms (or only returned 5xx). It must boot and serve a non-5xx response.\n${err.slice(0, 800)}\n`
+      );
+
+      return 1;
+    }
+
+    process.stdout.write(
+      `boot-check: server answered ${cfg.url} with ${status}. OK\n`
+    );
+
+    return 0;
+  } finally {
+    child.kill();
+  }
+}
+
+if (import.meta.main) {
+  process.exit(await main());
+}

package/scripts/build-rule-docs.ts

@@ -98,10 +98,13 @@ for (const pack of Object.values(RULE_PACKS)) {
     const ruleId = `tsforge/${ruleName}`;
     const description = getRuleDescription(ruleModule) ?? ruleName;
 
+    // No fake placeholders: leave bad/good empty so the feedback renderer shows
+    // just the description. Real worked examples come from curated RULE_DOCS,
+    // which take precedence over this generated cache.
     out[ruleId] = {
       what: description,
-      bad: `// Example that violates the rule`,
-      good: `// Corrected version`,
+      bad: "",
+      good: "",
     };
 
     packRulesAdded += 1;

package/scripts/test-coverage-check.ts

@@ -0,0 +1,138 @@
+// Gate-runnable TEST-COVERAGE oracle: run the project's tests with lcov coverage
+// and fail if line coverage falls below a floor. Proves the tests don't just
+// *pass* but actually *exercise* the code — closing the "added code, added no
+// test" gap (a test suite can be green and assert almost nothing).
+//
+// OPT-IN: only wired into the gate when TSFORGE_COVERAGE is set (a percent, e.g.
+// `TSFORGE_COVERAGE=80`). Skips cleanly (exit 0) when the project has no tests or
+// the coverage report can't be produced — it never blocks a project that simply
+// has nothing to measure yet.
+//
+//   TSFORGE_COVERAGE=80 bun test-coverage-check.ts
+import { mkdtempSync, rmSync, existsSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+export interface ICoverage {
+  readonly lineFound: number; // LF
+  readonly lineHit: number; // LH
+  readonly funcFound: number; // FNF
+  readonly funcHit: number; // FNH
+  readonly linePct: number; // 0..100
+  readonly funcPct: number; // 0..100
+  /** The weaker of line/function coverage — the floor is checked against this so
+   *  an uncovered FUNCTION can't hide behind line counts (bun marks a one-line
+   *  arrow's declaration line "hit" even when the function is never called). */
+  readonly pct: number;
+}
+
+function sumPrefixed(text: string, prefix: string): number {
+  let total = 0;
+
+  for (const line of text.split("\n")) {
+    if (line.startsWith(prefix)) {
+      const n = Number(line.slice(prefix.length).trim());
+
+      total += Number.isNaN(n) ? 0 : n;
+    }
+  }
+
+  return total;
+}
+
+/** Sum line (LF/LH) and function (FNF/FNH) coverage across an lcov.info report. */
+export function parseLcovCoverage(text: string): ICoverage {
+  const lineFound = sumPrefixed(text, "LF:");
+  const lineHit = sumPrefixed(text, "LH:");
+  const funcFound = sumPrefixed(text, "FNF:");
+  const funcHit = sumPrefixed(text, "FNH:");
+  const linePct = lineFound === 0 ? 100 : (lineHit / lineFound) * 100;
+  const funcPct = funcFound === 0 ? 100 : (funcHit / funcFound) * 100;
+
+  return {
+    lineFound,
+    lineHit,
+    funcFound,
+    funcHit,
+    linePct,
+    funcPct,
+    pct: Math.min(linePct, funcPct),
+  };
+}
+
+/** The configured floor: TSFORGE_COVERAGE as a percent, default 80 when set
+ *  truthy-but-not-a-useful-number (e.g. `=1`). */
+export function coverageFloor(raw: string | undefined): number {
+  if (raw === undefined) {
+    return 80;
+  }
+
+  const n = Number(raw);
+
+  return Number.isFinite(n) && n > 1 && n <= 100 ? n : 80;
+}
+
+async function main(): Promise<number> {
+  const floor = coverageFloor(process.env.TSFORGE_COVERAGE);
+  const covDir = mkdtempSync(join(tmpdir(), "tsforge-cov-"));
+
+  try {
+    const proc = Bun.spawn(
+      [
+        "bun",
+        "test",
+        "--coverage",
+        "--coverage-reporter=lcov",
+        `--coverage-dir=${covDir}`,
+      ],
+      { cwd: process.cwd(), stdout: "pipe", stderr: "pipe" }
+    );
+
+    await proc.exited;
+
+    const lcovPath = join(covDir, "lcov.info");
+
+    if (!existsSync(lcovPath)) {
+      process.stdout.write(
+        "test-coverage-check: no lcov report produced (no tests?) — skipping.\n"
+      );
+
+      return 0;
+    }
+
+    const cov = parseLcovCoverage(readFileSync(lcovPath, "utf8"));
+
+    if (cov.lineFound === 0 && cov.funcFound === 0) {
+      process.stdout.write(
+        "test-coverage-check: nothing instrumented — skipping.\n"
+      );
+
+      return 0;
+    }
+
+    const pct = cov.pct.toFixed(1);
+
+    if (cov.pct + 1e-9 < floor) {
+      process.stderr.write(
+        `test-coverage-check: coverage ${pct}% is below the ${floor}% floor ` +
+          `(lines ${cov.lineHit}/${cov.lineFound}, functions ${cov.funcHit}/${cov.funcFound}). ` +
+          `Add tests that actually call the uncovered code.\n`
+      );
+
+      return 1;
+    }
+
+    process.stdout.write(
+      `test-coverage-check: ${pct}% >= ${floor}% floor ` +
+        `(lines ${cov.lineHit}/${cov.lineFound}, functions ${cov.funcHit}/${cov.funcFound}). OK\n`
+    );
+
+    return 0;
+  } finally {
+    rmSync(covDir, { recursive: true, force: true });
+  }
+}
+
+if (import.meta.main) {
+  process.exit(await main());
+}

package/src/detect-gate.ts

@@ -77,6 +77,13 @@ const BROWSER_CHECK = join(
 );
 
 const STUB_CHECK = join(import.meta.dir, "..", "scripts", "stub-check.ts");
+const TEST_COVERAGE_CHECK = join(
+  import.meta.dir,
+  "..",
+  "scripts",
+  "test-coverage-check.ts"
+);
+const BOOT_CHECK = join(import.meta.dir, "..", "scripts", "boot-check.ts");
 
 // The strict tsconfig tsforge brings to a greenfield project — strict + the
 // index-safety the local model is weakest at, with DOM + JSX libs so browser /
@@ -677,9 +684,34 @@ export async function buildGate(
     }
   }
 
+  appendOptInOracles(parts, labels, process.env);
+
   return { command: parts.join(" && "), label: labels.join(" + ") };
 }
 
+/**
+ * Opt-in quality oracles (default OFF, mirroring the web a11y/screenshot flags).
+ * They run AFTER tests and read their own config from env, so the gate command
+ * stays free of shell-quoting:
+ *   - TSFORGE_COVERAGE=<pct> — fail if line coverage is below the floor.
+ *   - TSFORGE_BOOT="<start cmd>" — boot the server and require a non-5xx response.
+ */
+function appendOptInOracles(
+  parts: string[],
+  labels: string[],
+  env: Record<string, string | undefined>
+): void {
+  if (env.TSFORGE_COVERAGE !== undefined && env.TSFORGE_COVERAGE.length > 0) {
+    parts.push(`bun "${TEST_COVERAGE_CHECK}"`);
+    labels.push("test coverage");
+  }
+
+  if (env.TSFORGE_BOOT !== undefined && env.TSFORGE_BOOT.trim().length > 0) {
+    parts.push(`bun "${BOOT_CHECK}"`);
+    labels.push("boot smoke");
+  }
+}
+
 /** 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;

package/src/loop/feedback/meta-rule-docs.ts

@@ -32,6 +32,12 @@ export const META_RULE_DOCS: Record<string, string> = {
   "production-must-not-use-drizzle-push":
     "Replace `drizzle-kit push` in scripts and CI with checked-in SQL migrations and `drizzle-kit migrate`.",
 
+  "no-undeclared-dependencies":
+    "Add the imported package to package.json (dependencies or devDependencies) — relying on a hoisted/transitive copy breaks on a clean install.",
+
+  "no-circular-imports":
+    "Break the import cycle by extracting the shared code both modules need into a third module they each import (one-way edges only).",
+
   "migrations-must-be-checked-in":
     "Add a drizzle/ or migrations/ folder with generated SQL migration files when using Drizzle ORM.",
 

package/src/loop/feedback/rule-docs.ts

@@ -25,6 +25,39 @@ const GENERATED: Record<string, IRuleDoc> = generatedJson;
  * failure beats making the model re-derive the fix from scratch.
  */
 const RULE_DOCS: Record<string, IRuleDoc> = {
+  // --- Type-aware: implicit-`any` containment (no `any` token to see) ---
+  // (no-unsafe-assignment / -member-access / -return are curated further below)
+  "@typescript-eslint/no-unsafe-call": {
+    what: "Calling an `any`-typed value. Type the callee so the call is checked.",
+    bad: "const fn = lib.run; fn(); // lib is any",
+    good: "const fn: () => void = lib.run; fn();",
+  },
+  "@typescript-eslint/no-unsafe-argument": {
+    what: "Passing an `any` into a typed parameter. Validate/narrow before the call.",
+    bad: "save(JSON.parse(body));",
+    good: "save(UserSchema.parse(JSON.parse(body)));",
+  },
+  "sonarjs/cognitive-complexity": {
+    what: "Function is too tangled (cognitive complexity > 20). Extract named helper functions for the inner branches/loops — don't suppress.",
+    bad: "function handle(x) { /* many nested if/for/switch in one body */ }",
+    good: "function handle(x) { return isA(x) ? doA(x) : doB(x); } // branches extracted",
+  },
+  // --- AI-SDK pack ---
+  "tsforge/no-api-key-in-client": {
+    what: "An AI provider client constructed in a `'use client'` file ships the API key to the browser. Call the model from a server route/action.",
+    bad: "'use client';\nconst client = new OpenAI({ apiKey: process.env.KEY });",
+    good: "// server action / route handler:\nconst client = new OpenAI({ apiKey: process.env.KEY });",
+  },
+  "tsforge/require-completion-token-limit": {
+    what: "AI completion calls must bound output tokens to cap cost/latency.",
+    bad: "await generateText({ model, prompt });",
+    good: "await generateText({ model, prompt, maxTokens: 512 });",
+  },
+  "tsforge/no-user-input-in-system-prompt": {
+    what: "Don't splice request/user data into the system prompt (injection). Keep the system prompt constant; pass user input as a user message.",
+    bad: "generateText({ system: `You are ${role}`, prompt });",
+    good: "generateText({ system: SYSTEM_PROMPT, messages: [{ role: 'user', content: userInput }] });",
+  },
   TS2532: {
     what: "Indexed access is `T | undefined` (noUncheckedIndexedAccess). Bind and guard before use; never `!`.",
     bad: "total += arr[i];",
@@ -416,7 +449,17 @@ export function ruleHelp(errors: ErrorSet): string {
     }
 
     seen.add(e.rule);
-    blocks.push(`${e.rule}: ${doc.what}\n  ✗ ${doc.bad}\n  ✓ ${doc.good}`);
+
+    // Only show the ✗/✓ pair when there is a REAL worked example. Generated-only
+    // entries (pack rules without a curated example) carry just `what` — a fake
+    // "// Example that violates the rule" placeholder is worse than nothing.
+    const hasExample = doc.bad.length > 0 && doc.good.length > 0;
+
+    blocks.push(
+      hasExample
+        ? `${e.rule}: ${doc.what}\n  ✗ ${doc.bad}\n  ✓ ${doc.good}`
+        : `${e.rule}: ${doc.what}`
+    );
   }
 
   return blocks.join("\n");