feat: introduce twoslash-protocol package

package.json

@@ -50,6 +50,7 @@
     "unbuild": "^2.0.0",
     "unplugin-vue-components": "^0.26.0",
     "vite": "^5.1.0",
+    "vite-tsconfig-paths": "^4.3.1",
     "vitest": "^1.2.2",
     "vue": "^3.4.16"
   },

packages/twoslash-protocol/LICENSE

@@ -0,0 +1,18 @@
+The MIT License (MIT)
+
+Copyright (c) 2024-PRESENT Anthony Fu <https://github.com/antfu>
+
+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.

packages/twoslash-protocol/README.md

@@ -0,0 +1,30 @@
+<img src="https://twoslash.netlify.app/logo.svg" alt="Twoslash Logo" width="150">
+
+# twoslash-protocol
+
+[![npm version][npm-version-src]][npm-version-href]
+[![npm downloads][npm-downloads-src]][npm-downloads-href]
+[![bundle][bundle-src]][bundle-href]
+[![JSDocs][jsdocs-src]][jsdocs-href]
+[![License][license-src]][license-href]
+
+[📚 Documentation](https://twoslash.netlify.app/)
+
+The protocol for Twoslash interface, a universal layer to support different language services that describe common editor features. This package also includes some common utilities for working with the protocol.
+
+## License
+
+MIT License © [Anthony Fu](https://github.com/antfu
+
+<!-- Badges -->
+
+[npm-version-src]: https://img.shields.io/npm/v/twoslash-protocol?style=flat&colorA=161514&colorB=EAB836
+[npm-version-href]: https://npmjs.com/package/twoslash-protocol
+[npm-downloads-src]: https://img.shields.io/npm/dm/twoslash-protocol?style=flat&colorA=161514&colorB=E66041
+[npm-downloads-href]: https://npmjs.com/package/twoslash-protocol
+[bundle-src]: https://img.shields.io/bundlephobia/minzip/twoslash-protocol?style=flat&colorA=161514&colorB=45627B&label=minzip
+[bundle-href]: https://bundlephobia.com/result?p=twoslash-protocol
+[license-src]: https://img.shields.io/github/license/twoslashes/twoslash.svg?style=flat&colorA=161514&colorB=45627B
+[license-href]: https://github.com/twoslashes/twoslash/blob/main/LICENSE
+[jsdocs-src]: https://img.shields.io/badge/jsdocs-reference-161514?style=flat&colorA=161514&colorB=EAB836
+[jsdocs-href]: https://www.jsdocs.io/package/twoslash-protocol

packages/twoslash-protocol/build.config.ts

@@ -0,0 +1,13 @@
+import { defineBuildConfig } from 'unbuild'
+
+export default defineBuildConfig({
+  entries: [
+    'src/index',
+    'src/types',
+  ],
+  declaration: true,
+  clean: true,
+  rollup: {
+    emitCJS: true,
+  },
+})

packages/twoslash-protocol/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "twoslash-protocol",
+  "type": "module",
+  "version": "0.1.2",
+  "description": "The protocol for the Twoslash interface",
+  "author": "Anthony Fu",
+  "license": "MIT",
+  "homepage": "https://github.com/twoslashes/twoslash",
+  "repository": {
+    "url": "https://github.com/twoslashes/twoslash",
+    "type": "git",
+    "directory": "packages/twoslash-protocol"
+  },
+  "bugs": {
+    "url": "https://github.com/twoslashes/twoslash/issues"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    },
+    "./types": {
+      "types": "./dist/types.d.mts",
+      "import": "./dist/types.mjs",
+      "require": "./dist/types.cjs"
+    }
+  },
+  "main": "dist/index.mjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.mts",
+  "typesVersions": {
+    "*": {
+      "./types": ["./dist/types.d.mts"],
+      "*": ["./dist/index.d.mts"]
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "unbuild",
+    "prepublishOnly": "nr build"
+  },
+  "simple-git-hooks": {
+    "pre-commit": "pnpm lint-staged"
+  },
+  "lint-staged": {
+    "*": "eslint --fix"
+  }
+}

packages/twoslash-protocol/src/index.ts

@@ -0,0 +1,2 @@
+export * from './types'
+export * from './utils'

packages/twoslash-protocol/src/types.ts

@@ -0,0 +1 @@
+export * from './types/index'

packages/twoslash-protocol/src/types/index.ts

@@ -0,0 +1,2 @@
+export * from './nodes'
+export * from './returns'

packages/twoslash/src/types/nodes.ts → packages/twoslash-protocol/src/types/nodes.ts

@@ -1,5 +1,3 @@
-import type { CompletionEntry } from 'typescript'
-
 /**
  * Basic node with start and length to represent a range in the code
  */
@@ -36,6 +34,11 @@ export interface NodeQuery extends Omit<NodeHover, 'type'> {
   type: 'query'
 }
 
+export interface CompletionEntry {
+  name: string
+  kind?: string
+}
+
 export interface NodeCompletion extends NodeBase {
   type: 'completion'
   /** Results for completions at a particular point */
@@ -44,22 +47,20 @@ export interface NodeCompletion extends NodeBase {
   completionsPrefix: string
 }
 
+export type ErrorLevel = 'warning' | 'error' | 'suggestion' | 'message'
+
 export interface NodeError extends NodeBase {
   type: 'error'
   id?: string
   /**
-   * Error level:
-   *
-   * Warning = 0
-   * Error = 1
-   * Suggestion = 2
-   * Message = 3
+   * Error level
+   * When not provided, defaults to 'error'
    */
-  level?: 0 | 1 | 2 | 3
+  level?: ErrorLevel
   /**
    * Error code
    */
-  code: number
+  code?: number | string
   /**
    * Error message
    */

packages/twoslash-protocol/src/types/returns.ts

@@ -0,0 +1,20 @@
+import type { TwoslashNode } from './nodes'
+
+export interface TwoslashGenericResult {
+  /**
+   * The output code, could be TypeScript, but could also be a JS/JSON/d.ts
+   */
+  code: string
+
+  /**
+   * Extension of the output code
+   */
+  extension?: string
+
+  /**
+   * Nodes containing various bits of information about the code
+   */
+  nodes: TwoslashNode[]
+}
+
+export type TwoslashGenericFunction<Options> = (code: string, filename?: string, options?: Options) => TwoslashGenericResult

packages/twoslash-protocol/src/utils.ts

@@ -0,0 +1,139 @@
+import type { NodeStartLength, NodeWithoutPosition, Position, Range, TwoslashNode } from './types'
+
+export function isInRange(index: number, range: Range) {
+  return range[0] <= index && index <= range[1]
+}
+
+export function isInRanges(index: number, ranges: Range[]) {
+  return ranges.find(range => isInRange(index, range))
+}
+
+/**
+ * Merge overlapping ranges
+ */
+export function mergeRanges(ranges: Range[]) {
+  ranges.sort((a, b) => a[0] - b[0])
+  const merged: Range[] = []
+  for (const range of ranges) {
+    const last = merged[merged.length - 1]
+    if (last && last[1] >= range[0])
+      last[1] = Math.max(last[1], range[1])
+    else
+      merged.push(range)
+  }
+  return merged
+}
+
+/**
+ * Slipt a string into lines, each line preserves the line ending.
+ */
+export function splitLines(code: string, preserveEnding = false): [string, number][] {
+  const parts = code.split(/(\r?\n)/g)
+  let index = 0
+  const lines: [string, number][] = []
+  for (let i = 0; i < parts.length; i += 2) {
+    const line = preserveEnding
+      ? parts[i] + (parts[i + 1] || '')
+      : parts[i]
+    lines.push([line, index])
+    index += parts[i].length
+    index += parts[i + 1]?.length || 0
+  }
+  return lines
+}
+
+/**
+ * Creates a converter between index and position in a code block.
+ */
+export function createPositionConverter(code: string) {
+  const lines = splitLines(code, true).map(([line]) => line)
+
+  function indexToPos(index: number): Position {
+    let character = index
+    let line = 0
+    for (const lineText of lines) {
+      if (character < lineText.length)
+        break
+      character -= lineText.length
+      line++
+    }
+    return { line, character }
+  }
+
+  function posToIndex(line: number, character: number) {
+    let index = 0
+    for (let i = 0; i < line; i++)
+      index += lines[i].length
+
+    index += character
+    return index
+  }
+
+  return {
+    lines,
+    indexToPos,
+    posToIndex,
+  }
+}
+
+/**
+ * Remove ranages for a string, and update nodes' `start` property accordingly
+ *
+ * Note that items in `nodes` will be mutated
+ */
+export function removeCodeRanges<T extends NodeStartLength>(code: string, removals: Range[], nodes: T[]): { code: string, removals: Range[], nodes: T[] }
+export function removeCodeRanges(code: string, removals: Range[]): { code: string, removals: Range[], nodes: undefined }
+export function removeCodeRanges(code: string, removals: Range[], nodes?: NodeStartLength[]) {
+  // Sort descending, so that we start removal from the end
+  const ranges = mergeRanges(removals)
+    .sort((a, b) => b[0] - a[0])
+
+  let outputCode = code
+  for (const remove of ranges) {
+    const removalLength = remove[1] - remove[0]
+    outputCode = outputCode.slice(0, remove[0]) + outputCode.slice(remove[1])
+    nodes?.forEach((node) => {
+      // nodes before the range, do nothing
+      if (node.start + node.length <= remove[0])
+        return undefined
+
+      // remove nodes that are within in the range
+      else if (node.start < remove[1])
+        node.start = -1
+
+      // move nodes after the range forward
+      else
+        node.start -= removalLength
+    })
+  }
+
+  return {
+    code: outputCode,
+    removals: ranges,
+    nodes,
+  }
+}
+
+/**
+ * - Calculate nodes `line` and `character` properties to match the code
+ * - Remove nodes that has negative `start` property
+ * - Sort nodes by `start`
+ *
+ * Note that the nodes items will be mutated, clone them beforehand if not desired
+ */
+export function resolveNodePositions(nodes: NodeWithoutPosition[], code: string): TwoslashNode[]
+export function resolveNodePositions(nodes: NodeWithoutPosition[], indexToPos: (index: number) => Position): TwoslashNode[]
+export function resolveNodePositions(nodes: NodeWithoutPosition[], options: string | ((index: number) => Position)): TwoslashNode[] {
+  const indexToPos = typeof options === 'string'
+    ? createPositionConverter(options).indexToPos
+    : options
+
+  const resolved = nodes
+    .filter(node => node.start >= 0)
+    .sort((a, b) => a.start - b.start || a.type.localeCompare(b.type)) as TwoslashNode[]
+
+  resolved
+    .forEach(node => Object.assign(node, indexToPos(node.start)))
+
+  return resolved
+}

packages/twoslash-vue/package.json

@@ -51,6 +51,7 @@
   },
   "dependencies": {
     "@vue/language-core": "^1.8.27",
-    "twoslash": "workspace:*"
+    "twoslash": "workspace:*",
+    "twoslash-protocol": "workspace:*"
   }
 }

packages/twoslash-vue/src/index.ts

@@ -13,16 +13,18 @@ import type {
   TwoslashReturnMeta,
 } from 'twoslash'
 import {
-  createPositionConverter,
   createTwoslasher as createTwoslasherBase,
   defaultCompilerOptions,
   defaultHandbookOptions,
   findFlagNotations,
   findQueryMarkers,
   getObjectHash,
+} from 'twoslash'
+import {
+  createPositionConverter,
   removeCodeRanges,
   resolveNodePositions,
-} from 'twoslash'
+} from 'twoslash-protocol'
 
 export interface VueSpecificOptions {
   /**

packages/twoslash/package.json

@@ -38,7 +38,8 @@
     "typescript": "*"
   },
   "dependencies": {
-    "@typescript/vfs": "1.5.0"
+    "@typescript/vfs": "1.5.0",
+    "twoslash-protocol": "workspace:*"
   },
   "devDependencies": {
     "ohash": "^1.1.3"