@agjs/tsforge 0.1.19 → 0.2.1

package/src/rule-packs/test-conventions/rules/no-real-network-in-unit-tests.ts

@@ -0,0 +1,174 @@
+import { AST_NODE_TYPES, type TSESTree } from "@typescript-eslint/utils";
+import type { JSONSchema4 } from "@typescript-eslint/utils/json-schema";
+
+import { createRule } from "../../create-rule";
+import { toPosixRelative } from "../../utils";
+
+export const RULE_NAME = "no-real-network-in-unit-tests";
+
+export interface INoRealNetworkInUnitTestsOptions {
+  readonly testFileSuffixes?: readonly string[];
+  readonly integrationMarkers?: readonly string[];
+  readonly networkCallees?: readonly string[];
+}
+
+type RuleOptions = [INoRealNetworkInUnitTestsOptions];
+type MessageIds = "realNetworkInUnitTest";
+
+const DEFAULT_TEST_FILE_SUFFIXES = [
+  ".test.ts",
+  ".test.tsx",
+  ".spec.ts",
+  ".spec.tsx",
+] as const;
+
+const DEFAULT_INTEGRATION_MARKERS = [
+  ".integration.test.",
+  ".integration.spec.",
+  "/integration/",
+] as const;
+
+const DEFAULT_NETWORK_CALLEES = ["fetch"] as const;
+
+const optionSchema: JSONSchema4 = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    testFileSuffixes: {
+      type: "array",
+      items: { type: "string" },
+    },
+    integrationMarkers: {
+      type: "array",
+      items: { type: "string" },
+    },
+    networkCallees: {
+      type: "array",
+      items: { type: "string" },
+    },
+  },
+};
+
+function isUnitTestFile(relPath: string, suffixes: readonly string[]): boolean {
+  return suffixes.some((suffix) => relPath.endsWith(suffix));
+}
+
+function isIntegrationTestFile(
+  relPath: string,
+  markers: readonly string[]
+): boolean {
+  return markers.some((marker) => relPath.includes(marker));
+}
+
+function getCalleeName(callee: TSESTree.Node): string | null {
+  if (callee.type === AST_NODE_TYPES.Identifier) {
+    return callee.name;
+  }
+
+  if (
+    callee.type === AST_NODE_TYPES.MemberExpression &&
+    !callee.computed &&
+    callee.property.type === AST_NODE_TYPES.Identifier
+  ) {
+    return callee.property.name;
+  }
+
+  return null;
+}
+
+function isAxiosCall(node: TSESTree.CallExpression): boolean {
+  const callee = node.callee;
+
+  if (callee.type !== AST_NODE_TYPES.MemberExpression || callee.computed) {
+    return false;
+  }
+
+  if (
+    callee.object.type !== AST_NODE_TYPES.Identifier ||
+    callee.object.name !== "axios"
+  ) {
+    return false;
+  }
+
+  if (callee.property.type !== AST_NODE_TYPES.Identifier) {
+    return false;
+  }
+
+  const method = callee.property.name;
+
+  return (
+    method === "get" ||
+    method === "post" ||
+    method === "put" ||
+    method === "patch" ||
+    method === "delete" ||
+    method === "request"
+  );
+}
+
+export const noRealNetworkInUnitTestsRule = createRule<RuleOptions, MessageIds>(
+  {
+    name: RULE_NAME,
+    meta: {
+      type: "suggestion",
+      docs: {
+        description:
+          "Unit tests should not perform real network I/O — mock HTTP clients or move the test to an integration suite.",
+      },
+      schema: [optionSchema],
+      messages: {
+        realNetworkInUnitTest:
+          "Avoid real network calls in unit tests — mock `{{callee}}` or move this test to an integration file.",
+      },
+    },
+    defaultOptions: [
+      {
+        testFileSuffixes: [...DEFAULT_TEST_FILE_SUFFIXES],
+        integrationMarkers: [...DEFAULT_INTEGRATION_MARKERS],
+        networkCallees: [...DEFAULT_NETWORK_CALLEES],
+      },
+    ],
+    create(context, [options]) {
+      const testSuffixes =
+        options.testFileSuffixes ?? DEFAULT_TEST_FILE_SUFFIXES;
+      const integrationMarkers =
+        options.integrationMarkers ?? DEFAULT_INTEGRATION_MARKERS;
+      const networkCallees = new Set(
+        options.networkCallees ?? DEFAULT_NETWORK_CALLEES
+      );
+      const relPath = toPosixRelative(context.filename, context.cwd);
+
+      if (!isUnitTestFile(relPath, testSuffixes)) {
+        return {};
+      }
+
+      if (isIntegrationTestFile(relPath, integrationMarkers)) {
+        return {};
+      }
+
+      return {
+        CallExpression(node) {
+          const name = getCalleeName(node.callee);
+
+          if (name !== null && networkCallees.has(name)) {
+            context.report({
+              node,
+              messageId: "realNetworkInUnitTest",
+              data: { callee: name },
+            });
+
+            return;
+          }
+
+          if (isAxiosCall(node)) {
+            context.report({
+              node,
+              messageId: "realNetworkInUnitTest",
+              data: { callee: "axios" },
+            });
+          }
+        },
+      };
+    },
+  }
+);

