@agjs/tsforge 0.3.4 → 0.5.0

package/src/meta-rules/rules/supply-chain/no-undeclared-dependencies.ts

@@ -0,0 +1,180 @@
+import { builtinModules } from "node:module";
+import type {
+  IMetaRule,
+  IMetaRuleContext,
+  IMetaRuleViolation,
+} from "../../meta-rules.types";
+
+/**
+ * Every bare `import` must resolve to a DECLARED dependency. A classic AI mistake
+ * is importing a package it never added to package.json — it works locally via a
+ * hoisted/transitive copy, then breaks on a clean install in CI or for a teammate.
+ * We compare each imported package against package.json's declared deps (+ Node
+ * builtins, `bun:` specifiers, tsconfig path aliases, and the project's own name).
+ */
+const IMPORT_FROM = /(?:import|export)[^'"]*?from\s*['"](?<spec>[^'"]+)['"]/gu;
+const DYNAMIC_IMPORT = /\bimport\s*\(\s*['"](?<spec>[^'"]+)['"]\s*\)/gu;
+const NODE_BUILTINS = new Set([
+  ...builtinModules,
+  ...builtinModules.map((m) => `node:${m}`),
+]);
+
+/** Bare specifiers (packages), skipping relative/absolute paths. */
+function bareSpecifiers(text: string): string[] {
+  const out: string[] = [];
+
+  for (const re of [IMPORT_FROM, DYNAMIC_IMPORT]) {
+    re.lastIndex = 0;
+
+    for (const m of text.matchAll(re)) {
+      const spec = m.groups?.spec;
+
+      if (
+        spec !== undefined &&
+        !spec.startsWith(".") &&
+        !spec.startsWith("/")
+      ) {
+        out.push(spec);
+      }
+    }
+  }
+
+  return out;
+}
+
+/** The package name a specifier belongs to (`@scope/pkg/sub` → `@scope/pkg`). */
+function packageName(spec: string): string {
+  const parts = spec.split("/");
+
+  if (spec.startsWith("@")) {
+    return parts.slice(0, 2).join("/");
+  }
+
+  return parts[0] ?? spec;
+}
+
+/** Collect declared dependency names from every dependency field. */
+function declaredDeps(pkg: Record<string, unknown> | null): Set<string> {
+  const names = new Set<string>();
+  const fields = [
+    "dependencies",
+    "devDependencies",
+    "peerDependencies",
+    "optionalDependencies",
+  ];
+
+  for (const field of fields) {
+    const map = pkg?.[field];
+
+    if (typeof map === "object" && map !== null) {
+      for (const name of Object.keys(map)) {
+        names.add(name);
+      }
+    }
+  }
+
+  return names;
+}
+
+/** Read a string-keyed property as `unknown` without surfacing `any`. */
+function prop(value: unknown, key: string): unknown {
+  if (typeof value !== "object" || value === null || !(key in value)) {
+    return undefined;
+  }
+
+  const record: Record<string, unknown> = { ...value };
+
+  return record[key];
+}
+
+/** tsconfig `compilerOptions.paths` alias prefixes (e.g. `@/*` → `@/`). */
+function aliasPrefixes(ctx: IMetaRuleContext): string[] {
+  const raw = ctx.readFile("tsconfig.json");
+
+  if (raw === null) {
+    return [];
+  }
+
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    const paths = prop(prop(parsed, "compilerOptions"), "paths");
+
+    if (typeof paths !== "object" || paths === null) {
+      return [];
+    }
+
+    return Object.keys(paths).map((k) => k.replace(/\*$/u, ""));
+  } catch {
+    return [];
+  }
+}
+
+/** True when an import is satisfied without a runtime dep declaration. */
+function isAllowed(
+  pkg: string,
+  spec: string,
+  declared: ReadonlySet<string>,
+  aliases: readonly string[],
+  ownName: string
+): boolean {
+  if (spec.startsWith("bun:") || pkg === "bun") {
+    return true;
+  }
+
+  if (NODE_BUILTINS.has(pkg) || NODE_BUILTINS.has(spec)) {
+    return true;
+  }
+
+  if (pkg === ownName || declared.has(pkg) || declared.has(`@types/${pkg}`)) {
+    return true;
+  }
+
+  return aliases.some((prefix) => prefix.length > 0 && spec.startsWith(prefix));
+}
+
+export const noUndeclaredDependenciesRule: IMetaRule = {
+  id: "no-undeclared-dependencies",
+  category: "supply-chain",
+  description:
+    "Every imported package must be declared in package.json — an undeclared import works via hoisting locally but breaks on a clean install.",
+  severity: "error",
+  run(ctx) {
+    if (ctx.packageJson === null) {
+      return []; // no manifest to check against
+    }
+
+    const declared = declaredDeps(ctx.packageJson);
+    const aliases = aliasPrefixes(ctx);
+    const ownNameRaw = prop(ctx.packageJson, "name");
+    const ownName = typeof ownNameRaw === "string" ? ownNameRaw : "";
+    const violations: IMetaRuleViolation[] = [];
+    const seen = new Set<string>();
+
+    for (const file of ctx.sourceFiles) {
+      const text = ctx.readFile(file);
+
+      if (text === null) {
+        continue;
+      }
+
+      for (const spec of bareSpecifiers(text)) {
+        const pkg = packageName(spec);
+        const key = `${file}::${pkg}`;
+
+        if (isAllowed(pkg, spec, declared, aliases, ownName) || seen.has(key)) {
+          continue;
+        }
+
+        seen.add(key);
+        violations.push({
+          file,
+          ruleId: "no-undeclared-dependencies",
+          severity: "error",
+          message: `Imports \`${pkg}\` but it is not in package.json — add it to dependencies (or devDependencies) so a clean install resolves it.`,
+        });
+      }
+    }
+
+    return violations;
+  },
+};

