@tbox.cn/app-toolkit 0.3.0 → 0.5.0

package/tests/module-schema.test.ts

@@ -7,37 +7,67 @@ import {
 
 /**
  * module-schema（descriptor zod 单源）迁移改造验证（C2-5 + C1 P6 归位）：
- * - demand meta additive（serviceNeedContribSchema 增 title?/description?——P6）
+ * - demand meta additive（serviceConsumeContribSchema 增 name?/description?——P6）
  * - resource type 放宽（z.enum(RESOURCE_TYPE_IDS) → z.string()——词汇校验移谓词）
  * - 安全钉子 H9b（provider 字符集 pattern）
  * - 既有无 meta 素材全过（additive 等价）
+ * - v7 词汇统一（标识/展示名分轴）：id/name 翻转 + 四象限 legacy 矩阵
  */
 
 const BASE_MANIFEST = {
   schemaVersion: 1,
-  name: 'module-sample',
+  id: 'module-sample',
   version: '0.1.0',
 };
 
 describe('module-schema（descriptor zod 单源）', () => {
-  it('P6 demand meta additive：services 元素带 title/description 通过；缺席仍合法', () => {
+  it('v6 N1 旧键定向拒：顶层 contributes → ok:false + 三路径升级指引（非泛化 strict 报错）', () => {
+    const r = parseModuleDescriptor({ ...BASE_MANIFEST, contributes: { services: [] } });
+    expect(r.ok).toBe(false);
+    if (r.ok) return;
+    expect(r.errors[0]).toContain('`contributes` 已更名 `declare`');
+    expect(r.errors[0]).toContain('module update --source');
+  });
+
+  it('v6 N1 旧键定向拒：declare.services → ok:false + consumes 指引', () => {
+    const r = parseModuleDescriptor({ ...BASE_MANIFEST, declare: { services: [{ service: 'x.y' }] } });
+    expect(r.ok).toBe(false);
+    if (r.ok) return;
+    expect(r.errors[0]).toContain('`declare.services` 已更名 `declare.consumes`');
+  });
+
+  it('v6 owns 薄形状：strict 单键（元数据键拒——S1 防双数组漂移）；owns/consumes 双键并存合法', () => {
+    const thin = parseModuleDescriptor({ ...BASE_MANIFEST, declare: { owns: [{ service: 'a.b', optional: true } as never] } });
+    expect(thin.ok).toBe(false); // owns 元素 strict——元数据归 consumes
+    const both = parseModuleDescriptor({
+      ...BASE_MANIFEST,
+      declare: { owns: [{ service: 'a.b' }], consumes: [{ service: 'a.b', optional: false, name: 'T' }] },
+    });
+    expect(both.ok).toBe(true);
+    if (both.ok) {
+      expect(both.value.declare.owns).toEqual([{ service: 'a.b' }]);
+      expect(both.value.declare.consumes[0].name).toBe('T');
+    }
+  });
+
+  it('P6 demand meta additive：services 元素带 name/description 通过；缺席仍合法', () => {
     const withMeta = parseModuleDescriptor({
       ...BASE_MANIFEST,
-      contributes: {
-        services: [
-          { service: 'parking.query', optional: false, title: '车位查询', description: '查询车位状态' },
+      declare: {
+        consumes: [
+          { service: 'parking.query', optional: false, name: '车位查询', description: '查询车位状态' },
         ],
       },
     });
     expect(withMeta.ok).toBe(true);
     if (withMeta.ok) {
-      expect(withMeta.value.contributes.services[0].title).toBe('车位查询');
-      expect(withMeta.value.contributes.services[0].description).toBe('查询车位状态');
+      expect(withMeta.value.declare.consumes[0].name).toBe('车位查询');
+      expect(withMeta.value.declare.consumes[0].description).toBe('查询车位状态');
     }
     // 既有无 meta 素材全过（additive 等价）
     const withoutMeta = parseModuleDescriptor({
       ...BASE_MANIFEST,
-      contributes: { services: [{ service: 'parking.query' }] },
+      declare: { consumes: [{ service: 'parking.query' }] },
     });
     expect(withoutMeta.ok).toBe(true);
   });
@@ -45,7 +75,7 @@ describe('module-schema（descriptor zod 单源）', () => {
   it('resource type 放宽：任意 string 通过（词汇校验移谓词经 resolver 取词表）', () => {
     const result = parseModuleDescriptor({
       ...BASE_MANIFEST,
-      contributes: { resources: [{ id: 'kb-1', type: 'knowledge' }, { id: 'kb-2', type: 'future-type' }] },
+      declare: { resources: [{ id: 'kb-1', type: 'knowledge' }, { id: 'kb-2', type: 'future-type' }] },
     });
     expect(result.ok).toBe(true);
   });
@@ -53,14 +83,14 @@ describe('module-schema（descriptor zod 单源）', () => {
   it('H9b 安全钉子：provider 名含路径敌对字符 → 拒绝；合法字符集通过', () => {
     const evil = parseModuleDescriptor({
       ...BASE_MANIFEST,
-      contributes: {
+      declare: {
         providers: { slots: [{ service: 'a.b', provider: '../etc', implementation: 'x@1', credentialType: '-' }] },
       },
     });
     expect(evil.ok).toBe(false);
     const good = parseModuleDescriptor({
       ...BASE_MANIFEST,
-      contributes: {
+      declare: {
         providers: { slots: [{ service: 'a.b', provider: 'wanda', implementation: 'wanda-a@1', credentialType: '-' }] },
       },
     });
@@ -72,13 +102,84 @@ describe('module-schema（descriptor zod 单源）', () => {
     expect(SAFE_NAME_PATTERN.test('-lead')).toBe(false);
   });
 
-  it('零贡献合法（provider-custom 空包形态）：contributes 全 default', () => {
+  it('零贡献合法（provider-custom 空包形态）：declare 全 default', () => {
     const parsed = moduleDescriptorSchema.safeParse(BASE_MANIFEST);
     expect(parsed.success).toBe(true);
     if (parsed.success) {
-      expect(parsed.data.contributes.providers.slots).toEqual([]);
-      expect(parsed.data.contributes.services).toEqual([]);
-      expect(parsed.data.contributes.resources).toEqual([]);
+      expect(parsed.data.declare.providers.slots).toEqual([]);
+      expect(parsed.data.declare.consumes).toEqual([]);
+      expect(parsed.data.declare.resources).toEqual([]);
+    }
+  });
+
+  it('v7 B1 模块 meta：name = 展示名（id = 标识键）；缺席仍合法（回退归视图层）', () => {
+    const withMeta = parseModuleDescriptor({ ...BASE_MANIFEST, name: '停车缴费', description: '车辆查询与绑定、停车费用查询、缴费支付与开票' });
+    expect(withMeta.ok).toBe(true);
+    if (withMeta.ok) {
+      expect(withMeta.value.id).toBe('module-sample');
+      expect(withMeta.value.name).toBe('停车缴费');
+      expect(withMeta.value.description).toContain('停车费用查询');
+    }
+    const withoutMeta = moduleDescriptorSchema.safeParse(BASE_MANIFEST);
+    expect(withoutMeta.success).toBe(true);
+    if (withoutMeta.success) {
+      expect(withoutMeta.data.name).toBeUndefined();
+      expect(withoutMeta.data.description).toBeUndefined();
+    }
+  });
+
+  // ── v7 词汇统一：legacy 四象限矩阵（旧态/半迁移定向拒；v7 两形态放行）──
+
+  it('v7 legacy ①：v6 旧态（name 标识 + title 展示、无 id）→ 定向拒 + legacy 标志 + 双键指引', () => {
+    const r = parseModuleDescriptor({
+      schemaVersion: 1,
+      name: 'module-old',
+      title: '旧模块',
+      version: '0.1.0',
+      declare: { consumes: [{ service: 'a.b' }] },
+    });
+    expect(r.ok).toBe(false);
+    if (r.ok) return;
+    expect(r.legacy).toBe(true);
+    const joined = r.errors.join('\n');
+    expect(joined).toContain('标识键 `name` 已更名 `id`');
+    expect(joined).toContain('展示名键 `title` 已更名 `name`');
+    expect(joined).toContain('module update --source');
+  });
+
+  it('v7 legacy ②：v6 最小旧态（仅 name 无 title）→ 定向拒 + legacy 标志', () => {
+    const r = parseModuleDescriptor({ schemaVersion: 1, name: 'module-old', version: '0.1.0' });
+    expect(r.ok).toBe(false);
+    if (r.ok) return;
+    expect(r.legacy).toBe(true);
+    expect(r.errors[0]).toContain('标识键 `name` 已更名 `id`');
+  });
+
+  it('v7 legacy ③：半迁移（有 id 残留 title）→ 定向拒（title→name）', () => {
+    const r = parseModuleDescriptor({ ...BASE_MANIFEST, title: '残留展示名' });
+    expect(r.ok).toBe(false);
+    if (r.ok) return;
+    expect(r.legacy).toBe(true);
+    expect(r.errors[0]).toContain('展示名键 `title` 已更名 `name`');
+  });
+
+  it('v7 legacy ④：declare.consumes[].title 残留（根级已翻转）→ 定向拒', () => {
+    const r = parseModuleDescriptor({
+      ...BASE_MANIFEST,
+      declare: { consumes: [{ service: 'a.b', title: '旧槽名' }] },
+    });
+    expect(r.ok).toBe(false);
+    if (r.ok) return;
+    expect(r.legacy).toBe(true);
+    expect(r.errors[0]).toContain('展示名键 `title` 已更名 `name`');
+  });
+
+  it('v7 完整形态：id + name（展示名）+ description 并存合法（同名键歧义以 id 在场性消解）', () => {
+    const r = parseModuleDescriptor({ ...BASE_MANIFEST, name: '示例模块' });
+    expect(r.ok).toBe(true);
+    if (r.ok) {
+      expect(r.value.id).toBe('module-sample');
+      expect(r.value.name).toBe('示例模块');
     }
   });
 });

package/tests/resolve-key.test.ts

@@ -0,0 +1,154 @@
+import { describe, expect, it } from 'vitest';
+import { resolveModuleKey, resolveServiceKey } from '../src/assembly/resolve-key.js';
+import { AppToolkitError } from '../src/core/errors.js';
+import type { WalkManifestsResult, WalkModuleInfo } from '../src/assembly/walk-manifests.js';
+
+/**
+ * resolve-key（双键寻址 helper——v7 词汇统一）：歧义矩阵单测（纯参数式——walk 手工构造）。
+ * 语义锁：id 精确优先 / 展示名唯一命中 / 多命中 404 带候选 / 零命中 404 /
+ * 供给足迹进服务键集（O6）/ configuredKeys 注入。
+ */
+
+function mod(id: string, name?: string): WalkModuleInfo {
+  return {
+    id,
+    dir: `/x/${id}`,
+    pkg: `@app/${id}`,
+    descriptor: {
+      schemaVersion: 1,
+      id,
+      ...(name !== undefined ? { name } : {}),
+      version: '0.1.0',
+      kind: 'business',
+      risk: { level: 'low', writeBoundary: 'source' },
+      distribution: { defaultMode: 'codegen' },
+      declare: {
+        handlers: [], tools: [], cards: [], routes: [], pages: [], tabs: [],
+        providers: { slots: [] }, owns: [], consumes: [], resources: [],
+      },
+      dependencies: { modules: [] },
+      env: [],
+    },
+  };
+}
+
+function walk(overrides: Partial<WalkManifestsResult> = {}): WalkManifestsResult {
+  return {
+    modules: [],
+    catalog: { providers: {}, services: {}, credentialTypes: {} },
+    serviceSchemas: {},
+    vocabulary: [],
+    slotMeta: {},
+    ownership: {},
+    declarationIssues: [],
+    ...overrides,
+  };
+}
+
+describe('resolveModuleKey（模块双键）', () => {
+  it('id 精确命中优先（即使展示名域存在同串冲突）', () => {
+    const w = walk({
+      modules: [mod('module-a', '模块X'), mod('module-b', 'module-a')],
+    });
+    expect(resolveModuleKey(w, 'module-a').id).toBe('module-a');
+  });
+
+  it('唯一展示名命中 → 返回该模块', () => {
+    const w = walk({ modules: [mod('module-a', '停车缴费'), mod('module-b')] });
+    expect(resolveModuleKey(w, '停车缴费').id).toBe('module-a');
+  });
+
+  it('展示名缺省模块：name 兜底 = id（可按 id 命中兜底分支）', () => {
+    const w = walk({ modules: [mod('module-b')] });
+    expect(resolveModuleKey(w, 'module-b').id).toBe('module-b');
+  });
+
+  it('多展示名命中 → 404 MODULE_NOT_FOUND + 候选列表 + 改用 id 指引', () => {
+    const w = walk({ modules: [mod('module-a', '同名'), mod('module-b', '同名')] });
+    try {
+      resolveModuleKey(w, '同名');
+      expect.unreachable('应 throw');
+    } catch (e) {
+      expect(e).toBeInstanceOf(AppToolkitError);
+      const err = e as AppToolkitError;
+      expect(err.code).toBe('MODULE_NOT_FOUND');
+      expect(err.httpStatus).toBe(404);
+      expect(err.message).toContain('id=module-a');
+      expect(err.message).toContain('id=module-b');
+      expect(err.message).toContain('改用模块 id');
+    }
+  });
+
+  it('零命中 → 404 MODULE_NOT_FOUND', () => {
+    expect(() => resolveModuleKey(walk({ modules: [mod('module-a')] }), 'ghost')).toThrowError(AppToolkitError);
+  });
+});
+
+describe('resolveServiceKey（服务双键）', () => {
+  it('词汇键精确命中（vocabulary）', () => {
+    const w = walk({ vocabulary: ['parking.query'] });
+    expect(resolveServiceKey(w, [], 'parking.query')).toBe('parking.query');
+  });
+
+  it('demand 侧命中（catalog.services）', () => {
+    const w = walk({ catalog: { providers: {}, services: { 'auth.x': { optional: true, defaults: [], owners: [] } }, credentialTypes: {} } });
+    expect(resolveServiceKey(w, [], 'auth.x')).toBe('auth.x');
+  });
+
+  it('供给足迹命中（纯供给无词汇/demand——O6 多 impl 形态）', () => {
+    const w = walk({
+      catalog: {
+        providers: { mock: { 'mock-p@1': { provider: 'mock', implementation: 'mock-p@1', credentialType: '-', owner: '@app/provider-mock', services: ['parking.query'] } } },
+        services: {},
+        credentialTypes: {},
+      },
+    });
+    expect(resolveServiceKey(w, [], 'parking.query')).toBe('parking.query');
+  });
+
+  it('configuredKeys 注入命中（已配置未声明槽）', () => {
+    expect(resolveServiceKey(walk(), ['legacy.slot'], 'legacy.slot')).toBe('legacy.slot');
+  });
+
+  it('唯一展示名命中（slotMeta 词汇 meta 源）', () => {
+    const w = walk({
+      vocabulary: ['parking.query', 'parking.payment'],
+      slotMeta: { 'parking.query': { name: '停车查询' } },
+    });
+    expect(resolveServiceKey(w, [], '停车查询')).toBe('parking.query');
+  });
+
+  it('展示名 demand meta 源命中（词汇缺席回落）', () => {
+    const w = walk({
+      vocabulary: ['auth.x'],
+      catalog: { providers: {}, services: { 'auth.x': { optional: true, defaults: [], name: '登录', owners: [] } }, credentialTypes: {} },
+    });
+    expect(resolveServiceKey(w, [], '登录')).toBe('auth.x');
+  });
+
+  it('多展示名命中 → 404 SERVICE_NOT_FOUND + 候选列表', () => {
+    const w = walk({
+      vocabulary: ['a.x', 'b.x'],
+      slotMeta: { 'a.x': { name: '同名' }, 'b.x': { name: '同名' } },
+    });
+    try {
+      resolveServiceKey(w, [], '同名');
+      expect.unreachable('应 throw');
+    } catch (e) {
+      const err = e as AppToolkitError;
+      expect(err.code).toBe('SERVICE_NOT_FOUND');
+      expect(err.httpStatus).toBe(404);
+      expect(err.message).toContain('a.x');
+      expect(err.message).toContain('b.x');
+    }
+  });
+
+  it('零命中 → 404 SERVICE_NOT_FOUND', () => {
+    expect(() => resolveServiceKey(walk({ vocabulary: ['a.x'] }), [], 'ghost')).toThrowError(AppToolkitError);
+  });
+
+  it('原型键不放行（hasOwn 判据——"toString"/"constructor" 非自有键）', () => {
+    expect(() => resolveServiceKey(walk(), [], 'toString')).toThrowError(AppToolkitError);
+    expect(() => resolveServiceKey(walk(), [], 'constructor')).toThrowError(AppToolkitError);
+  });
+});

package/tests/vendor-schema-keywords.test.ts

@@ -22,6 +22,10 @@ const SUPPORTED: ReadonlySet<string> = new Set([
   'format', 'minLength', 'maxLength', 'additionalProperties', '$schema',
   // 结构性（只读降级 + 值保全——支持集含之，出现不红）
   'oneOf', 'anyOf', '$ref', 'items', 'patternProperties',
+  // G 批（v6 全局字段声明）：属性级 x-tbox-global 旗标——表单收窄消费（app/module 轴过滤），
+  // 渲染器不解释（toolkit buildIntegrationFieldRegistry 收集）；Ajv compile 位若未来启用，
+  // 支持集须含本键（当前 config schema 零 compile 位——文档纪律见 integrations-v6 Note）
+  'x-tbox-global',
 ]);
 
 /** 递归走已知 subschema 位，收集 schema 节点自身键（properties 值下的键 = 字段名，不属关键词） */
@@ -98,4 +102,86 @@ describe('vendor schema 关键词矩阵 ⊆ 渲染器支持集（D32 表单引
       expect(used.has(k), `基线关键词 ${k} 未被提取到——提取器或目录布局变化，人工核对`).toBe(true);
     }
   });
+
+  it('B5 展示名 tripwire：全文件 properties.*.title 必在（新字段裸键名结构性不可上线）', () => {
+    const files = schemaFiles();
+    expect(files.length).toBeGreaterThan(5);
+    for (const { pkg, rel } of files) {
+      const doc = JSON.parse(readFileSync(rel, 'utf8')) as { properties?: Record<string, unknown> };
+      for (const [key, sub] of Object.entries(doc.properties ?? {})) {
+        const hasTitle = !!sub && typeof sub === 'object' && typeof (sub as { title?: unknown }).title === 'string';
+        expect(hasTitle, `${pkg} 字段 "${key}" 缺 title——集成配置表单展示名必填（B5 防线；纯名词，长尾注记移 description）`).toBe(true);
+      }
+    }
+  });
+});
+
+describe('G 批 x-tbox-global 标记结构断言（integrations-v6 全局字段声明）', () => {
+  function globalKeysOf(rel: string): string[] {
+    const doc = JSON.parse(readFileSync(rel, 'utf8')) as {
+      properties?: Record<string, { 'x-tbox-global'?: unknown }>;
+    };
+    return Object.entries(doc.properties ?? {})
+      .filter(([, v]) => v && typeof v === 'object' && v['x-tbox-global'] === true)
+      .map(([k]) => k);
+  }
+
+  it('标记值恒布尔 true 且标记键 ∈ properties（结构形状 tripwire）', () => {
+    for (const { pkg, rel } of schemaFiles()) {
+      const doc = JSON.parse(readFileSync(rel, 'utf8')) as {
+        properties?: Record<string, Record<string, unknown>>;
+      };
+      for (const [k, sub] of Object.entries(doc.properties ?? {})) {
+        if (sub && 'x-tbox-global' in sub) {
+          expect(sub['x-tbox-global'], `${pkg} ${k} 标记值恒 true（布尔旗标非枚举位）`).toBe(true);
+        }
+      }
+    }
+  });
+
+  it('mocktest 期望集锁⑥：member/parking/promotion 全局标记键恒等（消费面 S8 互证基线）', () => {
+    // 2026-09-20 拆分：config schema 供给面随 provider-mocktest 迁移（键集不变）
+    const base = join(fileURLToPath(new URL('../../..', import.meta.url)), 'modules', 'provider-mocktest', 'schemas');
+    expect(globalKeysOf(join(base, 'member.config.json')).sort()).toEqual(['cardName', 'initialPoints', 'levelName']);
+    expect(globalKeysOf(join(base, 'parking.config.json'))).toEqual(['parkName']);
+    expect(globalKeysOf(join(base, 'promotion.config.json')).sort()).toEqual(['activityTitle', 'couponTitle']);
+    expect(globalKeysOf(join(base, 'shopping.config.json'))).toEqual([]); // 零声明负例
+    expect(globalKeysOf(join(base, 'mall-info.config.json'))).toEqual([]); // 零声明负例
+  });
+
+  it('素材对账锁：.real-env 全局层键 ⊆ 对应厂商声明并集（mock/mocktest/wanda/joycity 四档）', () => {
+    const repoRoot = fileURLToPath(new URL('../../..', import.meta.url));
+    const collect = (vendor: string): Set<string> => {
+      const out = new Set<string>();
+      for (const f of schemaFiles().filter((x) => x.pkg === `provider-${vendor}`)) {
+        for (const k of globalKeysOf(f.rel)) out.add(k);
+      }
+      return out;
+    };
+    const globalLayerKeys = (vendor: string): Set<string> => {
+      const ig = JSON.parse(readFileSync(join(repoRoot, '.real-env', 'config', vendor, 'integrations.json'), 'utf8')) as {
+        config?: Record<string, unknown>;
+        configByInstance?: Record<string, Record<string, unknown>>;
+        modules?: Record<string, { config?: Record<string, unknown> }>;
+      };
+      const out = new Set<string>();
+      for (const k of Object.keys(ig.config ?? {})) out.add(k);
+      for (const layer of Object.values(ig.configByInstance ?? {})) {
+        for (const k of Object.keys(layer)) out.add(k);
+      }
+      for (const node of Object.values(ig.modules ?? {})) {
+        for (const k of Object.keys(node.config ?? {})) out.add(k);
+      }
+      return out;
+    };
+    // mock 保留 = 空集 tripwire（公开包 0.5.0 零 schema 后任何 config 键混回 mock 档即红）；
+    // mocktest 承接 schema 供给面并续接对账
+    for (const vendor of ['mock', 'mocktest', 'wanda', 'joycity']) {
+      const declared = collect(vendor);
+      const used = globalLayerKeys(vendor);
+      for (const k of used) {
+        expect(declared.has(k), `${vendor} 档全局层键 "${k}" ∉ schema x-tbox-global 声明并集——补标记或改素材（对账锁）`).toBe(true);
+      }
+    }
+  });
 });