feat: emit an explicit color level from codeToANSI (#1320)

Author: EvanProgramming

docs/packages/cli.md

@@ -123,3 +123,18 @@ console.log(highlighted)
 1. `code: string`
 2. `lang: BundledLanguage`
 3. `theme: BundledTheme`
+
+and one optional parameter:
+
+4. `options?: CodeToANSIOptions`
+
+The color level of the emitted escape codes is explicit instead of being inferred from the environment, and defaults to `3` (truecolor). Use `options.colorLevel` to target a different level — pass the level reported by `ansis` to follow the current terminal, or `0` to get plain text:
+
+```ts
+import { codeToANSI } from '@shikijs/cli'
+import ansis from 'ansis'
+
+const highlighted = await codeToANSI(source, 'typescript', 'nord', {
+  colorLevel: ansis.level,
+})
+```

packages/cli/src/code-to-ansi.ts

@@ -1,10 +1,40 @@
 import type { BundledLanguage, BundledTheme } from 'shiki'
 import { FontStyle } from '@shikijs/vscode-textmate'
-import c from 'ansis'
+import { Ansis } from 'ansis'
 import { codeToTokensBase, getSingletonHighlighter } from 'shiki'
 import { hexApplyAlpha } from './colors'
 
-export async function codeToANSI(code: string, lang: BundledLanguage, theme: BundledTheme): Promise<string> {
+/**
+ * The ANSI color level of the emitted escape codes, matching the levels
+ * understood by `ansis`: `0` no color, `1` basic (16 colors), `2` 256 colors,
+ * `3` truecolor (24-bit).
+ */
+export type ANSIColorLevel = 0 | 1 | 2 | 3
+
+export interface CodeToANSIOptions {
+  /**
+   * The color level to emit.
+   *
+   * Defaults to `3` (truecolor), so the result does not depend on the
+   * environment this code happens to run in.
+   */
+  colorLevel?: ANSIColorLevel
+}
+
+/**
+ * Converts code to a string containing ANSI escape codes.
+ *
+ * The color level is explicit and does not depend on the current environment,
+ * as the result is not necessarily printed to the terminal that runs this
+ * code. Pass {@link CodeToANSIOptions.colorLevel} to target a different level.
+ */
+export async function codeToANSI(code: string, lang: BundledLanguage, theme: BundledTheme, options: CodeToANSIOptions = {}): Promise<string> {
+  // The default `ansis` instance infers color support from the environment
+  // (`NO_COLOR`, `FORCE_COLOR`, TTY detection, ...), which silently strips all
+  // highlighting when it guesses "wrong". Use an instance with an explicit
+  // level instead.
+  const ansi = new Ansis(options.colorLevel ?? 3)
+
   let output = ''
 
   const lines = await codeToTokensBase(code, {
@@ -20,16 +50,16 @@ export async function codeToANSI(code: string, lang: BundledLanguage, theme: Bun
       let text = token.content
       const color = token.color || themeReg.fg
       if (color)
-        text = c.hex(hexApplyAlpha(color, themeReg.type))(text)
+        text = ansi.hex(hexApplyAlpha(color, themeReg.type))(text)
       if (token.fontStyle) {
         if (token.fontStyle & FontStyle.Bold)
-          text = c.bold(text)
+          text = ansi.bold(text)
         if (token.fontStyle & FontStyle.Italic)
-          text = c.italic(text)
+          text = ansi.italic(text)
         if (token.fontStyle & FontStyle.Underline)
-          text = c.underline(text)
+          text = ansi.underline(text)
         if (token.fontStyle & FontStyle.Strikethrough)
-          text = c.strikethrough(text)
+          text = ansi.strikethrough(text)
       }
       output += text
     }

packages/cli/test/code-to-ansi.test.ts

@@ -0,0 +1,61 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+const ESCAPE = '\u001B'
+const ANSI_PREFIX = `${ESCAPE}[`
+const TRUECOLOR_FOREGROUND = `${ESCAPE}[38;2;`
+const ANSI256_FOREGROUND = `${ESCAPE}[38;5;`
+
+/**
+ * `codeToANSI` must not inherit the color support that the default `ansis`
+ * instance infers from the current environment: its result is not necessarily
+ * printed to the terminal running this code, so a "no color" environment used
+ * to silently strip all highlighting (#1274).
+ *
+ * The environment is set before importing the module under test, because
+ * `ansis` resolves color support at import time.
+ */
+async function importCodeToANSI() {
+  vi.resetModules()
+  return await import('../src/code-to-ansi')
+}
+
+describe('codeToANSI', () => {
+  afterEach(() => {
+    vi.unstubAllEnvs()
+    vi.resetModules()
+  })
+
+  it('emits truecolor escape codes when the environment disables color', async () => {
+    vi.stubEnv('NO_COLOR', '1')
+    vi.stubEnv('FORCE_COLOR', undefined)
+
+    const { codeToANSI } = await importCodeToANSI()
+    const output = await codeToANSI('# hi', 'markdown', 'github-dark-default')
+
+    expect(output).toContain(ANSI_PREFIX)
+    expect(output).toContain(TRUECOLOR_FOREGROUND)
+    expect(output).toContain('# hi')
+  })
+
+  it('emits plain text when the caller asks for no color', async () => {
+    vi.stubEnv('NO_COLOR', '1')
+    vi.stubEnv('FORCE_COLOR', undefined)
+
+    const { codeToANSI } = await importCodeToANSI()
+    const output = await codeToANSI('# hi', 'markdown', 'github-dark-default', { colorLevel: 0 })
+
+    expect(output).not.toContain(ANSI_PREFIX)
+    expect(output).toContain('# hi')
+  })
+
+  it('honors an explicit lower color level', async () => {
+    vi.stubEnv('NO_COLOR', '1')
+    vi.stubEnv('FORCE_COLOR', undefined)
+
+    const { codeToANSI } = await importCodeToANSI()
+    const output = await codeToANSI('# hi', 'markdown', 'github-dark-default', { colorLevel: 2 })
+
+    expect(output).toContain(ANSI256_FOREGROUND)
+    expect(output).not.toContain(TRUECOLOR_FOREGROUND)
+  })
+})