docs: update

Author: 9romise

AGENTS.md

@@ -1,22 +1,31 @@
 # AGENTS.md
 
 ## Commands (pnpm, run from root)
-- `pnpm dev` / `pnpm build` — dev/build all packages
-- `pnpm test` — run all tests (vitest, workspace projects under `extensions/*`)
-- `pnpm test -- --run tests/path/to/file.test.ts` — run a single test file
-- `pnpm lint:fix` — ESLint auto-fix (`@vida0905/eslint-config`)
-- `pnpm typecheck` — type-check with `tsgo -b --noEmit`
+- `pnpm dev` — start dev server (all packages)
+- `pnpm build` — production build (all packages)
+- `pnpm lint:fix` — auto-fix lint issues (ESLint via `@vida0905/eslint-config`)
+- `pnpm typecheck` — type check with `tsgo`
+- `pnpm test` — run all tests (Vitest)
+- `pnpm vitest run path/to/file.test.ts` — run a single test file
 
 ## Architecture
-- **Monorepo** (pnpm workspaces). Main extension: `extensions/vscode/` (VS Code extension using `reactive-vscode`). Shared code: `shared/` (constants, types, meta). Internal packages: `packages/language-core/`, `packages/language-service/`, `packages/language-server/` (bundled into the extension via tsdown, not standalone workspace packages).
-- Extension entry: `extensions/vscode/src/index.ts`. Key dirs: `api/` (npm registry), `commands/`, `composables/`, `core/`, `providers/`, `utils/`.
-- Tests live in `extensions/vscode/tests/` and `packages/*/tests/` using vitest + `jest-mock-vscode` + `msw` for HTTP mocking.
+Monorepo (pnpm workspaces) for VS Code extension around [npmx.dev](https://npmx.dev). Uses `reactive-vscode` for reactivity, `tsdown` for bundling, Volar for language server. Tests are colocated (`.test.ts` next to source).
+
+### Workspaces
+- `extensions/vscode/` — thin client (language client, commands, providers). Commands in `src/commands/` must NOT import `reactive-vscode`; use `vscode` API directly.
+- `packages/shared` — constants, types, LSP protocol definitions
+- `packages/language-core` — extractors, API clients, workspace context
+- `packages/language-service` — Volar plugins (hover, completion, diagnostics, document-link, catalog)
+- `packages/language-server` — Volar server
+
+### Key abstractions
+- **Extractor** — parses package files into dependency AST data
+- **WorkspaceContext** — per-folder state (package manager, catalogs, deps)
+- **Plugin** — Volar language service plugin consuming resolved deps
 
 ## Code Style
-- **TypeScript strict mode**, ESNext target, Bundler resolution, ESM (`"type": "module"`).
-- Use `interface` over `type`. Never use `any`. Avoid `as` casts—validate instead.
-- No `node:` built-in imports in `src/` (browser-compatible). No `semver` default import—use subpath.
-- No `reactive-vscode` composables in `src/commands/`—use `vscode` API directly.
-- Minimal comments—only when truly necessary (prefix hacks with `// HACK:`).
-- Conventional Commits: `type(scope): description` (lowercase subject).
-- Bundler: tsdown. Package manager: pnpm (deps managed via catalogs in `pnpm-workspace.yaml`).
+- ESM, strict TypeScript — never use `any` or type-cast with `as`; validate rather than assert
+- Imports: type imports first, then `#` aliases (`#state`, `#utils/`, `#core/`), then external packages, then relative — no blank lines between groups
+- No `node:` built-in imports in `src/` (browser-compat constraint); use `semver` subpath imports (not bare `semver`)
+- Naming: files/folders `kebab-case`, tests `*.test.ts`, functions `camelCase`, constants `SCREAMING_SNAKE_CASE`, types `PascalCase`
+- Commits: [Conventional Commits](https://www.conventionalcommits.org/) — `type(scope): description` (lowercase subject)

CONTRIBUTING.md

@@ -82,46 +82,54 @@ This project is organized as a monorepo using pnpm workspaces:
 
 ```
 extensions/
-└── vscode/             # VS Code extension
-    ├── src/            # Extension source code
-    │   ├── api/        # API clients (package, replacement, vulnerability)
-    │   ├── commands/   # Command handlers (vscode API only, no reactive-vscode)
-    │   ├── composables/ # Composables (reactive-vscode hooks)
-    │   ├── core/       # Core logic
-    │   │   ├── extractors/ # Extractors (JSON, YAML)
-    │   │   └── workspace.ts # Workspace context resolution
-    │   ├── providers/  # Providers
-    │   │   ├── code-actions/ # Code action providers (quick fixes)
-    │   │   ├── completion-item/ # Completion providers (version autocomplete)
-    │   │   ├── diagnostics/ # Diagnostic providers
-    │   │   ├── document-link/ # Document link providers (package links)
-    │   │   └── hover/  # Hover providers
-    │   ├── types/      # TypeScript types
-    │   ├── utils/      # Utility functions
-    │   ├── index.ts    # Extension entry point
-    │   └── state.ts    # State management
-    ├── package.json
-    └── tsdown.config.ts
-shared/                 # Shared code across packages
-├── constants.ts
-├── meta.ts             # Auto-generated extension metadata
-└── types.ts
-playground/             # Playground for testing
-res/                    # Assets (e.g. marketplace icon)
-tests/                  # Tests
-├── __setup__/          # Test setup and utilities
-├── code-actions/       # Code action tests
-├── diagnostics/        # Diagnostic tests
-├── fixtures/           # Test fixtures (workspace scenarios)
-└── utils/              # Utility tests
+└── vscode/                  # VS Code extension (thin client)
+    ├── src/
+    │   ├── commands/        # Command handlers (vscode API only, no reactive-vscode)
+    │   ├── providers/       # VS Code provider registrations
+    │   ├── utils/           # Extension-specific utilities
+    │   ├── client.ts        # Language client setup
+    │   ├── index.ts         # Extension entry point
+    │   ├── request.ts       # Request handling
+    │   └── state.ts         # State management
+    └── tests/
+packages/
+├── shared/                  # Shared code across packages
+│   └── src/
+│       ├── commands.ts      # Command identifiers
+│       ├── constants.ts     # Shared constants
+│       ├── meta.ts          # Auto-generated extension metadata
+│       ├── protocol.ts      # LSP protocol definitions
+│       └── types.ts         # Shared types
+├── language-core/           # Core logic (extractors, API clients, workspace)
+│   └── src/
+│       ├── api/             # API clients (package, replacement, vulnerability)
+│       ├── extractors/      # File parsers (JSON, YAML)
+│       ├── utils/           # Core utilities (with colocated tests)
+│       ├── workspace.ts     # Workspace context resolution
+│       └── types.ts         # Core types
+├── language-service/        # Language service plugins (Volar)
+│   └── src/
+│       ├── plugins/         # Service plugins
+│       │   ├── diagnostics/ # Diagnostic rules (with colocated tests)
+│       │   ├── catalog.ts   # Catalog resolution
+│       │   ├── document-link.ts
+│       │   ├── hover.ts
+│       │   └── version-completion.ts
+│       └── utils/           # Service utilities (with colocated tests)
+└── language-server/         # Language server (Volar)
+    └── src/
+        ├── server.ts        # Server setup
+        └── workspace.ts     # Server workspace handling
+playground/                  # Playground for testing
+res/                         # Assets (e.g. marketplace icon)
 ```
 
 ### Key concepts
 
-- **Extractor** – Parses a supported file (`package.json`, `pnpm-workspace.yaml`, `.yarnrc.yml`) and extracts dependency information with AST ranges. Each file format has its own extractor in `extensions/vscode/src/core/extractors/`.
+- **Extractor** – Parses a supported file (`package.json`, `pnpm-workspace.yaml`, `.yarnrc.yml`) and extracts dependency information with AST ranges. Each file format has its own extractor in `packages/language-core/src/extractors/`.
 - **WorkspaceContext** – Holds per-workspace-folder state: detected package manager, resolved catalogs, and memoized dependency info. Created lazily and invalidated when workspace-level files change.
-- **ResolvedDependencyInfo** – A dependency with its protocol resolved (e.g., `catalog:` → actual version, `npm:alias@version` → underlying package). Providers consume resolved dependencies instead of raw AST data.
-- **Provider** – VS Code language feature (hover, completion, diagnostics, etc.) that operates on resolved dependencies.
+- **ResolvedDependencyInfo** – A dependency with its protocol resolved (e.g., `catalog:` → actual version, `npm:alias@version` → underlying package). Plugins consume resolved dependencies instead of raw AST data.
+- **Plugin** – A Volar language service plugin (hover, completion, diagnostics, etc.) in `packages/language-service/` that operates on resolved dependencies.
 
 ## Code style
 

README.md

@@ -12,6 +12,10 @@
 | Package | Description |
 | ------- | ----------- |
 | [`extensions/vscode`](./extensions/vscode) | [VS Code extension](https://marketplace.visualstudio.com/items?itemName=npmx-dev.vscode-npmx) for npmx |
+| [`packages/shared`](./packages/shared) | Shared constants, types, and LSP protocol definitions |
+| [`packages/language-core`](./packages/language-core) | Core logic: extractors, API clients, workspace context |
+| [`packages/language-service`](./packages/language-service) | Volar language service plugins (hover, completion, diagnostics, etc.) |
+| [`packages/language-server`](./packages/language-server) | Volar language server |
 
 ## Features