import type { MigrationAnnotation } from "@effect/api-diff/Annotations" import { extractImportMapSections, markdownSafetyIssues, renderMigrationDocument, renderMissingAnnotations } from "@effect/api-diff/MigrationDoc" import type { ApiChange, ApiDiff } from "@effect/api-diff/Model" import { assert, describe, it } from "@effect/vitest" const change = (change: Partial & Pick): ApiChange => ({ id: `change-${change.classification}-${change.baseApiId ?? change.headApiId}`, confidence: 1, authoritative: true, ...change }) const diff: ApiDiff = { version: 1, base: { ref: "v3", sha: "a".repeat(40) }, head: { ref: "main", sha: "b".repeat(40) }, changes: [ change({ classification: "parameter-removed", baseApiId: "effect/Zeta#changed#value", headApiId: "effect/Zeta#changed#value", before: "declare const changed: (value: string) => string", after: "declare const changed: () => string" }), change({ classification: "api-renamed", baseApiId: "effect/Alpha#oldName#value", headApiId: "effect/Alpha#newName#value" }), change({ classification: "api-removed", baseApiId: "effect/Alpha#oldName#value" }), change({ classification: "api-removed", baseApiId: "effect/Beta#removed#value", before: "declare const removed: string" }), change({ classification: "api-moved", baseApiId: "effect/Legacy#keptName#value", headApiId: "effect/Current#keptName#value" }), change({ classification: "api-removed", baseApiId: "effect/Legacy#keptName#value" }), change({ classification: "documentation-changed", baseApiId: "effect/Zeta#documented#value" }), change({ classification: "parameter-added", baseApiId: "effect/Zeta#optional#value", headApiId: "effect/Zeta#optional#value", delta: { before: [], after: [{ name: "options", type: { kind: "primitive", name: "string" }, optional: true, rest: false }] } }), change({ classification: "api-added", headApiId: "effect/Zeta#added#value" }) ] } const annotations = new Map([ ["effect/Alpha#oldName", { replacement: "Alpha.newName", note: "Use the renamed function." }] ]) describe("migration document", () => { it("renders the selected API changes deterministically", () => { const document = renderMigrationDocument( diff, annotations, "## Import Map\n\n```text\neffect/Alpha -> effect/Alpha\n```\n" ) assert.strictEqual( document, [ "", "", "# v3 to v4 Migration Reference", "", `Base: \`v3\` (\`${"a".repeat(40)}\`)`, "", `Head: \`main\` (\`${"b".repeat(40)}\`)`, "", "This file is generated from the API diff and `migration/annotations/*.yaml`.", "", "## Import Map", "", "```text", "effect/Alpha -> effect/Alpha", "```", "", "## Removed Modules", "", "No modules were removed.", "", "## API Reference", "", "### `effect/Alpha`", "", "- `Alpha.oldName` -> `Alpha.newName`: Use the renamed function.", "", "### `effect/Beta`", "", "- `Beta.removed`: TODO: needs guidance", "", "### `effect/Zeta`", "", "- `Zeta.changed`: TODO: needs guidance", "" ].join("\n") ) assert(!document.includes("keptName")) assert(!document.includes("documented")) assert(!document.includes("optional")) assert(!document.includes("added")) }) it("lists unannotated ids grouped by module", () => { assert.strictEqual( renderMissingAnnotations(diff, annotations), "effect/Beta:\n - effect/Beta#removed\neffect/Zeta:\n - effect/Zeta#changed\n" ) }) it("renders guidance and examples for detailed changes", () => { const document = renderMigrationDocument( diff, new Map([...annotations, ["effect/Zeta#changed", { replacement: "Zeta.changed()", note: "Call the zero-argument form.", example: "Zeta.changed()" }]]), "## Import Map\n" ) assert(document.includes("**Replacement:** `Zeta.changed()`")) assert(document.includes("Call the zero-argument form.")) assert(document.includes("**Example**\n\n```ts\nZeta.changed()\n```")) assert(!document.includes("**Before**")) assert(!document.includes("**After**")) }) it.each([ { name: "plain", example: "const value = 1", fence: "```" }, { name: "empty", example: "", fence: "```" }, { name: "single backticks", example: "const value = `text`", fence: "```" }, { name: "double backticks", example: "// ``literal``", fence: "```" }, { name: "triple backticks", example: "/*\n```text\nliteral\n```\n*/", fence: "````" }, { name: "four backticks", example: "/*\n````text\nliteral\n````\n*/", fence: "`````" }, { name: "longest run last", example: "const value = `text`\n/*\n```\n`````\n*/", fence: "``````" }, { name: "whitespace", example: "\n const value = 1 \n\n", fence: "```" }, { name: "many backtick runs", example: "// ` ".repeat(400_000), fence: "```" } ])("preserves example framing: $name", ({ example, fence }) => { const document = renderMigrationDocument( diff, new Map([...annotations, ["effect/Zeta#changed", { replacement: "Zeta.changed()", note: "Call the zero-argument form.", example }]]), "## Import Map\n" ) assert.strictEqual(document.split("**Example**\n\n")[1], `${fence}ts\n${example}\n${fence}\n`) assert.deepStrictEqual(markdownSafetyIssues(document), []) }) it.each([ { name: "compact", example: undefined }, { name: "detailed", example: "Zeta.changed()" } ])("renders replacements with many backtick runs in $name entries", ({ example }) => { const replacement = "// ` ".repeat(400_000) const document = renderMigrationDocument( diff, new Map([...annotations, ["effect/Zeta#changed", { replacement, note: "Use the replacement.", example }]]), "## Import Map\n" ) assert(document.includes("``" + replacement + "``")) assert.deepStrictEqual(markdownSafetyIssues(document), []) }) it("escapes annotation prose while preserving inline code and fenced examples", () => { const document = renderMigrationDocument( diff, new Map([...annotations, ["effect/Zeta#changed", { replacement: "Zeta.changed()", note: "Use ~effect/Zeta with Effect, *literal*, snake_case, `Context.Context`, and a bare ` marker.", example: "const marker = `~effect/Zeta<*>`" }]]), "## Import Map\n" ) assert(document.includes( "Use \\~effect/Zeta with Effect\\, \\*literal\\*, snake\\_case, `Context.Context`, and a bare \\` marker." )) assert(document.includes("```ts\nconst marker = `~effect/Zeta<*>`\n```")) assert.deepStrictEqual(markdownSafetyIssues(document), []) assert.deepStrictEqual(markdownSafetyIssues("Unsafe ~~note and Effect"), [ "line 1: unescaped \"~\"", "line 1: unescaped \"~\"", "line 1: unescaped \"<\"" ]) }) it("retains annotated removals that also have move suggestions", () => { const serviceDiff: ApiDiff = { ...diff, changes: [ change({ classification: "api-moved", baseApiId: "effect/Effect#Service#value", headApiId: "effect/Context#Service#value", authoritative: false }), change({ classification: "api-removed", baseApiId: "effect/Effect#Service#value", before: "declare const Service: unknown" }) ] } const document = renderMigrationDocument( serviceDiff, new Map([["effect/Effect#Service", { replacement: "Context.Service", note: "Use the v4 service constructor." }]]), "## Import Map\n" ) assert(document.includes("- `Effect.Service` -> `Context.Service`: Use the v4 service constructor.")) }) it("renders removed modules and omits unchanged APIs moved with them", () => { const moduleDiff: ApiDiff = { ...diff, changes: [ change({ classification: "module-removed", delta: { from: "effect/Legacy", to: [] } }), change({ classification: "api-removed", baseApiId: "effect/Legacy#unchanged#value", before: "declare const unchanged: string" }), change({ classification: "api-added", headApiId: "effect/Current#unchanged#value", after: "declare const unchanged: string" }), change({ classification: "api-removed", baseApiId: "effect/Legacy#changed#value", before: "declare const changed: string" }), change({ classification: "api-added", headApiId: "effect/Current#changed#value", after: "declare const changed: number" }) ] } const document = renderMigrationDocument( moduleDiff, new Map([["effect/Legacy#changed", { replacement: "Current.changed", note: "Use the changed API." }]]), "## Import Map\n\neffect/Legacy -> effect/Current\n" ) assert(document.includes("## Removed Modules\n\n- `effect/Legacy` -> `effect/Current`")) assert(!document.includes("Legacy.unchanged")) assert(document.includes("- `Legacy.changed` -> `Current.changed`: Use the changed API.")) assert.strictEqual( extractImportMapSections(document), "## Import Map\n\neffect/Legacy -> effect/Current\n" ) }) it.each(["LF", "CRLF", "mixed"])("preserves %s import-map replacement guidance", (ending) => { const moduleDiff: ApiDiff = { ...diff, changes: [ change({ classification: "module-removed", delta: { from: "effect/Legacy", to: [] } }), change({ classification: "api-removed", baseApiId: "effect/Legacy#unchanged#value", before: "declare const unchanged: string" }), change({ classification: "api-added", headApiId: "effect/Current#unchanged#value", after: "declare const unchanged: string" }) ] } const eol = ending === "LF" ? "\n" : "\r\n" const authored = [ "## Import Map", "", "```text", "effect/Legacy -> effect/Other", "effect/Legacy -> effect/Current (barrel: effect)", "effect/Legacy -> effect/Current", "```", "", "## No Counterpart Imports", "", "None." ].join(eol) const section = ending === "mixed" ? authored.replace("## Import Map\r\n", "## Import Map\n") : authored const importMap = extractImportMapSections( `# Existing reference${eol}${section}${eol}${eol}## Removed Modules${eol}Old guidance.` ) const moduleAnnotations = new Map() const document = renderMigrationDocument(moduleDiff, moduleAnnotations, importMap) assert.strictEqual(importMap, `${section}\n`) assert.strictEqual(extractImportMapSections(document), importMap) assert(document.includes("## Removed Modules\n\n- `effect/Legacy` -> `effect/Other`, `effect/Current`\n")) assert(!document.includes("Legacy.unchanged")) assert.strictEqual( renderMissingAnnotations(moduleDiff, moduleAnnotations, importMap), "All migration APIs and removed modules have guidance.\n" ) }) it("uses exact removed-module guidance for APIs without replacements", () => { const moduleDiff: ApiDiff = { ...diff, changes: [ change({ classification: "module-removed", delta: { from: "effect/Legacy", to: [] } }), change({ classification: "api-removed", baseApiId: "effect/Legacy#removed#value", before: "declare const removed: string" }), change({ classification: "api-removed", baseApiId: "effect/Legacy#replaced#value", before: "declare const replaced: string" }), change({ classification: "api-removed", baseApiId: "effect/LegacyExtra#removed#value", before: "declare const removed: string" }), change({ classification: "api-removed", baseApiId: "effect/Current#removed#value", before: "declare const removed: string" }) ] } const moduleAnnotations = new Map([ ["effect/Legacy", { replacement: "none", note: "The module was removed." }], ["effect/Legacy#replaced", { replacement: "Current.replaced", note: "Use the replacement." }], ["effect/LegacyExtra#removed", { replacement: "none", note: "This similarly prefixed module still exists." }], ["effect/Current#removed", { replacement: "none", note: "This module still exists." }] ]) const document = renderMigrationDocument(moduleDiff, moduleAnnotations, "## Import Map\n") assert(document.includes("- `effect/Legacy` -> `none`: The module was removed.")) assert(!document.includes("Legacy.removed")) assert(document.includes("- `Legacy.replaced` -> `Current.replaced`: Use the replacement.")) assert(document.includes("- `LegacyExtra.removed` -> `none`: This similarly prefixed module still exists.")) assert(document.includes("- `Current.removed` -> `none`: This module still exists.")) assert.strictEqual( renderMissingAnnotations(moduleDiff, moduleAnnotations), "All migration APIs and removed modules have guidance.\n" ) }) it("keeps removals from relocated modules and modules without module guidance", () => { const moduleDiff: ApiDiff = { ...diff, changes: [ change({ classification: "module-removed", delta: { from: "effect/Relocated", to: [] } }), change({ classification: "module-removed", delta: { from: "effect/Unguided", to: [] } }), change({ classification: "api-removed", baseApiId: "effect/Relocated#removed#value" }), change({ classification: "api-removed", baseApiId: "effect/Unguided#removed#value" }) ] } const moduleAnnotations = new Map([ ["effect/Relocated", { replacement: "effect/Current", note: "The module moved." }], ["effect/Relocated#removed", { replacement: "none", note: "This API was not moved." }], ["effect/Unguided#removed", { replacement: "none", note: "This API was removed." }] ]) const document = renderMigrationDocument(moduleDiff, moduleAnnotations, "## Import Map\n") assert(document.includes("- `effect/Relocated` -> `effect/Current`: The module moved.")) assert(document.includes("- `Relocated.removed` -> `none`: This API was not moved.")) assert(document.includes("- `Unguided.removed` -> `none`: This API was removed.")) assert.strictEqual( renderMissingAnnotations(moduleDiff, moduleAnnotations), "All migration APIs and removed modules have guidance.\n" ) }) it("uses per-API annotations for split modules and reports missing module guidance", () => { const moduleDiff: ApiDiff = { ...diff, changes: [ change({ classification: "module-removed", delta: { from: "effect/Split", to: [] } }), change({ classification: "module-removed", delta: { from: "effect/Unknown", to: [] } }), change({ classification: "api-removed", baseApiId: "effect/Split#removed#value", before: "declare const removed: string" }) ] } const splitAnnotations = new Map([["effect/Split#removed", { replacement: "Current.removed", note: "Use the split replacement." }]]) const document = renderMigrationDocument(moduleDiff, splitAnnotations, "## Import Map\n") assert( document.includes("- `effect/Split`: No single module replacement; follow the curated per-API guidance below.") ) assert(document.includes("- `effect/Unknown`: TODO: needs module guidance")) assert.strictEqual( renderMissingAnnotations(moduleDiff, splitAnnotations), "Removed modules:\n - effect/Unknown\n" ) }) })