flecto 2.0.0 → 3.0.0

package/package.json

@@ -4,8 +4,8 @@
     "access": "public",
     "provenance": true
   },
-  "version": "2.0.0",
-  "description": "Flecto — semantic config watcher that reports meaningful changes in plain English",
+  "version": "3.0.0",
+  "description": "Flecto \u2014 semantic config watcher that reports meaningful changes in plain English",
   "license": "MIT",
   "keywords": [
     "flecto",
@@ -25,7 +25,7 @@
     "url": "git+https://github.com/myselfsiddharth/Flecto.git"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=20.19.0"
   },
   "type": "module",
   "main": "index.js",
@@ -37,20 +37,22 @@
     "src/**/*",
     "schemas/**/*",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "test": "node --test test/*.test.js",
     "test:watch": "node --test --watch test/*.test.js",
+    "bench": "node bench/run.js",
     "pack:check": "npm pack --dry-run"
   },
   "dependencies": {
     "@iarna/toml": "^2.2.5",
     "chalk": "^5.3.0",
-    "chokidar": "^3.6.0",
+    "chokidar": "^5.0.0",
     "commander": "^12.1.0",
-    "dotenv": "^16.4.5",
+    "dotenv": "^17.4.2",
     "fast-glob": "^3.3.3",
-    "js-yaml": "^4.1.0"
+    "js-yaml": "^4.3.0"
   }
 }

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