package/src/rule-packs/ai-sdk/index.ts

@@ -0,0 +1,28 @@
+import type { TSESLint } from "@typescript-eslint/utils";
+
+import { noApiKeyInClientRule } from "./rules/no-api-key-in-client";
+import { requireCompletionTokenLimitRule } from "./rules/require-completion-token-limit";
+import { noUserInputInSystemPromptRule } from "./rules/no-user-input-in-system-prompt";
+import type { IRulePack } from "../rule-packs.types";
+
+const rules: Record<string, TSESLint.RuleModule<string, readonly unknown[]>> = {
+  "no-api-key-in-client": noApiKeyInClientRule,
+  "require-completion-token-limit": requireCompletionTokenLimitRule,
+  "no-user-input-in-system-prompt": noUserInputInSystemPromptRule,
+};
+
+export const aiSdkPack: IRulePack = {
+  id: "ai-sdk",
+  description:
+    "LLM/AI-SDK security and cost guardrails: no provider key in client bundles, bounded completion tokens, and no request data spliced into the system prompt",
+  rules,
+  // Structural checks block (error); the injection heuristic warns until proven
+  // precise — a false positive on an un-bypassable gate would deadlock the model.
+  rulesConfig: {
+    "no-api-key-in-client": "error",
+    "require-completion-token-limit": "error",
+    "no-user-input-in-system-prompt": "warn",
+  },
+};
+
+export default aiSdkPack;

package/src/rule-packs/ai-sdk/rules/no-api-key-in-client.ts

