@uipath/common 1.203.0-preview.235 → 1.203.0-preview.237

package/dist/formatter.d.ts

@@ -103,6 +103,13 @@ export declare class SuccessOutput {
     Data: DataRecord | DataRecord[];
     Pagination?: Pagination;
     Instructions?: string;
+    /**
+     * A note for the caller that does not change the `Data` contract — e.g.
+     * why `--output-filter` returned nothing. Declared here because agents
+     * read the envelope and nothing else; `emitList` and the filter paths
+     * both set it.
+     */
+    Warning?: string;
     Log?: string;
     constructor(code: string, data: DataRecord | DataRecord[]);
 }
@@ -317,6 +324,9 @@ export declare namespace OutputFormatter {
      *
      * **Side-effect:** records the exit code through {@link setExitCode}, so a
      * printed failure exits non-zero even when no `context.exit()` follows.
+     *
+     * `--output-filter` projects `Data` here as it does in {@link success};
+     * see {@link filterFailureData}.
      */
     function error(data: FailureOutput): void;
     /** Emit a list result. Always uses `Result: "Success"` — an empty list is not an error. */
@@ -333,6 +343,11 @@ export declare namespace OutputFormatter {
     /**
      * Format structured output to a string without writing to console.
      * Useful when the caller needs the formatted string (e.g., Commander's formatHelp).
+     *
+     * This is the structured-help path, so it carries the filter note on the
+     * envelope like {@link success} does: a mistyped filter against `--help`
+     * is the same ambiguity as one against a list, and stdout is the only
+     * channel its reader has.
      */
     function formatToString(data: StructuredOutput): string;
 }

package/dist/index.js

@@ -10922,6 +10922,7 @@ class SuccessOutput {
   Data;
   Pagination;
   Instructions;
+  Warning;
   Log;
   constructor(code, data) {
     this.Code = code;
@@ -11563,7 +11564,165 @@ class ConfigurationError extends Error {
 function isConfigurationError(error) {
   return typeof error === "object" && error !== null && "__brand" in error && error.__brand === "ConfigurationError";
 }
-function applyFilter(data, filter) {
+function countRecords(data) {
+  if (Array.isArray(data))
+    return data.length;
+  return data == null ? 0 : 1;
+}
+function availableFields(data) {
+  const records = Array.isArray(data) ? data : [data];
+  const keys = new Set;
+  for (const record of records) {
+    if (record && typeof record === "object" && !Array.isArray(record)) {
+      for (const key of Object.keys(record))
+        keys.add(key);
+    }
+  }
+  return [...keys];
+}
+function decodeQuotedIdentifier(whole, inner) {
+  const [error, decoded] = catchError(() => JSON.parse(whole));
+  if (!error && typeof decoded === "string")
+    return decoded;
+  return inner.replace(/\\(.)/g, "$1");
+}
+function referencedFields(filter) {
+  const top = new Set;
+  const nested = new Set;
+  const withoutValueLiterals = filter.replace(/'(?:\\.|[^'\\])*'/g, " ").replace(/`(?:\\.|[^`\\])*`/g, " ");
+  const isPathTail = (text, index) => text[index - 1] === "." && /[A-Za-z0-9_"]/.test(text[index - 2] ?? "");
+  const quoted = [];
+  const withoutLiterals = withoutValueLiterals.replace(/"((?:\\.|[^"\\])*)"/g, (whole, name, index) => {
+    const isAlias = /^\s*:/.test(withoutValueLiterals.slice(index + whole.length));
+    if (!isAlias) {
+      quoted.push({
+        name: decodeQuotedIdentifier(whole, name),
+        index,
+        tail: isPathTail(withoutValueLiterals, index)
+      });
+    }
+    return `"${" ".repeat(whole.length - 2)}"`;
+  });
+  const descent = /[A-Za-z0-9_"]\s*[.[]/.exec(withoutLiterals);
+  const rootEnd = descent ? descent.index + 1 : Number.POSITIVE_INFINITY;
+  const place = (name, index, tail) => {
+    if (tail || index >= rootEnd)
+      nested.add(name);
+    else
+      top.add(name);
+  };
+  for (const entry of quoted)
+    place(entry.name, entry.index, entry.tail);
+  const identifiers = withoutLiterals.matchAll(/([A-Za-z_][A-Za-z0-9_]*)(\s*[:(])?/g);
+  const reserved = new Set(["true", "false", "null", "and", "or", "not"]);
+  for (const match of identifiers) {
+    const [, name, trailing] = match;
+    if (trailing || reserved.has(name))
+      continue;
+    place(name, match.index, isPathTail(withoutLiterals, match.index));
+  }
+  return {
+    top: [...top],
+    nested: [...nested].filter((name) => !top.has(name)),
+    hasPredicate: /\[\s*\?/.test(withoutValueLiterals)
+  };
+}
+function appearsBelowTopLevel(data, name) {
+  let budget = 2000;
+  const visit = (value, depth) => {
+    if (budget-- <= 0 || depth > 4)
+      return false;
+    if (value === null || typeof value !== "object")
+      return false;
+    if (Array.isArray(value))
+      return value.some((entry) => visit(entry, depth));
+    const record = value;
+    if (depth > 0 && Object.hasOwn(record, name))
+      return true;
+    return Object.values(record).some((entry) => visit(entry, depth + 1));
+  };
+  return visit(data, 0);
+}
+function alwaysNullKeys(records) {
+  const objects = records.filter((r) => r != null && typeof r === "object" && !Array.isArray(r));
+  if (objects.length === 0 || objects.length !== records.length)
+    return [];
+  const keys = [...new Set(objects.flatMap((o) => Object.keys(o)))];
+  if (keys.length === 0)
+    return [];
+  const nullKeys = keys.filter((key) => objects.every((record) => record[key] === null));
+  return nullKeys.length === keys.length ? nullKeys : [];
+}
+function carriesOnlyNulls(value) {
+  if (value === null)
+    return true;
+  if (Array.isArray(value)) {
+    return value.length > 0 && value.every(carriesOnlyNulls);
+  }
+  if (typeof value === "object" && value !== undefined) {
+    const values = Object.values(value);
+    return values.length > 0 && values.every(carriesOnlyNulls);
+  }
+  return false;
+}
+function nameList(names, cap2 = 12) {
+  const shown = names.slice(0, cap2).map((n) => `\`${n}\``);
+  const rest = names.length - shown.length;
+  return shown.join(", ") + (rest > 0 ? `, and ${rest} more` : "");
+}
+function buildFilterWarning(filter, data, outcome) {
+  const present = availableFields(data);
+  const refs = referencedFields(filter);
+  const unknown = refs.top.filter((name) => !present.includes(name) && !appearsBelowTopLevel(data, name));
+  const unchecked = refs.nested.filter((name) => !present.includes(name));
+  const count = countRecords(data);
+  const scope = `${count} record(s)`;
+  const isNotAField = (names) => `${nameList(names)} ${names.length === 1 ? "is not a field" : "are not fields"} on the ${scope} it read`;
+  const soundness = unchecked.length > 0 ? `${nameList(unchecked)} ${unchecked.length === 1 ? "reads" : "read"} below the top level, so ${unchecked.length === 1 ? "it was" : "they were"} not checked against the record keys` : refs.top.length > 0 ? "every field it names exists" : "";
+  const withSoundness = (base) => soundness ? `${base}, and ${soundness}` : base;
+  let detail;
+  let lede;
+  if (outcome.kind === "null-elements") {
+    lede = "returned only null values";
+    const projected = `all ${outcome.count} of the elements it projected are null`;
+    if (unknown.length > 0) {
+      detail = `${projected}, because ${isNotAField(unknown)}`;
+    } else if (unchecked.length > 0) {
+      detail = withSoundness(projected);
+    } else {
+      detail = `${projected}, and every field it names exists — a multi-select list ` + `(\`[A, B]\`) reads each entry against \`Data\` itself, so on a list ` + `result use \`[].[A, B]\` or \`[].{a: A, b: B}\` to read the records`;
+    }
+  } else if (outcome.kind === "null-rows") {
+    lede = "returned only null values";
+    const projected = `every value it projected is null on all ${outcome.count} row(s)`;
+    detail = unknown.length > 0 ? `${projected}, because ${isNotAField(unknown)}` : withSoundness(projected);
+  } else if (outcome.kind === "null-values") {
+    lede = "returned only null values";
+    const projected = `every key it projected (${nameList(outcome.keys)}) is null`;
+    const sameSet = unknown.length === outcome.keys.length && outcome.keys.every((k) => unknown.includes(k));
+    if (sameSet) {
+      detail = `${isNotAField(outcome.keys)}, so every key it projected is null`;
+    } else if (unknown.length > 0) {
+      detail = `${projected}, because ${isNotAField(unknown)}`;
+    } else {
+      detail = withSoundness(`${projected} on all ${scope}`);
+    }
+  } else {
+    lede = "returned nothing";
+    if (unknown.length > 0) {
+      detail = isNotAField(unknown);
+    } else {
+      const selection = refs.hasPredicate ? "no record matched" : "the expression resolved to no value";
+      detail = withSoundness(`${selection} — it read ${scope}`);
+    }
+  }
+  const fields = present.length > 0 ? ` Available fields: ${nameList(present)}.` : "";
+  return `--output-filter ${JSON.stringify(filter)} ${lede}: ${detail}.${fields}`;
+}
+function appendWarning(existing, note) {
+  return existing ? `${existing} ${note}` : note;
+}
+function applyFilter(data, filter, onWarning) {
   const codec = requireJmespath();
   let result;
   try {
@@ -11571,9 +11730,34 @@ function applyFilter(data, filter) {
   } catch (err) {
     throw new FilterEvaluationError(filter, err);
   }
-  if (result == null)
+  const inputCount = countRecords(data);
+  const warn = (outcome) => {
+    if (inputCount === 0)
+      return;
+    const note = buildFilterWarning(filter, data, outcome);
+    getOutputSink().writeErr(`[WARN] ${note}
+`);
+    onWarning?.(note);
+  };
+  const warnIfAllNull = (records) => {
+    const keys = alwaysNullKeys(records);
+    if (keys.length > 0)
+      warn({ kind: "null-values", keys });
+  };
+  if (result == null) {
+    warn({ kind: "empty" });
     return [];
+  }
   if (Array.isArray(result)) {
+    if (result.length === 0) {
+      warn({ kind: "empty" });
+    } else if (result.every((entry) => entry === null)) {
+      warn({ kind: "null-elements", count: result.length });
+    } else if (result.every((entry) => Array.isArray(entry)) && carriesOnlyNulls(result)) {
+      warn({ kind: "null-rows", count: result.length });
+    } else {
+      warnIfAllNull(result);
+    }
     if (result.length > 0 && typeof result[0] !== "object") {
       const fieldMatch = filter.match(/\.(\w+)$/);
       const key = fieldMatch ? fieldMatch[1] : "Value";
@@ -11581,10 +11765,30 @@ function applyFilter(data, filter) {
     }
     return result;
   }
-  if (typeof result === "object")
+  if (typeof result === "object") {
+    warnIfAllNull([result]);
     return result;
+  }
   return { Value: result };
 }
+function filterFailureData(envelope) {
+  const filter = getOutputFilter();
+  const data = envelope.Data;
+  if (!filter || data == null)
+    return;
+  let note;
+  const [filterError, filtered] = catchError(() => applyFilter(data, filter, (n) => {
+    note = n;
+  }));
+  if (filterError) {
+    envelope.Warning = appendWarning(envelope.Warning, `--output-filter was not applied, so Data is shown in full: ${filterError.message}`);
+    return;
+  }
+  envelope.Data = filtered;
+  if (note) {
+    envelope.Warning = appendWarning(envelope.Warning, note);
+  }
+}
 function defaultErrorCodeForResult(result) {
   switch (result) {
     case RESULTS.AuthenticationError:
@@ -11667,8 +11871,14 @@ var OutputFormatter;
     }
     const filter = getOutputFilter();
     if (filter) {
-      const filtered = applyFilter(data.Data, filter);
+      let note;
+      const filtered = applyFilter(data.Data, filter, (n) => {
+        note = n;
+      });
       data.Data = normalize ? normalizeDataKeys(filtered, verbatim, subtrees && { refs: subtrees.refs, mode: "skip" }) : filtered;
+      if (note) {
+        data.Warning = appendWarning(data.Warning, note);
+      }
     }
     logOutput(normalizeOutputKeys(data), getOutputFormat(), options?.tableRowStyle);
   }
@@ -11696,6 +11906,7 @@ var OutputFormatter;
     delete envelope.TelemetryErrorClass;
     delete envelope.TelemetryTerminalOutcome;
     delete envelope.TelemetryTerminalSignal;
+    filterFailureData(envelope);
     if (!suppressTelemetry) {
       telemetry.trackEvent(CommonTelemetryEvents.Error, {
         result: data.Result,
@@ -11744,13 +11955,20 @@ var OutputFormatter;
   OutputFormatter.log = log;
   function formatToString(data) {
     const filter = getOutputFilter();
+    const envelope = data;
     if ("Data" in data && data.Data != null) {
       data.Data = normalizeDataKeys(data.Data);
       if (filter) {
-        data.Data = normalizeDataKeys(applyFilter(data.Data, filter));
+        let note;
+        data.Data = normalizeDataKeys(applyFilter(data.Data, filter, (n) => {
+          note = n;
+        }));
+        if (note) {
+          envelope.Warning = appendWarning(envelope.Warning, note);
+        }
       }
     }
-    const output = normalizeOutputKeys(data);
+    const output = normalizeOutputKeys(envelope);
     const lines = [];
     const sink = getOutputSink();
     printOutput(output, getOutputFormat(), (msg) => {
@@ -14032,4 +14250,4 @@ export {
   writeTelemetrySpoolFile
 };
 
-//# debugId=1C8485A93560E50864756E2164756E21
+//# debugId=C7396FAC1D7B6F8064756E2164756E21

package/package.json

@@ -2,7 +2,7 @@
     "name": "@uipath/common",
     "author": "UiPath",
     "license": "SEE LICENSE IN LICENSE.txt",
-    "version": "1.203.0-preview.235",
+    "version": "1.203.0-preview.237",
     "description": "Common infrastructure needed by uip tools.",
     "repository": {
         "type": "git",
@@ -80,5 +80,5 @@
         "mihaigirleanu",
         "vlad-uipath"
     ],
-    "gitHead": "4788b04c17a4429e5a994af2c3eba3898d1c4b13"
+    "gitHead": "4ad3e17a66f2c7fb7fe1f0e3e04a5b6175a0a9a3"
 }