@mfeflow/core 0.4.0 → 0.6.0

package/dist/plan.d.ts

@@ -17,12 +17,16 @@ export interface PlanFeature {
     name: string;
     version: string;
     options?: Record<string, unknown>;
+    /** `sha256-<hex>` of the feature.json a registry served; recorded in mfeflow.json. */
+    integrity?: string;
 }
 export interface DependencyAdd {
     file: string;
     name: string;
     range: string;
     dev: boolean;
+    /** Added by a third-party feature, so `summarize` lists it in its own block. */
+    thirdParty?: boolean;
 }
 /** Added to package.json and shown. The engine never runs it. */
 export interface ScriptAdd {
@@ -91,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;
@@ -99,8 +105,23 @@ export declare class PlanBuilder {
     create(file: string, content: string, track?: boolean): Promise<void>;
     /** Rewrites an existing file. */
     patch(file: string, edit: (source: string) => string): Promise<void>;
+    /** Overwrites a file that exists, shown as a modification. First-party only: a third-party feature never replaces content. */
+    replace(file: string, content: string): Promise<void>;
     delete(file: string): Promise<void>;
     addDependency(file: string, name: string, range: string, dev?: boolean): Promise<void>;
+    /**
+     * Moves an existing dependency to `range`. A dependency on `catalog:` changes
+     * its entry in pnpm-workspace.yaml instead. A `workspace:` link, or any
+     * specifier that is not a registry range (`npm:`, `link:`, `file:`, a
+     * repository or a URL), is the project's own choice and is left alone with a
+     * warning. The new range must be a semver range or a dist-tag (E202). A
+     * missing dependency is an E208. A third-party feature can only ask for the
+     * 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. */
     addScript(file: string, name: string, command: string): Promise<void>;
     addEnvKey(file: string, key: string): void;

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.4.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.4.0",
+    "@mfeflow/contracts": "0.6.0",
     "diff": "9.0.0",
     "eta": "4.6.0",
     "semver": "7.8.5",