Merge pull request #40 from aridyckovsky/feat/core-version-registry

feat(core,cli): schema version registry and revision utilities for Amp context artifacts

Author: aridyckovsky

.changeset/amp-out-tri-state-support.md

@@ -0,0 +1,16 @@
+---
+"@effect-migrate/cli": minor
+---
+
+Add tri-state --amp-out option with Effect patterns
+
+- Add `normalizeArgs.ts` for handling bare --amp-out flag (converts to sentinel value)
+- Add Effect-based helpers in `amp/options.ts`:
+  - `resolveAmpOut()`: converts Option<string> to tri-state AmpOutMode
+  - `withAmpOut()`: conditionally executes Effect when output requested
+  - `getAmpOutPathWithDefault()`: for commands that always write output
+- Refactor audit, metrics, and thread commands to use helpers (no switch statements)
+- Support three modes:
+  - Omitted flag: no file output
+  - Bare flag `--amp-out`: writes to default path `.amp/effect-migrate`
+  - Flag with value `--amp-out=path`: writes to custom path

.changeset/cli-uses-core-amp.md

@@ -0,0 +1,10 @@
+---
+"@effect-migrate/cli": patch
+---
+
+Refactor CLI to use amp utilities from core package
+
+- Import amp utilities from `@effect-migrate/core/amp` instead of local modules
+- Create `amp/options.ts` for CLI-specific amp options
+- Update audit, metrics, and thread commands to use core schemas
+- Remove duplicate amp utility code from CLI package

.changeset/schema-version-registry.md

@@ -0,0 +1,13 @@
+---
+"@effect-migrate/core": minor
+---
+
+Add unified schema versioning and amp utilities to core package
+
+- Add `SCHEMA_VERSION` constant - single version for all artifacts (simplicity over complexity)
+- Add Semver schema validator with subpath export `@effect-migrate/core/schema`
+- Move amp utilities (context-writer, metrics-writer, thread-manager) from CLI to core
+- Add `schemaVersion` field to index.json and audit.json schemas
+- Add `revision` counter field to audit.json (increments on each write)
+- Export amp utilities via `@effect-migrate/core/amp` subpath
+- All artifacts share same schema version for clearer versioning semantics

.changeset/upgrade-effect-deps.md

@@ -0,0 +1,14 @@
+---
+"@effect-migrate/core": patch
+"@effect-migrate/cli": patch
+"@effect-migrate/preset-basic": patch
+---
+
+Upgrade `effect` packages and fix dependency versions
+
+- Upgrade `effect` from 3.18.4 to 3.19.2
+- Upgrade `@effect/platform` from 0.92.1 to 0.93.0
+- Upgrade `@effect/platform-node` from 0.98.4 to 0.100.0
+- Upgrade `@effect/cli` from 0.71.0 to 0.72.0
+- Upgrade `@effect/vitest` from 0.26.0 to 0.27.0
+- Replace "latest" with specific versions for `@types/node` (^24.10.0) and `typescript` (^5.9.3)

README.md

@@ -242,33 +242,43 @@ Warnings: 1
 ### 3. Generate Amp Context
 
 ```bash
+# Write to custom directory
 pnpm effect-migrate audit --amp-out .amp/effect-migrate
+
+# Or write to default .amp/ directory
+pnpm effect-migrate audit --amp-out
 ```
 
-This creates `.amp/effect-migrate/context.json`:
+This creates structured context files with schema versioning:
 
+**`.amp/effect-migrate/index.json`** (entry point):
 ```json
 {
-  "version": 1,
+  "schemaVersion": "0.1.0",
   "timestamp": "2025-01-03T10:00:00Z",
-  "projectPath": "/Users/you/project",
-  "migrationState": {
-    "phase": "pattern-detection",
-    "completedModules": ["src/models/user.ts"],
-    "pendingModules": ["src/api/fetchUser.ts"]
-  },
-  "findings": {
-    "summary": {
-      "errors": 1,
-      "warnings": 3,
-      "totalFiles": 24,
-      "migratedFiles": 16,
-      "progress": 67
+  "resources": {
+    "audit": "./audit.json",
+    "metrics": "./metrics.json",
+    "threads": "./threads.json",
+    "badges": "./badges.md"
+  }
+}
+```
+
+**`.amp/effect-migrate/audit.json`** (detailed findings):
+```json
+{
+  "schemaVersion": "0.1.0",
+  "revision": 1,
+  "timestamp": "2025-01-03T10:00:00Z",
+  "findings": [
+    {
+      "ruleId": "no-async-await",
+      "severity": "warning",
+      "file": "src/api/fetchUser.ts",
+      "line": 23,
+      "message": "Replace async/await with Effect.gen"
     }
-  },
-  "recommendations": [
-    "Convert async/await functions to Effect.gen",
-    "Replace node:fs imports with @effect/platform/FileSystem"
   ]
 }
 ```
@@ -359,11 +369,12 @@ I'm migrating src/api/fetchUser.ts to Effect.
 
 Amp will:
 
-- Load audit.json and metrics.json via index.json
+- Load the index.json (schema version 0.1.0) which references all context files
+- Read audit.json (with revision tracking) and metrics.json
 - Know which files are migrated vs. legacy
 - Suggest Effect patterns based on active rules
-- Track progress and next steps
-- Cross-reference prior migration threads
+- Track progress across audit revisions
+- Cross-reference prior migration threads from threads.json
 
 ### 6. Programmatic Use (Amp TypeScript SDK)
 
@@ -373,8 +384,8 @@ import { execute } from "@sourcegraph/amp-sdk"
 async function proposeNextSteps(cwd: string) {
   const prompt = [
     "Load @.amp/effect-migrate/index.json",
-    "Read @.amp/effect-migrate/metrics.json and @.amp/effect-migrate/audit.json",
-    "Propose the 3 highest-impact modules to migrate next."
+    "The index references audit.json (with schemaVersion and revision), metrics.json, and threads.json",
+    "Propose the 3 highest-impact modules to migrate next based on the current revision."
   ].join("\n")
 
   for await (const msg of execute({ prompt, options: { cwd, continue: false } })) {
@@ -386,6 +397,11 @@ async function proposeNextSteps(cwd: string) {
 }
 ```
 
+**Schema versioning benefits:**
+- All context files include `schemaVersion: "0.1.0"` for compatibility tracking
+- `audit.json` includes a `revision` number that increments on each run
+- Amp can detect schema changes and handle migrations gracefully
+
 See [Amp TypeScript SDK documentation](https://ampcode.com/docs/sdk) for more examples and options.
 
 ---