flecto 1.0.0

package/src/config.js

@@ -0,0 +1,107 @@
+import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { resolve } from 'path';
+import fg from 'fast-glob';
+import yaml from 'js-yaml';
+
+const RC_CANDIDATES = ['.flectorc', '.flectorc.json', '.flectorc.yaml', '.flectorc.yml'];
+
+/**
+ * @typedef {{
+ *  defaults?: Record<string, unknown>,
+ *  profiles?: Record<string, Record<string, unknown>>,
+ *  files?: string[],
+ *  include?: string[],
+ *  exclude?: string[]
+ * }} FlectoRc
+ */
+
+/**
+ * @param {string} cwd
+ * @returns {{ path: string | null, config: FlectoRc | null }}
+ */
+export function loadRcConfig(cwd = process.cwd()) {
+  for (const candidate of RC_CANDIDATES) {
+    const fullPath = resolve(cwd, candidate);
+    if (!existsSync(fullPath)) continue;
+    const raw = readFileSync(fullPath, 'utf8');
+    let parsed;
+    try {
+      if (candidate.endsWith('.yaml') || candidate.endsWith('.yml')) {
+        parsed = yaml.load(raw);
+      } else {
+        try {
+          parsed = JSON.parse(raw);
+        } catch {
+          parsed = yaml.load(raw);
+        }
+      }
+    } catch (err) {
+      throw new Error(`Failed to parse ${candidate}: ${err.message}`);
+    }
+    return { path: fullPath, config: parsed ?? {} };
+  }
+  return { path: null, config: null };
+}
+
+/**
+ * Resolve effective options with optional profile and CLI overrides.
+ * @param {FlectoRc | null} config
+ * @param {string | undefined} profile
+ * @param {Record<string, unknown>} cliOverrides
+ */
+export function resolveEffectiveOptions(config, profile, cliOverrides = {}) {
+  const defaults = config?.defaults ?? {};
+  const profileOptions = profile && config?.profiles?.[profile] ? config.profiles[profile] : {};
+  return { ...defaults, ...profileOptions, ...cliOverrides };
+}
+
+/**
+ * Expand file patterns from rc include/files and direct CLI inputs.
+ * @param {{ cwd?: string, files?: string[], include?: string[], exclude?: string[] }} input
+ * @returns {Promise<string[]>}
+ */
+export async function resolveFiles(input) {
+  const cwd = input.cwd ?? process.cwd();
+  const files = input.files ?? [];
+  const include = input.include ?? [];
+  const exclude = input.exclude ?? [];
+  const patterns = [...files, ...include].filter(Boolean);
+  if (patterns.length === 0) return [];
+  const matches = await fg(patterns, {
+    cwd,
+    absolute: true,
+    onlyFiles: true,
+    unique: true,
+    ignore: exclude,
+    dot: true,
+  });
+  return matches.map((p) => resolve(p));
+}
+
+/**
+ * Scaffold a starter rc file if missing.
+ * @param {string} cwd
+ * @returns {string}
+ */
+export function initRcFile(cwd = process.cwd()) {
+  const path = resolve(cwd, '.flectorc.json');
+  if (existsSync(path)) return path;
+  const starter = {
+    defaults: {
+      mode: 'compact',
+      interval: 100,
+      ignore: ['**.updated_at'],
+      deliveryMode: 'best-effort',
+      onAlertFailure: 'warn',
+    },
+    profiles: {
+      dev: { mode: 'verbose' },
+      ci: { failOn: 'policy,error' },
+    },
+    files: ['config/**/*.yaml', '.env'],
+    exclude: ['**/node_modules/**'],
+  };
+  writeFileSync(path, JSON.stringify(starter, null, 2), 'utf8');
+  return path;
+}
+

package/src/differ.js

