flecto 1.0.2 → 2.1.0

package/schemas/flecto-policy-pack-2.0.json

@@ -0,0 +1,124 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/myselfsiddharth/Flecto/schemas/flecto-policy-pack-2.0.json",
+  "title": "FlectoPolicyPack",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["rules"],
+  "properties": {
+    "id": { "type": "string", "minLength": 1 },
+    "rules": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/rule" }
+    }
+  },
+  "$defs": {
+    "rule": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "severity"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "severity": { "enum": ["info", "warn", "error"] },
+        "when": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "enum": ["added", "removed", "changed"] }
+        },
+        "match": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "path": { "type": "string" },
+            "pathFlags": { "type": "string" },
+            "pathEquals": { "type": "string" },
+            "pathPrefix": { "type": "string" }
+          }
+        },
+        "beforeEquals": true,
+        "afterEquals": true,
+        "beforeIn": { "type": "array" },
+        "afterIn": { "type": "array" },
+        "beforeTruthy": { "const": true },
+        "afterTruthy": { "const": true },
+        "afterMatches": { "type": "string" },
+        "numericJump": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["minMultiple"],
+          "properties": {
+            "minMultiple": {
+              "type": "number",
+              "exclusiveMinimum": 0
+            }
+          }
+        },
+        "numericDelta": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["min"],
+          "properties": {
+            "min": {
+              "type": "number",
+              "minimum": 0
+            }
+          }
+        },
+        "allOf": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/clause" }
+        },
+        "anyOf": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/clause" }
+        },
+        "message": { "type": "string" },
+        "messageTemplate": { "type": "string" }
+      }
+    },
+    "clause": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "match": { "$ref": "#/$defs/match" },
+        "beforeEquals": true,
+        "afterEquals": true,
+        "beforeIn": { "type": "array" },
+        "afterIn": { "type": "array" },
+        "beforeTruthy": { "const": true },
+        "afterTruthy": { "const": true },
+        "afterMatches": { "type": "string" },
+        "numericJump": { "$ref": "#/$defs/numericJump" },
+        "numericDelta": { "$ref": "#/$defs/numericDelta" }
+      }
+    },
+    "match": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "path": { "type": "string" },
+        "pathFlags": { "type": "string" },
+        "pathEquals": { "type": "string" },
+        "pathPrefix": { "type": "string" }
+      }
+    },
+    "numericJump": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["minMultiple"],
+      "properties": {
+        "minMultiple": { "type": "number", "exclusiveMinimum": 0 }
+      }
+    },
+    "numericDelta": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["min"],
+      "properties": {
+        "min": { "type": "number", "minimum": 0 }
+      }
+    }
+  }
+}

package/src/alerter.js

