flecto 2.0.0 → 2.1.0

package/src/policy.js

@@ -17,13 +17,35 @@ import yaml from 'js-yaml';
  *   id: string,
  *   severity: PolicySeverity,
  *   when?: Array<'added' | 'removed' | 'changed'>,
- *   match?: { path?: string, pathFlags?: string },
+ *   match?: { path?: string, pathFlags?: string, pathEquals?: string, pathPrefix?: string },
+ *   beforeEquals?: unknown,
  *   afterEquals?: unknown,
+ *   beforeIn?: unknown[],
+ *   afterIn?: unknown[],
+ *   beforeTruthy?: true,
+ *   afterTruthy?: true,
+ *   afterMatches?: string,
  *   numericJump?: { minMultiple: number },
+ *   numericDelta?: { min: number },
+ *   allOf?: PolicyMatchClause[],
+ *   anyOf?: PolicyMatchClause[],
  *   message?: string,
  *   messageTemplate?: string
  * }} PolicyRule
  *
+ * @typedef {{
+ *   match?: { path?: string, pathFlags?: string, pathEquals?: string, pathPrefix?: string },
+ *   beforeEquals?: unknown,
+ *   afterEquals?: unknown,
+ *   beforeIn?: unknown[],
+ *   afterIn?: unknown[],
+ *   beforeTruthy?: true,
+ *   afterTruthy?: true,
+ *   afterMatches?: string,
+ *   numericJump?: { minMultiple: number },
+ *   numericDelta?: { min: number }
+ * }} PolicyMatchClause
+ *
  * @typedef {{ id: string, rules: PolicyRule[] }} PolicyPack
  *
  * @typedef {{
@@ -32,12 +54,85 @@ import yaml from 'js-yaml';
  *   profile?: string | null,
  *   source?: 'watch' | 'ci' | 'diff',
  *   policies?: string[],
- *   plugins?: string[]
+ *   plugins?: string[],
+ *   severityRemap?: Record<string, PolicySeverity | 'off'>
  * }} PolicyEvalOptions
  */
 
 const SEVERITY_RANK = { info: 1, warn: 2, error: 3 };
 const PACKS_DIR = join(dirname(fileURLToPath(import.meta.url)), 'packs');
+const CHANGE_TYPES = new Set(['added', 'removed', 'changed']);
+const RULE_FIELDS = new Set([
+  'id', 'severity', 'when', 'match', 'beforeEquals', 'afterEquals',
+  'beforeIn', 'afterIn', 'beforeTruthy', 'afterTruthy', 'numericJump',
+  'afterMatches', 'numericDelta', 'allOf', 'anyOf', 'message', 'messageTemplate',
+]);
+const CLAUSE_FIELDS = new Set([
+  'match', 'beforeEquals', 'afterEquals', 'beforeIn', 'afterIn',
+  'beforeTruthy', 'afterTruthy', 'afterMatches', 'numericJump', 'numericDelta',
+]);
+const MATCH_FIELDS = new Set(['path', 'pathFlags', 'pathEquals', 'pathPrefix']);
+
+/**
+ * @param {string} path
+ * @param {string} message
+ * @returns {never}
+ */
+function invalidPack(path, message) {
+  throw new Error(`Invalid policy pack at ${path}: ${message}`);
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is Record<string, unknown>}
+ */
+function isObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+/**
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function isTruthyToggle(value) {
+  if (value === true) return true;
+  if (typeof value !== 'string') return false;
+  return ['true', '1', 'yes'].includes(value.trim().toLowerCase());
+}
+
+/**
+ * Validate a parsed policy pack and reject typos before evaluation.
+ * @param {unknown} pack
+ * @param {string} path
+ * @returns {asserts pack is PolicyPack}
+ */
+function validatePack(pack, path) {
+  if (!isObject(pack)) invalidPack(path, 'pack must be an object');
+
+  const packFields = new Set(['id', 'rules']);
+  for (const field of Object.keys(pack)) {
+    if (!packFields.has(field)) invalidPack(path, `pack.${field} is not allowed`);
+  }
+  if (Object.hasOwn(pack, 'id') && (typeof pack.id !== 'string' || !pack.id.trim())) {
+    invalidPack(path, 'pack.id must be a non-empty string');
+  }
+  if (!Array.isArray(pack.rules)) invalidPack(path, 'pack.rules must be an array');
+
+  for (const [index, rule] of pack.rules.entries()) {
+    try {
+      validateRule(rule, `rules[${index}]`);
+    } catch (error) {
+      const label = isObject(rule) && typeof rule.id === 'string' && rule.id
+        ? `rule "${rule.id}"`
+        : `rules[${index}]`;
+      const message = error.message.replace(/^Invalid policy rule at [^:]+: /, '')
+        .replace(/^unknown field "([^"]+)"$/, '$1 is not allowed (unknown field "$1")')
+        .replace(/^unknown match field "([^"]+)"$/, 'match.$1 is not allowed (unknown match field "$1")')
+        .replace(/^match\.path is not a valid regular expression$/, 'match.path must be a valid regular expression');
+      invalidPack(path, `${label}.${message}`);
+    }
+  }
+}
 
 /**
  * @param {string} cwd
@@ -59,18 +154,150 @@ function resolvePackPath(cwd, packId) {
 
 /**
  * @param {string} path
+ * @param {string} fallbackId
  * @returns {PolicyPack}
  */