@@ -0,0 +1,92 @@
+import { AST_NODE_TYPES, type TSESTree } from "@typescript-eslint/utils";
+
+import { createRule } from "../../create-rule";
+
+export const RULE_NAME = "no-api-key-in-client";
+
+type MessageIds = "clientProvider";
+
+// Providers whose constructor / factory takes an API key. Building one in a
+// `"use client"` file ships the key into the browser bundle.
+const PROVIDER_CONSTRUCTORS = new Set([
+  "OpenAI",
+  "Anthropic",
+  "GoogleGenerativeAI",
+]);
+const PROVIDER_FACTORIES = new Set([
+  "createOpenAI",
+  "createAnthropic",
+  "createGoogleGenerativeAI",
+  "createAzure",
+  "createMistral",
+]);
+
+/** True when the file opens with a `"use client"` directive (client component). */
+function hasUseClientDirective(
+  body: readonly TSESTree.ProgramStatement[]
+): boolean {
+  for (const stmt of body) {
+    if (stmt.type !== AST_NODE_TYPES.ExpressionStatement) {
+      return false; // directives must lead; first non-expression ends the prologue
+    }
+
+    const expr = stmt.expression;
+
+    if (expr.type === AST_NODE_TYPES.Literal && expr.value === "use client") {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/** `new OpenAI(...)` etc. */
+function isProviderConstruction(node: TSESTree.NewExpression): boolean {
+  return (
+    node.callee.type === AST_NODE_TYPES.Identifier &&
+    PROVIDER_CONSTRUCTORS.has(node.callee.name)
+  );
+}
+
+/** `createOpenAI(...)` etc. */
+function isProviderFactory(node: TSESTree.CallExpression): boolean {
+  return (
+    node.callee.type === AST_NODE_TYPES.Identifier &&
+    PROVIDER_FACTORIES.has(node.callee.name)
+  );
+}
+
+export const noApiKeyInClientRule = createRule<[], MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow constructing an AI provider client in a client component — it leaks the API key into the browser bundle. Call the model from a server route/action.",
+    },
+    schema: [],
+    messages: {
+      clientProvider:
+        "Do not create an AI provider client in a `'use client'` file — the API key would ship to the browser. Move the call to a server route or server action.",
+    },
+  },
+  defaultOptions: [],
+  create(context) {
+    if (!hasUseClientDirective(context.sourceCode.ast.body)) {
+      return {};
+    }
+
+    return {
+      NewExpression(node: TSESTree.NewExpression) {
+        if (isProviderConstruction(node)) {
+          context.report({ node, messageId: "clientProvider" });
+        }
+      },
+      CallExpression(node: TSESTree.CallExpression) {
+        if (isProviderFactory(node)) {
+          context.report({ node, messageId: "clientProvider" });
+        }
+      },
+    };
+  },
+});

package/src/rule-packs/ai-sdk/rules/no-user-input-in-system-prompt.ts

@@ -0,0 +1,91 @@
+import { AST_NODE_TYPES, type TSESTree } from "@typescript-eslint/utils";
+
+import { createRule } from "../../create-rule";
+
+export const RULE_NAME = "no-user-input-in-system-prompt";
+
+type MessageIds = "dynamicSystemPrompt";
+
+/** A value built by interpolation/concatenation rather than a constant string —
+ *  the shape that splices request data into the system prompt (injection). A
+ *  plain string, identifier, or constant template (no `${}`) is fine. */
+function isDynamicString(node: TSESTree.Node): boolean {
+  if (node.type === AST_NODE_TYPES.TemplateLiteral) {
+    return node.expressions.length > 0;
+  }
+
+  return node.type === AST_NODE_TYPES.BinaryExpression && node.operator === "+";
+}
+
+/** Find a non-computed string-keyed property on an object literal. */
+function findProperty(
+  obj: TSESTree.ObjectExpression,
+  name: string
+): TSESTree.Property | null {
+  for (const p of obj.properties) {
+    if (
+      p.type === AST_NODE_TYPES.Property &&
+      !p.computed &&
+      p.key.type === AST_NODE_TYPES.Identifier &&
+      p.key.name === name
+    ) {
+      return p;
+    }
+  }
+
+  return null;
+}
+
+/** True when the object is a chat message with `role: "system"`. */
+function isSystemMessage(obj: TSESTree.ObjectExpression): boolean {
+  const role = findProperty(obj, "role");
+
+  return (
+    role !== null &&
+    role.value.type === AST_NODE_TYPES.Literal &&
+    role.value.value === "system"
+  );
+}
+
+export const noUserInputInSystemPromptRule = createRule<[], MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: "suggestion",
+    docs: {
+      description:
+        "Warn when a system prompt is built by string interpolation/concatenation — splicing request data into the system role enables prompt injection. Keep the system prompt constant; pass user input as a user message.",
+    },
+    schema: [],
+    messages: {
+      dynamicSystemPrompt:
+        "System prompt is built dynamically — do not interpolate request/user data into the system role (prompt injection). Keep it a constant and pass user input as a `user` message.",
+    },
+  },
+  defaultOptions: [],
+  create(context) {
+    const reportIfDynamic = (value: TSESTree.Node | null): void => {
+      if (value !== null && isDynamicString(value)) {
+        context.report({ node: value, messageId: "dynamicSystemPrompt" });
+      }
+    };
+
+    return {
+      // Vercel AI SDK: `{ system: `...${x}...` }`
+      "Property[key.name='system']"(node: TSESTree.Property) {
+        if (!node.computed) {
+          reportIfDynamic(node.value);
+        }
+      },
+      // Chat messages: `{ role: "system", content: `...${x}...` }`
+      ObjectExpression(node: TSESTree.ObjectExpression) {
+        if (!isSystemMessage(node)) {
+          return;
+        }
+
+        const content = findProperty(node, "content");
+
+        reportIfDynamic(content === null ? null : content.value);
+      },
+    };
+  },
+});

