feat: improve warning messages

Author: antfu

packages/compat/src/index.ts

@@ -4,7 +4,7 @@ import type { AnsiToHtmlOptions, CodeToHtmlOptions, CodeToHtmlOptionsExtra, High
 import fs from 'node:fs'
 import fsp from 'node:fs/promises'
 import { transformerCompactLineOptions } from '@shikijs/transformers'
-import { bundledLanguages, bundledThemes, createHighlighter as getShiki, normalizeTheme, tokenizeAnsiWithTheme } from 'shiki'
+import { bundledLanguages, bundledThemes, createHighlighter as getShiki, normalizeTheme, tokenizeAnsiWithTheme, warnDeprecated } from 'shiki'
 import { ShikiCompatError } from './error'
 
 export const BUNDLED_LANGUAGES = bundledLanguages
@@ -35,6 +35,8 @@ export interface ShikiCompatHighlighter {
 }
 
 export async function getHighlighter(options: Partial<HighlighterOptions> = {}): Promise<ShikiCompatHighlighter> {
+  warnDeprecated(`@shikijs/compat is deprecated and will be removed in v3, please migrate to the main shiki package`)
+
   const themes = options.themes || []
   const langs = options.langs || []
 

packages/core/src/textmate/grammar-state.ts

@@ -1,6 +1,7 @@
 import type { GrammarState as GrammarStateInterface, GrammarStateMapKey } from '@shikijs/types'
 import type { StateStack, StateStackImpl } from '@shikijs/vscode-textmate'
 
+import { warnDeprecated } from '@shikijs/core'
 import { INITIAL } from '@shikijs/vscode-textmate'
 import { ShikiError } from '../../../types/src/error'
 import { toArray } from '../utils'
@@ -88,6 +89,7 @@ export class GrammarState implements GrammarStateInterface {
    * @deprecated use `getScopes` instead
    */
   get scopes(): string[] {
+    warnDeprecated('GrammarState.scopes is deprecated, use GrammarState.getScopes() instead')
     return getScopes(this._stacks[this.theme] as StateStackImpl)
   }
 

packages/core/src/warn.ts

@@ -1,21 +1,37 @@
-let emitDeprecation = false
+let _emitDeprecation: DeprecationTarget | boolean = false
+let _emitError = false
+
+export type DeprecationTarget = 3
 
 /**
  * Enable runtime warning for deprecated APIs, for the future versions of Shiki.
  *
- * Disabled by default, will be enabled in Shiki v2.
+ * You can pass a major version to only warn for deprecations that will be removed in that version.
  *
- * @experimental The accuracy of the warning messages is not yet guaranteed.
+ * By default, deprecation warning is set to 3 since Shiki v2.0.0
  */
-export function enableDeprecationWarnings(value = true): void {
-  emitDeprecation = value
+export function enableDeprecationWarnings(
+  emitDeprecation: DeprecationTarget | boolean = true,
+  emitError = false,
+): void {
+  _emitDeprecation = emitDeprecation
+  _emitError = emitError
 }
 
 /**
  * @internal
  */
-export function warnDeprecated(message: string): void {
-  if (emitDeprecation)
+export function warnDeprecated(message: string, version: DeprecationTarget = 3): void {
+  if (!_emitDeprecation)
+    return
+  if (typeof _emitDeprecation === 'number' && version > _emitDeprecation)
+    return
+
+  if (_emitError) {
+    throw new Error(`[SHIKI DEPRECATE]: ${message}`)
+  }
+  else {
     // eslint-disable-next-line no-console
     console.trace(`[SHIKI DEPRECATE]: ${message}`)
+  }
 }

packages/engine-javascript/test/compare.test.ts

@@ -160,7 +160,7 @@ const cases: Cases[] = [
 ]
 
 describe('cases', async () => {
-  await loadWasm(import('@shikijs/core/wasm-inlined'))
+  await loadWasm(import('@shikijs/engine-oniguruma/wasm-inlined'))
 
   const resolved = await Promise.all(cases.map(async (c) => {
     const theme = await c.theme().then(r => r.default)

packages/shiki/test/get-highlighter.test.ts

@@ -1,4 +1,4 @@
-import { getSingletonHighlighter } from 'shiki'
+import { createOnigurumaEngine, getSingletonHighlighter } from 'shiki'
 import { expect, it } from 'vitest'
 import { getSingletonHighlighterCore } from '../src/core'
 import js from '../src/langs/javascript.mjs'
@@ -9,7 +9,7 @@ it('getSingletonHighlighterCore', async () => {
   const shiki1 = await getSingletonHighlighterCore({
     themes: [nord],
     langs: [js as any],
-    loadWasm: import('@shikijs/core/wasm-inlined'),
+    engine: createOnigurumaEngine(import('@shikijs/engine-oniguruma/wasm-inlined')),
   })
 
   expect(shiki1.codeToHtml('console.log("Hi")', { lang: 'javascript', theme: 'nord' }))

packages/transformers/package.json

@@ -35,6 +35,6 @@
     "prepublishOnly": "nr build"
   },
   "dependencies": {
-    "shiki": "workspace:*"
+    "@shikijs/types": "workspace:*"
   }
 }

packages/transformers/src/shared/notation-transformer.ts

@@ -1,5 +1,6 @@
+import type { ShikiTransformer, ShikiTransformerContext } from '@shikijs/core'
 import type { Element, Text } from 'hast'
-import type { ShikiTransformer, ShikiTransformerContext } from 'shiki'
+import { warnDeprecated } from '@shikijs/core'
 import { parseComments, type ParsedComments, v1ClearEndCommentPrefix } from './parse-comments'
 
 export type MatchAlgorithm = 'v1' | 'v3'
@@ -27,6 +28,10 @@ export function createCommentNotationTransformer(
   ) => boolean,
   matchAlgorithm: MatchAlgorithm = 'v1',
 ): ShikiTransformer {
+  if (matchAlgorithm === 'v1') {
+    warnDeprecated('`matchAlgorithm: "v1"` is deprecated and will be removed in the future. Please explicitly set `matchAlgorithm: "v3"` in the transformer options.', 3)
+  }
+
   return {
     name,
     code(code) {

packages/transformers/src/transformers/compact-line-options.ts

@@ -1,4 +1,4 @@
-import type { ShikiTransformer } from 'shiki'
+import type { ShikiTransformer } from '@shikijs/types'
 
 export interface TransformerCompactLineOption {
   /**

packages/transformers/src/transformers/meta-highlight-word.ts

@@ -1,4 +1,4 @@
-import type { ShikiTransformer } from 'shiki'
+import type { ShikiTransformer } from '@shikijs/types'
 
 export function parseMetaHighlightWords(meta: string): string[] {
   if (!meta)

packages/transformers/src/transformers/meta-highlight.ts

@@ -1,4 +1,4 @@
-import type { ShikiTransformer } from 'shiki'
+import type { ShikiTransformer } from '@shikijs/types'
 
 export function parseMetaHighlightString(meta: string): number[] | null {
   if (!meta)