eslint-plugin-aurora-999 0.1.0

package/README.md

@@ -0,0 +1,91 @@
+# eslint-plugin-aurora
+
+Aurora 项目 ESLint 插件：提供一套可复用的基础 Flat Config（JS/TS/import），并附带若干 Aurora 约定的结构/语义类自定义规则。
+
+- 运行环境：Node.js >= 18
+- ESLint：v9+（Flat Config）
+
+## 安装
+
+```bash
+npm i -D eslint eslint-plugin-aurora
+```
+
+说明：本插件内部会用到 `@eslint/js`、`typescript-eslint`、`eslint-plugin-import`、`globals` 等依赖；安装本插件时会一并安装。
+
+如果你需要让 `eslint-plugin-import` 的 TypeScript 解析/路径解析更准确，建议项目也安装：
+
+```bash
+npm i -D eslint-import-resolver-typescript
+```
+
+## 使用（推荐：Flat Config）
+
+在项目根目录创建/修改 `eslint.config.js`：
+
+```js
+const aurora = require("eslint-plugin-aurora");
+
+const baseDir = __dirname;
+
+module.exports = [
+  // 1) 基础规则集（JS/TS/import）
+  ...aurora.configs.recommended(baseDir),
+
+  // 2) 选择性启用 Aurora 自定义规则
+  {
+    plugins: { aurora },
+    rules: {
+      "aurora/base-check": "error",
+      "aurora/trial-check": "error",
+      "aurora/scene-check": "error",
+      "aurora/prefab-check": "error",
+    },
+  },
+];
+```
+
+然后执行：
+
+```bash
+npx eslint .
+```
+
+## configs
+
+### `configs.recommended(baseDir)`
+
+生成基础 Flat Config 数组，包含：
+
+- `@eslint/js` 的 recommended
+- `typescript-eslint`：
+  - 若 `baseDir/tsconfig.json` 存在，则启用 type-aware 的 `recommendedTypeChecked`
+  - 否则降级为 `recommended`
+- `eslint-plugin-import` 的 recommended + 常用 resolver/settings
+
+> `baseDir` 必须传项目根目录（用于定位 `tsconfig.json`）。
+
+## rules
+
+- `aurora/base-check`
+  - 禁止 `console.log/debug/info/trace`
+  - 禁止 `debugger`
+- `aurora/trial-check`
+  - 仅对 `trialGeneration/**/trialservice.ts` 生效
+  - 约束 `TrialGenerator` 子类、`generate()` 方法以及返回值包含 `target_answer`
+- `aurora/scene-check`
+  - 仅对 `*scene.ts` 生效
+  - 约束 Phaser/BaseScene/NodeConfig 的导入与 `getSceneConfig()` 返回
+- `aurora/prefab-check`
+  - 仅对 `*prefab.ts` 生效
+  - 约束 Phaser/phaser-kit 导入、`PrefabConfig` 结构，以及 GameObjectFactory remove/register
+
+## 目录结构
+
+- `lib/index.js`：插件入口（导出 `rules` 与 `configs`）
+- `lib/configs/base-config.js`：基础 Flat Config 生成函数
+- `lib/rules/*.js`：Aurora 自定义规则实现
+
+## 备注
+
+- 更详细的背景与设计说明见：`设计.md`

package/lib/configs/base-config.js

@@ -0,0 +1,101 @@
+"use strict";
+
+const path = require("path");
+const fs = require("fs");
+const globals = require("globals");
+const js = require("@eslint/js");
+const tseslint = require("typescript-eslint");
+const importPlugin = require("eslint-plugin-import");
+
+/**
+ * 生成基础 ESLint 配置（JS/TS + import 语义规则）。
+ *
+ * 注意：这里返回的是 ESLint flat config 数组（用于 ESLint v9+）。
+ * @param {string} baseDir - 项目根目录
+ */
+function eslintBaseConfig(baseDir) {
+  const tsconfigPath = path.join(baseDir, "tsconfig.json");
+  const hasTsConfig = fs.existsSync(tsconfigPath);
+
+  const typescriptRulesToDisable = {
+    "@typescript-eslint/no-unused-vars": "off",
+    "no-unused-vars": "off",
+    "@typescript-eslint/explicit-module-boundary-types": "off",
+    "@typescript-eslint/no-explicit-any": "off",
+  };
+
+  const baseConfig = {
+    languageOptions: {
+      ecmaVersion: 2022,
+      sourceType: "module",
+      globals: {
+        ...globals.browser,
+        ...globals.node,
+        ...globals.jest,
+      },
+    },
+    rules: {
+      ...js.configs.recommended.rules,
+      "no-unused-vars": "off",
+      "no-console": "warn",
+      semi: ["error", "always"],
+    },
+  };
+
+  const tsConfigs = hasTsConfig
+    ? tseslint.configs.recommendedTypeChecked.map((config) => ({
+        ...config,
+        files: ["**/*.ts", "**/*.tsx"],
+        languageOptions: {
+          ...config.languageOptions,
+          parserOptions: {
+            project: [tsconfigPath],
+            tsconfigRootDir: baseDir,
+          },
+        },
+        rules: {
+          ...(config.rules || {}),
+          ...typescriptRulesToDisable,
+        },
+      }))
+    : [
+        ...tseslint.configs.recommended,
+        {
+          files: ["**/*.ts", "**/*.tsx"],
+          rules: {
+            ...typescriptRulesToDisable,
+          },
+        },
+      ];
+
+  const importConfig = {
+    plugins: {
+      import: importPlugin,
+    },
+    settings: {
+      "import/parsers": {
+        "@typescript-eslint/parser": [".ts", ".tsx"],
+      },
+      "import/resolver": {
+        typescript: {
+          ...(hasTsConfig ? { project: tsconfigPath } : {}),
+        },
+        node: {
+          extensions: [".js", ".jsx", ".ts", ".tsx"],
+        },
+      },
+      "import/extensions": [".js", ".jsx", ".ts", ".tsx"],
+    },
+    rules: {
+      ...importPlugin.configs.recommended.rules,
+      "import/no-unresolved": "error",
+      "import/extensions": ["error", "never", { js: "never", jsx: "never", ts: "never", tsx: "never" }],
+    },
+  };
+
+  return [baseConfig, ...tsConfigs, importConfig];
+}
+
+module.exports = {
+  eslintBaseConfig,
+};