package/src/rule-packs/ai-sdk/rules/require-completion-token-limit.ts

@@ -0,0 +1,112 @@
+import { AST_NODE_TYPES, type TSESTree } from "@typescript-eslint/utils";
+
+import { createRule } from "../../create-rule";
+
+export const RULE_NAME = "require-completion-token-limit";
+
+type MessageIds = "missingLimit";
+
+// Vercel AI SDK top-level generators.
+const VERCEL_FNS = new Set([
+  "generateText",
+  "streamText",
+  "generateObject",
+  "streamObject",
+]);
+// Provider-SDK members that own a `.create(...)` completion call.
+const CREATE_OWNERS = new Set(["completions", "messages", "responses"]);
+// Any of these keys bounds the output, across SDKs.
+const TOKEN_KEYS = new Set([
+  "maxTokens",
+  "max_tokens",
+  "maxOutputTokens",
+  "max_output_tokens",
+  "max_completion_tokens",
+]);
+
+/** The options object literal for a Vercel generator call, or null. */
+function vercelOptionsArg(
+  node: TSESTree.CallExpression
+): TSESTree.ObjectExpression | null {
+  if (node.callee.type !== AST_NODE_TYPES.Identifier) {
+    return null;
+  }
+
+  if (!VERCEL_FNS.has(node.callee.name)) {
+    return null;
+  }
+
+  const arg = node.arguments[0];
+
+  return arg?.type === AST_NODE_TYPES.ObjectExpression ? arg : null;
+}
+
+/** The options object for an `x.<owner>.create({...})` SDK call, or null. */
+function createCallOptionsArg(
+  node: TSESTree.CallExpression
+): TSESTree.ObjectExpression | null {
+  const callee = node.callee;
+
+  if (
+    callee.type !== AST_NODE_TYPES.MemberExpression ||
+    callee.computed ||
+    callee.property.type !== AST_NODE_TYPES.Identifier ||
+    callee.property.name !== "create"
+  ) {
+    return null;
+  }
+
+  const owner = callee.object;
+
+  if (
+    owner.type !== AST_NODE_TYPES.MemberExpression ||
+    owner.computed ||
+    owner.property.type !== AST_NODE_TYPES.Identifier ||
+    !CREATE_OWNERS.has(owner.property.name)
+  ) {
+    return null;
+  }
+
+  const arg = node.arguments[0];
+
+  return arg?.type === AST_NODE_TYPES.ObjectExpression ? arg : null;
+}
+
+/** True when the object literal sets one of the recognized token-limit keys. */
+function hasTokenLimit(obj: TSESTree.ObjectExpression): boolean {
+  return obj.properties.some(
+    (p) =>
+      p.type === AST_NODE_TYPES.Property &&
+      !p.computed &&
+      p.key.type === AST_NODE_TYPES.Identifier &&
+      TOKEN_KEYS.has(p.key.name)
+  );
+}
+
+export const requireCompletionTokenLimitRule = createRule<[], MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Require a token limit (maxTokens / max_tokens) on AI completion calls to bound runaway cost and latency.",
+    },
+    schema: [],
+    messages: {
+      missingLimit:
+        "AI completion call has no token limit — set `maxTokens` (Vercel AI SDK) or `max_tokens` (OpenAI/Anthropic) to bound cost and latency.",
+    },
+  },
+  defaultOptions: [],
+  create(context) {
+    return {
+      CallExpression(node: TSESTree.CallExpression) {
+        const options = vercelOptionsArg(node) ?? createCallOptionsArg(node);
+
+        if (options !== null && !hasTokenLimit(options)) {
+          context.report({ node, messageId: "missingLimit" });
+        }
+      },
+    };
+  },
+});

