@ai0x0/utils 0.7.0 → 0.7.1

package/eslint-rules/api-route-via-nrf.js

@@ -0,0 +1,83 @@
+/**
+ * api-route-via-nrf
+ * -----------------
+ * API 路由一律走 next-rest-framework（route / routeOperation），不许裸导 HTTP 方法。
+ *
+ * 裸写 `export async function POST(req)` 的代价不是风格不统一，是这条端点从此不存在于
+ * openapi.json：生成器不会给它出 client，CLI / agent 读不到它，前端只能手写 fetch 直连
+ * （那是 no-direct-api-url 拦的另一头）。框架统一做的鉴权预热、错误翻译、响应校验，
+ * 它也都得自己记得补。
+ *
+ * 判的是「导出形状」，不是「有没有 import route」：
+ * 报：`export async function POST(...)`、`export const GET = handler`；
+ * 放：`export const { POST } = route({...})`（从 route() 解构，id 是 ObjectPattern）。
+ *
+ * 作用范围由调用方在 flat config 里用 files 圈定（比如只在 api 目录的 route.ts 上开）；
+ * 确有理由裸导的文件（第三方库的整体转发，如 better-auth 的 catch-all）用 files override
+ * 单独关掉，并在那个文件里写明理由。
+ */
+
+const HTTP_METHODS = new Set([
+  "GET",
+  "POST",
+  "PUT",
+  "DELETE",
+  "PATCH",
+  "HEAD",
+  "OPTIONS",
+]);
+
+/** @type {import('eslint').Rule.RuleModule} */
+const rule = {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "API 路由必须用 next-rest-framework 的 route()/routeOperation() 构建，禁止裸导 HTTP 方法。",
+    },
+    schema: [],
+    messages: {
+      rawMethodExport:
+        "API 路由不许裸导 HTTP 方法，改用 next-rest-framework 的 route()/routeOperation" +
+        "（export const { POST } = route({...})）。裸导的端点进不了 openapi.json，" +
+        "前端与 CLI 都拿不到它的 client。",
+    },
+  },
+  create(context) {
+    return {
+      ExportNamedDeclaration(node) {
+        const declaration = node.declaration;
+        if (!declaration) {
+          return;
+        }
+        if (
+          declaration.type === "FunctionDeclaration" &&
+          declaration.id &&
+          HTTP_METHODS.has(declaration.id.name)
+        ) {
+          context.report({
+            node: declaration.id,
+            messageId: "rawMethodExport",
+          });
+          return;
+        }
+        if (declaration.type === "VariableDeclaration") {
+          for (const declarator of declaration.declarations) {
+            // 从 route() 解构出来的是 ObjectPattern，那才叫走框架。
+            if (
+              declarator.id.type === "Identifier" &&
+              HTTP_METHODS.has(declarator.id.name)
+            ) {
+              context.report({
+                node: declarator.id,
+                messageId: "rawMethodExport",
+              });
+            }
+          }
+        }
+      },
+    };
+  },
+};
+
+export default rule;

package/eslint-rules/index.js

@@ -12,6 +12,8 @@ import noThen from "./no-then.js";
 import noOneLetterVars from "./no-one-letter-vars.js";
 import noConsecutiveSetState from "./no-consecutive-setstate.js";
 import maxLines from "./max-lines.js";
+import apiRouteViaNrf from "./api-route-via-nrf.js";
+import noDirectApiUrl from "./no-direct-api-url.js";
 
 const rules = {
   "require-section-divider": requireSectionDivider,
@@ -25,8 +27,17 @@ const rules = {
   "no-one-letter-vars": noOneLetterVars,
   "no-consecutive-setstate": noConsecutiveSetState,
   "max-lines": maxLines,
+  "api-route-via-nrf": apiRouteViaNrf,
+  "no-direct-api-url": noDirectApiUrl,
 };
 
+// 这两条只管「特定位置」的代码，不能跟着 recommended 全局开：
+//   · api-route-via-nrf 只该挂在 API 路由文件上（别的文件 export 一个叫 GET 的函数是自由的）；
+//   · no-direct-api-url 只该挂在前端目录上（后端与中间件里出现 "/api/..." 字面量是本分）。
+// 调用方在 flat config 里用 files 圈定范围自行开启，豁免文件用 files override 关掉，
+// 用法写在两条规则各自的文件头。
+const SCOPED_RULES = new Set(["api-route-via-nrf", "no-direct-api-url"]);
+
 const plugin = {
   rules,
   configs: {
@@ -34,7 +45,9 @@ const plugin = {
       plugins: { ai0x0: { rules } },
       rules: {
         ...Object.fromEntries(
-          Object.keys(rules).map((name) => [`ai0x0/${name}`, "error"]),
+          Object.keys(rules)
+            .filter((name) => !SCOPED_RULES.has(name))
+            .map((name) => [`ai0x0/${name}`, "error"]),
         ),
         curly: "error",
         "ai0x0/max-lines": [

package/eslint-rules/no-direct-api-url.js

@@ -0,0 +1,55 @@
+/**
+ * no-direct-api-url
+ * -----------------
+ * 前端不许手写 "/api/..." 地址直连后端，一律走生成的 client。
+ *
+ * 手写 `fetch("/api/xxx")` 绕掉的不是一层方便，是一整套集中处理（401 重登、错误提示、
+ * 作用域头、重复请求去重），而且 TypeScript 对它是瞎的 —— 路由改了形状，编译不红。
+ * 所以要调一个端点：先让它进 openapi.json（后端路由走 nrf，见 api-route-via-nrf），
+ * 重新生成 client，再调生成出来的方法。
+ *
+ * 判的是字符串字面量与模板串的开头：`/api/`。注释与 JSDoc 不是 AST 节点，天然不报。
+ * 作用范围由调用方在 flat config 里用 files 圈定（比如只挂前端目录），client 封装层
+ * 自己（生成文件与拦截器）用 files override 关掉 —— 地址本来就该只写在那儿。
+ */
+
+const API_PREFIX = "/api/";
+
+function startsWithApi(value) {
+  return typeof value === "string" && value.startsWith(API_PREFIX);
+}
+
+/** @type {import('eslint').Rule.RuleModule} */
+const rule = {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        '前端禁止手写 "/api/..." 地址直连后端，必须走生成的 client。',
+    },
+    schema: [],
+    messages: {
+      directApiUrl:
+        '前端不许手写 "/api/..." 直连后端：走生成的 client。端点先进 openapi.json' +
+        "（后端路由走 nrf），重新生成 client 之后调生成出来的方法；401 重登、错误提示、" +
+        "作用域头都在那一层集中处理，手写 fetch 全部绕开。",
+    },
+  },
+  create(context) {
+    return {
+      Literal(node) {
+        if (startsWithApi(node.value)) {
+          context.report({ node, messageId: "directApiUrl" });
+        }
+      },
+      TemplateLiteral(node) {
+        // 只看第一段静态文本：`${base}/api/x` 的地址不归这条管（那是封装层的拼法）。
+        if (startsWithApi(node.quasis[0]?.value.cooked)) {
+          context.report({ node, messageId: "directApiUrl" });
+        }
+      },
+    };
+  },
+};
+
+export default rule;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai0x0/utils",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "AI0x0 utils",
   "keywords": [
     "ai0x0"