-function readPackFile(path) {
+function readPackFile(path, fallbackId) {
   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[] }`);
+  let parsed;
+  try {
+    parsed = path.endsWith('.json') ? JSON.parse(raw) : yaml.load(raw);
+  } catch (error) {
+    invalidPack(path, `could not parse file (${error.message})`);
   }
-  return {
-    id: String(parsed.id ?? ''),
-    rules: parsed.rules,
-  };
+  validatePack(parsed, path);
+  return { ...parsed, id: parsed.id ?? fallbackId };
+}
+
+/**
+ * Validate a rule or composition clause so pack typos fail closed at load time.
+ * @param {unknown} candidate
+ * @param {string} location
+ * @param {boolean} [isClause]
+ */
+function validateRule(candidate, location, isClause = false) {
+  if (!candidate || typeof candidate !== 'object' || Array.isArray(candidate)) {
+    throw new Error(`Invalid policy rule at ${location}: expected an object`);
+  }
+
+  const allowedFields = isClause ? CLAUSE_FIELDS : RULE_FIELDS;
+  for (const key of Object.keys(candidate)) {
+    if (!allowedFields.has(key)) {
+      throw new Error(`Invalid policy rule at ${location}: unknown field "${key}"`);
+    }
+  }
+
+  const rule = /** @type {Record<string, unknown>} */ (candidate);
+  if (!isClause && (typeof rule.id !== 'string' || !rule.id)) {
+    throw new Error(`Invalid policy rule at ${location}: id is required`);
+  }
+  if (!isClause && (!Object.hasOwn(rule, 'severity') || !Object.hasOwn(SEVERITY_RANK, rule.severity))) {
+    throw new Error(`Invalid policy rule at ${location}: severity must be one of: info, warn, error`);
+  }
+  if (rule.when !== undefined
+    && (!Array.isArray(rule.when) || rule.when.length === 0 || rule.when.some((type) => !CHANGE_TYPES.has(type)))) {
+    const invalidIndex = Array.isArray(rule.when)
+      ? rule.when.findIndex((type) => !CHANGE_TYPES.has(type))
+      : -1;
+    throw new Error(`Invalid policy rule at ${location}: when${invalidIndex >= 0 ? `[${invalidIndex}]` : ''} must be one of: added, removed, changed`);
+  }
+  validateMatch(rule.match, location);
+  validateArrayPredicate(rule.beforeIn, 'beforeIn', location);
+  validateArrayPredicate(rule.afterIn, 'afterIn', location);
+  validateTruthyPredicate(rule.beforeTruthy, 'beforeTruthy', location);
+  validateTruthyPredicate(rule.afterTruthy, 'afterTruthy', location);
+  validateRegexPredicate(rule.afterMatches, 'afterMatches', location);
+  validateNumericPredicate(rule.numericJump, 'numericJump', 'minMultiple', location, true);
+  validateNumericPredicate(rule.numericDelta, 'numericDelta', 'min', location, false);
+  for (const name of ['message', 'messageTemplate']) {
+    if (rule[name] !== undefined && typeof rule[name] !== 'string') {
+      throw new Error(`Invalid policy rule at ${location}: ${name} must be a string`);
+    }
+  }
+
+  if (!isClause) {
+    validateComposition(rule.allOf, 'allOf', location);
+    validateComposition(rule.anyOf, 'anyOf', location);
+  }
+}
+
+/** @param {unknown} match @param {string} location */
+function validateMatch(match, location) {
+  if (match === undefined) return;
+  if (!match || typeof match !== 'object' || Array.isArray(match)) {
+    throw new Error(`Invalid policy rule at ${location}: match must be an object`);
+  }
+  for (const key of Object.keys(match)) {
+    if (!MATCH_FIELDS.has(key)) {
+      throw new Error(`Invalid policy rule at ${location}: unknown match field "${key}"`);
+    }
+  }
+  const typedMatch = /** @type {Record<string, unknown>} */ (match);
+  for (const key of MATCH_FIELDS) {
+    if (typedMatch[key] !== undefined && typeof typedMatch[key] !== 'string') {
+      throw new Error(`Invalid policy rule at ${location}: match.${key} must be a string`);
+    }
+  }
+  if (typedMatch.path !== undefined) {
+    try {
+      new RegExp(typedMatch.path, typedMatch.pathFlags ?? '');
+    } catch {
+      if (typedMatch.pathFlags !== undefined) {
+        try {
+          new RegExp('(?:)', typedMatch.pathFlags);
+        } catch {
+          throw new Error(`Invalid policy rule at ${location}: match.pathFlags must be valid regular expression flags`);
+        }
+      }
+      throw new Error(`Invalid policy rule at ${location}: match.path is not a valid regular expression`);
+    }
+  }
+}
+
+/** @param {unknown} value @param {string} name @param {string} location */
+function validateArrayPredicate(value, name, location) {
+  if (value !== undefined && !Array.isArray(value)) {
+    throw new Error(`Invalid policy rule at ${location}: ${name} must be an array`);
+  }
+}
+
+/** @param {unknown} value @param {string} name @param {string} location */
+function validateTruthyPredicate(value, name, location) {
+  if (value !== undefined && value !== true) {
+    throw new Error(`Invalid policy rule at ${location}: ${name} must be true`);
+  }
+}
+
+/** @param {unknown} value @param {string} name @param {string} location */
+function validateRegexPredicate(value, name, location) {
+  if (value === undefined) return;
+  if (typeof value !== 'string') {
+    throw new Error(`Invalid policy rule at ${location}: ${name} must be a string`);
+  }
+  try {
+    new RegExp(value);
+  } catch {
+    throw new Error(`Invalid policy rule at ${location}: ${name} is not a valid regular expression`);
+  }
+}
+
+/** @param {unknown} value @param {string} name @param {string} property @param {string} location @param {boolean} positive */
+function validateNumericPredicate(value, name, property, location, positive) {
+  if (value === undefined) return;
+  if (!value || typeof value !== 'object' || Array.isArray(value)
+    || typeof value[property] !== 'number' || !Number.isFinite(value[property])
+    || (positive ? value[property] <= 0 : value[property] < 0)) {
+    throw new Error(`Invalid policy rule at ${location}: ${name}.${property} must be a ${positive ? 'positive' : 'non-negative'} finite number`);
+  }
+}
+
+/** @param {unknown} clauses @param {string} name @param {string} location */
+function validateComposition(clauses, name, location) {
+  if (clauses === undefined) return;
+  if (!Array.isArray(clauses) || clauses.length === 0) {
+    throw new Error(`Invalid policy rule at ${location}: ${name} must be a non-empty array of match clauses`);
+  }
+  clauses.forEach((clause, index) => validateRule(clause, `${location}.${name}[${index}]`, true));
 }
 
 /**
@@ -86,9 +313,7 @@ export function loadPack(packId, cwd = process.cwd()) {
   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;
+  return readPackFile(path, id);
 }
 
 /**
@@ -102,6 +327,47 @@ export function listBuiltinPackIds() {
     .map((f) => f.replace(/\.json$/, ''));
 }
 
+/**
+ * List every policy pack resolvable from a working directory. Local packs take
+ * precedence over built-ins using the same order as loadPack().
+ * @param {string} [cwd]
+ * @returns {Array<{
+ *   id: string,
+ *   sourcePath: string,
+ *   source: 'builtin' | 'local',
+ *   ruleCount: number,
+ *   overridesBuiltin: boolean
+ * }>}
+ */
+export function listPolicyPacks(cwd = process.cwd()) {
+  const localDir = resolve(cwd, 'policies');
+  const localIds = existsSync(localDir)
+    ? readdirSync(localDir)
+      .filter((file) => /\.(json|yaml|yml)$/.test(file))
+      .map((file) => file.replace(/\.(json|yaml|yml)$/, ''))
+    : [];
+  const builtinIds = listBuiltinPackIds();
+  const builtinIdSet = new Set(builtinIds);
+
+  return [...new Set([...builtinIds, ...localIds])]
+    .sort()
+    .map((id) => {
+      const sourcePath = resolvePackPath(cwd, id);
+      if (!sourcePath) {
+        throw new Error(`Unable to resolve policy pack "${id}"`);
+      }
+      const pack = readPackFile(sourcePath, id);
+      const isLocal = localIds.includes(id);
+      return {
+        id,
+        sourcePath,
+        source: isLocal ? 'local' : 'builtin',
+        ruleCount: pack.rules.length,
+        overridesBuiltin: isLocal && builtinIdSet.has(id),
+      };
+    });
+}
+
 /**
  * @param {PolicyRule} rule
  * @param {import('./differ.js').ChangeEvent} change
@@ -110,22 +376,44 @@ export function listBuiltinPackIds() {
 function ruleMatches(rule, change) {
   const when = rule.when ?? ['added', 'removed', 'changed'];
   if (!when.includes(change.type)) return false;
+  if (!matchClause(rule, change)) return false;
+  if (rule.allOf?.some((clause) => !matchClause(clause, change))) return false;
+  if (rule.anyOf && !rule.anyOf.some((clause) => matchClause(clause, change))) return false;
+  return true;
+}
 
-  if (rule.match?.path) {
-    const flags = rule.match.pathFlags ?? '';
-    const re = new RegExp(rule.match.path, flags);
-    if (!re.test(change.path ?? '')) return false;
-  }
+/**
+ * @param {PolicyMatchClause} clause
+ * @param {import('./differ.js').ChangeEvent} change
+ * @returns {boolean}
+ */
+function matchClause(clause, change) {
+  const path = change.path ?? '';
+  const match = clause.match;
+  if (match?.path && !new RegExp(match.path, match.pathFlags ?? '').test(path)) return false;
+  if (match?.pathEquals !== undefined && path !== match.pathEquals) return false;
+  if (match?.pathPrefix !== undefined && !path.startsWith(match.pathPrefix)) return false;
+
+  if (Object.prototype.hasOwnProperty.call(clause, 'beforeEquals') && change.before !== clause.beforeEquals) return false;
+  if (Object.prototype.hasOwnProperty.call(clause, 'afterEquals') && change.after !== clause.afterEquals) return false;
+  if (clause.beforeIn && !clause.beforeIn.includes(change.before)) return false;
+  if (clause.afterIn && !clause.afterIn.includes(change.after)) return false;
+  if (clause.beforeTruthy && !isTruthyToggle(change.before)) return false;
+  if (clause.afterTruthy && !isTruthyToggle(change.after)) return false;
+  if (clause.afterMatches && (typeof change.after !== 'string' || !new RegExp(clause.afterMatches).test(change.after))) return false;
 
-  if (Object.prototype.hasOwnProperty.call(rule, 'afterEquals')) {
-    if (change.after !== rule.afterEquals) return false;
+  if (clause.numericJump) {
+    const before = change.before;
+    const after = change.after;
+    if (typeof before !== 'number' || typeof after !== 'number') return false;
+    if (!(before > 0 && after >= before * clause.numericJump.minMultiple)) return false;
   }
 
-  if (rule.numericJump) {
+  if (clause.numericDelta) {
     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;
+    if (Math.abs(after - before) < clause.numericDelta.min) return false;
   }
 
   return true;
@@ -149,17 +437,20 @@ function formatMessage(rule, change) {
 /**
  * @param {PolicyPack} pack
  * @param {import('./differ.js').ChangeEvent[]} changes
+ * @param {Record<string, PolicySeverity | 'off'>} [severityRemap]
  * @returns {PolicyFinding[]}
  */
-export function evaluatePack(pack, changes) {
+export function evaluatePack(pack, changes, severityRemap = {}) {
   /** @type {PolicyFinding[]} */
   const findings = [];
   for (const change of changes) {
     for (const rule of pack.rules ?? []) {
       if (!ruleMatches(rule, change)) continue;
+      const severity = severityRemap[String(rule.id)] ?? rule.severity ?? 'warn';
+      if (severity === 'off') continue;
       findings.push({
         id: String(rule.id),
-        severity: rule.severity ?? 'warn',
+        severity,
         path: change.path ?? '',
         message: formatMessage(rule, change),
         pack: pack.id,
@@ -241,12 +532,19 @@ export async function evaluatePolicies(changes, options = {}) {
   const cwd = options.cwd ?? process.cwd();
   const packIds = options.policies?.length ? options.policies : ['default'];
   const plugins = options.plugins ?? [];
+  const severityRemap = options.severityRemap ?? {};
 
   /** @type {PolicyFinding[]} */
   const findings = [];
-  for (const packId of packIds) {
-    const pack = loadPack(packId, cwd);
-    findings.push(...evaluatePack(pack, changes));
+  const packs = packIds.map((packId) => loadPack(packId, cwd));
+  const knownRuleIds = new Set(packs.flatMap((pack) => pack.rules.map((rule) => String(rule.id))));
+  for (const ruleId of Object.keys(severityRemap)) {
+    if (!knownRuleIds.has(ruleId)) {
+      console.warn(`Unknown policy rule id in severityRemap: "${ruleId}"`);
+    }
+  }
+  for (const pack of packs) {
+    findings.push(...evaluatePack(pack, changes, severityRemap));
   }
 
   const ctx = {

package/src/renderer.js

@@ -154,7 +154,11 @@ export function maskSensitiveValue(value, path = '') {
   if (Array.isArray(value)) {
     return value.map((v, i) => maskSensitiveValue(v, `${path}[${i}]`));
   }
-  if (value && typeof value === 'object') {
+  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)) {
@@ -171,10 +175,9 @@ export function maskSensitiveValue(value, path = '') {
  * @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 : '***',
+    before: event.before === undefined ? undefined : maskSensitiveValue(event.before, event.path),
+    after: event.after === undefined ? undefined : maskSensitiveValue(event.after, event.path),
   };
 }

package/src/watcher.js

@@ -12,6 +12,7 @@ import { renderWarn, renderInfo } from './renderer.js';
  * @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]
  */
 
@@ -20,7 +21,7 @@ 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) {
@@ -30,6 +31,7 @@ export function startWatcher(filepath, options = {}, onEvent) {
   const diffOpts = {
     ignorePaths,
     arrayIdKey: options.arrayIdKey ?? null,
+    arrayIdentity: options.arrayIdentity !== false,
     arrayIgnoreOrder: Boolean(options.arrayIgnoreOrder),
   };
 
@@ -42,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 },
@@ -72,12 +74,12 @@ export function startWatcher(filepath, options = {}, onEvent) {
           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.' },
@@ -96,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.' },
@@ -105,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 },
@@ -115,10 +117,18 @@ 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 {{ ignorePaths?: string[], arrayIdKey?: string | null, arrayIgnoreOrder?: boolean }} diffOpts
+ * @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
  */