@tbox.cn/app-toolkit 0.2.0 → 0.4.0

package/tests/demo-app.ts

@@ -50,6 +50,11 @@ export interface FakeContractsOptions {
   resolveBody?: string;
   /** service-slots.json 词汇（P9 身份判据/求值键集；缺省不物化 = 词汇空） */
   slots?: string[];
+  /** 词汇 meta 节（per-service {title,description}——B1 展示名链 fixture） */
+  meta?: Record<string, { title?: string; description?: string }>;
+  /** service-slots.json 落位：'root' = 包根（缺省——夹具/旧布局形态）；
+   *  'src' = 包内 src/（发布包 src 附带 / shim 链接形态——B0 探测跳 ②） */
+  slotsLayout?: 'root' | 'src';
   /** zod 形拒绝 fixture（A1 T9/T10）：parseIntegrationsConfig 恒抛带 issues 的结构化错误
    *  （结构性 ZodError 形——issues[].path 供 fields 断言；仅在专属 fixture 上使用） */
   zodRejectPaths?: string[][];
@@ -58,7 +63,7 @@ export interface FakeContractsOptions {
 /** 假 contracts 包：package.json exports 形态逐字段复刻发布面（types+import 双条件、无 require/default）
  *  ——resolver 不经 exports 解析（包根直探），该形态为 E4 类错误的机械防线。 */
 export function writeFakeContractsPackage(packageRoot: string, opts: FakeContractsOptions = {}): void {
-  const { version = '0.9.0', withStrict = true, withDist = true, brokenDist = false, missingEvaluationExports = false, rejectMarker, resolveBody, slots, zodRejectPaths } = opts;
+  const { version = '0.9.0', withStrict = true, withDist = true, brokenDist = false, missingEvaluationExports = false, rejectMarker, resolveBody, slots, meta, slotsLayout = 'root', zodRejectPaths } = opts;
   const strictBody = withStrict
     ? `export function parseIntegrationsConfig(raw) { ${
         rejectMarker ? `if (JSON.stringify(raw).includes(${JSON.stringify(rejectMarker)})) throw new Error("fake strict reject"); ` : ''
@@ -113,12 +118,31 @@ export function writeFakeContractsPackage(packageRoot: string, opts: FakeContrac
     mkdirSync(join(packageRoot, 'src'), { recursive: true });
     writeFileSync(join(packageRoot, 'src', 'runtime.ts'), exportsBody);
   }
-  // service-slots.json（P9 词汇源——探测链发现位 = 包根；缺省不物化 = 词汇空）
+  // service-slots.json（P9 词汇源——探测三跳发现位；缺省不物化 = 词汇空；
+  // slotsLayout 控制包根/src 落位——B0 探测跳①/②）
   if (slots && slots.length > 0) {
-    writeFileSync(join(packageRoot, 'service-slots.json'), `${JSON.stringify({ slots }, null, 2)}\n`);
+    const slotsFile = slotsLayout === 'src' ? join(packageRoot, 'src', 'service-slots.json') : join(packageRoot, 'service-slots.json');
+    mkdirSync(dirname(slotsFile), { recursive: true });
+    writeFileSync(slotsFile, `${JSON.stringify(meta ? { slots, meta } : { slots }, null, 2)}\n`);
   }
 }
 
+/**
+ * 候选自身 src 词汇包（B0 探测跳 ③——local/codegen 全量副本形态）：
+ * 落 <appDir>/packages/<name>/src/service-slots.json（无 package.json/node_modules——
+ * mall 生成应用主形态：stage rewriteExportsToSrc 展开后永驻 packages/*，不依赖 install）。
+ */
+export function writeSelfSrcContractPackage(
+  appDir: string,
+  name: string,
+  content: { slots: string[]; meta?: Record<string, { title?: string; description?: string }> },
+): string {
+  const dir = join(appDir, 'packages', name, 'src');
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, 'service-slots.json'), `${JSON.stringify(content, null, 2)}\n`);
+  return join(appDir, 'packages', name);
+}
+
 export interface LinkOptions {
   /** 候选子目录：''（appDir 根）/ 'apps/server' / 'apps/client' / 'packages/<id>' */
   subdir: string;

package/tests/dev-manifest-catalog.test.ts

@@ -2,7 +2,7 @@ import { describe, it, expect, afterEach } from 'vitest';
 import { mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { walkManifests } from '../src/assembly/walk-manifests.js';
-import { createTempApp, type TempApp } from './demo-app.js';
+import { createTempApp, linkContracts, writeFakeContractsPackage, writeSelfSrcContractPackage, type TempApp } from './demo-app.js';
 
 /**
  * dev-manifest catalog 通道（通道 1.5）单测：聚合宽/声明窄不变量锁定。
@@ -112,3 +112,83 @@ describe('walkManifests · dev-manifest catalog 通道（聚合宽/声明窄）'
     expect(walk.modules).toHaveLength(0);
   });
 });
+
+/**
+ * 词汇探测三跳（B0 回归锁）：词汇源三真实布局全覆盖——
+ * ① nm 包根（夹具/旧布局）② nm src/（发布包 src 附带 + 模板 shim 链接）③ 候选自身 src/
+ * （local/codegen 全量副本——mall 生成应用主形态，不依赖 install）。
+ * 修复前探测只扫包根 → 三形态全 miss（vocabulary 恒空）。
+ */
+describe('walkManifests · 词汇探测三跳 + slotMeta（B0）', () => {
+  it('P1: nm 包根布局（跳①）→ vocabulary 命中；slotMeta 透传', () => {
+    app = createTempApp('tbox-probe-');
+    const store = join(app.appDir, '_store-a');
+    writeFakeContractsPackage(store, {
+      slots: ['auth.alipay-login', 'mall.info'],
+      meta: { 'auth.alipay-login': { title: '支付宝登录', description: '登录换码（code2Session）' } },
+    });
+    linkContracts(app.appDir, store, { subdir: 'apps/server' });
+
+    const walk = walkManifests(app.appDir);
+    expect(walk.vocabulary).toEqual(['auth.alipay-login', 'mall.info']);
+    expect(walk.slotMeta['auth.alipay-login']).toEqual({ title: '支付宝登录', description: '登录换码（code2Session）' });
+    expect(walk.slotMeta['mall.info']).toBeUndefined(); // meta 缺席槽不入表
+  });
+
+  it('P2: nm src 布局（跳②——发布包 src 附带 / shim 链接形态）→ 命中', () => {
+    app = createTempApp('tbox-probe-');
+    const store = join(app.appDir, '_store-b');
+    writeFakeContractsPackage(store, { slots: ['parking.query'], slotsLayout: 'src' });
+    linkContracts(app.appDir, store, { subdir: 'apps/server' });
+
+    const walk = walkManifests(app.appDir);
+    expect(walk.vocabulary).toEqual(['parking.query']);
+  });
+
+  it('P3: 候选自身 src 布局（跳③——local/codegen 全量副本，无 node_modules 链接）→ 命中', () => {
+    app = createTempApp('tbox-probe-');
+    writeSelfSrcContractPackage(app.appDir, 'contracts-mall', {
+      slots: ['member.account', 'parking.payment'],
+      meta: { 'member.account': { title: '会员账户' } },
+    });
+
+    const walk = walkManifests(app.appDir);
+    expect(walk.vocabulary).toEqual(['member.account', 'parking.payment']);
+    expect(walk.slotMeta['member.account']).toEqual({ title: '会员账户' });
+  });
+
+  it('P4: 多包同槽 meta → 发现序首声明胜出（apps/* 先于 packages/* 候选序）', () => {
+    app = createTempApp('tbox-probe-');
+    const storeA = join(app.appDir, '_store-first');
+    writeFakeContractsPackage(storeA, { slots: ['x.y'], meta: { 'x.y': { title: '甲' } } });
+    linkContracts(app.appDir, storeA, { subdir: 'apps/server' });
+    const storeB = join(app.appDir, '_store-second');
+    writeFakeContractsPackage(storeB, { slots: ['x.y'], meta: { 'x.y': { title: '乙' } } });
+    linkContracts(app.appDir, storeB, { subdir: 'packages/mock' });
+
+    const walk = walkManifests(app.appDir);
+    expect(walk.slotMeta['x.y']).toEqual({ title: '甲' });
+  });
+
+  it('P5: 坏 meta 条目（非对象/非 string/空串）→ 宽松跳过，slots 正常', () => {
+    app = createTempApp('tbox-probe-');
+    const store = join(app.appDir, '_store-bad');
+    writeFakeContractsPackage(store, { slots: ['a.b'] });
+    writeFileSync(
+      join(store, 'service-slots.json'),
+      JSON.stringify({ slots: ['a.b', 'c.d', 'e.f'], meta: { 'a.b': '字符串', 'c.d': { title: 42 }, 'e.f': { title: '甲', description: '' } } }),
+    );
+    linkContracts(app.appDir, store, { subdir: 'apps/server' });
+
+    const walk = walkManifests(app.appDir);
+    expect(walk.vocabulary).toEqual(['a.b', 'c.d', 'e.f']);
+    expect(walk.slotMeta).toEqual({ 'e.f': { title: '甲' } }); // 空串 description 不入表（与 title 守卫对称）
+  });
+
+  it('P6: 无契约包（退化态）→ vocabulary 空 + slotMeta 空（P9 退化路径语义锁）', () => {
+    app = createTempApp('tbox-probe-');
+    const walk = walkManifests(app.appDir);
+    expect(walk.vocabulary).toEqual([]);
+    expect(walk.slotMeta).toEqual({});
+  });
+});

package/tests/file-cache.test.ts

@@ -180,7 +180,9 @@ describe('Freshness Contract W3/W7 — agent 动线矩阵（工厂方法级；FX
       }),
     );
     const modules = await tk.loadModules();
-    expect(modules.modules.map((m) => m.id)).toContain('provider-x');
+    // provider 家族包不在清单（2026-09-16 bug-fix）——排除本身随目录新增即时生效；
+    // loadModules 新鲜度由下方 case c（module-sdk-y）承载，供给轴新鲜度见下两行
+    expect(modules.modules.map((m) => m.id)).not.toContain('provider-x');
     const providers = await tk.loadProviders();
     expect(providers.providers.map((p) => p.provider)).toContain('joycity');
 

package/tests/module-schema.test.ts

@@ -81,4 +81,19 @@ describe('module-schema（descriptor zod 单源）', () => {
       expect(parsed.data.contributes.resources).toEqual([]);
     }
   });
+
+  it('B1 模块 meta additive：根级 title/description 保真；缺席仍合法（回退归视图层）', () => {
+    const withMeta = parseModuleDescriptor({ ...BASE_MANIFEST, title: '停车缴费', description: '车辆查询与绑定、停车费用查询、缴费支付与开票' });
+    expect(withMeta.ok).toBe(true);
+    if (withMeta.ok) {
+      expect(withMeta.value.title).toBe('停车缴费');
+      expect(withMeta.value.description).toContain('停车费用查询');
+    }
+    const withoutMeta = moduleDescriptorSchema.safeParse(BASE_MANIFEST);
+    expect(withoutMeta.success).toBe(true);
+    if (withoutMeta.success) {
+      expect(withoutMeta.data.title).toBeUndefined();
+      expect(withoutMeta.data.description).toBeUndefined();
+    }
+  });
 });

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

@@ -98,4 +98,16 @@ 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);
+      }
+    }
+  });
 });