@yoyoboot/web-lint-config 10.5.5

package/README.md

@@ -0,0 +1,23 @@
+# `@yoyoboot/web-lint-config`
+
+YoyoBoot 的公共 Web 语义检查预设，提供 ESLint flat config、Stylelint 16 config 与只减不增的历史债务门禁。Prettier 仍由消费者拥有格式偏好，项目架构规则留在项目本地配置。
+
+## 使用
+
+```js
+// eslint.config.mjs
+import { webLintConfig } from '@yoyoboot/web-lint-config/eslint'
+export default webLintConfig({ environment: 'browser' })
+```
+
+```js
+// stylelint.config.mjs
+import { styleLintConfig } from '@yoyoboot/web-lint-config/stylelint'
+export default styleLintConfig({ tailwind: true })
+```
+
+Stylelint 预设使用字符串形式的 `postcss-html` / `postcss-less` custom syntax，兼容声明的 Stylelint 16.11+ peer 范围；Vue SFC 为兼容 `<style lang="less">` 不把 Less function 与 `//` comment 当作 CSS 语义错误，其它样式 correctness 规则仍保持启用。
+
+消费者通过 `quality.config.mjs` 显式声明 eslint/style/format glob，并使用 `web-quality ci` 执行渐进门禁。首次基线只能在仓库历史中不存在该文件时用 `web-quality init` 建立；后续只能运行 `web-quality prune` 删除已消失条目，禁止手工扩容、总数额度或通配符忽略。
+
+源 manifest 始终保持 `private: true` 与 `0.0.0-private`。产品版本由 Unified Release Train staging 注入；本地 tarball 或 prepare-only 结果不代表 registry 已发布。

package/cli.mjs

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+import { mkdir, writeFile } from 'node:fs/promises'
+import { runQuality } from './quality.mjs'
+
+const args = process.argv.slice(2)
+const [mode = 'check', tool = 'all', flag] = args
+try {
+  if (
+    args.length > 3 ||
+    !['check', 'ci', 'report', 'init', 'prune'].includes(mode) ||
+    !['all', 'eslint', 'style', 'format'].includes(tool) ||
+    (flag && flag !== '--fix') ||
+    (mode !== 'check' && (flag || tool !== 'all'))
+  ) {
+    throw new Error(
+      'Usage: web-quality check [all|eslint|style|format] [--fix] | ci | report | init | prune',
+    )
+  }
+  const result = await runQuality({ mode, tool, fix: flag === '--fix' })
+  if (mode === 'report') {
+    await mkdir('.quality', { recursive: true })
+    await writeFile('.quality/report.json', `${JSON.stringify(result, null, 2)}\n`)
+  } else if (!result.passed) process.exitCode = 1
+} catch (error) {
+  console.error(error)
+  process.exitCode = 2
+}

package/eslint.mjs

