@deepexi/datasense-connector 3.0.1 → 3.1.0

package/test/testing/run-tests.test.ts

@@ -0,0 +1,137 @@
+/**
+ * `runTests`：按能力目录的 `tests/` 跑用例并统计覆盖；未声明字段让用例失败（可扩展表除外）；建议列用例照常运行但不计入覆盖。
+ * 连接器项目写在临时目录里，描述手写进 `.ontos/descriptor.json`，经 vm 子进程执行（与 CLI 同一路径）。
+ */
+import { afterAll, describe, expect, test } from 'bun:test';
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import ts from 'typescript';
+import { loadLocalConnector, operationCaseGaps, runTests, testCoverage } from '../../src/testing';
+import { configField, descriptor, operation, stream, table, valueField } from '../fixtures/descriptor';
+
+const DESCRIPTOR = descriptor({
+  name: 'crm',
+  streams: {
+    orders: stream({ orders: table({ id: 'string', amount: 'integer' }, ['id']) }, {
+      syncModes: ['full'], params: { withFoo: configField('boolean', { optional: true }) },
+    }),
+    customers: stream({ customers: table({ id: 'string' }, ['id'], { extensible: true }) }, { syncModes: ['full'], suggestColumns: true }),
+  },
+  operations: {
+    create_followup: operation({ customerId: valueField('string') }, { followupId: valueField('string') }),
+  },
+});
+
+const SOURCES: Record<string, string> = {
+  'package.json': JSON.stringify({ dependencies: { '@deepexi/datasense-connector': '^3.0.0' } }),
+  '.ontos/descriptor.json': JSON.stringify(DESCRIPTOR),
+  'streams/orders/index.ts': `import { defineStream } from '@deepexi/datasense-connector';
+export default defineStream('orders', async function* (ctx, input) {
+  yield ctx.record('orders', input.streamConfig.withFoo ? { id: 'o1', amount: 1, foo: 'x', bar: 2 } : { id: 'o1', amount: 1 });
+});
+`,
+  'streams/customers/index.ts': `import { defineStream } from '@deepexi/datasense-connector';
+export default defineStream('customers', async function* (ctx) {
+  yield ctx.record('customers', { id: 'c1', vip_level: 'gold' });
+});
+`,
+  'streams/customers/suggest-columns.ts': `import { defineSuggestColumns } from '@deepexi/datasense-connector';
+export default defineSuggestColumns('customers', async () => [{ name: 'vip_level', type: 'string', title: 'VIP level' }]);
+`,
+  'operations/create_followup/index.ts': `import { defineOperation, errors } from '@deepexi/datasense-connector';
+export default defineOperation('create_followup', {
+  async run(ctx, params) {
+    if (params.customerId === 'blocked') throw new errors.RejectedError('customer is blocked', { code: 'BLOCKED' });
+    return { followupId: 'f-' + params.customerId };
+  },
+});
+`,
+};
+
+const CASES: Record<string, Record<string, unknown>> = {
+  'streams/orders/tests/first-page': { mode: 'full', config: {}, expect: { records: { orders: 1 } } },
+  'streams/orders/tests/with-foo': { mode: 'full', config: {}, streamConfig: { withFoo: true } },
+  'streams/customers/tests/extra': { mode: 'full', config: {}, expect: { records: { customers: 1 } } },
+  'streams/customers/tests/s1': { kind: 'suggest', table: 'customers', config: {}, expect: { columns: [{ name: 'vip_level', type: 'string', title: 'VIP level' }] } },
+  'streams/customers/tests/s2': { kind: 'suggest', table: 'customers', config: {}, expect: { columns: [{ name: 'tier', type: 'string', title: 'Tier' }] } },
+  'operations/create_followup/tests/ok': { params: { customerId: 'c1' }, idempotencyKey: 'k1', config: {}, expect: { ok: { followupId: 'f-c1' } } },
+  'operations/create_followup/tests/rejected': { params: { customerId: 'blocked' }, idempotencyKey: 'k2', config: {}, expect: { error: 'REJECTED' } },
+};
+
+const temps: string[] = [];
+afterAll(async () => {
+  await Promise.all(temps.map((dir) => rm(dir, { recursive: true, force: true })));
+});
+
+/** 写一个带指定用例的项目。 */
+async function project(cases: string[]): Promise<string> {
+  const dir = await mkdtemp(path.join(os.tmpdir(), 'sdk-run-tests-'));
+  temps.push(dir);
+  const write = async (file: string, content: string) => {
+    await mkdir(path.dirname(path.join(dir, file)), { recursive: true });
+    await writeFile(path.join(dir, file), content);
+  };
+  for (const [file, content] of Object.entries(SOURCES)) await write(file, content);
+  for (const name of cases) await write(`${name}/case.json`, JSON.stringify(CASES[name]));
+  return dir;
+}
+
+const load = async (cases: string[]) => loadLocalConnector(await project(cases), { typescript: ts });
+
+describe('runTests', () => {
+  test('coverage: orders and create_followup are covered; customers with only a suggest case is uncovered; ok is false', async () => {
+    const report = await runTests(await load(['streams/orders/tests/first-page', 'operations/create_followup/tests/ok', 'streams/customers/tests/s1']));
+    expect(report.covered).toEqual(['streams/orders', 'operations/create_followup']);
+    expect(report.uncovered).toEqual(['streams/customers']);
+    expect(report.ok).toBe(false);
+    // 每个用例都通过：建议列用例比对了 expect.columns
+    expect(report.cases.map((item) => [`${item.capability}/${item.name}`, item.ok])).toEqual([
+      ['operations/create_followup/ok', true],
+      ['streams/customers/s1', true],
+      ['streams/orders/first-page', true],
+    ]);
+  }, 30_000);
+
+  test('undeclared fields on a non-extensible table fail the case with UNDECLARED_FIELDS listing the fields', async () => {
+    const report = await runTests(await load(['streams/orders/tests/with-foo']));
+    const [item] = report.cases;
+    expect(item?.ok).toBe(false);
+    expect(item?.failure?.code).toBe('UNDECLARED_FIELDS');
+    expect(item?.failure?.message).toContain('bar, foo');
+  }, 30_000);
+
+  test('extra fields on an extensible table pass; a wrong suggestion list fails; with every capability covered ok is true', async () => {
+    const all = ['streams/orders/tests/first-page', 'streams/customers/tests/extra', 'operations/create_followup/tests/ok', 'operations/create_followup/tests/rejected'];
+    const passing = await runTests(await load([...all, 'streams/customers/tests/s1']));
+    expect(passing.cases.every((item) => item.ok)).toBe(true);
+    expect(passing.uncovered).toEqual([]);
+    expect(passing.ok).toBe(true);
+
+    const failing = await runTests(await load([...all, 'streams/customers/tests/s2']));
+    expect(failing.ok).toBe(false);
+    expect(failing.cases.find((item) => item.name === 's2')?.failure?.code).toBe('EXPECTATION_FAILED');
+  }, 30_000);
+
+  test('发布门禁：操作只有成功用例时 operationCases 列出缺 REJECTED，ok 为 false；成功与拒绝用例都齐时为 []', async () => {
+    const base = ['streams/orders/tests/first-page', 'streams/customers/tests/extra'];
+    const onlyOk = await runTests(await load([...base, 'operations/create_followup/tests/ok']));
+    expect(onlyOk.uncovered).toEqual([]);
+    expect(onlyOk.cases.every((item) => item.ok)).toBe(true);
+    expect(onlyOk.operationCases).toEqual([{ operation: 'create_followup', missing: ['REJECTED'] }]);
+    expect(onlyOk.ok).toBe(false);
+
+    const both = await runTests(await load([...base, 'operations/create_followup/tests/ok', 'operations/create_followup/tests/rejected']));
+    expect(both.operationCases).toEqual([]);
+    expect(both.ok).toBe(true);
+    expect(operationCaseGaps(DESCRIPTOR, [])).toEqual([{ operation: 'create_followup', missing: ['ok', 'REJECTED'] }]);
+  }, 30_000);
+
+  test('options.cases runs only the selected cases; coverage still counts every case', async () => {
+    const connector = await load(['streams/orders/tests/first-page', 'operations/create_followup/tests/ok', 'streams/customers/tests/extra']);
+    const report = await runTests(connector, { cases: ['streams/orders'] });
+    expect(report.cases.map((item) => item.name)).toEqual(['first-page']);
+    expect(report.uncovered).toEqual([]);
+    expect(testCoverage(DESCRIPTOR, [])).toEqual({ covered: [], uncovered: ['streams/orders', 'streams/customers', 'operations/create_followup'] });
+  }, 30_000);
+});