@@ -0,0 +1,129 @@
+{
+  "$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 },
+    "expandSubtrees": { "type": "boolean" },
+    "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 },
+        "beforeLooksSecret": { "const": true },
+        "afterLooksSecret": { "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 },
+        "beforeLooksSecret": { "const": true },
+        "afterLooksSecret": { "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

@@ -2,6 +2,7 @@ import { spawn } from 'child_process';
 import { mkdirSync, writeFileSync, readFileSync, readdirSync, unlinkSync } from 'fs';
 import { resolve } from 'path';
 import { renderWarn } from './renderer.js';
+import { formatWebhookPayload } from './notifiers.js';
 
 const ALERT_TMP_DIR = '.flecto-tmp';
 const ALERT_QUEUE_DIR = '.flecto-queue';
@@ -11,12 +12,13 @@ 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;
 }
 
 /**
@@ -134,11 +136,19 @@ async function flushPersistentQueue(deliver) {
 /**
  * @param {string} url
  * @param {import('./envelope.js').FlectoEnvelope} envelope
- * @param {{ headers?: Record<string, string>, timeoutMs?: number, retries?: number }} [options]
+ * @param {{
+ *  headers?: Record<string, string>,
+ *  timeoutMs?: number,
+ *  retries?: number,
+ *  format?: import('./notifiers.js').WebhookFormat
+ * }} [options]
  * @returns {Promise<boolean>}
  */
 export async function postWebhook(url, envelope, options = {}) {
-  const body = JSON.stringify(envelope);
+  // `flecto` (the default) returns the envelope untouched, so the body is
+  // byte-identical to what has always been posted. Chat formats reshape only
+  // the body: headers, retries, and delivery modes are unchanged.
+  const body = JSON.stringify(formatWebhookPayload(envelope, options.format ?? 'flecto'));
   const timeoutMs = options.timeoutMs ?? 5_000;
   const retries = options.retries ?? 2;
   const headers = {
@@ -185,7 +195,13 @@ export async function postWebhook(url, envelope, options = {}) {
 }
 
 /**
- * @param {{ webhook?: string, webhookHeaders?: Record<string, string>, webhookTimeoutMs?: number, webhookRetries?: number }} options
+ * @param {{
+ *  webhook?: string,
+ *  webhookHeaders?: Record<string, string>,
+ *  webhookTimeoutMs?: number,
+ *  webhookRetries?: number,
+ *  webhookFormat?: import('./notifiers.js').WebhookFormat
+ * }} options
  * @param {import('./envelope.js').FlectoEnvelope} envelope
  */
 async function deliverWebhook(options, envelope) {
@@ -194,6 +210,7 @@ async function deliverWebhook(options, envelope) {
     headers: options.webhookHeaders,
     timeoutMs: options.webhookTimeoutMs,
     retries: options.webhookRetries,
+    format: options.webhookFormat,
   });
 }
 
@@ -216,6 +233,7 @@ function applyFailurePolicy(options, ok) {
  *  webhookHeaders?: Record<string, string>,
  *  webhookTimeoutMs?: number,
  *  webhookRetries?: number,
+ *  webhookFormat?: import('./notifiers.js').WebhookFormat,
  *  deliveryMode?: 'best-effort' | 'at-least-once',
  *  onAlertFailure?: 'warn' | 'exit' | 'retry'
  * }} options

package/src/config.js

@@ -1,9 +1,14 @@
-import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { existsSync, readFileSync, readdirSync, writeFileSync } from 'fs';
 import { resolve } from 'path';
 import fg from 'fast-glob';
 import yaml from 'js-yaml';
+import { isEnvFilename } from './parser.js';
 
 const RC_CANDIDATES = ['.flectorc', '.flectorc.json', '.flectorc.yaml', '.flectorc.yml'];
+const COMPOSE_FILENAMES = ['docker-compose.yml', 'docker-compose.yaml', 'compose.yml', 'compose.yaml'];
+const CONFIG_DIR_PATTERN = 'config/**/*.{yaml,yml,json,toml,ini}';
+const ENV_FILE_PATTERNS = ['.env', '.env.*', '*.env'];
+const GENERIC_FILE_PATTERNS = [CONFIG_DIR_PATTERN, ...ENV_FILE_PATTERNS];
 
 /**
  * @typedef {{
@@ -13,6 +18,15 @@ const RC_CANDIDATES = ['.flectorc', '.flectorc.json', '.flectorc.yaml', '.flecto
  *  include?: string[],
  *  exclude?: string[]
  * }} FlectoRc
+ *
+ * @typedef {{
+ *  id: string,
+ *  evidence: string[],
+ *  pack: string | null,
+ *  summary: string
+ * }} StackSignal
+ *
+ * @typedef {{ signals: StackSignal[], packs: string[], files: string[] }} StackDetection
  */
 
 /**
@@ -73,6 +87,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 +98,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 };
 }
 
 /**
@@ -110,13 +140,104 @@ export async function resolveFiles(input) {
 }
 
 /**
- * Scaffold a starter rc file if missing.
+ * Detect stack signals in a directory and map them to policy packs and file
+ * patterns. Only built-in pack ids and patterns Flecto can actually parse are
+ * ever returned, so a config built from this stays loadable by every command.
+ * Terraform files are reported as context only: `.tf` is not a supported parse
+ * format, and the `terraform` pack reads plan JSON rather than `.tf` sources,
+ * so neither belongs in a config built from a directory listing.
  * @param {string} cwd
- * @returns {string}
+ * @returns {StackDetection}
+ */
+export function detectStack(cwd = process.cwd()) {
+  /** @type {StackSignal[]} */
+  const signals = [];
+  const packs = ['default'];
+  /** @type {string[]} */
+  const files = [];
+
+  let entries = [];
+  try {
+    entries = readdirSync(cwd, { withFileTypes: true });
+  } catch {
+    return { signals, packs, files };
+  }
+  const fileNames = entries.filter((entry) => entry.isFile()).map((entry) => entry.name);
+  const dirNames = new Set(entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name));
+  const fileNameSet = new Set(fileNames);
+
+  const composeFiles = COMPOSE_FILENAMES.filter((name) => fileNameSet.has(name));
+  if (composeFiles.length > 0) {
+    packs.push('compose');
+    files.push(...composeFiles);
+    signals.push({
+      id: 'compose',
+      evidence: composeFiles,
+      pack: 'compose',
+      summary: `Detected ${composeFiles.join(', ')} → enabled the \`compose\` policy pack and watched ${composeFiles.length === 1 ? 'it' : 'them'}`,
+    });
+  }
+
+  if (fileNameSet.has('package.json')) {
+    packs.push('node-runtime');
+    files.push('package.json');
+    signals.push({
+      id: 'node',
+      evidence: ['package.json'],
+      pack: 'node-runtime',
+      summary: 'Detected package.json → enabled the `node-runtime` policy pack and watched it',
+    });
+  }
+
+  const terraformFiles = fileNames.filter((name) => name.toLowerCase().endsWith('.tf')).sort();
+  if (terraformFiles.length > 0) {
+    signals.push({
+      id: 'terraform',
+      evidence: terraformFiles,
+      pack: null,
+      summary: `Detected Terraform files (${terraformFiles.join(', ')}) → .tf is not a parseable format, so nothing was enabled; run "flecto plan" on "terraform show -json" output to use the terraform pack`,
+    });
+  }
+
+  if (dirNames.has('config')) {
+    files.push(CONFIG_DIR_PATTERN);
+    signals.push({
+      id: 'config-dir',
+      evidence: ['config/'],
+      pack: null,
+      summary: `Detected config/ → watched ${CONFIG_DIR_PATTERN}`,
+    });
+  }
+
+  const envFiles = fileNames.filter((name) => isEnvFilename(name)).sort();
+  if (envFiles.length > 0) {
+    files.push(...ENV_FILE_PATTERNS);
+    signals.push({
+      id: 'dotenv',
+      evidence: envFiles,
+      pack: null,
+      summary: `Detected ${envFiles.join(', ')} → watched ${ENV_FILE_PATTERNS.join(', ')}`,
+    });
+  }
+
+  return { signals, packs, files: [...new Set(files)] };
+}
+
+/**
+ * Scaffold a starter rc file if missing, pre-selecting policy packs and file
+ * patterns from the stack signals found in `cwd`. Never overwrites an existing
+ * config: any of the four `.flectorc` candidates is reported back untouched.
+ * @param {string} cwd
+ * @returns {{ path: string, created: boolean, detection: StackDetection }}
  */
 export function initRcFile(cwd = process.cwd()) {
+  const detection = detectStack(cwd);
+  const existingPath = RC_CANDIDATES
+    .map((candidate) => resolve(cwd, candidate))
+    .find((candidate) => existsSync(candidate));
+  if (existingPath) return { path: existingPath, created: false, detection };
+
   const path = resolve(cwd, '.flectorc.json');
-  if (existsSync(path)) return path;
   const starter = {
     defaults: {
       mode: 'compact',
@@ -124,20 +245,25 @@ export function initRcFile(cwd = process.cwd()) {
       ignore: ['**.updated_at'],
       deliveryMode: 'best-effort',
       onAlertFailure: 'warn',
-      policies: ['default'],
+      policies: detection.packs,
       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: [...detection.packs, 'strict-prod'],
+        severityRemap: { 'pool-size-jump': 'error' },
+        maskSecrets: true,
+      },
     },
-    files: ['config/**/*.{yaml,yml,json,toml,ini}', '.env', '.env.*', '*.env'],
+    files: detection.files.length > 0 ? detection.files : [...GENERIC_FILE_PATTERNS],
     exclude: ['**/node_modules/**'],
   };
   writeFileSync(path, JSON.stringify(starter, null, 2), 'utf8');
-  return path;
+  return { path, created: true, detection };
 }