@calltea/pr-lens-schema (法语)

PR Lens合约. 提取出这些文件,由渲染器消耗,而其他表面(CLI,GitHub Action,代理技能,主机应用)都传出. 如果一个文件在这里被验证, 则可以安全渲染 .

麻省理工学院 Coldtea AI.

pnpm add @coldtea/pr-lens-schema

import { parseGraphDoc, safeParseGraphDoc } from "@coldtea/pr-lens-schema";

const graph = parseGraphDoc(json);          // throws PrLensSchemaError
const result = safeParseGraphDoc(json);     // { ok: true, value } | { ok: false, error }

四份文件

每个文件都包含 schemaVersion,包括: 存储器的校正必须随着合同的移动而保持其意义.

意见及其含义

名单还列出嵌入其中的走道 walkthrough,每半个主题组合中有一个条目,当文档带出巡演时;它坐落在视图资产旁边而不是其中,因此从不与下方的视图上限相抵.

每个主题的渲染是每个视图的一个资产,所以钻倒树的大小和显示的渲染是一条规则,而不是两个数字:

MAX_VIEWS * THEMES.length === MAX_RENDER_ASSETS; // 128 * 2 === 256

视图树上的每个阵列都封顶了,但是它的深度没有,所以总数以 graphIntegrityIssues: 载有比清单所描述的更多观点的文件在此遭到拒绝,而不是在制作者处遭到拒绝,否则,制作者将保留它被告知的文件。 导入 MAX_VIEWS, (中文(简体) ), MAX_RENDER_ASSETS 财务报告和审定财务报表 THEMES 而不是重复其中任何一项:提出预算或增加一个主题,另一端随它而去.

盖子是最糟糕的,每个主题, 而不是一个特定的表达。 单一主题可描述两倍于其他观点,但文件是否可以翻译将取决于要求如何提供,以及 如果它解析,它使 是这个软件包的保证.

三道镜头

architecture 显示与现有系统相撞的爆炸半径. data-flow 动画一个订购的管道. data-model 绘制表格中的更改和它们之间的键。 故意没有安全镜头,也没有发现领域:PR Lens是理解层,载有发现的文件被拒绝,而不是悄悄地剥去. 这个 Lens enum是添加剂:未来的合同版本可能会添加透镜,所以将您不识别的透镜视为跳过,而不是失败.

数据模型

更改了计划的文件可能载有: dataModel,然后宣布 data-model 镜片.

dataModel: {
  stores: [{ id: "billing", label: "Billing", platform: "Postgres" }],
  tables: [
    {
      id: "subscription",
      label: "Subscription",
      store: "billing",
      name: "subscriptions",
      delta: "modified",
      badges: ["key moved"],
      columns: [
        { name: "id", type: "uuid", key: "primary", delta: "unchanged" },
        { name: "user_id", type: "uuid", key: "foreign", delta: "removed" },
        { name: "org_id", type: "uuid", key: "foreign", delta: "added" },
        { name: "amount_cents", type: "bigint", previousType: "int", delta: "modified" },
      ],
      files: [{ path: "migrations/0042_billing_by_org.sql", startLine: 36, endLine: 48 }],
    },
  ],
  relations: [
    {
      id: "subscription-user",
      from: { table: "subscription", column: "user_id" },
      to: { table: "user", column: "id" },
      delta: "removed",
      label: "billed to the user until now",
    },
  ],
}

A 类 store 是一个数据库、一个计划或一个命名空间:一个表格所坐入的车道,其头有平台。 A 类 table 是一个表格,一个收藏或一个关键家族, 并列出它的柱子 每一个三角洲, 因此一个掉出柱子被划穿, 一个到达绿色。 类型已改变的列 previousType所以照片上说 int → bigintA级 type 这是一个名字,就像计划拼写它: uuid, (中文(简体) ), text[], (中文(简体) ), numeric(5,4), (中文(简体) ), timestamp with time zone。引文、等号、斜线、结肠或 -- 在类型名称中没有位置,在默认、字节、连接字符串或注释中,每个位置都不存在,因此一个带有一个字的类型被拒绝:图片显示数据的形状,从不显示数据. key 标记表格本身的密钥,或索引行。 A 类 relation 从它指向的一列起; enforced: false 引出一个不执行的参考物,比如一个跨商店的,作为一个被点缀的行.

