@agjs/tsforge 0.1.0

package/src/rule-packs/react-component-architecture/rules/forwardref-display-name.ts

@@ -0,0 +1,93 @@
+import { AST_NODE_TYPES, type TSESTree } from "@typescript-eslint/utils";
+
+import { createRule } from "../../create-rule";
+
+export const RULE_NAME = "forwardref-display-name";
+
+type RuleOptions = [];
+type MessageIds = "missingDisplayName";
+
+export const forwardrefDisplayNameRule = createRule<RuleOptions, MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: "problem",
+    docs: {
+      description: "forwardRef components must have displayName set",
+    },
+    schema: [],
+    messages: {
+      missingDisplayName:
+        'Component using forwardRef must have displayName set: {{name}}.displayName = "..."',
+    },
+  },
+  defaultOptions: [],
+  create(context) {
+    const forwardRefVars = new Set<string>();
+
+    return {
+      "VariableDeclarator > CallExpression"(node: TSESTree.CallExpression) {
+        // Check if calling forwardRef or React.forwardRef
+        const callee = node.callee;
+        let isForwardRef = false;
+
+        if (callee.type === AST_NODE_TYPES.Identifier) {
+          isForwardRef = callee.name === "forwardRef";
+        } else if (
+          callee.type === AST_NODE_TYPES.MemberExpression &&
+          callee.object.type === AST_NODE_TYPES.Identifier &&
+          callee.object.name === "React" &&
+          callee.property.type === AST_NODE_TYPES.Identifier &&
+          callee.property.name === "forwardRef"
+        ) {
+          isForwardRef = true;
+        }
+
+        if (
+          isForwardRef &&
+          node.parent?.type === AST_NODE_TYPES.VariableDeclarator
+        ) {
+          const decl = node.parent;
+
+          if (decl.id.type === AST_NODE_TYPES.Identifier) {
+            forwardRefVars.add(decl.id.name);
+          }
+        }
+      },
+
+      "Program:exit"(program) {
+        const displayNameAssignments = new Set<string>();
+
+        // Find all displayName assignments
+        for (const stmt of program.body) {
+          if (stmt.type === AST_NODE_TYPES.ExpressionStatement) {
+            const expr = stmt.expression;
+
+            if (expr.type === AST_NODE_TYPES.AssignmentExpression) {
+              const left = expr.left;
+
+              if (
+                left.type === AST_NODE_TYPES.MemberExpression &&
+                left.object.type === AST_NODE_TYPES.Identifier &&
+                left.property.type === AST_NODE_TYPES.Identifier &&
+                left.property.name === "displayName"
+              ) {
+                displayNameAssignments.add(left.object.name);
+              }
+            }
+          }
+        }
+
+        // Report missing displayName for forwardRef vars
+        for (const varName of forwardRefVars) {
+          if (!displayNameAssignments.has(varName)) {
+            context.report({
+              node: program,
+              messageId: "missingDisplayName",
+              data: { name: varName },
+            });
+          }
+        }
+      },
+    };
+  },
+});

package/src/rule-packs/react-component-architecture/rules/index-must-reexport-default.ts

