@vscode/vscode-settings-history 0.0.2-0

package/README.md

@@ -0,0 +1,111 @@
+# @vscode/vscode-settings-history
+
+Tracks VS Code settings schema changes across versions using [RFC 6902 JSON Patch](https://datatracker.ietf.org/doc/html/rfc6902). Each VS Code release is diffed against its base version, producing a compact changelog of added, removed, and modified settings (including schema and default changes).
+
+## Installation
+
+```
+pnpm add @vscode/vscode-settings-history
+```
+
+## What's in the package
+
+- **`types.d.ts`** — TypeScript types (`SettingsHistory`, `VersionedEdit`, `SettingSchema`, `PatchOperation`)
+- **`dist/history.json`** — the changelog (array of versioned JSON Patches)
+- **`dist/vscode-settings.d.ts`** — generated versioned settings types with `Patch<>` utility (use via `@vscode/vscode-settings-history/settings`)
+
+## Usage
+
+### Types
+
+```ts
+import type {
+  SettingsHistory,
+  VersionedEdit,
+  SettingSchema,
+  PatchOperation,
+} from '@vscode/vscode-settings-history';
+```
+
+### Generated versioned settings types
+
+```ts
+import type {
+  LatestVscodeSettings,
+  VscodeSettingsFor,
+  VscodeVersion,
+} from '@vscode/vscode-settings-history/settings';
+
+// Type-safe settings for a specific version
+const settings: VscodeSettingsFor<'1.115'> = {
+  'editor.fontSize': 14,
+};
+```
+
+### History data
+
+```ts
+import history from '@vscode/vscode-settings-history/history.json';
+```
+
+### Format
+
+`history.json` is an array of versioned edits. Each entry contains RFC 6902 patch operations relative to a base version:
+
+```jsonc
+[
+  {
+    "version": "1.114",
+    "base": "initial",           // diffs from {}
+    "patch": [
+      { "op": "add", "path": "/editor.fontSize", "value": { "type": "number", "default": 14 } },
+      // ... 1832 ops (full baseline)
+    ]
+  },
+  {
+    "version": "1.115",
+    "base": { "version": "1.114" },  // diffs from 1.114
+    "patch": [
+      { "op": "remove", "path": "/update.statusBar" },
+      { "op": "replace", "path": "/editor.fontSize/default", "value": 16 },
+      { "op": "add", "path": "/editor.newFeature", "value": { "type": "boolean" } },
+      // ... only what changed
+    ]
+  }
+]
+```
+
+Replay from `{}` by applying patches to reconstruct the full state at any version. Branching is supported via explicit `base` pointers (e.g. patch releases like `1.114.1` base on `1.114`, not `1.115`).
+
+## CLI (dev only, not shipped)
+
+Extract settings from a VS Code version and update the history:
+
+```sh
+npx tsx src/cli/extract.ts extract                          # latest stable
+npx tsx src/cli/extract.ts extract --version 1.116.0        # specific version
+npx tsx src/cli/extract.ts extract --from-schema schema.json --version 1.116
+```
+
+Regenerate `.d.ts` from existing history:
+
+```sh
+npx tsx src/cli/extract.ts generate --history ./dist/history.json --out-dts ./dist/vscode-settings.d.ts
+```
+
+## Development
+
+```sh
+pnpm install
+pnpm test       # vitest
+```
+
+No build step — the package ships a hand-written `types.d.ts` and `dist/history.json` (produced by the CI extract pipeline).
+
+## Publishing
+
+Published automatically via Azure Pipelines:
+
+- **Nightly scheduled** (`publish-nightly-scheduled.yml`): runs daily, checks for new VS Code releases, publishes a prerelease (`next` tag) if a new version is detected.
+- **Nightly on-push** (`publish-nightly.yml`): can be manually triggered with the settings-history flag enabled.
+- **Stable** (`publish-stable.yml`): manually triggered to promote to `latest` tag.