@starpak/lang 0.0.0-stage → 0.1.2

package/src/checker.ts

@@ -0,0 +1,554 @@
+/**
+ * Spak Lang - Static checker (M2)
+ *
+ * Walks the AST and reports diagnostics from `diagnostics.ts`.
+ * Types are erased after checking; nothing here affects code generation.
+ */
+
+import type {
+  Assign,
+  Block,
+  ClassDecl,
+  Expr,
+  FnDecl,
+  MatchStmt,
+  Pattern,
+  Program,
+  Statement,
+  TablePattern,
+  TypeAliasDecl,
+  TypeAnn,
+  VarDecl,
+} from './ast'
+import { CODES, error, warning, type Diagnostic } from './diagnostics'
+import {
+  ANY, BOOLEAN, NIL, NUMBER, STRING,
+  fromTypeAnn, isAssignable, print, union, withoutNil,
+  type Type,
+} from './types'
+
+export interface CheckOptions {
+  /** Report implicit `any` as an error instead of a warning. */
+  strictAny?: boolean
+  /** Emit W001 for unused locals. Default true. */
+  reportUnused?: boolean
+}
+
+interface Scope {
+  parent?: Scope
+  vars: Map<string, { type: Type, decl: VarDecl | FnDecl | ClassDecl, used: boolean }>
+}
+
+interface FnContext {
+  returnType: Type | null
+  name: string
+}
+
+const GLOBAL_SCOPE: Scope = { vars: new Map() }
+
+function newScope(parent: Scope): Scope {
+  return { parent, vars: new Map() }
+}
+
+function lookup(scope: Scope, name: string) {
+  let current: Scope | undefined = scope
+  while (current) {
+    const found = current.vars.get(name)
+    if (found) return found
+    current = current.parent
+  }
+  return undefined
+}
+
+function declare(scope: Scope, name: string, type: Type, decl: VarDecl | FnDecl | ClassDecl) {
+  scope.vars.set(name, { type, decl, used: false })
+}
+
+export function check(program: Program, options: CheckOptions = {}): Diagnostic[] {
+  const diagnostics: Diagnostic[] = []
+  const aliases = new Map<string, Type>()
+
+  // Pass 1: type aliases, so later annotations can resolve them.
+  for (const statement of program.body) {
+    const decl = unwrapExport(statement)
+    if (decl.kind === 'TypeAliasDecl') aliases.set(decl.name, fromTypeAnn(decl.type))
+  }
+  for (const [name, type] of aliases) {
+    if (type.kind === 'named' && type.name === name) {
+      diagnostics.push(error('E006', `类型别名「${name}」循环引用`, program.loc))
+    }
+  }
+
+  const resolveAnn = (ann: TypeAnn): Type => {
+    const type = fromTypeAnn(ann)
+    return resolveNamed(type, aliases)
+  }
+
+  const push = (diag: Diagnostic) => diagnostics.push(diag)
+
+  const checkCall = (
+    node: { loc: { line: number, column: number } },
+    argNodes: Expr[],
+    callee: Type,
+    args: Type[],
+    offset = 0,
+  ): Type => {
+    if (callee.kind !== 'fn') return ANY
+    const hasSpread = argNodes.some(node => node.kind === 'Spread')
+    if (!hasSpread && args.length !== callee.params.length) {
+      push(error('E004', `需要 ${callee.params.length} 个参数，实际 ${args.length} 个`, node.loc))
+      return callee.returns
+    }
+    if (hasSpread) return callee.returns
+    callee.params.forEach((param, index) => {
+      if (!isAssignable(param, args[index])) {
+        const at = argNodes[index - offset]?.loc ?? node.loc
+        push(error('E001', `第 ${index + 1} 个参数应为 ${print(param)}，得到 ${print(args[index])}`, at))
+      }
+    })
+    return callee.returns
+  }
+
+  const checkTypeKnown = (ann: TypeAnn, loc = ann.loc) => {
+    if (ann.kind === 'named') {
+      const known = ['any', 'nil', 'number', 'string', 'boolean', 'bool']
+      if (!known.includes(ann.name) && !aliases.has(ann.name)) {
+        push(error('E003', `未知类型名「${ann.name}」`, loc))
+      }
+      return
+    }
+    if (ann.kind === 'array') checkTypeKnown(ann.element, ann.element.loc)
+    if (ann.kind === 'dict') {
+      checkTypeKnown(ann.key, ann.key.loc)
+      checkTypeKnown(ann.value, ann.value.loc)
+    }
+    if (ann.kind === 'record') for (const field of ann.fields) checkTypeKnown(field.type, field.type.loc)
+    if (ann.kind === 'union') for (const item of ann.types) checkTypeKnown(item, item.loc)
+    if (ann.kind === 'fn') {
+      for (const item of ann.params) checkTypeKnown(item, item.loc)
+      checkTypeKnown(ann.returns, ann.returns.loc)
+    }
+    if (ann.kind === 'optional') checkTypeKnown(ann.type, ann.type.loc)
+  }
+
+  const checkExpr = (expr: Expr, scope: Scope, fn: FnContext | null, narrow?: Map<string, Type>): Type => {
+    switch (expr.kind) {
+      case 'NumberLit':
+        return NUMBER
+      case 'StringLit':
+        if (expr.parts) for (const part of expr.parts) if (typeof part !== 'string') checkExpr(part, scope, fn, narrow)
+        return STRING
+      case 'BoolLit':
+        return BOOLEAN
+      case 'NilLit':
+        return NIL
+      case 'Ident': {
+        if (narrow?.has(expr.name)) return narrow.get(expr.name)!
+        const found = lookup(scope, expr.name)
+        if (!found) return ANY
+        found.used = true
+        return found.type
+      }
+      case 'SelfExpr':
+        return ANY
+      case 'Member': {
+        const object = checkExpr(expr.object, scope, fn, narrow)
+        if (object.kind === 'record') {
+          const field = object.fields.get(expr.property)
+          if (!field) {
+            push(error('E007', `记录类型没有字段「${expr.property}」`, expr.loc))
+            return ANY
+          }
+          return expr.optional ? union([field, NIL]) : field
+        }
+        return expr.optional ? ANY : ANY
+      }
+      case 'Index': {
+        const object = checkExpr(expr.object, scope, fn, narrow)
+        const index = checkExpr(expr.index, scope, fn, narrow)
+        if (object.kind === 'array') {
+          if (expr.isRange) return object
+          if (!isAssignable(NUMBER, index)) {
+            push(error('E001', `数组下标应为 number，得到 ${print(index)}`, expr.index.loc))
+          }
+          return object.element
+        }
+        if (object.kind === 'dict') {
+          if (!isAssignable(object.key, index)) {
+            push(error('E001', `字典键应为 ${print(object.key)}，得到 ${print(index)}`, expr.index.loc))
+          }
+          return object.value
+        }
+        return ANY
+      }
+      case 'Call': {
+        const callee = checkExpr(expr.callee, scope, fn, narrow)
+        const args = expr.args.map(arg => checkExpr(arg, scope, fn, narrow))
+        return checkCall(expr, expr.args, callee, args)
+      }
+      case 'Binary': {
+        if (expr.op === '|>') {
+          const left = checkExpr(expr.left, scope, fn, narrow)
+          if (expr.right.kind !== 'Call') {
+            checkExpr(expr.right, scope, fn, narrow)
+            return ANY
+          }
+          const callee = checkExpr(expr.right.callee, scope, fn, narrow)
+          const args = [left, ...expr.right.args.map(arg => checkExpr(arg, scope, fn, narrow))]
+          return checkCall(expr.right, expr.right.args, callee, args, 1)
+        }
+        const left = checkExpr(expr.left, scope, fn, narrow)
+        const right = checkExpr(expr.right, scope, fn, narrow)
+        return checkBinary(expr.op, left, right, expr, push)
+      }
+      case 'Unary': {
+        const argument = checkExpr(expr.argument, scope, fn, narrow)
+        if (expr.op === '-' && !isNumeric(argument)) {
+          push(error('E001', `一元 - 只能用于 number，得到 ${print(argument)}`, expr.argument.loc))
+        }
+        if (expr.op === 'not') return BOOLEAN
+        if (expr.op === '#') return NUMBER
+        return argument
+      }
+      case 'Table': {
+        const values: Type[] = []
+        const fields = new Map<string, Type>()
+        let positional = true
+        for (const field of expr.fields) {
+          const value = checkExpr(field.value, scope, fn, narrow)
+          values.push(value)
+          if (field.key?.kind === 'Ident') {
+            positional = false
+            fields.set(field.key.name, value)
+          }
+        }
+        if (positional) {
+          return { kind: 'array', element: values.length ? union(values) : ANY }
+        }
+        return { kind: 'record', fields }
+      }
+      case 'FunctionExpr': {
+        const inner = newScope(scope)
+        for (const param of expr.params) {
+          const type = param.type ? resolveAnn(param.type) : ANY
+          if (param.type) checkTypeKnown(param.type)
+          declare(inner, param.name, type, { kind: 'FnDecl' } as FnDecl)
+        }
+        const returns = expr.exprBody
+          ? checkExpr(expr.exprBody, inner, fn, narrow)
+          : checkBlock(expr.body, inner, { returnType: null, name: 'fn' }, narrow)
+        return { kind: 'fn', params: expr.params.map(p => (p.type ? resolveAnn(p.type) : ANY)), returns }
+      }
+      case 'Range': {
+        checkExpr(expr.from, scope, fn, narrow)
+        checkExpr(expr.to, scope, fn, narrow)
+        return ANY
+      }
+      case 'AwaitExpr':
+        return checkExpr(expr.argument, scope, fn, narrow)
+      case 'Spread':
+        return expr.argument ? checkExpr(expr.argument, scope, fn, narrow) : ANY
+      default:
+        return ANY
+    }
+  }
+
+  const checkBlock = (block: Block | undefined, scope: Scope, fn: FnContext | null, narrow?: Map<string, Type>): Type => {
+    if (!block) return NIL
+    const returns: Type[] = []
+    for (const statement of block.body) {
+      const type = checkStatement(statement, scope, fn, narrow)
+      if (statement.kind === 'ReturnStmt') returns.push(type)
+    }
+    return returns.length ? union(returns) : NIL
+  }
+
+  const bindPattern = (pattern: Pattern, scope: Scope) => {
+    if (pattern.kind === 'TablePattern') {
+      for (const entry of pattern.entries) {
+        declare(scope, entry.target ?? entry.key, ANY, { kind: 'VarDecl' } as VarDecl)
+      }
+      return
+    }
+    for (const name of pattern.elements) {
+      declare(scope, name, ANY, { kind: 'VarDecl' } as VarDecl)
+    }
+  }
+
+  const checkAssign = (statement: Assign, scope: Scope, fn: FnContext | null, narrow?: Map<string, Type>) => {
+    const values = statement.values.map(value => checkExpr(value, scope, fn, narrow))
+    statement.targets.forEach((target, index) => {
+      const valueType = values[index] ?? ANY
+      if (isPattern(target)) {
+        bindPattern(target, scope)
+        return
+      }
+      if (target.kind === 'Ident') {
+        const found = lookup(scope, target.name)
+        if (found) {
+          if (!isAssignable(found.type, valueType)) {
+            push(error('E001', `变量「${target.name}」是 ${print(found.type)}，不能赋 ${print(valueType)}`, target.loc))
+          }
+        } else {
+          declare(scope, target.name, valueType, { kind: 'VarDecl' } as VarDecl)
+        }
+        return
+      }
+      checkExpr(target, scope, fn, narrow)
+    })
+  }
+
+  const checkVarDecl = (statement: VarDecl, scope: Scope, narrow?: Map<string, Type>) => {
+    statement.names.forEach((entry, index) => {
+      if (entry.type) checkTypeKnown(entry.type)
+      const annotated = entry.type ? resolveAnn(entry.type) : null
+      const value = statement.values[index]
+      if (value) {
+        const valueType = checkExpr(value, scope, null, narrow)
+        if (annotated && !isAssignable(annotated, valueType)) {
+          push(error('E001', `「${entry.name}」标注为 ${print(annotated)}，赋值是 ${print(valueType)}`, value.loc))
+        }
+        declare(scope, entry.name, annotated ?? valueType, statement)
+        return
+      }
+      if (annotated) {
+        declare(scope, entry.name, annotated, statement)
+        return
+      }
+      declare(scope, entry.name, ANY, statement)
+      if (options.strictAny) {
+        push(error('W003', `「${entry.name}」是隐式 any`, statement.loc))
+      }
+    })
+  }
+
+  const checkFn = (statement: FnDecl, scope: Scope) => {
+    for (const param of statement.params) if (param.type) checkTypeKnown(param.type)
+    const params = statement.params.map(param => (param.type ? resolveAnn(param.type) : ANY))
+    const declaredReturn = statement.returnType ? resolveAnn(statement.returnType) : null
+    if (statement.returnType) checkTypeKnown(statement.returnType)
+
+    const inner = newScope(scope)
+    statement.params.forEach((param, index) => declare(inner, param.name, params[index], statement))
+
+    const context: FnContext = { returnType: declaredReturn, name: statement.name }
+    if (statement.exprBody) {
+      const actual = checkExpr(statement.exprBody, inner, context)
+      if (declaredReturn && !isAssignable(declaredReturn, actual)) {
+        push(error('E005', `「${statement.name}」应返回 ${print(declaredReturn)}，实际 ${print(actual)}`, statement.exprBody.loc))
+      }
+      return
+    }
+
+    const actual = checkBlock(statement.body, inner, context)
+    if (declaredReturn && !isAssignable(declaredReturn, actual) && statement.body?.body.some(s => s.kind === 'ReturnStmt')) {
+      push(error('E005', `「${statement.name}」应返回 ${print(declaredReturn)}，实际 ${print(actual)}`, statement.loc))
+    }
+  }
+
+  const checkClass = (statement: ClassDecl, scope: Scope) => {
+    const inner = newScope(scope)
+    for (const member of statement.members) {
+      if (member.kind === 'FnDecl') {
+        const params = member.params.map(param => (param.type ? resolveAnn(param.type) : ANY))
+        declare(inner, member.name, { kind: 'fn', params, returns: member.returnType ? resolveAnn(member.returnType) : ANY }, member)
+        checkFn(member, inner)
+      } else {
+        checkVarDecl(member, inner)
+      }
+    }
+    declare(scope, statement.name, { kind: 'named', name: statement.name }, statement)
+  }
+
+  const checkMatch = (statement: MatchStmt, scope: Scope, fn: FnContext | null) => {
+    checkExpr(statement.subject, scope, fn)
+    for (const arm of statement.arms) {
+      const inner = newScope(scope)
+      for (const pattern of arm.patterns) checkExpr(pattern, inner, fn)
+      if (arm.guard) checkExpr(arm.guard, inner, fn)
+      checkBlock(arm.body, inner, fn)
+    }
+    if (statement.elseBody) checkBlock(statement.elseBody, scope, fn)
+  }
+
+  const checkStatement = (statement: Statement, scope: Scope, fn: FnContext | null, narrow?: Map<string, Type>): Type => {
+    switch (statement.kind) {
+      case 'VarDecl':
+        checkVarDecl(statement, scope, narrow)
+        return NIL
+      case 'Assign':
+        checkAssign(statement, scope, fn, narrow)
+        return NIL
+      case 'FnDecl':
+        checkFn(statement, scope)
+        declare(scope, statement.name, { kind: 'fn', params: statement.params.map(p => (p.type ? resolveAnn(p.type) : ANY)), returns: statement.returnType ? resolveAnn(statement.returnType) : ANY }, statement)
+        return NIL
+      case 'ClassDecl':
+        checkClass(statement, scope)
+        return NIL
+      case 'IfStmt': {
+        const condType = checkExpr(statement.cond, scope, fn, narrow)
+        const narrowed = narrowCond(statement.cond, condType, scope, narrow, true)
+        checkBlock(statement.then, newScope(scope), fn, narrowed)
+        for (const branch of statement.elifs) {
+          checkExpr(branch.cond, scope, fn, narrow)
+          checkBlock(branch.body, newScope(scope), fn, narrowed)
+        }
+        if (statement.else) checkBlock(statement.else, newScope(scope), fn, narrow)
+        return NIL
+      }
+      case 'UnlessStmt':
+        checkExpr(statement.cond, scope, fn, narrow)
+        checkBlock(statement.body, newScope(scope), fn, narrow)
+        return NIL
+      case 'WhileStmt':
+        checkExpr(statement.cond, scope, fn, narrow)
+        checkBlock(statement.body, newScope(scope), fn, narrow)
+        return NIL
+      case 'RepeatStmt':
+        checkBlock(statement.body, newScope(scope), fn, narrow)
+        checkExpr(statement.cond, scope, fn, narrow)
+        return NIL
+      case 'ForNumeric': {
+        const inner = newScope(scope)
+        declare(inner, statement.varName, NUMBER, { kind: 'VarDecl' } as VarDecl)
+        checkExpr(statement.from, scope, fn, narrow)
+        checkExpr(statement.to, scope, fn, narrow)
+        if (statement.step) checkExpr(statement.step, scope, fn, narrow)
+        checkBlock(statement.body, inner, fn, narrow)
+        return NIL
+      }
+      case 'ForIn': {
+        const inner = newScope(scope)
+        const iter = checkExpr(statement.iter, scope, fn, narrow)
+        const element = iter.kind === 'array' ? iter.element : ANY
+        statement.vars.forEach((name, index) => declare(inner, name, index === 0 ? element : ANY, { kind: 'VarDecl' } as VarDecl))
+        checkBlock(statement.body, inner, fn, narrow)
+        return NIL
+      }
+      case 'ReturnStmt': {
+        const values = statement.values.map(value => checkExpr(value, scope, fn, narrow))
+        const type = values.length === 0 ? NIL : values.length === 1 ? values[0] : union(values)
+        if (fn?.returnType && !isAssignable(fn.returnType, type)) {
+          push(error('E005', `「${fn.name}」应返回 ${print(fn.returnType)}，实际 ${print(type)}`, statement.loc))
+        }
+        return type
+      }
+      case 'ThrowStmt':
+      case 'SpawnStmt':
+        checkExpr(statement.value, scope, fn, narrow)
+        return NIL
+      case 'MatchStmt':
+        checkMatch(statement, scope, fn)
+        return NIL
+      case 'TryStmt': {
+        checkBlock(statement.body, newScope(scope), fn, narrow)
+        const catchScope = newScope(scope)
+        if (statement.catchVar) declare(catchScope, statement.catchVar, statement.catchType ? resolveAnn(statement.catchType) : ANY, { kind: 'VarDecl' } as VarDecl)
+        checkBlock(statement.catchBody, catchScope, fn, narrow)
+        checkBlock(statement.finallyBody, newScope(scope), fn, narrow)
+        return NIL
+      }
+      case 'ExportDecl':
+        return checkStatement(statement.declaration, scope, fn, narrow)
+      case 'ExportDefault':
+        checkExpr(statement.expr, scope, fn, narrow)
+        return NIL
+      case 'TypeAliasDecl':
+        checkTypeKnown(statement.type)
+        return NIL
+      case 'ImportDecl':
+        for (const clause of statement.clauses) declare(scope, clause.alias ?? clause.name, ANY, { kind: 'VarDecl' } as VarDecl)
+        return NIL
+      case 'ExprStmt':
+        checkExpr(statement.expr, scope, fn, narrow)
+        return NIL
+      case 'BreakStmt':
+      case 'ContinueStmt':
+        return NIL
+      default:
+        return NIL
+    }
+  }
+
+  const block = newScope(GLOBAL_SCOPE)
+  for (const statement of program.body) checkStatement(statement, block, null)
+
+  if (options.reportUnused !== false) {
+    const walkUnused = (scope: Scope) => {
+      for (const [name, entry] of scope.vars) {
+        if (!entry.used && !name.startsWith('_') && entry.decl.kind !== 'FnDecl') {
+          diagnostics.push(warning('W001', `声明「${name}」未使用`, entry.decl.loc))
+        }
+      }
+    }
+    walkUnused(block)
+  }
+
+  return diagnostics
+}
+
+function unwrapExport(statement: Statement): Statement {
+  return statement.kind === 'ExportDecl' ? statement.declaration : statement
+}
+
+function isPattern(target: Expr | Pattern): target is Pattern {
+  return target.kind === 'TablePattern' || target.kind === 'ArrayPattern'
+}
+
+function isNumeric(type: Type): boolean {
+  return type.kind === 'any' || (type.kind === 'prim' && type.name === 'number')
+}
+
+function checkBinary(op: string, left: Type, right: Type, expr: Expr, push: (diag: Diagnostic) => void): Type {
+  if (op === 'and' || op === 'or') return union([left, right])
+  if (op === '==' || op === '~=' || op === '<' || op === '<=' || op === '>' || op === '>=') return BOOLEAN
+  if (op === '..') return STRING
+  if (op === '|>') return ANY
+  if (op === '??') return union([withoutNil(left), right])
+  if (op === '+' && (left.kind === 'prim' && left.name === 'string' || right.kind === 'prim' && right.name === 'string')) {
+    if (!(left.kind === 'prim' && left.name === 'string') || !(right.kind === 'prim' && right.name === 'string')) {
+      push(error('E001', `${print(left)} 与 ${print(right)} 不能相加`, expr.loc, '用 tostring(x) 或 f"{x}" 转成字符串'))
+    }
+    return STRING
+  }
+  if (!isNumeric(left) || !isNumeric(right)) {
+    push(error('E001', `${print(left)} 与 ${print(right)} 不能做 ${op} 运算`, expr.loc))
+    return ANY
+  }
+  return NUMBER
+}
+
+function narrowCond(
+  cond: Expr,
+  condType: Type,
+  scope: Scope,
+  narrow: Map<string, Type> | undefined,
+  positive: boolean,
+): Map<string, Type> | undefined {
+  if (positive && cond.kind === 'Ident') {
+    const next = new Map(narrow ?? [])
+    next.set(cond.name, withoutNil(lookup(scope, cond.name)?.type ?? condType))
+    return next
+  }
+  return narrow
+}
+
+function resolveNamed(type: Type, aliases: Map<string, Type>): Type {
+  if (type.kind === 'named') {
+    const found = aliases.get(type.name)
+    if (found) return { kind: 'named', name: type.name, resolved: found }
+  }
+  if (type.kind === 'array') return { kind: 'array', element: resolveNamed(type.element, aliases) }
+  if (type.kind === 'dict') return { kind: 'dict', key: resolveNamed(type.key, aliases), value: resolveNamed(type.value, aliases) }
+  if (type.kind === 'record') {
+    const fields = new Map<string, Type>()
+    for (const [name, value] of type.fields) fields.set(name, resolveNamed(value, aliases))
+    return { kind: 'record', fields }
+  }
+  if (type.kind === 'fn') return { kind: 'fn', params: type.params.map(p => resolveNamed(p, aliases)), returns: resolveNamed(type.returns, aliases) }
+  if (type.kind === 'union') return union(type.types.map(item => resolveNamed(item, aliases)))
+  return type
+}
+
+export { CODES }

