@agjs/tsforge 0.1.19 → 0.2.1

package/src/meta-rules/rules/ci/workflow-permissions-least-privilege.ts

@@ -0,0 +1,44 @@
+import type { IMetaRule, IMetaRuleViolation } from "../../meta-rules.types";
+import {
+  collectWorkflowPermissionsLines,
+  hasWorkflowLevelPermissions,
+} from "../../utils/workflow-yaml";
+
+const BROAD_PERMISSION_PATTERN =
+  /^ {2}(?:contents|id-token):\s*write\s*(?:#.*)?$/u;
+
+export const workflowPermissionsLeastPrivilegeRule: IMetaRule = {
+  id: "workflow-permissions-least-privilege",
+  category: "ci",
+  description:
+    "Warn when workflow-level permissions grant contents: write or id-token: write.",
+  severity: "warn",
+  run({ workflowFiles, readFile }) {
+    const violations: IMetaRuleViolation[] = [];
+
+    for (const file of workflowFiles) {
+      const text = readFile(file);
+
+      if (text === null || !hasWorkflowLevelPermissions(text)) {
+        continue;
+      }
+
+      const permissionLines = collectWorkflowPermissionsLines(text);
+
+      for (const line of permissionLines) {
+        if (!BROAD_PERMISSION_PATTERN.test(line)) {
+          continue;
+        }
+
+        violations.push({
+          file,
+          ruleId: "workflow-permissions-least-privilege",
+          severity: "warn",
+          message: `Workflow-level \`${line.trim()}\` is broader than necessary — scope write permissions to the job that needs them instead of the whole workflow.`,
+        });
+      }
+    }
+
+    return violations;
+  },
+};

package/src/meta-rules/rules/config/next-image-remote-patterns-no-wildcards.ts

@@ -0,0 +1,77 @@
+import { parsePackageJsonObject } from "../../parsers/package-json-parser";
+import type { IMetaRule, IMetaRuleViolation } from "../../meta-rules.types";
+
+const NEXT_CONFIG_PATHS = [
+  "next.config.ts",
+  "next.config.js",
+  "next.config.mjs",
+  "next.config.cjs",
+] as const;
+
+const WILDCARD_HOSTNAME_PATTERN =
+  /hostname\s*:\s*['"`]\*\*['"`]|hostname\s*:\s*['"`][^'"`]*\*[^'"`]*['"`]/;
+
+function hasNextDependency(
+  packageJson: Record<string, unknown> | null
+): boolean {
+  if (packageJson === null) {
+    return false;
+  }
+
+  const parsed = parsePackageJsonObject(packageJson);
+
+  if (parsed === null) {
+    return false;
+  }
+
+  const merged: Record<string, string> = {
+    ...(parsed.dependencies ?? {}),
+    ...(parsed.devDependencies ?? {}),
+  };
+
+  return merged.next !== undefined;
+}
+
+function configContainsWildcardRemotePattern(content: string): boolean {
+  if (!content.includes("remotePatterns")) {
+    return false;
+  }
+
+  return WILDCARD_HOSTNAME_PATTERN.test(content);
+}
+
+export const nextImageRemotePatternsNoWildcardsRule: IMetaRule = {
+  id: "next-image-remote-patterns-no-wildcards",
+  category: "config",
+  description:
+    "Disallow wildcard hostnames in `images.remotePatterns` — overly broad patterns enable SSRF via next/image.",
+  severity: "error",
+  appliesTo: ["nextjs"],
+  run({ packageJson, readFile }) {
+    const violations: IMetaRuleViolation[] = [];
+
+    if (!hasNextDependency(packageJson)) {
+      return violations;
+    }
+
+    for (const path of NEXT_CONFIG_PATHS) {
+      const content = readFile(path);
+
+      if (content === null) {
+        continue;
+      }
+
+      if (configContainsWildcardRemotePattern(content)) {
+        violations.push({
+          file: path,
+          ruleId: "next-image-remote-patterns-no-wildcards",
+          severity: "error",
+          message:
+            "`images.remotePatterns` contains a wildcard hostname — list explicit hostnames instead of `**` or `*`-patterns to reduce SSRF risk.",
+        });
+      }
+    }
+
+    return violations;
+  },
+};

package/src/meta-rules/rules/config/next-instrumentation-present.ts

@@ -0,0 +1,66 @@
+import { parsePackageJsonObject } from "../../parsers/package-json-parser";
+import type { IMetaRule, IMetaRuleViolation } from "../../meta-rules.types";
+
+function hasNextDependency(
+  packageJson: Record<string, unknown> | null
+): boolean {
+  if (packageJson === null) {
+    return false;
+  }
+
+  const parsed = parsePackageJsonObject(packageJson);
+
+  if (parsed === null) {
+    return false;
+  }
+
+  const merged: Record<string, string> = {
+    ...(parsed.dependencies ?? {}),
+    ...(parsed.devDependencies ?? {}),
+  };
+
+  return merged.next !== undefined;
+}
+
+function hasAppRouter(sourceFiles: readonly string[]): boolean {
+  return sourceFiles.some(
+    (file) => file.startsWith("app/") || file.startsWith("src/app/")
+  );
+}
+
+export const nextInstrumentationPresentRule: IMetaRule = {
+  id: "next-instrumentation-present",
+  category: "config",
+  description:
+    "Recommend instrumentation.ts for OpenTelemetry when using the Next.js app router.",
+  severity: "warn",
+  appliesTo: ["nextjs"],
+  run({ packageJson, sourceFiles, readFile }) {
+    const violations: IMetaRuleViolation[] = [];
+
+    if (!hasNextDependency(packageJson) || !hasAppRouter(sourceFiles)) {
+      return violations;
+    }
+
+    const instrumentationPaths = [
+      "instrumentation.ts",
+      "src/instrumentation.ts",
+    ] as const;
+
+    const hasInstrumentation = instrumentationPaths.some(
+      (path) => readFile(path) !== null
+    );
+
+    if (!hasInstrumentation) {
+      violations.push({
+        file: "instrumentation.ts",
+        ruleId: "next-instrumentation-present",
+        severity: "warn",
+        message:
+          "Add instrumentation.ts at the project root (or src/) with registerOTel for OpenTelemetry tracing of Server Components and route handlers.",
+      });
+    }
+
+    return violations;
+  },
+};

package/src/meta-rules/rules/config/next-proxy-over-middleware.ts

@@ -0,0 +1,64 @@
+import { parsePackageJsonObject } from "../../parsers/package-json-parser";
+import type { IMetaRule, IMetaRuleViolation } from "../../meta-rules.types";
+
+function hasNextDependency(
+  packageJson: Record<string, unknown> | null
+): boolean {
+  if (packageJson === null) {
+    return false;
+  }
+
+  const parsed = parsePackageJsonObject(packageJson);
+
+  if (parsed === null) {
+    return false;
+  }
+
+  const merged: Record<string, string> = {
+    ...(parsed.dependencies ?? {}),
+    ...(parsed.devDependencies ?? {}),
+  };
+
+  return merged.next !== undefined;
+}
+
+function fileExists(
+  readFile: (relPath: string) => string | null,
+  paths: readonly string[]
+): boolean {
+  return paths.some((path) => readFile(path) !== null);
+}
+
+export const nextProxyOverMiddlewareRule: IMetaRule = {
+  id: "next-proxy-over-middleware",
+  category: "config",
+  description:
+    "When using Next.js 16+, prefer proxy.ts over legacy middleware.ts for early request interception.",
+  severity: "warn",
+  appliesTo: ["nextjs"],
+  run({ packageJson, readFile }) {
+    const violations: IMetaRuleViolation[] = [];
+
+    if (!hasNextDependency(packageJson)) {
+      return violations;
+    }
+
+    const middlewarePaths = ["middleware.ts", "src/middleware.ts"] as const;
+    const proxyPaths = ["proxy.ts", "src/proxy.ts"] as const;
+
+    const hasMiddleware = fileExists(readFile, middlewarePaths);
+    const hasProxy = fileExists(readFile, proxyPaths);
+
+    if (hasMiddleware && !hasProxy) {
+      violations.push({
+        file: "middleware.ts",
+        ruleId: "next-proxy-over-middleware",
+        severity: "warn",
+        message:
+          "middleware.ts is legacy — migrate early request interception to proxy.ts (Next.js 16 Node.js-native routing boundary).",
+      });
+    }
+
+    return violations;
+  },
+};

package/src/meta-rules/rules/config/tsconfig-recommended-flags.ts

@@ -0,0 +1,75 @@
+import { join } from "node:path";
+import { readFileSync, statSync } from "node:fs";
+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;
+}
+
+/** Strip block and line comments from JSON before parsing. */
+function stripJsonComments(text: string): string {
+  return text
+    .replace(/\/\*[\s\S]*?\*\//gu, "")
+    .replace(/^\s*\/\/.*$/gmu, "")
+    .replace(/,\s*([\]}])/gu, "$1");
+}
+
+const RECOMMENDED_FLAGS: readonly { flag: string; label: string }[] = [
+  { flag: "useUnknownInCatchVariables", label: "useUnknownInCatchVariables" },
+  { flag: "erasableSyntaxOnly", label: "erasableSyntaxOnly" },
+  { flag: "exactOptionalPropertyTypes", label: "exactOptionalPropertyTypes" },
+  { flag: "verbatimModuleSyntax", label: "verbatimModuleSyntax" },
+  {
+    flag: "noPropertyAccessFromIndexSignature",
+    label: "noPropertyAccessFromIndexSignature",
+  },
+];
+
+export const tsconfigRecommendedFlagsRule: IMetaRule = {
+  id: "tsconfig-recommended-flags",
+  category: "config",
+  description:
+    "tsconfig.json should enable recommended strict-adjacent compiler flags (useUnknownInCatchVariables, erasableSyntaxOnly, exactOptionalPropertyTypes, verbatimModuleSyntax, noPropertyAccessFromIndexSignature).",
+  severity: "warn",
+  run({ root }) {
+    const violations: IMetaRuleViolation[] = [];
+    const tsconfigPath = join(root, "tsconfig.json");
+
+    try {
+      statSync(tsconfigPath);
+    } catch {
+      return violations;
+    }
+
+    try {
+      const text = readFileSync(tsconfigPath, "utf8");
+      const parsed: unknown = JSON.parse(stripJsonComments(text));
+
+      if (!isRecord(parsed)) {
+        return violations;
+      }
+
+      const compilerOptions = parsed.compilerOptions;
+
+      if (!isRecord(compilerOptions)) {
+        return violations;
+      }
+
+      for (const { flag, label } of RECOMMENDED_FLAGS) {
+        if (compilerOptions[flag] !== true) {
+          violations.push({
+            file: "tsconfig.json",
+            ruleId: "tsconfig-recommended-flags",
+            severity: "warn",
+            message: `tsconfig.json compilerOptions should set "${label}": true for stricter, more predictable TypeScript behavior.`,
+          });
+        }
+      }
+    } catch {
+      // Invalid JSON or file read error — skip this check
+    }
+
+    return violations;
+  },
+};