三角洲与其它地方一样有四个. 标记的关系 removed 是一个被删除的更改,以及它的 label 在哪里说它过去的意思.

观点可以涵盖范围 tables,一个走过的步骤可以突出它们,一个引用可以命名一个表格或一栏: { "kind": "table", "table": "subscription" } 或者说 { "kind": "column", "table": "subscription", "column": "org_id" }。 。 。 .

校验器检查每个表格都坐落在一个申报的商店里,没有表格列出一列两次,每个关系都结束在表格的一栏上,并且带有数据模型的文档宣布镜头. 一个存储的地图从不携带一个:一个数据模型显示一个被触摸到的表格,一个地图描述一个系统.

走过

文件可载有: walkthrough。 。 。 .

walkthrough: {
  steps: [
    {
      id: "four-batch-calls",
      heading: "Postmark now gets 500 emails per call",
      body: "One call per batch, and Postmark answers with a result for each message.",
      stage: { kind: "flow", flow: "send-pipeline" },
      focus: { kind: "selection", messages: ["batch-post", "batch-results"] },
      detail: {
        text: "sendBroadcastBulk posts each batch to Postmark and reads the results back.",
        cites: [
          { text: "sendBroadcastBulk", ref: { kind: "node", node: "send-broadcast-bulk" } },
          { text: "posts each batch", ref: { kind: "message", flow: "send-pipeline", message: "batch-post" } },
          { text: "Postmark", ref: { kind: "node", node: "postmark" } },
        ],
      },
    },
    {
      id: "old-path-goes-dark",
      heading: "processBroadcast and sendSingleEmail removed",
      body: "sendBroadcastBulk does their job for whole batches.",
      stage: { kind: "view", view: "retired-path" },
      focus: { kind: "selection", nodes: ["process-broadcast", "send-single-email"] },
    },
  ],
}

行走就是短时间的导游参观图表。 它有两到十二步。 每个步骤都显示一个图,点到其中的一部分,并说出一些关于它的话.

每个步骤有:

• heading:事和所出事事,有多达48个字符,为句子相. 例如"邮戳现在每通电话得到500个电子邮件".

• body:标题下一行,最多140个字符,关于改变意味着什么行为. 例如"每批一通电话而不是每人一通电话". 没有身体的标本读作未完成,所以解析器需要一个.

• stage: 要显示哪个图表 。 文档可以有多个图:其视图(自钻出图)和流出(序列图). { "kind": "view", "view": "overview" } 显示名为 overview。 。 。 . { "kind": "flow", "flow": "send-pipeline" } 显示调用的流动 send-pipeline离开 stage 退出,步骤使用读取器已经打开的图表.

