@planet-matrix/mobius-mono 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @planet-matrix/mobius-mono
 
+## 0.4.0
+
+### Minor Changes
+
+- e69bf92: update Mobius Mono Spec.
+
+## 0.3.1
+
+### Patch Changes
+
+- 5216b44: fix $schema path for oxlintrc.json and oxfmtrc.json
+
 ## 0.3.0
 
 ### Minor Changes

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-present, Planet Matrix Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,24 +1,158 @@
 # Mobius Mono
 
-Repository rules as code.
+Mobius Mono 是一个用于规范项目的项目，由规范文本（Specification）、配套工具（Tool）组成。
+
+该规范的正式名称为 Mobius Mono。在指称该规范时，可称为“Mobius Mono 规范”或“Mobius Mono Spec”。
 
 ## Principles
 
-- 不考虑保障原则与 Mobius Mono 相悖的项目的开发体验。
+- 不考虑保障不符合 Mobius Mono 规范的项目的开发体验。
 - 优先使用 TypeScript，并且只在必要的时候转译为 JavaScript。
 - 业务代码中优先使用跨运行时、跨平台兼容的特性。
-- 优先使用 Bun 提供的 infra 能力。
+- 优先使用 Bun 提供的基础设施（infra）。
 - 优先使用 Oxc 生态系统中的工具。