package/src/meta-rules/rules/supply-chain/dependency-overrides-require-comment.ts

@@ -0,0 +1,61 @@
+import type { IMetaRule, IMetaRuleViolation } from "../../meta-rules.types";
+
+const OVERRIDE_KEY_PATTERN = /^(\s*)"(?:overrides|resolutions)"\s*:/u;
+const LINE_COMMENT_PATTERN = /^\s*\/\/.*$/u;
+
+function hasAdjacentComment(lines: readonly string[], index: number): boolean {
+  const line = lines[index];
+
+  if (line === undefined) {
+    return false;
+  }
+
+  if (/\/\/.*$/u.test(line)) {
+    return true;
+  }
+
+  const previous = lines[index - 1];
+
+  return previous !== undefined && LINE_COMMENT_PATTERN.test(previous);
+}
+
+export const dependencyOverridesRequireCommentRule: IMetaRule = {
+  id: "dependency-overrides-require-comment",
+  category: "supply-chain",
+  description:
+    "overrides/resolutions in package.json must include an adjacent comment explaining why.",
+  severity: "warn",
+  run({ readFile }) {
+    const violations: IMetaRuleViolation[] = [];
+    const text = readFile("package.json");
+
+    if (text === null) {
+      return violations;
+    }
+
+    const lines = text.split("\n");
+
+    for (let index = 0; index < lines.length; index += 1) {
+      const line = lines[index];
+
+      if (line === undefined || !OVERRIDE_KEY_PATTERN.test(line)) {
+        continue;
+      }
+
+      if (hasAdjacentComment(lines, index)) {
+        continue;
+      }
+
+      const keyName = line.includes("overrides") ? "overrides" : "resolutions";
+
+      violations.push({
+        file: "package.json",
+        ruleId: "dependency-overrides-require-comment",
+        severity: "warn",
+        message: `"${keyName}" is declared without an adjacent comment — document why the override is required (security patch, upstream bug, etc.).`,
+      });
+    }
+
+    return violations;
+  },
+};