@@ -0,0 +1,42 @@
+import js from '@eslint/js'
+import prettier from 'eslint-config-prettier/flat'
+import vue from 'eslint-plugin-vue'
+import globals from 'globals'
+import ts from 'typescript-eslint'
+import vueParser from 'vue-eslint-parser'
+
+export const defaultIgnores = ['**/node_modules/**', '**/dist/**', '**/coverage/**']
+
+/** Project architecture and naming exceptions belong in the caller's config. */
+export function webLintConfig({ environment = 'browser', ignores = [] } = {}) {
+  if (!['browser', 'node'].includes(environment)) throw new Error('Unknown lint environment')
+  const code = ['**/*.{js,mjs,cjs,jsx,ts,tsx,mts,cts,vue}']
+  const typed = ['**/*.{ts,tsx,mts,cts,vue}']
+  return ts.config(
+    { ignores: [...defaultIgnores, ...ignores] },
+    {
+      files: code,
+      extends: [js.configs.recommended],
+      languageOptions: { globals: globals[environment], ecmaVersion: 'latest' },
+    },
+    { files: typed, extends: [...ts.configs.recommended] },
+    {
+      files: ['**/*.vue'],
+      extends: [...vue.configs['flat/recommended']],
+      languageOptions: {
+        parser: vueParser,
+        parserOptions: { parser: ts.parser, extraFileExtensions: ['.vue'] },
+      },
+    },
+    {
+      files: [
+        '**/*.{mjs,cjs}',
+        '**/*.config.{js,ts}',
+        '**/tools/**/*.{js,ts}',
+        '**/scripts/**/*.{js,ts}',
+      ],
+      languageOptions: { globals: globals.node },
+    },
+    prettier,
+  )
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@yoyoboot/web-lint-config",
+  "version": "10.5.5",
+  "type": "module",
+  "description": "共享 Web 语义检查预设与渐进质量门禁",
+  "homepage": "https://github.com/yoyoboot/YoyoBoot/tree/main/packages/web-lint-config",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yoyoboot/YoyoBoot.git",
+    "directory": "packages/web-lint-config"
+  },
+  "bugs": {
+    "url": "https://github.com/yoyoboot/YoyoBoot/issues"
+  },
+  "exports": {
+    "./eslint": "./eslint.mjs",
+    "./stylelint": "./stylelint.mjs",
+    "./quality": "./quality.mjs"
+  },
+  "bin": {
+    "web-quality": "./cli.mjs"
+  },
+  "files": [
+    "eslint.mjs",
+    "stylelint.mjs",
+    "quality.mjs",
+    "cli.mjs",
+    "README.md"
+  ],
+  "engines": {
+    "node": "^20.19.0 || ^22.13.0 || >=24"
+  },
+  "dependencies": {
+    "@eslint/js": "9.39.1",
+    "eslint-config-prettier": "10.1.8",
+    "eslint-plugin-vue": "10.9.2",
+    "fast-glob": "3.3.3",
+    "globals": "17.7.0",
+    "postcss-html": "1.8.0",
+    "postcss-less": "6.0.0",
+    "typescript-eslint": "8.63.0",
+    "vue-eslint-parser": "10.4.1"
+  },
+  "peerDependencies": {
+    "eslint": "^9.15.0 || ^10.0.0",
+    "prettier": "^3.3.3",
+    "stylelint": "^16.11.0",
+    "typescript": ">=4.8.4 <6.1.0"
+  }
+}

package/quality.mjs

