npm - @agjs/tsforge - Versions diffs - 0.1.6 → 0.1.8 - Mend

@agjs/tsforge 0.1.6 → 0.1.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (13) hide show

package/package.json CHANGED Viewed

@@ -1,7 +1,7 @@
 {
   "name": "@agjs/tsforge",
   "type": "module",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "license": "MIT",
   "description": "TypeScript coding harness with a deterministic gate, stack-aware guardrails, and stream-level correction.",
   "repository": {

package/src/loop/rule-docs.generated.json CHANGED Viewed

@@ -289,6 +289,31 @@
     "bad": "// Example that violates the rule",
     "good": "// Corrected version"
   },
+  "tsforge/no-import-build-output": {
+    "what": "Disallow importing from build/output directories within the project. Source must import source, not compiled artifacts, to avoid stale-code drift and broken module boundaries.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
+  "tsforge/no-import-test-from-source": {
+    "what": "Disallow production/source files from importing test files. Tests may depend on source, never the reverse — test code must not ship in the production graph.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
+  "tsforge/client-hooks-require-use-client": {
+    "what": "Require the 'use client' directive in app-router page/layout/template files that call client-only hooks. Server Components cannot use state/effect/navigation hooks — doing so crashes at runtime.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
+  "tsforge/no-next-head-in-app": {
+    "what": "Disallow importing 'next/head' in app-router files. The <Head> component is a no-op under app/ — use the Metadata API (export const metadata / generateMetadata) instead.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
+  "tsforge/no-pages-router-data-fetching-in-app": {
+    "what": "Disallow pages-router data-fetching exports (getServerSideProps, getStaticProps, getStaticPaths, getInitialProps) in app-router files. Next.js ignores them under app/, so they are silent dead code — use async Server Components or route handlers instead.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
   "tsforge/pkce-required-for-oidc": {
     "what": "OIDC providers must use PKCE: `buildAuthorizationURL` must call `generateCodeVerifier()` and pass it to `createAuthorizationURL`.",
     "bad": "// Example that violates the rule",

package/src/rule-packs/index.ts CHANGED Viewed

@@ -8,6 +8,8 @@ import { elysiaPack } from "./elysia";
 import { envAccessPack } from "./env-access";
 import { i18nKeysPack } from "./i18n-keys";
 import { jwtCookiesPack } from "./jwt-cookies";
+import { moduleBoundariesPack } from "./module-boundaries";
+import { nextjsPack } from "./nextjs";
 import { oauthSecurityPack } from "./oauth-security";
 import { reactComponentArchitecturePack } from "./react-component-architecture";
 import { structuredLoggingPack } from "./structured-logging";
@@ -25,6 +27,8 @@ export const RULE_PACKS = {
   "env-access": envAccessPack,
   "i18n-keys": i18nKeysPack,
   "jwt-cookies": jwtCookiesPack,
+  "module-boundaries": moduleBoundariesPack,
+  nextjs: nextjsPack,
   "oauth-security": oauthSecurityPack,
   "react-component-architecture": reactComponentArchitecturePack,
   "structured-logging": structuredLoggingPack,

package/src/rule-packs/module-boundaries/index.ts ADDED Viewed

@@ -0,0 +1,23 @@
+import type { TSESLint } from "@typescript-eslint/utils";
+import { noImportBuildOutputRule } from "./rules/no-import-build-output";
+import { noImportTestFromSourceRule } from "./rules/no-import-test-from-source";
+import type { IRulePack } from "../rule-packs.types";
+const rules: Record<string, TSESLint.RuleModule<string, readonly unknown[]>> = {
+  "no-import-build-output": noImportBuildOutputRule,
+  "no-import-test-from-source": noImportTestFromSourceRule,
+};
+export const moduleBoundariesPack: IRulePack = {
+  id: "module-boundaries",
+  description:
+    "Module boundary hygiene: keep the test/production and source/build-output boundaries clean so the dependency graph stays sound.",
+  rules,
+  rulesConfig: {
+    "no-import-build-output": "error",
+    "no-import-test-from-source": "error",
+  },
+};
+export default moduleBoundariesPack;

package/src/rule-packs/module-boundaries/rules/no-import-build-output.ts ADDED Viewed

@@ -0,0 +1,71 @@
+import type { JSONSchema4 } from "@typescript-eslint/utils/json-schema";
+import { createRule } from "../../create-rule";
+import { hasDirSegment, isRelativeImport } from "../utils";
+export const RULE_NAME = "no-import-build-output";
+export interface NoImportBuildOutputOptions {
+  readonly outputDirs?: readonly string[];
+}
+type RuleOptions = [NoImportBuildOutputOptions];
+type MessageIds = "buildOutputImported";
+const DEFAULT_OUTPUT_DIRS: readonly string[] = [
+  "dist",
+  "build",
+  "out",
+  ".next",
+  "coverage",
+];
+const optionSchema: JSONSchema4 = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    outputDirs: {
+      type: "array",
+      uniqueItems: true,
+      items: { type: "string" },
+    },
+  },
+};
+export const noImportBuildOutputRule = createRule<RuleOptions, MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow importing from build/output directories within the project. Source must import source, not compiled artifacts, to avoid stale-code drift and broken module boundaries.",
+    },
+    schema: [optionSchema],
+    messages: {
+      buildOutputImported:
+        "Do not import from build output ('{{source}}'). Import the source module directly so the build graph stays the single source of truth.",
+    },
+  },
+  defaultOptions: [{ outputDirs: [...DEFAULT_OUTPUT_DIRS] }],
+  create(context, [options]) {
+    const outputDirs = new Set(options.outputDirs ?? DEFAULT_OUTPUT_DIRS);
+    return {
+      ImportDeclaration(node) {
+        const source = node.source.value;
+        if (typeof source !== "string" || !isRelativeImport(source)) {
+          return;
+        }
+        if (hasDirSegment(source, outputDirs)) {
+          context.report({
+            node: node.source,
+            messageId: "buildOutputImported",
+            data: { source },
+          });
+        }
+      },
+    };
+  },
+});

package/src/rule-packs/module-boundaries/rules/no-import-test-from-source.ts ADDED Viewed

@@ -0,0 +1,74 @@
+import type { JSONSchema4 } from "@typescript-eslint/utils/json-schema";
+import { createRule } from "../../create-rule";
+import { hasDirSegment, isRelativeImport, isTestFileName } from "../utils";
+export const RULE_NAME = "no-import-test-from-source";
+export interface NoImportTestFromSourceOptions {
+  readonly testDirNames?: readonly string[];
+}
+type RuleOptions = [NoImportTestFromSourceOptions];
+type MessageIds = "testImportedFromSource";
+const DEFAULT_TEST_DIR_NAMES: readonly string[] = ["__tests__", "__mocks__"];
+const optionSchema: JSONSchema4 = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    testDirNames: {
+      type: "array",
+      uniqueItems: true,
+      items: { type: "string" },
+    },
+  },
+};
+export const noImportTestFromSourceRule = createRule<RuleOptions, MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow production/source files from importing test files. Tests may depend on source, never the reverse — test code must not ship in the production graph.",
+    },
+    schema: [optionSchema],
+    messages: {
+      testImportedFromSource:
+        "Source files must not import test files ('{{source}}'). Move shared helpers into a non-test module so production code never depends on tests.",
+    },
+  },
+  defaultOptions: [{ testDirNames: [...DEFAULT_TEST_DIR_NAMES] }],
+  create(context, [options]) {
+    const testDirs = new Set(options.testDirNames ?? DEFAULT_TEST_DIR_NAMES);
+    // A test file may freely import other test files; only enforce the
+    // boundary when the importing file is itself non-test.
+    if (
+      isTestFileName(context.filename) ||
+      hasDirSegment(context.filename, testDirs)
+    ) {
+      return {};
+    }
+    return {
+      ImportDeclaration(node) {
+        const source = node.source.value;
+        if (typeof source !== "string" || !isRelativeImport(source)) {
+          return;
+        }
+        if (isTestFileName(source) || hasDirSegment(source, testDirs)) {
+          context.report({
+            node: node.source,
+            messageId: "testImportedFromSource",
+            data: { source },
+          });
+        }
+      },
+    };
+  },
+});