package/src/rule-packs/typescript-core/index.ts

@@ -0,0 +1,30 @@
+import type { TSESLint } from "@typescript-eslint/utils";
+
+import { exportedFunctionsRequireReturnTypeRule } from "./rules/exported-functions-require-return-type";
+import { fetchMustCheckOkRule } from "./rules/fetch-must-check-ok";
+import { jsonParseMustValidateRule } from "./rules/json-parse-must-validate";
+import { noUnsafeBoundaryCastRule } from "./rules/no-unsafe-boundary-cast";
+import type { IRulePack } from "../rule-packs.types";
+
+const rules: Record<string, TSESLint.RuleModule<string, readonly unknown[]>> = {
+  "exported-functions-require-return-type":
+    exportedFunctionsRequireReturnTypeRule,
+  "fetch-must-check-ok": fetchMustCheckOkRule,
+  "json-parse-must-validate": jsonParseMustValidateRule,
+  "no-unsafe-boundary-cast": noUnsafeBoundaryCastRule,
+};
+
+export const typescriptCorePack: IRulePack = {
+  id: "typescript-core",
+  description:
+    "Cross-cutting TypeScript boundary safety: fetch status checks, JSON validation, and module export typing.",
+  rules,
+  rulesConfig: {
+    "exported-functions-require-return-type": "warn",
+    "fetch-must-check-ok": "error",
+    "json-parse-must-validate": "error",
+    "no-unsafe-boundary-cast": "error",
+  },
+};
+
+export default typescriptCorePack;

package/src/rule-packs/typescript-core/rules/exported-functions-require-return-type.ts

@@ -0,0 +1,74 @@
+import { AST_NODE_TYPES, type TSESTree } from "@typescript-eslint/utils";
+
+import { createRule } from "../../create-rule";
+
+export const RULE_NAME = "exported-functions-require-return-type";
+
+type MessageIds = "missingReturnType";
+
+function isExported(node: TSESTree.Node): boolean {
+  return (
+    node.type === AST_NODE_TYPES.ExportNamedDeclaration ||
+    node.type === AST_NODE_TYPES.ExportDefaultDeclaration
+  );
+}
+
+export const exportedFunctionsRequireReturnTypeRule = createRule<
+  [],
+  MessageIds
+>({
+  name: RULE_NAME,
+  meta: {
+    type: "suggestion",
+    docs: {
+      description:
+        "Exported functions should declare an explicit return type at module boundaries.",
+    },
+    schema: [],
+    messages: {
+      missingReturnType:
+        "Exported function `{{name}}` should declare an explicit return type.",
+    },
+  },
+  defaultOptions: [],
+  create(context) {
+    function checkFunction(
+      node: TSESTree.FunctionDeclaration,
+      exported: boolean
+    ): void {
+      if (!exported || node.returnType !== undefined) {
+        return;
+      }
+
+      const name = node.id?.name ?? "anonymous";
+
+      context.report({
+        node,
+        messageId: "missingReturnType",
+        data: { name },
+      });
+    }
+
+    return {
+      ExportNamedDeclaration(node: TSESTree.ExportNamedDeclaration) {
+        const decl = node.declaration;
+
+        if (decl?.type === AST_NODE_TYPES.FunctionDeclaration) {
+          checkFunction(decl, true);
+        }
+      },
+      FunctionDeclaration(node: TSESTree.FunctionDeclaration) {
+        if (node.parent !== undefined && isExported(node.parent)) {
+          return;
+        }
+
+        if (
+          node.parent?.type === AST_NODE_TYPES.ExportNamedDeclaration ||
+          node.parent?.type === AST_NODE_TYPES.ExportDefaultDeclaration
+        ) {
+          checkFunction(node, true);
+        }
+      },
+    };
+  },
+});

