@mawaru/sdk 0.5.0

package/_schemas/port-spec.test.ts

@@ -0,0 +1,657 @@
+import { describe, expect, it } from "vitest"
+import type { GraphPort, JsonSchema } from "./node.js"
+import {
+  ANY_SCHEMA,
+  dataFormatOf,
+  dataSchemaOf,
+  envelopeDataSchemaOf,
+  envelopeSchemaOf,
+  fileSchema,
+  isAiEnvelopeSchema,
+  isFileSchema,
+  isSchemaSubset,
+  kindPortsViolation,
+  propagateDerivedPorts,
+  resolvePortSchemas,
+} from "./port-spec.js"
+
+let seq = 0
+const uuid = () => `00000000-0000-4000-8000-${String(++seq).padStart(12, "0")}`
+
+const port = (
+  io: "in" | "out",
+  key: string,
+  schema?: JsonSchema,
+): GraphPort => ({
+  id: uuid(),
+  io,
+  key,
+  name: key,
+  schema: schema ?? ANY_SCHEMA,
+})
+
+describe("データフォーマットカタログ（S）", () => {
+  it("テキスト: S = { type: string } と往復できる", () => {
+    const schema = dataSchemaOf({ format: "text" })
+    expect(schema).toEqual({ type: "string" })
+    expect(dataFormatOf(schema)).toEqual({ format: "text" })
+  })
+
+  it("リスト: 列定義（key・表示名・型）が items に落ち、往復できる", () => {
+    const format = {
+      format: "list" as const,
+      columns: [
+        { key: "to", name: "宛先", type: "string" as const },
+        { key: "amount", name: "金額", type: "number" as const },
+        { key: "paid", name: "支払済", type: "boolean" as const },
+        { key: "due", name: "期日", type: "date" as const },
+      ],
+    }
+    const schema = dataSchemaOf(format)
+    expect(schema).toEqual({
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          to: { type: "string", title: "宛先" },
+          amount: { type: "number", title: "金額" },
+          paid: { type: "boolean", title: "支払済" },
+          due: { type: "string", format: "date", title: "期日" },
+        },
+        required: ["to", "amount", "paid", "due"],
+      },
+    })
+    expect(dataFormatOf(schema)).toEqual(format)
+  })
+
+  it("カタログ外のスキーマは逆引きできない（null）", () => {
+    expect(dataFormatOf({ type: "object" })).toBeNull()
+    expect(
+      dataFormatOf({ type: "array", items: { type: "string" } }),
+    ).toBeNull()
+    expect(dataFormatOf({})).toBeNull()
+  })
+})
+
+describe("封筒型 { data: T, description: string }", () => {
+  it("envelopeSchemaOf：任意の data スキーマを包み、data / description とも必須", () => {
+    const text = envelopeSchemaOf({ type: "string" })
+    expect(text).toEqual({
+      type: "object",
+      properties: {
+        data: { type: "string" },
+        description: { type: "string" },
+      },
+      required: ["data", "description"],
+    })
+    // カタログ外の任意型も包める
+    const custom = {
+      type: "object",
+      properties: { title: { type: "string" }, count: { type: "number" } },
+      required: ["title"],
+    }
+    expect(envelopeSchemaOf(custom).properties).toMatchObject({ data: custom })
+  })
+
+  it("envelopeDataSchemaOf：封筒型なら data のサブスキーマ、そうでなければ null", () => {
+    const dataSchema = { type: "array", items: { type: "string" } }
+    expect(envelopeDataSchemaOf(envelopeSchemaOf(dataSchema))).toEqual(
+      dataSchema,
+    )
+    // data キーが無い / optional / object でない
+    expect(envelopeDataSchemaOf({ type: "object", properties: {} })).toBeNull()
+    expect(
+      envelopeDataSchemaOf({
+        type: "object",
+        properties: { data: { type: "string" } },
+      }),
+    ).toBeNull()
+    expect(envelopeDataSchemaOf({ type: "string" })).toBeNull()
+    expect(envelopeDataSchemaOf(ANY_SCHEMA)).toBeNull()
+  })
+
+  it("isAiEnvelopeSchema：data と description: string の両方が必須のときだけ true", () => {
+    expect(isAiEnvelopeSchema(envelopeSchemaOf({ type: "string" }))).toBe(true)
+    expect(isAiEnvelopeSchema(envelopeSchemaOf({ type: "object" }))).toBe(true)
+    // description が無い / optional / string でない
+    expect(
+      isAiEnvelopeSchema({
+        type: "object",
+        properties: { data: { type: "string" } },
+        required: ["data"],
+      }),
+    ).toBe(false)
+    expect(
+      isAiEnvelopeSchema({
+        type: "object",
+        properties: {
+          data: { type: "string" },
+          description: { type: "string" },
+        },
+        required: ["data"],
+      }),
+    ).toBe(false)
+    expect(
+      isAiEnvelopeSchema({
+        type: "object",
+        properties: {
+          data: { type: "string" },
+          description: { type: "number" },
+        },
+        required: ["data", "description"],
+      }),
+    ).toBe(false)
+    expect(isAiEnvelopeSchema(ANY_SCHEMA)).toBe(false)
+  })
+})
+
+describe("kindPortsViolation（kind 別ポート構成）", () => {
+  it("ai は out の key 自由・複数可。in の key だけ in 固定（AI の複数出口）", () => {
+    expect(
+      kindPortsViolation("ai", [port("in", "in"), port("out", "main")]),
+    ).toBeNull()
+    expect(
+      kindPortsViolation("ai", [port("in", "in"), port("out", "draft")]),
+    ).toBeNull()
+    expect(
+      kindPortsViolation("ai", [
+        port("in", "in"),
+        port("out", "spam"),
+        port("out", "sales"),
+        port("out", "support"),
+      ]),
+    ).toBeNull()
+    expect(
+      kindPortsViolation("ai", [port("in", "input"), port("out", "main")]),
+    ).toMatch(/ai/)
+  })
+
+  it("human は in / approve / reject 固定", () => {
+    expect(
+      kindPortsViolation("human", [
+        port("in", "in"),
+        port("out", "approve"),
+        port("out", "reject"),
+      ]),
+    ).toBeNull()
+    // 旧 ok/ng は違反
+    expect(
+      kindPortsViolation("human", [
+        port("in", "in"),
+        port("out", "ok"),
+        port("out", "ng"),
+      ]),
+    ).toMatch(/human/)
+  })
+
+  it("wait は in / main 固定", () => {
+    expect(
+      kindPortsViolation("wait", [port("in", "in"), port("out", "main")]),
+    ).toBeNull()
+    expect(
+      kindPortsViolation("wait", [port("in", "in"), port("out", "done")]),
+    ).toMatch(/wait/)
+  })
+
+  it("program は out の key 自由・複数可。in の key だけ in 固定", () => {
+    expect(
+      kindPortsViolation("program", [
+        port("in", "in"),
+        port("out", "success"),
+        port("out", "failure"),
+      ]),
+    ).toBeNull()
+    expect(
+      kindPortsViolation("program", [port("in", "input"), port("out", "main")]),
+    ).toMatch(/program/)
+  })
+})
+
+describe("型伝播（導出ポートの解決）", () => {
+  const envelope = envelopeSchemaOf({ type: "string" })
+
+  it("ai → human 直結：approve は封筒を剥がした data 型、reject は content（any）", () => {
+    const aiOut = port("out", "main", envelope)
+    const ai = { id: uuid(), kind: "ai", ports: [port("in", "in"), aiOut] }
+    const humanIn = port("in", "in")
+    const approve = port("out", "approve")
+    const reject = port("out", "reject")
+    const human = {
+      id: uuid(),
+      kind: "human",
+      ports: [humanIn, approve, reject],
+    }
+    const resolved = resolvePortSchemas(
+      [ai, human],
+      [{ from_port_id: aiOut.id, to_port_id: humanIn.id }],
+    )
+    expect(resolved.get(humanIn.id)).toEqual(envelope)
+    expect(resolved.get(approve.id)).toEqual({ type: "string" })
+    expect(resolved.get(reject.id)).toEqual(ANY_SCHEMA)
+  })
+
+  it("ai → wait → human：素通しで封筒型が伝播し、reject は content（any）のまま", () => {
+    // ai の in は宣言型（nodes/ai/<dir>/config.json の inputs.in 由来。実行repoの構造見直し）
+    const aiInSchema = {
+      type: "object",
+      properties: { inquiry: { type: "string" } },
+      required: ["inquiry"],
+    }
+    const aiIn = port("in", "in", aiInSchema)
+    const aiOut = port("out", "main", envelope)
+    const waitIn = port("in", "in")
+    const waitOut = port("out", "main")
+    const humanIn = port("in", "in")
+    const approve = port("out", "approve")
+    const reject = port("out", "reject")
+    const ai = { id: uuid(), kind: "ai", ports: [aiIn, aiOut] }
+    const wait = { id: uuid(), kind: "wait", ports: [waitIn, waitOut] }
+    const human = {
+      id: uuid(),
+      kind: "human",
+      ports: [humanIn, approve, reject],
+    }
+    const conns = [
+      { from_port_id: aiOut.id, to_port_id: waitIn.id },
+      { from_port_id: waitOut.id, to_port_id: humanIn.id },
+    ]
+    const resolved = resolvePortSchemas([ai, wait, human], conns)
+    expect(resolved.get(waitIn.id)).toEqual(envelope)
+    expect(resolved.get(waitOut.id)).toEqual(envelope)
+    expect(resolved.get(humanIn.id)).toEqual(envelope)
+    // 封筒剥がしは「in の直接の接続元が AI ノード」のときだけ。wait 越しは素通し
+    expect(resolved.get(approve.id)).toEqual(envelope)
+    expect(resolved.get(reject.id)).toEqual(ANY_SCHEMA)
+    // ai の in は宣言型がそのまま残る（const 扱いは廃止）
+    expect(resolved.get(aiIn.id)).toEqual(aiInSchema)
+  })
+
+  it("未接続の導出ポート・純パラメトリック閉路は any", () => {
+    const in1 = port("in", "in")
+    const out1 = port("out", "main")
+    const in2 = port("in", "in")
+    const out2 = port("out", "main")
+    const w1 = { id: uuid(), kind: "wait", ports: [in1, out1] }
+    const w2 = { id: uuid(), kind: "wait", ports: [in2, out2] }
+    // w1 → w2 → w1 の閉路（宣言の源泉なし）
+    const resolved = resolvePortSchemas(
+      [w1, w2],
+      [
+        { from_port_id: out1.id, to_port_id: in2.id },
+        { from_port_id: out2.id, to_port_id: in1.id },
+      ],
+    )
+    expect(resolved.get(out1.id)).toEqual(ANY_SCHEMA)
+    expect(resolved.get(out2.id)).toEqual(ANY_SCHEMA)
+  })
+
+  it("program の in は接続鏡映（sticky）：具体型の接続元だけ上書きする", () => {
+    const declared = {
+      type: "object",
+      properties: { inquiry: { type: "string" } },
+      required: ["inquiry"],
+    }
+    const aiOut = port("out", "main", envelope)
+    const ai = { id: uuid(), kind: "ai", ports: [port("in", "in"), aiOut] }
+    const progIn = port("in", "in", declared)
+    const program = {
+      id: uuid(),
+      kind: "program",
+      ports: [progIn, port("out", "main", { type: "object" })],
+    }
+    const resolved = resolvePortSchemas(
+      [ai, program],
+      [{ from_port_id: aiOut.id, to_port_id: progIn.id }],
+    )
+    expect(resolved.get(progIn.id)).toEqual(envelope)
+  })
+
+  it("ai の in も接続鏡映（sticky）：具体型の接続元だけ上書きする", () => {
+    const declared = {
+      type: "object",
+      properties: { topic: { type: "string" } },
+    }
+    const progOut = port("out", "main", envelope)
+    const program = {
+      id: uuid(),
+      kind: "program",
+      ports: [port("in", "in"), progOut],
+    }
+    const aiIn = port("in", "in", declared)
+    const ai = { id: uuid(), kind: "ai", ports: [aiIn, port("out", "main")] }
+    // 具体型の接続元 → 上書き（接続両端の同値同期）
+    const resolved = resolvePortSchemas(
+      [program, ai],
+      [{ from_port_id: progOut.id, to_port_id: aiIn.id }],
+    )
+    expect(resolved.get(aiIn.id)).toEqual(envelope)
+    // 接続元が any（源泉の無い wait）→ 宣言を維持
+    const waitOut = port("out", "main")
+    const wait = {
+      id: uuid(),
+      kind: "wait",
+      ports: [port("in", "in"), waitOut],
+    }
+    const aiIn2 = port("in", "in", declared)
+    const ai2 = { id: uuid(), kind: "ai", ports: [aiIn2, port("out", "main")] }
+    const kept = resolvePortSchemas(
+      [wait, ai2],
+      [{ from_port_id: waitOut.id, to_port_id: aiIn2.id }],
+    )
+    expect(kept.get(aiIn2.id)).toEqual(declared)
+  })
+
+  it("program の in：未接続・接続元 any は宣言スキーマを維持する", () => {
+    const declared = { type: "object" }
+    // 未接続
+    const alone = port("in", "in", declared)
+    const program1 = {
+      id: uuid(),
+      kind: "program",
+      ports: [alone, port("out", "main")],
+    }
+    expect(resolvePortSchemas([program1], []).get(alone.id)).toEqual(declared)
+    // 接続元が any（源泉の無い wait）
+    const waitOut = port("out", "main")
+    const wait = {
+      id: uuid(),
+      kind: "wait",
+      ports: [port("in", "in"), waitOut],
+    }
+    const connected = port("in", "in", declared)
+    const program2 = {
+      id: uuid(),
+      kind: "program",
+      ports: [connected, port("out", "main")],
+    }
+    const resolved = resolvePortSchemas(
+      [wait, program2],
+      [{ from_port_id: waitOut.id, to_port_id: connected.id }],
+    )
+    expect(resolved.get(connected.id)).toEqual(declared)
+  })
+
+  it("program の in：wait 越しでも具体型が鏡映される（固定点反復）", () => {
+    const aiOut = port("out", "main", envelope)
+    const ai = { id: uuid(), kind: "ai", ports: [port("in", "in"), aiOut] }
+    const waitIn = port("in", "in")
+    const waitOut = port("out", "main")
+    const wait = { id: uuid(), kind: "wait", ports: [waitIn, waitOut] }
+    const progIn = port("in", "in", { type: "object" })
+    const program = {
+      id: uuid(),
+      kind: "program",
+      ports: [progIn, port("out", "main")],
+    }
+    const resolved = resolvePortSchemas(
+      [program, wait, ai], // program を先頭に置いても反復で解決される
+      [
+        { from_port_id: aiOut.id, to_port_id: waitIn.id },
+        { from_port_id: waitOut.id, to_port_id: progIn.id },
+      ],
+    )
+    expect(resolved.get(progIn.id)).toEqual(envelope)
+  })
+
+  // start の run 入力契約は接続先から導出する
+  // （開始ノードの入力契約を接続先から導出.md）
+  const startNode = () => {
+    const inPort = port("in", "in")
+    const outMain = port("out", "main")
+    return {
+      node: { id: uuid(), kind: "start", ports: [inPort, outMain] },
+      inPort,
+      outMain,
+    }
+  }
+  const programNode = (declared: JsonSchema) => {
+    const inPort = port("in", "in", declared)
+    return {
+      node: {
+        id: uuid(),
+        kind: "program",
+        ports: [inPort, port("out", "main")],
+      },
+      inPort,
+    }
+  }
+
+  it("start：接続先（program の宣言 in）が out main と in に転写される", () => {
+    const declared = {
+      type: "object",
+      properties: { message: { type: "string" } },
+      required: ["message"],
+    }
+    const start = startNode()
+    const program = programNode(declared)
+    const resolved = resolvePortSchemas(
+      [start.node, program.node],
+      [{ from_port_id: start.outMain.id, to_port_id: program.inPort.id }],
+    )
+    expect(resolved.get(start.outMain.id)).toEqual(declared)
+    expect(resolved.get(start.inPort.id)).toEqual(declared)
+  })
+
+  it("start：未接続は any（ports.schema に古い値が残っていても引きずらない）", () => {
+    const inPort = port("in", "in", { type: "object" })
+    const outMain = port("out", "main", { type: "object" })
+    const start = { id: uuid(), kind: "start", ports: [inPort, outMain] }
+    const resolved = resolvePortSchemas([start], [])
+    expect(resolved.get(outMain.id)).toEqual(ANY_SCHEMA)
+    expect(resolved.get(inPort.id)).toEqual(ANY_SCHEMA)
+  })
+
+  it("start：fan-out で非 any が1種類（program＋導出 wait）ならそれを採用し、wait へも流れる", () => {
+    const declared = {
+      type: "object",
+      properties: { message: { type: "string" } },
+      required: ["message"],
+    }
+    const start = startNode()
+    const program = programNode(declared)
+    const waitIn = port("in", "in")
+    const waitOut = port("out", "main")
+    const wait = { id: uuid(), kind: "wait", ports: [waitIn, waitOut] }
+    const resolved = resolvePortSchemas(
+      [start.node, program.node, wait],
+      [
+        { from_port_id: start.outMain.id, to_port_id: program.inPort.id },
+        { from_port_id: start.outMain.id, to_port_id: waitIn.id },
+      ],
+    )
+    expect(resolved.get(start.inPort.id)).toEqual(declared)
+    expect(resolved.get(waitIn.id)).toEqual(declared)
+    expect(resolved.get(waitOut.id)).toEqual(declared)
+  })
+
+  it("start：fan-out で型が割れたら any", () => {
+    const start = startNode()
+    const a = programNode({
+      type: "object",
+      properties: { a: { type: "string" } },
+      required: ["a"],
+    })
+    const b = programNode({
+      type: "object",
+      properties: { b: { type: "number" } },
+      required: ["b"],
+    })
+    const resolved = resolvePortSchemas(
+      [start.node, a.node, b.node],
+      [
+        { from_port_id: start.outMain.id, to_port_id: a.inPort.id },
+        { from_port_id: start.outMain.id, to_port_id: b.inPort.id },
+      ],
+    )
+    expect(resolved.get(start.outMain.id)).toEqual(ANY_SCHEMA)
+    expect(resolved.get(start.inPort.id)).toEqual(ANY_SCHEMA)
+  })
+
+  it("start：宣言を持たない経路（start → wait → …）は any（パラメトリック閉路の割り切り）", () => {
+    const start = startNode()
+    const waitIn = port("in", "in")
+    const waitOut = port("out", "main")
+    const wait = { id: uuid(), kind: "wait", ports: [waitIn, waitOut] }
+    const resolved = resolvePortSchemas(
+      [start.node, wait],
+      [{ from_port_id: start.outMain.id, to_port_id: waitIn.id }],
+    )
+    expect(resolved.get(start.inPort.id)).toEqual(ANY_SCHEMA)
+    expect(resolved.get(start.outMain.id)).toEqual(ANY_SCHEMA)
+  })
+
+  it("propagateDerivedPorts：schema を書き戻し、変化のないノードは同じ参照を返す", () => {
+    const progOut = port("out", "main", envelope)
+    const program = {
+      id: uuid(),
+      kind: "program",
+      ports: [port("in", "in", { type: "object" }), progOut],
+    }
+    const waitIn = port("in", "in")
+    const wait = {
+      id: uuid(),
+      kind: "wait",
+      ports: [waitIn, port("out", "main")],
+    }
+    const next = propagateDerivedPorts(
+      [program, wait],
+      [{ from_port_id: progOut.id, to_port_id: waitIn.id }],
+    )
+    expect(next[0]).toBe(program) // 宣言のみ＝無変更
+    expect(next[1]?.ports.map((p) => p.schema)).toEqual([envelope, envelope])
+    // 接続を消すと any に戻る
+    const cleared = propagateDerivedPorts(next, [])
+    expect(cleared[1]?.ports.map((p) => p.schema)).toEqual([
+      ANY_SCHEMA,
+      ANY_SCHEMA,
+    ])
+  })
+
+  it("propagateDerivedPorts：side / offset（表示位置）を落とさない", () => {
+    const progOut = {
+      ...port("out", "main", envelope),
+      side: "top" as const,
+      offset: 0.3,
+    }
+    const program = {
+      id: uuid(),
+      kind: "program",
+      ports: [port("in", "in", { type: "object" }), progOut],
+    }
+    const waitIn = port("in", "in")
+    const waitOut = { ...port("out", "main"), side: "left" as const, offset: 1 }
+    const wait = { id: uuid(), kind: "wait", ports: [waitIn, waitOut] }
+    const next = propagateDerivedPorts(
+      [program, wait],
+      [{ from_port_id: progOut.id, to_port_id: waitIn.id }],
+    )
+    // 書き戻しが起きた wait 側でも side / offset が保持される
+    const nextWaitOut = next[1]?.ports.find((p) => p.io === "out")
+    expect(nextWaitOut).toMatchObject({ side: "left", offset: 1 })
+    expect(next[0]?.ports[1]).toMatchObject({ side: "top", offset: 0.3 })
+  })
+})
+
+describe("file 型（nominal）", () => {
+  it("fileSchema はマーカー付き object、isFileSchema で識別できる", () => {
+    const schema = fileSchema()
+    expect(schema["x-mawaru-type"]).toBe("file")
+    expect(schema.required).toEqual(["path", "name"])
+    expect(isFileSchema(schema)).toBe(true)
+    expect(isFileSchema({ type: "object" })).toBe(false)
+    // 構造が file と同じでもマーカーが無ければ file ではない
+    expect(
+      isFileSchema({
+        type: "object",
+        properties: { path: { type: "string" }, name: { type: "string" } },
+        required: ["path", "name"],
+      }),
+    ).toBe(false)
+  })
+
+  it("接続は file 同士だけ可・file → any は可・file と非 file object は不可", () => {
+    const file = fileSchema()
+    const lookalike = {
+      type: "object",
+      properties: { path: { type: "string" }, name: { type: "string" } },
+      required: ["path", "name"],
+    }
+    // file ↔ file
+    expect(isSchemaSubset(file, fileSchema())).toBe(true)
+    // file → any / any → file
+    expect(isSchemaSubset(file, ANY_SCHEMA)).toBe(true)
+    expect(isSchemaSubset(ANY_SCHEMA, file)).toBe(true)
+    // 構造が同じだけの object は file に繋がない（nominal）
+    expect(isSchemaSubset(lookalike, file)).toBe(false)
+    expect(isSchemaSubset(file, lookalike)).toBe(false)
+    // file[] 同士は items が file 同士なら可
+    expect(
+      isSchemaSubset(
+        { type: "array", items: fileSchema() },
+        { type: "array", items: fileSchema() },
+      ),
+    ).toBe(true)
+  })
+})
+
+describe("isSchemaSubset（伝播型 ⊆ 宣言スキーマ）", () => {
+  it("any はどちら向きも許可", () => {
+    expect(isSchemaSubset(ANY_SCHEMA, { type: "object" })).toBe(true)
+    expect(isSchemaSubset({ type: "object" }, ANY_SCHEMA)).toBe(true)
+  })
+
+  it("object：宣言側の required が伝播側に必須として存在し、型互換であること", () => {
+    const sup = {
+      type: "object",
+      properties: { data: { type: "string" } },
+      required: ["data"],
+    }
+    expect(
+      isSchemaSubset(
+        {
+          type: "object",
+          properties: {
+            data: { type: "string" },
+            description: { type: "string" },
+          },
+          required: ["data", "description"],
+        },
+        sup,
+      ),
+    ).toBe(true)
+    // data が無い / optional / 型不一致
+    expect(isSchemaSubset({ type: "object", properties: {} }, sup)).toBe(false)
+    expect(
+      isSchemaSubset(
+        { type: "object", properties: { data: { type: "string" } } },
+        sup,
+      ),
+    ).toBe(false)
+    expect(
+      isSchemaSubset(
+        {
+          type: "object",
+          properties: { data: { type: "number" } },
+          required: ["data"],
+        },
+        sup,
+      ),
+    ).toBe(false)
+  })
+
+  it("type 不一致・array の items 互換", () => {
+    expect(isSchemaSubset({ type: "string" }, { type: "object" })).toBe(false)
+    expect(
+      isSchemaSubset(
+        { type: "array", items: { type: "string" } },
+        { type: "array", items: { type: "string" } },
+      ),
+    ).toBe(true)
+    expect(
+      isSchemaSubset(
+        { type: "array", items: { type: "number" } },
+        { type: "array", items: { type: "string" } },
+      ),
+    ).toBe(false)
+  })
+})