flecto 2.0.0 → 2.1.0

package/src/config.js

@@ -73,6 +73,7 @@ export function resolveEffectiveOptions(config, profile, cliOverrides = {}) {
 export function resolvePolicyOptions(effective) {
   const policiesRaw = effective.policies;
   const pluginsRaw = effective.plugins;
+  const severityRemapRaw = effective.severityRemap;
   const policies = Array.isArray(policiesRaw)
     ? policiesRaw.map(String)
     : typeof policiesRaw === 'string'
@@ -83,7 +84,22 @@ export function resolvePolicyOptions(effective) {
     : typeof pluginsRaw === 'string'
       ? String(pluginsRaw).split(',').map((s) => s.trim()).filter(Boolean)
       : [];
-  return { policies, plugins };
+  if (
+    severityRemapRaw !== undefined
+    && (severityRemapRaw === null || Array.isArray(severityRemapRaw) || typeof severityRemapRaw !== 'object')
+  ) {
+    throw new Error('severityRemap must be an object mapping rule ids to info, warn, error, or off');
+  }
+  const severityRemap = {};
+  for (const [ruleId, severity] of Object.entries(severityRemapRaw ?? {})) {
+    if (!['info', 'warn', 'error', 'off'].includes(severity)) {
+      throw new Error(
+        `severityRemap for "${ruleId}" must be one of: info, warn, error, off`,
+      );
+    }
+    severityRemap[ruleId] = severity;
+  }
+  return { policies, plugins, severityRemap };
 }
 
 /**
@@ -127,13 +143,18 @@ export function initRcFile(cwd = process.cwd()) {
       policies: ['default'],
       plugins: [],
       arrayIdKey: null,
+      arrayId: true,
       arrayIgnoreOrder: false,
       maskSecrets: false,
     },
     profiles: {
       dev: { mode: 'verbose' },
       ci: { failOn: 'policy,error' },
-      prod: { policies: ['default', 'strict-prod'], maskSecrets: true },
+      prod: {
+        policies: ['default', 'strict-prod'],
+        severityRemap: { 'pool-size-jump': 'error' },
+        maskSecrets: true,
+      },
     },
     files: ['config/**/*.{yaml,yml,json,toml,ini}', '.env', '.env.*', '*.env'],
     exclude: ['**/node_modules/**'],

package/src/differ.js

@@ -61,10 +61,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 +138,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 +199,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 +244,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 +348,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 +387,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 +396,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),
   };
 

package/src/packs/compose.json

@@ -0,0 +1,45 @@
+{
+  "id": "compose",
+  "rules": [
+    {
+      "id": "compose-privileged-service",
+      "severity": "error",
+      "when": ["added", "changed"],
+      "match": {
+        "path": "(^|\\.)privileged$"
+      },
+      "afterEquals": true,
+      "message": "Docker Compose service is privileged. Remove privileged mode or document the required host access."
+    },
+    {
+      "id": "compose-host-network",
+      "severity": "error",
+      "when": ["added", "changed"],
+      "match": {
+        "path": "(^|\\.)network_mode$"
+      },
+      "afterIn": ["host", "host:"],
+      "message": "Docker Compose service uses the host network. Confirm the service needs to bypass network isolation."
+    },
+    {
+      "id": "compose-docker-socket-bind",
+      "severity": "error",
+      "when": ["added", "changed"],
+      "match": {
+        "path": "(^|\\.)volumes\\[\\d+\\](\\.source)?$"
+      },
+      "afterMatches": "^/var/run/docker\\.sock(?::|$)",
+      "message": "Docker Compose service mounts the Docker socket. This grants control over the host Docker daemon."
+    },
+    {
+      "id": "compose-sensitive-host-bind",
+      "severity": "warn",
+      "when": ["added", "changed"],
+      "match": {
+        "path": "(^|\\.)volumes\\[\\d+\\](\\.source)?$"
+      },
+      "afterMatches": "^/(?:etc|root|home|var/lib)(?::|$)",
+      "message": "Docker Compose service bind-mounts a sensitive host directory. Confirm the container needs this host access."
+    }
+  ]
+}

package/src/packs/default.json

@@ -19,7 +19,7 @@
         "path": "(debug|allow_insecure|disable_tls|skip_tls_verify)",
         "pathFlags": "i"
       },
-      "afterEquals": true,
+      "afterTruthy": true,
       "message": "Potentially dangerous toggle enabled."
     },
     {

package/src/packs/node-runtime.json

@@ -0,0 +1,44 @@
+{
+  "id": "node-runtime",
+  "rules": [
+    {
+      "id": "node-runtime-engine-removed",
+      "severity": "warn",
+      "when": ["removed"],
+      "match": {
+        "pathEquals": "engines.node"
+      },
+      "message": "Node.js engine requirement was removed. Keep a supported runtime floor to avoid accidental runtime downgrades."
+    },
+    {
+      "id": "node-runtime-tls-verification-disabled",
+      "severity": "error",
+      "when": ["added", "changed"],
+      "match": {
+        "path": "(^|\\.)NODE_TLS_REJECT_UNAUTHORIZED$"
+      },
+      "afterIn": [0, "0"],
+      "message": "NODE_TLS_REJECT_UNAUTHORIZED disables TLS certificate verification. Remove it and fix the certificate chain."
+    },
+    {
+      "id": "node-runtime-debug-enabled",
+      "severity": "warn",
+      "when": ["added", "changed"],
+      "match": {
+        "path": "(^|\\.)NODE_DEBUG$"
+      },
+      "afterMatches": ".+",
+      "message": "NODE_DEBUG is enabled. Confirm verbose runtime debugging is appropriate for this environment."
+    },
+    {
+      "id": "node-runtime-inspector-enabled",
+      "severity": "warn",
+      "when": ["added", "changed"],
+      "match": {
+        "path": "(^|\\.)NODE_OPTIONS$"
+      },
+      "afterMatches": "(^|\\s)--inspect(?:-brk)?(?:=|\\s|$)",
+      "message": "Node.js inspector is enabled through NODE_OPTIONS. Avoid exposing debug ports outside trusted development environments."
+    }
+  ]
+}

package/src/packs/strict-prod.json

@@ -19,7 +19,7 @@
         "path": "(debug|allow_insecure|disable_tls|skip_tls_verify|permit_all)",
         "pathFlags": "i"
       },
