《游戏引擎实现原理》11.3 着色器调试与错误定位（getCompilationInfo）

// file: src/render/shader/diagnostics.ts
// tier: L1
// verify: npx vitest run src/render/shader/diagnostics.test.ts
//
// helio 渲染卷：把 getCompilationInfo() 的原始诊断映射回「原始文件:行:列」。
// 展开 include 之后，报错行号指向的是拼接后的大文件；这里用 11.1 产出的行映射
// 把它还原成用户真正编辑的那个文件，编辑器里才能一键跳转。

import type { LineMapping } from './include-resolver.ts';

export type DiagnosticType = 'error' | 'warning' | 'info';

/** getCompilationInfo() 返回的一条原始消息（字段名与 WebGPU 一致）。 */
export interface RawDiagnostic {
  readonly type: string;
  readonly message: string;
  readonly lineNum: number;
  readonly linePos: number;
  readonly offset: number;
  readonly length: number;
}

/** 映射回源文件之后的诊断。 */
export interface LocatedDiagnostic {
  readonly severity: DiagnosticType;
  readonly file: string;
  readonly line: number;
  readonly column: number;
  readonly message: string;
}

function asType(t: string): DiagnosticType {
  return t === 'error' || t === 'warning' ? t : 'info';
}

/** 把一条原始诊断按行映射还原到源文件位置。 */
export function mapDiagnostic(d: RawDiagnostic, lines: readonly LineMapping[]): LocatedDiagnostic {
  const lm = lines[d.lineNum - 1];
  return {
    severity: asType(d.type),
    file: lm ? lm.file : '<generated>',
    line: lm ? lm.inLine : d.lineNum,
    column: d.linePos,
    message: d.message,
  };
}

/** 单行文本形式：`error: shaders/lib/color.wgsl:3:10: 消息`。 */
export function formatDiagnostic(d: LocatedDiagnostic): string {
  return `${d.severity}: ${d.file}:${d.line}:${d.column}: ${d.message}`;
}

/** 按严重级别计数。 */
export function summarize(messages: readonly RawDiagnostic[]): {
  errors: number; warnings: number; infos: number;
} {
  let errors = 0, warnings = 0, infos = 0;
  for (const m of messages) {
    const t = asType(m.type);
    if (t === 'error') errors++;
    else if (t === 'warning') warnings++;
    else infos++;
  }
  return { errors, warnings, infos };
}

/** 只要有 error 就返回 true；供编译流程决定是否中止。 */
export function hasErrors(messages: readonly RawDiagnostic[]): boolean {
  return summarize(messages).errors > 0;
}

// file: shaders/lib/tonemap.wgsl
// tier: L2
// verify: node tools/run-l2.mjs src/render/shader/diagnostics-l2.ts

// 色调映射：Reinhard，把 HDR 值压回 [0,1)。
fn reinhard(c: vec3<f32>) -> vec3<f32> {
  return c / (c + vec3<f32>(1.0));
}

// snippet: 故意写错的库文件（少传一个参数）
fn srgb_to_linear(c: vec3<f32>) -> vec3<f32> {
  return pow(c);
}

// file: src/render/shader/diagnostics-l2.ts
// tier: L2
// verify: node tools/run-l2.mjs src/render/shader/diagnostics-l2.ts
//
// 11.3 的 L2 验收：真跑 getCompilationInfo()。
// 一份好源码要求 0 error；一份在「被 include 的库文件」里故意写错的源码，
// 拿到带行号列号的诊断，再用 11.1 的行映射还原回原始文件:行:列。

import { resolveIncludes } from './include-resolver.ts';
import { formatDiagnostic, hasErrors, mapDiagnostic, summarize, type RawDiagnostic } from './diagnostics.ts';

export interface L2Check { readonly name: string; readonly ok: boolean; readonly detail: string }
export interface L2Result {
  readonly checks: L2Check[];
  readonly data: Record<string, unknown>;
}

