flecto 1.0.2 → 2.0.0

package/src/policy.js

@@ -1,57 +1,267 @@
+import { existsSync, readFileSync, readdirSync } from 'fs';
+import { dirname, isAbsolute, join, resolve } from 'path';
+import { fileURLToPath, pathToFileURL } from 'url';
+import yaml from 'js-yaml';
+
 /**
  * @typedef {'info' | 'warn' | 'error'} PolicySeverity
- * @typedef {{ id: string, severity: PolicySeverity, path: string, message: string }} PolicyFinding
+ * @typedef {{
+ *   id: string,
+ *   severity: PolicySeverity,
+ *   path: string,
+ *   message: string,
+ *   pack?: string
+ * }} PolicyFinding
+ *
+ * @typedef {{
+ *   id: string,
+ *   severity: PolicySeverity,
+ *   when?: Array<'added' | 'removed' | 'changed'>,
+ *   match?: { path?: string, pathFlags?: string },
+ *   afterEquals?: unknown,
+ *   numericJump?: { minMultiple: number },
+ *   message?: string,
+ *   messageTemplate?: string
+ * }} PolicyRule
+ *
+ * @typedef {{ id: string, rules: PolicyRule[] }} PolicyPack
+ *
+ * @typedef {{
+ *   cwd?: string,
+ *   file?: string,
+ *   profile?: string | null,
+ *   source?: 'watch' | 'ci' | 'diff',
+ *   policies?: string[],
+ *   plugins?: string[]
+ * }} PolicyEvalOptions
+ */
+
+const SEVERITY_RANK = { info: 1, warn: 2, error: 3 };
+const PACKS_DIR = join(dirname(fileURLToPath(import.meta.url)), 'packs');
+
+/**
+ * @param {string} cwd
+ * @param {string} packId
+ * @returns {string | null}
  */
+function resolvePackPath(cwd, packId) {
+  const localJson = resolve(cwd, 'policies', `${packId}.json`);
+  const localYaml = resolve(cwd, 'policies', `${packId}.yaml`);
+  const localYml = resolve(cwd, 'policies', `${packId}.yml`);
+  if (existsSync(localJson)) return localJson;
+  if (existsSync(localYaml)) return localYaml;
+  if (existsSync(localYml)) return localYml;
 
-const SECRET_KEY_RE = /(secret|token|password|api[_-]?key|private[_-]?key)/i;
-const DANGEROUS_TOGGLE_RE = /(debug|allow_insecure|disable_tls|skip_tls_verify)/i;
+  const builtinJson = join(PACKS_DIR, `${packId}.json`);
+  if (existsSync(builtinJson)) return builtinJson;
+  return null;
+}
 
 /**
- * Evaluate built-in policy checks against semantic changes.
+ * @param {string} path
+ * @returns {PolicyPack}
+ */
+function readPackFile(path) {
+  const raw = readFileSync(path, 'utf8');
+  const parsed = path.endsWith('.json') ? JSON.parse(raw) : yaml.load(raw);
+  if (!parsed || typeof parsed !== 'object' || !Array.isArray(parsed.rules)) {
+    throw new Error(`Invalid policy pack at ${path}: expected { id, rules[] }`);
+  }
+  return {
+    id: String(parsed.id ?? ''),
+    rules: parsed.rules,
+  };
+}
+
+/**
+ * Load a pack by id from policies/ then built-ins.
+ * @param {string} packId
+ * @param {string} [cwd]
+ * @returns {PolicyPack}
+ */
+export function loadPack(packId, cwd = process.cwd()) {
+  const id = String(packId ?? '').trim();
+  if (!id) throw new Error('Policy pack id is required');
+  const path = resolvePackPath(cwd, id);
+  if (!path) {
+    throw new Error(`Unknown policy pack "${id}". Add policies/${id}.json or use a built-in pack.`);
+  }
+  const pack = readPackFile(path);
+  if (!pack.id) pack.id = id;
+  return pack;
+}
+
+/**
+ * List built-in pack ids.
+ * @returns {string[]}
+ */
+export function listBuiltinPackIds() {
+  if (!existsSync(PACKS_DIR)) return [];
+  return readdirSync(PACKS_DIR)
+    .filter((f) => f.endsWith('.json'))
+    .map((f) => f.replace(/\.json$/, ''));
+}
+
+/**
+ * @param {PolicyRule} rule
+ * @param {import('./differ.js').ChangeEvent} change
+ * @returns {boolean}
+ */
+function ruleMatches(rule, change) {
+  const when = rule.when ?? ['added', 'removed', 'changed'];
+  if (!when.includes(change.type)) return false;
+
+  if (rule.match?.path) {
+    const flags = rule.match.pathFlags ?? '';
+    const re = new RegExp(rule.match.path, flags);
+    if (!re.test(change.path ?? '')) return false;
+  }
+
+  if (Object.prototype.hasOwnProperty.call(rule, 'afterEquals')) {
+    if (change.after !== rule.afterEquals) return false;
+  }
+
+  if (rule.numericJump) {
+    const before = change.before;
+    const after = change.after;
+    if (typeof before !== 'number' || typeof after !== 'number') return false;
+    if (!(before > 0 && after >= before * rule.numericJump.minMultiple)) return false;
+  }
+
+  return true;
+}
+
+/**
+ * @param {PolicyRule} rule
+ * @param {import('./differ.js').ChangeEvent} change
+ * @returns {string}
+ */
+function formatMessage(rule, change) {
+  if (rule.messageTemplate) {
+    return rule.messageTemplate
+      .replaceAll('{before}', String(change.before))
+      .replaceAll('{after}', String(change.after))
+      .replaceAll('{path}', String(change.path ?? ''));
+  }
+  return rule.message ?? `Policy ${rule.id} matched`;
+}
+
+/**
+ * @param {PolicyPack} pack
  * @param {import('./differ.js').ChangeEvent[]} changes
  * @returns {PolicyFinding[]}
  */
