@agjs/tsforge 0.2.6 → 0.2.8

package/src/loop/rule-docs.generated.json

@@ -109,6 +109,21 @@
     "bad": "[1, 2, 3].reduce((arr, num) => arr.concat(num * 2), [] as number[]);\n\n['a', 'b'].reduce(\n  (accumulator, name) => ({\n    ...accumulator,\n    [name]: true,\n  }),\n  {} as Record<string, boolean>,",
     "good": "[1, 2, 3].reduce<number[]>((arr, num) => arr.concat(num * 2), []);\n\n['a', 'b'].reduce<Record<string, boolean>>(\n  (accumulator, name) => ({\n    ...accumulator,\n    [name]: true,\n  }),\n  {},"
   },
+  "tsforge/id-param-requires-object-authz": {
+    "what": "Warn when a handler reads `params.id` and queries the database without an authorization check in the same function.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
+  "tsforge/mutating-route-requires-authz": {
+    "what": "POST/PUT/PATCH/DELETE route handlers must call an authorization helper before mutating state.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
+  "tsforge/server-action-requires-authz": {
+    "what": "Files with `\"use server\"` that perform database mutations must call an authorization helper in the same function.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
   "tsforge/job-name-must-be-constant": {
     "what": "Disallow string-literal job names in `<queue>.add(name, ...)` calls — use a constant identifier so all consumers share one source of truth.",
     "bad": "// Example that violates the rule",
@@ -219,6 +234,16 @@
     "bad": "// Example that violates the rule",
     "good": "// Corrected version"
   },
+  "tsforge/update-delete-account-scoped-must-filter-scope": {
+    "what": "Require Drizzle `.update()` / `.delete()` against account-scoped tables to filter by a scope column in `.where()`.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
+  "tsforge/update-delete-must-have-where": {
+    "what": "Require every Drizzle `.update()` and `.delete()` call to include a `.where()` clause — unscoped writes affect every row.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
   "tsforge/consistent-status-via-set": {
     "what": "Inside Elysia route handlers, set HTTP status via `set.status = N`, not by returning a `new Response(body, { status: N })`.",
     "bad": "// Example that violates the rule",
@@ -319,11 +344,26 @@
     "bad": "// Example that violates the rule",
     "good": "// Corrected version"
   },
+  "tsforge/auth-cookie-must-set-maxage-or-expires": {
+    "what": "Auth-cookie writes should set `maxAge` or `expires` so session cookies do not live forever by default.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
+  "tsforge/auth-cookie-must-set-samesite": {
+    "what": "Auth-cookie writes must set `sameSite` (`strict` or `lax`) — missing SameSite allows cross-site cookie delivery.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
   "tsforge/bcrypt-rounds-min": {
     "what": "Disallow `bcrypt.hash` / `bcrypt.hashSync` calls with a numeric-literal rounds value below the configured minimum (default 10).",
     "bad": "// Example that violates the rule",
     "good": "// Corrected version"
   },
+  "tsforge/jwt-must-verify-not-decode": {
+    "what": "Disallow `jwt.decode` / `decodeJwt` — decoding without verification accepts forged tokens. Use `jwt.verify` or `jwtVerify` instead.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
   "tsforge/no-import-build-output": {
     "what": "Disallow importing from build/output directories within the project. Source must import source, not compiled artifacts, to avoid stale-code drift and broken module boundaries.",
     "bad": "// Example that violates the rule",
@@ -354,6 +394,11 @@
     "bad": "// Example that violates the rule",
     "good": "// Corrected version"
   },
+  "tsforge/mutation-should-revalidate-cache": {
+    "what": "After database mutations in server actions or route handlers, call `revalidatePath` or `revalidateTag` so cached pages reflect the change.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
   "tsforge/no-html-img-element": {
     "what": "Prefer next/image over raw <img> elements for optimized responsive images and Core Web Vitals.",
     "bad": "// Example that violates the rule",
@@ -374,6 +419,11 @@
     "bad": "// Example that violates the rule",
     "good": "// Corrected version"
   },
+  "tsforge/no-secret-props-to-client": {
+    "what": "Warn when Server Components pass secret-looking props to JSX — values may cross the client boundary.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
   "tsforge/no-sensitive-next-public-env": {
     "what": "Disallow NEXT_PUBLIC_* env vars whose names suggest secrets — public build-time vars are visible in the client bundle.",
     "bad": "// Example that violates the rule",
@@ -384,6 +434,16 @@
     "bad": "// Example that violates the rule",
     "good": "// Corrected version"
   },
+  "tsforge/server-action-requires-authz-and-validation": {
+    "what": "Server actions (`\"use server\"`) that mutate the database must call authorization helpers and validate input with `.parse()` / `.safeParse()`.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
+  "tsforge/server-only-modules-import-server-only": {
+    "what": "App-router server modules must import `\"server-only\"` so accidental client bundling fails at build time.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
   "tsforge/pkce-required-for-oidc": {
     "what": "OIDC providers must use PKCE: `buildAuthorizationURL` must call `generateCodeVerifier()` and pass it to `createAuthorizationURL`.",
     "bad": "// Example that violates the rule",
@@ -399,8 +459,13 @@
     "bad": "// Example that violates the rule",
     "good": "// Corrected version"
   },
+  "tsforge/component-file-purity": {
+    "what": "A component .tsx contains only imports and the component itself — types go to <feature>.types.ts, constants to <feature>.constants.ts, helpers to src/lib",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
   "tsforge/component-folder-structure": {
-    "what": "Enforce required sibling files in component folders (hooks, types, stories, test, index)",
+    "what": "A component .tsx must live in src/views/<Feature>/components/ (feature component), src/components/ui/ (shared primitive), or be the view root src/views/<Feature>/index.tsx",
     "bad": "// Example that violates the rule",
     "good": "// Corrected version"
   },
@@ -469,6 +534,31 @@
     "bad": "// Example that violates the rule",
     "good": "// Corrected version"
   },
+  "tsforge/no-prototype-polluting-merge": {
+    "what": "Disallow merging request body/query/params into objects — enables prototype pollution.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
+  "tsforge/no-user-controlled-fetch-url": {
+    "what": "Disallow fetch/axios requests to non-literal URLs — dynamic URLs enable SSRF.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
+  "tsforge/no-user-controlled-redirect": {
+    "what": "Disallow redirects to non-literal URLs — user-controlled redirects enable open redirects.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
+  "tsforge/upload-must-set-limits": {
+    "what": "Multipart upload handlers should declare `limits` or `maxFileSize` to bound request size.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
+  "tsforge/webhook-must-verify-signature-before-parse": {
+    "what": "Webhook handlers must verify signatures before calling `.json()` on the request body.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
   "tsforge/catch-must-handle": {
     "what": "Catch blocks must log, rethrow, or propagate errors — not silently return empty defaults on failure.",
     "bad": "// Example that violates the rule",
@@ -499,6 +589,16 @@
     "bad": "// Example that violates the rule",
     "good": "// Corrected version"
   },
+  "tsforge/caught-error-log-requires-cause": {
+    "what": "When logging a caught error, include a `cause` field in the structured payload so downstream tools preserve the error chain.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
+  "tsforge/logger-not-console": {
+    "what": "Service modules should use the structured logger instead of `console.*` — console output is unstructured and hard to search.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
   "tsforge/mask-pii-fields": {
     "what": "Disallow unmasked PII (email, phone, password, token, ...) in structured-logger payloads — the #1 way data leaks quietly.",
     "bad": "// Example that violates the rule",
@@ -519,14 +619,49 @@
     "bad": "// Example that violates the rule",
     "good": "// Corrected version"
   },
+  "tsforge/fake-timers-must-be-restored": {
+    "what": "When a test file calls `useFakeTimers()`, it must also call `useRealTimers()` so later tests are not affected.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
+  "tsforge/no-conditional-expect": {
+    "what": "Disallow `expect()` inside conditionals — tests must fail when assertions are skipped.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
   "tsforge/no-focused-tests": {
     "what": "Disallow focused tests (`test.only`, `it.only`, `fdescribe`, ...) — the canonical 'I forgot to remove this before committing' leak.",
     "bad": "// Example that violates the rule",
     "good": "// Corrected version"
   },
+  "tsforge/no-real-network-in-unit-tests": {
+    "what": "Unit tests should not perform real network I/O — mock HTTP clients or move the test to an integration suite.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
   "tsforge/test-file-mirrors-source": {
     "what": "Every test file under `tests/` must mirror a source file under `src/`. Catches orphaned tests left behind after refactors and renames.",
     "bad": "// Example that violates the rule",
     "good": "// Corrected version"
+  },
+  "tsforge/exported-functions-require-return-type": {
+    "what": "Exported functions should declare an explicit return type at module boundaries.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
+  "tsforge/fetch-must-check-ok": {
+    "what": "HTTP fetch responses must check `.ok` or status before calling `.json()`.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
+  "tsforge/json-parse-must-validate": {
+    "what": "Disallow bare JSON.parse on untrusted input — validate through a schema library.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
+  "tsforge/no-unsafe-boundary-cast": {
+    "what": "Disallow type assertions immediately after parsing untrusted boundary input.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
   }
 }

package/src/loop/run.ts

@@ -1,16 +1,25 @@
-import { join } from "node:path";
 import type { ITask } from "../spec";
 import type { IChatMessage, IModelResponse, IProvider } from "../inference";
 import { validate, type ErrorParser } from "../validate";
 import { parseEslintJson } from "../validate";
 import { readFiles } from "../lib/fs";
 import { RUN_STATUS, STUCK_REASON, LOOP_LIMITS } from "./loop.constants";
-import type { IRunResult, IRunOptions, Reporter } from "./loop.types";
+import type {
+  IRunResult,
+  IRunOptions,
+  Reporter,
+  ILoopEvent,
+} from "./loop.types";
+import { mineLessons, consolidate as consolidateMemory } from "./memory";
 import { flags } from "../config";
 import { SYSTEM, seedPrompt } from "./prompt";
 import { detectStack } from "../stack-detection";
-import { TtsrManager, parseProjectRules, type ITtsrRule } from "./ttsr";
-import { DEFAULT_TTSR_RULES } from "./ttsr-defaults";
+import type { TtsrManager } from "./ttsr";
+import {
+  initTtsrManager,
+  loadProjectTtsrRules,
+  applyTtsrInterrupt,
+} from "./ttsr-init";
 import {
   type ILoopCtx,
   type ILoopState,
@@ -66,57 +75,14 @@ function handleDegeneration(
   };
 }
 
-/** Read and parse `<cwd>/.tsforge/rules.json` if present. Missing or invalid
- *  files yield no rules (parseProjectRules tolerates malformed JSON). */
-export async function loadProjectTtsrRules(cwd: string): Promise<ITtsrRule[]> {
-  const file = Bun.file(join(cwd, ".tsforge", "rules.json"));
-
-  if (!(await file.exists())) {
-    return [];
-  }
+// TTSR init + project/learned-rule loading live in the shared ttsr-init module
+// (the interactive session uses the same loaders). Re-exported here so existing
+// importers (and tests) keep their path.
+export { initTtsrManager, loadProjectTtsrRules };
 
-  return parseProjectRules(await file.text());
-}
-
-/** Build and configure a TTSR manager if enabled. Returns null if disabled.
- *  Built-in defaults register first, then optional project rules from
- *  `<cwd>/.tsforge/rules.json`; `addRule` ignores duplicate names, so a
- *  built-in safety rule always wins over a same-named project rule. */
-export async function initTtsrManager(
-  cwd: string,
-  report: Reporter,
-  taskId: string
-): Promise<TtsrManager | null> {
-  if (!flags.ttsr()) {
-    return null;
-  }
-
-  const manager = new TtsrManager();
-
-  for (const rule of DEFAULT_TTSR_RULES) {
-    manager.addRule(rule);
-  }
-
-  let added = 0;
-
-  for (const rule of await loadProjectTtsrRules(cwd)) {
-    if (manager.addRule(rule)) {
-      added += 1;
-    }
-  }
-
-  if (added > 0) {
-    report({
-      kind: "ttsr",
-      task: taskId,
-      message: `loaded ${added} custom TTSR rule(s) from .tsforge/rules.json`,
-    });
-  }
-
-  return manager;
-}
-
-/** Handle a TTSR interrupt: report, inject corrective message, and optionally disable. */
+/** Handle a TTSR interrupt in the headless loop: apply the shared interrupt
+ *  (count, report, inject corrective guidance, disable at the cap) then emit
+ *  timing for the interrupted turn. */
 function handleTtsrInterrupt(
   ttsrFired: { ruleName: string; guidance: string },
   state: ILoopState,
@@ -128,32 +94,41 @@ function handleTtsrInterrupt(
   taskStart: number,
   ttsrManager: TtsrManager | null
 ): void {
-  state.ttsrInterrupts += 1;
-
-  report({
-    kind: "ttsr",
-    task: taskId,
-    message: `⚠ TTSR interrupted: ${ttsrFired.ruleName}`,
-  });
-
-  // Hard cap: after 3 interrupts, disable TTSR to prevent loops
-  if (state.ttsrInterrupts >= 3) {
-    report({
-      kind: "tool",
-      task: taskId,
-      message: `TTSR disabled after ${state.ttsrInterrupts} interrupts (hit cap)`,
-    });
+  applyTtsrInterrupt(ttsrFired, state, messages, report, taskId, ttsrManager);
+  emitTiming(report, taskId, turn, turnStart, taskStart);
+}
 
-    ttsrManager?.disable();
+/**
+ * MEMORY post-run hook: mine this run's events for failure→fix lessons and
+ * consolidate them into `.tsforge/`. Gated on the TTSR flag (learned rules are
+ * recalled via TTSR, so there's nothing to learn for if it's off). Best-effort:
+ * a memory failure never affects the run's result. `runId` is unique per run so
+ * the same task re-run counts as a distinct session for the recurrence gate.
+ */
+async function consolidateLessons(
+  cwd: string,
+  events: readonly ILoopEvent[],
+  runId: string,
+  report: Reporter
+): Promise<void> {
+  if (!flags.ttsr()) {
+    return;
   }
 
-  // Append corrective message and retry without counting as a normal cycle
-  messages.push({
-    role: "user",
-    content: `⚠ generation interrupted: ${ttsrFired.guidance} Rewrite the affected part without that pattern.`,
-  });
+  try {
+    const candidates = mineLessons(events);
+    const active = await consolidateMemory(cwd, candidates, runId);
 
-  emitTiming(report, taskId, turn, turnStart, taskStart);
+    if (active > 0) {
+      report({
+        kind: "ttsr",
+        task: runId,
+        message: `memory: ${String(active)} learned rule(s) active in .tsforge/learned-rules.json`,
+      });
+    }
+  } catch {
+    // Memory is supplementary — never let it break a run.
+  }
 }
 
 /** Assemble per-call completion options, leaving optional knobs unset when absent. */
@@ -242,7 +217,25 @@ export async function runTask(
   const effectiveParse = effectiveParserFor(parse);
   const temperature = opts.temperature ?? 0;
   const maxTurns = opts.maxTurns ?? LOOP_LIMITS.maxTurns;
-  const report: Reporter = opts.onEvent ?? (() => undefined);
+  // Buffer every event so the post-run memory hook can mine the run for
+  // failure→fix lessons, while still forwarding live to the real reporter.
+  const base: Reporter = opts.onEvent ?? (() => undefined);
+  const events: ILoopEvent[] = [];
+
+  const report: Reporter = (event) => {
+    events.push(event);
+    base(event);
+  };
+
+  // Unique per run, so re-running the same task counts as a distinct session for
+  // the lesson-recurrence gate.
+  const runId = `${task.id}-${Date.now().toString(36)}`;
+
+  const finish = async (result: IRunResult): Promise<IRunResult> => {
+    await consolidateLessons(cwd, events, runId, report);
+
+    return result;
+  };
 
   report({
     kind: "start",
@@ -330,6 +323,7 @@ export async function runTask(
   const state: ILoopState = {
     prevGateErrors: red.errors,
     gateNoProgress: 0,
+    errorAge: new Map(),
     lastGateCount: -1,
     edits: 0,
     regressions: 0,
@@ -402,7 +396,7 @@ export async function runTask(
     });
 
     if (looped !== null) {
-      return looped;
+      return finish(looped);
     }
 
     const touchedEditable =
@@ -418,11 +412,11 @@ export async function runTask(
       emitTiming(report, task.id, turn, turnStart, taskStart);
 
       if (settled !== null) {
-        return {
+        return finish({
           ...settled,
           edits: state.edits,
           regressions: state.regressions,
-        };
+        });
       }
 
       // Stopped with no tool call while still red → nudge it to act, not narrate.
@@ -443,7 +437,7 @@ export async function runTask(
     message: `task ${task.id}: stuck (hit ${maxTurns}-turn cap)`,
   });
 
-  return {
+  return finish({
     task: task.id,
     redConfirmed: true,
     status: RUN_STATUS.stuck,
@@ -451,5 +445,5 @@ export async function runTask(
     reason: STUCK_REASON.cap,
     edits: state.edits,
     regressions: state.regressions,
-  };
+  });
 }