const GOOD_COLOR = `// shaders/lib/color.wgsl
fn srgb_to_linear(c: vec3<f32>) -> vec3<f32> {
  return pow(c, vec3<f32>(2.2));
}`;

const BAD_COLOR = `// shaders/lib/color.wgsl
fn srgb_to_linear(c: vec3<f32>) -> vec3<f32> {
  return pow(c);
}`;

const ROOT = `// shaders/island.wgsl
#include "lib/color.wgsl"
#include "lib/tonemap.wgsl"

@fragment
fn fs() -> @location(0) vec4<f32> {
  return vec4<f32>(reinhard(srgb_to_linear(vec3<f32>(0.5))), 1.0);
}`;

const TONEMAP = `// shaders/lib/tonemap.wgsl
fn reinhard(c: vec3<f32>) -> vec3<f32> {
  return c / (c + vec3<f32>(1.0));
}`;

function toRaw(m: GPUCompilationMessage): RawDiagnostic {
  return {
    type: m.type, message: m.message,
    lineNum: m.lineNum, linePos: m.linePos, offset: m.offset, length: m.length,
  };
}

export async function runL2(): Promise<L2Result> {
  const checks: L2Check[] = [];
  const data: Record<string, unknown> = {};
  const push = (name: string, ok: boolean, detail: unknown): void => {
    checks.push({ name, ok, detail: String(detail) });
  };

  const adapter = await navigator.gpu.requestAdapter();
  if (!adapter) throw new Error('requestAdapter() returned null');
  const device = await adapter.requestDevice();

  const rootFile = { path: 'shaders/island.wgsl', text: ROOT };

  // 好源码：color.wgsl 与 tonemap.wgsl 都干净
  const good = resolveIncludes(rootFile, new Map([
    ['shaders/lib/color.wgsl', GOOD_COLOR],
    ['shaders/lib/tonemap.wgsl', TONEMAP],
  ]));
  const goodMod = device.createShaderModule({ code: good.code });
  const goodInfo = await goodMod.getCompilationInfo();
  const goodMsgs = goodInfo.messages.map(toRaw);
  data.goodSummary = summarize(goodMsgs);
  push('好源码 0 error', !hasErrors(goodMsgs), JSON.stringify(data.goodSummary));

  // 坏源码：错误在 include 进来的库文件里
  const bad = resolveIncludes(rootFile, new Map([
    ['shaders/lib/color.wgsl', BAD_COLOR],
    ['shaders/lib/tonemap.wgsl', TONEMAP],
  ]));
  const badMod = device.createShaderModule({ code: bad.code });
  const badInfo = await badMod.getCompilationInfo();
  const badMsgs = badInfo.messages.map(toRaw);
  data.badSummary = summarize(badMsgs);
  push('坏源码报出 error', hasErrors(badMsgs), JSON.stringify(data.badSummary));

  const located = badMsgs.filter((m) => m.type === 'error').map((m) => mapDiagnostic(m, bad.lines));
  data.located = located.map(formatDiagnostic);
  data.rawFirst = badMsgs.find((m) => m.type === 'error') ?? null;
  push('诊断还原到库文件而非拼接大文件',
    located.length > 0 && located[0]!.file === 'shaders/lib/color.wgsl',
    located[0] ? formatDiagnostic(located[0]) : 'none');
  push('还原后的行号落在库文件内 (1..3)',
    located.length > 0 && located[0]!.line >= 1 && located[0]!.line <= 3,
    located[0] ? String(located[0]!.line) : 'none');

  device.destroy();
  return { checks, data };
}

goodSummary  {errors: 0, warnings: 0, infos: 0}
badSummary   {errors: 1, warnings: 0, infos: 0}
rawFirst     lineNum=4 linePos=10 offset=105 length=6
located      error: shaders/lib/color.wgsl:3:10: no matching call to 'pow(vec3<f32>)'