@meith/upgrade 0.16.0

package/LICENSE.md

@@ -0,0 +1,165 @@
+                   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions.
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@meith/upgrade",
+  "version": "0.16.0",
+  "license": "LGPL-3.0-or-later",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/meith-dev/meith.git",
+    "directory": "packages/upgrade"
+  },
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "files": [
+    "src",
+    "!src/**/*.test.*",
+    "!src/**/*.type-test.*"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.ts

@@ -0,0 +1,16 @@
+export {
+  checkUpgradeSpan,
+  compareVersions,
+  type OrderFailure,
+  orderPlugins,
+  type PluginUpgrade,
+  parseVersion,
+  planUpgrade,
+  SUPPORTED_MAJOR_SPAN,
+  type UpgradePlan,
+  type UpgradeRefusal,
+  type UpgradeState,
+  type UpgradeStep,
+  upgradeNotice,
+  type Version,
+} from './plan'

package/src/plan.ts

@@ -0,0 +1,203 @@
+export interface Version {
+  readonly major: number
+  readonly minor: number
+  readonly patch: number
+}
+
+export function parseVersion(value: string): Version {
+  const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(value.trim())
+  if (match === null) {
+    throw new Error(`upgrade: "${value}" is not a version. Expected major.minor.patch.`)
+  }
+  return { major: Number(match[1]), minor: Number(match[2]), patch: Number(match[3]) }
+}
+
+export function compareVersions(a: string, b: string): number {
+  const left = parseVersion(a)
+  const right = parseVersion(b)
+  return left.major - right.major || left.minor - right.minor || left.patch - right.patch
+}
+
+export const SUPPORTED_MAJOR_SPAN = 2
+
+export type UpgradeRefusal =
+  | { readonly kind: 'downgrade'; readonly from: string; readonly to: string }
+  | { readonly kind: 'too-far'; readonly from: string; readonly to: string; readonly span: number }
+
+export function checkUpgradeSpan(from: string, to: string): UpgradeRefusal | null {
+  const order = compareVersions(from, to)
+  if (order > 0) return { kind: 'downgrade', from, to }
+  if (order === 0) return null
+
+  const span = parseVersion(to).major - parseVersion(from).major
+  if (span > SUPPORTED_MAJOR_SPAN) return { kind: 'too-far', from, to, span }
+  return null
+}
+
+export interface PluginUpgrade {
+  readonly key: string
+  readonly version: string
+  readonly dependsOn: readonly string[]
+  readonly migrationIds: readonly string[]
+}
+
+export type OrderFailure =
+  | { readonly kind: 'cycle'; readonly keys: readonly string[] }
+  | { readonly kind: 'missing'; readonly key: string; readonly dependency: string }
+
+export function orderPlugins(
+  plugins: readonly PluginUpgrade[],
+):
+  | { readonly ok: true; readonly order: readonly PluginUpgrade[] }
+  | { readonly ok: false; readonly failure: OrderFailure } {
+  const byKey = new Map(plugins.map((plugin) => [plugin.key, plugin]))
+
+  for (const plugin of plugins) {
+    for (const dependency of plugin.dependsOn) {
+      if (!byKey.has(dependency)) {
+        return { ok: false, failure: { kind: 'missing', key: plugin.key, dependency } }
+      }
+    }
+  }
+
+  const remaining = new Map(byKey)
+  const order: PluginUpgrade[] = []
+
+  while (remaining.size > 0) {
+    const ready = [...remaining.values()]
+      .filter((plugin) => plugin.dependsOn.every((key) => !remaining.has(key)))
+      .sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0))
+
+    if (ready.length === 0) {
+      return { ok: false, failure: { kind: 'cycle', keys: [...remaining.keys()].sort() } }
+    }
+
+    const next = ready[0]!
+    remaining.delete(next.key)
+    order.push(next)
+  }
+
+  return { ok: true, order }
+}
+
+export interface UpgradeStep {
+  readonly kind: 'core-migrations' | 'plugin-migrations' | 'record-version'
+  readonly label: string
+  readonly pluginKey: string | null
+  readonly migrationIds: readonly string[]
+}
+
+export interface UpgradeState {
+  readonly recordedVersion: string
+  readonly codeVersion: string
+  readonly pendingCoreMigrations: readonly string[]
+  readonly plugins: readonly PluginUpgrade[]
+  readonly appliedPluginMigrations: Readonly<Record<string, readonly string[]>>
+}
+
+export interface UpgradePlan {
+  readonly steps: readonly UpgradeStep[]
+  readonly refusal: UpgradeRefusal | null
+  readonly orderFailure: OrderFailure | null
+  readonly pending: boolean
+}
+
+export function planUpgrade(state: UpgradeState): UpgradePlan {
+  const refusal = checkUpgradeSpan(state.recordedVersion, state.codeVersion)
+  if (refusal !== null) {
+    return { steps: [], refusal, orderFailure: null, pending: false }
+  }
+
+  const ordered = orderPlugins(state.plugins)
+  if (!ordered.ok) {
+    return { steps: [], refusal: null, orderFailure: ordered.failure, pending: false }
+  }
+
+  const steps: UpgradeStep[] = []
+
+  if (state.pendingCoreMigrations.length > 0) {
+    steps.push({
+      kind: 'core-migrations',
+      label: `Apply ${state.pendingCoreMigrations.length} core migration(s)`,
+      pluginKey: null,
+      migrationIds: state.pendingCoreMigrations,
+    })
+  }
+
+  for (const plugin of ordered.order) {
+    const applied = new Set(state.appliedPluginMigrations[plugin.key] ?? [])
+    const pending = plugin.migrationIds.filter((id) => !applied.has(id))
+    if (pending.length === 0) continue
+
+    steps.push({
+      kind: 'plugin-migrations',
+      label: `Apply ${pending.length} migration(s) for ${plugin.key}`,
+      pluginKey: plugin.key,
+      migrationIds: pending,
+    })
+  }
+
+  const versionChanged = compareVersions(state.recordedVersion, state.codeVersion) !== 0
+  if (steps.length > 0 || versionChanged) {
+    steps.push({
+      kind: 'record-version',
+      label: `Record version ${state.codeVersion}`,
+      pluginKey: null,
+      migrationIds: [],
+    })
+  }
+
+  return { steps, refusal: null, orderFailure: null, pending: steps.length > 0 }
+}
+
+export function upgradeNotice(plan: UpgradePlan, state: UpgradeState): string | null {
+  if (plan.refusal?.kind === 'downgrade') {
+    return (
+      `This board's database is at ${plan.refusal.from} and the running code is ` +
+      `${plan.refusal.to}. That is a downgrade: migrations are forward-only, so the code ` +
+      'is older than the schema it is talking to. Deploy the newer version again.'
+    )
+  }
+  if (plan.refusal?.kind === 'too-far') {
+    return (
+      `This board is at ${plan.refusal.from} and the running code is ${plan.refusal.to} — ` +
+      `${plan.refusal.span} majors apart, and upgrades are supported across ` +
+      `${SUPPORTED_MAJOR_SPAN}. Upgrade in stages; see docs/upgrading.md.`
+    )
+  }
+  if (plan.orderFailure?.kind === 'cycle') {
+    return `These plugins depend on each other in a cycle: ${plan.orderFailure.keys.join(', ')}.`
+  }
+  if (plan.orderFailure?.kind === 'missing') {
+    return (
+      `Plugin "${plan.orderFailure.key}" needs "${plan.orderFailure.dependency}", which is not ` +
+      'installed.'
+    )
+  }
+  if (!plan.pending) return null
+
+  const migrations = plan.steps
+    .filter((step) => step.kind !== 'record-version')
+    .reduce((total, step) => total + step.migrationIds.length, 0)
+
+  if (compareVersions(state.recordedVersion, state.codeVersion) === 0) {
+    const plugins = plan.steps
+      .filter((step) => step.kind === 'plugin-migrations')
+      .map((step) => step.pluginKey)
+      .filter((key): key is string => key !== null)
+
+    return (
+      `The database and this deployment are both at ${state.recordedVersion}, but ` +
+      `${migrations} migration(s) have never been applied` +
+      (plugins.length > 0 ? ` (${plugins.join(', ')})` : '') +
+      '. Run `community upgrade`.'
+    )
+  }
+
+  return (
+    `An upgrade is pending: the database is at ${state.recordedVersion} and this deployment ` +
+    `is ${state.codeVersion}` +
+    (migrations > 0 ? `, with ${migrations} migration(s) to apply` : '') +
+    '. Run `community upgrade`.'
+  )
+}