limina 0.0.3 → 0.0.5

package/LICENSE.md

@@ -1,3 +1,8 @@
+<!-- markdownlint-disable MD003 MD009 MD025 MD035 MD026 -->
+# limina license
+
+limina is released under the MIT license:
+
 MIT License
 
 Copyright (c) 2025-present, Senao Xi. and docs islands contributors.
@@ -19,3 +24,9 @@ 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.
+
+# Licenses of bundled dependencies
+
+The published limina artifact additionally contains code with the following licenses:
+
+# Bundled dependencies:

package/README.md

@@ -1,383 +1,30 @@
 # limina
 
+<p align="center">
+  <a href="https://docs.senao.me/docs-islands/limina" target="_blank" rel="noopener noreferrer">
+    <img width="180" src="https://docs.senao.me/docs-islands/limina/logo.svg" alt="limina logo">
+  </a>
+</p>
 <p align="center">
   <a href="https://npmjs.com/package/limina"><img src="https://img.shields.io/npm/v/limina.svg" alt="npm package"></a>
   <a href="https://nodejs.org/en/about/previous-releases"><img src="https://img.shields.io/node/v/limina.svg" alt="node compatibility"></a>
   <a href="https://github.com/XiSenao/docs-islands/actions/workflows/ci.yml"><img src="https://github.com/XiSenao/docs-islands/actions/workflows/ci.yml/badge.svg?branch=main" alt="build status"></a>
-  <a href="https://github.com/XiSenao/docs-islands/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/limina.svg" alt="license"></a>
+  <a href="https://github.com/XiSenao/docs-islands/blob/main/packages/limina/LICENSE.md"><img src="https://img.shields.io/npm/l/limina.svg" alt="license"></a>
 </p>
 
 English | [简体中文](./README.zh-CN.md)
 