@@ -11,16 +11,17 @@ const MAX_ENV_CHANGES_CHARS = 16_000;
 let alertQueue = Promise.resolve();
 
 function enqueue(fn) {
-  alertQueue = alertQueue
-    .then(async () => { await fn(); })
+  const result = alertQueue
+    .then(() => fn());
+  alertQueue = result
     .catch((err) => {
       renderWarn(`Alert pipeline error: ${err?.message ?? String(err)}`);
     });
-  return alertQueue;
+  return result;
 }
 
 /**
- * @param {import('./envelope.js').SentinelEnvelope} envelope
+ * @param {import('./envelope.js').FlectoEnvelope} envelope
  */
 function buildCommandEnv(envelope) {
   const json = JSON.stringify(envelope.changes);
@@ -54,7 +55,7 @@ function buildCommandEnv(envelope) {
 
 /**
  * @param {string} command
- * @param {import('./envelope.js').SentinelEnvelope} envelope
+ * @param {import('./envelope.js').FlectoEnvelope} envelope
  * @returns {Promise<boolean>}
  */
 export function runCommand(command, envelope) {
@@ -93,7 +94,7 @@ function sleep(ms) {
 }
 
 /**
- * @param {import('./envelope.js').SentinelEnvelope} envelope
+ * @param {import('./envelope.js').FlectoEnvelope} envelope
  */
 function enqueuePersistent(envelope) {
   mkdirSync(ALERT_QUEUE_DIR, { recursive: true });
@@ -102,7 +103,7 @@ function enqueuePersistent(envelope) {
 }
 
 /**
- * @param {(envelope: import('./envelope.js').SentinelEnvelope) => Promise<boolean>} deliver
+ * @param {(envelope: import('./envelope.js').FlectoEnvelope) => Promise<boolean>} deliver
  */
 async function flushPersistentQueue(deliver) {
   try {
@@ -133,7 +134,7 @@ async function flushPersistentQueue(deliver) {
 
 /**
  * @param {string} url
- * @param {import('./envelope.js').SentinelEnvelope} envelope
+ * @param {import('./envelope.js').FlectoEnvelope} envelope
  * @param {{ headers?: Record<string, string>, timeoutMs?: number, retries?: number }} [options]
  * @returns {Promise<boolean>}
  */
@@ -186,7 +187,7 @@ export async function postWebhook(url, envelope, options = {}) {
 
 /**
  * @param {{ webhook?: string, webhookHeaders?: Record<string, string>, webhookTimeoutMs?: number, webhookRetries?: number }} options
- * @param {import('./envelope.js').SentinelEnvelope} envelope
+ * @param {import('./envelope.js').FlectoEnvelope} envelope
  */
 async function deliverWebhook(options, envelope) {
   if (!options.webhook) return true;
@@ -219,7 +220,7 @@ function applyFailurePolicy(options, ok) {
  *  deliveryMode?: 'best-effort' | 'at-least-once',
  *  onAlertFailure?: 'warn' | 'exit' | 'retry'
  * }} options
- * @param {import('./envelope.js').SentinelEnvelope} envelope
+ * @param {import('./envelope.js').FlectoEnvelope} envelope
  * @returns {Promise<{ ok: boolean }>}
  */
 export async function fireAlerts(options, envelope) {

package/src/config.js

@@ -43,6 +43,17 @@ export function loadRcConfig(cwd = process.cwd()) {
   return { path: null, config: null };
 }
 
+/**
+ * Resolve profile name: CLI > FLECTO_PROFILE > none.
+ * @param {string | undefined} cliProfile
+ * @returns {string | undefined}
+ */
+export function resolveProfileName(cliProfile) {
+  if (cliProfile) return String(cliProfile);
+  if (process.env.FLECTO_PROFILE) return String(process.env.FLECTO_PROFILE);
+  return undefined;
+}
+
 /**
  * Resolve effective options with optional profile and CLI overrides.
  * @param {FlectoRc | null} config
@@ -55,6 +66,42 @@ export function resolveEffectiveOptions(config, profile, cliOverrides = {}) {
   return { ...defaults, ...profileOptions, ...cliOverrides };
 }
 
+/**
+ * Normalize policy-related effective options.
+ * @param {Record<string, unknown>} effective
+ */
+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'
+      ? String(policiesRaw).split(',').map((s) => s.trim()).filter(Boolean)
+      : ['default'];
+  const plugins = Array.isArray(pluginsRaw)
+    ? pluginsRaw.map(String)
+    : typeof pluginsRaw === 'string'
+      ? String(pluginsRaw).split(',').map((s) => s.trim()).filter(Boolean)
+      : [];
+  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 };
+}
+
 /**
  * Expand file patterns from rc include/files and direct CLI inputs.
  * @param {{ cwd?: string, files?: string[], include?: string[], exclude?: string[] }} input
@@ -93,15 +140,25 @@ export function initRcFile(cwd = process.cwd()) {
       ignore: ['**.updated_at'],
       deliveryMode: 'best-effort',
       onAlertFailure: 'warn',
+      policies: ['default'],
+      plugins: [],
+      arrayIdKey: null,
+      arrayId: true,
+      arrayIgnoreOrder: false,
+      maskSecrets: false,
     },
     profiles: {
       dev: { mode: 'verbose' },
       ci: { failOn: 'policy,error' },
+      prod: {
+        policies: ['default', 'strict-prod'],
+        severityRemap: { 'pool-size-jump': 'error' },
+        maskSecrets: true,
+      },
     },
-    files: ['config/**/*.yaml', '.env'],
+    files: ['config/**/*.{yaml,yml,json,toml,ini}', '.env', '.env.*', '*.env'],
     exclude: ['**/node_modules/**'],
   };
   writeFileSync(path, JSON.stringify(starter, null, 2), 'utf8');
   return path;
 }
-

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,8 +138,9 @@ function matchParts(patternParts, pathParts) {
  * @param {unknown} after
  * @param {string} path
  * @param {ChangeEvent[]} events  accumulator
+ * @param {{ arrayIdKey?: string | null, arrayIdentity?: boolean, arrayIgnoreOrder?: boolean }} [options]
  */
-function diffValues(before, after, path, events) {
+function diffValues(before, after, path, events, options = {}) {
   const beforeIsObj = isPlainObject(before);
   const afterIsObj = isPlainObject(after);
   const beforeIsArr = Array.isArray(before);
@@ -148,13 +148,13 @@ function diffValues(before, after, path, events) {
 
   // Both plain objects → recurse into keys
   if (beforeIsObj && afterIsObj) {
-    diffObjects(before, after, path, events);
+    diffObjects(before, after, path, events, options);
     return;
   }
 
-  // Both arrays → diff by index
+  // Both arrays → diff by index or identity key
   if (beforeIsArr && afterIsArr) {
-    diffArrays(before, after, path, events);
+    diffArrays(before, after, path, events, options);
     return;
   }
 
@@ -199,8 +199,9 @@ function diffValues(before, after, path, events) {
  * @param {Record<string, unknown>} after
  * @param {string} basePath
  * @param {ChangeEvent[]} events
+ * @param {{ arrayIdKey?: string | null, arrayIdentity?: boolean, arrayIgnoreOrder?: boolean }} [options]
  */
-function diffObjects(before, after, basePath, events) {
+function diffObjects(before, after, basePath, events, options = {}) {
   const beforeKeys = new Set(Object.keys(before));
   const afterKeys = new Set(Object.keys(after));
 
@@ -224,19 +225,150 @@ function diffObjects(before, after, basePath, events) {
   for (const key of beforeKeys) {
     if (afterKeys.has(key)) {
       const childPath = basePath ? `${basePath}.${key}` : key;
-      diffValues(before[key], after[key], childPath, events);
+      diffValues(before[key], after[key], childPath, events, options);
     }
   }
 }
 
 /**
- * Diff two arrays by index.
+ * @param {unknown} item
+ * @param {string} idKey
+ * @returns {string | null}
+ */
+function identityKey(item, idKey) {
+  if (!isPlainObject(item)) return null;
+  if (!Object.prototype.hasOwnProperty.call(item, idKey)) return null;
+  const v = item[idKey];
+  if (v == null || typeof v === 'object') return null;
+  return String(v);
+}
+
+/**
+ * @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, arrayIdentity?: boolean, arrayIgnoreOrder?: boolean }} [options]
  */
-function diffArrays(before, after, basePath, events) {
+function diffArrays(before, after, basePath, events, options = {}) {
+  const idKey = resolveArrayIdKey(before, after, options);
+
+  if (idKey) {
+    const beforeMap = identityMap(before, idKey);
+    const afterMap = identityMap(after, idKey);
+
+    if (beforeMap && afterMap) {
+      for (const [key, afterItem] of afterMap) {
+        const childPath = `${basePath}[${JSON.stringify(key)}]`;
+        if (!beforeMap.has(key)) {
+          events.push({ type: 'added', path: childPath, after: afterItem.value });
+        } else {
+          diffValues(beforeMap.get(key).value, afterItem.value, childPath, events, options);
+        }
+      }
+      for (const [key, beforeItem] of beforeMap) {
+        if (!afterMap.has(key)) {
+          const childPath = `${basePath}[${JSON.stringify(key)}]`;
+          events.push({ type: 'removed', path: childPath, before: beforeItem.value });
+        }
+      }
+      return;
+    }
+  }
+
+  if (options.arrayIgnoreOrder) {
+    // Order-insensitive without id key: multiset compare via JSON signatures
+    /** @type {Map<unknown, { count: number, value: unknown }>} */
+    const counts = new Map();
+    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 entry of counts.values()) {
+      for (let i = 0; i < entry.count; i++) {
+        events.push({ type: 'removed', path: `${basePath}[*]`, before: entry.value });
+      }
+    }
+    return;
+  }
+
   const maxLen = Math.max(before.length, after.length);
   for (let i = 0; i < maxLen; i++) {
     const childPath = `${basePath}[${i}]`;
@@ -245,7 +377,7 @@ function diffArrays(before, after, basePath, events) {
     } else if (i >= after.length) {
       events.push({ type: 'removed', path: childPath, before: before[i] });
     } else {
-      diffValues(before[i], after[i], childPath, events);
+      diffValues(before[i], after[i], childPath, events, options);
     }
   }
 }
@@ -255,22 +387,27 @@ function diffArrays(before, after, basePath, events) {
  * Accepts any JSON-like values at the root (object/array/scalar/null).
  * @param {unknown} before
  * @param {unknown} after
- * @param {{ ignorePaths?: string[] }} [options]
+ * @param {{ ignorePaths?: string[], arrayIdKey?: string | null, arrayIdentity?: boolean, arrayIgnoreOrder?: boolean }} [options]
  * @returns {ChangeEvent[]}
  */
 export function diffTrees(before, after, options = {}) {
   /** @type {ChangeEvent[]} */
   const events = [];
   const ignore = makeIgnoreMatcher(options.ignorePaths ?? []);
+  const diffOpts = {
+    arrayIdKey: options.arrayIdKey ?? null,
+    arrayIdentity: options.arrayIdentity !== false,
+    arrayIgnoreOrder: Boolean(options.arrayIgnoreOrder),
+  };
 
   // Root handling: avoid assuming object roots.
   if (isPlainObject(before) && isPlainObject(after)) {
-    diffObjects(before, after, '', events);
+    diffObjects(before, after, '', events, diffOpts);
   } else if (Array.isArray(before) && Array.isArray(after)) {
-    diffArrays(before, after, '', events);
+    diffArrays(before, after, '', events, diffOpts);
   } else {
     // Compare as a single root value. Use "<root>" so we can still ignore it if desired.
-    diffValues(before, after, '<root>', events);
+    diffValues(before, after, '<root>', events, diffOpts);
   }
 
   return events.filter(e => !ignore(e.path));

package/src/envelope.js

@@ -1,6 +1,6 @@
 import { randomUUID } from 'crypto';
 
-export const EVENT_SCHEMA_VERSION = '1.1';
+export const EVENT_SCHEMA_VERSION = '2.0';
 
 /**
  * @typedef {'watch' | 'ci' | 'diff'} EventSource
@@ -15,8 +15,9 @@ export const EVENT_SCHEMA_VERSION = '1.1';
  *  emitted_at: string,
  *  file: string,
  *  changes: import('./differ.js').ChangeEvent[],
+ *  policies?: import('./policy.js').PolicyFinding[],
  *  lifecycle?: { type: string, message: string }
- * }} SentinelEnvelope
+ * }} FlectoEnvelope
  */
 
 /**
@@ -25,10 +26,11 @@ export const EVENT_SCHEMA_VERSION = '1.1';
  *  file: string,
  *  source: EventSource,
  *  changes?: import('./differ.js').ChangeEvent[],
+ *  policies?: import('./policy.js').PolicyFinding[],
  *  lifecycle?: { type: string, message: string },
  *  batchId?: string
  * }} input
- * @returns {SentinelEnvelope}
+ * @returns {FlectoEnvelope}
  */
 export function createEnvelope(input) {
   const batchId = input.batchId ?? randomUUID();
@@ -41,7 +43,7 @@ export function createEnvelope(input) {
     emitted_at: new Date().toISOString(),
     file: input.file,
     changes: input.changes ?? [],
+    policies: input.policies ?? [],
     lifecycle: input.lifecycle,
   };
 }
-

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

@@ -0,0 +1,37 @@
+{
+  "id": "default",
+  "rules": [
+    {
+      "id": "secret-key-changed",
+      "severity": "error",
+      "when": ["added", "changed"],
+      "match": {
+        "path": "(secret|token|password|api[_-]?key|private[_-]?key)",
+        "pathFlags": "i"
+      },
+      "message": "Sensitive-looking key added or changed. Confirm secret storage, rotation, and access controls."
+    },
+    {
+      "id": "dangerous-toggle-enabled",
+      "severity": "error",
+      "when": ["changed"],
+      "match": {
+        "path": "(debug|allow_insecure|disable_tls|skip_tls_verify)",
+        "pathFlags": "i"
+      },
+      "afterTruthy": true,
+      "message": "Potentially dangerous toggle enabled."
+    },
+    {
+      "id": "pool-size-jump",
+      "severity": "warn",
+      "when": ["changed"],
+      "match": {
+        "path": "pool_size$",
+        "pathFlags": "i"
+      },
+      "numericJump": { "minMultiple": 2 },
+      "messageTemplate": "Pool size increased from {before} to {after} (>=2x)."
+    }
+  ]
+}