-      "afterEquals": true,
+      "afterTruthy": true,
       "message": "Dangerous toggle enabled in production profile."
     },
     {

package/src/policy-test.js

@@ -0,0 +1,124 @@
+import { existsSync, readFileSync } from 'fs';
+import { join, resolve } from 'path';
+
+import { diffTrees } from './differ.js';
+import { parseFile } from './parser.js';
+import { evaluatePolicies } from './policy.js';
+
+const DEFAULT_CONFIG_NAME = 'flecto-policy-test.json';
+
+function readJson(path, label) {
+  if (!existsSync(path)) {
+    throw new Error(`Policy fixture ${label} not found: ${path}`);
+  }
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch (err) {
+    throw new Error(`Policy fixture ${label} is not valid JSON: ${path}: ${err.message}`);
+  }
+}
+
+function validateExpectedFinding(finding, index) {
+  if (!finding || typeof finding !== 'object') {
+    throw new Error(`Policy fixture expected[${index}] must be an object`);
+  }
+  for (const field of ['id', 'severity', 'path']) {
+    if (typeof finding[field] !== 'string' || !finding[field]) {
+      throw new Error(`Policy fixture expected[${index}].${field} must be a non-empty string`);
+    }
+  }
+}
+
+function findingKey(finding) {
+  return `${finding.id}\u0000${finding.severity}\u0000${finding.path}`;
+}
+
+function displayFinding(finding) {
+  return `${finding.severity} ${finding.id} at ${finding.path}`;
+}
+
+/**
+ * Compare findings by id, severity, and path, ignoring messages and pack labels.
+ * @param {import('./policy.js').PolicyFinding[]} actual
+ * @param {Array<{id: string, severity: string, path: string}>} expected
+ */
+export function assertExpectedFindings(actual, expected) {
+  const expectedByKey = new Map();
+  const actualByKey = new Map();
+  for (const finding of expected) {
+    const key = findingKey(finding);
+    expectedByKey.set(key, (expectedByKey.get(key) ?? 0) + 1);
+  }
+  for (const finding of actual) {
+    const key = findingKey(finding);
+    actualByKey.set(key, (actualByKey.get(key) ?? 0) + 1);
+  }
+
+  const missing = [];
+  const unexpected = [];
+  for (const finding of expected) {
+    const key = findingKey(finding);
+    if ((actualByKey.get(key) ?? 0) > 0) {
+      actualByKey.set(key, actualByKey.get(key) - 1);
+    } else {
+      missing.push(finding);
+    }
+  }
+  for (const finding of actual) {
+    const key = findingKey(finding);
+    if ((expectedByKey.get(key) ?? 0) > 0) {
+      expectedByKey.set(key, expectedByKey.get(key) - 1);
+    } else {
+      unexpected.push(finding);
+    }
+  }
+
+  if (missing.length === 0 && unexpected.length === 0) return;
+
+  const lines = ['Policy fixture findings did not match.'];
+  if (missing.length > 0) {
+    lines.push('Missing findings:');
+    lines.push(...missing.map((finding) => `  - ${displayFinding(finding)}`));
+  }
+  if (unexpected.length > 0) {
+    lines.push('Unexpected findings:');
+    lines.push(...unexpected.map((finding) => `  - ${displayFinding(finding)}`));
+  }
+  throw new Error(lines.join('\n'));
+}
+
+/**
+ * Run a policy fixture stored in a directory.
+ * @param {string} fixtureDir
+ * @param {{ configName?: string }} [options]
+ */
+export async function testPolicyFixture(fixtureDir, options = {}) {
+  const dir = resolve(fixtureDir);
+  const configName = options.configName ?? DEFAULT_CONFIG_NAME;
+  const configPath = join(dir, configName);
+  const config = readJson(configPath, 'config');
+  if (!Array.isArray(config.expected)) {
+    throw new Error(`Policy fixture config must contain an expected array: ${configPath}`);
+  }
+  config.expected.forEach(validateExpectedFinding);
+
+  const baselinePath = resolve(dir, config.baseline ?? 'baseline.json');
+  const currentPath = resolve(dir, config.current ?? 'current.json');
+  const baseline = readJson(baselinePath, 'baseline');
+  if (!existsSync(currentPath)) {
+    throw new Error(`Policy fixture current file not found: ${currentPath}`);
+  }
+
+  const changes = diffTrees(baseline.state ?? baseline, parseFile(currentPath));
+  const findings = await evaluatePolicies(changes, {
+    cwd: dir,
+    file: currentPath,
+    profile: config.profile ?? null,
+    source: config.source ?? 'ci',
+    policies: config.policies,
+    plugins: config.plugins,
+  });
+  assertExpectedFindings(findings, config.expected);
+
+  return { fixtureDir: dir, changes, findings };
+}