Files
effect/packages/tools/api-diff/test/Diff.test.ts
T

220 lines
8.0 KiB
TypeScript

import { diffSnapshots } from "@effect/api-diff/Diff"
import type { ApiDiff, ApiEntity, ApiSnapshot, DeclarationModel } from "@effect/api-diff/Model"
import { renderMarkdownReport } from "@effect/api-diff/Report"
import { assert, describe, it } from "@effect/vitest"
const entity = (
module: string,
name: string,
declaration: DeclarationModel,
hash: string
): ApiEntity => ({
id: `${module}#${name}#value`,
packageName: module.split("/")[0]!,
module,
path: [name],
bucket: "value",
declarationKind: declaration.kind,
importRoutes: [{ module, path: [name] }],
declarations: [declaration],
displaySignature: `declare const ${name}: unknown`,
fingerprint: hash,
documentation: { stability: "stable" },
source: { file: `${name}.d.ts`, line: 1, column: 1 }
})
const snapshot = (ref: string, entities: ReadonlyArray<ApiEntity>): ApiSnapshot => ({
version: 1,
compiler: { name: "typescript", version: "fixture" },
ref,
sha: ref.repeat(40).slice(0, 40),
packages: ["old", "new"],
entrypoints: [],
entities,
diagnostics: []
})
describe("snapshot diff", () => {
it("matches renames, classifies signature changes, and separates suggestions", () => {
const base = snapshot("a", [
entity("old/A", "changed", {
kind: "function",
name: "changed",
parameters: [{ name: "value", type: { kind: "primitive", name: "string" }, optional: false, rest: false }],
returnType: { kind: "primitive", name: "string" }
}, "before"),
entity("old/A", "similarName", {
kind: "variable",
name: "similarName",
type: { kind: "primitive", name: "string" }
}, "x"),
entity(
"old/A",
"removed",
{ kind: "variable", name: "removed", type: { kind: "primitive", name: "string" } },
"r"
)
])
const head = snapshot("b", [
entity("old/A", "changed", {
kind: "function",
name: "changed",
parameters: [
{ name: "value", type: { kind: "primitive", name: "string" }, optional: false, rest: false },
{ name: "count", type: { kind: "primitive", name: "number" }, optional: true, rest: false }
],
returnType: { kind: "primitive", name: "number" }
}, "different"),
entity("old/A", "similarNames", {
kind: "variable",
name: "similarNames",
type: { kind: "primitive", name: "number" }
}, "y"),
entity("old/A", "added", { kind: "variable", name: "added", type: { kind: "primitive", name: "string" } }, "a")
])
const diff = diffSnapshots(base, head)
assert(diff.changes.some((change) => change.classification === "parameter-added"))
assert(diff.changes.some((change) => change.classification === "return-type-changed"))
assert(diff.changes.some((change) => change.baseApiId?.includes("similarName") && !change.authoritative))
assert(
diff.changes.some((change) =>
change.classification === "api-removed" && change.baseApiId?.includes("similarName")
)
)
assert(
diff.changes.some((change) => change.classification === "api-added" && change.headApiId?.includes("similarNames"))
)
const report = renderMarkdownReport(diff)
assert(report.includes("Suggested replacements for removed APIs"))
assert(report.includes(base.sha))
assert.deepStrictEqual(diff, diffSnapshots(base, head))
})
it("suggests replacements across modules and preserves class facets", () => {
const variable = (name: string): DeclarationModel => ({
kind: "variable",
name,
type: { kind: "primitive", name: "unknown" }
})
const serviceInterface = (name: string, extraMember?: string): DeclarationModel => ({
kind: "interface",
name,
members: [
{
kind: "method",
name: "context",
parameters: [],
returnType: { kind: "primitive", name: "unknown" }
},
{
kind: "method",
name: "of",
parameters: [],
returnType: { kind: "primitive", name: "unknown" }
},
...(extraMember === undefined
? []
: [{
kind: "method",
name: extraMember,
parameters: [],
returnType: { kind: "primitive", name: "unknown" }
}])
]
})
const withBucket = (api: ApiEntity, bucket: ApiEntity["bucket"]): ApiEntity => ({
...api,
id: `${api.module}#${api.path.join(".")}#${bucket}`,
bucket
})
const effectService = {
...entity("effect/Effect", "Service", variable("Service"), "effect-service"),
documentation: {
summary: "Creates a Context Tag and Layer for a service.",
stability: "stable" as const
}
}
const contextTagValue = entity("effect/Context", "Tag", variable("Tag"), "tag-value")
const contextTagType = withBucket(
entity("effect/Context", "Tag", serviceInterface("Tag"), "tag-type"),
"type"
)
const contextServiceValue = entity("effect/Context", "Service", variable("Service"), "service-value")
const contextServiceType = withBucket(
entity("effect/Context", "Service", serviceInterface("Service", "use"), "service-type"),
"type"
)
const layerMapService = entity("effect/LayerMap", "Service", variable("Service"), "layer-map-service")
const diff = diffSnapshots(
snapshot("a", [effectService, contextTagType, contextTagValue]),
snapshot("b", [contextServiceType, contextServiceValue, layerMapService])
)
const suggestions = diff.changes.filter((change) => !change.authoritative)
assert(suggestions.some((change) =>
change.baseApiId === "effect/Effect#Service#value" &&
change.headApiId === "effect/Context#Service#value"
))
assert(suggestions.some((change) =>
change.baseApiId === "effect/Context#Tag#type" &&
change.headApiId === "effect/Context#Service#type"
))
assert(suggestions.some((change) =>
change.baseApiId === "effect/Context#Tag#value" &&
change.headApiId === "effect/Context#Service#value"
))
assert(!suggestions.some((change) => change.headApiId === "effect/LayerMap#Service#value"))
assert.strictEqual(diff.changes.filter((change) => change.classification === "api-removed").length, 3)
assert.strictEqual(diff.changes.filter((change) => change.classification === "api-added").length, 3)
})
it("classifies overload and parameter reordering", () => {
const signature = (name: string, parameters: ReadonlyArray<"left" | "right">): DeclarationModel => ({
kind: "function",
name,
parameters: parameters.map((parameter) => ({
name: parameter,
type: { kind: "primitive", name: "string" },
optional: false,
rest: false
})),
returnType: { kind: "primitive", name: "string" }
})
const before = entity("old/A", "ordered", signature("ordered", ["left", "right"]), "before")
const after = entity("old/A", "ordered", signature("ordered", ["right", "left"]), "after")
const diff = diffSnapshots(
snapshot("a", [before]),
snapshot("b", [after])
)
assert(diff.changes.some((change) => change.classification === "parameter-reordered"))
})
it("groups package and module changes by their delta names", () => {
const report = renderMarkdownReport(
{
version: 1,
base: { ref: "a", sha: "a".repeat(40) },
head: { ref: "b", sha: "b".repeat(40) },
changes: [
{
id: "package-removed",
classification: "package-removed",
confidence: 1,
delta: { packageName: "@effect/old" },
authoritative: true
},
{
id: "module-added",
classification: "module-added",
confidence: 1,
delta: { to: ["effect/New"] },
authoritative: true
}
]
} satisfies ApiDiff
)
assert(report.includes("| @effect/old | @effect/old | 1 |"))
assert(report.includes("| stable | effect/New | 1 |"))
assert(!report.includes("<package>"))
})
})