@@ -0,0 +1,123 @@
+import { AST_NODE_TYPES } from "@typescript-eslint/utils";
+import { existsSync } from "fs";
+import { dirname, join } from "path";
+
+import { createRule } from "../../create-rule";
+
+export const RULE_NAME = "index-must-reexport-default";
+
+type RuleOptions = [];
+type MessageIds = "mustReexport" | "unexpectedStatement";
+
+const isIndexFile = (filename: string): boolean => {
+  const basename = filename.split("/").pop();
+
+  return basename === "index.ts" || basename === "index.tsx";
+};
+
+const getParentComponentName = (filename: string): string | null => {
+  const dir = dirname(filename);
+  const basename = dir.split("/").pop();
+
+  if (!basename || !/^[A-Z]/.test(basename)) {
+    return null;
+  }
+
+  return basename;
+};
+
+const componentFileExists = (dir: string, name: string): boolean => {
+  return existsSync(join(dir, `${name}.tsx`));
+};
+
+export const indexMustReexportDefaultRule = createRule<RuleOptions, MessageIds>(
+  {
+    name: RULE_NAME,
+    meta: {
+      type: "problem",
+      docs: {
+        description:
+          "index.ts in component folders must re-export the component default export and types",
+      },
+      schema: [],
+      messages: {
+        mustReexport:
+          'index.ts must contain re-export: export {{ default as {{name}} }} from "./{{name}}";',
+        unexpectedStatement:
+          "Unexpected statement in index.ts - only re-exports are allowed",
+      },
+    },
+    defaultOptions: [],
+    create(context) {
+      const filename = context.filename;
+
+      if (!isIndexFile(filename)) {
+        return {};
+      }
+
+      const componentName = getParentComponentName(filename);
+
+      if (!componentName) {
+        return {};
+      }
+
+      const dir = dirname(filename);
+
+      if (!componentFileExists(dir, componentName)) {
+        return {};
+      }
+
+      return {
+        "Program:exit"(program) {
+          let foundDefaultExport = false;
+
+          for (const stmt of program.body) {
+            if (
+              stmt.type === AST_NODE_TYPES.ExportNamedDeclaration &&
+              stmt.declaration === null
+            ) {
+              // Check for default re-export
+              if (stmt.specifiers.length > 0) {
+                const spec = stmt.specifiers[0];
+
+                if (
+                  spec?.type === AST_NODE_TYPES.ExportSpecifier &&
+                  spec.exported?.type === AST_NODE_TYPES.Identifier &&
+                  spec.exported.name === componentName &&
+                  spec.local?.type === AST_NODE_TYPES.Identifier &&
+                  spec.local.name === "default"
+                ) {
+                  foundDefaultExport = true;
+                }
+              }
+
+              // Type re-exports are OK too
+              continue;
+            }
+
+            if (stmt.type === AST_NODE_TYPES.ExportAllDeclaration) {
+              // Type re-exports like export * from "./<Name>.types"
+              continue;
+            }
+
+            // Any other statement is not allowed
+            if (stmt.type !== AST_NODE_TYPES.ExportNamedDeclaration) {
+              context.report({
+                node: stmt,
+                messageId: "unexpectedStatement",
+              });
+            }
+          }
+
+          if (!foundDefaultExport) {
+            context.report({
+              node: program,
+              messageId: "mustReexport",
+              data: { name: componentName },
+            });
+          }
+        },
+      };
+    },
+  }
+);

package/src/rule-packs/react-component-architecture/rules/max-hooks-per-file.ts