-export function evaluatePolicies(changes) {
+export function evaluatePack(pack, changes) {
   /** @type {PolicyFinding[]} */
   const findings = [];
-
   for (const change of changes) {
-    const path = change.path ?? '';
-    const pathLower = path.toLowerCase();
-
-    if (SECRET_KEY_RE.test(pathLower) && (change.type === 'changed' || change.type === 'added')) {
+    for (const rule of pack.rules ?? []) {
+      if (!ruleMatches(rule, change)) continue;
       findings.push({
-        id: 'secret-key-changed',
-        severity: 'error',
-        path,
-        message: change.type === 'added'
-          ? 'Sensitive-looking key added. Confirm secret storage and access controls.'
-          : 'Sensitive-looking key changed. Confirm secret rotation and access controls.',
+        id: String(rule.id),
+        severity: rule.severity ?? 'warn',
+        path: change.path ?? '',
+        message: formatMessage(rule, change),
+        pack: pack.id,
       });
     }
+  }
+  return findings;
+}
 
-    if (DANGEROUS_TOGGLE_RE.test(pathLower) && change.type === 'changed' && change.after === true) {
-      findings.push({
-        id: 'dangerous-toggle-enabled',
-        severity: 'error',
-        path,
-        message: 'Potentially dangerous toggle enabled.',
-      });
+/**
+ * Merge findings: same id+path keeps highest severity; ties keep first.
+ * @param {PolicyFinding[]} findings
+ * @returns {PolicyFinding[]}
+ */
+export function mergeFindings(findings) {
+  /** @type {Map<string, PolicyFinding>} */
+  const byKey = new Map();
+  for (const finding of findings) {
+    const key = `${finding.id}::${finding.path}`;
+    const existing = byKey.get(key);
+    if (!existing) {
+      byKey.set(key, finding);
+      continue;
     }
+    const nextRank = SEVERITY_RANK[finding.severity] ?? 0;
+    const prevRank = SEVERITY_RANK[existing.severity] ?? 0;
+    if (nextRank > prevRank) byKey.set(key, finding);
+  }
+  return [...byKey.values()];
+}
 
-    if (pathLower.endsWith('pool_size') && typeof change.before === 'number' && typeof change.after === 'number') {
-      if (change.before > 0 && change.after >= change.before * 2) {
-        findings.push({
-          id: 'pool-size-jump',
-          severity: 'warn',
-          path,
-          message: `Pool size increased from ${change.before} to ${change.after} (>=2x).`,
-        });
-      }
-    }
+/**
+ * @param {string} pluginPath
+ * @param {string} cwd
+ * @returns {string}
+ */
+function resolvePluginPath(pluginPath, cwd) {
+  if (/^https?:\/\//i.test(pluginPath)) {
+    throw new Error(`Remote plugins are not allowed: ${pluginPath}`);
   }
+  return isAbsolute(pluginPath) ? pluginPath : resolve(cwd, pluginPath);
+}
 
-  return findings;
+/**
+ * @param {string} pluginPath
+ * @param {import('./differ.js').ChangeEvent[]} changes
+ * @param {Required<Pick<PolicyEvalOptions, 'cwd' | 'file' | 'profile' | 'source'>> & { packIds: string[] }} ctx
+ * @returns {Promise<PolicyFinding[]>}
+ */
+async function runPlugin(pluginPath, changes, ctx) {
+  const abs = resolvePluginPath(pluginPath, ctx.cwd);
+  if (!existsSync(abs)) {
+    throw new Error(`Policy plugin not found: ${pluginPath}`);
+  }
+  const mod = await import(pathToFileURL(abs).href);
+  if (typeof mod.evaluate !== 'function') {
+    throw new Error(`Policy plugin missing export evaluate(): ${pluginPath}`);
+  }
+  const result = await mod.evaluate(changes, ctx);
+  if (!Array.isArray(result)) {
+    throw new Error(`Policy plugin must return PolicyFinding[]: ${pluginPath}`);
+  }
+  return result.map((f) => ({
+    id: String(f.id),
+    severity: f.severity,
+    path: String(f.path ?? ''),
+    message: String(f.message ?? ''),
+    pack: f.pack ?? `plugin:${pluginPath}`,
+  }));
+}
+
+/**
+ * Evaluate active packs then plugins.
+ * @param {import('./differ.js').ChangeEvent[]} changes
+ * @param {PolicyEvalOptions} [options]
+ * @returns {Promise<PolicyFinding[]>}
+ */
+export async function evaluatePolicies(changes, options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const packIds = options.policies?.length ? options.policies : ['default'];
+  const plugins = options.plugins ?? [];
+
+  /** @type {PolicyFinding[]} */
+  const findings = [];
+  for (const packId of packIds) {
+    const pack = loadPack(packId, cwd);
+    findings.push(...evaluatePack(pack, changes));
+  }
+
+  const ctx = {
+    cwd,
+    file: options.file ?? '',
+    profile: options.profile ?? null,
+    source: options.source ?? 'watch',
+    packIds,
+  };
+
+  for (const pluginPath of plugins) {
+    findings.push(...await runPlugin(pluginPath, changes, ctx));
+  }
+
+  return mergeFindings(findings);
 }
 
 /**
@@ -64,4 +274,3 @@ export function highestSeverity(findings) {
   if (findings.some((f) => f.severity === 'warn')) return 'warn';
   return 'info';
 }
-

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,43 @@ 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') {
+    /** @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) {
+  if (!SECRET_PATH_RE.test(event.path ?? '')) return event;
+  return {
+    ...event,
+    before: event.before === undefined ? undefined : '***',
+    after: event.after === undefined ? undefined : '***',
+  };
 }

package/src/watcher.js

@@ -11,6 +11,8 @@ 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} [arrayIgnoreOrder]
  */
 
 /**
@@ -25,6 +27,11 @@ 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,
+    arrayIgnoreOrder: Boolean(options.arrayIgnoreOrder),
+  };
 
   /** @type {unknown | null} */
   let lastGoodState = null;
@@ -60,7 +67,7 @@ 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;
         }
@@ -111,11 +118,11 @@ export function startWatcher(filepath, options = {}, onEvent) {
 /**
  * Internal: re-parse the file and diff against the previous state.
  * @param {string} filepath
- * @param {string[]} ignorePaths
+ * @param {{ ignorePaths?: string[], arrayIdKey?: string | null, 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 +139,6 @@ function handleChange(filepath, ignorePaths, lastGoodState, callback) {
     return;
   }
 
-  const events = diffTrees(lastGoodState, newState, { ignorePaths });
+  const events = diffTrees(lastGoodState, newState, diffOpts);
   callback(newState, events, null);
 }