@hirobius/design-system 0.20.0 → 0.22.0

package/upgrade/schema.json

@@ -0,0 +1,989 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "@hirobius/design-system upgrade ledger",
+  "description": "Generated from scripts/upgrade/schema.mjs; do not edit. The root validates a release ledger (upgrade/releases/<version>.json); $defs.index validates upgrade/index.json, $defs.snapshot a release snapshot (docs/api/releases/<version>.json), $defs.pendingNote a changeset's upgrade note (upgrade/pending/<changeset>.json) and $defs.upgradeReport what the upgrade command prints with --json.",
+  "$ref": "#/$defs/release",
+  "$defs": {
+    "auto": {
+      "type": "object",
+      "properties": {
+        "codemod": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]*$",
+          "description": "The name of a bin this package ships (package.json#bin), such as hds-patterns-subpath."
+        },
+        "args": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Extra arguments. The upgrade command passes --root, --dry-run and --check itself."
+        }
+      },
+      "required": [
+        "codemod",
+        "args"
+      ],
+      "additionalProperties": false,
+      "description": "The codemod that applies this step for the consumer."
+    },
+    "detect": {
+      "type": "object",
+      "properties": {
+        "imports": {
+          "description": "Named imports (and re-exports) that use the changed thing.",
+          "minItems": 1,
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "from": {
+                "type": "string",
+                "minLength": 1,
+                "description": "The module specifier as written in the import: @hirobius/design-system or one of its subpaths."
+              },
+              "names": {
+                "minItems": 1,
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "description": "Export names. A named import of any of them from `from` is a use."
+              }
+            },
+            "required": [
+              "from",
+              "names"
+            ],
+            "additionalProperties": false
+          }
+        },
+        "jsx": {
+          "minItems": 1,
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "description": "JSX tag names, as exported (Card, Card.Header). The tool resolves a local alias."
+        },
+        "cssVars": {
+          "description": "Custom properties read with var(--name), in CSS or in code.",
+          "minItems": 1,
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^--[\\w-]+$"
+          }
+        },
+        "cssVarWrites": {
+          "description": "Custom properties the consumer sets (--name: value), overriding HDS.",
+          "minItems": 1,
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^--[\\w-]+$"
+          }
+        },
+        "classes": {
+          "description": "Class names, in className strings or CSS selectors.",
+          "minItems": 1,
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^\\S+$"
+          }
+        },
+        "bareImports": {
+          "description": "Package specifiers the consumer imports or requires directly, such as a dependency HDS stopped installing.",
+          "minItems": 1,
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^(?:@[^\\s/]+\\/)?[^\\s/@][^\\s]*$"
+          }
+        },
+        "regex": {
+          "description": "JavaScript regular expression sources, each tested against a whole file.",
+          "minItems": 1,
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      },
+      "additionalProperties": false,
+      "minProperties": 1,
+      "description": "How to find a use of the changed thing in consumer code. Any match is a use."
+    },
+    "index": {
+      "type": "object",
+      "properties": {
+        "package": {
+          "type": "string",
+          "const": "@hirobius/design-system"
+        },
+        "latest": {
+          "type": "string",
+          "pattern": "^\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?$",
+          "description": "The newest release with a ledger."
+        },
+        "floor": {
+          "type": "string",
+          "pattern": "^\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?$",
+          "description": "The oldest version the upgrade command can upgrade from. Below it, the command stops and changes nothing."
+        },
+        "versions": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "version": {
+                "type": "string",
+                "pattern": "^\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?$",
+                "description": "A semver version, such as 0.20.0."
+              },
+              "date": {
+                "type": "string",
+                "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+                "description": "The release day, YYYY-MM-DD: the day `pnpm changeset:version` cut it (its Version PR, which publishes when it merges, as last regenerated), or, for a release recorded after it shipped, the day npm published it."
+              },
+              "bump": {
+                "type": "string",
+                "enum": [
+                  "patch",
+                  "minor",
+                  "major"
+                ]
+              },
+              "breaking": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991,
+                "description": "How many of its steps have impact breaking."
+              },
+              "summary": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 140
+              }
+            },
+            "required": [
+              "version",
+              "date",
+              "bump",
+              "breaking",
+              "summary"
+            ],
+            "additionalProperties": false
+          },
+          "description": "Every release with a ledger."
+        },
+        "deprecated": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "name": {
+                "type": "string",
+                "minLength": 1,
+                "description": "The deprecated export or class or, for a deprecation that lists neither (a token path, a prop, a prop value), the subject of its step: a label to show, not a name to search code for. To find its uses, read the detect of the step `step` names."
+              },
+              "entry": {
+                "description": "The package.json#exports key that exports it, such as `.`.",
+                "type": "string"
+              },
+              "removeIn": {
+                "type": "string",
+                "pattern": "^\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?$",
+                "description": "A semver version, such as 0.20.0."
+              },
+              "useInstead": {
+                "type": "string",
+                "minLength": 1
+              },
+              "step": {
+                "type": "string",
+                "minLength": 1,
+                "description": "The id of the deprecated step that announced it."
+              }
+            },
+            "required": [
+              "name",
+              "removeIn",
+              "step"
+            ],
+            "additionalProperties": false
+          },
+          "description": "Names deprecated today, with the release that removes them (Coming next)."
+        }
+      },
+      "required": [
+        "package",
+        "latest",
+        "floor",
+        "versions",
+        "deprecated"
+      ],
+      "additionalProperties": false,
+      "description": "upgrade/index.json: the releases the upgrade command knows, and its floor."
+    },
+    "pendingNote": {
+      "type": "object",
+      "properties": {
+        "impact": {
+          "type": "string",
+          "enum": [
+            "none",
+            "additive",
+            "look",
+            "behavior",
+            "breaking"
+          ],
+          "description": "The most severe impact of this change on a consumer that does nothing. A change with none says so: impact none, stated, never left out."
+        },
+        "plain": {
+          "description": "The change in one sentence a non-expert can act on, ending in a full stop. Required unless impact is none.",
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 300,
+          "pattern": "^[^\\n]+[.]$"
+        },
+        "steps": {
+          "description": "The ledger steps this change adds. A fact the snapshot diff finds (a removed export, a dropped dependency) needs a step that lists it in facts.",
+          "minItems": 1,
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/pendingStep"
+          }
+        }
+      },
+      "required": [
+        "impact"
+      ],
+      "additionalProperties": false,
+      "description": "upgrade/pending/<changeset>.json: the upgrade note a changeset carries until its release (hds#448)."
+    },
+    "pendingStep": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^(?:removed|moved|renamed|folded|deprecated|value-changed|look|behavior|dependency|peer|engines|exports|tenant|manual)\\/\\S+$",
+          "description": "<kind>/<subject>, a release step id without its version: the compiler (hds#451) prefixes the version when it merges the note into upgrade/releases/<version>.json."
+        },
+        "kind": {
+          "type": "string",
+          "enum": [
+            "removed",
+            "moved",
+            "renamed",
+            "folded",
+            "deprecated",
+            "value-changed",
+            "look",
+            "behavior",
+            "dependency",
+            "peer",
+            "engines",
+            "exports",
+            "tenant",
+            "manual"
+          ],
+          "description": "What changed."
+        },
+        "impact": {
+          "type": "string",
+          "enum": [
+            "none",
+            "additive",
+            "look",
+            "behavior",
+            "breaking"
+          ],
+          "description": "What happens to a consumer that does nothing: none, additive (new, opt-in), look, behavior, or breaking (it stops compiling or running)."
+        },
+        "plain": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 300,
+          "pattern": "^[^\\n]+[.]$",
+          "description": "One sentence a non-expert can act on, ending in a full stop."
+        },
+        "auto": {
+          "$ref": "#/$defs/auto"
+        },
+        "detect": {
+          "$ref": "#/$defs/detect"
+        },
+        "done": {
+          "description": "How to tell the consumer has already made this change, in the detect shape: when any of it matches, the step is done even where detect matches too. For a step that asks the consumer to add something, such as an import.",
+          "$ref": "#/$defs/detect"
+        },
+        "removeIn": {
+          "description": "For a deprecation: the version that removes it.",
+          "type": "string",
+          "pattern": "^\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?$"
+        },
+        "range": {
+          "description": "For a dependency or peer step: the range this package declared before the release, so a consumer that still imports it can add it back.",
+          "type": "string",
+          "minLength": 1
+        },
+        "facts": {
+          "description": "The ids of the snapshot-diff facts this step accounts for (scripts/upgrade/diff.mjs), such as removed:.:IconButton.",
+          "minItems": 1,
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "source": {
+          "description": "Where the step comes from. When absent, the compiler (hds#451) fills it in.",
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "required": [
+        "id",
+        "kind",
+        "impact",
+        "plain"
+      ],
+      "additionalProperties": false,
+      "description": "One step of a pending note: a release step whose id leaves out the version."
+    },
+    "release": {
+      "type": "object",
+      "properties": {
+        "version": {
+          "type": "string",
+          "pattern": "^\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?$",
+          "description": "A semver version, such as 0.20.0."
+        },
+        "date": {
+          "type": "string",
+          "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+          "description": "The release day, YYYY-MM-DD: the day `pnpm changeset:version` cut it (its Version PR, which publishes when it merges, as last regenerated), or, for a release recorded after it shipped, the day npm published it."
+        },
+        "bump": {
+          "type": "string",
+          "enum": [
+            "patch",
+            "minor",
+            "major"
+          ],
+          "description": "The semver bump from the previous release."
+        },
+        "summary": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 140,
+          "description": "The release in one line, 140 characters at most."
+        },
+        "backfilled": {
+          "type": "boolean",
+          "description": "True when this ledger was written after the release shipped, from its tarball and CHANGELOG."
+        },
+        "steps": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/step"
+          }
+        }
+      },
+      "required": [
+        "version",
+        "date",
+        "bump",
+        "summary",
+        "backfilled",
+        "steps"
+      ],
+      "additionalProperties": false,
+      "description": "A release ledger, upgrade/releases/<version>.json: every step a consumer crosses with this release."
+    },
+    "snapshot": {
+      "type": "object",
+      "properties": {
+        "format": {
+          "type": "number",
+          "const": 1
+        },
+        "name": {
+          "type": "string",
+          "minLength": 1
+        },
+        "version": {
+          "type": "string",
+          "pattern": "^\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?$",
+          "description": "A semver version, such as 0.20.0."
+        },
+        "entries": {
+          "type": "object",
+          "propertyNames": {
+            "type": "string"
+          },
+          "additionalProperties": {
+            "type": "object",
+            "propertyNames": {
+              "type": "string"
+            },
+            "additionalProperties": {
+              "type": "string"
+            }
+          },
+          "description": "Every JS entry in package.json#exports: its export names, each with the module that declares it (relative to dist/types, no extension)."
+        },
+        "exportsKeys": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Every package.json#exports key."
+        },
+        "dependencies": {
+          "type": "object",
+          "propertyNames": {
+            "type": "string"
+          },
+          "additionalProperties": {
+            "type": "string"
+          }
+        },
+        "peerDependencies": {
+          "type": "object",
+          "propertyNames": {
+            "type": "string"
+          },
+          "additionalProperties": {
+            "type": "object",
+            "properties": {
+              "range": {
+                "type": "string"
+              },
+              "optional": {
+                "type": "boolean"
+              }
+            },
+            "required": [
+              "range",
+              "optional"
+            ],
+            "additionalProperties": false
+          }
+        },
+        "engines": {
+          "type": "object",
+          "propertyNames": {
+            "type": "string"
+          },
+          "additionalProperties": {
+            "type": "string"
+          }
+        },
+        "bin": {
+          "type": "object",
+          "propertyNames": {
+            "type": "string"
+          },
+          "additionalProperties": {
+            "type": "string"
+          }
+        },
+        "files": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "package.json#files."
+        }
+      },
+      "required": [
+        "format",
+        "name",
+        "version",
+        "entries",
+        "exportsKeys",
+        "dependencies",
+        "peerDependencies",
+        "engines",
+        "bin",
+        "files"
+      ],
+      "additionalProperties": false,
+      "description": "docs/api/releases/<version>.json: the public surface of one published release (scripts/upgrade/snapshot.mjs)."
+    },
+    "step": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?\\/(?:removed|moved|renamed|folded|deprecated|value-changed|look|behavior|dependency|peer|engines|exports|tenant|manual)\\/\\S+$",
+          "description": "Stable id, <version>/<kind>/<subject>: the subject is the export, package, component or variable the step is about."
+        },
+        "kind": {
+          "type": "string",
+          "enum": [
+            "removed",
+            "moved",
+            "renamed",
+            "folded",
+            "deprecated",
+            "value-changed",
+            "look",
+            "behavior",
+            "dependency",
+            "peer",
+            "engines",
+            "exports",
+            "tenant",
+            "manual"
+          ],
+          "description": "What changed."
+        },
+        "impact": {
+          "type": "string",
+          "enum": [
+            "none",
+            "additive",
+            "look",
+            "behavior",
+            "breaking"
+          ],
+          "description": "What happens to a consumer that does nothing: none, additive (new, opt-in), look, behavior, or breaking (it stops compiling or running)."
+        },
+        "plain": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 300,
+          "pattern": "^[^\\n]+[.]$",
+          "description": "One sentence a non-expert can act on, ending in a full stop."
+        },
+        "auto": {
+          "$ref": "#/$defs/auto"
+        },
+        "detect": {
+          "$ref": "#/$defs/detect"
+        },
+        "done": {
+          "description": "How to tell the consumer has already made this change, in the detect shape: when any of it matches, the step is done even where detect matches too. For a step that asks the consumer to add something, such as an import.",
+          "$ref": "#/$defs/detect"
+        },
+        "removeIn": {
+          "description": "For a deprecation: the version that removes it.",
+          "type": "string",
+          "pattern": "^\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?$"
+        },
+        "range": {
+          "description": "For a dependency or peer step: the range this package declared before the release, so a consumer that still imports it can add it back.",
+          "type": "string",
+          "minLength": 1
+        },
+        "facts": {
+          "description": "The ids of the snapshot-diff facts this step accounts for (scripts/upgrade/diff.mjs), such as removed:.:IconButton.",
+          "minItems": 1,
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "backfilled": {
+          "description": "True when the step was written from CHANGELOG prose after the release shipped.",
+          "type": "boolean"
+        },
+        "source": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Where the step comes from: CHANGELOG.md:<line> (as of the release), a codemod data file, or the snapshot diff."
+        }
+      },
+      "required": [
+        "id",
+        "kind",
+        "impact",
+        "plain",
+        "source"
+      ],
+      "additionalProperties": false,
+      "description": "One thing a consumer may have to do, or should know, when crossing this release."
+    },
+    "upgradeReport": {
+      "type": "object",
+      "properties": {
+        "package": {
+          "type": "string",
+          "const": "@hirobius/design-system"
+        },
+        "tool": {
+          "type": "string",
+          "pattern": "^\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?$",
+          "description": "The version of the package the command ran from."
+        },
+        "mode": {
+          "type": "string",
+          "enum": [
+            "apply",
+            "dry-run",
+            "check"
+          ],
+          "description": "apply writes; dry-run and --check write nothing."
+        },
+        "target": {
+          "type": "string",
+          "pattern": "^\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?$",
+          "description": "The version upgraded to."
+        },
+        "floor": {
+          "type": "string",
+          "pattern": "^\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?$",
+          "description": "The oldest version the command upgrades from."
+        },
+        "packageManager": {
+          "anyOf": [
+            {
+              "type": "string",
+              "enum": [
+                "pnpm",
+                "npm",
+                "yarn",
+                "bun"
+              ]
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "lockfile": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "The lockfile read, by name, or null."
+        },
+        "importers": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "dir": {
+                "type": "string",
+                "minLength": 1,
+                "description": ". for the root, else the workspace directory."
+              },
+              "from": {
+                "anyOf": [
+                  {
+                    "type": "string",
+                    "pattern": "^\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?$",
+                    "description": "A semver version, such as 0.20.0."
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "description": "The installed version, or null when unknown."
+              },
+              "source": {
+                "type": "string",
+                "enum": [
+                  "lockfile",
+                  "node_modules",
+                  "flag",
+                  "git-head",
+                  "git-merge-base",
+                  "git-log",
+                  "unknown"
+                ],
+                "description": "Where the installed version was read."
+              },
+              "range": {
+                "type": "string",
+                "description": "The range package.json declared."
+              },
+              "newRange": {
+                "anyOf": [
+                  {
+                    "type": "string"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "description": "The range at the target, or null when it cannot be rewritten."
+              }
+            },
+            "required": [
+              "dir",
+              "from",
+              "source",
+              "range",
+              "newRange"
+            ],
+            "additionalProperties": false
+          },
+          "description": "Every importer that declares the package."
+        },
+        "split": {
+          "type": "boolean",
+          "description": "True when the importers start from different versions."
+        },
+        "fixedForYou": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "string",
+                "minLength": 1,
+                "description": "The ledger step id (0.21.0/removed/StatusDot), or a tool item: range, tool/two-copies, tool/no-history, tool/range, tool/install, tool/typecheck, tool/not-read, or <codemod>/manual."
+              },
+              "plain": {
+                "type": "string",
+                "minLength": 1,
+                "description": "What happened or what to do, in one sentence."
+              },
+              "importers": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "description": "The importers (. or a workspace directory) it applies to."
+              },
+              "files": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "description": "Where it was found or changed, relative to the project root."
+              },
+              "removeIn": {
+                "description": "For Coming next: the version that removes it.",
+                "type": "string",
+                "pattern": "^\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?$"
+              },
+              "blocking": {
+                "description": "For Do by hand: true while the code still needs an edit (exit 1); false for a behavior change to check, which never blocks.",
+                "type": "boolean"
+              }
+            },
+            "required": [
+              "id",
+              "plain",
+              "importers",
+              "files"
+            ],
+            "additionalProperties": false
+          }
+        },
+        "looksDifferent": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "string",
+                "minLength": 1,
+                "description": "The ledger step id (0.21.0/removed/StatusDot), or a tool item: range, tool/two-copies, tool/no-history, tool/range, tool/install, tool/typecheck, tool/not-read, or <codemod>/manual."
+              },
+              "plain": {
+                "type": "string",
+                "minLength": 1,
+                "description": "What happened or what to do, in one sentence."
+              },
+              "importers": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "description": "The importers (. or a workspace directory) it applies to."
+              },
+              "files": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "description": "Where it was found or changed, relative to the project root."
+              },
+              "removeIn": {
+                "description": "For Coming next: the version that removes it.",
+                "type": "string",
+                "pattern": "^\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?$"
+              },
+              "blocking": {
+                "description": "For Do by hand: true while the code still needs an edit (exit 1); false for a behavior change to check, which never blocks.",
+                "type": "boolean"
+              }
+            },
+            "required": [
+              "id",
+              "plain",
+              "importers",
+              "files"
+            ],
+            "additionalProperties": false
+          }
+        },
+        "comingNext": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "string",
+                "minLength": 1,
+                "description": "The ledger step id (0.21.0/removed/StatusDot), or a tool item: range, tool/two-copies, tool/no-history, tool/range, tool/install, tool/typecheck, tool/not-read, or <codemod>/manual."
+              },
+              "plain": {
+                "type": "string",
+                "minLength": 1,
+                "description": "What happened or what to do, in one sentence."
+              },
+              "importers": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "description": "The importers (. or a workspace directory) it applies to."
+              },
+              "files": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "description": "Where it was found or changed, relative to the project root."
+              },
+              "removeIn": {
+                "description": "For Coming next: the version that removes it.",
+                "type": "string",
+                "pattern": "^\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?$"
+              },
+              "blocking": {
+                "description": "For Do by hand: true while the code still needs an edit (exit 1); false for a behavior change to check, which never blocks.",
+                "type": "boolean"
+              }
+            },
+            "required": [
+              "id",
+              "plain",
+              "importers",
+              "files"
+            ],
+            "additionalProperties": false
+          }
+        },
+        "doByHand": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "string",
+                "minLength": 1,
+                "description": "The ledger step id (0.21.0/removed/StatusDot), or a tool item: range, tool/two-copies, tool/no-history, tool/range, tool/install, tool/typecheck, tool/not-read, or <codemod>/manual."
+              },
+              "plain": {
+                "type": "string",
+                "minLength": 1,
+                "description": "What happened or what to do, in one sentence."
+              },
+              "importers": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "description": "The importers (. or a workspace directory) it applies to."
+              },
+              "files": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "description": "Where it was found or changed, relative to the project root."
+              },
+              "removeIn": {
+                "description": "For Coming next: the version that removes it.",
+                "type": "string",
+                "pattern": "^\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?$"
+              },
+              "blocking": {
+                "description": "For Do by hand: true while the code still needs an edit (exit 1); false for a behavior change to check, which never blocks.",
+                "type": "boolean"
+              }
+            },
+            "required": [
+              "id",
+              "plain",
+              "importers",
+              "files"
+            ],
+            "additionalProperties": false
+          }
+        },
+        "changedFiles": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Files written, relative to the project root."
+        },
+        "refused": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "Why the command refused (exit 2), having changed nothing; null otherwise."
+        },
+        "exitCode": {
+          "anyOf": [
+            {
+              "type": "number",
+              "const": 0
+            },
+            {
+              "type": "number",
+              "const": 1
+            },
+            {
+              "type": "number",
+              "const": 2
+            }
+          ]
+        }
+      },
+      "required": [
+        "package",
+        "tool",
+        "mode",
+        "target",
+        "floor",
+        "packageManager",
+        "lockfile",
+        "importers",
+        "split",
+        "fixedForYou",
+        "looksDifferent",
+        "comingNext",
+        "doByHand",
+        "changedFiles",
+        "refused",
+        "exitCode"
+      ],
+      "additionalProperties": false,
+      "description": "What `npx @hirobius/design-system upgrade --json` prints (hds#452): the four lists, per importer versions, and the exit code."
+    }
+  }
+}