package/lib/index.js

@@ -0,0 +1,16 @@
+"use strict";
+
+const { eslintBaseConfig } = require("./configs/base-config");
+
+module.exports = {
+  rules: {
+    "base-check": require("./rules/base-check"),
+    "trial-check": require("./rules/trial-check"),
+    "prefab-check": require("./rules/prefab-check"),
+    "scene-check": require("./rules/scene-check"),
+  },
+  configs: {
+    // 注意：这里导出的是一个函数，需要传入项目根目录 baseDir 才能生成 flat config
+    recommended: eslintBaseConfig,
+  },
+};

package/lib/rules/base-check.js

@@ -0,0 +1,76 @@
+"use strict";
+
+/**
+ * @fileoverview Aurora 基础检测规则
+ * 说明：这里只实现 ESLint rule 本身，不包含 ESLint 配置拼装逻辑。
+ */
+
+/**
+ * @param {import('estree').Expression} callee
+ */
+function getConsoleMethodName(callee) {
+  if (!callee || callee.type !== "MemberExpression") return;
+  if (!callee.object || callee.object.type !== "Identifier" || callee.object.name !== "console") return;
+
+  if (callee.property?.type === "Identifier") return callee.property.name;
+  if (callee.property?.type === "Literal" && typeof callee.property.value === "string") {
+    return callee.property.value;
+  }
+  return;
+}
+
+module.exports = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Aurora 项目基础代码规范检查",
+      recommended: true,
+    },
+    schema: [],
+    messages: {
+      noConsole: "生产代码中禁止使用 console.{{name}}",
+      noDebugger: "生产代码中禁止使用 debugger",
+    },
+  },
+
+  /**
+   * @param {import('eslint').Rule.RuleContext} context
+   */
+  create(context) {
+    const fileName = context.getFilename?.() || "";
+    const lower = typeof fileName === "string" ? fileName.toLowerCase() : "";
+
+    // 只关注 js/ts 文件；常见产物/依赖目录直接跳过
+    const isSupportedExt = /\.(js|jsx|ts|tsx)$/.test(lower);
+    if (!isSupportedExt || lower === "<input>") return {};
+
+    const ignoredParts = ["/node_modules/", "/dist/", "/build/", "/coverage/", "/temp/"];
+    for (const part of ignoredParts) {
+      if (lower.includes(part)) return {};
+    }
+
+    const bannedConsoleMethods = new Set(["log", "debug", "info", "trace"]);
+
+    return {
+      CallExpression(node) {
+        const name = getConsoleMethodName(node.callee);
+        if (!name) return;
+
+        if (bannedConsoleMethods.has(name)) {
+          context.report({
+            node,
+            messageId: "noConsole",
+            data: { name },
+          });
+        }
+      },
+
+      DebuggerStatement(node) {
+        context.report({
+          node,
+          messageId: "noDebugger",
+        });
+      },
+    };
+  },
+};

package/lib/rules/prefab-check.js

