flecto 1.0.2 → 2.1.0

package/src/renderer.js

@@ -1,12 +1,18 @@
 import chalk from 'chalk';
 
+const SECRET_PATH_RE = /(secret|token|password|api[_-]?key|private[_-]?key|credential)/i;
+
 /**
  * Format a scalar value for display. Strings get quoted; others are JSON-stringified.
  * @param {unknown} v
+ * @param {{ maskSecrets?: boolean, path?: string }} [opts]
  * @returns {string}
  */
-function fmt(v) {
+function fmt(v, opts = {}) {
   if (v === undefined) return '';
+  if (opts.maskSecrets && opts.path && SECRET_PATH_RE.test(opts.path)) {
+    return chalk.dim('"***"');
+  }
   if (typeof v === 'string') return JSON.stringify(v);
   if (typeof v === 'object' && v !== null) return JSON.stringify(v);
   return String(v);
@@ -24,35 +30,36 @@ function timestamp() {
  * Render a single change event as a colored string.
  * @param {import('./differ.js').ChangeEvent} event
  * @param {'compact' | 'verbose'} mode
+ * @param {{ maskSecrets?: boolean }} [opts]
  * @returns {string}
  */
-function renderEvent(event, mode) {
+function renderEvent(event, mode, opts = {}) {
   const { type, path, before, after, note } = event;
+  const maskOpts = { maskSecrets: Boolean(opts.maskSecrets), path };
 
   if (type === 'added') {
-    const line = `  ${chalk.green('+')} ${chalk.green(path)}: ${chalk.green(fmt(after))}`;
+    const line = `  ${chalk.green('+')} ${chalk.green(path)}: ${chalk.green(fmt(after, maskOpts))}`;
     return mode === 'verbose'
       ? `${line}\n    ${chalk.dim('(key added)')}`
       : line;
   }
 
   if (type === 'removed') {
-    const line = `  ${chalk.red('-')} ${chalk.red(path)}: ${chalk.red(fmt(before))}`;
+    const line = `  ${chalk.red('-')} ${chalk.red(path)}: ${chalk.red(fmt(before, maskOpts))}`;
     return mode === 'verbose'
       ? `${line}\n    ${chalk.dim('(key removed)')}`
       : line;
   }
 
-  // changed
   const noteStr = note ? chalk.dim(` [${note}]`) : '';
   if (mode === 'verbose') {
     return [
       `  ${chalk.yellow('~')} ${chalk.yellow(path)}${noteStr}`,
-      `    ${chalk.dim('before:')} ${chalk.red(fmt(before))}`,
-      `    ${chalk.dim('after: ')} ${chalk.green(fmt(after))}`,
+      `    ${chalk.dim('before:')} ${chalk.red(fmt(before, maskOpts))}`,
+      `    ${chalk.dim('after: ')} ${chalk.green(fmt(after, maskOpts))}`,
     ].join('\n');
   }
-  return `  ${chalk.yellow('~')} ${chalk.yellow(path)}: ${chalk.red(fmt(before))} ${chalk.dim('→')} ${chalk.green(fmt(after))}${noteStr}`;
+  return `  ${chalk.yellow('~')} ${chalk.yellow(path)}: ${chalk.red(fmt(before, maskOpts))} ${chalk.dim('→')} ${chalk.green(fmt(after, maskOpts))}${noteStr}`;
 }
 
 /**
@@ -60,15 +67,16 @@ function renderEvent(event, mode) {
  * @param {string} filepath
  * @param {import('./differ.js').ChangeEvent[]} events
  * @param {'compact' | 'verbose'} mode
+ * @param {{ maskSecrets?: boolean }} [opts]
  */
-export function renderChanges(filepath, events, mode = 'compact') {
+export function renderChanges(filepath, events, mode = 'compact', opts = {}) {
   const ts = chalk.dim(`[${timestamp()}]`);
   const file = chalk.cyan(filepath);
   const count = `${events.length} change${events.length !== 1 ? 's' : ''}`;
 
   console.log(`${ts} ${file} — ${count}`);
   for (const event of events) {
-    console.log(renderEvent(event, mode));
+    console.log(renderEvent(event, mode, opts));
   }
 
   if (mode === 'verbose') {
@@ -80,8 +88,9 @@ export function renderChanges(filepath, events, mode = 'compact') {
  * Print a diff result (for --diff mode) to stdout.
  * @param {string} filepath
  * @param {import('./differ.js').ChangeEvent[]} events
+ * @param {{ maskSecrets?: boolean }} [opts]
  */
-export function renderDiff(filepath, events) {
+export function renderDiff(filepath, events, opts = {}) {
   if (events.length === 0) {
     console.log(chalk.green(`✓ ${filepath} matches snapshot — no changes`));
     return;
@@ -89,7 +98,7 @@ export function renderDiff(filepath, events) {
 
   console.log(chalk.cyan(`${filepath}`) + ` — ${events.length} change${events.length !== 1 ? 's' : ''} from snapshot:`);
   for (const event of events) {
-    console.log(renderEvent(event, 'compact'));
+    console.log(renderEvent(event, 'compact', opts));
   }
 }
 
@@ -129,6 +138,46 @@ export function renderPolicyFindings(findings) {
       : f.severity === 'warn'
         ? chalk.yellow('! policy(warn)')
         : chalk.blue('! policy(info)');
-    console.log(`  ${prefix} ${chalk.cyan(f.path)}: ${f.message}`);
+    const pack = f.pack ? chalk.dim(` [${f.pack}]`) : '';
+    console.log(`  ${prefix}${pack} ${chalk.cyan(f.path)}: ${f.message}`);
+  }
+}
+
+/**
+ * Mask secret-like values in a plain object tree for CI output.
+ * @param {unknown} value
+ * @param {string} [path]
+ * @returns {unknown}
+ */
+export function maskSensitiveValue(value, path = '') {
+  if (SECRET_PATH_RE.test(path)) return '***';
+  if (Array.isArray(value)) {
+    return value.map((v, i) => maskSensitiveValue(v, `${path}[${i}]`));
   }
+  if (
+    value
+    && typeof value === 'object'
+    && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null)
+  ) {
+    /** @type {Record<string, unknown>} */
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+      const child = path ? `${path}.${k}` : k;
+      out[k] = maskSensitiveValue(v, child);
+    }
+    return out;
+  }
+  return value;
+}
+
+/**
+ * @param {import('./differ.js').ChangeEvent} event
+ * @returns {import('./differ.js').ChangeEvent}
+ */
+export function maskChangeEvent(event) {
+  return {
+    ...event,
+    before: event.before === undefined ? undefined : maskSensitiveValue(event.before, event.path),
+    after: event.after === undefined ? undefined : maskSensitiveValue(event.after, event.path),
+  };
 }

package/src/watcher.js

@@ -11,6 +11,9 @@ import { renderWarn, renderInfo } from './renderer.js';
  * @property {boolean}  [polling]      Force polling mode (default: false)
  * @property {string}   [mode]         Output mode: 'compact' | 'verbose'
  * @property {string[]} [ignorePaths]  Key paths to suppress in diffs
+ * @property {string | null} [arrayIdKey]
+ * @property {boolean} [arrayIdentity]
+ * @property {boolean} [arrayIgnoreOrder]
  */
 
 /**
@@ -18,13 +21,19 @@ import { renderWarn, renderInfo } from './renderer.js';
  *
  * @param {string} filepath
  * @param {WatcherOptions} options
- * @param {(event: { kind: 'changes', filepath: string, events: ChangeEvent[] } | { kind: 'lifecycle', filepath: string, lifecycle: { type: string, message: string } }) => void} onEvent
+ * @param {(event: { kind: 'changes', filepath: string, events: ChangeEvent[] } | { kind: 'lifecycle', filepath: string, lifecycle: { type: string, message: string } }) => void | Promise<void>} onEvent
  * @returns {import('chokidar').FSWatcher}
  */
 export function startWatcher(filepath, options = {}, onEvent) {
   const interval = options.interval ?? 100;
   const ignorePaths = options.ignorePaths ?? [];
   const polling = options.polling ?? false;
+  const diffOpts = {
+    ignorePaths,
+    arrayIdKey: options.arrayIdKey ?? null,
+    arrayIdentity: options.arrayIdentity !== false,
+    arrayIgnoreOrder: Boolean(options.arrayIgnoreOrder),
+  };
 
   /** @type {unknown | null} */
   let lastGoodState = null;
@@ -35,7 +44,7 @@ export function startWatcher(filepath, options = {}, onEvent) {
   } catch (err) {
     renderWarn(`Could not parse initial state of "${filepath}": ${err.message}`);
     renderWarn('Watching anyway — will use first successful parse as baseline.');
-    onEvent({
+    safelyEmit(onEvent, {
       kind: 'lifecycle',
       filepath,
       lifecycle: { type: 'initial-parse-failed', message: err.message },
@@ -60,17 +69,17 @@ export function startWatcher(filepath, options = {}, onEvent) {
   const scheduleRead = (reason) => {
     if (debounceTimer) clearTimeout(debounceTimer);
     debounceTimer = setTimeout(() => {
-      handleChange(filepath, ignorePaths, lastGoodState, (newState, events, lifecycle) => {
+      handleChange(filepath, diffOpts, lastGoodState, (newState, events, lifecycle) => {
         if (newState !== null) {
           lastGoodState = newState;
         }
         if (lifecycle) {
-          onEvent({ kind: 'lifecycle', filepath, lifecycle });
+          safelyEmit(onEvent, { kind: 'lifecycle', filepath, lifecycle });
         }
         if (events.length > 0) {
-          onEvent({ kind: 'changes', filepath, events });
+          safelyEmit(onEvent, { kind: 'changes', filepath, events });
         } else if (reason === 'add') {
-          onEvent({
+          safelyEmit(onEvent, {
             kind: 'lifecycle',
             filepath,
             lifecycle: { type: 'file-restored', message: 'File content reloaded after add event.' },
@@ -89,7 +98,7 @@ export function startWatcher(filepath, options = {}, onEvent) {
   watcher.on('unlink', () => {
     // File temporarily missing; keep last good state and wait for add.
     renderWarn(`File disappeared: "${filepath}" (waiting for it to reappear)`);
-    onEvent({
+    safelyEmit(onEvent, {
       kind: 'lifecycle',
       filepath,
       lifecycle: { type: 'file-missing', message: 'File disappeared; waiting for restore.' },
@@ -98,7 +107,7 @@ export function startWatcher(filepath, options = {}, onEvent) {
 
   watcher.on('error', (err) => {
     renderWarn(`Watcher error: ${err.message}`);
-    onEvent({
+    safelyEmit(onEvent, {
       kind: 'lifecycle',
       filepath,
       lifecycle: { type: 'watcher-error', message: err.message },
@@ -108,14 +117,22 @@ export function startWatcher(filepath, options = {}, onEvent) {
   return watcher;
 }
 
+function safelyEmit(onEvent, event) {
+  Promise.resolve()
+    .then(() => onEvent(event))
+    .catch((err) => {
+      renderWarn(`Watcher event handler error: ${err?.message ?? String(err)}`);
+    });
+}
+
 /**
  * Internal: re-parse the file and diff against the previous state.
  * @param {string} filepath
- * @param {string[]} ignorePaths
+ * @param {{ ignorePaths?: string[], arrayIdKey?: string | null, arrayIdentity?: boolean, arrayIgnoreOrder?: boolean }} diffOpts
  * @param {unknown | null} lastGoodState
  * @param {(newState: unknown | null, events: ChangeEvent[], lifecycle: { type: string, message: string } | null) => void} callback
  */
-function handleChange(filepath, ignorePaths, lastGoodState, callback) {
+function handleChange(filepath, diffOpts, lastGoodState, callback) {
   let newState;
   try {
     newState = parseFile(filepath);
@@ -132,6 +149,6 @@ function handleChange(filepath, ignorePaths, lastGoodState, callback) {
     return;
   }
 
-  const events = diffTrees(lastGoodState, newState, { ignorePaths });
+  const events = diffTrees(lastGoodState, newState, diffOpts);
   callback(newState, events, null);
 }