package/src/meta-rules/rules/supply-chain/fastify-security-plugins.ts

@@ -0,0 +1,54 @@
+import { parsePackageJsonObject } from "../../parsers/package-json-parser";
+import type { IMetaRule, IMetaRuleViolation } from "../../meta-rules.types";
+
+const SECURITY_PLUGINS = [
+  "@fastify/helmet",
+  "@fastify/cors",
+  "@fastify/rate-limit",
+] as const;
+
+export const fastifySecurityPluginsRule: IMetaRule = {
+  id: "fastify-security-plugins",
+  category: "supply-chain",
+  description:
+    "When fastify is a dependency, recommend official security plugins (@fastify/helmet, @fastify/cors, @fastify/rate-limit).",
+  severity: "warn",
+  appliesTo: ["fastify"],
+  run({ packageJson }) {
+    const violations: IMetaRuleViolation[] = [];
+
+    if (packageJson === null) {
+      return violations;
+    }
+
+    const parsed = parsePackageJsonObject(packageJson);
+
+    if (parsed === null) {
+      return violations;
+    }
+
+    const merged: Record<string, string> = {
+      ...(parsed.dependencies ?? {}),
+      ...(parsed.devDependencies ?? {}),
+    };
+
+    if (merged.fastify === undefined) {
+      return violations;
+    }
+
+    const missing = SECURITY_PLUGINS.filter((pkg) => merged[pkg] === undefined);
+
+    if (missing.length === 0) {
+      return violations;
+    }
+
+    violations.push({
+      file: "package.json",
+      ruleId: "fastify-security-plugins",
+      severity: "warn",
+      message: `fastify is listed but security plugins are missing: ${missing.join(", ")}. Register @fastify/helmet, @fastify/cors, and @fastify/rate-limit at the production boundary.`,
+    });
+
+    return violations;
+  },
+};