@@ -0,0 +1,260 @@
+import { createHash } from 'node:crypto'
+import { execFileSync } from 'node:child_process'
+import { readFile, writeFile } from 'node:fs/promises'
+import { relative, resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import fg from 'fast-glob'
+import { ESLint } from 'eslint'
+import stylelint from 'stylelint'
+import * as prettier from 'prettier'
+
+const portable = (value) => value.replaceAll('\\', '/')
+const normalized = (value) => value.replaceAll('\r\n', '\n')
+const hash = (value) => createHash('sha256').update(normalized(value)).digest('hex')
+
+export function fingerprint({ tool, file, rule, message, source }) {
+  return hash(JSON.stringify([tool, portable(file), rule, message, normalized(source).trim()]))
+}
+
+export function collectEntries(issues) {
+  const entries = {}
+  for (const issue of issues) {
+    if (issue.fatal) throw new Error(`Cannot baseline fatal issue: ${issue.file}: ${issue.message}`)
+    const key = fingerprint(issue)
+    if (entries[key]) entries[key].count += 1
+    else
+      entries[key] = {
+        tool: issue.tool,
+        file: issue.file,
+        rule: issue.rule,
+        message: issue.message,
+        count: 1,
+      }
+  }
+  return Object.fromEntries(Object.entries(entries).sort(([a], [b]) => a.localeCompare(b)))
+}
+
+export function compareBaseline(current, baseline) {
+  const added = Object.entries(current).filter(
+    ([key, item]) => item.count > (baseline[key]?.count ?? 0),
+  )
+  const removed = Object.entries(baseline).filter(
+    ([key, item]) => item.count > (current[key]?.count ?? 0),
+  )
+  return { added, removed }
+}
+
+export function pruneBaseline(current, baseline) {
+  return Object.fromEntries(
+    Object.entries(baseline)
+      .filter(([key]) => current[key])
+      .map(([key, item]) => [key, { ...item, count: Math.min(item.count, current[key].count) }]),
+  )
+}
+
+export function validateBaseline(value) {
+  if (
+    value?.schemaVersion !== 1 ||
+    !value.entries ||
+    typeof value.entries !== 'object' ||
+    Array.isArray(value.entries)
+  ) {
+    throw new Error('Invalid quality baseline schema')
+  }
+  for (const [key, entry] of Object.entries(value.entries)) {
+    if (!/^[a-f0-9]{64}$/.test(key) || !Number.isSafeInteger(entry.count) || entry.count < 1) {
+      throw new Error('Invalid quality baseline fingerprint/count')
+    }
+  }
+  return value
+}
+
+export function assertBaselineDoesNotGrow(baseline, previous) {
+  if (compareBaseline(baseline.entries, previous.entries).added.length) {
+    throw new Error('Quality baseline grew relative to Git base; remove added exceptions')
+  }
+}
+
+function checkGitBaseline(cwd, baselinePath) {
+  const gitRoot = execFileSync('git', ['rev-parse', '--show-toplevel'], {
+    cwd,
+    encoding: 'utf8',
+  }).trim()
+  const locator = portable(relative(gitRoot, baselinePath))
+  const base = process.env.WEB_LINT_BASE_REF || 'HEAD'
+  // Missing/invalid history must not silently disable the ratchet.
+  execFileSync('git', ['rev-parse', '--verify', `${base}^{commit}`], { cwd, stdio: 'pipe' })
+  const files = execFileSync('git', ['ls-tree', '--name-only', base, '--', locator], {
+    cwd: gitRoot,
+    encoding: 'utf8',
+  }).trim()
+  if (!files) return undefined // Initial baseline is a reviewable addition in this change.
+  return validateBaseline(
+    JSON.parse(execFileSync('git', ['show', `${base}:${locator}`], { cwd, encoding: 'utf8' })),
+  )
+}
+
+export async function scan({ cwd, config, tool = 'all', fix = false }) {
+  const issues = []
+  const counts = {}
+  const ignored = [
+    '**/node_modules/**',
+    '**/dist/**',
+    '**/coverage/**',
+    '**/.quality/**',
+    ...(config.ignore ?? []),
+  ]
+  const filesFor = async (kind) => {
+    const patterns = config[kind]
+    if (!Array.isArray(patterns)) throw new Error(`Missing explicit ${kind} scope`)
+    const files = (
+      await fg(patterns, { cwd, ignore: ignored, onlyFiles: true, unique: true, dot: true })
+    ).sort()
+    counts[kind] = files.length
+    if (!files.length && kind === 'eslint') throw new Error('ESLint scope matched no files')
+    return files
+  }
+  const add = (toolName, file, diagnostic, source) => {
+    const { rule, message, line = 1, column = 1, fatal = false } = diagnostic
+    const lines = normalized(source).split('\n')
+    issues.push({
+      tool: toolName,
+      file: portable(file),
+      rule,
+      message,
+      line,
+      column,
+      fatal,
+      source: lines.slice(line - 1, diagnostic.endLine ?? line).join('\n'),
+    })
+  }
+  if (tool === 'all' || tool === 'eslint') {
+    const files = await filesFor('eslint')
+    const eslint = new ESLint({ cwd, fix, errorOnUnmatchedPattern: true })
+    const results = await eslint.lintFiles(files)
+    if (fix) await ESLint.outputFixes(results)
+    for (const result of results) {
+      const file = portable(relative(cwd, result.filePath))
+      const source = result.output ?? (await readFile(result.filePath, 'utf8'))
+      for (const item of result.messages)
+        add(
+          'eslint',
+          file,
+          {
+            ...item,
+            rule: item.ruleId ?? 'parser',
+            fatal: item.fatal || !item.ruleId,
+          },
+          source,
+        )
+    }
+  }
+  if (tool === 'all' || tool === 'style') {
+    for (const file of await filesFor('style')) {
+      const result = await stylelint.lint({
+        cwd,
+        files: resolve(cwd, file),
+        configFile: resolve(cwd, 'stylelint.config.mjs'),
+        fix,
+      })
+      for (const entry of result.results) {
+        if (entry.invalidOptionWarnings.length || entry.parseErrors.length) {
+          throw new Error(
+            `Stylelint configuration/parse failure: ${file}: ${JSON.stringify([...entry.invalidOptionWarnings, ...entry.parseErrors])}`,
+          )
+        }
+        const source = await readFile(resolve(cwd, file), 'utf8')
+        for (const item of entry.warnings)
+          add(
+            'style',
+            file,
+            {
+              ...item,
+              message: item.text,
+              fatal: ['CssSyntaxError', 'syntax-string'].includes(item.rule),
+            },
+            source,
+          )
+      }
+    }
+  }
+  if (tool === 'all' || tool === 'format') {
+    for (const file of await filesFor('format')) {
+      const filePath = resolve(cwd, file)
+      const info = await prettier.getFileInfo(filePath, {
+        ignorePath: resolve(cwd, '.prettierignore'),
+      })
+      if (info.ignored || !info.inferredParser) continue
+      const options = { ...(await prettier.resolveConfig(filePath)), filepath: filePath }
+      const source = await readFile(filePath, 'utf8')
+      // Git may materialize the same tracked file as CRLF on Windows and LF on Linux.
+      // Line-ending policy belongs to Git; the format ratchet must fingerprint semantic
+      // formatting debt consistently on both hosts.
+      if (!(await prettier.check(normalized(source), options))) {
+        if (fix) await writeFile(filePath, await prettier.format(source, options))
+        else
+          issues.push({
+            tool: 'format',
+            file,
+            rule: 'prettier',
+            message: 'File differs from local Prettier configuration',
+            source: hash(source),
+          })
+      }
+    }
+  }
+  const fatal = issues.filter((issue) => issue.fatal)
+  if (fatal.length) throw new Error(`Unbaselinable lint failure: ${JSON.stringify(fatal)}`)
+  return { counts, issues, entries: collectEntries(issues) }
+}
+
+export async function runQuality({
+  cwd = process.cwd(),
+  mode = 'check',
+  tool = 'all',
+  fix = false,
+} = {}) {
+  const config = (await import(pathToFileURL(resolve(cwd, 'quality.config.mjs')).href)).default
+  const report = await scan({ cwd, config, tool, fix })
+  console.log(JSON.stringify({ scanned: report.counts, issues: report.issues.length }))
+  if (mode === 'report') return report
+  if (mode === 'check') {
+    for (const issue of report.issues)
+      console.error(`${issue.file}:${issue.line ?? 1} ${issue.rule}: ${issue.message}`)
+    return { ...report, passed: !report.issues.length }
+  }
+  const baselinePath = resolve(cwd, 'quality-baseline.json')
+  if (mode === 'init') {
+    try {
+      await readFile(baselinePath, 'utf8')
+      throw new Error('Quality baseline already exists; only prune is allowed after bootstrap')
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error
+    }
+    if (checkGitBaseline(cwd, baselinePath)) {
+      throw new Error('Quality baseline exists in Git history; restore it and prune instead')
+    }
+    await writeFile(
+      baselinePath,
+      `${JSON.stringify({ schemaVersion: 1, entries: report.entries }, null, 2)}\n`,
+      { flag: 'wx' },
+    )
+    console.log(`Bootstrapped ${Object.keys(report.entries).length} historical fingerprints`)
+    return { ...report, passed: true }
+  }
+  const baseline = validateBaseline(JSON.parse(await readFile(baselinePath, 'utf8')))
+  const previous = checkGitBaseline(cwd, baselinePath)
+  if (previous) assertBaselineDoesNotGrow(baseline, previous)
+  if (mode === 'prune') {
+    baseline.entries = pruneBaseline(report.entries, baseline.entries)
+    await writeFile(baselinePath, `${JSON.stringify(baseline, null, 2)}\n`)
+  }
+  const { added, removed } = compareBaseline(report.entries, baseline.entries)
+  for (const [, entry] of added) console.error(`NEW ${entry.file}: ${entry.rule}: ${entry.message}`)
+  if (removed.length)
+    console.error(`${removed.length} stale baseline entries; run lint:baseline:prune`)
+  console.log(
+    `Historical issues: ${report.issues.length}; new fingerprints: ${added.length}; retired fingerprints: ${removed.length}`,
+  )
+  return { ...report, passed: !added.length && !removed.length }
+}

package/stylelint.mjs

@@ -0,0 +1,83 @@
+/** Explicit semantic rules: no standard/style formatting preset. */
+export function styleLintConfig({ tailwind = false } = {}) {
+  return {
+    ignoreFiles: ['**/node_modules/**', '**/dist/**', '**/coverage/**'],
+    rules: {
+      'annotation-no-unknown': true,
+      'at-rule-no-unknown': [
+        true,
+        {
+          ignoreAtRules: tailwind
+            ? [
+                'theme',
+                'source',
+                'utility',
+                'variant',
+                'custom-variant',
+                'apply',
+                'reference',
+                'config',
+                'plugin',
+                'tailwind',
+              ]
+            : [],
+        },
+      ],
+      'block-no-empty': true,
+      'color-no-invalid-hex': true,
+      'comment-no-empty': true,
+      'custom-property-no-missing-var-function': true,
+      'declaration-block-no-duplicate-properties': [
+        true,
+        { ignore: ['consecutive-duplicates-with-different-syntaxes'] },
+      ],
+      'declaration-block-no-shorthand-property-overrides': true,
+      'font-family-no-duplicate-names': true,
+      'font-family-no-missing-generic-family-keyword': true,
+      'function-no-unknown': [
+        true,
+        { ignoreFunctions: tailwind ? ['--alpha', '--spacing', 'theme'] : [] },
+      ],
+      'keyframe-block-no-duplicate-selectors': true,
+      'keyframe-declaration-no-important': true,
+      'media-feature-name-no-unknown': true,
+      'no-descending-specificity': null,
+      'no-duplicate-at-import-rules': true,
+      'no-duplicate-selectors': true,
+      'no-invalid-double-slash-comments': true,
+      'property-no-unknown': true,
+      'selector-pseudo-class-no-unknown': [
+        true,
+        { ignorePseudoClasses: ['deep', 'global', 'slotted'] },
+      ],
+      'selector-pseudo-element-no-unknown': [
+        true,
+        { ignorePseudoElements: ['v-deep', 'v-global', 'v-slotted'] },
+      ],
+      'selector-type-no-unknown': [true, { ignore: ['custom-elements'] }],
+      'string-no-newline': true,
+      'unit-no-unknown': true,
+    },
+    overrides: [
+      {
+        files: ['**/*.vue'],
+        customSyntax: 'postcss-html',
+        rules: {
+          // Vue SFC may embed Less; file globs cannot distinguish <style lang="less">.
+          'function-no-unknown': null,
+          'no-invalid-double-slash-comments': null,
+        },
+      },
+      {
+        files: ['**/*.less'],
+        customSyntax: 'postcss-less',
+        // Less extends CSS with variables, functions and mixins.
+        rules: {
+          'at-rule-no-unknown': null,
+          'function-no-unknown': null,
+          'no-invalid-double-slash-comments': null,
+        },
+      },
+    ],
+  }
+}