@@ -0,0 +1,122 @@
+import { AST_NODE_TYPES, type TSESTree } from "@typescript-eslint/utils";
+import type { JSONSchema4 } from "@typescript-eslint/utils/json-schema";
+
+import { createRule } from "../../create-rule";
+
+export const RULE_NAME = "max-hooks-per-file";
+
+export interface MaxHooksPerFileOptions {
+  readonly threshold?: number;
+  readonly filePattern?: string;
+}
+
+type RuleOptions = [MaxHooksPerFileOptions];
+type MessageIds = "tooManyHooks";
+
+const DEFAULT_THRESHOLD = 4;
+const DEFAULT_FILE_PATTERN = "\\.(queries|hooks|mutations)\\.tsx?$";
+
+const optionSchema: JSONSchema4 = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    threshold: { type: "integer", minimum: 1 },
+    filePattern: { type: "string", minLength: 1 },
+  },
+};
+
+function isHookName(name: string): boolean {
+  if (name.length < 4 || !name.startsWith("use")) {
+    return false;
+  }
+
+  const fourth = name[3];
+
+  return fourth !== undefined && /^[A-Z]/.test(fourth);
+}
+
+function collectExportedHookName(
+  statement: TSESTree.ProgramStatement
+): string | null {
+  if (statement.type !== AST_NODE_TYPES.ExportNamedDeclaration) {
+    return null;
+  }
+
+  const decl = statement.declaration;
+
+  if (decl === null || decl === undefined) {
+    return null;
+  }
+
+  if (decl.type === AST_NODE_TYPES.FunctionDeclaration) {
+    if (decl.id !== null && isHookName(decl.id.name)) {
+      return decl.id.name;
+    }
+
+    return null;
+  }
+
+  if (decl.type === AST_NODE_TYPES.VariableDeclaration) {
+    for (const declarator of decl.declarations) {
+      if (
+        declarator.id.type === AST_NODE_TYPES.Identifier &&
+        isHookName(declarator.id.name)
+      ) {
+        return declarator.id.name;
+      }
+    }
+  }
+
+  return null;
+}
+
+export const maxHooksPerFileRule = createRule<RuleOptions, MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: "suggestion",
+    docs: {
+      description:
+        "Flag query/hook modules that export more than N hooks. Same-kind modules pass the single-semantic-module rule but still grow into god files; this rule sets a hard ceiling so the split conversation happens early.",
+    },
+    schema: [optionSchema],
+    messages: {
+      tooManyHooks:
+        "This file exports {{count}} hooks ({{names}}), exceeding the threshold of {{threshold}}. Split into focused modules (e.g. *.list.queries.ts + *.mutations.ts).",
+    },
+  },
+  defaultOptions: [{}],
+  create(context, [options]) {
+    const threshold = options.threshold ?? DEFAULT_THRESHOLD;
+    const pattern = new RegExp(options.filePattern ?? DEFAULT_FILE_PATTERN);
+
+    if (!pattern.test(context.filename)) {
+      return {};
+    }
+
+    return {
+      Program(program) {
+        const hookNames: string[] = [];
+
+        for (const statement of program.body) {
+          const name = collectExportedHookName(statement);
+
+          if (name !== null) {
+            hookNames.push(name);
+          }
+        }
+
+        if (hookNames.length > threshold) {
+          context.report({
+            node: program,
+            messageId: "tooManyHooks",
+            data: {
+              count: String(hookNames.length),
+              threshold: String(threshold),
+              names: hookNames.join(", "),
+            },
+          });
+        }
+      },
+    };
+  },
+});

package/src/rule-packs/react-component-architecture/rules/no-cross-feature-imports.ts