package/src/meta-rules/rules/supply-chain/lockfile-required.ts

@@ -0,0 +1,51 @@
+import type { IMetaRule, IMetaRuleViolation } from "../../meta-rules.types";
+import {
+  detectPresentLockfiles,
+  hasLockfileForManager,
+  resolvePackageManager,
+} from "../../utils/lockfiles";
+
+const MANAGER_LABELS = {
+  npm: "package-lock.json",
+  yarn: "yarn.lock",
+  pnpm: "pnpm-lock.yaml",
+  bun: "bun.lockb or bun.lock",
+} as const;
+
+export const lockfileRequiredRule: IMetaRule = {
+  id: "lockfile-required",
+  category: "supply-chain",
+  description:
+    "Projects must commit exactly one lockfile matching the detected package manager.",
+  severity: "warn",
+  run({ root, packageJson }) {
+    const violations: IMetaRuleViolation[] = [];
+    const manager = resolvePackageManager(root, packageJson);
+    const present = detectPresentLockfiles(root);
+
+    if (manager === null) {
+      if (present.length === 0) {
+        violations.push({
+          file: "package.json",
+          ruleId: "lockfile-required",
+          severity: "warn",
+          message:
+            "No lockfile found — add the lockfile for your package manager (package-lock.json, yarn.lock, pnpm-lock.yaml, or bun.lockb) and set packageManager in package.json.",
+        });
+      }
+
+      return violations;
+    }
+
+    if (!hasLockfileForManager(root, manager)) {
+      violations.push({
+        file: "package.json",
+        ruleId: "lockfile-required",
+        severity: "warn",
+        message: `Detected package manager "${manager}" but missing ${MANAGER_LABELS[manager]} — commit the lockfile produced by your package manager.`,
+      });
+    }
+
+    return violations;
+  },
+};

package/src/meta-rules/rules/supply-chain/migrations-must-be-checked-in.ts

