@agjs/tsforge 0.1.18 → 0.2.0

package/src/meta-rules/rules/supply-chain/production-must-not-use-drizzle-push.ts

@@ -0,0 +1,75 @@
+import type { IMetaRule, IMetaRuleViolation } from "../../meta-rules.types";
+
+/** Narrow `unknown` to a record without a type assertion. */
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+const DRIZZLE_PUSH_PATTERN = /\bdrizzle(?:-kit)?\s+push\b/u;
+
+function collectScriptViolations(
+  scripts: Record<string, string>
+): IMetaRuleViolation[] {
+  const violations: IMetaRuleViolation[] = [];
+
+  for (const [name, command] of Object.entries(scripts)) {
+    if (!DRIZZLE_PUSH_PATTERN.test(command)) {
+      continue;
+    }
+
+    violations.push({
+      file: "package.json",
+      ruleId: "production-must-not-use-drizzle-push",
+      severity: "warn",
+      message: `Script "${name}" runs \`drizzle-kit push\` — use versioned SQL migrations (drizzle-kit generate + migrate) in production instead of schema push.`,
+    });
+  }
+
+  return violations;
+}
+
+export const productionMustNotUseDrizzlePushRule: IMetaRule = {
+  id: "production-must-not-use-drizzle-push",
+  category: "supply-chain",
+  description:
+    "Do not run drizzle-kit push in package.json scripts or CI workflows.",
+  severity: "warn",
+  appliesTo: ["drizzle"],
+  run({ packageJson, workflowFiles, readFile }) {
+    const violations: IMetaRuleViolation[] = [];
+
+    if (packageJson !== null) {
+      const scriptsValue = packageJson.scripts;
+
+      if (isRecord(scriptsValue)) {
+        const scripts: Record<string, string> = {};
+
+        for (const [key, value] of Object.entries(scriptsValue)) {
+          if (typeof value === "string") {
+            scripts[key] = value;
+          }
+        }
+
+        violations.push(...collectScriptViolations(scripts));
+      }
+    }
+
+    for (const file of workflowFiles) {
+      const text = readFile(file);
+
+      if (text === null || !DRIZZLE_PUSH_PATTERN.test(text)) {
+        continue;
+      }
+
+      violations.push({
+        file,
+        ruleId: "production-must-not-use-drizzle-push",
+        severity: "warn",
+        message:
+          "Workflow runs `drizzle-kit push` — replace with checked-in migrations and `drizzle-kit migrate` for production schema changes.",
+      });
+    }
+
+    return violations;
+  },
+};

package/src/meta-rules/rules/supply-chain/single-package-manager.ts

@@ -0,0 +1,30 @@
+import type { IMetaRule, IMetaRuleViolation } from "../../meta-rules.types";
+import { detectPresentLockfiles } from "../../utils/lockfiles";
+
+export const singlePackageManagerRule: IMetaRule = {
+  id: "single-package-manager",
+  category: "supply-chain",
+  description:
+    "Do not mix lockfiles from different package managers in the same repo.",
+  severity: "warn",
+  run({ root }) {
+    const violations: IMetaRuleViolation[] = [];
+    const present = detectPresentLockfiles(root);
+    const managers = new Set(present.map((entry) => entry.manager));
+
+    if (managers.size <= 1) {
+      return violations;
+    }
+
+    const lockfileNames = present.map((entry) => entry.filename).join(", ");
+
+    violations.push({
+      file: "package.json",
+      ruleId: "single-package-manager",
+      severity: "warn",
+      message: `Mixed package manager lockfiles detected (${lockfileNames}) — keep one lockfile for a single package manager and delete the rest.`,
+    });
+
+    return violations;
+  },
+};

package/src/meta-rules/utils/lockfiles.ts

