API

readAndTranslate(path, options?, context?)

• 读取 Excel 并按插件流水线处理，返回 Table
• options.sheetName：不传默认选 __data 或第一张 sheet
• options.plugins：按顺序执行的插件数组

const { readAndTranslate, tableConvert } = require('@khgame/tables')
const table = readAndTranslate('example/example.xlsx', { plugins: [tableConvert] })
console.log(table.schema)   // 解析出的 schema AST
console.log(table.convert)  // { tids, result, collisions }

serialize(pathIn, dirOut, serializers, context?)

• 读取单个 Excel，并用多个序列化器生成多个产物文件
• serializers 形如：{ 'Example.json': jsonSerializer, 'Example.ts': tsSerializer }

const { serialize, jsonSerializer, tsSerializer } = require('@khgame/tables')
serialize('example/example.xlsx', 'out', {
  'Example.json': jsonSerializer,
  'Example.ts': tsSerializer
})

inspectTableFile(pathIn, options?, context?)

• 读取单个 Excel/CSV 并返回机器可读诊断对象
• 诊断包含实际 sheet 名、mark/desc 信息、schema model、convert 计数、索引与 alias 计数与转换错误
• convert 阶段自有错误会在 diagnostics.convert.errorMeta 中附带结构化错误码、定位和细节；第三方或旧式错误仍保留字符串错误
• 适合调试表头、生成 AI 修复上下文，或在导出前做轻量检查

const { inspectTableFile, loadContext } = require('@khgame/tables')
const ctx = loadContext('example')
const diagnostics = inspectTableFile('example/items.csv', {}, ctx)
console.log(diagnostics.convert.tidCount)

validateTableFile(pathIn, options?, context?)

validateTableFile 是 inspectTableFile 之上的稳定校验摘要，适合 AI agent、CI 和编辑器集成直接调用：

• 返回 { success, fileName, sheetName?, diagnostics, errors, warnings }
• errors[] / warnings[] 使用 { severity, code, message, location?, diagnosticPath?, details? }
• location 面向编辑器和 agent 定位，当前会尽量包含 sheetName、row、column、fieldPath
• details 面向自动修复和 CI 展示，当前会尽量包含 tableName、tid、sourceAlias、rawValue、suggestedType、duplicateAliases
• 当前错误码包括 schema_error、convert_error、tid_collision、context_ref_error、inspect_error
• 自有 convert 错误会优先使用结构化 metadata 生成 location / details，再回退到兼容旧错误文案的解析逻辑
• CLI --validate --json 会先校验 context enum refs；缺失目标表或目标字段不是 alias 列时返回 context_ref_error
• 自身不写文件；CLI machine mode 会隔离底层偶发日志，方便测试和 AI agent 直接调用
• diagnostics 保留完整 inspectTableFile 结果，便于定位 sheet、mark/desc、schema 和 convert 信息

调用方式：

const { validateTableFile, loadContext } = require('@khgame/tables')
const ctx = loadContext('example')
const report = validateTableFile('example/items.csv', {}, ctx)

if (!report.success) {
  console.error(JSON.stringify(report.errors, null, 2))
}

上下文（Context）与枚举

• loadContext(dir) 会将 dir 下符合 context.*.json 的文件聚合为上下文对象
• loadContextPath(path) 可接收 context 目录、context.<blob>.json 文件或完整 context JSON 文件；CLI --context 与该 API 共享同一加载语义
• validateContextReferences(pathOrContext, baseDir?) 会检查 context.enums.* 中的表引用，并返回 { success, references, errors, warnings }
• collectContextEnumReferences(context) 可只收集 enum refs，不读取目标表
• serializeContext(dirOut, serializers, context) 会生成 context.ts（供 TS 序列化器引用），并可输出枚举
• 在 context.meta.exports.enum = [ 'enums', ... ] 中声明要导出的枚举集合名

const { loadContextPath, serializeContext, tsSerializer, validateContextReferences } = require('@khgame/tables')
const check = validateContextReferences('example')
if (!check.success) console.error(check.errors)
const ctx = loadContextPath('example')
serializeContext('out', [tsSerializer], ctx) // 生成 out/context.ts

索引（Indexes）

• context.indexes / context.meta.indexes 可声明额外索引，按表名、驼峰名、接口名或 * 匹配
• 支持字符串路径、路径数组或对象配置，默认生成唯一键映射到 TID
• 结果写入 table.convert.indexes，并在 table.convert.meta.indexes 提供模式与冲突信息

{
  "indexes": {
    "Example": [
      "Label",
      { "name": "skill", "path": "rule.skillId", "mode": "multi" }
    ]
  }
}

一键批量导出（Out-of-Box）

• exportTablesToTs(dirIn, dirOut)：扫描目录所有 xlsx，生成聚合 index.ts、各自的 TS、context.ts

const { exportTablesToTs } = require('@khgame/tables')
exportTablesToTs('./example', './out')