@@ -0,0 +1,49 @@
+import { join } from "node:path";
+import { readdirSync, statSync } from "node:fs";
+import type { IMetaRule, IMetaRuleViolation } from "../../meta-rules.types";
+
+const MIGRATION_DIRS = ["drizzle", "migrations"] as const;
+
+function directoryHasFiles(root: string, relDir: string): boolean {
+  try {
+    const stat = statSync(join(root, relDir));
+
+    if (!stat.isDirectory()) {
+      return false;
+    }
+
+    return readdirSync(join(root, relDir)).length > 0;
+  } catch {
+    return false;
+  }
+}
+
+export const migrationsMustBeCheckedInRule: IMetaRule = {
+  id: "migrations-must-be-checked-in",
+  category: "supply-chain",
+  description:
+    "When using Drizzle, commit SQL migrations under drizzle/ or migrations/.",
+  severity: "warn",
+  appliesTo: ["drizzle"],
+  run({ root }) {
+    const violations: IMetaRuleViolation[] = [];
+
+    const hasMigrationDir = MIGRATION_DIRS.some((dir) =>
+      directoryHasFiles(root, dir)
+    );
+
+    if (hasMigrationDir) {
+      return violations;
+    }
+
+    violations.push({
+      file: "drizzle/",
+      ruleId: "migrations-must-be-checked-in",
+      severity: "warn",
+      message:
+        "No checked-in Drizzle migrations found — add a drizzle/ or migrations/ folder with generated SQL migration files.",
+    });
+
+    return violations;
+  },
+};

package/src/meta-rules/rules/supply-chain/no-git-or-tarball-dependencies.ts

@@ -0,0 +1,70 @@
+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 REMOTE_DEP_PATTERN =
+  /^(?:git\+|git:|http:|https:\/\/(?!registry\.npmjs\.org))/iu;
+
+const DEP_SECTIONS = [
+  "dependencies",
+  "devDependencies",
+  "optionalDependencies",
+  "peerDependencies",
+] as const;
+
+function toStringRecord(value: unknown): Record<string, string> | undefined {
+  if (!isRecord(value)) {
+    return undefined;
+  }
+
+  const out: Record<string, string> = {};
+
+  for (const [key, entry] of Object.entries(value)) {
+    if (typeof entry === "string") {
+      out[key] = entry;
+    }
+  }
+
+  return out;
+}
+
+export const noGitOrTarballDependenciesRule: IMetaRule = {
+  id: "no-git-or-tarball-dependencies",
+  category: "supply-chain",
+  description:
+    "Warn on git+, git:, or http(s) tarball dependency URLs in package.json.",
+  severity: "warn",
+  run({ packageJson }) {
+    const violations: IMetaRuleViolation[] = [];
+
+    if (packageJson === null) {
+      return violations;
+    }
+
+    for (const section of DEP_SECTIONS) {
+      const entries = toStringRecord(packageJson[section]);
+
+      if (entries === undefined) {
+        continue;
+      }
+
+      for (const [name, spec] of Object.entries(entries)) {
+        if (!REMOTE_DEP_PATTERN.test(spec)) {
+          continue;
+        }
+
+        violations.push({
+          file: "package.json",
+          ruleId: "no-git-or-tarball-dependencies",
+          severity: "warn",
+          message: `${section}.${name} uses remote URL "${spec}" — prefer registry versions for reproducible installs and supply-chain auditing.`,
+        });
+      }
+    }
+
+    return violations;
+  },
+};

package/src/meta-rules/rules/supply-chain/package-manager-field-required.ts

@@ -0,0 +1,31 @@
+import type { IMetaRule, IMetaRuleViolation } from "../../meta-rules.types";
+
+export const packageManagerFieldRequiredRule: IMetaRule = {
+  id: "package-manager-field-required",
+  category: "supply-chain",
+  description: "package.json must declare a packageManager field.",
+  severity: "warn",
+  run({ packageJson }) {
+    const violations: IMetaRuleViolation[] = [];
+
+    if (packageJson === null) {
+      return violations;
+    }
+
+    const value = packageJson.packageManager;
+
+    if (typeof value === "string" && value.trim().length > 0) {
+      return violations;
+    }
+
+    violations.push({
+      file: "package.json",
+      ruleId: "package-manager-field-required",
+      severity: "warn",
+      message:
+        'Add a "packageManager" field to package.json (e.g. "bun@1.3.14") so CI and contributors use the same package manager.',
+    });
+
+    return violations;
+  },
+};