package/src/rule-packs/index.ts

@@ -1,6 +1,7 @@
 import type { TSESLint } from "@typescript-eslint/utils";
 
 import type { IRulePack } from "./rule-packs.types";
+import { aiSdkPack } from "./ai-sdk";
 import { authorizationPack } from "./authorization";
 import { bullmqPack } from "./bullmq";
 import { commentHygienePack } from "./comment-hygiene";
@@ -25,6 +26,7 @@ import { PACK_REGISTRY } from "../stack-detection";
 
 /** Registry of all available rule packs, keyed by pack ID. */
 export const RULE_PACKS = {
+  "ai-sdk": aiSdkPack,
   authorization: authorizationPack,
   bullmq: bullmqPack,
   "code-flow": codeFlowPack,

package/src/stack-detection/packs.ts

@@ -222,6 +222,25 @@ export const PACK_REGISTRY = {
     appliesWhen: { anyDeps: ["i18next", "react-i18next"] },
     guidance: "Keep i18n keys organized and validated.",
   } as const satisfies IRulePackDescriptor,
+
+  "ai-sdk": {
+    id: "ai-sdk",
+    label: "AI SDK Security",
+    description:
+      "LLM/AI-SDK security and cost guardrails: no provider key in client bundles, bounded completion tokens, no request data in the system prompt",
+    category: "library",
+    appliesWhen: {
+      anyDeps: [
+        "ai",
+        "openai",
+        "@anthropic-ai/sdk",
+        "@ai-sdk/openai",
+        "@ai-sdk/anthropic",
+      ],
+    },
+    guidance:
+      "Call models server-side, bound output tokens, and keep the system prompt constant.",
+  } as const satisfies IRulePackDescriptor,
 } as const;
 
 /** Ordered list of always-on pack IDs (for deterministic ordering). */

package/strict.eslint.config.mjs

@@ -13,6 +13,7 @@
 // map of bare rule names to "error" | "warn" | "off").
 import tseslint from "typescript-eslint";
 import stylistic from "@stylistic/eslint-plugin";
+import sonarjs from "eslint-plugin-sonarjs";
 
 // Load stack-aware packs if TSFORGE_PACKS env var is set
 let packConfig = [];
