@uipath/maestro-builder-sdk 6.54.0 → 6.54.1

package/dist/registry/curated-overlay.d.ts

@@ -78,6 +78,30 @@ export declare function readOverlayCorrections(overlayPath: string): Promise<Ove
  * What was done is reported in one line, and recorded in `.curated-overlay.json`
  * beside the index, so a second application recognises its own patches: the
  * record keeps a sha256 of each patched entry and sidecar, and a correction
- * whose files no longer match it is patched again.
+ * whose files no longer match it is patched again. The record also names the
+ * overlay that wrote it ({@link curatedOverlayIdentity}). Under a different
+ * overlay, such as a newer SDK pulling a published archive, every correction
+ * is patched again, so fields a newer correction lists are added.
  */
 export declare function applyCuratedOverlay(libraryPath: string, overlayPath?: string, reporter?: Reporter): Promise<CuratedOverlayResult>;
+/** What {@link checkCuratedOverlay} found, one line per item. */
+export interface CuratedOverlayCheck {
+    /** Parts the overlay adds that are absent: the overlay was not applied, or broke. */
+    missing: string[];
+    /**
+     * Corrections whose target the library no longer serves at the correction's
+     * path, or serves without the fields the patch adds: the operation moved,
+     * was renamed or re-versioned. `registry pull` only warns about these too.
+     */
+    staleCorrections: string[];
+}
+/**
+ * Check `libraryPath` against the curated overlay. Both lists are empty once
+ * {@link applyCuratedOverlay} has run on it, unless a correction went stale.
+ * Every overlay identity that is not a correction must be indexed at a file
+ * that exists, and each side-table must equal the bundled copy.
+ *
+ * The connector library pipeline runs this on the archive it publishes,
+ * because readers that load that archive directly apply no overlay.
+ */
+export declare function checkCuratedOverlay(libraryPath: string, overlayPath?: string): Promise<CuratedOverlayCheck>;

package/dist/registry/curated-overlay.js

@@ -34,6 +34,25 @@ export async function curatedOverlayIdentity(overlayPath = bundledOverlayPath())
 function entryIdentity(entry) {
     return `${String(entry.nodeType)}\0${String(entry.version)}`;
 }
+/**
+ * Every path the library resolves each identity to. A `GenericExpanded` or
+ * per-object entry shares its nodeType with its siblings, so an identity
+ * legitimately has more than one.
+ */
+function pathsByIdentity(entries) {
+    const resolvedPaths = new Map();
+    for (const entry of entries) {
+        if (typeof entry.path !== "string")
+            continue;
+        const identity = entryIdentity(entry);
+        const known = resolvedPaths.get(identity);
+        if (known === undefined)
+            resolvedPaths.set(identity, [entry.path]);
+        else
+            known.push(entry.path);
+    }
+    return resolvedPaths;
+}
 /** The ledger of deliberate patches; read here, never copied into a library. */
 export const CORRECTIONS_FILE = "overlay-corrections.json";
 /**
@@ -209,7 +228,10 @@ async function patchCorrection(libraryPath, overlayPath, correction) {
  * What was done is reported in one line, and recorded in `.curated-overlay.json`
  * beside the index, so a second application recognises its own patches: the
  * record keeps a sha256 of each patched entry and sidecar, and a correction
- * whose files no longer match it is patched again.
+ * whose files no longer match it is patched again. The record also names the
+ * overlay that wrote it ({@link curatedOverlayIdentity}). Under a different
+ * overlay, such as a newer SDK pulling a published archive, every correction
+ * is patched again, so fields a newer correction lists are added.
  */
 export async function applyCuratedOverlay(libraryPath, overlayPath = bundledOverlayPath(), 
 // The public materializer API does not forward one, and a warning nobody
@@ -223,24 +245,13 @@ reporter = consoleReporter) {
     const previous = (await exists(recordPath))
         ? (await readJson(recordPath))
         : {};
+    const overlayIdentity = await curatedOverlayIdentity(overlayPath);
+    const sameOverlay = previous.overlayIdentity === overlayIdentity;
     const previouslyAdded = new Set(previous.added ?? []);
     const previousDigests = previous.correctedSha256 ?? {};
     const digests = {};
     const entries = destination.entries ?? [];
-    // Every path the library resolves each identity to. A `GenericExpanded` or
-    // per-object entry shares its nodeType with its siblings, so an identity
-    // legitimately has more than one.
-    const resolvedPaths = new Map();
-    for (const entry of entries) {
-        if (typeof entry.path !== "string")
-            continue;
-        const identity = entryIdentity(entry);
-        const known = resolvedPaths.get(identity);
-        if (known === undefined)
-            resolvedPaths.set(identity, [entry.path]);
-        else
-            known.push(entry.path);
-    }
+    const resolvedPaths = pathsByIdentity(entries);
     const additions = [];
     const skipped = new Set();
     const added = [];
@@ -285,15 +296,18 @@ reporter = consoleReporter) {
             continue;
         }
         // Our own earlier patch, as long as neither file changed since: a refreshed
-        // entry (an `unzip -o` over the same directory, say) is patched again.
+        // entry (an `unzip -o` over the same directory, say) is patched again. So
+        // is our patch under another overlay, whose correction may list more; when
+        // it lists nothing new, the patch is still ours, not upstream catching up.
         const digest = await correctionDigest(libraryPath, row.path);
