limina 0.0.1 → 0.0.3

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-present, Senao Xi. and docs islands contributors.
+
+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

@@ -0,0 +1,383 @@
+# limina
+
+<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.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.
+
+## Design principles
+
+- 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.
+
+## License
+
+MIT

package/chunks/{dep-jgc7X0zw.js → dep-DzYrmtQJ.js}

@@ -35,39 +35,30 @@ function isPathInsideDirectory(filePath, directoryPath) {
 function createTscCommandTarget(options) {
 	const relativeConfigPath = toRelativePath(options.projectRootDir, options.configPath);
 	return {
-		args: options.executionKind === "build" ? [
+		args: [
 			"-b",
 			relativeConfigPath,
 			"--pretty",
 			"false"
-		] : [
-			"-p",
-			relativeConfigPath,
-			"--noEmit"
 		],
 		command: options.commandOverride ?? "tsc",
-		label: options.executionKind === "build" ? `tsc -b ${relativeConfigPath}` : `tsc: ${relativeConfigPath}`
+		label: `tsc -b ${relativeConfigPath}`
 	};
 }
 function createVueTscCommandTarget(options) {
 	const relativeConfigPath = toRelativePath(options.projectRootDir, options.configPath);
 	return {
-		args: options.executionKind === "build" ? [
+		args: [
 			"-b",
 			relativeConfigPath,
 			"--pretty",
 			"false"
-		] : [
-			"-p",
-			relativeConfigPath,
-			"--noEmit"
 		],
 		command: "vue-tsc",
-		label: options.executionKind === "build" ? `${options.checker.name}: vue-tsc -b ${relativeConfigPath}` : `${options.checker.name}: vue-tsc -p ${relativeConfigPath}`
+		label: `${options.checker.name}: vue-tsc -b ${relativeConfigPath}`
 	};
 }
 function createSvelteCheckCommandTarget(options) {
-	if (options.executionKind === "build") throw new Error(`Checker "${options.checker.name}" uses svelte-check, which does not support checker:build.`);
 	const relativeConfigPath = toRelativePath(options.projectRootDir, options.configPath);
 	return {
 		args: ["--tsconfig", relativeConfigPath],
@@ -79,10 +70,11 @@ const builtinCheckerAdapters = {
 	"svelte-check": {
 		createCommandTarget: createSvelteCheckCommandTarget,
 		defaultExtensions: [".svelte"],
-		graph: false,
-		packageName: "svelte-check",
+		execution: "typecheck",
+		packageNames: ["svelte-check"],
 		preset: "svelte-check",
-		supportedExecutions: ["typecheck"]
+		sourceGraph: false,
+		tier: "source-only"
 	},
 	tsc: {
 		createCommandTarget: createTscCommandTarget,
@@ -96,18 +88,20 @@ const builtinCheckerAdapters = {
 			".d.mts",
 			".json"
 		],
-		graph: true,
-		packageName: "typescript",
+		execution: "build",
+		packageNames: ["typescript"],
 		preset: "tsc",
-		supportedExecutions: ["typecheck", "build"]
+		sourceGraph: true,
+		tier: "first-class"
 	},
 	"vue-tsc": {
 		createCommandTarget: createVueTscCommandTarget,
 		defaultExtensions: [".vue"],
-		graph: false,
-		packageName: "vue-tsc",
+		execution: "build",
+		packageNames: ["vue-tsc", "@vue/compiler-sfc"],
 		preset: "vue-tsc",
-		supportedExecutions: ["typecheck", "build"]
+		sourceGraph: true,
+		tier: "first-class"
 	}
 };
 function isBuiltinCheckerPreset(value) {
@@ -130,15 +124,16 @@ function collectMissingCheckerPeerDependencies(options) {
 	const resolvePackage = options.resolvePackage ?? resolveCheckerPackageFromRoot;
 	const missingCheckersByPackage = /* @__PURE__ */ new Map();
 	for (const checker of options.checkers) {
-		const packageName = getCheckerAdapter(checker.preset)?.packageName;
-		if (!packageName) continue;
-		if (resolvePackage({
-			packageName,
-			projectRootDir: options.projectRootDir
-		})) continue;
-		const checkerNames = missingCheckersByPackage.get(packageName) ?? /* @__PURE__ */ new Set();
-		checkerNames.add(checker.name);
-		missingCheckersByPackage.set(packageName, checkerNames);
+		const packageNames = getCheckerAdapter(checker.preset)?.packageNames ?? [];
+		for (const packageName of packageNames) {
+			if (resolvePackage({
+				packageName,
+				projectRootDir: options.projectRootDir
+			})) continue;
+			const checkerNames = missingCheckersByPackage.get(packageName) ?? /* @__PURE__ */ new Set();
+			checkerNames.add(checker.name);
+			missingCheckersByPackage.set(packageName, checkerNames);
+		}
 	}
 	return [...missingCheckersByPackage.entries()].map(([packageName, checkerNames]) => ({
 		checkerNames: [...checkerNames].sort((left, right) => left.localeCompare(right)),
@@ -157,10 +152,9 @@ function formatMissingCheckerPeerDependencies(missingDependencies) {
 	].join("\n");
 }
 function getCheckerExtensions(checker) {
-	if (checker.extensions) return normalizeExtensions(checker.extensions);
 	const adapter = getCheckerAdapter(checker.preset);
-	if (adapter?.defaultExtensions) return normalizeExtensions(adapter.defaultExtensions);
-	throw new Error(`Checker preset "${checker.preset}" must declare non-empty extensions because it is not a built-in preset.`);
+	if (adapter) return normalizeExtensions(adapter.defaultExtensions);
+	throw new Error(`Checker preset "${checker.preset}" is not supported.`);
 }
 function getResolvedCheckers(config) {
 	const checkers = config.config?.checkers;
@@ -185,11 +179,9 @@ function defineConfig(config) {
 	return config;
 }
 const nonEmptyStringSchema = z.string().refine((value) => value.trim().length > 0);
-const dotPrefixedStringSchema = nonEmptyStringSchema.refine((value) => value.startsWith("."));
 const checkerObjectSchema = z.looseObject({});
 const checkerConfigShapeSchema = z.looseObject({
 	entry: nonEmptyStringSchema,
-	extensions: z.array(dotPrefixedStringSchema).nonempty().optional(),
 	preset: nonEmptyStringSchema
 });
 const liminaConfigShapeSchema = z.looseObject({ config: z.looseObject({ checkers: z.record(z.string(), checkerConfigShapeSchema).optional() }).optional() });
@@ -245,15 +237,6 @@ function formatLiminaConfigShapeIssue(value, issue) {
 			`  value: ${formatUnknownValue(getValueAtPath(value, pathSegments))}`,
 			"  reason: checker entry must be a non-empty string path."
 		].join("\n");
-		if (pathSegments[3] === "extensions") {
-			const extensionsPath = pathSegments.slice(0, 4);
-			return [
-				"Invalid Limina checker config:",
-				`  field: ${checkerField}.extensions`,
-				`  value: ${formatUnknownValue(getValueAtPath(value, extensionsPath))}`,
-				"  reason: checker extensions must be a non-empty array of dot-prefixed strings."
-			].join("\n");
-		}
 	}
 	return [
 		"Invalid Limina config:",
@@ -279,11 +262,11 @@ function collectCheckerConfigProblems(config) {
 		if (!checkerObjectResult.success) continue;
 		const checkerRecord = checkerObjectResult.data;
 		const preset = checkerRecord.preset;
-		if (checkerRecord.extensions === void 0 && typeof preset === "string" && !isBuiltinCheckerPreset(preset)) problems.push([
+		if (Object.hasOwn(checkerRecord, "extensions")) problems.push([
 			"Invalid Limina checker config:",
 			`  field: ${field}.extensions`,
-			"  value: undefined",
-			"  reason: extensions may only be omitted for built-in presets."
+			`  value: ${formatUnknownValue(checkerRecord.extensions)}`,
+			"  reason: checker extensions are fixed by built-in presets and cannot be configured."
 		].join("\n"));
 		if (Object.hasOwn(checkerRecord, "routes")) problems.push([
 			"Invalid Limina checker config:",
@@ -374,4 +357,4 @@ async function loadConfig(options = {}) {
 }
 
 //#endregion
-export { validateLiminaConfig as a, getCheckerAdapter as c, normalizeSlashes as d, normalizeWorkspacePath as f, toRelativePath as h, loadConfig as i, isPathInsideDirectory as l, toPosixPath as m, getActiveCheckerExtensions as n, collectMissingCheckerPeerDependencies as o, toAbsolutePath as p, getActiveCheckers as r, formatMissingCheckerPeerDependencies as s, defineConfig as t, normalizeAbsolutePath as u };
+export { validateLiminaConfig as a, getCheckerAdapter as c, normalizeAbsolutePath as d, normalizeSlashes as f, toRelativePath as g, toPosixPath as h, loadConfig as i, normalizeExtensions as l, toAbsolutePath as m, getActiveCheckerExtensions as n, collectMissingCheckerPeerDependencies as o, normalizeWorkspacePath as p, getActiveCheckers as r, formatMissingCheckerPeerDependencies as s, defineConfig as t, isPathInsideDirectory as u };