@sebgroup/green-core 2.37.1 → 2.37.3

package/bin/context-cli/index.js

@@ -14,6 +14,7 @@ import {
   DOCS_FRAMEWORK_CANONICAL,
   normalizeDocsFramework
 } from "./framework.js";
+import { handleMigrate } from "./migrate/index.js";
 import { parseArgs } from "./parse-args.js";
 function getPrimaryTextContent(result) {
   const textBlock = result.content.find(
@@ -43,6 +44,7 @@ COMMANDS
   guides                            List available guides
   guide <name>                      Get a specific guide's content
   instructions                      Get base usage instructions
+  migrate <subcommand>              Run code migrations
 
 GLOBAL OPTIONS
   -h, --help                        Show this help message
@@ -337,6 +339,9 @@ async function main() {
     case "instructions":
       await runInstructions(args);
       break;
+    case "migrate":
+      await handleMigrate(args);
+      break;
     default:
       process.stderr.write(`Error: Unknown command '${args.command}'.
 

package/bin/context-cli/migrate/engine.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Migration engine — file discovery and migration orchestration.
+ *
+ * The engine walks a directory tree, filters files by extension, and runs
+ * migration units in detect-only or detect+apply mode. All file I/O uses
+ * Node built-in modules (no external dependencies).
+ *
+ * Security:
+ * - Writes files only when `apply: true` is explicitly set
+ * - Skips unreadable files and directories silently
+ * - Normalises all output paths to forward slashes
+ *
+ * @module migrate/engine
+ */
+import type { MigrationResult, MigrationUnit } from './types.js';
+/** Directories that are always skipped during file discovery. */
+export declare const DEFAULT_SKIP_DIRS: Set<string>;
+/**
+ * Discover all files under `basePath` whose extension is in `extensions`.
+ *
+ * @param basePath   - Root directory to scan
+ * @param extensions - Set of extensions to include (e.g. `new Set(['.ts', '.html'])`)
+ * @param skipDirs   - Directory names to skip (defaults to {@link DEFAULT_SKIP_DIRS})
+ * @returns Sorted array of absolute file paths
+ */
+export declare function discoverFiles(basePath: string, extensions: Set<string>, skipDirs?: Set<string>): Promise<string[]>;
+/** Options for {@link runMigrations}. */
+export interface RunOptions {
+    /** Root directory to scan for files */
+    basePath: string;
+    /** Migration units to execute */
+    units: MigrationUnit[];
+    /** When true, apply transformations and write files. Default: false (detect only). */
+    apply?: boolean;
+    /** Additional directory names to skip during file discovery */
+    skipDirs?: string[];
+}
+/**
+ * Run one or more migration units against a directory tree.
+ *
+ * In detect-only mode (default), files are scanned but never modified.
+ * In apply mode (`apply: true`), each unit's `apply()` function is called
+ * and the result is written back to disk.
+ *
+ * @param options - Configuration for the migration run
+ * @returns One {@link MigrationResult} per unit, in the same order as `options.units`
+ */
+export declare function runMigrations(options: RunOptions): Promise<MigrationResult[]>;

package/bin/context-cli/migrate/engine.js

@@ -0,0 +1,111 @@
+import "../../../chunks/chunk.QU3DSPNU.js";
+import { readdir, readFile, writeFile } from "node:fs/promises";
+import { extname, join, relative, resolve } from "node:path";
+const DEFAULT_SKIP_DIRS = /* @__PURE__ */ new Set([
+  "node_modules",
+  ".git",
+  "dist",
+  ".nx",
+  ".cache",
+  "coverage",
+  ".angular",
+  ".next",
+  "__pycache__"
+]);
+async function* walkDir(dir, skipDirs) {
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      if (skipDirs.has(entry.name)) continue;
+      yield* walkDir(join(dir, entry.name), skipDirs);
+    } else if (entry.isFile()) {
+      yield join(dir, entry.name);
+    }
+  }
+}
+async function discoverFiles(basePath, extensions, skipDirs) {
+  const skip = skipDirs ?? DEFAULT_SKIP_DIRS;
+  const files = [];
+  for await (const filePath of walkDir(basePath, skip)) {
+    if (extensions.has(extname(filePath))) {
+      files.push(filePath);
+    }
+  }
+  return files.sort();
+}
+async function runMigrations(options) {
+  const { basePath, units, apply = false, skipDirs: extraSkip } = options;
+  const resolvedBase = resolve(basePath);
+  const skipDirs = new Set(DEFAULT_SKIP_DIRS);
+  if (extraSkip) {
+    for (const dir of extraSkip) skipDirs.add(dir);
+  }
+  const allExtensions = /* @__PURE__ */ new Set();
+  for (const unit of units) {
+    for (const ext of unit.fileExtensions) {
+      allExtensions.add(ext.startsWith(".") ? ext : `.${ext}`);
+    }
+  }
+  const allFiles = await discoverFiles(resolvedBase, allExtensions, skipDirs);
+  const unitExtSets = /* @__PURE__ */ new Map();
+  for (const unit of units) {
+    unitExtSets.set(
+      unit.id,
+      new Set(
+        unit.fileExtensions.map((e) => e.startsWith(".") ? e : `.${e}`)
+      )
+    );
+  }
+  const results = [];
+  for (const unit of units) {
+    const extSet = unitExtSets.get(unit.id);
+    const relevantFiles = allFiles.filter((f) => extSet.has(extname(f)));
+    const allMatches = [];
+    const manualReview = [];
+    let filesModified = 0;
+    for (const filePath of relevantFiles) {
+      let content;
+      try {
+        content = await readFile(filePath, "utf-8");
+      } catch {
+        continue;
+      }
+      const matches = unit.detect(filePath, content);
+      if (matches.length === 0) continue;
+      const relFile = relative(resolvedBase, filePath).replace(/\\/g, "/");
+      for (const m of matches) {
+        m.file = relFile;
+        if (m.manualReview) {
+          manualReview.push(m);
+        }
+      }
+      allMatches.push(...matches);
+      if (apply) {
+        const transformed = unit.apply(filePath, content);
+        if (transformed !== null && transformed !== content) {
+          await writeFile(filePath, transformed, "utf-8");
+          filesModified++;
+        }
+      }
+    }
+    results.push({
+      unitId: unit.id,
+      summary: unit.summary,
+      filesScanned: relevantFiles.length,
+      matches: allMatches,
+      filesModified,
+      manualReview
+    });
+  }
+  return results;
+}
+export {
+  DEFAULT_SKIP_DIRS,
+  discoverFiles,
+  runMigrations
+};

package/bin/context-cli/migrate/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * CLI handler for the `migrate` command.
+ *
+ * Subcommands:
+ * - `list`  — List available migration units
+ * - `run`   — Detect (and optionally apply) migrations
+ *
+ * @module migrate
+ */
+import type { ParsedArgs } from '../parse-args.js';
+export declare const MIGRATE_HELP: string;
+/**
+ * Route the `migrate` command to the appropriate subcommand.
+ */
+export declare function handleMigrate(args: ParsedArgs): Promise<void>;

package/bin/context-cli/migrate/index.js

@@ -0,0 +1,232 @@
+import "../../../chunks/chunk.QU3DSPNU.js";
+import { runMigrations } from "./engine.js";
+import { getMigrationUnits } from "./registry.js";
+const PROGRAM_NAME = "green-core-context";
+const MIGRATE_HELP = `
+Detect and apply automated code migrations for Green Design System
+major version upgrades.
+
+USAGE
+  ${PROGRAM_NAME} migrate <subcommand> [options]
+
+SUBCOMMANDS
+  list                              List available migration units
+  run                               Detect issues (default: detect only)
+
+OPTIONS (for 'run')
+  --apply                           Apply changes (default: detect only)
+  --unit <id>                       Run a specific migration unit by ID
+  --major <n>                       Run all migrations for major version n
+  --path <dir>                      Target directory (default: current dir)
+  --json                            Output results as JSON
+  -h, --help                        Show this help message
+
+EXAMPLES
+  ${PROGRAM_NAME} migrate list
+  ${PROGRAM_NAME} migrate run --path ./src
+  ${PROGRAM_NAME} migrate run --unit 3.0.0/my-migration --apply
+  ${PROGRAM_NAME} migrate run --major 3 --json
+`.trim();
+function runList(args) {
+  return runListAsync(args);
+}
+async function runListAsync(args) {
+  const majorFlag = args.flags["major"];
+  const jsonFlag = args.flags["json"];
+  const filterMajor = majorFlag !== void 0 && majorFlag !== true ? Number(majorFlag) : void 0;
+  if (filterMajor !== void 0 && Number.isNaN(filterMajor)) {
+    process.stderr.write("Error: --major must be a number.\n");
+    process.exitCode = 1;
+    return;
+  }
+  const resolved = await getMigrationUnits({ major: filterMajor });
+  if (jsonFlag) {
+    const json = resolved.map((r) => ({
+      id: r.unit.id,
+      major: r.major,
+      summary: r.unit.summary,
+      safe: r.unit.safe,
+      fileExtensions: r.unit.fileExtensions,
+      exampleBefore: r.unit.exampleBefore,
+      exampleAfter: r.unit.exampleAfter
+    }));
+    process.stdout.write(JSON.stringify(json, null, 2) + "\n");
+    return;
+  }
+  if (resolved.length === 0) {
+    process.stdout.write("No migration units available.\n");
+    if (filterMajor !== void 0) {
+      process.stdout.write(`(filtered by --major ${filterMajor})
+`);
+    }
+    return;
+  }
+  process.stdout.write("Available migrations:\n\n");
+  const idWidth = Math.max(4, ...resolved.map((r) => r.unit.id.length));
+  const header = `  ${"ID".padEnd(idWidth)}  Major  Safe  Summary`;
+  const separator = `  ${"\u2500".repeat(idWidth)}  \u2500\u2500\u2500\u2500\u2500  \u2500\u2500\u2500\u2500  ${"\u2500".repeat(40)}`;
+  process.stdout.write(header + "\n");
+  process.stdout.write(separator + "\n");
+  for (const r of resolved) {
+    const safe = r.unit.safe ? "yes " : "no  ";
+    const line = `  ${r.unit.id.padEnd(idWidth)}  ${String(r.major).padEnd(5)}  ${safe}  ${r.unit.summary}`;
+    process.stdout.write(line + "\n");
+  }
+  process.stdout.write(`
+${resolved.length} migration(s) available.
+`);
+}
+async function runRun(args) {
+  const applyFlag = args.flags["apply"] === true;
+  const jsonFlag = args.flags["json"] === true;
+  const pathFlag = args.flags["path"];
+  const unitFlag = args.flags["unit"];
+  const majorFlag = args.flags["major"];
+  const targetPath = typeof pathFlag === "string" ? pathFlag : process.cwd();
+  const filterMajor = majorFlag !== void 0 && majorFlag !== true ? Number(majorFlag) : void 0;
+  if (filterMajor !== void 0 && Number.isNaN(filterMajor)) {
+    process.stderr.write("Error: --major must be a number.\n");
+    process.exitCode = 1;
+    return;
+  }
+  const filterId = typeof unitFlag === "string" ? unitFlag : void 0;
+  const resolved = await getMigrationUnits({ major: filterMajor, id: filterId });
+  if (resolved.length === 0) {
+    if (filterId) {
+      process.stderr.write(
+        `Error: No migration unit found with ID '${filterId}'.
+`
+      );
+    } else if (filterMajor !== void 0) {
+      process.stderr.write(
+        `Error: No migration units found for major version ${filterMajor}.
+`
+      );
+    } else {
+      process.stderr.write("No migration units are registered.\n");
+    }
+    process.exitCode = 1;
+    return;
+  }
+  const mode = applyFlag ? "apply" : "detect";
+  if (!jsonFlag) {
+    process.stderr.write(
+      `Running ${resolved.length} migration(s) in ${mode} mode...
+
+`
+    );
+  }
+  const results = await runMigrations({
+    basePath: targetPath,
+    units: resolved.map((r) => r.unit),
+    apply: applyFlag
+  });
+  if (jsonFlag) {
+    process.stdout.write(JSON.stringify(results, null, 2) + "\n");
+    return;
+  }
+  formatTextResults(results, applyFlag);
+}
+function formatTextResults(results, applied) {
+  let totalMatches = 0;
+  let totalModified = 0;
+  let totalManual = 0;
+  let totalScanned = 0;
+  for (const result of results) {
+    process.stdout.write(`\u2500\u2500 ${result.unitId} \u2500\u2500
+`);
+    process.stdout.write(`${result.summary}
+
+`);
+    totalScanned += result.filesScanned;
+    totalMatches += result.matches.length;
+    totalModified += result.filesModified;
+    totalManual += result.manualReview.length;
+    if (result.matches.length === 0) {
+      process.stdout.write("  No issues found.\n\n");
+      continue;
+    }
+    if (applied) {
+      const byFile = /* @__PURE__ */ new Map();
+      for (const m of result.matches) {
+        byFile.set(m.file, (byFile.get(m.file) ?? 0) + 1);
+      }
+      for (const [file, count] of byFile) {
+        const prefix = result.manualReview.some((m) => m.file === file) ? "!" : "\u2713";
+        process.stdout.write(
+          `  ${prefix} ${file} (${count} change${count > 1 ? "s" : ""})
+`
+        );
+      }
+    } else {
+      for (const m of result.matches) {
+        const marker = m.manualReview ? " [manual]" : "";
+        process.stdout.write(
+          `  ${m.file}:${m.line}${marker}
+    ${m.message}
+
+`
+        );
+      }
+    }
+    process.stdout.write(
+      `  ${result.matches.length} issue(s) in ${filesWithMatches(result)} file(s) (scanned ${result.filesScanned})
+
+`
+    );
+  }
+  process.stdout.write("\u2500\u2500 Summary \u2500\u2500\n");
+  process.stdout.write(`Scanned: ${totalScanned} files
+`);
+  process.stdout.write(`Found:   ${totalMatches} issue(s)
+`);
+  if (applied) {
+    process.stdout.write(`Applied: ${totalModified} file(s) modified
+`);
+  } else if (totalMatches > 0) {
+    process.stdout.write(`
+Run with --apply to fix automatically.
+`);
+  }
+  if (totalManual > 0) {
+    process.stdout.write(
+      `Manual:  ${totalManual} issue(s) require manual review
+`
+    );
+  }
+}
+function filesWithMatches(result) {
+  return new Set(result.matches.map((m) => m.file)).size;
+}
+async function handleMigrate(args) {
+  if (args.flags["h"] || args.flags["help"]) {
+    process.stdout.write(MIGRATE_HELP + "\n");
+    return;
+  }
+  const subcommand = args.positional[0];
+  switch (subcommand) {
+    case "list":
+      await runList(args);
+      break;
+    case "run":
+      await runRun(args);
+      break;
+    default:
+      if (subcommand) {
+        process.stderr.write(
+          `Error: Unknown migrate subcommand '${subcommand}'.
+
+`
+        );
+      }
+      process.stdout.write(MIGRATE_HELP + "\n");
+      if (!subcommand) {
+      } else {
+        process.exitCode = 1;
+      }
+  }
+}
+export {
+  MIGRATE_HELP,
+  handleMigrate
+};

package/bin/context-cli/migrate/registry.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Migration unit registry — auto-discovery from the file system.
+ *
+ * Units are discovered by scanning the `units/` directory for numbered
+ * subdirectories (each representing a major version). Every `.ts` / `.js`
+ * file inside a major directory that exports a `unit` constant is
+ * registered automatically.
+ *
+ *     units/
+ *       0/            ← major 0 (examples / disabled units)
+ *         example.ts
+ *       3/            ← major 3
+ *         remove-dropdown-value-generic.ts
+ *
+ * @module migrate/registry
+ */
+import type { ResolvedMigrationUnit } from './types.js';
+/**
+ * Discover migration units from the `units/<major>/` directory structure.
+ *
+ * @param basePath - Root `units/` directory to scan. Defaults to the
+ *                   co-located `./units` directory next to this module.
+ * @returns All discovered units, sorted by major then ID.
+ */
+export declare function discoverMigrationUnits(basePath?: string): Promise<ResolvedMigrationUnit[]>;
+/**
+ * Get migration units matching optional filter criteria.
+ *
+ * By default only enabled units are returned. Set `includeDisabled: true`
+ * to include disabled units (useful for tooling / debugging).
+ *
+ * @param options.major           - Filter by target major version
+ * @param options.id              - Filter by exact unit ID
+ * @param options.includeDisabled - Include units with `enabled: false`
+ * @param options.basePath        - Override the units directory (for tests)
+ * @returns Filtered array of resolved migration units
+ */
+export declare function getMigrationUnits(options?: {
+    major?: number;
+    id?: string;
+    includeDisabled?: boolean;
+    basePath?: string;
+}): Promise<ResolvedMigrationUnit[]>;

package/bin/context-cli/migrate/registry.js

@@ -0,0 +1,75 @@
+import "../../../chunks/chunk.QU3DSPNU.js";
+import { readdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const DEFAULT_UNITS_DIR = join(__dirname, "units");
+function isUnitFile(name) {
+  if (name.endsWith(".d.ts")) return false;
+  if (name.endsWith(".test.ts") || name.endsWith(".test.js")) return false;
+  if (name.endsWith(".spec.ts") || name.endsWith(".spec.js")) return false;
+  return name.endsWith(".ts") || name.endsWith(".js");
+}
+async function discoverMigrationUnits(basePath) {
+  const unitsDir = basePath ?? DEFAULT_UNITS_DIR;
+  const results = [];
+  let topEntries;
+  try {
+    topEntries = await readdir(unitsDir, { withFileTypes: true });
+  } catch {
+    return results;
+  }
+  for (const entry of topEntries) {
+    if (!entry.isDirectory()) continue;
+    const major = Number(entry.name);
+    if (Number.isNaN(major)) continue;
+    const majorDir = join(unitsDir, entry.name);
+    let files;
+    try {
+      files = await readdir(majorDir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const file of files) {
+      if (!file.isFile() || !isUnitFile(file.name)) continue;
+      try {
+        const moduleUrl = pathToFileURL(join(majorDir, file.name)).href;
+        const mod = await import(moduleUrl);
+        if (mod.unit && typeof mod.unit === "object" && "id" in mod.unit) {
+          results.push({ major, unit: mod.unit });
+        } else {
+          process.stderr.write(
+            `Warning: ${entry.name}/${file.name} does not export a 'unit' constant \u2014 skipped.
+`
+          );
+        }
+      } catch (err) {
+        process.stderr.write(
+          `Warning: Failed to import ${entry.name}/${file.name}: ${err instanceof Error ? err.message : String(err)}
+`
+        );
+      }
+    }
+  }
+  results.sort(
+    (a, b) => a.major - b.major || a.unit.id.localeCompare(b.unit.id)
+  );
+  return results;
+}
+async function getMigrationUnits(options) {
+  let units = await discoverMigrationUnits(options?.basePath);
+  if (!options?.includeDisabled) {
+    units = units.filter((r) => r.unit.enabled);
+  }
+  if (options?.major !== void 0) {
+    units = units.filter((r) => r.major === options.major);
+  }
+  if (options?.id !== void 0) {
+    units = units.filter((r) => r.unit.id === options.id);
+  }
+  return units;
+}
+export {
+  discoverMigrationUnits,
+  getMigrationUnits
+};

package/bin/context-cli/migrate/types.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Types for the Green Design System migration engine.
+ *
+ * Migration units are versioned, self-contained modules that detect and
+ * optionally fix breaking changes in consumer codebases. Each unit targets
+ * a specific major version upgrade and encapsulates:
+ * - Detection logic (regex-based, zero external dependencies)
+ * - Transformation logic (string replacement or manual-review flagging)
+ *
+ * ## Directory layout
+ *
+ * Units are organized by major version in the file system:
+ *
+ *     units/
+ *       3/
+ *         remove-dropdown-value-generic.ts
+ *         rename-datepicker-slot.ts
+ *       4/
+ *         some-future-migration.ts
+ *
+ * The major version is derived from the directory name — not from a field
+ * on the unit itself. Units that should not appear in listings or be run
+ * can set `enabled: false`.
+ *
+ * @module migrate/types
+ */
+/**
+ * A single match found by a migration unit's detect function.
+ */
+export interface MigrationMatch {
+    /** File path (made relative by the engine after detect returns) */
+    file: string;
+    /** 1-based line number where the match was found */
+    line: number;
+    /** The matched text snippet (the relevant line fragment) */
+    match: string;
+    /** Human-readable description of what needs to change */
+    message: string;
+    /**
+     * If true, this match cannot be auto-fixed and requires manual
+     * intervention. The engine will report it separately.
+     */
+    manualReview?: boolean;
+}
+/**
+ * Aggregated result from running a single migration unit across a project.
+ */
+export interface MigrationResult {
+    /** The migration unit ID */
+    unitId: string;
+    /** Short summary of the migration */
+    summary: string;
+    /** Number of files scanned */
+    filesScanned: number;
+    /** All matches found */
+    matches: MigrationMatch[];
+    /** Number of files that were modified (0 in detect-only mode) */
+    filesModified: number;
+    /** Matches that require manual review (subset of matches) */
+    manualReview: MigrationMatch[];
+}
+/**
+ * A migration unit describes a single automated migration step.
+ *
+ * ## Creating a new unit
+ *
+ * 1. Create a new file under `migrate/units/<major>/`
+ *    (e.g. `units/3/remove-dropdown-value-generic.ts`)
+ * 2. Export a `MigrationUnit` object named `unit`
+ * 3. The registry auto-discovers it from the directory structure
+ *
+ * See `migrate/units/0/example.ts` for a documented template.
+ */
+export interface MigrationUnit {
+    /**
+     * Unique identifier (kebab-case slug).
+     * Example: `remove-dropdown-value-generic`
+     */
+    id: string;
+    /**
+     * Whether this unit should be listed and available for execution.
+     * Set to `false` for drafts, examples, or temporarily disabled units.
+     */
+    enabled: boolean;
+    /** Short human-readable summary (one line) */
+    summary: string;
+    /**
+     * Code example showing the pattern **before** the migration is applied.
+     * Primarily serves as context for coding models applying changes manually.
+     */
+    exampleBefore: string;
+    /**
+     * Code example showing the expected result **after** migration.
+     * Primarily serves as context for coding models applying changes manually.
+     */
+    exampleAfter: string;
+    /**
+     * File extensions to scan, including the leading dot.
+     * Example: `['.ts', '.tsx', '.html']`
+     */
+    fileExtensions: string[];
+    /**
+     * Whether this migration is safe to auto-apply without manual review.
+     * When `true`, `apply()` is guaranteed to produce correct output for
+     * every match that `detect()` finds. When `false`, some matches may
+     * require manual intervention.
+     */
+    safe: boolean;
+    /**
+     * Detect occurrences of the deprecated pattern in a file.
+     *
+     * @param filePath - Absolute path to the file being scanned
+     * @param content  - The file's full text content (UTF-8)
+     * @returns Array of matches found in the file (may be empty)
+     */
+    detect(filePath: string, content: string): MigrationMatch[];
+    /**
+     * Apply the migration transformation to a file's content.
+     *
+     * @param filePath - Absolute path to the file being transformed
+     * @param content  - The file's full text content (UTF-8)
+     * @returns The transformed content, or `null` if no changes were made
+     */
+    apply(filePath: string, content: string): string | null;
+}
+/**
+ * A migration unit enriched with metadata derived from the directory
+ * structure during auto-discovery. Returned by the registry.
+ */
+export interface ResolvedMigrationUnit {
+    /** Major version, derived from the `units/<major>/` directory name */
+    major: number;
+    /** The migration unit definition */
+    unit: MigrationUnit;
+}