sailfork / t3code-github / .repos/ effect/ packages/ tools/ api-diff/ src/ MigrationDoc.ts

import type { MigrationAnnotation } from "./Annotations.ts"
import type { ApiChange, ApiDiff, ChangeClassification } from "./Model.ts"

const breakingClassifications = new Set<ChangeClassification>([
  "bucket-changed",
  "declaration-kind-changed",
  "overload-removed",
  "overload-reordered",
  "parameter-removed",
  "parameter-reordered",
  "parameter-changed",
  "return-type-changed",
  "generic-parameter-changed",
  "member-removed",
  "member-changed",
  "heritage-changed",
  "union-member-changed",
  "intersection-member-changed",
  "structural-change"
])

const stableApiId = (id: string): string => id.replace(/#(?:type|value)$/, "")

const displayApiId = (id: string): string => {
  const separator = id.indexOf("#")
  if (separator === -1) {
    return id
  }
  const module = id.slice(0, separator).split("/").at(-1)!
  return `${module}.${id.slice(separator + 1)}`
}

const backtickDelimiter = (value: string, minimum: number): string => {
  let length = minimum
  for (const match of value.matchAll(/`+/g)) {
    length = Math.max(length, match[0].length + 1)
  }
  return "`".repeat(length)
}

const codeSpan = (value: string): string => {
  const delimiter = backtickDelimiter(value, 1)
  const content = value.startsWith("`") || value.endsWith("`") ? ` ${value} ` : value
  return `${delimiter}${content}${delimiter}`
}

const escapeMarkdownText = (value: string): string => value.replace(/\\/g, "\\\\").replace(/[~<>*_]/g, "\\

Loading Sailfork

amp;") const escapeAnnotationText = (value: string): string => { const output: Array<string> = [] let index = 0 while (index < value.length) { const start = value.indexOf("`", index) if (start === -1) { output.push(escapeMarkdownText(value.slice(index))) break } output.push(escapeMarkdownText(value.slice(index, start))) let end = start + 1 while (value[end] === "`") { end++ } const delimiter = value.slice(start, end) const close = value.indexOf(delimiter, end) if (close === -1) { output.push("\\`".repeat(delimiter.length)) index = end } else { output.push(value.slice(start, close + delimiter.length)) index = close + delimiter.length } } return output.join("") } const compareStrings = (left: string, right: string): number => left < right ? -1 : left > right ? 1 : 0 const isBreakingChange = (change: ApiChange): boolean => { if (change.classification !== "parameter-added") { return breakingClassifications.has(change.classification) } const delta = change.delta as { readonly before?: ReadonlyArray<unknown> readonly after?: ReadonlyArray<{ readonly optional?: boolean; readonly rest?: boolean }> } | undefined const beforeLength = delta?.before?.length ?? 0 return delta?.after?.slice(beforeLength).some((parameter) => !parameter.optional && !parameter.rest) ?? true } interface MigrationEntry { readonly id: string readonly module: string readonly rename: ApiChange | undefined } const importMapReplacements = (importMapSections: string): ReadonlyMap<string, ReadonlyArray<string>> => { const replacements = new Map<string, Array<string>>() for (const line of importMapSections.split(/\r?\n/)) { const match = /^(\S+) -> (\S+)(?: \(barrel: [^)]+\))?$/.exec(line) if (match === null) { continue } const targets = replacements.get(match[1]!) if (targets === undefined) { replacements.set(match[1]!, [match[2]!]) } else if (!targets.includes(match[2]!)) { targets.push(match[2]!) } } return replacements } const removedModules = (diff: ApiDiff): ReadonlyArray<string> => [ ...new Set(diff.changes.flatMap((change) => { if (change.classification !== "module-removed") { return [] } const from = (change.delta as { readonly from?: unknown } | undefined)?.from return typeof from === "string" ? [from] : [] })) ].sort(compareStrings) const sameStrings = (left: ReadonlyArray<string>, right: ReadonlyArray<string>): boolean => left.length === right.length && left.every((value, index) => value === right[index]) const addedApiSignatures = (diff: ApiDiff): ReadonlyMap<string, ReadonlyArray<string>> => { const signatures = new Map<string, Array<string>>() for (const change of diff.changes) { if (change.classification !== "api-added" || change.headApiId === undefined || change.after === undefined) { continue } const id = stableApiId(change.headApiId) const group = signatures.get(id) if (group === undefined) { signatures.set(id, [change.after]) } else { group.push(change.after) } } for (const group of signatures.values()) { group.sort(compareStrings) } return signatures } const isUnchangedModuleMove = ( id: string, changes: ReadonlyArray<ApiChange>, removed: ReadonlySet<string>, replacements: ReadonlyMap<string, ReadonlyArray<string>>, addedSignatures: ReadonlyMap<string, ReadonlyArray<string>> ): boolean => { const separator = id.indexOf("#") const module = id.slice(0, separator) const targets = replacements.get(module) if (separator === -1 || !removed.has(module) || targets === undefined) { return false } const before = changes .filter((change) => change.classification === "api-removed" && change.before !== undefined) .map((change) => change.before!) .sort(compareStrings) if (before.length === 0) { return false } const path = id.slice(separator + 1) return targets.some((target) => { const after = addedSignatures.get(`${target}#${path}`) return after !== undefined && sameStrings(before, after) }) } const isRemovalCoveredByModule = ( id: string, removed: ReadonlySet<string>, annotations: ReadonlyMap<string, MigrationAnnotation> ): boolean => { const separator = id.indexOf("#") const module = id.slice(0, separator) if (separator === -1 || !removed.has(module) || annotations.get(module)?.replacement !== "none") { return false } const annotation = annotations.get(id) return annotation === undefined || annotation.replacement === "none" } const migrationEntries = ( diff: ApiDiff, annotations: ReadonlyMap<string, MigrationAnnotation>, importMapSections: string ): ReadonlyArray<MigrationEntry> => { const grouped = new Map<string, Array<ApiChange>>() for (const change of diff.changes) { if (change.baseApiId === undefined) { continue } const id = stableApiId(change.baseApiId) const changes = grouped.get(id) if (changes === undefined) { grouped.set(id, [change]) } else { changes.push(change) } } const entries: Array<MigrationEntry> = [] const removedModuleSet = new Set(removedModules(diff)) const replacements = importMapReplacements(importMapSections) const addedSignatures = addedApiSignatures(diff) for (const [id, changes] of grouped) { const rename = changes.find((change) => change.classification === "api-renamed") const breaking = changes.some(isBreakingChange) const removed = changes.some((change) => change.classification === "api-removed") const importMove = changes.some((change) => change.classification === "api-moved") if ( isUnchangedModuleMove(id, changes, removedModuleSet, replacements, addedSignatures) || (removed && isRemovalCoveredByModule(id, removedModuleSet, annotations)) || (!breaking && rename === undefined && !removed) || (importMove && rename === undefined && !breaking && !annotations.has(id)) ) { continue } entries.push({ id, module: id.split("#")[0]!, rename }) } for (const [id, annotation] of annotations) { if (annotation.include === true && id.includes("#") && !entries.some((entry) => entry.id === id)) { entries.push({ id, module: id.split("#")[0]!, rename: undefined }) } } return entries.sort((left, right) => compareStrings(left.module, right.module) || compareStrings(left.id, right.id)) } const renderDetailedEntry = ( entry: MigrationEntry, annotation: MigrationAnnotation, example: string ): ReadonlyArray<string> => { const fence = backtickDelimiter(example, 3) return [ `#### ${codeSpan(displayApiId(entry.id))}`, "", `**Replacement:** ${codeSpan(annotation.replacement)}`, "", escapeAnnotationText(annotation.note), "", "**Example**", "", `${fence}ts`, example, fence, "" ] } const renderCompactEntry = ( entry: MigrationEntry, annotation: MigrationAnnotation | undefined ): string => { if (annotation !== undefined) { return `- ${codeSpan(displayApiId(entry.id))} -> ${codeSpan(annotation.replacement)}: ${ escapeAnnotationText(annotation.note) }` } const target = entry.rename?.headApiId return target === undefined ? `- ${codeSpan(displayApiId(entry.id))}: TODO: needs guidance` : `- ${codeSpan(displayApiId(entry.id))} -> ${codeSpan(displayApiId(stableApiId(target)))}: TODO: needs guidance` } export const extractImportMapSections = (document: string): string => { const start = document.indexOf("## Import Map") if (start === -1) { return "## Import Map\n\nNo import map is available.\n" } const apiRenames = document.indexOf("\n## API Renames", start) const removedModules = document.indexOf("\n## Removed Modules", start) const apiReference = document.indexOf("\n## API Reference", start) const ends = [apiRenames, removedModules, apiReference].filter((index) => index !== -1) const end = ends.length === 0 ? document.length : Math.min(...ends) return `${document.slice(start, end).trim()}\n` } export const renderMigrationDocument = ( diff: ApiDiff, annotations: ReadonlyMap<string, MigrationAnnotation>, importMapSections: string ): string => { const entries = migrationEntries(diff, annotations, importMapSections) const replacements = importMapReplacements(importMapSections) const modulesRemoved = removedModules(diff) const modules = new Map<string, Array<MigrationEntry>>() for (const entry of entries) { const group = modules.get(entry.module) if (group === undefined) { modules.set(entry.module, [entry]) } else { group.push(entry) } } const lines = [ "<!-- dprint-ignore-file -->", "", "# v3 to v4 Migration Reference", "", `Base: \`${diff.base.ref}\` (\`${diff.base.sha}\`)`, "", `Head: \`${diff.head.ref}\` (\`${diff.head.sha}\`)`, "", "This file is generated from the API diff and `migration/annotations/*.yaml`.", "", importMapSections.trim(), "", "## Removed Modules", "" ] for (const module of modulesRemoved) { const annotation = annotations.get(module) const targets = replacements.get(module) if (annotation !== undefined) { lines.push( `- ${codeSpan(module)} -> ${codeSpan(annotation.replacement)}: ${escapeAnnotationText(annotation.note)}` ) } else if (targets !== undefined) { lines.push(`- ${codeSpan(module)} -> ${targets.map(codeSpan).join(", ")}`) } else if ([...annotations.keys()].some((id) => id.startsWith(`${module}#`))) { lines.push(`- ${codeSpan(module)}: No single module replacement; follow the curated per-API guidance below.`) } else { lines.push(`- ${codeSpan(module)}: TODO: needs module guidance`) } } if (modulesRemoved.length === 0) { lines.push("No modules were removed.") } lines.push( "", "## API Reference", "" ) for (const [module, moduleEntries] of modules) { lines.push(`### ${codeSpan(module)}`, "") for (const entry of moduleEntries) { const annotation = annotations.get(entry.id) if (annotation?.example !== undefined) { lines.push(...renderDetailedEntry(entry, annotation, annotation.example)) } else { lines.push(renderCompactEntry(entry, annotation), "") } } } return `${lines.join("\n").trim()}\n` } export const markdownSafetyIssues = (document: string): ReadonlyArray<string> => { const issues: Array<string> = [] let fence: string | undefined const lines = document.split("\n") for (let lineIndex = 0; lineIndex < lines.length; lineIndex++) { const line = lines[lineIndex]! const fenceMatch = /^\s*(`{3,})(?:[^`]*)$/.exec(line) if (fence !== undefined) { if (line.trim() === fence) { fence = undefined } continue } if (fenceMatch !== null) { fence = fenceMatch[1]! continue } if ( line === "<!-- dprint-ignore-file -->" || line.startsWith("**Replacement:** ") || line === "**Example**" ) { continue } let index = 0 while (index < line.length) { const character = line[index]! if (character === "\\") { index += 2 continue } if (character === "`") { let end = index + 1 while (line[end] === "`") { end++ } const delimiter = line.slice(index, end) const close = line.indexOf(delimiter, end) if (close === -1) { issues.push(`line ${lineIndex + 1}: unclosed inline code span`) break } index = close + delimiter.length continue } if (character === "~" || character === "<" || character === "*" || character === "_") { issues.push(`line ${lineIndex + 1}: unescaped ${JSON.stringify(character)}`) } index++ } } if (fence !== undefined) { issues.push(`unclosed ${fence} code fence`) } return issues } export const unannotatedApiIds = ( diff: ApiDiff, annotations: ReadonlyMap<string, MigrationAnnotation>, importMapSections = "" ): ReadonlyMap<string, ReadonlyArray<string>> => { const modules = new Map<string, Array<string>>() for (const entry of migrationEntries(diff, annotations, importMapSections)) { if (annotations.has(entry.id)) { continue } const ids = modules.get(entry.module) if (ids === undefined) { modules.set(entry.module, [entry.id]) } else { ids.push(entry.id) } } return modules } export const unannotatedModuleIds = ( diff: ApiDiff, annotations: ReadonlyMap<string, MigrationAnnotation>, importMapSections: string ): ReadonlyArray<string> => { const replacements = importMapReplacements(importMapSections) return removedModules(diff).filter((module) => !annotations.has(module) && !replacements.has(module) && ![...annotations.keys()].some((id) => id.startsWith(`${module}#`)) ) } export const renderMissingAnnotations = ( diff: ApiDiff, annotations: ReadonlyMap<string, MigrationAnnotation>, importMapSections = "" ): string => { const missingApis = unannotatedApiIds(diff, annotations, importMapSections) const missingModules = unannotatedModuleIds(diff, annotations, importMapSections) if (missingApis.size === 0 && missingModules.length === 0) { return "All migration APIs and removed modules have guidance.\n" } return `${ [ ...(missingModules.length === 0 ? [] : ["Removed modules:", ...missingModules.map((module) => ` - ${module}`)]), ...[...missingApis].flatMap(([module, ids]) => [ `${module}:`, ...ids.map((id) => ` - ${id}`) ]) ].join("\n") }\n` }