@@ -0,0 +1,170 @@
+import type { TSESTree } from "@typescript-eslint/utils";
+import type { JSONSchema4 } from "@typescript-eslint/utils/json-schema";
+import * as path from "path";
+
+import { createRule } from "../../create-rule";
+
+export const RULE_NAME = "no-cross-feature-imports";
+
+export interface NoCrossFeatureImportsOptions {
+  readonly featuresDir?: string;
+  readonly allowSiblingTypes?: boolean;
+  readonly allowList?: readonly (readonly [string, string])[];
+}
+
+type RuleOptions = [NoCrossFeatureImportsOptions];
+type MessageIds = "crossFeatureImport";
+
+const optionSchema: JSONSchema4 = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    featuresDir: {
+      type: "string",
+    },
+    allowSiblingTypes: {
+      type: "boolean",
+    },
+    allowList: {
+      type: "array",
+      items: {
+        type: "array",
+        minItems: 2,
+        maxItems: 2,
+        items: { type: "string" },
+      },
+    },
+  },
+};
+
+function extractFeatureName(
+  filename: string,
+  featuresDir: string
+): string | null {
+  const normalized = filename.replace(/\\/g, "/");
+  const featuresDirNorm = featuresDir.replace(/\\/g, "/");
+
+  // Match: <anything>/src/features/<featureName>/...
+  const pattern = new RegExp(
+    `(^|/)${featuresDirNorm.split("/").join("/")}[/]([^/]+)[/]`
+  );
+  const match = normalized.match(pattern);
+
+  return match?.[2] ?? null;
+}
+
+function resolveImportSource(
+  importSource: string,
+  currentDir: string
+): string | null {
+  // Handle @/ alias
+  if (importSource.startsWith("@/")) {
+    return importSource;
+  }
+
+  // Handle relative imports
+  if (importSource.startsWith(".")) {
+    let resolved = path.resolve(currentDir, importSource);
+
+    resolved = resolved.replace(/\\/g, "/");
+
+    // Normalize to @/ format if it resolves to features
+    if (resolved.includes("/src/features/")) {
+      const match = /^(.*)\/src\/features\/([^/]+)(\/.*)?$/.exec(resolved);
+
+      if (match?.[2]) {
+        const suffix = match[3] ?? "";
+
+        return `@/features/${match[2]}${suffix}`;
+      }
+    }
+
+    return resolved;
+  }
+
+  return importSource;
+}
+
+export const noCrossFeatureImportsRule = createRule<RuleOptions, MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Prevent imports across different features",
+    },
+    schema: [optionSchema],
+    messages: {
+      crossFeatureImport:
+        'Feature "{{from}}" must not import from feature "{{to}}". Shared code belongs in @/lib or @/components.',
+    },
+  },
+  defaultOptions: [
+    {
+      featuresDir: "src/features",
+      allowSiblingTypes: true,
+      allowList: [],
+    },
+  ],
+  create(context, [options]) {
+    const featuresDir = options.featuresDir ?? "src/features";
+    const allowSiblingTypes = options.allowSiblingTypes ?? true;
+    const allowList = new Set(
+      (options.allowList ?? []).map((pair) => pair.join("→"))
+    );
+
+    const filename = context.filename;
+    const currentFeature = extractFeatureName(filename, featuresDir);
+
+    // Only check files inside features
+    if (!currentFeature) {
+      return {};
+    }
+
+    return {
+      ImportDeclaration(node: TSESTree.ImportDeclaration) {
+        // If allowSiblingTypes is true and this is a type-only import, skip
+        if (allowSiblingTypes && node.importKind === "type") {
+          return;
+        }
+
+        const importSource = node.source.value;
+
+        // Check if this is a feature import
+        if (!importSource.includes("/features/")) {
+          return;
+        }
+
+        const currentDir = path.dirname(filename);
+        const resolved = resolveImportSource(importSource, currentDir);
+
+        if (!resolved?.includes("/features/")) {
+          return;
+        }
+
+        // Extract feature name from import
+        const match = /\/features\/([^/]+)/.exec(resolved);
+        const importedFeature = match ? match[1] : null;
+
+        if (!importedFeature || importedFeature === currentFeature) {
+          return;
+        }
+
+        // Check if this is in the allow list
+        const allowKey = `${currentFeature}→${importedFeature}`;
+
+        if (allowList.has(allowKey)) {
+          return;
+        }
+
+        context.report({
+          node,
+          messageId: "crossFeatureImport",
+          data: {
+            from: currentFeature,
+            to: importedFeature,
+          },
+        });
+      },
+    };
+  },
+});

package/src/rule-packs/react-component-architecture/rules/no-inline-jsx-functions.ts

@@ -0,0 +1,66 @@
+import type { TSESTree } from "@typescript-eslint/utils";
+import type { JSONSchema4 } from "@typescript-eslint/utils/json-schema";
+
+import { createRule } from "../../create-rule";
+import { isStoryFile } from "../utils";
+
+export const RULE_NAME = "no-inline-jsx-functions";
+
+export interface NoInlineJsxFunctionsOptions {
+  readonly allowSpreadPassthrough?: boolean;
+}
+
+type RuleOptions = [NoInlineJsxFunctionsOptions];
+type MessageIds = "noInlineFunction";
+
+const optionSchema: JSONSchema4 = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    allowSpreadPassthrough: {
+      type: "boolean",
+    },
+  },
+};
+
+export const noInlineJsxFunctionsRule = createRule<RuleOptions, MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: "suggestion",
+    docs: {
+      description: "Disallow inline function expressions in JSX attributes",
+    },
+    schema: [optionSchema],
+    messages: {
+      noInlineFunction:
+        "Use a named function reference instead of an inline function for event handlers",
+    },
+  },
+  defaultOptions: [{ allowSpreadPassthrough: false }],
+  create(context) {
+    const filename = context.filename;
+
+    if (isStoryFile(filename)) {
+      return {};
+    }
+
+    return {
+      "JSXAttribute > JSXExpressionContainer > ArrowFunctionExpression"(
+        node: TSESTree.ArrowFunctionExpression
+      ) {
+        context.report({
+          node,
+          messageId: "noInlineFunction",
+        });
+      },
+      "JSXAttribute > JSXExpressionContainer > FunctionExpression"(
+        node: TSESTree.FunctionExpression
+      ) {
+        context.report({
+          node,
+          messageId: "noInlineFunction",
+        });
+      },
+    };
+  },
+});