@@ -0,0 +1,449 @@
+"use strict";
+
+/**
+ * @fileoverview Prefab（*.prefab.ts / *prefab.ts）通用结构 ESLint 规则
+ *
+ * 说明：
+ * - 本规则仅做“语义检查”，不做 import 路径可解析性校验。
+ */
+
+/**
+ * 判断一个 ImportDeclaration 是否是 `import Phaser from 'phaser'`
+ * @param {import('estree').ImportDeclaration} node
+ */
+function isPhaserDefaultImport(node) {
+  if (!node || node.type !== "ImportDeclaration") return false;
+  if (!node.source || node.source.type !== "Literal" || node.source.value !== "phaser") return false;
+
+  const defaultSpecifier = node.specifiers?.find((s) => s.type === "ImportDefaultSpecifier");
+  return Boolean(defaultSpecifier && defaultSpecifier.local && defaultSpecifier.local.name === "Phaser");
+}
+
+/**
+ * 从指定模块的 import 中提取命名导入（忽略 type/value 形式差异）
+ * @param {import('estree').ImportDeclaration} node
+ * @param {string} sourceValue
+ */
+function getNamedImportsFrom(node, sourceValue) {
+  if (!node || node.type !== "ImportDeclaration") return [];
+  if (!node.source || node.source.type !== "Literal" || node.source.value !== sourceValue) return [];
+
+  return (node.specifiers || [])
+    .filter((s) => s.type === "ImportSpecifier")
+    .map((s) => s.imported?.name)
+    .filter(Boolean);
+}
+
+/**
+ * 判断 `Identifier` 的 TS 类型注解是否为指定类型名
+ * @param {import('estree').Identifier} id
+ * @param {string} typeName
+ */
+function hasTSTypeAnnotation(id, typeName) {
+  const typeAnnotation = id?.typeAnnotation?.typeAnnotation;
+  if (!typeAnnotation) return false;
+
+  // TSTypeReference: `PrefabConfig`
+  if (typeAnnotation.type === "TSTypeReference") {
+    return (
+      typeAnnotation.typeName?.type === "Identifier" && typeAnnotation.typeName.name === typeName
+    );
+  }
+
+  return false;
+}
+
+/**
+ * 从 ObjectExpression 中读取 `name` / `type` 字段
+ * @param {import('estree').ObjectExpression} obj
+ */
+function readPrefabConfigFields(obj) {
+  /** @type {{hasName?: boolean, nameValue?: string, typeValue?: string}} */
+  const result = {};
+
+  for (const prop of obj.properties || []) {
+    // 仅处理普通对象属性：{ name: 'xxx' }
+    if (!prop || prop.type !== "Property") continue;
+
+    const keyName =
+      prop.key?.type === "Identifier"
+        ? prop.key.name
+        : prop.key?.type === "Literal"
+          ? String(prop.key.value)
+          : undefined;
+
+    if (!keyName) continue;
+
+    if (keyName === "name") {
+      // name 字段允许为任意表达式，这里只做“存在性”检查
+      result.hasName = true;
+
+      // 仅当为字符串字面量时，才记录具体值（用于后续与 factory key 的强一致校验）
+      if (prop.value?.type === "Literal" && typeof prop.value.value === "string") {
+        result.nameValue = prop.value.value;
+      }
+    }
+
+    if (keyName === "type") {
+      if (prop.value?.type === "Literal" && typeof prop.value.value === "string") {
+        result.typeValue = prop.value.value;
+      }
+    }
+  }
+
+  return result;
+}
+
+/**
+ * 获取 MemberExpression 的调用链（从根到叶）
+ * 例如 Phaser.GameObjects.GameObjectFactory.remove => ['Phaser','GameObjects','GameObjectFactory','remove']
+ * @param {import('estree').Expression} callee
+ */
+function getMemberChain(callee) {
+  /** @type {string[]} */
+  const parts = [];
+
+  /** @type {any} */
+  let current = callee;
+
+  while (current && current.type === "MemberExpression") {
+    const propertyName =
+      current.property?.type === "Identifier"
+        ? current.property.name
+        : current.property?.type === "Literal"
+          ? String(current.property.value)
+          : undefined;
+
+    if (!propertyName) return [];
+
+    parts.unshift(propertyName);
+    current = current.object;
+  }
+
+  // 根节点必须是 Identifier，例如 Phaser
+  if (current && current.type === "Identifier") {
+    parts.unshift(current.name);
+    return parts;
+  }
+
+  return [];
+}
+
+/**
+ * 判断 CallExpression 的 callee 是否匹配指定成员链
+ * @param {import('estree').CallExpression} node
+ * @param {string[]} chain
+ */
+function isCallOfMemberChain(node, chain) {
+  if (!node || node.type !== "CallExpression") return false;
+
+  const actual = getMemberChain(node.callee);
+  if (actual.length !== chain.length) return false;
+
+  for (let i = 0; i < chain.length; i++) {
+    if (actual[i] !== chain[i]) return false;
+  }
+
+  return true;
+}
+
+/**
+ * 获取一个节点用于排序的 key（优先 range，其次 loc）
+ * @param {import('estree').Node} node
+ */
+function getOrderKey(node) {
+  const rangeStart = Array.isArray(node?.range) ? node.range[0] : undefined;
+  if (typeof rangeStart === "number") return rangeStart;
+
+  const line = node?.loc?.start?.line;
+  const column = node?.loc?.start?.column;
+  if (typeof line === "number" && typeof column === "number") {
+    return line * 1000000 + column;
+  }
+
+  return 0;
+}
+
+/**
+ * @param {import('eslint').Rule.RuleContext} context
+ */
+function reportAtFileStart(context, messageId, data) {
+  context.report({
+    loc: { line: 1, column: 0 },
+    messageId,
+    data,
+  });
+}
+
+module.exports = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "约束 prefab 预制件文件的通用共性结构",
+      recommended: false,
+    },
+    schema: [],
+    messages: {
+      missingPhaserImport: "必须存在 `import Phaser from 'phaser'`（默认导入名必须为 Phaser）",
+      missingKitImports: "必须从 `@aurora.js/phaser-kit` 引入 BasePrefab、PrefabConfig、PrefabProps",
+      missingPrefabConfig: "必须存在至少一个 `const xxx: PrefabConfig = { ... }` 配置对象",
+      prefabConfigMissingName: "`PrefabConfig` 配置对象必须包含 `name` 字段",
+      prefabConfigInvalidType: "`PrefabConfig.type` 必须为字符串字面量 'Prefab'",
+      missingDefaultPrefabClass: "必须存在 `export default class Xxx extends BasePrefab`",
+      missingGetPrefabConfig: "默认导出 Prefab 类必须实现 `protected getPrefabConfig(): PrefabConfig`",
+      invalidGetPrefabConfigSignature: "`getPrefabConfig` 的签名必须为 `protected getPrefabConfig(): PrefabConfig`",
+      invalidGetPrefabConfigReturn:
+        "`getPrefabConfig()` 必须 `return` 本文件内声明的 PrefabConfig 配置对象标识符",
+      missingFactoryRemove: "必须包含 `Phaser.GameObjects.GameObjectFactory.remove('<key>')`",
+      missingFactoryRegister: "必须包含 `Phaser.GameObjects.GameObjectFactory.register('<key>', ...)`",
+      factoryKeyMismatch: "GameObjectFactory.remove/register 的 key 必须一致，且与 PrefabConfig.name 一致",
+      factoryOrderInvalid: "必须先调用 GameObjectFactory.remove，再调用 GameObjectFactory.register",
+    },
+  },
+
+  /**
+   * @param {import('eslint').Rule.RuleContext} context
+   */
+  create(context) {
+    // 为了避免误报，这里再按文件名做一次兜底过滤（配置层也会按文件模式启用）
+    const fileName = context.getFilename?.()?.toLowerCase?.() || "";
+    if (!fileName.endsWith("prefab.ts")) {
+      return {};
+    }
+
+    /** @type {Set<string>} */
+    const auroraKitNamedImports = new Set();
+
+    /** @type {Map<string, {hasName?: boolean, nameValue?: string, typeValue?: string}>} */
+    const prefabConfigMap = new Map();
+
+    /** @type {string | undefined} */
+    let defaultClassName;
+
+    /** @type {string | undefined} */
+    let getPrefabConfigReturnIdentifier;
+
+    /** @type {{key?: string, loc?: import('estree').SourceLocation, rangeStart?: number}[]} */
+    const removeCalls = [];
+
+    /** @type {{key?: string, loc?: import('estree').SourceLocation, rangeStart?: number}[]} */
+    const registerCalls = [];
+
+    let hasPhaserImport = false;
+
+    return {
+      /**
+       * Program 里做一次整文件检查，避免散落到多个 visitor 造成状态难维护
+       * @param {import('estree').Program} program
+       */
+      Program(program) {
+        // 1) import 语义检查
+        for (const node of program.body || []) {
+          if (node.type !== "ImportDeclaration") continue;
+
+          if (isPhaserDefaultImport(node)) {
+            hasPhaserImport = true;
+          }
+
+          for (const name of getNamedImportsFrom(node, "@aurora.js/phaser-kit")) {
+            auroraKitNamedImports.add(name);
+          }
+        }
+
+        if (!hasPhaserImport) {
+          reportAtFileStart(context, "missingPhaserImport");
+        }
+
+        const hasBasePrefab = auroraKitNamedImports.has("BasePrefab");
+        const hasPrefabConfig = auroraKitNamedImports.has("PrefabConfig");
+        const hasPrefabProps = auroraKitNamedImports.has("PrefabProps");
+        if (!hasBasePrefab || !hasPrefabConfig || !hasPrefabProps) {
+          reportAtFileStart(context, "missingKitImports");
+        }
+
+        // 2) 扫描变量声明：PrefabConfig 配置对象
+        for (const node of program.body || []) {
+          if (node.type !== "VariableDeclaration") continue;
+
+          for (const declarator of node.declarations || []) {
+            if (declarator.type !== "VariableDeclarator") continue;
+            if (declarator.id?.type !== "Identifier") continue;
+
+            // const xxx: PrefabConfig = { ... }
+            if (!hasTSTypeAnnotation(declarator.id, "PrefabConfig")) continue;
+
+            if (declarator.init?.type !== "ObjectExpression") {
+              // 允许先只认 ObjectExpression，避免复杂表达式误报
+              continue;
+            }
+
+            const fields = readPrefabConfigFields(declarator.init);
+            prefabConfigMap.set(declarator.id.name, fields);
+
+            if (!fields.hasName) {
+              context.report({ node: declarator, messageId: "prefabConfigMissingName" });
+            }
+            if (fields.typeValue !== "Prefab") {
+              context.report({ node: declarator, messageId: "prefabConfigInvalidType" });
+            }
+          }
+        }
+
+        if (prefabConfigMap.size === 0) {
+          reportAtFileStart(context, "missingPrefabConfig");
+        }
+
+        // 3) 扫描 export default class 是否继承 BasePrefab，并找 getPrefabConfig 的 return
+        for (const node of program.body || []) {
+          if (node.type !== "ExportDefaultDeclaration") continue;
+
+          const declaration = node.declaration;
+          if (!declaration || declaration.type !== "ClassDeclaration") continue;
+
+          const superClass = declaration.superClass;
+          const isExtendsBasePrefab =
+            superClass && superClass.type === "Identifier" && superClass.name === "BasePrefab";
+
+          if (!isExtendsBasePrefab) continue;
+
+          defaultClassName = declaration.id?.name;
+
+          // 找 getPrefabConfig 方法
+          const classBody = declaration.body?.body || [];
+          const getPrefabConfigMethod = classBody.find(
+            (m) =>
+              m.type === "MethodDefinition" &&
+              m.key?.type === "Identifier" &&
+              m.key.name === "getPrefabConfig"
+          );
+
+          if (!getPrefabConfigMethod || getPrefabConfigMethod.type !== "MethodDefinition") {
+            continue;
+          }
+
+          // 要求签名为：protected getPrefabConfig(): PrefabConfig
+          const accessibility = /** @type {any} */ (getPrefabConfigMethod).accessibility;
+          const returnType = /** @type {any} */ (getPrefabConfigMethod).value?.returnType
+            ?.typeAnnotation;
+          const isReturnPrefabConfig =
+            returnType?.type === "TSTypeReference" &&
+            returnType.typeName?.type === "Identifier" &&
+            returnType.typeName.name === "PrefabConfig";
+
+          if (accessibility !== "protected" || !isReturnPrefabConfig) {
+            context.report({
+              node: getPrefabConfigMethod,
+              messageId: "invalidGetPrefabConfigSignature",
+            });
+          }
+
+          // 获取返回值标识符：return xxx
+          const bodyStatements = /** @type {any} */ (getPrefabConfigMethod).value?.body?.body || [];
+          for (const st of bodyStatements) {
+            if (st.type !== "ReturnStatement") continue;
+            if (st.argument?.type === "Identifier") {
+              getPrefabConfigReturnIdentifier = st.argument.name;
+              break;
+            }
+          }
+        }
+
+        if (!defaultClassName) {
+          reportAtFileStart(context, "missingDefaultPrefabClass");
+        }
+
+        if (!getPrefabConfigReturnIdentifier) {
+          reportAtFileStart(context, "missingGetPrefabConfig");
+        }
+
+        if (getPrefabConfigReturnIdentifier && !prefabConfigMap.has(getPrefabConfigReturnIdentifier)) {
+          reportAtFileStart(context, "invalidGetPrefabConfigReturn");
+        }
+
+        // 4) 扫描 remove / register 调用
+        // 说明：不要求一定“文件末尾”，但要求 remove 在 register 之前
+        /** @type {import('estree').Node[]} */
+        const stack = [...(program.body || [])];
+
+        while (stack.length > 0) {
+          const current = stack.pop();
+          if (!current) continue;
+
+          // 简易 DFS：把子节点推进栈
+          for (const value of Object.values(current)) {
+            if (!value) continue;
+            if (Array.isArray(value)) {
+              for (const item of value) {
+                if (item && typeof item.type === "string") stack.push(item);
+              }
+            } else if (value && typeof value.type === "string") {
+              stack.push(value);
+            }
+          }
+
+          if (current.type !== "CallExpression") continue;
+
+          const call = current;
+
+          if (isCallOfMemberChain(call, ["Phaser", "GameObjects", "GameObjectFactory", "remove"])) {
+            const firstArg = call.arguments?.[0];
+            if (firstArg?.type === "Literal" && typeof firstArg.value === "string") {
+              removeCalls.push({
+                key: firstArg.value,
+                loc: call.loc,
+                rangeStart: getOrderKey(call),
+              });
+            }
+          }
+
+          if (isCallOfMemberChain(call, ["Phaser", "GameObjects", "GameObjectFactory", "register"])) {
+            const firstArg = call.arguments?.[0];
+            if (firstArg?.type === "Literal" && typeof firstArg.value === "string") {
+              registerCalls.push({
+                key: firstArg.value,
+                loc: call.loc,
+                rangeStart: getOrderKey(call),
+              });
+            }
+          }
+        }
+
+        // 5) 规则校验：remove/register 必须存在
+        if (removeCalls.length === 0) {
+          reportAtFileStart(context, "missingFactoryRemove");
+        }
+        if (registerCalls.length === 0) {
+          reportAtFileStart(context, "missingFactoryRegister");
+        }
+
+        if (removeCalls.length > 0 && registerCalls.length > 0) {
+          const firstRemove = removeCalls.sort((a, b) => (a.rangeStart || 0) - (b.rangeStart || 0))[0];
+          const firstRegister = registerCalls
+            .sort((a, b) => (a.rangeStart || 0) - (b.rangeStart || 0))[0];
+
+          // 先 remove 后 register
+          if ((firstRemove.rangeStart || 0) > (firstRegister.rangeStart || 0)) {
+            reportAtFileStart(context, "factoryOrderInvalid");
+          }
+
+          // key 必须一致
+          const removeKey = firstRemove.key;
+          const registerKey = firstRegister.key;
+          if (!removeKey || !registerKey || removeKey !== registerKey) {
+            reportAtFileStart(context, "factoryKeyMismatch");
+          } else {
+            // 且必须等于 PrefabConfig.name
+            const configIdentifier = getPrefabConfigReturnIdentifier;
+            const config = configIdentifier ? prefabConfigMap.get(configIdentifier) : undefined;
+            const configName = config?.nameValue;
+
+            // 仅当能够静态解析出 name 的字符串字面量时，才强校验 key 与 name 的一致性
+            if (typeof configName === "string" && configName !== removeKey) {
+              reportAtFileStart(context, "factoryKeyMismatch");
+            }
+          }
+        }
+      },
+    };
+  },
+};