package/test/testing/source-loader.test.ts

@@ -0,0 +1,220 @@
+/**
+ * 本地加载：读 `.ontos/descriptor.json`、按目录约定生成入口、导入检查、路径逃逸、符号链接与体积上限；
+ * 正常目录转译成可在 guest 里执行的打包串，能力目录下的 `tests/` 收集为用例文件而不算源码。
+ */
+import { afterEach, describe, expect, test } from 'bun:test';
+import { mkdir, mkdtemp, rm, symlink, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import ts from 'typescript';
+import type { ConnectorDescriptor } from '../../src';
+import { loadLocalConnector, SourceLoadError, type SourceLoadErrorCode } from '../../src/testing';
+import { descriptor, push, table } from '../fixtures/descriptor';
+
+const MANIFEST = { dependencies: { '@deepexi/datasense-connector': '^3.0.0' } };
+const DESCRIPTOR = descriptor({ pushes: { default: push({ item: table({ id: 'string' }, ['id']) }) } });
+
+const PUSH = `import { definePush } from '@deepexi/datasense-connector';
+import { label } from './lib/label';
+export default definePush('default', { map(ctx) { ctx.log.info(label()); } });
+`;
+
+const dirs: string[] = [];
+
+async function project(
+  files: Record<string, string>,
+  options: { manifest?: Record<string, unknown>; descriptor?: ConnectorDescriptor | Record<string, unknown> | null } = {},
+): Promise<string> {
+  const base = await mkdtemp(path.join(os.tmpdir(), 'sdk-loader-'));
+  dirs.push(base);
+  const root = path.join(base, 'connector');
+  await mkdir(root);
+  await writeFile(path.join(root, 'package.json'), JSON.stringify(options.manifest ?? MANIFEST));
+  const desc = options.descriptor === undefined ? DESCRIPTOR : options.descriptor;
+  if (desc !== null) {
+    await mkdir(path.join(root, '.ontos'));
+    await writeFile(path.join(root, '.ontos', 'descriptor.json'), JSON.stringify(desc));
+  }
+  for (const [file, content] of Object.entries(files)) {
+    await mkdir(path.dirname(path.join(root, file)), { recursive: true });
+    await writeFile(path.join(root, file), content);
+  }
+  return root;
+}
+
+async function expectLoadError(dir: string, code: SourceLoadErrorCode): Promise<SourceLoadError> {
+  try {
+    await loadLocalConnector(dir, { typescript: ts });
+  } catch (error) {
+    expect(error).toBeInstanceOf(SourceLoadError);
+    expect((error as SourceLoadError).code).toBe(code);
+    return error as SourceLoadError;
+  }
+  throw new Error(`expected SourceLoadError ${code}`);
+}
+
+afterEach(async () => {
+  await Promise.all(dirs.splice(0).map((dir) => rm(dir, { recursive: true, force: true })));
+});
+
+describe('loadLocalConnector', () => {
+  test('a valid project becomes one CommonJS bundle whose generated entry exports { descriptor, implementations }', async () => {
+    const dir = await project({
+      'pushes/default/index.ts': PUSH,
+      'pushes/default/lib/label.ts': "import data from '../data.json';\nexport function label(): string { return `hello ${data.who}`; }\n",
+      'pushes/default/data.json': '{ "who": "world" }',
+      'pushes/default/tests/basic/case.json': '{ "config": {} }',
+      'pushes/default/tests/basic/requests.ndjson': '',
+      'node_modules/x/index.js': 'module.exports = 1;',
+    });
+    const loaded = await loadLocalConnector(dir, { typescript: ts });
+    expect(loaded.name).toBe('demo');
+    expect(loaded.version).toBe('1.0.0');
+    expect(loaded.descriptor).toEqual(DESCRIPTOR);
+    expect(loaded.sdkRange).toBe('^3.0.0');
+    // tests/ 与 .ontos/ 不算源码
+    expect(Object.keys(loaded.files).sort()).toEqual(['package.json', 'pushes/default/data.json', 'pushes/default/index.ts', 'pushes/default/lib/label.ts']);
+    expect(loaded.testFiles.map((file) => file.path)).toEqual(['pushes/default/tests/basic/case.json', 'pushes/default/tests/basic/requests.ndjson']);
+    const map = JSON.parse(loaded.sourcemap) as { version: number; sections: Array<{ map: { sources: string[] } }> };
+    expect(map.version).toBe(3);
+    expect(map.sections.map((section) => section.map.sources[0])).toEqual(['pushes/default/index.ts', 'pushes/default/lib/label.ts']);
+
+    // 打包串在 guest 外也能用一个假的 SDK require 求值：模块表按相对路径解析
+    const module = { exports: {} as Record<string, unknown> };
+    const sdk = { definePush: (name: string, impl: unknown) => ({ __ontos: 'push', name, handler: impl }) };
+    const evaluate = new Function('module', 'exports', 'require', loaded.code) as (m: unknown, e: unknown, r: (s: string) => unknown) => void;
+    evaluate(module, module.exports, (specifier) => {
+      if (specifier !== '@deepexi/datasense-connector') throw new Error(`unexpected require ${specifier}`);
+      return sdk;
+    });
+    const exported = module.exports as {
+      descriptor: ConnectorDescriptor;
+      implementations: { streams: object; suggestColumns: object; operations: object; pushes: { default: { name: string; handler: { map(ctx: unknown): void } } } };
+    };
+    expect(exported.descriptor).toEqual(DESCRIPTOR);
+    expect(exported.implementations.streams).toEqual({});
+    expect(exported.implementations.suggestColumns).toEqual({});
+    expect(exported.implementations.operations).toEqual({});
+    expect(exported.implementations.pushes.default.name).toBe('default');
+    const logs: string[] = [];
+    exported.implementations.pushes.default.handler.map({ log: { info: (message: string) => logs.push(message) } });
+    expect(logs).toEqual(['hello world']);
+  });
+
+  test('without .ontos/descriptor.json it is DESCRIPTOR_NOT_GENERATED and points at codegen', async () => {
+    const error = await expectLoadError(await project({ 'pushes/default/index.ts': PUSH }, { descriptor: null }), 'DESCRIPTOR_NOT_GENERATED');
+    expect(error.message).toContain('ontos admin connector codegen');
+  });
+
+  test('a descriptor that is not an object of the right shape, or has a bad capability name, is DESCRIPTOR_INVALID', async () => {
+    await expectLoadError(await project({}, { descriptor: { name: 'demo' } }), 'DESCRIPTOR_INVALID');
+    await expectLoadError(await project({}, { descriptor: { ...DESCRIPTOR, pushes: { '../x': push({}) } } }), 'DESCRIPTOR_INVALID');
+  });
+
+  test('a missing implementation file is left out of implementations (the guest then reports it)', async () => {
+    const loaded = await loadLocalConnector(await project({}), { typescript: ts });
+    const module = { exports: {} as Record<string, unknown> };
+    new Function('module', 'exports', 'require', loaded.code)(module, module.exports, () => ({}));
+    expect((module.exports as { implementations: { pushes: object } }).implementations.pushes).toEqual({});
+  });
+
+  test('stream sources may import the generated .ontos/types.ts', async () => {
+    const dir = await project({
+      'pushes/default/index.ts': "import { definePush } from '../../.ontos/types';\nexport default definePush('default', { map() {} });\n",
+    });
+    await writeFile(path.join(dir, '.ontos', 'types.ts'), "import { definePush as bound } from '@deepexi/datasense-connector';\nexport const definePush = bound;\n");
+    const loaded = await loadLocalConnector(dir, { typescript: ts });
+    expect(Object.keys(loaded.files)).not.toContain('.ontos/types.ts');
+    const module = { exports: {} as Record<string, unknown> };
+    new Function('module', 'exports', 'require', loaded.code)(module, module.exports, () => ({ definePush: (name: string) => ({ name }) }));
+    expect((module.exports as { implementations: { pushes: { default: { name: string } } } }).implementations.pushes.default.name).toBe('default');
+  });
+
+  test('a JSON module keeps JSON semantics: "__proto__" is an own key, not the prototype', async () => {
+    const dir = await project({
+      'pushes/default/index.ts': "import data from './data.json';\nexport default data;\n",
+      'pushes/default/data.json': '{\n  "__proto__": { "polluted": true },\n  "plain": 1\n}\n',
+    });
+    const loaded = await loadLocalConnector(dir, { typescript: ts });
+    const module = { exports: {} as Record<string, unknown> };
+    const evaluate = new Function('module', 'exports', 'require', loaded.code) as (m: unknown, e: unknown, r: (s: string) => unknown) => void;
+    evaluate(module, module.exports, () => ({}));
+    const data = (module.exports as { implementations: { pushes: { default: Record<string, unknown> } } }).implementations.pushes.default;
+    expect(Object.hasOwn(data, '__proto__')).toBe(true);
+    expect(Object.getPrototypeOf(data)).toBe(Object.prototype);
+    expect((data as { polluted?: unknown }).polluted).toBeUndefined();
+    expect(data.plain).toBe(1);
+  });
+
+  test("import fs from 'node:fs' is IMPORT_FORBIDDEN even when unused", async () => {
+    const error = await expectLoadError(await project({ 'pushes/default/index.ts': `import fs from 'node:fs';\n${PUSH}`, 'pushes/default/lib/label.ts': 'export const label = () => "x";' }), 'IMPORT_FORBIDDEN');
+    expect(error.file).toBe('pushes/default/index.ts');
+  });
+
+  test("import x from 'lodash' is IMPORT_FORBIDDEN", async () => {
+    await expectLoadError(await project({ 'pushes/default/index.ts': `import x from 'lodash';\nexport default x;\n` }), 'IMPORT_FORBIDDEN');
+  });
+
+  test("import y from '../../../outside' is PATH_ESCAPE", async () => {
+    await expectLoadError(await project({ 'pushes/default/index.ts': `import y from '../../../outside';\nexport default y;\n` }), 'PATH_ESCAPE');
+  });
+
+  test('import attributes are IMPORT_FORBIDDEN', async () => {
+    await expectLoadError(await project({ 'pushes/default/index.ts': `import z from './a.json' with { type: 'json' };\nexport default z;\n`, 'pushes/default/a.json': '{}' }), 'IMPORT_FORBIDDEN');
+  });
+
+  test('dynamic import with options is IMPORT_FORBIDDEN', async () => {
+    await expectLoadError(
+      await project({ 'pushes/default/index.ts': `export async function f() { return await import('./b', { with: { type: 'macro' } }); }\n`, 'pushes/default/b.ts': 'export const b = 1;' }),
+      'IMPORT_FORBIDDEN',
+    );
+  });
+
+  test('a computed require is IMPORT_FORBIDDEN', async () => {
+    await expectLoadError(await project({ 'pushes/default/index.ts': `const name = 'fs';\nexport const x = require(name);\n` }), 'IMPORT_FORBIDDEN');
+  });
+
+  test('the SDK testing subpath is IMPORT_FORBIDDEN', async () => {
+    await expectLoadError(await project({ 'pushes/default/index.ts': `import { runStream } from '@deepexi/datasense-connector/testing';\nexport default runStream;\n` }), 'IMPORT_FORBIDDEN');
+  });
+
+  test('a symbolic link pointing outside the source root is SYMLINK', async () => {
+    const dir = await project({ 'pushes/default/index.ts': PUSH, 'pushes/default/lib/label.ts': 'export const label = () => "x";' });
+    await writeFile(path.join(dir, '..', 'outside.ts'), 'export const secret = 1;');
+    await symlink(path.join(dir, '..', 'outside.ts'), path.join(dir, 'pushes', 'default', 'outside.ts'));
+    const error = await expectLoadError(dir, 'SYMLINK');
+    expect(error.file).toBe('pushes/default/outside.ts');
+  });
+
+  test('node_modules / dist that are themselves symbolic links are skipped, not SYMLINK', async () => {
+    const dir = await project({ 'pushes/default/index.ts': PUSH, 'pushes/default/lib/label.ts': 'export const label = () => "x";' });
+    const elsewhere = await mkdtemp(path.join(os.tmpdir(), 'sdk-linked-modules-'));
+    await symlink(elsewhere, path.join(dir, 'node_modules'), 'dir');
+    await symlink(elsewhere, path.join(dir, 'dist'), 'dir');
+    const loaded = await loadLocalConnector(dir, { typescript: ts });
+    expect(Object.keys(loaded.files).some((file) => file.startsWith('node_modules') || file.startsWith('dist'))).toBe(false);
+    await rm(elsewhere, { recursive: true, force: true });
+  });
+
+  test('more than 2 MB of source is TOO_LARGE', async () => {
+    const big = `export const blob = ${JSON.stringify('x'.repeat(1024 * 1024))};\n`;
+    await expectLoadError(await project({ 'pushes/default/index.ts': PUSH, 'pushes/default/a.ts': big, 'pushes/default/b.ts': big, 'pushes/default/c.ts': big }), 'TOO_LARGE');
+  });
+
+  test('a syntax error is SYNTAX_ERROR with the file', async () => {
+    const error = await expectLoadError(await project({ 'pushes/default/index.ts': 'export const = 1;\n' }), 'SYNTAX_ERROR');
+    expect(error.file).toBe('pushes/default/index.ts');
+  });
+
+  test('dependencies other than the SDK are MANIFEST_INVALID', async () => {
+    await expectLoadError(
+      await project({ 'pushes/default/index.ts': PUSH }, { manifest: { ...MANIFEST, dependencies: { '@deepexi/datasense-connector': '^3.0.0', lodash: '^4.0.0' } } }),
+      'MANIFEST_INVALID',
+    );
+  });
+
+  test('typescript must be the compiler API', async () => {
+    const dir = await project({ 'pushes/default/index.ts': PUSH });
+    await expect(loadLocalConnector(dir, { typescript: {} })).rejects.toThrow(TypeError);
+  });
+});

package/test/validate-config.test.ts

@@ -0,0 +1,104 @@
+/**
+ * 按描述校验值：连接配置（`validateConfig`）、连接器操作的入参与输出（`validateOperationValue`）、建议列（`validateSuggestedColumns`）。
+ */
+import { describe, expect, test } from 'bun:test';
+import {
+  PRESENTATION_LIMITS, SUGGESTED_COLUMNS_MAX, validateConfig, validateOperationValue, validateSuggestedColumns,
+} from '../src';
+import { configField, valueField } from './fixtures/descriptor';
+
+const paths = (issues: Array<{ path: string }>) => issues.map((issue) => issue.path);
+
+describe('validateConfig', () => {
+  test('{ accountSet: optional string, port: integer } with { port: "x" } reports only port', () => {
+    const fields = { accountSet: configField('string', { optional: true }), port: configField('integer') };
+    expect(paths(validateConfig(fields, { port: 'x' }))).toEqual(['port']);
+    expect(validateConfig(fields, { port: 8080 })).toEqual([]);
+  });
+
+  test('a required field that is missing or null is reported; a field with a default may be missing', () => {
+    const fields = { host: configField('string'), pageSize: configField('integer', { default: 100 }) };
+    expect(paths(validateConfig(fields, {}))).toEqual(['host']);
+    expect(paths(validateConfig(fields, { host: null }))).toEqual(['host']);
+    expect(validateConfig(fields, { host: 'a' })).toEqual([]);
+  });
+
+  test('url accepts only http and https', () => {
+    const fields = { baseUrl: configField('url') };
+    expect(validateConfig(fields, { baseUrl: 'https://api.example.com/v1' })).toEqual([]);
+    expect(validateConfig(fields, { baseUrl: 'http://localhost:8080' })).toEqual([]);
+    for (const bad of ['ftp://example.com', 'example.com', 'https://', 'javascript:alert(1)', 42]) {
+      expect(paths(validateConfig(fields, { baseUrl: bad }))).toEqual(['baseUrl']);
+    }
+  });
+
+  test('enum accepts only the listed values', () => {
+    const fields = { region: configField('enum', { values: ['cn', 'us'] }) };
+    expect(validateConfig(fields, { region: 'cn' })).toEqual([]);
+    expect(paths(validateConfig(fields, { region: 'eu' }))).toEqual(['region']);
+  });
+
+  test('secret fields are not checked; undeclared keys are reported', () => {
+    const fields = { token: configField('secret'), host: configField('string') };
+    expect(validateConfig(fields, { host: 'a' })).toEqual([]);
+    expect(paths(validateConfig(fields, { host: 'a', extra: 1 }))).toEqual(['extra']);
+  });
+
+  test('boolean and decimal values', () => {
+    const fields = { on: configField('boolean'), rate: configField('decimal') };
+    expect(validateConfig(fields, { on: true, rate: '1.25' })).toEqual([]);
+    expect(paths(validateConfig(fields, { on: 'yes', rate: 'abc' }))).toEqual(['on', 'rate']);
+  });
+
+  test('PRESENTATION_LIMITS keeps its values', () => {
+    expect(PRESENTATION_LIMITS).toMatchObject({ title: 40, description: 120, fieldTitle: 40, fieldDescription: 200, tableTitle: 40, tableDescription: 200 });
+  });
+});
+
+describe('validateOperationValue', () => {
+  const fields = {
+    sku: valueField('string'),
+    qty: valueField('integer'),
+    note: valueField('string', { optional: true }),
+    lines: valueField('array', { item: valueField('object', { fields: { n: valueField('integer') } }) }),
+  };
+
+  test('missing, wrong-typed, nested and undeclared fields are reported with their paths', () => {
+    expect(validateOperationValue(fields, { sku: 'A', qty: 1, lines: [{ n: 1 }] }, 'input')).toEqual([]);
+    expect(paths(validateOperationValue(fields, { qty: 'x', lines: [{ n: 'y' }], extra: true }, 'input')).sort())
+      .toEqual(['input.extra', 'input.lines[0].n', 'input.qty', 'input.sku']);
+    expect(paths(validateOperationValue(fields, 'nope', 'output'))).toEqual(['output']);
+  });
+});
+
+describe('validateSuggestedColumns', () => {
+  test('valid columns come back as plain SuggestedColumn objects', () => {
+    const result = validateSuggestedColumns([
+      { name: 'vip_level', type: 'string', title: 'VIP level' },
+      { name: 'credit', type: 'decimal', precision: 12, scale: 2, title: 'Credit', description: 'Credit limit' },
+    ]);
+    expect(result).toEqual({
+      ok: true,
+      columns: [
+        { name: 'vip_level', type: 'string', title: 'VIP level' },
+        { name: 'credit', type: 'decimal', precision: 12, scale: 2, title: 'Credit', description: 'Credit limit' },
+      ],
+    });
+  });
+
+  test('bad names, reserved prefixes, duplicates, unknown types, missing titles and decimals without precision are rejected', () => {
+    const result = validateSuggestedColumns([
+      { name: '1bad', type: 'string', title: 'x' },
+      { name: '_ontos_tenant', type: 'string', title: 'x' },
+      { name: 'dup', type: 'string', title: 'x' },
+      { name: 'dup', type: 'string', title: 'x' },
+      { name: 'kind', type: 'text', title: 'x' },
+      { name: 'untitled', type: 'string' },
+      { name: 'amount', type: 'decimal', title: 'x' },
+    ]);
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.issues.length).toBeGreaterThanOrEqual(6);
+    expect(validateSuggestedColumns({}).ok).toBe(false);
+    expect(validateSuggestedColumns(Array.from({ length: SUGGESTED_COLUMNS_MAX + 1 }, (_, i) => ({ name: `c${i}`, type: 'string', title: 'c' }))).ok).toBe(false);
+  });
+});

package/tsconfig.build.json

@@ -0,0 +1,23 @@
+{
+  // 发布产物（dist/）的 ESM 编译：tsc 只出 .js 与 .d.ts，扩展名与 CJS 版本由 scripts/build.ts 补齐。
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "lib": ["ESNext"],
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "moduleDetection": "force",
+    "verbatimModuleSyntax": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "noUncheckedIndexedAccess": true,
+    "types": ["bun"],
+    "rootDir": "src",
+    "outDir": "dist",
+    "declaration": true,
+    "sourceMap": false,
+    "noEmit": false,
+    "removeComments": false
+  },
+  "include": ["src"]
+}

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "lib": ["ESNext"],
+    "target": "ESNext",
+    "module": "Preserve",
+    "moduleResolution": "bundler",
+    "moduleDetection": "force",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "noUncheckedIndexedAccess": true,
+    "types": ["bun"],
+    "paths": { "@deepexi/datasense-connector": ["./src/index.ts"] }
+  },
+  "include": ["src", "test"]
+}