package/src/rule-packs/typescript-core/rules/fetch-must-check-ok.ts

@@ -0,0 +1,106 @@
+import { AST_NODE_TYPES, type TSESTree } from "@typescript-eslint/utils";
+
+import { createRule } from "../../create-rule";
+import { walkSome } from "../../utils";
+
+export const RULE_NAME = "fetch-must-check-ok";
+
+type MessageIds = "missingOkCheck";
+
+function fetchCallHasOkCheck(fetchCall: TSESTree.CallExpression): boolean {
+  let parent: TSESTree.Node | null | undefined = fetchCall.parent;
+
+  while (parent !== undefined && parent !== null) {
+    if (parent.type === AST_NODE_TYPES.AwaitExpression) {
+      parent = parent.parent;
+      continue;
+    }
+
+    if (parent.type === AST_NODE_TYPES.VariableDeclarator) {
+      const init = parent.init;
+
+      if (
+        init?.type === AST_NODE_TYPES.AwaitExpression &&
+        init.argument === fetchCall
+      ) {
+        const binding = parent.id;
+
+        if (binding.type === AST_NODE_TYPES.Identifier) {
+          const name = binding.name;
+
+          return walkSome(parent.parent ?? fetchCall, (node) => {
+            if (
+              node.type !== AST_NODE_TYPES.MemberExpression ||
+              node.computed
+            ) {
+              return false;
+            }
+
+            return (
+              node.object.type === AST_NODE_TYPES.Identifier &&
+              node.object.name === name &&
+              node.property.type === AST_NODE_TYPES.Identifier &&
+              node.property.name === "ok"
+            );
+          });
+        }
+      }
+    }
+
+    if (
+      parent.type === AST_NODE_TYPES.MemberExpression &&
+      !parent.computed &&
+      parent.property.type === AST_NODE_TYPES.Identifier &&
+      parent.property.name === "json"
+    ) {
+      return false;
+    }
+
+    break;
+  }
+
+  return true;
+}
+
+export const fetchMustCheckOkRule = createRule<[], MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "HTTP fetch responses must check `.ok` or status before calling `.json()`.",
+    },
+    schema: [],
+    messages: {
+      missingOkCheck:
+        "Check `response.ok` (or status) before calling `.json()` on a fetch response.",
+    },
+  },
+  defaultOptions: [],
+  create(context) {
+    return {
+      CallExpression(node: TSESTree.CallExpression) {
+        const callee = node.callee;
+
+        if (
+          callee.type !== AST_NODE_TYPES.Identifier ||
+          callee.name !== "fetch"
+        ) {
+          return;
+        }
+
+        const parent = node.parent;
+
+        if (
+          parent?.type === AST_NODE_TYPES.MemberExpression &&
+          !parent.computed &&
+          parent.property.type === AST_NODE_TYPES.Identifier &&
+          parent.property.name === "json" &&
+          !fetchCallHasOkCheck(node)
+        ) {
+          context.report({ node: parent, messageId: "missingOkCheck" });
+        }
+      },
+    };
+  },
+});

package/src/rule-packs/typescript-core/rules/json-parse-must-validate.ts

