biome.printDiagnostics write to STDOUT instead of HTML

[alexandernst]

It should be possible to call biome.printDiagnostics (or an equivalent method) and get the diagnostics printed on STDOUT instead as an HTML string.

Context: I'm making an esbuild plugin that could benefit from this.

[ematipico]

Sorry, I didn't understand the proposal. Could you provide more information about what you are talking about? You mentioned stdout (CLI) but before you talk about biome.* which, I suppose, is about the JavaScript bindings.

[alexandernst]

Sorry, my bad, i should have explained myself better.

I’m using the js-api bindings in a plugin for esbuild. My idea is to generate a report/diagnostics (like the one that gets printed on stdout when using the cli) when a file is modified.

I’m hooking to esbuild's hooks in order to get the path of the modified file(s) and then I’m calling biome (via the js-api). I’m able to get the diagnostics, but calling 'printDiagnostics' will return a string with HTML content, which is not suitable for printing to the stdout. It would be useful (for my use case) to be able to call a similar method that would return a string with diagnostics suitable to be printed on stdout.

[axetroy]

You need to customize a Printer(Formatter).

Similar to #4034

This is the formatter I imitated based on eslint.

It will output a format similar to eslint

const fs = require('node:fs')
const { promisify } = require('node:util')
const path = require('node:path')

const { WebpackError } = require('webpack')
const chalk = require('chalk')
const execa = require('execa')

/**
 * 将字符位置转换为行号和列号
 * @param {string} fileContent 文本内容
 * @param {number} position 字符位置
 * @returns {{ line: number, column: number }} 行号和列号
 */
function getLineAndColumn(fileContent, position) {
    let line = 1
    let column = 1
    let currentPos = 0

    // 提前返回，如果 position 超出文件内容的长度
    if (position >= fileContent.length) {
        return { line, column }
    }

    while (currentPos < position) {
        if (fileContent[currentPos] === '\n') {
            line++
            column = 1
        } else {
            column++
        }
        currentPos++
    }

    return { line, column }
}

/**
 * 对齐二维数组中的字符串
 * @param {string[][]} array 二维数组
 * @returns {string[][]} 对齐后的二维数组
 */
function alignStrings(array) {
    if (array.length === 0) return array

    // 找到每列的最大字符串长度
    const colMaxLengths = array[0].map((_, colIndex) => {
        return Math.max(...array.map((row) => row[colIndex]?.length || 0))
    })

    // 遍历数组，将每个字符串补齐到对应列的最大长度
    return array.map((row) => {
        return row.map((str, colIndex) => {
            const maxLength = colMaxLengths[colIndex]
            return str.padEnd(maxLength, ' ')
        })
    })
}

/**
 * FastBiomePlugin 插件用于在文件变更时运行 Biome
 */
class FastBiomePlugin {
    /** @type {Array<string>} */
    #extensions = []

    /** @type {string | undefined} */
    #configPath = undefined

    /**
     * 创建一个新的 FastBiomePlugin 实例。
     * @param {Object} options - Biome 配置选项。
     * @param {string[]} options.extensions - 要检查的文件扩展名
     * @param {string[]} options.configPath - Biome 配置文件
     */
    constructor({ extensions = ['js'], configPath } = {}) {
        this.#extensions = extensions
        this.#configPath = configPath
    }

    /**
     * 要检查的文件
     * @type {Set<string>}
     */
    #dirtyFiles = new Set()