package/src/diagnostics.ts

@@ -0,0 +1,100 @@
+/**
+ * Spak Lang - Diagnostics (M2)
+ *
+ * Codes and formatting follow `docs/syntax/typecheck.md` §4.
+ */
+
+import type { Position } from './ast'
+
+export type Severity = 'error' | 'warning'
+
+export const CODES = {
+  E001: '类型不匹配',
+  E002: '可能为 nil 的值未收窄',
+  E003: '未知类型名',
+  E004: '参数数量或类型不符',
+  E005: '返回值与注解不符',
+  E006: '重复声明或类型别名循环',
+  E007: '访问不存在的字段',
+  W001: '声明未使用',
+  W002: '分支不可达',
+  W003: '隐式 any',
+} as const
+
+export type DiagnosticCode = keyof typeof CODES
+
+export interface Diagnostic {
+  code: DiagnosticCode
+  severity: Severity
+  message: string
+  loc: Position
+  /** Optional end column on the same line, for caret width. */
+  endColumn?: number
+  hint?: string
+}
+
+export function error(code: DiagnosticCode, message: string, loc: Position, hint?: string): Diagnostic {
+  return { code, severity: 'error', message, loc, hint }
+}
+
+export function warning(code: DiagnosticCode, message: string, loc: Position, hint?: string): Diagnostic {
+  return { code, severity: 'warning', message, loc, hint }
+}
+
+export interface FormatOptions {
+  /** File name shown in the header. */
+  file?: string
+  /** Source text, needed to render the offending line. */
+  source?: string
+  /** Use ANSI colors (default: auto-detect TTY). */
+  color?: boolean
+}
+
+const COLOR = {
+  reset: '\u001b[0m',
+  red: '\u001b[31m',
+  yellow: '\u001b[33m',
+  dim: '\u001b[2m',
+  cyan: '\u001b[36m',
+}
+
+function paint(text: string, code: string, enabled: boolean): string {
+  return enabled ? `${code}${text}${COLOR.reset}` : text
+}
+
+/** Render one diagnostic in the compiler-style layout. */
+export function formatDiagnostic(diag: Diagnostic, options: FormatOptions = {}): string {
+  const color = options.color ?? Boolean(process.stdout.isTTY)
+  const file = options.file ?? '<input>'
+  const label = diag.severity === 'error'
+    ? paint('error', COLOR.red, color)
+    : paint('warning', COLOR.yellow, color)
+  const head = `${label}${paint(`[${diag.code}]`, COLOR.dim, color)} ${diag.message}`
+  const where = `  ${paint('-->', COLOR.cyan, color)} ${file}:${diag.loc.line}:${diag.loc.column}`
+  const lines = [head, where]
+
+  if (options.source) {
+    const sourceLine = options.source.split(/\r?\n/)[diag.loc.line - 1]
+    if (sourceLine !== undefined) {
+      const number = String(diag.loc.line)
+      const gutter = ' '.repeat(number.length + 2)
+      const width = Math.max(1, (diag.endColumn ?? diag.loc.column + 1) - diag.loc.column)
+      lines.push(`${gutter}${paint('|', COLOR.dim, color)}`)
+      lines.push(` ${paint(number, COLOR.dim, color)} ${paint('|', COLOR.dim, color)} ${sourceLine}`)
+      lines.push(`${gutter}${paint('|', COLOR.dim, color)} ${' '.repeat(diag.loc.column - 1)}${paint('^'.repeat(width), diag.severity === 'error' ? COLOR.red : COLOR.yellow, color)}`)
+    }
+  }
+
+  if (diag.hint) lines.push(`   = 提示：${diag.hint}`)
+  return lines.join('\n')
+}
+
+export function countBySeverity(diagnostics: Diagnostic[]): { errors: number, warnings: number } {
+  let errors = 0
+  let warnings = 0
+  for (const diag of diagnostics) {
+    if (diag.severity === 'error') errors++
+    else warnings++
+  }
+  return { errors, warnings }
+}