@@ -0,0 +1,105 @@
+import { join } from "node:path";
+import { statSync } from "node:fs";
+
+export type PackageManagerId = "npm" | "yarn" | "pnpm" | "bun";
+
+export interface ILockfileInfo {
+  readonly manager: PackageManagerId;
+  readonly filename: string;
+}
+
+export const LOCKFILES: readonly ILockfileInfo[] = [
+  { manager: "npm", filename: "package-lock.json" },
+  { manager: "yarn", filename: "yarn.lock" },
+  { manager: "pnpm", filename: "pnpm-lock.yaml" },
+  { manager: "bun", filename: "bun.lockb" },
+  { manager: "bun", filename: "bun.lock" },
+];
+
+const MANAGER_LOCKFILES: Readonly<Record<PackageManagerId, readonly string[]>> =
+  {
+    npm: ["package-lock.json"],
+    yarn: ["yarn.lock"],
+    pnpm: ["pnpm-lock.yaml"],
+    bun: ["bun.lockb", "bun.lock"],
+  };
+
+function fileExists(root: string, filename: string): boolean {
+  try {
+    return statSync(join(root, filename)).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/** Lockfiles present at the project root. */
+export function detectPresentLockfiles(root: string): ILockfileInfo[] {
+  const present: ILockfileInfo[] = [];
+
+  for (const lockfile of LOCKFILES) {
+    if (fileExists(root, lockfile.filename)) {
+      present.push(lockfile);
+    }
+  }
+
+  return present;
+}
+
+/** Parse `packageManager` field (e.g. bun@1.3.14) into a manager id. */
+export function parsePackageManagerField(
+  packageJson: Record<string, unknown> | null
+): PackageManagerId | null {
+  if (packageJson === null) {
+    return null;
+  }
+
+  const value = packageJson.packageManager;
+
+  if (typeof value !== "string" || value.length === 0) {
+    return null;
+  }
+
+  const manager = value.split("@")[0]?.trim();
+
+  if (
+    manager === "npm" ||
+    manager === "yarn" ||
+    manager === "pnpm" ||
+    manager === "bun"
+  ) {
+    return manager;
+  }
+
+  return null;
+}
+
+/** Resolve the canonical package manager for lockfile checks. */
+export function resolvePackageManager(
+  root: string,
+  packageJson: Record<string, unknown> | null
+): PackageManagerId | null {
+  const fromField = parsePackageManagerField(packageJson);
+
+  if (fromField !== null) {
+    return fromField;
+  }
+
+  const present = detectPresentLockfiles(root);
+  const managers = new Set(present.map((entry) => entry.manager));
+
+  if (managers.size === 1) {
+    return [...managers][0] ?? null;
+  }
+
+  return null;
+}
+
+/** Whether the root has a lockfile for the given package manager. */
+export function hasLockfileForManager(
+  root: string,
+  manager: PackageManagerId
+): boolean {
+  return MANAGER_LOCKFILES[manager].some((filename) =>
+    fileExists(root, filename)
+  );
+}

package/src/meta-rules/utils/workflow-yaml.ts

@@ -0,0 +1,86 @@
+export interface IJobBlock {
+  readonly name: string;
+  readonly lines: readonly string[];
+}
+
+const JOB_KEY_PATTERN = /^ {2}([\w-]+):\s*(?:#.*)?$/u;
+
+/** Collect job blocks from a GitHub Actions workflow YAML string. */
+export function collectJobBlocks(text: string): IJobBlock[] {
+  const lines = text.split("\n");
+  const blocks: IJobBlock[] = [];
+  let inJobs = false;
+  let current: { name: string; lines: string[] } | null = null;
+
+  for (const line of lines) {
+    if (/^jobs:\s*(?:#.*)?$/u.test(line)) {
+      inJobs = true;
+      continue;
+    }
+
+    if (!inJobs) {
+      continue;
+    }
+
+    if (/^\S/u.test(line)) {
+      inJobs = false;
+
+      if (current !== null) {
+        blocks.push(current);
+        current = null;
+      }
+
+      continue;
+    }
+
+    const jobMatch = JOB_KEY_PATTERN.exec(line);
+
+    if (jobMatch?.[1] !== undefined) {
+      if (current !== null) {
+        blocks.push(current);
+      }
+
+      current = { name: jobMatch[1], lines: [] };
+      continue;
+    }
+
+    if (current !== null) {
+      current.lines.push(line);
+    }
+  }
+
+  if (current !== null) {
+    blocks.push(current);
+  }
+
+  return blocks;
+}
+
+/** Whether the workflow declares top-level permissions. */
+export function hasWorkflowLevelPermissions(text: string): boolean {
+  return /^permissions:\s*(?:#.*)?$/mu.test(text);
+}
+
+/** Extract the top-level permissions block lines (excluding the header). */
+export function collectWorkflowPermissionsLines(text: string): string[] {
+  const lines = text.split("\n");
+  const block: string[] = [];
+  let inPermissions = false;
+
+  for (const line of lines) {
+    if (/^permissions:\s*(?:#.*)?$/u.test(line)) {
+      inPermissions = true;
+      continue;
+    }
+
+    if (inPermissions) {
+      if (/^\S/u.test(line)) {
+        break;
+      }
+
+      block.push(line);
+    }
+  }
+
+  return block;
+}

package/src/rule-packs/authorization/index.ts

@@ -0,0 +1,26 @@
+import type { TSESLint } from "@typescript-eslint/utils";
+
+import { idParamRequiresObjectAuthzRule } from "./rules/id-param-requires-object-authz";
+import { mutatingRouteRequiresAuthzRule } from "./rules/mutating-route-requires-authz";
+import { serverActionRequiresAuthzRule } from "./rules/server-action-requires-authz";
+import type { IRulePack } from "../rule-packs.types";
+
+const rules: Record<string, TSESLint.RuleModule<string, readonly unknown[]>> = {
+  "id-param-requires-object-authz": idParamRequiresObjectAuthzRule,
+  "mutating-route-requires-authz": mutatingRouteRequiresAuthzRule,
+  "server-action-requires-authz": serverActionRequiresAuthzRule,
+};
+
+export const authorizationPack: IRulePack = {
+  id: "authorization",
+  description:
+    "Experimental authorization heuristics for route handlers, server actions, and id-scoped database access.",
+  rules,
+  rulesConfig: {
+    "mutating-route-requires-authz": "error",
+    "server-action-requires-authz": "error",
+    "id-param-requires-object-authz": "warn",
+  },
+};
+
+export default authorizationPack;

package/src/rule-packs/authorization/rules/id-param-requires-object-authz.ts

@@ -0,0 +1,87 @@
+import { AST_NODE_TYPES } from "@typescript-eslint/utils";
+
+import { createRule } from "../../create-rule";
+import { walkSome } from "../../utils";
+import {
+  authzOptionSchema,
+  containsAuthzCall,
+  defaultAuthzOptions,
+  getFunctionLikeBody,
+  isDbQueryCall,
+  isParamsIdRead,
+  resolveAuthzFunctions,
+  type AuthzRuleOptions,
+  type FunctionLike,
+} from "../utils";
+
+export const RULE_NAME = "id-param-requires-object-authz";
+
+type MessageIds = "missingObjectAuthz";
+
+function analyzeFunction(
+  node: FunctionLike,
+  authzNames: Set<string>
+): { hasParamsId: boolean; hasDbQuery: boolean; hasAuthz: boolean } {
+  const body = getFunctionLikeBody(node);
+
+  if (body === null) {
+    return { hasParamsId: false, hasDbQuery: false, hasAuthz: false };
+  }
+
+  return {
+    hasParamsId: walkSome(body, isParamsIdRead),
+    hasDbQuery: walkSome(body, (child) => {
+      if (child.type !== AST_NODE_TYPES.CallExpression) {
+        return false;
+      }
+
+      return isDbQueryCall(child);
+    }),
+    hasAuthz: containsAuthzCall(body, authzNames),
+  };
+}
+
+export const idParamRequiresObjectAuthzRule = createRule<
+  AuthzRuleOptions,
+  MessageIds
+>({
+  name: RULE_NAME,
+  meta: {
+    type: "suggestion",
+    docs: {
+      description:
+        "Warn when a handler reads `params.id` and queries the database without an authorization check in the same function.",
+    },
+    schema: [authzOptionSchema],
+    messages: {
+      missingObjectAuthz:
+        "Reading `params.id` and querying the database in the same function requires object-level authorization (e.g. {{examples}}).",
+    },
+  },
+  defaultOptions: [defaultAuthzOptions()],
+  create(context, [options]) {
+    const authzNames = resolveAuthzFunctions(options);
+    const examples = [...authzNames].slice(0, 2).join(", ");
+
+    function visitFunction(node: FunctionLike): void {
+      const { hasParamsId, hasDbQuery, hasAuthz } = analyzeFunction(
+        node,
+        authzNames
+      );
+
+      if (hasParamsId && hasDbQuery && !hasAuthz) {
+        context.report({
+          node,
+          messageId: "missingObjectAuthz",
+          data: { examples },
+        });
+      }
+    }
+
+    return {
+      FunctionDeclaration: visitFunction,
+      FunctionExpression: visitFunction,
+      ArrowFunctionExpression: visitFunction,
+    };
+  },
+});

package/src/rule-packs/authorization/rules/mutating-route-requires-authz.ts

@@ -0,0 +1,116 @@
+import { AST_NODE_TYPES, type TSESTree } from "@typescript-eslint/utils";
+
+import { createRule } from "../../create-rule";
+import {
+  authzOptionSchema,
+  containsAuthzCall,
+  defaultAuthzOptions,
+  getExportedMutatingHandlerName,
+  getFunctionLikeBody,
+  isRouteHandlerFile,
+  resolveAuthzFunctions,
+  type AuthzRuleOptions,
+  type FunctionLike,
+} from "../utils";
+
+export const RULE_NAME = "mutating-route-requires-authz";
+
+type MessageIds = "missingAuthz";
+
+function getHandlerFunction(node: TSESTree.Node): FunctionLike | null {
+  if (node.type === AST_NODE_TYPES.ExportNamedDeclaration) {
+    const declaration = node.declaration;
+
+    if (
+      declaration?.type === AST_NODE_TYPES.FunctionDeclaration &&
+      declaration.body !== null
+    ) {
+      return declaration;
+    }
+
+    if (declaration?.type === AST_NODE_TYPES.VariableDeclaration) {
+      for (const declarator of declaration.declarations) {
+        const init = declarator.init;
+
+        if (
+          init?.type === AST_NODE_TYPES.FunctionExpression ||
+          init?.type === AST_NODE_TYPES.ArrowFunctionExpression
+        ) {
+          return init;
+        }
+      }
+    }
+
+    return null;
+  }
+
+  if (node.type === AST_NODE_TYPES.FunctionDeclaration && node.body !== null) {
+    return node;
+  }
+
+  return null;
+}
+
+export const mutatingRouteRequiresAuthzRule = createRule<
+  AuthzRuleOptions,
+  MessageIds
+>({
+  name: RULE_NAME,
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "POST/PUT/PATCH/DELETE route handlers must call an authorization helper before mutating state.",
+    },
+    schema: [authzOptionSchema],
+    messages: {
+      missingAuthz:
+        "Mutating route handler `{{method}}` must call an authorization helper (e.g. {{examples}}) before performing writes.",
+    },
+  },
+  defaultOptions: [defaultAuthzOptions()],
+  create(context, [options]) {
+    const authzNames = resolveAuthzFunctions(options);
+    const examples = [...authzNames].slice(0, 2).join(", ");
+
+    function reportMissingAuthz(node: TSESTree.Node, method: string): void {
+      context.report({
+        node,
+        messageId: "missingAuthz",
+        data: { method, examples },
+      });
+    }
+
+    function checkHandler(exportNode: TSESTree.Node, method: string): void {
+      const handler = getHandlerFunction(exportNode);
+
+      if (handler === null) {
+        return;
+      }
+
+      const body = getFunctionLikeBody(handler);
+
+      if (body === null || containsAuthzCall(body, authzNames)) {
+        return;
+      }
+
+      reportMissingAuthz(exportNode, method);
+    }
+
+    return {
+      ExportNamedDeclaration(node: TSESTree.ExportNamedDeclaration) {
+        if (!isRouteHandlerFile(context.filename)) {
+          return;
+        }
+
+        const method = getExportedMutatingHandlerName(node);
+
+        if (method === null) {
+          return;
+        }
+
+        checkHandler(node, method);
+      },
+    };
+  },
+});

package/src/rule-packs/authorization/rules/server-action-requires-authz.ts

@@ -0,0 +1,101 @@
+import { AST_NODE_TYPES, type TSESTree } from "@typescript-eslint/utils";
+
+import { createRule } from "../../create-rule";
+import { walkSome } from "../../utils";
+import {
+  authzOptionSchema,
+  containsAuthzCall,
+  defaultAuthzOptions,
+  getFunctionLikeBody,
+  hasUseServerDirective,
+  isDbMutationCall,
+  resolveAuthzFunctions,
+  type AuthzRuleOptions,
+  type FunctionLike,
+} from "../utils";
+
+export const RULE_NAME = "server-action-requires-authz";
+
+type MessageIds = "missingAuthz";
+
+function getFunctionName(node: FunctionLike): string {
+  if (node.type === AST_NODE_TYPES.FunctionDeclaration && node.id !== null) {
+    return node.id.name;
+  }
+
+  const parent = node.parent;
+
+  if (
+    parent?.type === AST_NODE_TYPES.VariableDeclarator &&
+    parent.id.type === AST_NODE_TYPES.Identifier
+  ) {
+    return parent.id.name;
+  }
+
+  return "server action";
+}
+
+export const serverActionRequiresAuthzRule = createRule<
+  AuthzRuleOptions,
+  MessageIds
+>({
+  name: RULE_NAME,
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        'Files with `"use server"` that perform database mutations must call an authorization helper in the same function.',
+    },
+    schema: [authzOptionSchema],
+    messages: {
+      missingAuthz:
+        'Server action "{{name}}" performs a database mutation but does not call an authorization helper (e.g. {{examples}}).',
+    },
+  },
+  defaultOptions: [defaultAuthzOptions()],
+  create(context, [options]) {
+    const authzNames = resolveAuthzFunctions(options);
+    const examples = [...authzNames].slice(0, 2).join(", ");
+    let useServerFile = false;
+
+    function visitFunction(node: FunctionLike): void {
+      if (!useServerFile) {
+        return;
+      }
+
+      const body = getFunctionLikeBody(node);
+
+      if (body === null) {
+        return;
+      }
+
+      const hasMutation = walkSome(
+        body,
+        (child) =>
+          child.type === AST_NODE_TYPES.CallExpression &&
+          isDbMutationCall(child)
+      );
+      const hasAuthz = containsAuthzCall(body, authzNames);
+
+      if (hasMutation && !hasAuthz) {
+        context.report({
+          node,
+          messageId: "missingAuthz",
+          data: {
+            name: getFunctionName(node),
+            examples,
+          },
+        });
+      }
+    }
+
+    return {
+      Program(node: TSESTree.Program) {
+        useServerFile = hasUseServerDirective(node);
+      },
+      FunctionDeclaration: visitFunction,
+      FunctionExpression: visitFunction,
+      ArrowFunctionExpression: visitFunction,
+    };
+  },
+});