    /**
     * @param {import('webpack').Compiler} compiler
     */
    apply(compiler) {
        const extensions = new Set(
            this.#extensions.map((ext) => {
                return ext.startsWith('.') ? ext : '.' + ext
            })
        )

        const logger = compiler.getInfrastructureLogger('fast-biome-webpack-plugin')

        compiler.hooks.make.tapPromise('FastBiomePlugin', async (compilation) => {
            // 监听文件修改，然后运行 biome
            if (compilation.compiler.modifiedFiles?.size) {
                const changedFiles = [...this.#dirtyFiles]

                logger.info('Running Biome on changed files...')

                // 获取变更的文件
                for (const file of Array.from(compilation.compiler.modifiedFiles.values())) {
                    if (file.includes('node_modules')) {
                        continue
                    }

                    // 只有受支持的扩展，才会运行 biome
                    if (!extensions.has(path.extname(file))) {
                        continue
                    }

                    // 如果文件已经在变更列表中，就不再添加
                    if (changedFiles.includes(file)) {
                        continue
                    }

                    const isExist = await promisify(fs.access)(file, fs.constants.F_OK)
                        .then(() => true)
                        .catch(() => false)

                    if (isExist) {
                        changedFiles.push(file)
                    }
                }

                for (const file of changedFiles) {
                    try {
                        await this.lintFile(compilation, file)
                    } catch (error) {
                        logger.error(error)
                        compilation.errors.push(error)
                    }
                }
            }
        })
    }

    /**
     *
     * @param {string} filePath
     * @param {Array<import('@biomejs/js-api').Diagnostic>} diagnostics
     */
    formatDiagnostic(filePath, diagnostics) {
        const output = [chalk.underline(filePath)]

        const summary = alignStrings(
            diagnostics.map((diagnostic) => {
                let pos = 'unknown:unknown'

                if (diagnostic.location.span && diagnostic.location.sourceCode) {
                    const [start] = diagnostic.location.span
                    const { line, column } = getLineAndColumn(diagnostic.location.sourceCode, start)

                    pos = `${line}:${column}`
                }

                const severityColor =
                    diagnostic.severity === 'error' || diagnostic.severity === 'fatal'
                        ? chalk.red
                        : diagnostic.severity === 'warning'
                          ? chalk.yellow
                          : chalk.blue

                return [chalk.gray(pos), severityColor(diagnostic.severity), diagnostic.description, chalk.gray('Biome:' + diagnostic.category)]
            })
        )
            .map((row) => {
                return '  ' + row.join('  ')
            })
            .join('\n')

        output.push(summary)

        const errorCount = diagnostics.filter((v) => v.severity === 'error').length
        const warningCount = diagnostics.filter((v) => v.severity === 'warning').length
        const fixableErrorCount = diagnostics.filter((v) => v.severity === 'error' && v.tags.includes('fixable')).length
        const fixableWarningCount = diagnostics.filter((v) => v.severity === 'warning' && v.tags.includes('fixable')).length

        const summarize = [chalk.red(`✖ ${diagnostics.length} problems (${errorCount} errors, ${warningCount} warnings)`)]

        if (fixableErrorCount > 0 || fixableWarningCount > 0) {
            const fixableErrorMessage = `${fixableErrorCount} error and ${fixableWarningCount} warnings potentially fixable with the \`--write\` option.`
            summarize.push(`  ${chalk.red(fixableErrorMessage)}`)
        }

        output.push('\n' + summarize.join('\n'))

        return '\n' + output.join('\n')
    }

    /**
     *
     * @param {string} filePath
     */
    async execLint(filePath) {
        const biomeScriptPath = require.resolve('@biomejs/biome/bin/biome')
        const { stdout } = await execa(
            'node',
            [
                biomeScriptPath,
                'check',
                this.#configPath ? `--config-path=${this.#configPath}` : undefined,
                '--reporter=json',
                '--no-errors-on-unmatched',
                filePath
            ].filter(Boolean),
            {
                stdout: 'pipe'
            }
        ).catch((error) => error)

        const result = JSON.parse(stdout)

        return result.diagnostics
    }

    /**
     *
     * @param {import('webpack').Compilation} compilation
     * @param {string} filePath
     */
    async lintFile(compilation, filePath) {
        /** @type {Map<string, any>} */
        const customLintRules = new Map()
        /** @type {Set<string>} */
        const skipRules = new Set([])

        if (this.#configPath) {
            /**
             * @type {typeof import('../../biome.json')}
             */
            const config = JSON.parse(await fs.promises.readFile(this.#configPath, 'utf8'))

            const rules = config.linter.rules

            for (const [group, ruleDefinition] of Object.entries(rules)) {
                if (typeof ruleDefinition === 'boolean') continue

                if (Object.prototype.toString.call(ruleDefinition) === '[object Object]') {
                    for (const [ruleName, ruleValue] of Object.entries(ruleDefinition)) {
                        const category = `lint/${group}/${ruleName}`

                        if (ruleValue === 'off' || ruleValue?.level === 'off') {
                            skipRules.add(category)
                        } else {
                            customLintRules.set(`lint/${group}/${ruleName}`, ruleValue)
                        }
                    }
                }
            }
        }

        const diagnostics = await this.execLint(filePath)

        const shouldReportSeverity = new Set(['error', 'fatal', 'warning'])
        const shouldReportedDiagnostics = diagnostics
            .filter((v) => shouldReportSeverity.has(v.severity) && !skipRules.has(v.category))
            .map((v) => {
                const customRuleValue = customLintRules.get(v.category)

                if (!customRuleValue) return v

                const customLevel = customRuleValue?.level ?? customRuleValue

                if (customLevel !== v.severity) {
                    const newDiagnostic = {
                        ...v,
                        severity: customLevel
                    }

                    return newDiagnostic
                }

                return v
            })

        if (shouldReportedDiagnostics.length > 0) {
            const errorMessage = this.formatDiagnostic(filePath, shouldReportedDiagnostics)

            const error = new WebpackError(errorMessage)

            compilation.errors.push(error)
        }

        // 判断这个文件是否还有 error 或 warning
        if (shouldReportedDiagnostics.length > 0) {
            this.#dirtyFiles.add(filePath)
        } else {
            this.#dirtyFiles.delete(filePath)
        }
    }
}

module.exports = FastBiomePlugin

[alexandernst]

It would be nice to have this builtin in biome!