package/src/rule-packs/module-boundaries/utils.ts ADDED Viewed

@@ -0,0 +1,29 @@
+/** True for relative import specifiers (`./x`, `../x`) — i.e. paths inside the
+ *  project, as opposed to bare package specifiers (`react`, `@scope/pkg`). */
+export function isRelativeImport(source: string): boolean {
+  return source.startsWith("./") || source.startsWith("../");
+}
+/** Path segments of a "/"-separated specifier, dropping "", ".", "..". */
+export function pathSegments(specifier: string): string[] {
+  return specifier
+    .split("/")
+    .filter((seg) => seg.length > 0 && seg !== "." && seg !== "..");
+}
+/** True if any directory segment of the specifier is in `dirs`. */
+export function hasDirSegment(
+  specifier: string,
+  dirs: ReadonlySet<string>
+): boolean {
+  return pathSegments(specifier).some((seg) => dirs.has(seg));
+}
+/** True if the specifier's final segment names a test/spec module
+ *  (`foo.test`, `foo.test.ts`, `foo.spec.tsx`, …). */
+export function isTestFileName(specifier: string): boolean {
+  const segments = specifier.split("/");
+  const base = segments[segments.length - 1] ?? "";
+  return /\.(?:test|spec)(?:\.[^.]+)?$/.test(base);
+}

