@mfeflow/core 0.5.0 → 0.6.0

package/dist/plan.d.ts

@@ -95,6 +95,8 @@ export declare class PlanBuilder {
     private open;
     exists(file: string): Promise<boolean>;
     content(file: string): Promise<string | undefined>;
+    /** Whether `file` was on disk before this plan changed anything. */
+    existed(file: string): Promise<boolean>;
     /** Remembers `mfeflow.json` as it is now; `applyPlan` refuses to continue if it changes before the write. */
     captureProject(): Promise<void>;
     addFeature(feature: PlanFeature): void;
@@ -117,6 +119,7 @@ export declare class PlanBuilder {
      * range that is already there.
      */
     setRange(file: string, name: string, range: string): Promise<void>;
+    /** The first range for `name` that is not already `wanted`, else the first one; a name can be listed in several sections. */
     private declaredRange;
     private setCatalogEntry;
     /** Adds a script. An identical one already there is a no-op; a different command under the same name is a conflict. */

package/dist/transforms/add-env-key.d.ts

@@ -11,6 +11,8 @@ export interface SchemaKey {
     name: string;
     /** The key may be missing: an arktype `'key?'`, or a Zod or Valibot schema whose outermost call is optional, nullish, default, catch, fallback or exactOptional. */
     optional: boolean;
+    /** The validator as written in the file, for example `z.string().min(1)`. */
+    schema: string;
 }
 /**
  * The keys of the `server` schema (`env.ts`) or of the runtime-config schema object,

package/dist/transforms/ast.d.ts

@@ -9,6 +9,7 @@ export interface Edit {
 /** Applies edits from the end backwards so earlier offsets stay valid. */
 export declare function applyEdits(source: string, edits: Edit[]): string;
 export declare function parseSource(source: string, file: string): File;
+export declare const SKIP_KEYS: Set<string>;
 /** Every node under `root` (including it) for which `match` returns true, in source order. */
 export declare function findAll(root: Node, match: (node: Node) => boolean): Node[];
 export type FunctionNode = FunctionDeclaration | FunctionExpression | ArrowFunctionExpression;

package/dist/upgrade.d.ts

@@ -0,0 +1,109 @@
+import type { LoadedFeature } from './features/load.js';
+import { PlanBuilder, type Plan, type ReadFile } from './plan.js';
+import type { MfeflowProject } from './project.js';
+/**
+ * What a first-party migration module exports (as `default` or `migrate`). It records its
+ * changes on the builder and returns nothing, so a dry run, `--json` and rollback work for it.
+ */
+export type Migration = (builder: PlanBuilder, project: MfeflowProject) => void | Promise<void>;
+export interface UpgradeInput {
+    /** The version the project is moving to; every `@mfeflow/*` range becomes `^<toVersion>`. */
+    toVersion: string;
+    /** Reads a project file by relative path; undefined when it does not exist. */
+    read: ReadFile;
+    /**
+     * The features to replay, in the order `init` applies them (`core` first). Each is replayed with
+     * the options `mfeflow.json` recorded for it.
+     */
+    features: readonly LoadedFeature[];
+    /** First-party parts replayed after the features, such as the per-remote registry and route files. */
+    glue?: readonly LoadedFeature[];
+    /** Recorded features the caller could not load. Their files are left alone and nothing is reported as removed. */
+    skipped?: readonly {
+        name: string;
+        reason: string;
+    }[];
+    /** Whether a project file is itself a symlink. Such a file is never replaced. */
+    isSymlink?: (file: string) => Promise<boolean>;
+    /** Loads a migration module. Defaults to a dynamic `import()`. */
+    importModule?: (file: string) => Promise<unknown>;
+    /**
+     * What the person decided about files that differ. An accepted file is written with the new
+     * version; a kept one is left, and the plan's project remembers it. `all` leaves out symlinks.
+     */
+    decisions?: UpgradeDecisions;
+}
+export interface UpgradeDecisions {
+    accept?: ReadonlySet<string> | 'all';
+    keep?: ReadonlySet<string> | 'all';
+}
+export type DivergeReason = 
+/** Tracked, and the file no longer matches the hash recorded when it was written. */
+'edited'
+/** The CLI never wrote this file, but a file is there and differs. */
+ | 'untracked'
+/** The CLI edits this file after generating it (`add env-key`), so a match with the recorded hash proves nothing. */
+ | 'edited-by-cli'
+/** A feature that could not be replayed may have patched this file, so a matching hash proves nothing. */
+ | 'skipped-feature'
+/** The path is a symlink; it is not replaced with a regular file. */
+ | 'symlink';
+/** A file the new version wants to change that the upgrade will not write. */
+export interface DivergedUpgrade {
+    path: string;
+    reason: DivergeReason;
+    /** What is on disk. */
+    yours: string;
+    /** What the new version generates. */
+    incoming: string;
+    /** Unified diff from `yours` to `incoming`. */
+    diff: string;
+    /** `accept` is written with the new version in `plan`; `keep` is left and remembered. Absent: undecided, left as it is. */
+    decision?: 'accept' | 'keep';
+    /** For files the CLI adds keys to: keys in your file that the new version lacks, which accepting drops. */
+    lostKeys?: string[];
+    /** The part of `lostKeys` that is in the new file with another value; the rest are not in it at all. */
+    changedValues?: string[];
+}
+export interface UpgradePlan {
+    /** The version the project was made with, and where that came from. */
+    from: string;
+    fromSource: 'mfeflow.json' | 'package.json';
+    to: string;
+    /** Replaced, created and structurally edited files. Apply it with `applyPlan`, passing `project`. */
+    plan: Plan;
+    /** The project to hand to `applyPlan`: `cli` is `to`; hashes and feature versions are filled in on apply. */
+    project: MfeflowProject;
+    /** Files the new version wants to change that you changed too, each with a diff. Only those without a `decision` are left undecided. */
+    diverged: DivergedUpgrade[];
+    /** Feature migrations that ran, in order. */
+    migrations: {
+        feature: string;
+        from: string;
+        to: string;
+    }[];
+    /** Files the old version generated and the new one no longer does. Reported, never deleted. */
+    removed: string[];
+    /** Files the old version generated that you deleted. They are not brought back. */
+    missing: string[];
+}
+/**
+ * The version of the CLI that made the project: `cli` in `mfeflow.json`, else the lowest version
+ * the shell's `@mfeflow/runtime` range allows (0.1 projects have no `cli`). A `workspace:`,
+ * `link:` or non-version range cannot be read, and that is an error rather than a guess.
+ */
+export declare function detectBaseline(project: MfeflowProject, read: ReadFile): Promise<{
+    version: string;
+    source: 'mfeflow.json' | 'package.json';
+}>;
+/**
+ * Works out what moving a project to `toVersion` changes, without touching the disk.
+ *
+ * It replays the skeleton and every recorded feature, with its recorded options, into memory and
+ * compares the result with the project. A tracked file you have not edited is replaced; one you
+ * have edited is returned in `diverged` with a diff and left alone; a new file is created; a file
+ * the new version no longer makes is listed in `removed` and never deleted. `package.json`,
+ * `pnpm-workspace.yaml` and `turbo.json` only get structured edits. Feature migrations whose
+ * version the upgrade crosses then run, in order, on the same plan.
+ */
+export declare function planUpgrade(project: MfeflowProject, input: UpgradeInput): Promise<UpgradePlan>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mfeflow/core",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "The engine behind the mfeflow CLI: project model, change plans with diffs, atomic apply with rollback, and feature resolution.",
   "keywords": [
     "micro-frontend",
@@ -45,7 +45,7 @@
   "dependencies": {
     "@babel/parser": "8.0.10",
     "@babel/types": "8.0.10",
-    "@mfeflow/contracts": "0.5.0",
+    "@mfeflow/contracts": "0.6.0",
     "diff": "9.0.0",
     "eta": "4.6.0",
     "semver": "7.8.5",