@vizejs/marquette

每个Vize目标的键入应用程序市场。

实验性的：序列化契约是版本化的，但TypeScript API可以 在验证目标适配器时进行演进。

马奎特是一种小型的、语言中立的描述，由网络、本地、 桌面、终端、后端、传输、测试和图库工具。这 包提供了保留文字的TypeScript创作。运行时验证是 可通过单独入口获得，同时实现规范化和兼容性 分析仍然集中在层次上。

作者：马奎特

import { defineApplicationMarquette } from "@vizejs/marquette";

export default defineApplicationMarquette({
  application: "shop",
  targets: ["web", "native"],
  environments: [
    {
      id: "web",
      target: "web",
      consumer: "client",
      runtime: "browser",
    },
    {
      id: "native",
      target: "native",
      consumer: "client",
      runtime: "native",
    },
    {
      id: "server",
      target: "web",
      consumer: "server",
      runtime: "rust",
    },
  ],
  backends: [
    {
      id: "api",
      family: "rust",
      environment: "server",
    },
  ],
  protocols: [
    {
      id: "api.query",
      family: "schema-query",
      backend: "api",
    },
  ],
  routes: [
    {
      id: "home",
      path: "/",
      environment: "web",
      rendering: "hybrid",
      backend: "api",
      protocol: "api.query",
    },
  ],
});

环境依赖关系、后端所有者、协议所有者和路由 根据同一对象中声明的标识符检查引用。一个 因此，拼写错误的引用是一个编写错误，而不是运行时错误 惊喜。

运行时验证

当契约跨文件、流程或文件时，使用专用验证项 语言的界限:

import { validateApplicationMarquette } from "@vizejs/marquette/validate";

const diagnostics = validateApplicationMarquette(shop);
for (const diagnostic of diagnostics) {
  console.error(diagnostic.code, diagnostic.path, diagnostic.message);
}

验证是确定的，不会改变所创建的对象，并报告 与本机契约实现共享的稳定代码。保持在一个 单独条目意味着仅用于创作的应用程序不包括验证 代码。

适配器能力协商

适配器发布包含的功能-版本范围独立于 应用马凯特。应用程序功能定义是权威 的要求;未声明的需求无法关闭，即使适配器 提供具有相同标识符的功能。只有适配器的功能是 允许并保持添加，直到应用程序需要它们。

import {
  negotiateAdapterCapabilities,
  type AdapterCapabilityManifest,
} from "@vizejs/marquette/adapter";

const adapter = {
  adapter: "terminal.fresco",
  capabilities: [{ id: "terminal.color", minVersion: 1, maxVersion: 3 }],
} satisfies AdapterCapabilityManifest;

const result = negotiateAdapterCapabilities(
  marquette,
  marquette.environments?.[0]?.capabilities ?? [],
  adapter,
);
if (!result.compatible) {
  console.error(result.diagnostics, result.mismatches);
}

精确匹配和包含绑定匹配是兼容的。失踪的支持, 要求低于适配器的最小值，要求高于适配器的最大值 使用马厩 missing-capability， version-below-minimum, version-above-maximum 代码。每个不匹配也带有确定性 path 和 message，因此本机适配器诊断可以在没有 特定于目标的字符串格式化。增加或扩大支撑区间 界是加性的；移除支撑或缩小任何一个边界都是突破。 协商和兼容性报告都是确定排序的 而不是改变它们的输入。的验证诊断 当其中一个输入无效时，两者都显示并忽略更改。已发布的清单架构可从 @vizejs/marquette/adapter/schema.

本机呈现适配器共享一个封闭的版本一基准进行呈现， 事件、布局、文本、图像、动画、可访问性和生命周期：

import { nativeEngineCapabilityProfile } from "@vizejs/marquette/adapter";

const nativeAdapter = {
  adapter: "native.example",
  capabilities: nativeEngineCapabilityProfile(),
};

规范标识符使用 native.* 命名空间中发出的 稳定的订单。帮助器返回新值，以便适配器可以添加private 功能，而不更改其他消费者使用的基线。

测试的证据

发布绑定的测试运行证据记录存在于它们自己的惰性条目中，因此 部署工具可以绑定 tests 检查保留的、不可变的事实：

import { defineTestRunEvidence } from "@vizejs/marquette/test-run";
import { validateTestRunEvidence } from "@vizejs/marquette/test-run/validate";
import { testRunAdmissionId } from "@vizejs/marquette/test-run/canonical";
import { admitTestRun, decideTestRunAdmission } from "@vizejs/marquette/test-run/admission";
import { verifyTestRunCheck } from "@vizejs/marquette/test-run/check";
import { verifyTestRunTransition } from "@vizejs/marquette/test-run/transition";

const diagnostics = validateTestRunEvidence(evidence);
const admissionId = await testRunAdmissionId(evidence); // test-run:<sha256>
const rejections = await admitTestRun(evidence, candidate, admissionId, now);
const decision = await decideTestRunAdmission(evidence, candidate, admissionId, now);
if (!decision.allowed) {
  console.error(decision.denialCodes); // e.g. ["record-expired"]
}
const release = await verifyTestRunCheck(retainedCheck, candidate, evidence, now);
const journal = await verifyTestRunTransition(nextTransition, chainTip);

验证共享其 VIZE_MARQUETTE_1xx 代码、路径和排序 本机实现，规范化条目产生的字节相同 串行化和SHA-256指纹，通过在共享fixture中验证 tests/fixtures/test-run-evidence/。录取决定是稳定的， 每个后端家族共享的仅追加拒绝码词汇表；相同的 fixture固定每个决定，因此JavaScript， Rust， Go或JVM拒绝 相同的机器可读原因。检查项替换每个泛型 发布证据中的测试结果参考：保留 vize.test-run.check 记录可能只列出确切的名称 test-run:<sha256> 入场id，绑定六 候选人的事实，并记录独立于竞选者的观察者。这个 产品化条目使每个发布决定和完整的被接受 反重放状态一个持久的原子记录，由规范的SHA-256链接 指纹;主机使用write-then-atomic-rename对其进行持久化，并验证 在决定做任何新事情之前收回小费。发布的记录模式为 可以从 @vizejs/marquette/test-run/schema，决定契约从 @vizejs/marquette/test-run/admission/schema，测试检查合同来自 @vizejs/marquette/test-run/check/schema的过渡合同 @vizejs/marquette/test-run/transition/schema.

担保

• 确切的标识符仍然可用为 EnvironmentId， BackendId， ProtocolId, RouteId 工会。
• defineApplicationMarquette 返回其输入而不分配或 规范化。
• 发布的应用程序契约模式可从 @vizejs/marquette/schema.
• 已发布的适配器清单架构可从 @vizejs/marquette/adapter/schema.
• 每个可选的契约字段在JSDoc中记录其默认值。
• 包构建对创作条目强制执行1 KiB的gzip预算和3 KiB的预算 或4 KiB预算用于验证条目。

马奎特描述组件和环境；它不编写UI 组件。公共Vize UI组件使用real .vue SFC文件作为它们的 规范的来源，从来没有写过 h() 调用或手写呈现函数。