@speclynx/apidom-ls 2.11.7 → 2.13.0

package/README.md

@@ -1,208 +1,65 @@
-<h1 align="center">SpecLynx ApiDOM Language Service</h1>
+# @speclynx/apidom-ls
 
-<p align="center">
-  A comprehensive <strong>Language Service Library</strong> for API description languages, built on <a href="https://github.com/speclynx/apidom">SpecLynx ApiDOM</a>.
-</p>
+This package has been renamed. It is now published as
+[`@speclynx/api-languageservice`](https://www.npmjs.com/package/@speclynx/api-languageservice),
+and its source lives at https://github.com/speclynx/api-languageservice.
 
-<p align="center">
-  <a href="https://www.npmjs.com/package/@speclynx/apidom-ls"><img src="https://img.shields.io/npm/v/@speclynx/apidom-ls.svg" alt="npm version"></a>
-  <img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="License: Apache 2.0">
-</p>
+Version 2.13.0 of `@speclynx/apidom-ls` is a final compatibility release. It contains no code of
+its own: it depends on `@speclynx/api-languageservice` and forwards every entry point the old
+package advertised — the CommonJS and ES module roots, the type declarations, all twelve
+`services/validation/providers/*` subpaths, and the UMD browser bundle at
+`dist/apidom-ls.browser.min.js` with its `apidomLs` global. Upgrading to it is a no-op, and it is
+published so that nothing breaks on the day of the rename.
 
-<div align="center">
-    <a href="https://speclynx.com"><img alt="SpecLynx Logo" src="https://github.com/user-attachments/assets/1cfd6c8e-0206-4d53-9a2c-e4d10be84ca0" /></a>
-</div>
+## Migrating
 
----
-
-## Overview
-
-**SpecLynx ApiDOM Language Service** (`@speclynx/apidom-ls`) is a language service library that provides intelligent editing features for API description languages. It implements programmatic language features following the [Language Server Protocol (LSP)](https://microsoft.github.io/language-server-protocol/) specification, making it easy to integrate into any LSP-compatible editor or IDE through a server wrapper.
-
-> **Note:** This is a *language service*, not a language server. A language service is a library that implements language features, while a language server is a separate process that communicates via LSP. This library can be wrapped by an LSP server to expose its features to editors.
-
-## Supported Languages
-
-| Language | Versions                          | Formats |
-|----------|-----------------------------------|---------|
-| [**OpenAPI**](https://spec.openapis.org/oas/) | 2.0, 3.0.0, 3.0.1, 3.0.2, 3.0.3, 3.0.4, 3.1.0, 3.1.1, 3.1.2 | JSON, YAML |
-| [**AsyncAPI**](https://v2.asyncapi.com/docs/reference/specification/v2.6.0) | 2.0, 2.1, 2.2, 2.3, 2.4, 2.5, 2.6 | JSON, YAML |
-| [**Arazzo**](https://spec.openapis.org/arazzo/latest.html) | 1.0.0, 1.0.1 | JSON, YAML |
-| [**Overlay**](https://spec.openapis.org/overlay/latest.html) | 1.0.0, 1.1.0 | JSON, YAML |
-| [**JSON Schema**](https://json-schema.org/specification-links) | Draft 4/5, 6, 7, 2019-09, 2020-12 | JSON, YAML |
-
-## Features
-
-The language service provides the following LSP-compatible features:
-
-| Feature | Method | Description |
-|---------|--------|-------------|
-| **Validation** | `doValidation()` | Syntax and semantic validation with diagnostics |
-| **Completion** | `doCompletion()` | Context-aware auto-completion suggestions |
-| **Hover** | `doHover()` | Documentation and type information on hover |
-| **Go to Definition** | `doProvideDefinition()` | Navigate to `$ref` target definitions |
-| **Find References** | `doProvideReferences()` | Find all references to a symbol |
-| **Document Symbols** | `doFindDocumentSymbols()` | Outline view and breadcrumbs |
-| **Semantic Tokens** | `computeSemanticTokens()` | Enhanced syntax highlighting |
-| **Code Actions** | `doCodeActions()` | Quick fixes and refactoring |
-| **Document Links** | `doLinks()` | Clickable links in documents |
-| **Formatting** | `doFormatting()` | Document formatting |
-| **Dereferencing** | `doDeref()` | Resolve all `$ref` references |
-| **Format Conversion** | `doConversion()` | Convert between JSON and YAML |
-| **Color Support** | `findDocumentColors()` | Color picker for color values |
-
-## Installation
+Change the dependency and the import specifier; nothing else moves.
 
 ```sh
-npm install @speclynx/apidom-ls
+npm uninstall @speclynx/apidom-ls
+npm install @speclynx/api-languageservice
 ```
 
-## Quick Start
-
-### Basic Setup
-
-```typescript
-import { getLanguageService } from '@speclynx/apidom-ls';
-import { TextDocument } from 'vscode-languageserver-textdocument';
-
-// Create the language service
-const languageService = getLanguageService({});
-
-// Create a document from your API specification
-const spec = `
-openapi: "3.1.0"
-info:
-  title: My API
-  version: 1.0.0
-paths: {}
-`;
-
-const document = TextDocument.create(
-  'file:///api.yaml',
-  'yaml',
-  0,
-  spec
-);
+```diff
+-import { getLanguageService } from '@speclynx/apidom-ls';
++import { getLanguageService } from '@speclynx/api-languageservice';
 ```
 
-### Validation
-
-```typescript
-const diagnostics = await languageService.doValidation(document);
+Subpath imports change the same way:
 
-for (const diagnostic of diagnostics) {
-  console.log(`[${diagnostic.severity}] Line ${diagnostic.range.start.line}: ${diagnostic.message}`);
-}
+```diff
+-import { OpenAPi31JsonSchemaValidationProvider } from '@speclynx/apidom-ls/services/validation/providers/openapi-31-json-schema';
++import { OpenAPi31JsonSchemaValidationProvider } from '@speclynx/api-languageservice/services/validation/providers/openapi-31-json-schema';
 ```
 
-### Auto-Completion
+Browser consumers loading the bundle from a CDN change the package in the URL, and the global
+from `apidomLs` to `apiLanguageService`:
 
-```typescript
-import { Position } from 'vscode-languageserver-types';
-
-const position = Position.create(4, 2); // line 4, character 2
-const completions = await languageService.doCompletion(document, {
-  textDocument: { uri: document.uri },
-  position
-});
-
-console.log('Suggestions:', completions?.items.map(item => item.label));
+```diff
+-<script src="https://unpkg.com/@speclynx/apidom-ls"></script>
++<script src="https://unpkg.com/@speclynx/api-languageservice"></script>
 ```
 
-### Hover Information
+The API itself is unchanged. There is no code change beyond the name.
 
-```typescript
-const hover = await languageService.doHover(document, Position.create(1, 5));
+## This is the last release under this name
 
-if (hover) {
-  console.log('Hover content:', hover.contents);
-}
-```
+2.13.0 is the final version of `@speclynx/apidom-ls`, and it is deprecated on publication. There
+will be no further releases under this name; everything — features, fixes, new specification
+versions — happens in `@speclynx/api-languageservice` from 2.13.0 onward.
 
-### Go to Definition
+One consequence is worth knowing, though it is a description of how npm works rather than a
+support commitment. This release depends on `@speclynx/api-languageservice@^2.13.0`, so an
+install of it continues to resolve whatever has since been published in the 2.x line. You are
+not frozen by staying here — but you are unsupported, and a 3.0.0 would fall outside that range.
+Migrate.
 
-```typescript
-const definition = await languageService.doProvideDefinition(document, {
-  textDocument: { uri: document.uri },
-  position: Position.create(10, 15) // position on a $ref value
-});
-
-if (definition) {
-  console.log('Definition location:', definition.uri, definition.range);
-}
-```
-
-### Cleanup
-
-```typescript
-// Always terminate when done to free resources
-languageService.terminate();
-```
-
-## Advanced Configuration
-
-The language service can be configured with custom providers and settings:
-
-```typescript
-import { getLanguageService, LogLevel } from '@speclynx/apidom-ls';
-
-const languageService = getLanguageService({
-  // Logging configuration
-  logLevel: LogLevel.WARN,
-  performanceLogs: false,
-
-  // Custom validation providers
-  validatorProviders: [/* custom validators */],
-
-  // Custom completion providers
-  completionProviders: [/* custom completions */],
-
-  // Custom hover providers
-  hoverProviders: [/* custom hovers */],
-
-  // Enable clickable links for URLs in hover
-  hoverFollowLinkEntry: true,
-});
-```
-
-## Architecture
-
-```
-        ┌─────────────────────────────────────┐
-        │          Your Application           │
-        │      (IDE, Editor, CLI, etc.)       │
-        └─────────────────┬───────────────────┘
-                          │
-                          ▼
-        ┌─────────────────────────────────────┐
-        │         LSP Server Wrapper          │
-        │      (implements LSP protocol)      │
-        └─────────────────┬───────────────────┘
-                          │
-                          ▼
-  ╔═══════════════════════════════════════════════╗
-  ║                                               ║
-  ║       SpecLynx ApiDOM Language Service        ║
-  ║            (this language service)            ║
-  ║                                               ║
-  ╚═══════════════════════╤═══════════════════════╝
-                          │
-                          ▼
-        ┌─────────────────────────────────────┐
-        │           SpecLynx ApiDOM           │
-        │   parsing ∙ datamodel ∙ traversal   │
-        └─────────────────────────────────────┘
-```
-
-## Support & Documentation
-
-For full documentation and **enterprise support** please contact: **info@speclynx.com**
+The exception is the browser bundle. `dist/apidom-ls.browser.min.js` physically contains the
+code rather than forwarding to it, so anything loading it from a CDN is pinned to this version's
+bytes.
 
 ## License
 
-ApiDOM Language Service is licensed under [Apache 2.0 license](https://github.com/speclynx/apidom/blob/main/LICENSES/Apache-2.0.txt).
-ApiDOM Language Service comes with an explicit **NOTICE** file inside npm distribution package
-containing additional legal notices and information.
-
-This project uses [REUSE specification](https://reuse.software/spec/) that defines a standardized method
-for declaring copyright and licensing for software projects.
+Licensed under the [Apache 2.0 license](https://github.com/speclynx/api-languageservice/blob/main/LICENSES/Apache-2.0.txt).
+This package ships an explicit `NOTICE` file containing additional legal notices, and a
+`dist/THIRD-PARTY-NOTICES.txt` listing the open source software bundled into its browser bundle.