-        if (previousDigests[row.path] === digest) {
+        const ownPatch = previousDigests[row.path] === digest;
+        if (ownPatch && sameOverlay) {
             corrected.push(row.path);
             digests[row.path] = digest;
             continue;
         }
         const patched = await patchCorrection(libraryPath, overlayPath, correction);
-        if (patched.added.length === 0) {
+        if (patched.added.length === 0 && !ownPatch) {
             kept.push(row.path);
             reporter.warn([
                 `  WARN: curated overlay correction no longer needed: ${row.path} (${correction.since})`,
@@ -338,6 +352,7 @@ reporter = consoleReporter) {
     };
     writeJsonFile(recordPath, {
         $comment: "What the SDK's curated overlay did to this library (registry pull). See curated-overlay.ts.",
+        overlayIdentity,
         added: result.added,
         corrected: result.corrected,
         correctedSha256: digests,
@@ -350,3 +365,82 @@ reporter = consoleReporter) {
         `, kept ${result.kept.length + result.skipped.length} published definition(s) unchanged.`);
     return result;
 }
+/**
+ * Check `libraryPath` against the curated overlay. Both lists are empty once
+ * {@link applyCuratedOverlay} has run on it, unless a correction went stale.
+ * Every overlay identity that is not a correction must be indexed at a file
+ * that exists, and each side-table must equal the bundled copy.
+ *
+ * The connector library pipeline runs this on the archive it publishes,
+ * because readers that load that archive directly apply no overlay.
+ */
+export async function checkCuratedOverlay(libraryPath, overlayPath = bundledOverlayPath()) {
+    const library = (await readJson(join(libraryPath, "index.json")));
+    const overlay = (await readJson(join(overlayPath, "index.json")));
+    const corrections = await readOverlayCorrections(overlayPath);
+    const correctionPaths = new Set(corrections.map((correction) => correction.path));
+    const resolvedPaths = pathsByIdentity(library.entries ?? []);
+    const overlayRows = new Map();
+    const missing = [];
+    const staleCorrections = [];
+    for (const row of overlay.entries ?? []) {
+        if (typeof row.path !== "string")
+            continue;
+        overlayRows.set(row.path, row);
+        if (correctionPaths.has(row.path))
+            continue;
+        const name = `${String(row.nodeType)}@${String(row.version)}`;
+        const paths = resolvedPaths.get(entryIdentity(row));
+        if (paths === undefined) {
+            missing.push(`definition ${name}: no index row`);
+            continue;
+        }
+        for (const path of paths) {
+            if (!(await exists(join(libraryPath, path))))
+                missing.push(`definition ${name}: indexed at ${path}, which is absent`);
+        }
+    }
+    for (const correction of corrections) {
+        const where = `correction ${correction.path} (${correction.since})`;
+        const paths = resolvedPaths.get(entryIdentity(overlayRows.get(correction.path))) ?? [];
+        if (!paths.includes(correction.path)) {
+            staleCorrections.push(`${where}: the library has no definition at that path${paths.length ? ` (it indexes ${paths.join(", ")})` : ""}`);
+            continue;
+        }
+        if (!(await exists(join(libraryPath, correction.path)))) {
+            staleCorrections.push(`${where}: the library indexes that path, but the file is absent`);
+            continue;
+        }
+        const lacks = [];
+        const entry = (await readJson(join(libraryPath, correction.path)));
+        const entryFields = fieldNames(entry.inputSchema?.fields);
+        for (const field of correction.inputFields ?? []) {
+            if (!entryFields.has(field))
+                lacks.push(`inputSchema field ${field}`);
+        }
+        const sidecarPath = join(libraryPath, sidecarOf(correction.path));
+        if (await exists(sidecarPath)) {
+            const sidecar = sidecarBody(await readJson(sidecarPath)) ?? {};
+            const sidecarFields = fieldNames(sidecar.inputDefinition?.fields);
+            for (const field of correction.inputFields ?? []) {
+                if (!sidecarFields.has(field))
+                    lacks.push(`sidecar inputDefinition field ${field}`);
+            }
+            for (const key of correction.sidecarKeys ?? []) {
+                if (!(key in sidecar))
+                    lacks.push(`sidecar key ${key}`);
+            }
+        }
+        if (lacks.length > 0)
+            staleCorrections.push(`${where}: the definition lacks ${lacks.join(", ")}`);
+    }
+    for (const table of SIDE_TABLES) {
+        const target = join(libraryPath, table);
+        if (!(await exists(target)))
+            missing.push(`side-table ${table}: absent`);
+        else if (!(await readFile(target)).equals(await readFile(join(overlayPath, table)))) {
+            missing.push(`side-table ${table}: differs from the SDK's copy`);
+        }
+    }
+    return { missing, staleCorrections };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/maestro-builder-sdk",
-  "version": "6.54.0",
+  "version": "6.54.1",
   "description": "Build UiPath Flow, Case, and BPMN artifacts by writing TypeScript.",
   "license": "MIT",
   "homepage": "https://docs.uipath.com/maestro",
@@ -96,5 +96,5 @@
     "@types/node": "^22.7.0",
     "esbuild": "^0.28.1"
   },
-  "gitref": "f215db445a4e5067bdf31b92c72604c121b52e9e"
+  "gitref": "5dfee12e621c69cfa2cf1338fc7df299768dbe16"
 }