-`limina` is a configurable governance CLI for TypeScript monorepos. It keeps TypeScript project references, source typechecks, compatibility paths, package export policy, and publish-time package checks in one explicit `limina.config.mjs` file.
-
-Limina is not a bundler and does not replace `tsc`, `vue-tsc`, tests, or release tooling. It coordinates them and verifies that the architecture they depend on stays consistent.
-
-## Why Limina?
-
-Large TypeScript workspaces often need more than `tsc --noEmit`:
-
-- project references must match real cross-project imports;
-- production graph projects should not depend on tools or tests;
-- browser/runtime output should not import Node builtins;
-- `workspace:*` dependencies should resolve to source during graph checks;
-- generated compatibility `paths` should not silently drift;
-- built package outputs need consumer-facing checks before release;
-- Vue, docs, playground, and smoke checks may need checker-specific tooling outside native `tsc -b`.
-
-Limina makes these rules reviewable, runnable, and suitable for CI.
-
-## Features
-
-- **Project graph validation**: checks reachable TypeScript declaration leaves, references, graph-owned imports, package boundaries, and label-based deny rules.
-- **Typecheck coverage proof**: verifies that reachable declaration leaves match strict local typecheck companions and that source files are covered by checker entries or allowlist entries.
-- **Compatibility path generation**: writes opt-in `tsconfig.dts.paths.generated.json` files for `workspace:*` dependencies whose package exports still point at build artifacts.
-- **Checker target runner**: runs configured TypeScript and UI-framework checker entries in `typecheck` or `build` execution mode.
-- **Published package checks**: validates built package outputs with `publint`, Are The Types Wrong, and a runtime import boundary audit.
-- **Composable pipelines**: combines built-in checks and shell commands into named workflows such as `typecheck`, `package`, and `publish`.
-- **Typed configuration**: ships `defineConfig(...)` for editor hints and typed user configs.
-
-## Requirements
-
-- Node.js `^20.19.0 || >=22.12.0`
-- pnpm workspace with `pnpm-workspace.yaml`
-- TypeScript installed in the consuming repository
-- ESM-compatible `limina.config.mjs`
-
-## Installation
-
-```sh
-pnpm add -D limina typescript
-```
-
-## Quick start
-
-Create `limina.config.mjs` at the workspace root:
-
-```js
-import { defineConfig } from 'limina';
-
-export default defineConfig({
-  config: {
-    checkers: {
-      typescript: {
-        preset: 'tsc',
-        entry: 'tsconfig.build.json',
-      },
-      vue: {
-        preset: 'vue-tsc',
-        entry: 'tsconfig.vue.build.json',
-      },
-    },
-  },
-
-  graph: {
-    rules: {
-      'runtime-client': {
-        deny: {
-          refs: [
-            {
-              path: 'packages/app/src/node/tsconfig.lib.dts.json',
-              reason: 'client runtime must not depend on the Node runtime',
-            },
-          ],
-        },
-      },
-    },
-  },
-
-  proof: {
-    allowlist: [
-      {
-        file: 'src/generated/runtime.d.ts',
-        reason: 'Generated declaration stub covered by the runtime build process.',
-      },
-    ],
-  },
-
-  packageChecks: {
-    targets: [
-      {
-        name: '@acme/core',
-        outDir: 'packages/core/dist',
-      },
-    ],
-  },
-
-  pipelines: {
-    package: ['package:check'],
-    publish: ['graph:check', 'proof:check', 'package:check'],
-  },
-});
-```
-
-Add scripts:
-
-```json
-{
-  "scripts": {
-    "typecheck": "limina check",
-    "lint:package": "limina package check",
-    "prepublishOnly": "limina check publish"
-  }
-}
-```
-
-Run checks:
-
-```sh
-pnpm typecheck
-pnpm exec limina graph check
-pnpm exec limina package check --package @acme/core
-```
-
-## Concepts
-
-### Checker entry
-
-Each checker has one required `config.checkers.<name>.entry`, usually a `tsconfig*.build.json` graph aggregator. Built-in first-class presets (`tsc` and `vue-tsc`) participate in graph, source, proof, and build checks. Source-only presets such as `svelte-check` prove source coverage and run direct checker execution through `limina checker typecheck`.
-
-### Declaration leaf and local companion
-
-Declaration leaves should have strict local companions. For example, `tsconfig.lib.dts.json` pairs with `tsconfig.lib.json`, and `tsconfig.dts.json` pairs with `tsconfig.json`.
-
-The default `tsconfig.json` is the IDE/typecheck entry for its directory. A single-environment directory should use it as the local leaf; a multi-environment directory should make it a pure aggregator with `files: []` and `references`.
-
-### Source dependencies and artifact dependencies
-
-A dependency declared as `workspace:*` is considered a source dependency. It should be represented by project references and source-facing package exports.
-
-A dependency declared as `link:`, `file:`, `catalog:`, or normal semver is treated as an artifact dependency. It should not be modeled as a project reference unless it is intentionally consumed as source.
-
-### Package checks
-
-Source graph checks do not prove that an installed package works for consumers. `limina package check` inspects built package outputs under `packageChecks.targets[].outDir` and checks the actual package manifest, exports, type resolution, and runtime imports. Publishable outputs whose `package.json` does not set `private: true` must also include root `README.md` and `LICENSE.md` files.
-
-## CLI
-
-```sh
-limina [--config limina.config.mjs] [--mode mode] <command>
-```
-
-| Command                                         | Description                                                                           |
-| ----------------------------------------------- | ------------------------------------------------------------------------------------- |
-| `limina check`                                  | Run the built-in default check pipeline.                                              |
-| `limina check <pipeline>`                       | Run a named user pipeline from `pipelines`.                                           |
-| `limina graph check`                            | Validate project references and architecture import rules.                            |
-| `limina proof check`                            | Prove declaration configs, local typecheck configs, and source coverage stay aligned. |
-| `limina paths generate`                         | Generate compatibility source `paths` configs for artifact-facing workspace exports.  |
-| `limina paths apply`                            | Compatibility alias for `paths generate`.                                             |
-| `limina paths check`                            | Fail when generated path files are stale.                                             |
-| `limina checker build`                          | Run build execution for checker entries that support it.                              |
-| `limina checker typecheck`                      | Run source-only checker entries such as `svelte-check`.                               |
-| `limina package check`                          | Run configured package output checks.                                                 |
-| `limina package check --package <name>`         | Check one configured package target.                                                  |
-| `limina package check --tool <tool>`            | Run only `publint`, `attw`, or `boundary`.                                            |
-| `limina package check --attw-profile <profile>` | Override the ATTW profile: `strict`, `node16`, or `esm-only`.                         |
-
-## Configuration reference
-
-### `config`
-
-```js
-config: {
-  checkers: {
-    typescript: {
-      preset: 'tsc',
-      entry: 'tsconfig.build.json',
-    },
-    vue: {
-      preset: 'vue-tsc',
-      entry: 'tsconfig.vue.build.json',
-    },
-  },
-  source: {
-    exclude: ['node_modules', 'dist', '.tsbuild'],
-  },
-}
-```
-
-`config.checkers` defines checker entries. Every configured checker must declare a non-empty `entry` and use a built-in preset. Checker `extensions` are fixed by Limina and cannot be configured; if `source.include` is omitted, Limina derives the source boundary from configured checker extensions, then applies `source.exclude`.
-
-### `graph`
-
-```js
-graph: {
-  rules: {
-    'runtime-client': {
-      deny: {
-        refs: [
-          {
-            path: 'packages/app/src/node/tsconfig.lib.dts.json',
-            reason: 'client runtime must stay independent from Node runtime',
-          },
-        ],
-        deps: [
-          {
-            name: '@acme/internal-node',
-            reason: 'client runtime must not consume Node-only packages',
-          },
-          {
-            name: 'node:*',
-            reason: 'client runtime must not import Node builtins',
-          },
-          {
-            name: '#server/*',
-            reason: 'client runtime must not use server-only package imports',
-          },
-        ],
-      },
-    },
-  },
-}
-```
-
-A declaration leaf opts into a rule by adding a `limina` label:
-
-```jsonc
-{
-  "limina": "runtime-client",
-  "extends": ["./tsconfig.json", "../../tsconfig.dts.base.json"],
-  "references": [],
-}
-```
-
-### `paths`
-
-```js
-paths: {
-  generatedFileName: 'tsconfig.dts.paths.generated.json',
-  conditionPriority: ['source', 'development', 'types'],
-  artifactDirectories: ['dist', 'build', 'lib', 'esm', 'cjs', 'out'],
-}
-```
-
-Use generated paths only when a workspace package must keep artifact-facing exports while still being consumed as a graph-owned source dependency.
-
-### `proof`
-
-```js
-proof: {
-  allowlist: [
-    {
-      file: 'src/generated/runtime.d.ts',
-      reason: 'Generated file validated by the build pipeline.',
-    },
-  ],
-}
-```
-
-Checker entries cover files validated by TypeScript or framework-aware tools. Allowlist entries are the final fallback after all configured checker entries fail to cover a source file; they should be rare and must include a reason.
-
-### `packageChecks`
-
-```js
-packageChecks: {
-  targets: [
-    {
-      name: '@acme/core',
-      outDir: 'packages/core/dist',
-      checks: ['publint', 'attw', 'boundary'],
-      publint: { strict: true },
-      attw: { profile: 'esm-only' },
-      boundary: {
-        environment: (file) => file.startsWith('node/') ? 'node' : 'browser',
-        ignoredExternalPackages: ['@acme/runtime-shim'],
-      },
-    },
-  ],
-}
-```
-
-`outDir` must point at the built package directory that contains the publish-ready `package.json`. If that manifest does not set `private: true`, the same directory must also contain `README.md` and `LICENSE.md`.
-
-### `pipelines`
-
-```js
-pipelines: {
-  package: [
-    { type: 'command', command: 'pnpm', args: ['build'] },
-    'package:check',
-  ],
-}
-```
-
-`limina check` runs the built-in default pipeline: `graph:check`, `source:check`, `proof:check`, `checker:build`, and `checker:typecheck`. `limina check <pipeline>` only runs user pipelines from `limina.config.mjs#pipelines`; if the name is missing, Limina reports the missing pipeline and asks you to define it there.
-
-String steps can be built-in task names or simple commands. Use object command steps when arguments, `cwd`, or `env` need to be explicit.
-
-## CI example
-
-```yaml
-name: Typecheck
-
-on:
-  pull_request:
-  push:
-    branches: [main]
-
-jobs:
-  typecheck:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: pnpm/action-setup@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 20.19.0
-          cache: pnpm
-      - run: pnpm install --frozen-lockfile
-      - run: pnpm exec limina check
-```
-
-## Programmatic API
-
-```ts
-import { defineConfig, loadConfig } from 'limina';
-
-export default defineConfig({
-  pipelines: {
-    typecheck: ['graph:check'],
-  },
-});
-
-const config = await loadConfig();
-```
-
-Most users only need `defineConfig(...)`. `loadConfig(...)` is available for custom wrappers and tests.
-
-## Troubleshooting
-
-### `Unable to find limina config`
-
-Run the command from inside the workspace, or pass `--config ./limina.config.mjs`.
-
-### `no pnpm-workspace.yaml was found`
-
-Limina infers the workspace root from `pnpm-workspace.yaml`. Place the config inside the workspace or pass a config path located under the workspace root.
-
-### `packageChecks.targets[x].outDir` is invalid
-
-Set `outDir` to the built package directory, not the source package directory, unless that directory is itself the publish-ready package output.
-
-### Generated paths are stale
-
-Run:
-
-```sh
-pnpm exec limina paths generate
-```
-
-Then add the generated file to the first position of the listed `extends` arrays and commit the generated file if your repository policy requires reproducible `tsc -b` without a pre-generation step.
+> Architecture governance CLI for TypeScript monorepos
 