package/src/rule-packs/nextjs/index.ts ADDED Viewed

@@ -0,0 +1,26 @@
+import type { TSESLint } from "@typescript-eslint/utils";
+import { clientHooksRequireUseClientRule } from "./rules/client-hooks-require-use-client";
+import { noNextHeadInAppRule } from "./rules/no-next-head-in-app";
+import { noPagesRouterDataFetchingInAppRule } from "./rules/no-pages-router-data-fetching-in-app";
+import type { IRulePack } from "../rule-packs.types";
+const rules: Record<string, TSESLint.RuleModule<string, readonly unknown[]>> = {
+  "client-hooks-require-use-client": clientHooksRequireUseClientRule,
+  "no-next-head-in-app": noNextHeadInAppRule,
+  "no-pages-router-data-fetching-in-app": noPagesRouterDataFetchingInAppRule,
+};
+export const nextjsPack: IRulePack = {
+  id: "nextjs",
+  description:
+    "Next.js app-router correctness: server/client component boundaries and dead pages-router APIs.",
+  rules,
+  rulesConfig: {
+    "client-hooks-require-use-client": "error",
+    "no-next-head-in-app": "error",
+    "no-pages-router-data-fetching-in-app": "error",
+  },
+};
+export default nextjsPack;

package/src/rule-packs/nextjs/rules/client-hooks-require-use-client.ts ADDED Viewed

@@ -0,0 +1,74 @@
+import { createRule } from "../../create-rule";
+import {
+  calleeName,
+  hasDirective,
+  isAppRouterFile,
+  isRouteEntryFile,
+} from "../utils";
+export const RULE_NAME = "client-hooks-require-use-client";
+type MessageIds = "missingUseClient";
+/** Hooks that only work in Client Components — calling them in a Server
+ *  Component throws at runtime. */
+const CLIENT_HOOKS = new Set<string>([
+  "useState",
+  "useEffect",
+  "useLayoutEffect",
+  "useReducer",
+  "useImperativeHandle",
+  "useSyncExternalStore",
+  "useRouter",
+  "usePathname",
+  "useSearchParams",
+  "useParams",
+]);
+export const clientHooksRequireUseClientRule = createRule<[], MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Require the 'use client' directive in app-router page/layout/template files that call client-only hooks. Server Components cannot use state/effect/navigation hooks — doing so crashes at runtime.",
+    },
+    schema: [],
+    messages: {
+      missingUseClient:
+        "'{{hook}}' is a client-only hook but this Server Component has no 'use client' directive. Add 'use client' at the top of the file or move the interactivity into a Client Component.",
+    },
+  },
+  defaultOptions: [],
+  create(context) {
+    if (
+      !isAppRouterFile(context.filename) ||
+      !isRouteEntryFile(context.filename)
+    ) {
+      return {};
+    }
+    let clientComponent = false;
+    return {
+      Program(node) {
+        clientComponent = hasDirective(node, "use client");
+      },
+      CallExpression(node) {
+        if (clientComponent) {
+          return;
+        }
+        const name = calleeName(node.callee);
+        if (name !== null && CLIENT_HOOKS.has(name)) {
+          context.report({
+            node,
+            messageId: "missingUseClient",
+            data: { hook: name },
+          });
+        }
+      },
+    };
+  },
+});

package/src/rule-packs/nextjs/rules/no-next-head-in-app.ts ADDED Viewed

@@ -0,0 +1,36 @@
+import { createRule } from "../../create-rule";
+import { isAppRouterFile } from "../utils";
+export const RULE_NAME = "no-next-head-in-app";
+type MessageIds = "nextHeadInApp";
+export const noNextHeadInAppRule = createRule<[], MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow importing 'next/head' in app-router files. The <Head> component is a no-op under app/ — use the Metadata API (export const metadata / generateMetadata) instead.",
+    },
+    schema: [],
+    messages: {
+      nextHeadInApp:
+        "'next/head' does nothing in the app router. Use the Metadata API (export const metadata or generateMetadata) instead.",
+    },
+  },
+  defaultOptions: [],
+  create(context) {
+    if (!isAppRouterFile(context.filename)) {
+      return {};
+    }
+    return {
+      ImportDeclaration(node) {
+        if (node.source.value === "next/head") {
+          context.report({ node: node.source, messageId: "nextHeadInApp" });
+        }
+      },
+    };
+  },
+});

package/src/rule-packs/nextjs/rules/no-pages-router-data-fetching-in-app.ts ADDED Viewed