package/lib/rules/scene-check.js

@@ -0,0 +1,224 @@
+"use strict";
+
+/**
+ * @fileoverview Scene（*.scene.ts / *scene.ts）通用结构 ESLint 规则
+ *
+ * 说明：
+ * - 本规则仅做“语义检查”，不做 import 路径可解析性校验。
+ */
+
+/**
+ * 判断一个 ImportDeclaration 是否是 `import Phaser from 'phaser'`
+ * @param {import('estree').ImportDeclaration} node
+ */
+function isPhaserDefaultImport(node) {
+  if (!node || node.type !== "ImportDeclaration") return false;
+  if (!node.source || node.source.type !== "Literal" || node.source.value !== "phaser") return false;
+
+  const defaultSpecifier = node.specifiers?.find((s) => s.type === "ImportDefaultSpecifier");
+  return Boolean(defaultSpecifier && defaultSpecifier.local && defaultSpecifier.local.name === "Phaser");
+}
+
+/**
+ * 从指定模块的 import 中提取命名导入（忽略 type/value 形式差异）
+ * @param {import('estree').ImportDeclaration} node
+ * @param {string} sourceValue
+ */
+function getNamedImportsFrom(node, sourceValue) {
+  if (!node || node.type !== "ImportDeclaration") return [];
+  if (!node.source || node.source.type !== "Literal" || node.source.value !== sourceValue) return [];
+
+  return (node.specifiers || [])
+    .filter((s) => s.type === "ImportSpecifier")
+    .map((s) => s.imported?.name)
+    .filter(Boolean);
+}
+
+/**
+ * 判断 Identifier 的 TS 类型注解是否为指定类型名
+ * @param {import('estree').Identifier} id
+ * @param {string} typeName
+ */
+function hasTSTypeAnnotation(id, typeName) {
+  const typeAnnotation = id?.typeAnnotation?.typeAnnotation;
+  if (!typeAnnotation) return false;
+
+  if (typeAnnotation.type === "TSTypeReference") {
+    return (
+      typeAnnotation.typeName?.type === "Identifier" && typeAnnotation.typeName.name === typeName
+    );
+  }
+
+  return false;
+}
+
+/**
+ * @param {import('eslint').Rule.RuleContext} context
+ */
+function reportAtFileStart(context, messageId, data) {
+  context.report({
+    loc: { line: 1, column: 0 },
+    messageId,
+    data,
+  });
+}
+
+module.exports = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "约束 scene 场景文件的通用共性结构",
+      recommended: false,
+    },
+    schema: [],
+    messages: {
+      missingPhaserImport: "必须存在 `import Phaser from 'phaser'`（默认导入名必须为 Phaser）",
+      missingBaseSceneImports: "必须从 `src/kit/BaseScene` 引入 BaseScene 与 NodeConfig",
+      missingNodeConfig: "必须存在至少一个 `const xxx: NodeConfig = { ... }` 配置对象",
+      missingDefaultSceneClass: "必须存在 `export default class Xxx extends BaseScene`",
+      missingGetSceneConfig: "默认导出 Scene 类必须实现 `protected getSceneConfig(): NodeConfig`",
+      invalidGetSceneConfigSignature: "`getSceneConfig` 的签名必须为 `protected getSceneConfig(): NodeConfig`",
+      invalidGetSceneConfigReturn: "`getSceneConfig()` 必须 `return` 本文件内声明的 NodeConfig 配置对象标识符",
+    },
+  },
+
+  /**
+   * @param {import('eslint').Rule.RuleContext} context
+   */
+  create(context) {
+    const fileName = context.getFilename?.()?.toLowerCase?.() || "";
+    if (!fileName.endsWith("scene.ts")) {
+      return {};
+    }
+
+    /** @type {Set<string>} */
+    const baseSceneNamedImports = new Set();
+
+    /** @type {Set<string>} */
+    const nodeConfigIdentifiers = new Set();
+
+    /** @type {string | undefined} */
+    let defaultSceneClassName;
+
+    /** @type {string | undefined} */
+    let getSceneConfigReturnIdentifier;
+
+    let hasPhaserImport = false;
+
+    return {
+      /**
+       * @param {import('estree').Program} program
+       */
+      Program(program) {
+        // 1) import 语义检查
+        for (const node of program.body || []) {
+          if (node.type !== "ImportDeclaration") continue;
+
+          if (isPhaserDefaultImport(node)) {
+            hasPhaserImport = true;
+          }
+
+          for (const name of getNamedImportsFrom(node, "src/kit/BaseScene")) {
+            baseSceneNamedImports.add(name);
+          }
+        }
+
+        if (!hasPhaserImport) {
+          reportAtFileStart(context, "missingPhaserImport");
+        }
+
+        const hasBaseScene = baseSceneNamedImports.has("BaseScene");
+        const hasNodeConfig = baseSceneNamedImports.has("NodeConfig");
+        if (!hasBaseScene || !hasNodeConfig) {
+          reportAtFileStart(context, "missingBaseSceneImports");
+        }
+
+        // 2) 扫描 NodeConfig 配置对象
+        for (const node of program.body || []) {
+          if (node.type !== "VariableDeclaration") continue;
+
+          for (const declarator of node.declarations || []) {
+            if (declarator.type !== "VariableDeclarator") continue;
+            if (declarator.id?.type !== "Identifier") continue;
+
+            if (!hasTSTypeAnnotation(declarator.id, "NodeConfig")) continue;
+
+            // 只记录标识符名即可
+            nodeConfigIdentifiers.add(declarator.id.name);
+          }
+        }
+
+        if (nodeConfigIdentifiers.size === 0) {
+          reportAtFileStart(context, "missingNodeConfig");
+        }
+
+        // 3) 扫描默认导出类，继承 BaseScene，并找到 getSceneConfig return
+        for (const node of program.body || []) {
+          if (node.type !== "ExportDefaultDeclaration") continue;
+
+          const declaration = node.declaration;
+          if (!declaration || declaration.type !== "ClassDeclaration") continue;
+
+          const superClass = declaration.superClass;
+          const isExtendsBaseScene =
+            superClass && superClass.type === "Identifier" && superClass.name === "BaseScene";
+
+          if (!isExtendsBaseScene) continue;
+
+          defaultSceneClassName = declaration.id?.name;
+
+          // 找 getSceneConfig 方法
+          const classBody = declaration.body?.body || [];
+          const getSceneConfigMethod = classBody.find(
+            (m) =>
+              m.type === "MethodDefinition" &&
+              m.key?.type === "Identifier" &&
+              m.key.name === "getSceneConfig"
+          );
+
+          if (!getSceneConfigMethod || getSceneConfigMethod.type !== "MethodDefinition") {
+            continue;
+          }
+
+          // 要求签名为：protected getSceneConfig(): NodeConfig
+          const accessibility = /** @type {any} */ (getSceneConfigMethod).accessibility;
+          const returnType = /** @type {any} */ (getSceneConfigMethod).value?.returnType
+            ?.typeAnnotation;
+          const isReturnNodeConfig =
+            returnType?.type === "TSTypeReference" &&
+            returnType.typeName?.type === "Identifier" &&
+            returnType.typeName.name === "NodeConfig";
+
+          if (accessibility !== "protected" || !isReturnNodeConfig) {
+            context.report({
+              node: getSceneConfigMethod,
+              messageId: "invalidGetSceneConfigSignature",
+            });
+          }
+
+          // 尝试获取返回标识符：return xxx
+          const bodyStatements = /** @type {any} */ (getSceneConfigMethod).value?.body?.body || [];
+          for (const st of bodyStatements) {
+            if (st.type !== "ReturnStatement") continue;
+            if (st.argument?.type === "Identifier") {
+              getSceneConfigReturnIdentifier = st.argument.name;
+              break;
+            }
+          }
+        }
+
+        if (!defaultSceneClassName) {
+          reportAtFileStart(context, "missingDefaultSceneClass");
+        }
+
+        if (!getSceneConfigReturnIdentifier) {
+          reportAtFileStart(context, "missingGetSceneConfig");
+        }
+
+        if (getSceneConfigReturnIdentifier && !nodeConfigIdentifiers.has(getSceneConfigReturnIdentifier)) {
+          reportAtFileStart(context, "invalidGetSceneConfigReturn");
+        }
+      },
+    };
+  },
+};

