jax-hono 1.0.14 → 1.0.15

package/README.md

@@ -1,6 +1,8 @@
 # Jax-hono
 
-Jax 是本项目的轻量框架层。完整说明见 [docs/jax.md](docs/jax.md)。
+Jax 是本项目的轻量框架层。完整说明见 [docs/jax.md](docs/jax.md)。
+
+给 Codex、Claude 等代码代理看的维护说明见 [docs/agent.md](docs/agent.md)。
 
 维护 Jax 内部代码时按目录职责放置文件：
 

package/build/generate-registry.ts

@@ -30,7 +30,7 @@ const controllerGroups: ControllerGroup[] = [
   { name: 'backend', dirs: ['backend', 'controllers/backend', 'controller/backend', 'modules'], suffix: '.backend' },
   { name: 'open', dirs: ['open', 'controllers/open', 'controller/open', 'modules'], suffix: '.open' },
   { name: 'client', dirs: ['client', 'controllers/client', 'controller/client', 'modules'], suffix: '.client' },
-  { name: 'controller', dirs: ['controllers', 'controller'] },
+  { name: 'controller', dirs: ['controllers', 'controller', 'modules'], suffix: '.controller' },
 ]
 
 const scopedControllerGroups = new Set(
@@ -126,15 +126,25 @@ function stripKnownSuffix(modulePath: string, suffixes: string[]) {
   return modulePath
 }
 
-function normalizeModulePath(modulePath: string) {
-  const parts = modulePath.split('/')
-  const last = parts.at(-1)
-  const parent = parts.at(-2)
-
-  return last && parent && last === parent
-    ? parts.slice(0, -1).join('/')
-    : modulePath
-}
+function normalizeModulePath(modulePath: string) {
+  const parts = modulePath.split('/')
+  const last = parts.at(-1)
+  const parent = parts.at(-2)
+
+  if (!last || !parent) {
+    return modulePath
+  }
+
+  if (last === parent) {
+    return parts.slice(0, -1).join('/')
+  }
+
+  if (last.startsWith(`${parent}-`) || last.startsWith(`${parent}_`)) {
+    return [...parts.slice(0, -2), last].join('/')
+  }
+
+  return modulePath
+}
 
 function toModulePath(baseDir: string, filePath: string, suffixes: string[] = []) {
   const modulePath = relative(join(srcDir, baseDir), filePath)
@@ -170,13 +180,13 @@ function isSuffixedModuleFile(filePath: string, suffix: string) {
     .endsWith(suffix)
 }
 
-function isModuleFeatureFile(filePath: string, suffix: string) {
-  return !isFileInDir(filePath, 'modules') || isSuffixedModuleFile(filePath, suffix)
-}
-
-function hasDefaultExport(filePath: string) {
-  return /\bexport\s+default\b/.test(readFileSync(filePath, 'utf8'))
-}
+function isModuleFeatureFile(filePath: string, suffix: string) {
+  return !isFileInDir(filePath, 'modules') || isSuffixedModuleFile(filePath, suffix)
+}
+
+function hasDefaultExport(filePath: string) {
+  return /\bexport\s+default\b/.test(readFileSync(filePath, 'utf8'))
+}
 
 function indentObject(content: string, spaces = 2) {
   if (!content) {
@@ -226,18 +236,18 @@ function generateControllersRegistry() {
   const groupLines: string[] = []
 
   for (const group of controllerGroups) {
-    const entries = getFilesFromDirs(group.dirs)
-      .filter((filePath) => basename(filePath) !== 'index.ts')
-      .filter((filePath) => !group.suffix || isModuleFeatureFile(filePath, group.suffix))
-      .filter(hasDefaultExport)
-      .map((filePath, index) => {
-        const baseDir = group.dirs.find((dirName) => {
-          return isFileInDir(filePath, dirName)
-        }) ?? group.dirs[0]
-        const modulePath = toModulePath(baseDir, filePath, group.suffix ? [group.suffix] : [])
-        const importName = toIdentifier([group.name, modulePath, String(index), 'Controller'])
-
-        return { modulePath, importName, filePath }
+    const entries = getFilesFromDirs(group.dirs)
+      .filter((filePath) => basename(filePath) !== 'index.ts')
+      .filter((filePath) => !group.suffix || isModuleFeatureFile(filePath, group.suffix))
+      .filter(hasDefaultExport)
+      .map((filePath, index) => {
+        const baseDir = group.dirs.find((dirName) => {
+          return isFileInDir(filePath, dirName)
+        }) ?? group.dirs[0]
+        const modulePath = toModulePath(baseDir, filePath, group.suffix ? [group.suffix] : [])
+        const importName = toIdentifier([group.name, modulePath, String(index), 'Controller'])
+
+        return { modulePath, importName, filePath }
       })
       .filter((entry) => {
         if (group.name !== 'controller') {
@@ -274,8 +284,12 @@ function generateControllersRegistry() {
       4,
     )
 
-    groupLines.push(`  ${group.name}: {\n${objectBody}\n  },`)
-  }
+    if (group.name === 'controller') {
+      groupLines.push(objectBody)
+    } else {
+      groupLines.push(`  ${group.name}: {\n${objectBody}\n  },`)
+    }
+  }
 
   const helperImport = imports.length > 0
     ? `import { createController } from 'jax-hono/core/controller'\n`

package/docs/agent.md

@@ -0,0 +1,105 @@
+# Agent 维护说明
+
+这份文档给 Codex、Claude 或其他代码代理阅读，用来说明维护 `jax-hono` 时的默认规则。
+
+## 本地 link 规则
+
+`jax-hono` 是用户自己维护的框架，常通过 `jax link` 链接到业务工程的 `node_modules/jax-hono`。
+
+如果在业务工程中需要修改 `jax-hono` 行为，先检查依赖是否已经 link 到本地源码目录。不要把它当成一次性的第三方 `node_modules` 临时补丁。
+
+在 Windows PowerShell 中，可以在业务仓库根目录查找所有 `jax-hono` 依赖：
+
+```powershell
+Get-ChildItem -Path . -Directory -Recurse -Filter jax-hono |
+  Where-Object { $_.FullName -match '\\node_modules\\jax-hono$' } |
+  Format-List LinkType,Target,FullName
+```
+
+如果 `LinkType` 是 `Junction` 或 `SymbolicLink`，直接修改 `Target` 指向的 `jax-hono` 源码目录。
+
+如果没有 link，先执行：
+
+```powershell
+jax link
+```
+
+然后再次确认 link 状态，再修改框架源码。
+
+## 修改生成器后的验证
+
+修改 `build/generate-registry.ts`、`build/generate-config.ts` 等生成逻辑后，需要在使用方工程里重新生成。
+
+常见命令：
+
+```powershell
+bun run setup
+```
+
+然后检查业务工程中的生成结果，例如：
+
+```text
+generated/controllers.generated.ts
+generated/models.generated.ts
+generated/services.generated.ts
+generated/middlewares.generated.ts
+generated/plugins.generated.ts
+```
+
+如果业务仓库里有多个工程都依赖 `jax-hono`，分别查看各工程的 `package.json`，运行它们自己的 setup/build 命令。
+
+## Controller 注册约定
+
+生成器需要保持不同命名空间的边界清晰：
+
+- `*.backend.ts` 注册到 `controllers.backend`
+- `*.api.ts` 注册到 `controllers.api`
+- `*.open.ts` 注册到 `controllers.open`
+- `*.client.ts` 注册到 `controllers.client`
+- `*.controller.ts` 注册到 `controllers` 根对象
+
+`.controller.ts` 表示通用 Controller，供 backend/api/open/client 等不同路由复用，不应自动归入 `controllers.backend`。
+
+例如：
+
+```text
+src/modules/oss/oss.controller.ts
+src/modules/oss/oss-bucket.controller.ts
+```
+
+应生成：
+
+```ts
+controllers.oss
+controllers.ossBucket
+```
+
+如果需要后台专用 Controller，使用：
+
+```text
+src/modules/foo/foo.backend.ts
+```
+
+应生成：
+
+```ts
+controllers.backend.foo
+```
+
+## 模块路径命名
+
+模块内文件名如果以模块目录名开头，生成 key 时可以去掉重复前缀：
+
+```text
+src/modules/oss/oss.controller.ts        -> controllers.oss
+src/modules/oss/oss-bucket.controller.ts -> controllers.ossBucket
+```
+
+不要生成成：
+
+```ts
+controllers.oss.oss
+controllers.oss.ossBucket
+```
+
+这样业务侧调用会更自然，也更适合在不同路由层复用。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jax-hono",
-  "version": "1.0.14",
+  "version": "1.0.15",
   "description": "Lightweight framework layer on top of Hono, built for Bun",
   "type": "module",
   "main": "./index.ts",