flecto 2.0.0 → 3.0.0

package/src/differ.js

@@ -1,14 +1,61 @@
+import { annotateEncryptedChanges } from './encrypted.js';
+import { diffDocumentKeys, stripDocumentPrefix } from './documents.js';
+
 /**
  * @typedef {{ type: 'added' | 'removed' | 'changed', path: string, before?: unknown, after?: unknown, note?: string }} ChangeEvent
  */
 
+/**
+ * Where an event's path carries a synthetic multi-document prefix, the same
+ * path without it. Recorded non-enumerably so the event stays byte-identical
+ * everywhere it is serialized — JSON output, webhook payloads, snapshots.
+ */
+const SECRET_MATCH_PATH = Symbol.for('flecto.secretMatchPath');
+
+/**
+ * The path to match secret-looking *key names* against.
+ *
+ * For an ordinary file this is just `event.path`. For a multi-document file it
+ * is the path with the document identity removed, because that identity is a
+ * resource name — user data — and a Deployment called `token-service` must not
+ * make every value inside it read as a secret. See documents.js.
+ * @param {ChangeEvent} event
+ * @returns {string}
+ */
+export function secretMatchPath(event) {
+  const stripped = /** @type {Record<string | symbol, unknown>} */ (event)?.[SECRET_MATCH_PATH];
+  return typeof stripped === 'string' ? stripped : (event?.path ?? '');
+}
+
+/**
+ * @param {ChangeEvent[]} events
+ * @param {readonly string[]} documentKeys
+ * @returns {ChangeEvent[]}
+ */
+function tagSecretMatchPaths(events, documentKeys) {
+  if (documentKeys.length === 0) return events;
+  for (const event of events) {
+    const stripped = stripDocumentPrefix(event.path, documentKeys);
+    if (stripped === event.path) continue;
+    Object.defineProperty(event, SECRET_MATCH_PATH, {
+      value: stripped,
+      enumerable: false,
+      writable: false,
+      configurable: true,
+    });
+  }
+  return events;
+}
+
 /**
  * Checks whether a value is a plain object (not array, not null).
  * @param {unknown} v
  * @returns {v is Record<string, unknown>}
  */
 function isPlainObject(v) {
-  return v !== null && typeof v === 'object' && !Array.isArray(v);
+  if (v === null || typeof v !== 'object' || Array.isArray(v)) return false;
+  const prototype = Object.getPrototypeOf(v);
+  return prototype === Object.prototype || prototype === null;
 }
 
 /**
@@ -61,10 +108,9 @@ function makeIgnoreMatcher(patterns) {
     }
 
     if (keyAnywhere.size > 0) {
+      const pathParts = splitPathParts(path);
       for (const key of keyAnywhere) {
-        if (path === key) return true;
-        if (path.includes(`.${key}`)) return true;
-        if (path.includes(`].${key}`)) return true;
+        if (pathParts.includes(key)) return true;
       }
     }
 
@@ -139,7 +185,7 @@ function matchParts(patternParts, pathParts) {
  * @param {unknown} after
  * @param {string} path
  * @param {ChangeEvent[]} events  accumulator
- * @param {{ arrayIdKey?: string | null, arrayIgnoreOrder?: boolean }} [options]
+ * @param {{ arrayIdKey?: string | null, arrayIdentity?: boolean, arrayIgnoreOrder?: boolean }} [options]
  */
 function diffValues(before, after, path, events, options = {}) {
   const beforeIsObj = isPlainObject(before);
@@ -200,7 +246,7 @@ function diffValues(before, after, path, events, options = {}) {
  * @param {Record<string, unknown>} after
  * @param {string} basePath
  * @param {ChangeEvent[]} events
- * @param {{ arrayIdKey?: string | null, arrayIgnoreOrder?: boolean }} [options]
+ * @param {{ arrayIdKey?: string | null, arrayIdentity?: boolean, arrayIgnoreOrder?: boolean }} [options]
  */
 function diffObjects(before, after, basePath, events, options = {}) {
   const beforeKeys = new Set(Object.keys(before));
@@ -245,43 +291,90 @@ function identityKey(item, idKey) {
 }
 
 /**
- * Diff arrays by identity key when configured; otherwise by index.
+ * @param {unknown[]} items
+ * @param {string} idKey
+ * @returns {Map<string, { value: unknown, index: number }> | null}
+ */
+function identityMap(items, idKey) {
+  /** @type {Map<string, { value: unknown, index: number }>} */
+  const map = new Map();
+  for (let i = 0; i < items.length; i++) {
+    const key = identityKey(items[i], idKey);
+    if (key == null || map.has(key)) return null;
+    map.set(key, { value: items[i], index: i });
+  }
+  return map;
+}
+
+/**
+ * Select a configured identity key, or auto-detect id then name.
+ * @param {unknown[]} before
+ * @param {unknown[]} after
+ * @param {{ arrayIdKey?: string | null, arrayIdentity?: boolean }} options
+ * @returns {string | null}
+ */
+function resolveArrayIdKey(before, after, options) {
+  // An explicit key always enables identity matching, even when arrayIdentity
+  // is off (e.g. .flectorc arrayId:false plus CLI --array-id-key).
+  const configured = options.arrayIdKey ? String(options.arrayIdKey) : null;
+  if (configured) return configured;
+
+  if (options.arrayIdentity === false) return null;
+
+  for (const candidate of ['id', 'name']) {
+    if (identityMap(before, candidate) && identityMap(after, candidate)) {
+      return candidate;
+    }
+  }
+  return null;
+}
+
+/**
+ * Produce a stable JSON signature for order-insensitive array comparison.
+ * Object keys are sorted so their insertion order does not affect equality.
+ * Non-JSON values fall back to their identity, avoiding serialization errors.
+ * @param {unknown} value
+ * @returns {unknown}
+ */
+function arraySignature(value) {
+  try {
+    const canonicalize = (item) => {
+      if (Array.isArray(item)) return item.map(canonicalize);
+      if (
+        !isPlainObject(item) ||
+        (Object.getPrototypeOf(item) !== Object.prototype && Object.getPrototypeOf(item) !== null)
+      ) {
+        return item;
+      }
+      return Object.fromEntries(
+        Object.keys(item)
+          .sort()
+          .map((key) => [key, canonicalize(item[key])])
+      );
+    };
+    const signature = JSON.stringify(canonicalize(value));
+    return signature === undefined ? value : signature;
+  } catch {
+    return value;
+  }
+}
+
+/**
+ * Diff arrays by configured or auto-detected identity key; otherwise by index.
  * @param {unknown[]} before
  * @param {unknown[]} after
  * @param {string} basePath
  * @param {ChangeEvent[]} events
- * @param {{ arrayIdKey?: string | null, arrayIgnoreOrder?: boolean }} [options]
+ * @param {{ arrayIdKey?: string | null, arrayIdentity?: boolean, arrayIgnoreOrder?: boolean }} [options]
  */
 function diffArrays(before, after, basePath, events, options = {}) {
-  const idKey = options.arrayIdKey ? String(options.arrayIdKey) : null;
+  const idKey = resolveArrayIdKey(before, after, options);
 
   if (idKey) {
-    /** @type {Map<string, { value: unknown, index: number }>} */
-    const beforeMap = new Map();
-    /** @type {Map<string, { value: unknown, index: number }>} */
-    const afterMap = new Map();
-    let canUseIdentity = true;
-
-    for (let i = 0; i < before.length; i++) {
-      const key = identityKey(before[i], idKey);
-      if (key == null || beforeMap.has(key)) {
-        canUseIdentity = false;
-        break;
-      }
-      beforeMap.set(key, { value: before[i], index: i });
-    }
-    if (canUseIdentity) {
-      for (let i = 0; i < after.length; i++) {
-        const key = identityKey(after[i], idKey);
-        if (key == null || afterMap.has(key)) {
-          canUseIdentity = false;
-          break;
-        }
-        afterMap.set(key, { value: after[i], index: i });
-      }
-    }
+    const beforeMap = identityMap(before, idKey);
+    const afterMap = identityMap(after, idKey);
 
-    if (canUseIdentity) {
+    if (beforeMap && afterMap) {
       for (const [key, afterItem] of afterMap) {
         const childPath = `${basePath}[${JSON.stringify(key)}]`;
         if (!beforeMap.has(key)) {
@@ -302,19 +395,22 @@ function diffArrays(before, after, basePath, events, options = {}) {
 
   if (options.arrayIgnoreOrder) {
     // Order-insensitive without id key: multiset compare via JSON signatures
-    const beforeSigs = before.map((v) => JSON.stringify(v));
-    const afterSigs = after.map((v) => JSON.stringify(v));
-    /** @type {Map<string, number>} */
+    /** @type {Map<unknown, { count: number, value: unknown }>} */
     const counts = new Map();
-    for (const s of beforeSigs) counts.set(s, (counts.get(s) ?? 0) + 1);
-    for (const s of afterSigs) {
-      const n = counts.get(s) ?? 0;
-      if (n > 0) counts.set(s, n - 1);
-      else events.push({ type: 'added', path: `${basePath}[*]`, after: JSON.parse(s) });
+    for (const value of before) {
+      const signature = arraySignature(value);
+      const entry = counts.get(signature);
+      if (entry) entry.count++;
+      else counts.set(signature, { count: 1, value });
+    }
+    for (const value of after) {
+      const entry = counts.get(arraySignature(value));
+      if (entry?.count > 0) entry.count--;
+      else events.push({ type: 'added', path: `${basePath}[*]`, after: value });
     }
-    for (const [s, n] of counts) {
-      for (let i = 0; i < n; i++) {
-        events.push({ type: 'removed', path: `${basePath}[*]`, before: JSON.parse(s) });
+    for (const entry of counts.values()) {
+      for (let i = 0; i < entry.count; i++) {
+        events.push({ type: 'removed', path: `${basePath}[*]`, before: entry.value });
       }
     }
     return;
@@ -338,7 +434,7 @@ function diffArrays(before, after, basePath, events, options = {}) {
  * Accepts any JSON-like values at the root (object/array/scalar/null).
  * @param {unknown} before
  * @param {unknown} after
- * @param {{ ignorePaths?: string[], arrayIdKey?: string | null, arrayIgnoreOrder?: boolean }} [options]
+ * @param {{ ignorePaths?: string[], arrayIdKey?: string | null, arrayIdentity?: boolean, arrayIgnoreOrder?: boolean }} [options]
  * @returns {ChangeEvent[]}
  */
 export function diffTrees(before, after, options = {}) {
@@ -347,6 +443,7 @@ export function diffTrees(before, after, options = {}) {
   const ignore = makeIgnoreMatcher(options.ignorePaths ?? []);
   const diffOpts = {
     arrayIdKey: options.arrayIdKey ?? null,
+    arrayIdentity: options.arrayIdentity !== false,
     arrayIgnoreOrder: Boolean(options.arrayIgnoreOrder),
   };
 
@@ -360,5 +457,15 @@ export function diffTrees(before, after, options = {}) {
     diffValues(before, after, '<root>', events, diffOpts);
   }
 
-  return events.filter(e => !ignore(e.path));
+  // Encrypted files carry signals a key-by-key walk cannot express: the file
+  // gaining or losing encryption, and a MAC that moved on its own. This is a
+  // no-op — the same array, untouched — when neither side is encrypted.
+  // Ignore patterns are applied afterwards so `--ignore` silences the derived
+  // paths exactly like any other.
+  const annotated = annotateEncryptedChanges(before, after, events).filter(e => !ignore(e.path));
+
+  // Multi-document paths carry a resource name in front. Record what secret-name
+  // matching should look at, once, here — the renderers see events and nothing
+  // else, and a resource name must never decide whether a value gets masked.
+  return tagSecretMatchPaths(annotated, diffDocumentKeys(before, after));
 }

package/src/documents.js

@@ -0,0 +1,106 @@
+/**
+ * Carrying the "this tree is a multi-document wrapper" signal.
+ *
+ * A `---`-separated YAML file parses to a synthetic object keyed by document
+ * identity (see `parseYamlStream`), so every path inside a document gains a
+ * `Kind/namespace/name` prefix. Several subsystems need to know which leading
+ * path segments are those synthetic keys rather than real configuration keys —
+ * most importantly secret-name matching, which must never look at a resource
+ * name, because a resource *named* `token-service` is not a secret.
+ *
+ * The parser is the only thing that can answer this without guessing: it
+ * invented the keys. Rather than re-deriving them downstream from the shape of
+ * the keys — a heuristic that misfires the first time somebody writes a config
+ * whose top-level keys genuinely look like `Kind/ns/name` — the parser records
+ * them here and everything else reads them back.
+ *
+ * The record is a non-enumerable symbol property, so it is invisible to
+ * `Object.keys`, `JSON.stringify`, spread, and `assert.deepEqual`: a marked tree
+ * is byte-for-byte the same snapshot, diff, and payload it was before. The flip
+ * side is that it does not survive a JSON round trip, so a tree read back out of
+ * a snapshot file carries the keys only if the snapshot recorded them.
+ * `documentKeysOf` distinguishes the two: `[]` means "known not to be a
+ * wrapper", `null` means "provenance unknown".
+ */
+
+/** Where the synthetic document keys are recorded on a parsed tree. */
+const DOCUMENT_KEYS = Symbol.for('flecto.documentKeys');
+
+/** @type {readonly string[]} */
+const NONE = Object.freeze([]);
+
+/**
+ * Record the synthetic document keys the parser invented for a tree.
+ *
+ * Returns the tree itself — marking is a side effect on an object Flecto just
+ * created, never a copy. Non-object roots (a scalar YAML document, an opaque
+ * age blob) cannot carry the mark and are returned unchanged.
+ * @template T
+ * @param {T} tree
+ * @param {readonly string[] | null | undefined} keys
+ * @returns {T}
+ */
+export function withDocumentKeys(tree, keys) {
+  if (tree === null || typeof tree !== 'object') return tree;
+  Object.defineProperty(tree, DOCUMENT_KEYS, {
+    value: keys == null ? null : Object.freeze([...keys]),
+    enumerable: false,
+    writable: false,
+    configurable: true,
+  });
+  return tree;
+}
+
+/**
+ * The synthetic document keys recorded on a tree.
+ * @param {unknown} tree
+ * @returns {readonly string[] | null} `[]` when the tree is known to be a single
+ *   document, `null` when nothing recorded its provenance
+ */
+export function documentKeysOf(tree) {
+  if (tree === null || typeof tree !== 'object') return null;
+  const keys = /** @type {Record<string | symbol, unknown>} */ (tree)[DOCUMENT_KEYS];
+  return Array.isArray(keys) ? /** @type {readonly string[]} */ (keys) : null;
+}
+
+/**
+ * The document keys covering either side of a diff, longest first.
+ *
+ * A document present on only one side still prefixes the paths of its own
+ * additions or removals, so the union is what a path can start with. Longest
+ * first so that if one identity is a prefix of another — `app` and `app.web` —
+ * a path is attributed to the more specific one.
+ * @param {unknown} before
+ * @param {unknown} after
+ * @returns {readonly string[]}
+ */
+export function diffDocumentKeys(before, after) {
+  const merged = [...(documentKeysOf(before) ?? NONE), ...(documentKeysOf(after) ?? NONE)];
+  if (merged.length === 0) return NONE;
+  return [...new Set(merged)].sort((a, b) => b.length - a.length);
+}
+
+/**
+ * Drop a leading document-identity segment from a diff path.
+ *
+ * Matching is by whole segment against the keys the parser actually invented,
+ * not by pattern, so `Deployment/prod/token-service.spec.replicas` becomes
+ * `spec.replicas` while an ordinary key that merely begins with the same text
+ * is left alone. Returns the path unchanged when no key applies, which is the
+ * single-document case and therefore the common one.
+ * @param {string} path
+ * @param {readonly string[] | null | undefined} keys tried in order; see
+ *   {@link diffDocumentKeys} for why callers pass them longest first
+ * @returns {string}
+ */
+export function stripDocumentPrefix(path, keys) {
+  if (!keys || keys.length === 0 || !path) return path;
+  for (const key of keys) {
+    if (!key || !path.startsWith(key)) continue;
+    if (path.length === key.length) return '';
+    const next = path[key.length];
+    if (next === '.') return path.slice(key.length + 1);
+    if (next === '[') return path.slice(key.length);
+  }
+  return path;
+}