package/lib/rules/trial-check.js

@@ -0,0 +1,126 @@
+"use strict";
+
+/**
+ * @fileoverview 校验 trialservice.ts 规范的 ESLint 规则
+ * 仅在匹配到 trialGeneration/<any>/trialservice.ts 时生效
+ */
+
+const WINDOWS_SEPARATOR = "\\";
+const POSIX_SEPARATOR = "/";
+
+const isInTrialGeneration = (fileName) =>
+  fileName.includes(`${POSIX_SEPARATOR}trialGeneration${POSIX_SEPARATOR}`) ||
+  fileName.includes(`${WINDOWS_SEPARATOR}trialGeneration${WINDOWS_SEPARATOR}`);
+
+// 约定：Trial 服务文件名固定为 trialservice.ts（不支持大小写变体）
+const isTrialServiceFile = (fileName) => fileName.toLowerCase().endsWith("trialservice.ts");
+
+const getBaseName = (fileName) => fileName.split(/[\\/]/).pop();
+
+/**
+ * 辅助函数：检查 generate 方法的返回值
+ * @param {import('estree').MethodDefinition} methodNode - generate 方法 AST 节点
+ * @param {import('eslint').Rule.RuleContext} context - ESLint 上下文
+ */
+const checkGenerateMethodReturn = (methodNode, context) => {
+  const body = methodNode.value?.body;
+  if (!body || body.type !== "BlockStatement") return;
+
+  const returnStatements = body.body.filter((statement) => statement.type === "ReturnStatement");
+
+  returnStatements.forEach((returnStatement) => {
+    const argument = returnStatement.argument;
+
+    if (argument && argument.type === "ObjectExpression") {
+      const hasTargetAnswer = argument.properties.some((prop) => {
+        if (!prop || prop.type !== "Property") return false;
+        if (!prop.key) return false;
+        return prop.key.name === "target_answer" || prop.key.value === "target_answer";
+      });
+
+      if (!hasTargetAnswer) {
+        context.report({
+          node: returnStatement,
+          messageId: "noTargetAnswer",
+        });
+      }
+    }
+  });
+};
+
+module.exports = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "约束 trialservice.ts 的实现规范",
+      recommended: false,
+    },
+    schema: [],
+    messages: {
+      invalidFileName: "试题服务文件必须命名为 trialservice.ts (当前: {{name}})",
+      noGeneratorClass: "必须定义一个继承自 TrialGenerator 的类",
+      noGenerateMethod: "Generator 类必须实现 generate 方法",
+      noTargetAnswer: "generate 方法返回值必须包含 target_answer 字段",
+    },
+  },
+
+  create(context) {
+    const fileName = context.getFilename?.() || "";
+
+    // 非目标目录或非目标文件直接跳过
+    if (!fileName || fileName === "<input>" || !isInTrialGeneration(fileName) || !isTrialServiceFile(fileName)) {
+      return {};
+    }
+
+    let hasGeneratorClass = false;
+
+    return {
+      Program() {
+        const baseName = getBaseName(fileName) || "";
+        if (baseName !== "trialservice.ts") {
+          context.report({
+            loc: { line: 1, column: 0 },
+            messageId: "invalidFileName",
+            data: { name: baseName },
+          });
+        }
+      },
+
+      ClassDeclaration(node) {
+        if (
+          node.superClass &&
+          node.superClass.type === "Identifier" &&
+          node.superClass.name === "TrialGenerator"
+        ) {
+          hasGeneratorClass = true;
+
+          const generateMethod = node.body.body.find(
+            (element) =>
+              element.type === "MethodDefinition" &&
+              element.key?.type === "Identifier" &&
+              element.key.name === "generate"
+          );
+
+          if (!generateMethod) {
+            context.report({
+              node: node.id || node,
+              messageId: "noGenerateMethod",
+            });
+            return;
+          }
+
+          checkGenerateMethodReturn(generateMethod, context);
+        }
+      },
+
+      "Program:exit"() {
+        if (!hasGeneratorClass) {
+          context.report({
+            loc: { line: 1, column: 0 },
+            messageId: "noGeneratorClass",
+          });
+        }
+      },
+    };
+  },
+};

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "eslint-plugin-aurora-999",
+  "version": "0.1.0",
+  "description": "Aurora ESLint plugin (rules) + flat config (recommended)",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js"
+  },
+  "files": [
+    "lib"
+  ],
+  "keywords": [
+    "eslint",
+    "eslintplugin",
+    "eslint-plugin",
+    "aurora"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "peerDependencies": {
+    "eslint": "^9.0.0"
+  },
+  "dependencies": {
+    "@eslint/js": "^9.0.0",
+    "eslint-import-resolver-typescript": "^3.6.0",
+    "eslint-plugin-import": "^2.29.0",
+    "globals": "^15.0.0",
+    "typescript-eslint": "^8.0.0"
+  }
+}