@@ -0,0 +1,71 @@
+import type { TSESTree } from "@typescript-eslint/utils";
+import { createRule } from "../../create-rule";
+import { isAppRouterFile } from "../utils";
+export const RULE_NAME = "no-pages-router-data-fetching-in-app";
+type MessageIds = "pagesDataFnInApp";
+/** Pages-router data-fetching exports — inert (dead code) under the app router. */
+const PAGES_DATA_FNS = new Set<string>([
+  "getServerSideProps",
+  "getStaticProps",
+  "getStaticPaths",
+  "getInitialProps",
+]);
+export const noPagesRouterDataFetchingInAppRule = createRule<[], MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow pages-router data-fetching exports (getServerSideProps, getStaticProps, getStaticPaths, getInitialProps) in app-router files. Next.js ignores them under app/, so they are silent dead code — use async Server Components or route handlers instead.",
+    },
+    schema: [],
+    messages: {
+      pagesDataFnInApp:
+        "'{{name}}' is a pages-router API and is ignored under app/. Fetch data inside an async Server Component or a route handler instead.",
+    },
+  },
+  defaultOptions: [],
+  create(context) {
+    if (!isAppRouterFile(context.filename)) {
+      return {};
+    }
+    function reportName(node: TSESTree.Node, name: string): void {
+      context.report({ node, messageId: "pagesDataFnInApp", data: { name } });
+    }
+    return {
+      ExportNamedDeclaration(node) {
+        const decl = node.declaration;
+        if (
+          decl?.type === "FunctionDeclaration" &&
+          decl.id !== null &&
+          PAGES_DATA_FNS.has(decl.id.name)
+        ) {
+          reportName(decl.id, decl.id.name);
+        } else if (decl?.type === "VariableDeclaration") {
+          for (const d of decl.declarations) {
+            if (d.id.type === "Identifier" && PAGES_DATA_FNS.has(d.id.name)) {
+              reportName(d.id, d.id.name);
+            }
+          }
+        }
+        for (const spec of node.specifiers) {
+          if (
+            spec.exported.type === "Identifier" &&
+            PAGES_DATA_FNS.has(spec.exported.name)
+          ) {
+            reportName(spec, spec.exported.name);
+          }
+        }
+      },
+    };
+  },
+});

package/src/rule-packs/nextjs/utils.ts ADDED Viewed

@@ -0,0 +1,55 @@
+import type { TSESTree } from "@typescript-eslint/utils";
+/** True if the file lives under a Next.js app-router directory (an `app` segment). */
+export function isAppRouterFile(filename: string): boolean {
+  return filename.split(/[\\/]/).includes("app");
+}
+/** True if the file is an app-router route-entry file (page/layout/template),
+ *  which default to React Server Components. */
+export function isRouteEntryFile(filename: string): boolean {
+  const base = filename.split(/[\\/]/).pop() ?? "";
+  return /^(?:page|layout|template)\.(?:tsx|ts|jsx|js)$/.test(base);
+}
+/** True if the program's directive prologue contains `directive`
+ *  (e.g. "use client" / "use server"). */
+export function hasDirective(
+  program: TSESTree.Program,
+  directive: string
+): boolean {
+  for (const stmt of program.body) {
+    if (
+      stmt.type !== "ExpressionStatement" ||
+      stmt.expression.type !== "Literal" ||
+      typeof stmt.expression.value !== "string"
+    ) {
+      return false; // directive prologue has ended
+    }
+    if (stmt.expression.value === directive) {
+      return true;
+    }
+  }
+  return false;
+}
+/** Resolve a call's callee to a simple name: `useState` or `React.useState`
+ *  → "useState". Returns null for computed or complex callees. */
+export function calleeName(callee: TSESTree.Node): string | null {
+  if (callee.type === "Identifier") {
+    return callee.name;
+  }
+  if (
+    callee.type === "MemberExpression" &&
+    !callee.computed &&
+    callee.property.type === "Identifier"
+  ) {
+    return callee.property.name;
+  }
+  return null;
+}

package/src/stack-detection/packs.ts CHANGED Viewed

@@ -61,6 +61,17 @@ export const PACK_REGISTRY = {
     guidance: "Follow Elysia patterns for HTTP routing and middleware.",
   } as const satisfies IRulePackDescriptor,
+  nextjs: {
+    id: "nextjs",
+    label: "Next.js",
+    description:
+      "App-router correctness: server/client boundaries and dead pages-router APIs",
+    category: "framework",
+    appliesWhen: { anyDeps: ["next"] },
+    guidance:
+      "Follow Next.js app-router conventions: mark interactive files 'use client' and use the Metadata API and Server Components instead of pages-router APIs.",
+  } as const satisfies IRulePackDescriptor,
   bullmq: {
     id: "bullmq",
     label: "BullMQ",