From 0fd35bfdab600a4496826e136b13359dacaa8588 Mon Sep 17 00:00:00 2001 From: hypercross Date: Wed, 15 Apr 2026 10:56:05 +0800 Subject: [PATCH] refactor: reorganize exports into main (full browser), runner (minimal), and plugins; remove node export --- AGENTS.md | 40 ++++++++++++++++++++++++++++++ package.json | 8 +++--- src/core.ts | 63 +++++++++++++++++++++++++++++++++++++++-------- src/index.ts | 67 +++++++++++++++++++++++++++++++++++++++++--------- src/node.ts | 23 ----------------- src/runner.ts | 30 ++++++++++++++++++++++ tsup.config.ts | 2 +- 7 files changed, 183 insertions(+), 50 deletions(-) create mode 100644 AGENTS.md delete mode 100644 src/node.ts create mode 100644 src/runner.ts diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..7f0933f --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,40 @@ +# AGENTS.md - Yarn Spinner Loader + +## Commands +- `npm run build` — Build all entry points (tsup, ESM + CJS) +- `npm run dev` — Watch mode +- `npm run test` — Vitest watch mode +- `npm run test:run` — Run tests once +- `npm run typecheck` — `tsc --noEmit` + +## Architecture +- **`src/index.ts`** — Main entry point. Full browser package: parse + compile + run + all types. No Node.js deps. +- **`src/core.ts`** — Mirror of index.ts. Not in package.json exports. +- **`src/runner.ts`** — Minimal runtime export: `YarnRunner` + runtime/IR types only. No parser, no compiler. +- **`src/loader/`** — Filesystem loader: parses `.yarnproject` files, validates against JSON schema (ajv), resolves globs (fast-glob), compiles `.yarn` files. +- **`src/plugins/`** — Build tool plugins: esbuild, rollup, vite, webpack. Each is a separate tsup entry point outputting to `dist/plugins/`. +- **`src/yarn-spinner/`** — Embedded Yarn Spinner implementation: `parse/`, `compile/`, `runtime/`, `markup/`, `model/`. +- **`src/runner/`** — Empty directory. Ignore. + +## Package exports +- `yarn-spinner-loader` → `dist/index.js` (full browser package) +- `yarn-spinner-loader/runner` → `dist/runner.js` (runtime only) +- `yarn-spinner-loader/esbuild` → `dist/plugins/esbuild.js` +- `yarn-spinner-loader/rollup` → `dist/plugins/rollup.js` +- `yarn-spinner-loader/vite` → `dist/plugins/vite.js` +- `yarn-spinner-loader/webpack` → `dist/plugins/webpack.js` + +## Key conventions +- `src/index.ts` and `src/core.ts` must NOT import from `src/loader/` or any Node.js-specific modules. +- `src/loader/` is the only code that uses `fs`, `path`, `fast-glob`. +- TypeScript: strict mode, ES2022, `moduleResolution: "bundler"`. +- Tests live in `tests/`, not `src/`. Pattern: `tests/**/*.test.ts`. + +## Build notes +- tsup config has 6 entry points. Main + runner output to `dist/`, plugins output to `dist/plugins/`. +- `npm run build` cleans `dist/` automatically. +- `core.ts` is NOT exported in package.json — it exists for internal consistency only. +- This package is intended as a `devDependency` alongside bundlers. Dependencies (`ajv`, `fast-glob`) are needed at build time. + +## Security +- `.npmrc` contains an npm auth token. Never commit or expose this. diff --git a/package.json b/package.json index 7fe8cf5..b9b3200 100644 --- a/package.json +++ b/package.json @@ -12,10 +12,10 @@ "import": "./dist/index.js", "require": "./dist/index.cjs" }, - "./node": { - "types": "./dist/node.d.ts", - "import": "./dist/node.js", - "require": "./dist/node.cjs" + "./runner": { + "types": "./dist/runner.d.ts", + "import": "./dist/runner.js", + "require": "./dist/runner.cjs" }, "./esbuild": { "types": "./dist/plugins/esbuild.d.ts", diff --git a/src/core.ts b/src/core.ts index 5042ee7..39ce42b 100644 --- a/src/core.ts +++ b/src/core.ts @@ -5,21 +5,64 @@ * This module does NOT depend on Node.js modules. */ -// Re-export yarn-spinner parser -export { parseYarn } from './yarn-spinner/parse/parser'; -export { compile } from './yarn-spinner/compile/compiler'; -export { YarnRunner } from './yarn-spinner/runtime/runner'; +// Parser +export { parseYarn, ParseError } from './yarn-spinner/parse/parser'; -// Re-export types +// Compiler +export { compile, type CompileOptions } from './yarn-spinner/compile/compiler'; + +// Runner +export { YarnRunner, type RunnerOptions } from './yarn-spinner/runtime/runner'; + +// AST types +export type { + Position, + NodeHeaderMap, + YarnDocument, + EnumDefinition, + YarnNode, + Statement, + Line, + Command, + Jump, + Detour, + Return, + OptionGroup, + Option, + IfBlock, + OnceBlock, + EnumBlock, +} from './yarn-spinner/model/ast'; + +// IR types export type { - LoadOptions, - LoadResult, IRProgram, - YarnProject, - SchemaValidationError, - RunnerOptions, + IRNode, + IRNodeGroup, + IRInstruction, +} from './yarn-spinner/compile/ir'; + +// Runtime types +export type { TextResult, OptionsResult, CommandResult, RuntimeResult, +} from './yarn-spinner/runtime/results'; + +// Markup types +export type { + MarkupValue, + MarkupWrapperType, + MarkupWrapper, + MarkupSegment, + MarkupParseResult, +} from './yarn-spinner/markup/types'; + +// Loader types +export type { + LoadOptions, + LoadResult, + YarnProject, + SchemaValidationError, } from './types'; diff --git a/src/index.ts b/src/index.ts index b5ed58f..ab44625 100644 --- a/src/index.ts +++ b/src/index.ts @@ -1,26 +1,69 @@ /** * Yarn Spinner Loader - Main Entry Point * - * Pure API for working with Yarn Spinner documents. + * Full browser-compatible package: parse, compile, and run Yarn Spinner documents. * This module does NOT depend on Node.js modules. - * For filesystem operations, use the 'yarn-spinner-loader/node' entry point. + * For filesystem loading, use the 'yarn-spinner-loader/node' entry point. */ -// Re-export yarn-spinner parser and runtime -export { parseYarn } from './yarn-spinner/parse/parser'; -export { compile } from './yarn-spinner/compile/compiler'; -export { YarnRunner } from './yarn-spinner/runtime/runner'; +// Parser +export { parseYarn, ParseError } from './yarn-spinner/parse/parser'; -// Re-export types +// Compiler +export { compile, type CompileOptions } from './yarn-spinner/compile/compiler'; + +// Runner +export { YarnRunner, type RunnerOptions } from './yarn-spinner/runtime/runner'; + +// AST types +export type { + Position, + NodeHeaderMap, + YarnDocument, + EnumDefinition, + YarnNode, + Statement, + Line, + Command, + Jump, + Detour, + Return, + OptionGroup, + Option, + IfBlock, + OnceBlock, + EnumBlock, +} from './yarn-spinner/model/ast'; + +// IR types export type { - LoadOptions, - LoadResult, IRProgram, - YarnProject, - SchemaValidationError, - RunnerOptions, + IRNode, + IRNodeGroup, + IRInstruction, +} from './yarn-spinner/compile/ir'; + +// Runtime types +export type { TextResult, OptionsResult, CommandResult, RuntimeResult, +} from './yarn-spinner/runtime/results'; + +// Markup types +export type { + MarkupValue, + MarkupWrapperType, + MarkupWrapper, + MarkupSegment, + MarkupParseResult, +} from './yarn-spinner/markup/types'; + +// Loader types +export type { + LoadOptions, + LoadResult, + YarnProject, + SchemaValidationError, } from './types'; diff --git a/src/node.ts b/src/node.ts deleted file mode 100644 index 2c8ec2d..0000000 --- a/src/node.ts +++ /dev/null @@ -1,23 +0,0 @@ -/** - * Yarn Spinner Loader - Node.js API - * - * Functions that depend on Node.js modules (fs, path, fast-glob). - * Use this entry point when you need to load .yarnproject files from the filesystem. - */ - -export { - loadYarnProject, - loadYarnProjectSync, - type LoadOptions, - type LoadResult, - LoadError, - ValidationError as LoaderValidationError, -} from './loader/index'; - -export { - validateYarnProject, - isYarnProject, - type SchemaValidationError, -} from './loader/validator'; - -export type { YarnProject } from './loader/types'; diff --git a/src/runner.ts b/src/runner.ts new file mode 100644 index 0000000..3875a90 --- /dev/null +++ b/src/runner.ts @@ -0,0 +1,30 @@ +/** + * Yarn Spinner Loader - Runner API + * + * Minimal runtime-only export for executing pre-compiled IRPrograms. + * No parser, no compiler — just the runner and its types. + */ + +export { YarnRunner, type RunnerOptions } from './yarn-spinner/runtime/runner'; + +export type { + TextResult, + OptionsResult, + CommandResult, + RuntimeResult, +} from './yarn-spinner/runtime/results'; + +export type { + IRProgram, + IRNode, + IRNodeGroup, + IRInstruction, +} from './yarn-spinner/compile/ir'; + +export type { + MarkupParseResult, + MarkupSegment, + MarkupWrapper, + MarkupWrapperType, + MarkupValue, +} from './yarn-spinner/markup/types'; diff --git a/tsup.config.ts b/tsup.config.ts index 3b88c38..df1f6a4 100644 --- a/tsup.config.ts +++ b/tsup.config.ts @@ -10,7 +10,7 @@ export default defineConfig([ outDir: 'dist', }, { - entry: ['src/node.ts'], + entry: ['src/runner.ts'], format: ['esm', 'cjs'], dts: true, sourcemap: true,