@@ -0,0 +1,97 @@
+import { AST_NODE_TYPES, type TSESTree } from "@typescript-eslint/utils";
+
+import { createRule } from "../../create-rule";
+
+export const RULE_NAME = "json-parse-must-validate";
+
+type MessageIds = "bareJsonParse";
+
+const VALIDATOR_IMPORTS = new Set([
+  "zod",
+  "valibot",
+  "@effect/schema",
+  "effect/Schema",
+  "arktype",
+]);
+
+function fileHasValidatorImport(program: TSESTree.Program): boolean {
+  for (const stmt of program.body) {
+    if (stmt.type !== AST_NODE_TYPES.ImportDeclaration) {
+      continue;
+    }
+
+    const source = stmt.source.value;
+
+    if (typeof source !== "string") {
+      continue;
+    }
+
+    const base = source.split("/")[0];
+
+    if (base !== undefined && VALIDATOR_IMPORTS.has(base)) {
+      return true;
+    }
+
+    if (VALIDATOR_IMPORTS.has(source)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+function isTestFile(filename: string): boolean {
+  return (
+    filename.includes(".test.") ||
+    filename.includes(".spec.") ||
+    filename.includes("/__tests__/")
+  );
+}
+
+export const jsonParseMustValidateRule = createRule<[], MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow bare JSON.parse on untrusted input — validate through a schema library.",
+    },
+    schema: [],
+    messages: {
+      bareJsonParse:
+        "Do not use bare `JSON.parse` on external input — parse through Zod, Valibot, or Effect Schema.",
+    },
+  },
+  defaultOptions: [],
+  create(context) {
+    if (isTestFile(context.filename)) {
+      return {};
+    }
+
+    let hasValidator = false;
+
+    return {
+      Program(node: TSESTree.Program) {
+        hasValidator = fileHasValidatorImport(node);
+      },
+      CallExpression(node: TSESTree.CallExpression) {
+        if (hasValidator) {
+          return;
+        }
+
+        const callee = node.callee;
+
+        if (
+          callee.type === AST_NODE_TYPES.MemberExpression &&
+          !callee.computed &&
+          callee.object.type === AST_NODE_TYPES.Identifier &&
+          callee.object.name === "JSON" &&
+          callee.property.type === AST_NODE_TYPES.Identifier &&
+          callee.property.name === "parse"
+        ) {
+          context.report({ node, messageId: "bareJsonParse" });
+        }
+      },
+    };
+  },
+});

package/src/rule-packs/typescript-core/rules/no-unsafe-boundary-cast.ts

@@ -0,0 +1,70 @@
+import { AST_NODE_TYPES, type TSESTree } from "@typescript-eslint/utils";
+
+import { createRule } from "../../create-rule";
+
+export const RULE_NAME = "no-unsafe-boundary-cast";
+
+type MessageIds = "unsafeBoundaryCast";
+
+const BOUNDARY_CALLEES = new Set([
+  "parse",
+  "json",
+  "get",
+  "getAll",
+  "text",
+  "formData",
+]);
+
+function isBoundarySource(node: TSESTree.Node): boolean {
+  if (node.type === AST_NODE_TYPES.CallExpression) {
+    const callee = node.callee;
+
+    if (
+      callee.type === AST_NODE_TYPES.MemberExpression &&
+      !callee.computed &&
+      callee.property.type === AST_NODE_TYPES.Identifier &&
+      BOUNDARY_CALLEES.has(callee.property.name)
+    ) {
+      return true;
+    }
+
+    if (
+      callee.type === AST_NODE_TYPES.MemberExpression &&
+      !callee.computed &&
+      callee.object.type === AST_NODE_TYPES.Identifier &&
+      callee.object.name === "JSON" &&
+      callee.property.type === AST_NODE_TYPES.Identifier &&
+      callee.property.name === "parse"
+    ) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+export const noUnsafeBoundaryCastRule = createRule<[], MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow type assertions immediately after parsing untrusted boundary input.",
+    },
+    schema: [],
+    messages: {
+      unsafeBoundaryCast:
+        "Do not cast untrusted parsed input with `as` — validate with a runtime schema instead.",
+    },
+  },
+  defaultOptions: [],
+  create(context) {
+    return {
+      TSAsExpression(node: TSESTree.TSAsExpression) {
+        if (isBoundarySource(node.expression)) {
+          context.report({ node, messageId: "unsafeBoundaryCast" });
+        }
+      },
+    };
+  },
+});