package/src/rule-packs/react-component-architecture/utils.ts

@@ -0,0 +1,47 @@
+/**
+ * Detect if a file is a component file (.tsx with uppercase name, not test/story)
+ */
+export function isComponentFile(filename: string): boolean {
+  if (!filename.endsWith(".tsx")) {
+    return false;
+  }
+
+  if (filename.includes(".test.tsx") || filename.includes(".stories.tsx")) {
+    return false;
+  }
+
+  const basename = getBasename(filename);
+
+  return /^[A-Z]/.test(basename);
+}
+
+/**
+ * Detect if a file is a story file
+ */
+export function isStoryFile(filename: string): boolean {
+  return filename.includes(".stories.tsx");
+}
+
+/**
+ * Detect if path is in shadcn/ui components folder
+ */
+export function isInShadcnUi(filename: string): boolean {
+  return filename.includes("/components/ui/");
+}
+
+/**
+ * Extract component name from filename (e.g., Button.tsx → Button)
+ */
+export function getComponentName(filename: string): string | null {
+  const basename = getBasename(filename);
+  const match = /^([A-Z][a-zA-Z0-9]*)\.tsx$/.exec(basename);
+
+  return match ? (match[1] ?? null) : null;
+}
+
+/**
+ * Get the basename without directory
+ */
+function getBasename(filename: string): string {
+  return filename.split("/").pop() ?? "";
+}

package/src/rule-packs/rule-packs.types.ts

@@ -0,0 +1,18 @@
+import type { TSESLint } from "@typescript-eslint/utils";
+
+/** A single ESLint rule pack, bundling multiple related rules with their configuration. */
+export interface IRulePack {
+  /** Unique identifier for this pack; must match a PACK_REGISTRY id from ../stack-detection. */
+  readonly id: string;
+
+  /** Human-readable description of what this pack enforces. */
+  readonly description: string;
+
+  /** ESLint rule module definitions, indexed by unprefixed rule name. */
+  readonly rules: Readonly<
+    Record<string, TSESLint.RuleModule<string, readonly unknown[]>>
+  >;
+
+  /** Default severity for each rule in the pack, indexed by unprefixed rule name. */
+  readonly rulesConfig: Readonly<Record<string, "error" | "warn">>;
+}

package/src/rule-packs/structured-logging/index.ts

@@ -0,0 +1,26 @@
+import type { TSESLint } from "@typescript-eslint/utils";
+
+import { maskPiiFieldsRule } from "./rules/mask-pii-fields";
+import { noErrorStringifyRule } from "./rules/no-error-stringify";
+import { requireEventFieldRule } from "./rules/require-event-field";
+import type { IRulePack } from "../rule-packs.types";
+
+const rules: Record<string, TSESLint.RuleModule<string, readonly unknown[]>> = {
+  "mask-pii-fields": maskPiiFieldsRule,
+  "no-error-stringify": noErrorStringifyRule,
+  "require-event-field": requireEventFieldRule,
+};
+
+export const structuredLoggingPack: IRulePack = {
+  id: "structured-logging",
+  description:
+    "Structured logging best practices: PII masking, error handling, and event field requirements",
+  rules,
+  rulesConfig: {
+    "mask-pii-fields": "error",
+    "no-error-stringify": "error",
+    "require-event-field": "error",
+  },
+};
+
+export default structuredLoggingPack;