• focus(笑声) (掌声) (掌声) (掌声) (掌声) (掌声) (掌声) (掌声) (掌声) (掌声) (掌声) (掌声) (掌声) (掌声). { "kind": "all" } 指整个图. 选择是指"只是这些东西":命名任何道道,节点,边缘或流阶(messages由id, 相机放大他们 而其他的一切暗淡。 选择必须至少命名一件事.

• detail:可选. 在正文下方有一到两句,可达240个字符,这些字符取出节点的名称,流出步骤并归档该步骤的相關. 例如"发送Broadcast Bulk将每批发到Postmark并读取结果回". 尸体没有链接,所以他们到这里. text 这是句子. cites 列出其中的单词名称, 以及每个单词的指向, 这些单词被绘制为链接。 一个引用 text 从细节中完全复制出来 text,以及 ref 这是:

  • { "kind": "node", "node": "postmark" } 作为节点,
  • { "kind": "message", "flow": "send-pipeline", "message": "batch-post" } 为一阶而行,
  • { "kind": "view", "view": "overview" } 或者说 { "kind": "flow", "flow": "send-pipeline" } 为了图,
  • { "kind": "file", "path": "functions/src/broadcast/send.ts" } 用于仓库中的文件.

  List引用了这句话的顺序 细节需要一到八 离开 detail 走出了毫无关联的一步.

验证器检查 :

• 文档中存在您所命名的每个 ID 。 您命名的流程步骤必须属于舞台所显示的流程,因为流程步骤标识只在自身流程内是独一无二的.
• messages 需要一个能显示流量的舞台。 当舞台是建筑风景时别管了.
• 每个引用的词出现在其细节的文本中,按照引用的顺序列出,没有两个引用的词是共享的. 文档中存在所引用的节点,流程步骤,视图或流程. 引用的文件只必须是寄存器内部的路径,因为文档不持有文件,无法检查文件是否存在.
• 步道标识在走道内是独一无二的. 最少两步,最多十二步.
• 存储的地图从不带行走道. 一张地图描述了系统;一个走行道讲述了一个变化的故事.

当一个补丁或一个更正从文档中去除某事时,走行部会如下:一个步骤会丢失已经去掉的名字,一个步骤会留下一无所剩的指向或者其图被丢弃,如果剩下不到两个步骤,走行部会被丢弃. 所列举的已经消失的东西也被删除,其文字作为简洁的文字保留在细节上。 留下的没有引用的细节被删除,步骤保留了身体. pruneWalkthrough 并导出用于删除文档部分的其他任何内容.

detailParts 按读取顺序将一个细节的文本分割为平方行和引用的运行。 每一个引用的运行带有其 ref。 。 。 .

三角洲

每个节点、边缘和流动步骤都声明它与基地的关系: added, (中文(简体) ), modified, (中文(简体) ), removed 或者说 unchanged。 。 。 . unchanged 元素是审查者判断爆炸半径所需的上下文,因此它们属于文档,而不是被过滤出.

验证范围

解析在一次通过 四个事情, 并报告每一个问题 它发现而不是仅仅第一个:

1. 结构: 类型、 长度、 enums、 没有未知的密钥, 以及文件路径, 这些路径实际上可以成为 diff permalink( repository- relative, POSIX, no) .. 分节).
2. 合同版本:同一少校和第一个合同发运的未成年人(0.1{\fn黑体\fs22\bord1\shad0\3aHBE\4aH00\fscx67\fscy66\2cHFFFFFF\3cH808080}直到这个包裹的自己 较新的未成年人被拒绝,因为它可能携带一个字段,而这个字段是发明的.
3. 参考完整性:每个节点坐落在一个已宣布的道上,每个边缘会加入已宣布的节点,每个流程步骤会贯穿于已宣布的参与者之间,每个已存在的钻下视图和布局提示名称元素,每个行走步骤会显示文档已有的图表,并聚焦和引用其已有的元素,一个载有流程的文档会宣布 data-flow 镜片.
4. 翻译可以描述该文件:见下文.

比堆栈走得更深的文档被报告为无法读取的过深文档,而不是被扔出: safeParse* 返回任意一个结果.

失败的到来 PrLensSchemaError 有机器可读 code (单位:千美元)INVALID_DOCUMENT, (中文(简体) ), BROKEN_REFERENCE, (中文(简体) ), DUPLICATE_ID, (中文(简体) ), UNSUPPORTED_SCHEMA_VERSION, (中文(简体) ), PATCH_CONFLICT, (中文(简体) ), NOT_A_SNAPSHOT和一个 issues 每个带路径和消息的阵列.

正在生成存储的图表

applyPatchDoc(graph, patch) 是补丁操作的可执行定义 :

import { applyPatchDoc, parseGraphDoc, parsePatchDoc } from "@coldtea/pr-lens-schema";

const result = applyPatchDoc(parseGraphDoc(baseline), parsePatchDoc(patch));

• 一个补丁命名它的目标地图和它携带它之间的承诺: graphId, (中文(简体) ), fromSha 财务报告和审定财务报表 toSha 所有要求,它们都是40个特征的 名字,它们必须不同。 简称对于一个人类读取的东西来说是罚款的,但是对于决定两个记录是否意味着同样的承诺,一个不移动地图的补丁是可以重放的补丁.
• 在应用任何内容之前检查目标:一个针对另一个地图的补丁,或者针对一个承诺写成的地图已经过去,是 PATCH_CONFLICT 而不是合并.
• 存储的地图是快照而不是diff:它有一个ID,它记录它完全反射的单一承诺 base 财务报告和审定财务报表 head,其中没有任何说明是改变. graphSnapshotIssues 这是规则,用于任何存储地图 applyPatchDoc 在进出的路上运行, 所以一个补丁既不能留下一个注释 也不能清洗一个已经带一个的地图。 失败的是 NOT_A_SNAPSHOT 并点出罪犯的名字, 下到一流的阶梯.
• 目标规则在内部重新检查 applyPatchDoc 而不是从解析中信任,因为被解析的半导体不能存活到推断的类型:a PatchDoc 召集的电话员与来自 parsePatchDoc。 。 。 .
• 操作按阵列顺序适用,第一次冲突停止了批次,因为后来的操作被写成针对原计划制作的状态.
• add_* 拒绝取回的id; update_* 财务报告和审定财务报表 remove_* 拒绝一个缺失的id; update_* 只写它命名的字段.
• 删除一个节点会取出它的边缘并与之相接而来流出步道,并会掉出一个留有不到两个参与者或没有步道的流道. 删除的 ids 从自钻下行的树和布局提示被挤出,一个其选择丢失其最后元素的视图被丢弃而不是被拓宽.
• 一次通过一次,对照所制作的操作文件,而不是同时进行。 一个步骤命名一个图表以及元素,这样它就可以命名树棱花刚刚掉落的视图,一个重写出一流的步子的更新将焦点成员带走,而不去掉其他花棱花会注意到的任何东西. 一个台阶已经走光了,或者焦点失去了最后元素的台阶也随之而去,一个仅剩了不到两步的巡演也随之而去. 重点流量步骤是对照该步骤自己阶段所绘制的流量来衡量的,从不对照整个文件.
• 删除仍然保持节点的道是冲突,而不是级联:先移动其节点.
• remove_* 从存储的图表中删除元素。 这个说法与 delta: "removed",它表示一个元素仍然存在,但正被审查中的修改所删除.
• 成功的结果总是通过的文件 parseGraphDoc: 候选人在返回前被整体验证.

输入文档从未变异 . applyPatch(graph, ops) 对于已经知道自己持有的文档的呼叫者来说,没有目标检查也是一样.

一个存储的地图描述了一个系统而不是一个变化,所以里面的一切都是 unchanged 联 合 国 base 等于其为 head; 三角洲属于拉请求文档.

仓库配置

# .github/pr-lens.yml
schemaVersion: 0.1.0
lenses: [architecture, data-flow, data-model]
branding: true
glossary: docs/CONTEXT.md#Language
github:
  draw: auto
  description: true
  comment:
    collapsed: false
    notice: true
map:
  rename:
    - match: functions/src/broadcast/sendBroadcastBulk.ts
      to: Broadcast sender
  exclude:
    - "**/*.test.ts"
  lane:
    - match: packages/broadcast-lib/**
      lane: functions
  group:
    - match: id:build-bulk-payload
      group: broadcast-lib

A 类 match 从开始 id: 完全地址一个节点; 其它的都是与节点文件路径相匹配的路径 glob, 因此在运行之间重命名节点的模型存活下来的更正 。 校正是对每跑一次的 新的推论的叠加 推论从不写回这个文件.

glossary 命名寄存器中一个可解释团队自身对系统术语的markdown文件,因此绘图,行走和画布使用这些单词而不是代码. 标题之后 # 缩小为一节. 托管的App从公关的头上读取.

托管的 App 读取 github 来自 PR 头部的设置 。 其他选项适用于CLI.

杰森·斯克马

json-schema/*.json (草案2020-12)由zod schemas生成并随包一起发布,用于不运行TypeScript的制作人和编辑验证 .github/pr-lens.yml数字 :

{ "$ref": "node_modules/@coldtea/pr-lens-schema/json-schema/graph-doc.schema.json" }

他们描述 作者可以写什么: 默认的字段是您可以忽略的字段 。 在JSON Schema可以说明的地方执行规则: 支持的合同版本、存储器-相对路径规则, endLine 需求 startLine,需要 url 或一个 path页:1 selection 视图需要选择一些东西.

JSON Schema不能说出七条规则

1. 各种要素之间的优待完整性,包括指向文字的走道,其细节并不表示,
2. 开始前结束的行范围,
3. 自我信息终点之间的协议,
4. 一条带子,两条带子是一样的,
5. 更多的观点,而不是表白,
6. 一个突出流出步骤的走行部位 其舞台上的图不会绘制,
7. 序列化后,在更深于8个水平或超过4096个字节的流量流程步骤上取样(a) shape 超过 2048 字节:JSON Schema 计数字符,而不是字节.

测试通过陈述和坚持同一判决,接受和拒绝文件表,包括上面的每个分歧案件,因此它们都是故意的,不能悄悄地增长到八分之一.

黄金

examples/ 持有参考文件,也可导入预分解:

import { postmarkRefactorGraph } from "@coldtea/pr-lens-schema/examples";

他们讲述了一个故事:一个真正的重构,将广播从每个接收者一个邮戳请求传送到500个批次:

• postmark-refactor.graph.json 是条条形文档:拉力请求本身,跨越三道,行使所有四个三角洲状态,一个英雄边缘,一个七步数据流有回放和一连串的分批步骤,一个嵌入式钻倒树,以及一个六步行走,这段行走既分取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取 下游出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出.
• broadcast-baseline.graph.json 作为 main 站在变化之前 broadcast-baseline.patch.json 把它带到合并的州,过渡 applyPatchDoc 执行.
• payload.graph.json 是拉行请求文档,其七个流程步骤中的六个有样本流量: 批量呼叫的两边, a before 这与它的 sample页:1 void 反应,还有一步空出.
• billing-org.graph.json 是数据模型的参考:计费从个人移动到组织,有两个表格到达,一个键将一个表格留给另一个表格,一个被丢弃的一列,一个被拓宽的型号,以及一个走过的数据模型视图.
• postmark-refactor.render-manifest.json 使拉动请求文件产生的东西, pr-lens.config.json 存放处的更正,以及 minimal.graph.json 用于验证的最小文档.

版本

SCHEMA_VERSION 是合同版本,它独立于此软件包的版本。 一个不改变合同、文件固定或其他补丁的发布, 运送一个新的软件包版本并离开 SCHEMA_VERSION 在它的位置,所以一个与旧字符串相对应的文档会继续解析. 微量释放只添加可选字段或拓宽一个enum,一个解析器接受来自 0.1 最多自有文件: 以 0.1.1 仍然打开在 0.2.0 参数和a 0.3.0 文档被一个拒绝,直到读取它的文件包。 主要释放可能去掉或重打字段.

合同 0.2.0 已添加 payload 流程步骤:作为JSON值的样本流量,用于移动数据的步骤.

合同 0.3.0 添加 data-model 镜头和 dataModel 文档上:表格中被触动的更改及其之间的密钥,与 tables 范围和步骤的重点 table 财务报告和审定财务报表 column 引用.

合同 0.3.1 已添加 walkthrough 到一个渲染表:走行道嵌入,每半个主题对一个条目,旁边是视图资产.

部分 PR 镜头审查什么才是真正重要的.