+- 所有敏感信息都只通过环境变量提供。
+
+## Specification
+
+### Monorepo
+
+- 所有子包均放置在 `packages/` 目录下，仅支持一级子包，不支持多级嵌套。
+- Monorepo 只是为了方便管理多个包，并不影响每个包的独立性，每个子包都拥有独立的 `package.json`、`tsconfig.json`、`README.md`、`LICENSE` 等文件，可以独立发布。
+
+### File
+
+- 文件、目录命名格式应使用 kebab-case，约定俗成的文件或目录可以例外，如 `node_modules` 等。
+- 文件、目录命名区分大小写且应该尽可能只使用小写字母，约定俗成的文件或目录可以例外，如 `README.md`、`CHANGELOG.md`、`LICENSE` 等。
+- 文件、目录命名时，表示集合用复数，如 `scripts`、`tests`、`docs` 等，表示概念用单数，如 `dist`、`signal`、`build` 等，约定俗成的文件或目录可以例外，如 `src`、`bin` 等。
+
+### Package
+
+- 使用 Bun 作为包管理工具。
+- 无论是源代码还是打包产物，都只支持 ES Modules。
+- 本地发包时，npm token 写在操作者的全局 `.npmrc` 中，CI/CD 发包时，使用 [Trusted publishing](https://docs.npmjs.com/trusted-publishers)。
+- 除敏感信息、临时文件、`node_modules` 外，其它所有文件均作为包的一部分进行发布。
+
+- `package.json` 一定要设置 `name` 字段。
+- `package.json` 一定要设置 `version` 字段。
+- `package.json` 一定要设置 `description` 字段。
+- `package.json` 一定要设置 `keywords` 字段。
+- `package.json` 一定要设置 `homepage` 字段，若没有 Homepage，该字段的值可设置为项目的仓库地址。
+- `package.json` 一定要设置 `bugs` 字段，`bugs` 字段的值一定要是对象，该对象一定要包含 `url` 字段，且 `url` 字段的值一定要是项目的 issue 地址，该对象一定要包含 `email` 字段，且 `email` 字段的值一定要是项目所有者的邮箱地址。
+- `package.json` 一定要设置 `license` 字段。
+- `package.json` 一定要设置 `author` 字段，且 `author` 字段的值一定要是对象，该对象一定要包含 `name` 字段，且 `name` 字段的值一定要是项目所有者的名称，该对象一定要包含 `email` 字段，且 `email` 字段的值一定要是项目所有者的邮箱地址，该对象一定要包含 `url` 字段，且 `url` 字段的值一定要是项目所有者的主页地址。
+- `package.json` 一定要设置 `contributors` 字段。
+- `package.json` 一定要设置 `files` 字段，`files` 字段的值一定要是 `["*"]`。
+- `package.json` 一定要设置 `bin` 字段，`bin` 字段的值一定要是对象。
+- `package.json` 一定要设置 `man` 字段，`man` 字段的值一定要是数组。
+- `package.json` 一定要设置 `type` 字段，该字段的值一定要是 `module`。
+- `package.json` 一定要设置 `exports` 字段，`exports` 字段的值一定要是对象，该对象至少要包含 `.` 字段用于指定包的主要入口文件，且 `.` 字段的值一定要是包含且只包含 `import` 字段的对象（只支持 ES Modules），且 `import` 字段的值一定要是对象，该对象的字段包含且只包含 `@planet-matrix/mobius-mono`、`bun`、`types` 和 `default` 四个字段（顺序一定要与描述一致，虽然 Node.js 推荐总是将 `types` 作为第一个 condition，但 Live TypeScript 追求直接指向 `.ts` 文件，因此将 `types` condition 后移）。示例如下：
+  ```jsonc
+  {
+    // other fields of package.json omitted
+    "exports": {
+      ".": {
+        "import": {
+          "@planet-matrix/mobius-mono": "./src/index.ts",
+          "bun": "./src/index.ts",
+          "types": "./dist/index.d.ts",
+          "default": "./dist/index.js"
+        }
+      },
+      // other subpath omitted
+    },
+    // other fields of package.json omitted
+  }
+  ```
+- `package.json` 一定要设置 `imports` 字段。示例如下：
+  ```jsonc
+  {
+    // other fields of package.json omitted
+    "imports": {
+      "#Project/*": {
+        "import": {
+          "@planet-matrix/mobius-mono": "./*",
+          "bun": "./*",
+          "default": "./*"
+        }
+      },
+      "#Source/*": {
+        "import": {
+          "@planet-matrix/mobius-mono": "./src/*",
+          "bun": "./src/*",
+          "default": "./src/*"
+        }
+      },
+      // other subpath omitted
+    },
+    // other fields of package.json omitted
+  }
+  ```
+- `package.json` 一定不要设置 `main` 字段。
+- `package.json` 一定要设置 `repository` 字段，且 `repository` 字段的值一定要是对象，该对象一定要包含 `type` 字段，且 `type` 字段的值一定要是 `git`，该对象一定要包含 `url` 字段，且 `url` 字段的值一定要是项目的仓库地址，如果该包位于 monorepo 中且该 `package.json` 不位于仓库根目录，该对象一定要包含 `directory` 字段，且 `directory` 字段的值一定要是该包相对于仓库根目录的路径。
+- `package.json` 一定要设置 `scripts` 字段。
+- `package.json` 一定要设置 `dependencies` 字段。
+- `package.json` 一定要设置 `devDependencies` 字段。
+- `package.json` 一定要设置 `peerDependencies` 字段。
+- `package.json` 一定要设置 `peerDependenciesMeta` 字段。
+- `package.json` 一定要设置 `bundleDependencies` 字段。
+- `package.json` 一定要设置 `optionalDependencies` 字段。
+- `package.json` 一定要设置 `overrides` 字段。
+
+### TypeScript
+
+- 仅将 TypeScript（此处不是指作为语言的 TypeScript，而是指配套的库或工具）作为提升开发体验的工具使用，将类型文件输出、代码转译等工作交给其它工具来完成。
+- TypeScript 配置尽量与 Bun 的推荐配置保持一致，见：https://bun.com/docs/typescript。
+
+- 将 `compilerOptions.allowImportingTsExtensions` 设置为 `true`，导入任意文件都一定要包含文件扩展名。
+- 将 `@planet-matrix/mobius-mono` 设置为 `compilerOptions.customConditions` 的第一项，遵循 Mobius Mono 规范的项目会将 `@planet-matrix/mobius-mono` 作为 conditional exports 的第一个 condition，从而实现 Live TypeScript（aka. Live Types）。
+- 将 `compilerOptions.module` 设置为 `preserve`，虽然我们不使用 TypeScript 来转译代码，但设置这个字段有助于 TypeScript 正确处理类型，从而提升开发体验。
+- 将 `compilerOptions.moduleResolution` 设置为 `bundler`，从而让 TypeScript 可以正确消费 `package.json` 中的 `imports` 和 `exports` 字段。
+- 将 `compilerOptions.noUncheckedSideEffectImports` 设置为 `true`，从而让 TypeScript 严格检查所有的副作用导入语句，避免导入不存在的模块。
+- 将 `compilerOptions.paths` 设置为 `{}`（即不使用该功能），使用 [subpath imports](https://nodejs.org/api/packages.html#subpath-imports) 作为替代方案，后者被 Node.js、Bun 等运行时原生支持，且在 `package.json` 中进行定义可以更加显式地体现包的情况。
+- 将 `compilerOptions.resolveJsonModule` 设置为 `true`，从而允许导入 JSON 文件。
+- 将 `compilerOptions.resolvePackageJsonExports` 设置为 `true`，从而让 TypeScript 可以正确消费 `package.json` 中的 `exports` 字段。
+- 将 `compilerOptions.resolvePackageJsonImports` 设置为 `true`，从而让 TypeScript 可以正确消费 `package.json` 中的 `imports` 字段。
+- 将 `compilerOptions.rewriteRelativeImportExtensions` 设置为 `false`，我们不使用 TypeScript 来转译代码，开启该选项会产生额外的报错，如 `This import uses a '.ts' extension to resolve to an input TypeScript file, but will not be rewritten during emit because it is not a relative path.`。
+- 将 `compilerOptions.typeRoots` 设置为 `["${configDir}/node_modules/@types"]`，从而让 TypeScript 只消费项目直接依赖的类型定义文件。
+- 将 `compilerOptions.types` 字段注释，否则 `compilerOptions.typeRoots` 不会生效。
+- 将 `compilerOptions.noEmit` 设置为 `true`，原因之一是我们不使用 TypeScript 来转译代码，原因之二是我们开启了 `compilerOptions.allowImportingTsExtensions`，开启该选项要求 `either --noEmit or --emitDeclarationOnly to be set`。
+- 将 `compilerOptions.forceConsistentCasingInFileNames` 设置为 `true`。
+- 将 `compilerOptions.isolatedDeclarations` 设置为 `true`。
+- 将 `compilerOptions.isolateModules` 设置为 `true`。
+- 将 `compilerOptions.verbatimModuleSyntax` 设置为 `true`。
+- 将 `compilerOptions.lib` 设置为 `["ESNext", "DOM", "WebWorker", "ScriptHost"]`，即默认启用所有不同运行环境的 API，以保持开发体验的一致性，正确性和跨平台兼容性由代码来保障。
+- 将 `compilerOptions.moduleDetection` 设置为 `force`，即要求尽可能将所有代码编写成模块。
+- 将 `compilerOptions.noLib` 设置为 `false`。
+- 将 `compilerOptions.target` 设置为 `esnext`，即拥抱最新的 JavaScript 特性。
+
+### Lint
+
 - 将 Formatting 视为 Linting 的一部分。
-- 源码即包，尽可能将所有可以发布的东西都作为包的一部分发布出去。
+- import 任意文件都一定要包含文件扩展名。
+
+### Build
+
+- `bin` 目录下的文件不需要打包，优先使用 Bun 直接运行。
+
+### Change
+
+- 基于 [changesets](https://github.com/changesets/changesets) 做变更管理。
 
-## Rules
+## Tool
 
-- 可执行文件放在单独的 `bin` 目录，不需要打包，通过 `package.json` 的 `bin` 字段对外提供。
-- `package.json` 不需要设置 `main` 字段。
+todo.
 
 ## Todos
 
-[] 当 oxfmt 支持在 monorepo 中为不同的包添加不同的配置之后将其引入。
-[] 当 oxlint `extends` 字段支持指定包产物时，更新所有相关配置。
-[] `change publish` 支持 dry-run 参数。
+- [ ] 当 oxfmt 支持在 monorepo 中为不同的包添加不同的配置之后将其引入。
+- [ ] 当 oxlint `extends` 字段支持指定包产物时，更新所有相关配置。
+- [ ] `change publish` 支持 dry-run 参数。
+- [ ] 待自动识别能力恢复之后，将 `.vscode/settings.json` 中的 `oxc.path.oxfmt` 和 `oxc.path.oxlint` 移除。
+  - see: https://github.com/oxc-project/oxc/blob/main/editors/vscode/client/ConfigService.ts#L172
+  - see: https://github.com/oxc-project/oxc/commit/605dbf12ab64a52948742df8480aa341faa73256
+  - see: https://github.com/oxc-project/oxc/issues/17596
+- [ ] 规范稳定之后，将其固化为工具。
+- [ ] vite does not respect conditions for subpath imports.
+  - see: https://medium.com/@vitaliypotapov/setting-up-subpath-import-aliases-in-a-typescript-project-3ee027b75f1d
+  - see: https://vite.dev/config/shared-options#resolve-conditions