@@ -56,8 +57,19 @@ export default tseslint.config(
     plugins: {
       "@typescript-eslint": tseslint.plugin,
       "@stylistic": stylistic,
+      sonarjs,
     },
     rules: {
+      // Concern-mixing / copy-paste ceiling (syntactic — no type info needed).
+      // cc <= 20 is the house rule tsforge holds ITSELF to (eslint.config.js); it
+      // forces the model to decompose a sprawling function into named helpers
+      // instead of one un-reviewable block. Not auto-fixable, so it surfaces as a
+      // hand-fix error — the intended "split this up" signal. max-depth/max-params
+      // are zero-dep ESLint-core complements.
+      "sonarjs/cognitive-complexity": ["error", 20],
+      "sonarjs/no-identical-functions": "error",
+      "max-depth": ["error", 4],
+      "max-params": ["error", 4],
       // The idioms the model habitually violates — all caught WITHOUT type info.
       "@typescript-eslint/consistent-type-assertions": [
         "error",

package/strict.type-aware.eslint.config.mjs

@@ -1,7 +1,21 @@
 // Optional type-aware ESLint overlay — enabled only when the target has a
-// compiling tsconfig (see detect-gate.ts). Adds async correctness rules that
-// require parserOptions.project; kept separate from strict.eslint.config.mjs
-// so the syntactic gate still runs on any .ts file without type info.
+// compiling tsconfig (see detect-gate.ts). These rules need full type info
+// (parserOptions.project) and are kept separate from strict.eslint.config.mjs so
+// the syntactic gate still runs on any .ts file without type info.
+//
+// Two jobs:
+//   1. Async correctness — floating/misused promises (a dropped `await` is silent
+//      data loss / unhandled rejection).
+//   2. IMPLICIT-`any` containment — the `no-unsafe-*` family. `no-explicit-any`
+//      (in the syntactic config) bans the literal `any` token, but it CANNOT see
+//      `any` that leaks in from an untyped boundary: `JSON.parse(s)`, `await
+//      res.json()`, an untyped dependency. `tsc --strict` propagates that `any`
+//      silently. These rules are the only thing that catches it — they make the
+//      generated-code gate enforce what tsforge already enforces on its OWN source
+//      via strictTypeChecked. Curated to the HIGH-SIGNAL, low-thrash subset;
+//      narrative rules (strict-boolean-expressions, no-unnecessary-condition,
+//      restrict-template-expressions) are deliberately left off until a sweep
+//      shows they don't thrash the local model.
 import tseslint from "typescript-eslint";
 
 export default tseslint.config(
@@ -19,6 +33,7 @@ export default tseslint.config(
       "@typescript-eslint": tseslint.plugin,
     },
     rules: {
+      // Async correctness.
       "@typescript-eslint/no-floating-promises": "error",
       "@typescript-eslint/no-misused-promises": [
         "error",
@@ -28,6 +43,24 @@ export default tseslint.config(
           },
         },
       ],
+      "@typescript-eslint/await-thenable": "error",
+
+      // Implicit-`any` containment: stop untyped boundary data from flowing
+      // through the program unchecked.
+      "@typescript-eslint/no-unsafe-assignment": "error",
+      "@typescript-eslint/no-unsafe-member-access": "error",
+      "@typescript-eslint/no-unsafe-call": "error",
+      "@typescript-eslint/no-unsafe-return": "error",
+      "@typescript-eslint/no-unsafe-argument": "error",
+
+      // Cheap, high-signal correctness rules that need type info.
+      "@typescript-eslint/no-for-in-array": "error",
+      "@typescript-eslint/no-base-to-string": "error",
+      "@typescript-eslint/restrict-plus-operands": "error",
+      "@typescript-eslint/switch-exhaustiveness-check": [
+        "error",
+        { considerDefaultExhaustiveForUnions: true },
+      ],
     },
   }
 );

package/strict.web.eslint.config.mjs

@@ -13,6 +13,7 @@ import stylistic from "@stylistic/eslint-plugin";
 import pluginReact from "eslint-plugin-react";
 import pluginReactHooks from "eslint-plugin-react-hooks";
 import pluginJsxA11y from "eslint-plugin-jsx-a11y";
+import sonarjs from "eslint-plugin-sonarjs";
 
 // Load stack-aware packs if TSFORGE_PACKS env var is set
 let packConfig = [];
@@ -112,6 +113,7 @@ export default tseslint.config(
       "@stylistic": stylistic,
       react: pluginReact,
       "react-hooks": pluginReactHooks,
+      sonarjs,
       boringstack: { rules: { "one-component-per-file": oneComponentPerFile } },
       ...packConfig
         .filter(
@@ -125,6 +127,13 @@ export default tseslint.config(
       // literal/tuple data (and it makes a fixed array a tuple, so literal-index
       // access is defined, not `T | undefined`). Instead we ban only the
       // value-changing forms (`x as Foo`, `<Foo>x`) via AST selectors below.
+      // Concern-mixing / copy-paste ceiling (syntactic — mirrors the core config).
+      // cc <= 20 forces decomposition into named helpers; max-depth/max-params are
+      // zero-dep ESLint-core complements.
+      "sonarjs/cognitive-complexity": ["error", 20],
+      "sonarjs/no-identical-functions": "error",
+      "max-depth": ["error", 4],
+      "max-params": ["error", 4],
       "@typescript-eslint/no-explicit-any": "error",
       "@typescript-eslint/no-non-null-assertion": "error",
       "@typescript-eslint/no-inferrable-types": "error",