@@ -0,0 +1,277 @@
+/**
+ * @typedef {{ type: 'added' | 'removed' | 'changed', path: string, before?: unknown, after?: unknown, note?: string }} ChangeEvent
+ */
+
+/**
+ * Checks whether a value is a plain object (not array, not null).
+ * @param {unknown} v
+ * @returns {v is Record<string, unknown>}
+ */
+function isPlainObject(v) {
+  return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+
+/**
+ * Default ignore matcher:
+ * - exact path match: "meta.timestamp"
+ * - subtree/prefix match: "meta" ignores "meta.*" and "meta[0].*"
+ * - wildcard segment match: "meta.*.timestamp"
+ * - ignore by key name anywhere: "**.updated_at" or "**.timestamp"
+ *
+ * Array indices in paths use "[N]" segments, e.g. "servers[1].port".
+ * @param {string[]} patterns
+ * @returns {(path: string) => boolean}
+ */
+function makeIgnoreMatcher(patterns) {
+  if (!patterns || patterns.length === 0) return () => false;
+
+  const exact = new Set();
+  /** @type {{ parts: string[] }[]} */
+  const globs = [];
+  /** @type {Set<string>} */
+  const keyAnywhere = new Set();
+
+  for (const raw of patterns) {
+    const p = String(raw ?? '').trim();
+    if (!p) continue;
+
+    if (p.startsWith('**.')) {
+      const key = p.slice(3).trim();
+      if (key) keyAnywhere.add(key);
+      continue;
+    }
+
+    if (p.includes('*')) {
+      globs.push({ parts: splitPathParts(p) });
+      continue;
+    }
+
+    exact.add(p);
+  }
+
+  return (path) => {
+    if (exact.has(path)) return true;
+
+    // Prefix/subtree ignore: "meta" ignores "meta.x" and "meta[0].x"
+    for (const p of exact) {
+      if (!p) continue;
+      if (path.startsWith(p) && (path.length === p.length || path[p.length] === '.' || path[p.length] === '[')) {
+        return true;
+      }
+    }
+
+    if (keyAnywhere.size > 0) {
+      for (const key of keyAnywhere) {
+        if (path === key) return true;
+        if (path.includes(`.${key}`)) return true;
+        if (path.includes(`].${key}`)) return true;
+      }
+    }
+
+    if (globs.length > 0) {
+      const parts = splitPathParts(path);
+      for (const g of globs) {
+        if (matchParts(g.parts, parts)) return true;
+      }
+    }
+
+    return false;
+  };
+}
+
+/**
+ * Split a path into comparable parts. Turns "a.b[1].c" into ["a","b","[1]","c"].
+ * @param {string} path
+ * @returns {string[]}
+ */
+function splitPathParts(path) {
+  if (!path) return [];
+  /** @type {string[]} */
+  const parts = [];
+  let buf = '';
+  for (let i = 0; i < path.length; i++) {
+    const ch = path[i];
+    if (ch === '.') {
+      if (buf) parts.push(buf);
+      buf = '';
+      continue;
+    }
+    if (ch === '[') {
+      if (buf) parts.push(buf);
+      buf = '';
+      const end = path.indexOf(']', i);
+      if (end === -1) {
+        // malformed; treat as literal remainder
+        buf = path.slice(i);
+        break;
+      }
+      const bracketToken = path.slice(i, end + 1); // include brackets
+      // Allow wildcard index syntax: [*]
+      parts.push(bracketToken === '[*]' ? '*' : bracketToken);
+      i = end;
+      continue;
+    }
+    buf += ch;
+  }
+  if (buf) parts.push(buf);
+  return parts;
+}
+
+/**
+ * Match glob parts against actual parts. "*" matches any single part (key or index).
+ * @param {string[]} patternParts
+ * @param {string[]} pathParts
+ * @returns {boolean}
+ */
+function matchParts(patternParts, pathParts) {
+  if (patternParts.length !== pathParts.length) return false;
+  for (let i = 0; i < patternParts.length; i++) {
+    const p = patternParts[i];
+    if (p === '*') continue;
+    if (p !== pathParts[i]) return false;
+  }
+  return true;
+}
+
+/**
+ * Recursively diff two values at a given key path.
+ * @param {unknown} before
+ * @param {unknown} after
+ * @param {string} path
+ * @param {ChangeEvent[]} events  accumulator
+ */
+function diffValues(before, after, path, events) {
+  const beforeIsObj = isPlainObject(before);
+  const afterIsObj = isPlainObject(after);
+  const beforeIsArr = Array.isArray(before);
+  const afterIsArr = Array.isArray(after);
+
+  // Both plain objects → recurse into keys
+  if (beforeIsObj && afterIsObj) {
+    diffObjects(before, after, path, events);
+    return;
+  }
+
+  // Both arrays → diff by index
+  if (beforeIsArr && afterIsArr) {
+    diffArrays(before, after, path, events);
+    return;
+  }
+
+  // Both nullish/undefined
+  if ((before == null) && (after == null)) {
+    return;
+  }
+
+  // Structural type change (e.g. object → scalar, array → object)
+  if (
+    (beforeIsObj || beforeIsArr) !== (afterIsObj || afterIsArr) ||
+    (beforeIsObj !== afterIsObj) ||
+    (beforeIsArr !== afterIsArr)
+  ) {
+    const beforeType = beforeIsObj ? 'object' : beforeIsArr ? 'array' : typeof before;
+    const afterType = afterIsObj ? 'object' : afterIsArr ? 'array' : typeof after;
+    events.push({
+      type: 'changed',
+      path,
+      before,
+      after,
+      note: `type changed from ${beforeType} to ${afterType}`,
+    });
+    return;
+  }
+
+  // Scalar comparison — note type changes
+  if (before !== after) {
+    const beforeType = typeof before;
+    const afterType = typeof after;
+    const event = { type: 'changed', path, before, after };
+    if (beforeType !== afterType) {
+      event.note = `type changed from ${beforeType} to ${afterType}`;
+    }
+    events.push(event);
+  }
+}
+
+/**
+ * Diff two plain objects. Key ordering is intentionally ignored.
+ * @param {Record<string, unknown>} before
+ * @param {Record<string, unknown>} after
+ * @param {string} basePath
+ * @param {ChangeEvent[]} events
+ */
+function diffObjects(before, after, basePath, events) {
+  const beforeKeys = new Set(Object.keys(before));
+  const afterKeys = new Set(Object.keys(after));
+
+  // Keys only in "after" → added
+  for (const key of afterKeys) {
+    if (!beforeKeys.has(key)) {
+      const childPath = basePath ? `${basePath}.${key}` : key;
+      events.push({ type: 'added', path: childPath, after: after[key] });
+    }
+  }
+
+  // Keys only in "before" → removed
+  for (const key of beforeKeys) {
+    if (!afterKeys.has(key)) {
+      const childPath = basePath ? `${basePath}.${key}` : key;
+      events.push({ type: 'removed', path: childPath, before: before[key] });
+    }
+  }
+
+  // Keys in both → recurse
+  for (const key of beforeKeys) {
+    if (afterKeys.has(key)) {
+      const childPath = basePath ? `${basePath}.${key}` : key;
+      diffValues(before[key], after[key], childPath, events);
+    }
+  }
+}
+
+/**
+ * Diff two arrays by index.
+ * @param {unknown[]} before
+ * @param {unknown[]} after
+ * @param {string} basePath
+ * @param {ChangeEvent[]} events
+ */
+function diffArrays(before, after, basePath, events) {
+  const maxLen = Math.max(before.length, after.length);
+  for (let i = 0; i < maxLen; i++) {
+    const childPath = `${basePath}[${i}]`;
+    if (i >= before.length) {
+      events.push({ type: 'added', path: childPath, after: after[i] });
+    } else if (i >= after.length) {
+      events.push({ type: 'removed', path: childPath, before: before[i] });
+    } else {
+      diffValues(before[i], after[i], childPath, events);
+    }
+  }
+}
+
+/**
+ * Compute the semantic difference between two parsed config trees.
+ * Accepts any JSON-like values at the root (object/array/scalar/null).
+ * @param {unknown} before
+ * @param {unknown} after
+ * @param {{ ignorePaths?: string[] }} [options]
+ * @returns {ChangeEvent[]}
+ */
+export function diffTrees(before, after, options = {}) {
+  /** @type {ChangeEvent[]} */
+  const events = [];
+  const ignore = makeIgnoreMatcher(options.ignorePaths ?? []);
+
+  // Root handling: avoid assuming object roots.
+  if (isPlainObject(before) && isPlainObject(after)) {
+    diffObjects(before, after, '', events);
+  } else if (Array.isArray(before) && Array.isArray(after)) {
+    diffArrays(before, after, '', events);
+  } else {
+    // Compare as a single root value. Use "<root>" so we can still ignore it if desired.
+    diffValues(before, after, '<root>', events);
+  }
+
+  return events.filter(e => !ignore(e.path));
+}

package/src/envelope.js

@@ -0,0 +1,47 @@
+import { randomUUID } from 'crypto';
+
+export const EVENT_SCHEMA_VERSION = '1.1';
+
+/**
+ * @typedef {'watch' | 'ci' | 'diff'} EventSource
+ * @typedef {'changes' | 'lifecycle'} EnvelopeEventType
+ *
+ * @typedef {{
+ *  schema_version: string,
+ *  event_id: string,
+ *  batch_id: string,
+ *  event_type: EnvelopeEventType,
+ *  source: EventSource,
+ *  emitted_at: string,
+ *  file: string,
+ *  changes: import('./differ.js').ChangeEvent[],
+ *  lifecycle?: { type: string, message: string }
+ * }} SentinelEnvelope
+ */
+
+/**
+ * Create a stable event envelope for automation sinks.
+ * @param {{
+ *  file: string,
+ *  source: EventSource,
+ *  changes?: import('./differ.js').ChangeEvent[],
+ *  lifecycle?: { type: string, message: string },
+ *  batchId?: string
+ * }} input
+ * @returns {SentinelEnvelope}
+ */
+export function createEnvelope(input) {
+  const batchId = input.batchId ?? randomUUID();
+  return {
+    schema_version: EVENT_SCHEMA_VERSION,
+    event_id: randomUUID(),
+    batch_id: batchId,
+    event_type: input.lifecycle ? 'lifecycle' : 'changes',
+    source: input.source,
+    emitted_at: new Date().toISOString(),
+    file: input.file,
+    changes: input.changes ?? [],
+    lifecycle: input.lifecycle,
+  };
+}
+

package/src/parser.js

@@ -0,0 +1,77 @@
+import { readFileSync } from 'fs';
+import { extname } from 'path';
+import yaml from 'js-yaml';
+import TOML from '@iarna/toml';
+import dotenv from 'dotenv';
+
+const SUPPORTED = ['.json', '.yaml', '.yml', '.toml', '.env'];
+
+/**
+ * Auto-detect the format of a file and parse it into a plain JS object.
+ * @param {string} filepath
+ * @param {string} raw
+ * @returns {unknown}
+ * @throws {Error} on unsupported format or parse failure
+ */
+export function parseContent(filepath, raw) {
+  const ext = extname(filepath).toLowerCase();
+
+  if (!SUPPORTED.includes(ext)) {
+    const supported = SUPPORTED.join(', ');
+    throw new Error(
+      `Unsupported file format "${ext}" for "${filepath}".\n` +
+      `Supported extensions: ${supported}`
+    );
+  }
+  try {
+    if (ext === '.json') {
+      return JSON.parse(raw);
+    }
+
+    if (ext === '.yaml' || ext === '.yml') {
+      const result = yaml.load(raw);
+      // yaml.load can return null for empty files
+      return result == null ? {} : result;
+    }
+
+    if (ext === '.toml') {
+      return TOML.parse(raw);
+    }
+
+    if (ext === '.env') {
+      const parsed = dotenv.parse(raw);
+      return parsed;
+    }
+  } catch (err) {
+    // Try to extract line info from error messages
+    const lineMatch = err.message?.match(/line (\d+)/i);
+    const lineInfo = lineMatch ? ` (line ${lineMatch[1]})` : '';
+    throw new Error(
+      `Parse error in "${filepath}"${lineInfo}: ${err.message}`
+    );
+  }
+}
+
+/**
+ * Auto-detect the format of a file and parse it into a plain JS value.
+ * @param {string} filepath
+ * @returns {unknown}
+ */
+export function parseFile(filepath) {
+  let raw;
+  try {
+    raw = readFileSync(filepath, 'utf8');
+  } catch (err) {
+    throw new Error(`Cannot read file "${filepath}": ${err.message}`);
+  }
+  return parseContent(filepath, raw);
+}
+
+/**
+ * Returns true if the file extension is supported.
+ * @param {string} filepath
+ * @returns {boolean}
+ */
+export function isSupported(filepath) {
+  return SUPPORTED.includes(extname(filepath).toLowerCase());
+}

package/src/policy.js

@@ -0,0 +1,65 @@
+/**
+ * @typedef {'info' | 'warn' | 'error'} PolicySeverity
+ * @typedef {{ id: string, severity: PolicySeverity, path: string, message: string }} PolicyFinding
+ */
+
+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;
+
+/**
+ * Evaluate built-in policy checks against semantic changes.
+ * @param {import('./differ.js').ChangeEvent[]} changes
+ * @returns {PolicyFinding[]}
+ */
+export function evaluatePolicies(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') {
+      findings.push({
+        id: 'secret-key-changed',
+        severity: 'error',
+        path,
+        message: 'Sensitive-looking key changed. Confirm secret rotation and access controls.',
+      });
+    }
+
+    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.',
+      });
+    }
+
+    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).`,
+        });
+      }
+    }
+  }
+
+  return findings;
+}
+
+/**
+ * @param {PolicyFinding[]} findings
+ * @returns {PolicySeverity | null}
+ */
+export function highestSeverity(findings) {
+  if (!findings || findings.length === 0) return null;
+  if (findings.some((f) => f.severity === 'error')) return 'error';
+  if (findings.some((f) => f.severity === 'warn')) return 'warn';
+  return 'info';
+}
+

package/src/renderer.js

@@ -0,0 +1,134 @@
+import chalk from 'chalk';
+
+/**
+ * Format a scalar value for display. Strings get quoted; others are JSON-stringified.
+ * @param {unknown} v
+ * @returns {string}
+ */
+function fmt(v) {
+  if (v === undefined) return '';
+  if (typeof v === 'string') return JSON.stringify(v);
+  if (typeof v === 'object' && v !== null) return JSON.stringify(v);
+  return String(v);
+}
+
+/**
+ * Return a HH:MM:SS timestamp string.
+ * @returns {string}
+ */
+function timestamp() {
+  return new Date().toTimeString().slice(0, 8);
+}
+
+/**
+ * Render a single change event as a colored string.
+ * @param {import('./differ.js').ChangeEvent} event
+ * @param {'compact' | 'verbose'} mode
+ * @returns {string}
+ */
+function renderEvent(event, mode) {
+  const { type, path, before, after, note } = event;
+
+  if (type === 'added') {
+    const line = `  ${chalk.green('+')} ${chalk.green(path)}: ${chalk.green(fmt(after))}`;
+    return mode === 'verbose'
+      ? `${line}\n    ${chalk.dim('(key added)')}`
+      : line;
+  }
+
+  if (type === 'removed') {
+    const line = `  ${chalk.red('-')} ${chalk.red(path)}: ${chalk.red(fmt(before))}`;
+    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))}`,
+    ].join('\n');
+  }
+  return `  ${chalk.yellow('~')} ${chalk.yellow(path)}: ${chalk.red(fmt(before))} ${chalk.dim('→')} ${chalk.green(fmt(after))}${noteStr}`;
+}
+
+/**
+ * Render a batch of change events to stdout.
+ * @param {string} filepath
+ * @param {import('./differ.js').ChangeEvent[]} events
+ * @param {'compact' | 'verbose'} mode
+ */
+export function renderChanges(filepath, events, mode = 'compact') {
+  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));
+  }
+
+  if (mode === 'verbose') {
+    console.log('');
+  }
+}
+
+/**
+ * Print a diff result (for --diff mode) to stdout.
+ * @param {string} filepath
+ * @param {import('./differ.js').ChangeEvent[]} events
+ */
+export function renderDiff(filepath, events) {
+  if (events.length === 0) {
+    console.log(chalk.green(`✓ ${filepath} matches snapshot — no changes`));
+    return;
+  }
+
+  console.log(chalk.cyan(`${filepath}`) + ` — ${events.length} change${events.length !== 1 ? 's' : ''} from snapshot:`);
+  for (const event of events) {
+    console.log(renderEvent(event, 'compact'));
+  }
+}
+
+/**
+ * Print an error message in red.
+ * @param {string} msg
+ */
+export function renderError(msg) {
+  console.error(chalk.red(`[error] ${msg}`));
+}
+
+/**
+ * Print a warning in yellow.
+ * @param {string} msg
+ */
+export function renderWarn(msg) {
+  console.warn(chalk.yellow(`[warn] ${msg}`));
+}
+
+/**
+ * Print an info message in dim text.
+ * @param {string} msg
+ */
+export function renderInfo(msg) {
+  console.log(chalk.dim(msg));
+}
+
+/**
+ * Print policy findings.
+ * @param {import('./policy.js').PolicyFinding[]} findings
+ */
+export function renderPolicyFindings(findings) {
+  if (!findings || findings.length === 0) return;
+  for (const f of findings) {
+    const prefix = f.severity === 'error'
+      ? chalk.red('! policy(error)')
+      : f.severity === 'warn'
+        ? chalk.yellow('! policy(warn)')
+        : chalk.blue('! policy(info)');
+    console.log(`  ${prefix} ${chalk.cyan(f.path)}: ${f.message}`);
+  }
+}