package/src/stack-detection/packs.ts

@@ -61,6 +61,17 @@ export const PACK_REGISTRY = {
     guidance: "Follow Elysia patterns for HTTP routing and middleware.",
   } as const satisfies IRulePackDescriptor,
 
+  fastify: {
+    id: "fastify",
+    label: "Fastify",
+    description:
+      "Schema-first Fastify routing, plugin encapsulation, and test hygiene",
+    category: "framework",
+    appliesWhen: { anyDeps: ["fastify"] },
+    guidance:
+      "Use schema-driven routes, fastify-plugin for shared decorators, and fastify.inject with app.close() in tests.",
+  } as const satisfies IRulePackDescriptor,
+
   nextjs: {
     id: "nextjs",
     label: "Next.js",
@@ -132,6 +143,50 @@ export const PACK_REGISTRY = {
     guidance: "Write comments that explain intent, not what the code does.",
   } as const satisfies IRulePackDescriptor,
 
+  security: {
+    id: "security",
+    label: "Security",
+    description:
+      "Application security guardrails: command injection, ReDoS, DOM XSS, and silent error masking",
+    category: "infra",
+    appliesWhen: { always: true },
+    guidance:
+      "Avoid shell execution, dynamic regex, innerHTML assignment, and catch blocks that silently mask failures.",
+  } as const satisfies IRulePackDescriptor,
+
+  "runtime-boundaries": {
+    id: "runtime-boundaries",
+    label: "Runtime Boundaries",
+    description:
+      "Runtime boundary safety: open redirects, SSRF, prototype pollution, webhook verification, and upload limits",
+    category: "infra",
+    appliesWhen: { always: true },
+    guidance:
+      "Use literal redirect/fetch URLs, avoid merging request fields into objects, verify webhooks before parsing, and cap multipart uploads.",
+  } as const satisfies IRulePackDescriptor,
+
+  "typescript-core": {
+    id: "typescript-core",
+    label: "TypeScript Core",
+    description:
+      "Cross-cutting TypeScript boundary safety: fetch status checks, JSON validation, and export typing",
+    category: "language",
+    appliesWhen: { always: false },
+    guidance:
+      "Validate HTTP responses, parse JSON through schemas, and annotate exported function return types.",
+  } as const satisfies IRulePackDescriptor,
+
+  authorization: {
+    id: "authorization",
+    label: "Authorization",
+    description:
+      "Experimental authorization heuristics for routes, server actions, and object-level access",
+    category: "infra",
+    appliesWhen: { always: false },
+    guidance:
+      "Mutating handlers should call authorization helpers before writes; opt in via the security profile.",
+  } as const satisfies IRulePackDescriptor,
+
   "structured-logging": {
     id: "structured-logging",
     label: "Structured Logging",
@@ -176,6 +231,8 @@ export const ALWAYS_ON_PACKS = [
   "module-boundaries",
   "code-flow",
   "comment-hygiene",
+  "security",
+  "runtime-boundaries",
 ] as const;
 
 /** Type-safe record of all pack descriptors. */

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

@@ -0,0 +1,33 @@
+// 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.
+import tseslint from "typescript-eslint";
+
+export default tseslint.config(
+  { ignores: ["**/node_modules/**", "**/dist/**", "**/build/**"] },
+  {
+    files: ["**/*.ts", "**/*.tsx"],
+    languageOptions: {
+      parser: tseslint.parser,
+      parserOptions: {
+        projectService: true,
+        tsconfigRootDir: process.cwd(),
+      },
+    },
+    plugins: {
+      "@typescript-eslint": tseslint.plugin,
+    },
+    rules: {
+      "@typescript-eslint/no-floating-promises": "error",
+      "@typescript-eslint/no-misused-promises": [
+        "error",
+        {
+          checksVoidReturn: {
+            attributes: false,
+          },
+        },
+      ],
+    },
+  }
+);