-## Design principles
+- Keep source dependency graphs aligned with type build graphs
+- Guard package, runtime, and workspace boundaries
+- Cover TypeScript and framework-specific checkers
+- Manage compatibility paths for workspace source dependencies
+- Validate package outputs before release
+- Compose checks for local development, CI, and publishing
 
-- Explicit policy is better than hidden presets.
-- Source graph checks and package artifact checks validate different surfaces.
-- Build graph configs should be strict, small, and directly referenced.
-- Generated compatibility paths should be transitional, not the default architecture.
-- Limina should fail with actionable messages instead of silently accepting graph drift.
+Limina helps teams turn drifting TypeScript monorepo constraints into explicit, reviewable, runnable checks. It keeps source relationships, type coverage, build coordination, package metadata, and publishable outputs aligned across everyday development, code review, and pre-release workflows.
 
-## License
+Limina is not a bundler, test runner, or release tool, and it does not replace TypeScript or framework checkers. It runs those existing tools and verifies that the monorepo structure they rely on is still trustworthy.
 
-MIT
+[Read the Docs to Learn More](https://docs.senao.me/docs-islands/limina/)

package/README.zh-CN.md

@@ -0,0 +1,30 @@
+# limina
+
+<p align="center">
+  <a href="https://docs.senao.me/docs-islands/limina/zh" target="_blank" rel="noopener noreferrer">
+    <img width="180" src="https://docs.senao.me/docs-islands/limina/logo.svg" alt="limina logo">
+  </a>
+</p>
+<p align="center">
+  <a href="https://npmjs.com/package/limina"><img src="https://img.shields.io/npm/v/limina.svg" alt="npm package"></a>
+  <a href="https://nodejs.org/en/about/previous-releases"><img src="https://img.shields.io/node/v/limina.svg" alt="node compatibility"></a>
+  <a href="https://github.com/XiSenao/docs-islands/actions/workflows/ci.yml"><img src="https://github.com/XiSenao/docs-islands/actions/workflows/ci.yml/badge.svg?branch=main" alt="build status"></a>
+  <a href="https://github.com/XiSenao/docs-islands/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/limina.svg" alt="license"></a>
+</p>
+
+[English](./README.md) | 简体中文
+
+> TypeScript monorepo 的架构治理 CLI
+
+- 保持源码依赖图与类型构建图一致
+- 守住 package、运行时与工程边界
+- 覆盖 TypeScript 与框架专属 checker
+- 管理 workspace 源码依赖的兼容路径
+- 验证发布前 package 产物
+- 组合适合本地、CI 与发布流程的检查
+
+Limina 帮助团队把 TypeScript monorepo 中容易漂移的工程约束变成显式、可审查、可运行的检查。它让源码关系、类型覆盖、构建协作、package metadata 和发布产物保持一致，适合放进日常开发、代码审查和发布前流程。
+
+Limina 不是 bundler、测试框架或发布工具，也不会替代 TypeScript / framework checker。它调用这些已有工具，并验证它们依赖的 monorepo 结构是否仍然可靠。
+
+[阅读文档了解更多](https://docs.senao.me/docs-islands/limina/zh/)

package/bin/limina.js

@@ -1,25 +1,36 @@
 #!/usr/bin/env node
-import "../chunks/dep-lkQg1P9Q.js";
-import { existsSync } from "node:fs";
-import path from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
-import { spawnSync } from "node:child_process";
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import path from 'pathe';
+
+const packageDir = path.resolve(fileURLToPath(new URL('..', import.meta.url)));
+const distCliPath = path.join(packageDir, 'cli.js');
+const sourceCliPath = path.join(packageDir, 'src/cli.ts');
+const tsxBinName = process.platform === 'win32' ? 'tsx.cmd' : 'tsx';
+const tsxCliPath =
+  [
+    path.join(packageDir, 'node_modules/.bin', tsxBinName),
+    path.join(packageDir, '../../node_modules/.bin', tsxBinName),
+  ].find((candidate) => existsSync(candidate)) ?? 'tsx';
 
-//#region bin/limina.js
-const packageDir = path.resolve(fileURLToPath(new URL("..", import.meta.url)));
-const distCliPath = path.join(packageDir, "cli.js");
-const sourceCliPath = path.join(packageDir, "src/cli.ts");
-const tsxBinName = process.platform === "win32" ? "tsx.cmd" : "tsx";
-const tsxCliPath = [path.join(packageDir, "node_modules/.bin", tsxBinName), path.join(packageDir, "../../node_modules/.bin", tsxBinName)].find((candidate) => existsSync(candidate)) ?? "tsx";
 if (existsSync(sourceCliPath)) {
-	const result = spawnSync(tsxCliPath, [sourceCliPath, ...process.argv.slice(2)], {
-		stdio: "inherit",
-		shell: process.platform === "win32"
-	});
-	if (result.error) throw result.error;
-	process.exit(result.status ?? 1);
-} else if (existsSync(distCliPath)) await import(pathToFileURL(distCliPath).href);
-else throw new Error(`Unable to find limina CLI entry. Expected ${distCliPath}.`);
+  const result = spawnSync(
+    tsxCliPath,
+    [sourceCliPath, ...process.argv.slice(2)],
+    {
+      stdio: 'inherit',
+      shell: process.platform === 'win32',
+    },
+  );
+
+  if (result.error) {
+    throw result.error;
+  }
 
-//#endregion
-export {  };
+  process.exit(result.status ?? 1);
+} else if (existsSync(distCliPath)) {
+  await import(pathToFileURL(distCliPath).href);
+} else {
+  throw new Error(`Unable to find limina CLI entry. Expected ${distCliPath}.`);
+}