flecto 1.0.2 → 2.1.0

package/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 import { program } from 'commander';
-import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
+import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, statSync } from 'fs';
 import { resolve, relative, dirname, join } from 'path';
 import { fileURLToPath } from 'url';
 import { createHash } from 'crypto';
@@ -11,11 +11,27 @@ import chalk from 'chalk';
 import { parseFile, isSupported, parseContent } from './src/parser.js';
 import { diffTrees } from './src/differ.js';
 import { startWatcher } from './src/watcher.js';
-import { renderChanges, renderDiff, renderError, renderInfo, renderWarn, renderPolicyFindings } from './src/renderer.js';
+import {
+  renderChanges,
+  renderDiff,
+  renderError,
+  renderInfo,
+  renderWarn,
+  renderPolicyFindings,
+  maskChangeEvent,
+} from './src/renderer.js';
 import { fireAlerts } from './src/alerter.js';
 import { createEnvelope } from './src/envelope.js';
-import { evaluatePolicies, highestSeverity } from './src/policy.js';
-import { loadRcConfig, resolveEffectiveOptions, resolveFiles, initRcFile } from './src/config.js';
+import { evaluatePolicies, highestSeverity, listPolicyPacks } from './src/policy.js';
+import { testPolicyFixture } from './src/policy-test.js';
+import {
+  loadRcConfig,
+  resolveEffectiveOptions,
+  resolveFiles,
+  initRcFile,
+  resolveProfileName,
+  resolvePolicyOptions,
+} from './src/config.js';
 
 const PKG = JSON.parse(
   readFileSync(join(dirname(fileURLToPath(import.meta.url)), 'package.json'), 'utf8'),
@@ -24,7 +40,6 @@ const PKG = JSON.parse(
 const SNAPSHOT_DIR = '.flecto-snapshots';
 
 function snapshotIdForPath(absPath) {
-  // Stable across platforms and avoids basename collisions
   const normalized = absPath.replaceAll('\\', '/');
   return createHash('sha256').update(normalized).digest('hex').slice(0, 16);
 }
@@ -34,6 +49,90 @@ function snapshotPathForFile(absPath) {
   return resolve(`${SNAPSHOT_DIR}/${id}.json`);
 }
 
+function snapshotHistoryPathForFile(absPath) {
+  const id = snapshotIdForPath(absPath);
+  let timestamp = Date.now();
+  let path = resolve(`${SNAPSHOT_DIR}/${id}.${timestamp}.json`);
+  while (existsSync(path)) {
+    timestamp += 1;
+    path = resolve(`${SNAPSHOT_DIR}/${id}.${timestamp}.json`);
+  }
+  return path;
+}
+
+function hasSnapshotHistoryForFile(absPath) {
+  if (!existsSync(SNAPSHOT_DIR)) return false;
+  const id = snapshotIdForPath(absPath);
+  return readdirSync(SNAPSHOT_DIR).some((name) => new RegExp(`^${id}\\.\\d+\\.json$`).test(name));
+}
+
+function preserveLegacySnapshotForHistory(absPath, snapshotPath) {
+  if (!existsSync(snapshotPath) || hasSnapshotHistoryForFile(absPath)) return;
+
+  const legacy = JSON.parse(readFileSync(snapshotPath, 'utf8'));
+  writeFileSync(
+    snapshotHistoryPathForFile(absPath),
+    JSON.stringify({
+      file: legacy.file ?? absPath,
+      state: legacy.state ?? legacy,
+      createdAt: legacy.createdAt ?? statSync(snapshotPath).mtime.toISOString(),
+    }, null, 2),
+    'utf8',
+  );
+}
+
+function readLocalSnapshotHistory() {
+  if (!existsSync(SNAPSHOT_DIR)) return [];
+
+  const entries = readdirSync(SNAPSHOT_DIR, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && entry.name.endsWith('.json'));
+  const historyEntries = entries.filter((entry) => /^[a-f0-9]{16}\.\d+\.json$/.test(entry.name));
+  const historyIds = new Set(historyEntries.map((entry) => entry.name.slice(0, 16)));
+  const legacyEntries = entries.filter((entry) =>
+    /^[a-f0-9]{16}\.json$/.test(entry.name) && !historyIds.has(entry.name.slice(0, 16)));
+  const snapshotEntries = [...historyEntries, ...legacyEntries];
+
+  return snapshotEntries.map((entry) => {
+    const path = resolve(SNAPSHOT_DIR, entry.name);
+    const snapshot = JSON.parse(readFileSync(path, 'utf8'));
+    const state = snapshot?.state ?? snapshot;
+    if (typeof snapshot?.file !== 'string') {
+      throw new Error(`Invalid snapshot file: ${path}`);
+    }
+    return {
+      file: snapshot.file,
+      state,
+      createdAt: snapshot.createdAt ?? statSync(path).mtime.toISOString(),
+    };
+  });
+}
+
+function summarizeSnapshotHistory(snapshots, limit, diffOpts = {}) {
+  const byFile = new Map();
+  for (const snapshot of snapshots) {
+    const records = byFile.get(snapshot.file) ?? [];
+    records.push(snapshot);
+    byFile.set(snapshot.file, records);
+  }
+
+  const summaries = [];
+  for (const records of byFile.values()) {
+    records.sort((a, b) => new Date(a.createdAt) - new Date(b.createdAt));
+    for (let index = 0; index < records.length; index += 1) {
+      summaries.push({
+        ...records[index],
+        changeCount: index === 0
+          ? 0
+          : diffTrees(records[index - 1].state, records[index].state, diffOpts).length,
+      });
+    }
+  }
+
+  return summaries
+    .sort((a, b) => new Date(b.createdAt) - new Date(a.createdAt))
+    .slice(0, limit);
+}
+
 function parseCsv(value) {
   if (!value) return [];
   if (Array.isArray(value)) return value;
@@ -66,6 +165,29 @@ function validateInterval(interval) {
   }
 }
 
+function stripUnsetCliOverrides(opts, command) {
+  return Object.fromEntries(
+    Object.entries(opts).filter(([key]) => command.getOptionValueSource(key) === 'cli'),
+  );
+}
+
+function diffOptionsFromEffective(effective, ignorePaths) {
+  const arrayIdKey = effective.arrayIdKey || null;
+  return {
+    ignorePaths,
+    arrayIdKey,
+    // Explicit --array-id-key / arrayIdKey enables identity matching even when
+    // .flectorc sets arrayId:false (index escape hatch for auto-detect only).
+    arrayIdentity: arrayIdKey ? true : effective.arrayId !== false,
+    arrayIgnoreOrder: Boolean(effective.arrayIgnoreOrder),
+  };
+}
+
+function maybeMaskChanges(events, maskSecrets) {
+  if (!maskSecrets) return events;
+  return events.map(maskChangeEvent);
+}
+
 async function resolveTargetFiles(cliFiles, rcConfig) {
   if (cliFiles && cliFiles.length > 0) {
     const direct = [];
@@ -107,7 +229,6 @@ function readSnapshotStateFromRef(filePath, snapshotRef) {
     return readSnapshotStateFromFile(maybePath);
   }
 
-  // git ref mode: flecto ci file --snapshot-ref HEAD~1
   const rel = relative(process.cwd(), filePath).replaceAll('\\', '/');
   const raw = execFileSync('git', ['show', `${snapshotRef}:${rel}`], { encoding: 'utf8' });
   return parseContent(filePath, raw);
@@ -128,6 +249,19 @@ function shouldFailFromChanges(events, failOn) {
   return false;
 }
 
+function escapeWorkflowCommandData(value) {
+  return String(value)
+    .replaceAll('%', '%25')
+    .replaceAll('\r', '%0D')
+    .replaceAll('\n', '%0A');
+}
+
+function escapeWorkflowCommandProperty(value) {
+  return escapeWorkflowCommandData(value)
+    .replaceAll(':', '%3A')
+    .replaceAll(',', '%2C');
+}
+
 function printCiOutput(results, format) {
   if (format === 'json') {
     console.log(JSON.stringify(results, null, 2));
@@ -143,11 +277,15 @@ function printCiOutput(results, format) {
     for (const result of results) {
       for (const event of result.envelope.changes) {
         const title = `flecto ${event.type}`;
-        console.log(`::warning file=${result.file},title=${title}::${event.path}`);
+        const detail = event.note ? `${event.path} (${event.note})` : event.path;
+        console.log(`::warning file=${escapeWorkflowCommandProperty(result.file)},title=${escapeWorkflowCommandProperty(title)}::${escapeWorkflowCommandData(detail)}`);
       }
       for (const finding of result.policies) {
         const level = finding.severity === 'error' ? 'error' : 'warning';
-        console.log(`::${level} file=${result.file},title=policy::${finding.path} ${finding.message}`);
+        const pack = finding.pack ? ` [${finding.pack}]` : '';
+        const title = `flecto policy ${finding.id}${pack}`;
+        const detail = `${finding.path}: ${finding.message}`;
+        console.log(`::${level} file=${escapeWorkflowCommandProperty(result.file)},title=${escapeWorkflowCommandProperty(title)}::${escapeWorkflowCommandData(detail)}`);
       }
     }
   }
@@ -161,7 +299,7 @@ program
 program
   .command('watch [files...]')
   .description('Watch config files/globs for semantic changes')
-  .option('-p, --profile <name>', 'Use profile from .flectorc')
+  .option('-p, --profile <name>', 'Use profile from .flectorc (else FLECTO_PROFILE)')
   .option('-i, --interval <ms>', 'Polling fallback interval in ms', '100')
   .option('--polling', 'Force polling mode (useful on network drives / some editors)', false)
   .option('-m, --mode <mode>', 'Output mode: compact | verbose', 'compact')
@@ -176,12 +314,22 @@ program
   .option('--webhook-timeout <ms>', 'Webhook timeout in ms', '5000')
   .option('--webhook-retries <n>', 'Webhook retries', '2')
   .option('--ignore <keys>', 'Comma-separated key paths to ignore (e.g. "updated_at,meta.ts")')
+  .option('--policies <ids>', 'Comma-separated policy pack ids (default: default)')
+  .option('--plugins <paths>', 'Comma-separated local ESM plugin paths')
+  .option('--array-id-key <key>', 'Diff arrays by this object identity key')
+  .option('--no-array-id', 'Diff arrays by index instead of object identity')
+  .option('--array-ignore-order', 'Treat array order as insignificant', false)
+  .option('--mask-secrets', 'Mask secret-like values in human output', false)
+  .option('--mask-secrets-webhooks', 'Also mask secrets in webhook payloads', false)
   .option('--snapshot', 'Save current state as baseline instead of watching')
   .option('--diff', 'Diff current file against saved baseline and exit')
-  .action(async (files, opts) => {
+  .option('--allow-empty', 'Allow --snapshot to succeed when nothing was written', false)
+  .action(async (files, opts, command) => {
     try {
       const { config } = loadRcConfig(process.cwd());
-      const effective = resolveEffectiveOptions(config, opts.profile, opts);
+      const profile = resolveProfileName(opts.profile);
+      const effective = resolveEffectiveOptions(config, profile, stripUnsetCliOverrides(opts, command));
+      const { policies, plugins, severityRemap } = resolvePolicyOptions(effective);
       const targets = (await resolveTargetFiles(files, config)).map((f) => resolve(f));
       if (targets.length === 0) {
         throw new Error('No files matched. Provide files or configure .flectorc files/include.');
@@ -193,15 +341,36 @@ program
       validateInterval(interval);
       const mode = String(effective.mode ?? 'compact');
       validateMode(mode);
+      const maskSecrets = Boolean(effective.maskSecrets);
+      const maskSecretsWebhooks = Boolean(effective.maskSecretsWebhooks);
+      const dOpts = diffOptionsFromEffective(effective, ignorePaths);
 
       if (effective.snapshot) {
         mkdirSync(SNAPSHOT_DIR, { recursive: true });
+        let written = 0;
         for (const filepath of targets) {
-          if (!existsSync(filepath) || !isSupported(filepath)) continue;
+          if (!existsSync(filepath)) {
+            renderWarn(`Skipping missing file: ${filepath}`);
+            continue;
+          }
+          if (!isSupported(filepath)) {
+            renderWarn(`Skipping unsupported file: ${filepath}`);
+            continue;
+          }
           const state = parseFile(filepath);
           const snapshotPath = snapshotPathForFile(filepath);
-          writeFileSync(snapshotPath, JSON.stringify({ file: filepath, state }, null, 2), 'utf8');
+          preserveLegacySnapshotForHistory(filepath, snapshotPath);
+          const snapshot = { file: filepath, state, createdAt: new Date().toISOString() };
+          writeFileSync(snapshotPath, JSON.stringify(snapshot, null, 2), 'utf8');
+          writeFileSync(snapshotHistoryPathForFile(filepath), JSON.stringify(snapshot, null, 2), 'utf8');
           console.log(chalk.green(`✓ Snapshot saved: ${snapshotPath}`));
+          written += 1;
+        }
+        if (written === 0 && !effective.allowEmpty) {
+          throw new Error(
+            'No snapshots written — all targets were missing or unsupported.' +
+              ' Pass --allow-empty to allow an empty snapshot run.',
+          );
         }
         return;
       }
@@ -216,8 +385,8 @@ program
           }
           const before = readSnapshotStateFromFile(snapshotPath);
           const after = parseFile(filepath);
-          const events = diffTrees(before, after, { ignorePaths });
-          renderDiff(filepath, events);
+          const events = diffTrees(before, after, dOpts);
+          renderDiff(filepath, events, { maskSecrets });
           if (events.length > 0) hasChanges = true;
         }
         process.exit(hasChanges ? 1 : 0);
@@ -237,17 +406,33 @@ program
         renderInfo(`flecto watching ${chalk.cyan(filepath)}`);
         const watcher = startWatcher(
           filepath,
-          { interval, mode, ignorePaths, polling: Boolean(effective.polling) },
+          { interval, mode, ignorePaths, polling: Boolean(effective.polling), ...dOpts },
           async (event) => {
             if (event.kind === 'changes') {
-              renderChanges(event.filepath, event.events, mode);
-              const policyFindings = evaluatePolicies(event.events);
+              renderChanges(event.filepath, event.events, mode, { maskSecrets });
+              let policyFindings = [];
+              try {
+                policyFindings = await evaluatePolicies(event.events, {
+                  cwd: process.cwd(),
+                  file: event.filepath,
+                  profile: profile ?? null,
+                  source: 'watch',
+                  policies,
+                  plugins,
+                  severityRemap,
+                });
+              } catch (err) {
+                renderError(`policy evaluation failed: ${err.message}`);
+                process.exit(1);
+              }
               renderPolicyFindings(policyFindings);
               if (effective.command || effective.webhook) {
+                const outboundChanges = maybeMaskChanges(event.events, maskSecretsWebhooks);
                 const envelope = createEnvelope({
                   source: 'watch',
                   file: event.filepath,
-                  changes: event.events,
+                  changes: outboundChanges,
+                  policies: policyFindings,
                 });
                 await fireAlerts({
                   command: effective.command,
@@ -303,57 +488,147 @@ program
     }
   });
 
+program
+  .command('history [files...]')
+  .description('Summarize drift across local snapshots')
+  .option('-l, --limit <n>', 'Number of recent snapshots to show', '10')
+  .option('-p, --profile <name>', 'Use profile from .flectorc (else FLECTO_PROFILE)')
+  .option('--ignore <keys>', 'Comma-separated key paths to ignore (e.g. "updated_at,meta.ts")')
+  .option('--array-id-key <key>', 'Diff arrays by this object identity key (opt-in)')
+  .option('--array-ignore-order', 'Treat array order as insignificant', false)
+  .action(async (files, opts, command) => {
+    try {
+      const limit = Number.parseInt(String(opts.limit), 10);
+      if (!Number.isInteger(limit) || limit < 1) {
+        throw new Error('--limit must be a positive integer');
+      }
+
+      const { config } = loadRcConfig(process.cwd());
+      const profile = resolveProfileName(opts.profile);
+      const effective = resolveEffectiveOptions(config, profile, stripUnsetCliOverrides(opts, command));
+      const ignorePaths = parseCsv(effective.ignore);
+      const dOpts = diffOptionsFromEffective(effective, ignorePaths);
+
+      const allSnapshots = readLocalSnapshotHistory();
+      let snapshots = allSnapshots;
+      if (files.length > 0) {
+        const targets = new Set((await resolveTargetFiles(files, config)).map((file) => resolve(file)));
+        snapshots = snapshots.filter((snapshot) => targets.has(resolve(snapshot.file)));
+      }
+
+      const summaries = summarizeSnapshotHistory(snapshots, limit, dOpts);
+      if (summaries.length === 0) {
+        if (files.length > 0 && allSnapshots.length > 0) {
+          throw new Error(
+            'No local snapshots matched the given files. Omit files to view all saved snapshot history.',
+          );
+        }
+        throw new Error('No local snapshots found. Run "flecto watch <file> --snapshot" first.');
+      }
+
+      console.log(`Local snapshot history (${summaries.length} snapshots)`);
+      for (const snapshot of summaries) {
+        const file = relative(process.cwd(), snapshot.file) || snapshot.file;
+        const changes = `${snapshot.changeCount} change${snapshot.changeCount === 1 ? '' : 's'}`;
+        console.log(`${snapshot.createdAt}  ${file} — ${changes}`);
+      }
+    } catch (err) {
+      renderError(err.message);
+      process.exit(1);
+    }
+  });
+
 program
   .command('ci [files...]')
   .description('Run semantic diff in CI mode')
-  .option('-p, --profile <name>', 'Use profile from .flectorc')
+  .option('-p, --profile <name>', 'Use profile from .flectorc (else FLECTO_PROFILE)')
   .option('--snapshot-ref <ref>', 'Snapshot reference: snapshot path or git ref')
   .option('--format <type>', 'Output format: json | ndjson | github-annotations', 'json')
   .option('--fail-on <rules>', 'Comma-separated fail rules: changed,added,removed,policy,error,warn', 'changed,policy,error')
   .option('--ignore <keys>', 'Comma-separated key paths to ignore')
-  .action(async (files, opts) => {
+  .option('--policies <ids>', 'Comma-separated policy pack ids')
+  .option('--plugins <paths>', 'Comma-separated local ESM plugin paths')
+  .option('--array-id-key <key>', 'Diff arrays by this object identity key')
+  .option('--no-array-id', 'Diff arrays by index instead of object identity')
+  .option('--array-ignore-order', 'Treat array order as insignificant', false)
+  .option('--mask-secrets', 'Mask secret-like values in CI output', false)
+  .option('--allow-empty', 'Allow CI to succeed when no files were diffed', false)
+  .action(async (files, opts, command) => {
     try {
       const { config } = loadRcConfig(process.cwd());
-      const effective = resolveEffectiveOptions(config, opts.profile, opts);
+      const profile = resolveProfileName(opts.profile);
+      const effective = resolveEffectiveOptions(config, profile, stripUnsetCliOverrides(opts, command));
+      const { policies: packIds, plugins, severityRemap } = resolvePolicyOptions(effective);
       const targets = (await resolveTargetFiles(files, config)).map((f) => resolve(f));
       if (targets.length === 0) {
         throw new Error('No files matched. Provide files or configure .flectorc files/include.');
       }
 
       const ignorePaths = parseCsv(effective.ignore);
-      const failOn = new Set(parseCsv(effective.failOn));
+      const failOn = new Set(parseCsv(effective.failOn ?? 'changed,policy,error'));
       const format = String(effective.format ?? 'json');
       if (!['json', 'ndjson', 'github-annotations'].includes(format)) {
         throw new Error('--format must be json, ndjson, or github-annotations');
       }
+      const maskSecrets = Boolean(effective.maskSecrets);
+      const dOpts = diffOptionsFromEffective(effective, ignorePaths);
 
       /** @type {any[]} */
       const results = [];
       let shouldFail = false;
+      let diffed = 0;
 
       for (const filepath of targets) {
-        if (!existsSync(filepath) || !isSupported(filepath)) continue;
+        if (!existsSync(filepath)) {
+          renderWarn(`Skipping missing file: ${filepath}`);
+          continue;
+        }
+        if (!isSupported(filepath)) {
+          renderWarn(`Skipping unsupported file: ${filepath}`);
+          continue;
+        }
         const after = parseFile(filepath);
-        let before = {};
+        let before;
         try {
           before = readSnapshotStateFromRef(filepath, effective.snapshotRef);
-        } catch {
-          before = {};
+        } catch (err) {
+          throw new Error(
+            `Failed to resolve snapshot baseline for "${filepath}"` +
+            `${effective.snapshotRef ? ` (ref: ${effective.snapshotRef})` : ''}: ${err.message}`
+          );
         }
-        const events = diffTrees(before, after, { ignorePaths });
-        const policies = evaluatePolicies(events);
+        const events = diffTrees(before, after, dOpts);
+        const policyFindings = await evaluatePolicies(events, {
+          cwd: process.cwd(),
+          file: filepath,
+          profile: profile ?? null,
+          source: 'ci',
+          policies: packIds,
+          plugins,
+          severityRemap,
+        });
+        const outboundChanges = maybeMaskChanges(events, maskSecrets);
         const envelope = createEnvelope({
           source: 'ci',
           file: filepath,
-          changes: events,
+          changes: outboundChanges,
+          policies: policyFindings,
         });
-        results.push({ file: filepath, envelope, policies });
+        results.push({ file: filepath, envelope, policies: policyFindings });
+        diffed += 1;
 
-        if (shouldFailFromChanges(events, failOn) || shouldFailFromPolicy(policies, failOn)) {
+        if (shouldFailFromChanges(events, failOn) || shouldFailFromPolicy(policyFindings, failOn)) {
           shouldFail = true;
         }
       }
 
+      if (diffed === 0 && !effective.allowEmpty) {
+        throw new Error(
+          'No files were diffed — all targets were missing or unsupported.' +
+            ' Pass --allow-empty to allow an empty CI run.',
+        );
+      }
+
       printCiOutput(results, format);
       process.exit(shouldFail ? 1 : 0);
     } catch (err) {
@@ -362,6 +637,53 @@ program
     }
   });
 
+{
+  const policies = program
+    .command('policies')
+    .description('Work with policy packs and plugins');
+
+  policies
+    .command('test <fixtureDir>')
+    .description('Assert policy findings from a fixture directory')
+    .option('--config <name>', 'Fixture config file name', 'flecto-policy-test.json')
+    .action(async (fixtureDir, opts) => {
+      try {
+        const result = await testPolicyFixture(fixtureDir, { configName: opts.config });
+        console.log(chalk.green(
+          `✓ Policy fixture passed: ${result.fixtureDir} (${result.findings.length} findings)`,
+        ));
+      } catch (err) {
+        renderError(err.message);
+        process.exitCode = 1;
+      }
+    });
+
+  policies
+    .command('list')
+    .description('List built-in and local policy packs')
+    .option('--json', 'Output machine-readable JSON')
+    .action((opts) => {
+      try {
+        const packs = listPolicyPacks(process.cwd());
+        if (opts.json) {
+          console.log(JSON.stringify(packs, null, 2));
+          return;
+        }
+
+        console.log('Resolution order: policies/<id>.json, .yaml, .yml, then built-in packs.');
+        console.log('id\tsource path\trules\toverrides builtin');
+        for (const pack of packs) {
+          console.log(
+            `${pack.id}\t${pack.sourcePath}\t${pack.ruleCount}\t${pack.overridesBuiltin ? 'yes' : 'no'}`,
+          );
+        }
+      } catch (err) {
+        renderError(err.message);
+        process.exit(1);
+      }
+    });
+}
+
 program
   .command('init')
   .description('Create starter .flectorc configuration')
@@ -389,10 +711,16 @@ program
         exclude: config?.exclude ?? [],
       });
       renderInfo(`resolved files: ${files.length}`);
+      const [major, minor] = process.versions.node.split('.').map(Number);
+      if (major < 20 || (major === 20 && minor < 19)) {
+        throw new Error(`Node.js ${process.versions.node} is unsupported. Use Node.js >= 20.19.0.`);
+      }
+      renderInfo(`node: ${process.versions.node}`);
       if (typeof fetch !== 'function') {
-        throw new Error('Global fetch unavailable. Use Node.js >= 18.');
+        throw new Error('Global fetch unavailable. Use Node.js >= 20.19.0.');
       }
       renderInfo('fetch: available');
+      renderInfo(`version: ${PKG.version}`);
       renderInfo('doctor: OK');
     } catch (err) {
       renderError(`doctor failed: ${err.message}`);
@@ -400,9 +728,8 @@ program
     }
   });
 
-program.parse(process.argv);
+await program.parseAsync(process.argv);
 
-// Show help if no command given
 if (!process.argv.slice(2).length) {
   program.help();
 }

package/package.json

@@ -4,7 +4,7 @@
     "access": "public",
     "provenance": true
   },
-  "version": "1.0.2",
+  "version": "2.1.0",
   "description": "Flecto — semantic config watcher that reports meaningful changes in plain English",
   "license": "MIT",
   "keywords": [
@@ -25,7 +25,7 @@
     "url": "git+https://github.com/myselfsiddharth/Flecto.git"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=20.19.0"
   },
   "type": "module",
   "main": "index.js",
@@ -35,8 +35,10 @@
   "files": [
     "index.js",
     "src/**/*",
+    "schemas/**/*",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "test": "node --test test/*.test.js",
@@ -46,10 +48,10 @@
   "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-envelope-2.0.json

@@ -0,0 +1,65 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/myselfsiddharth/Flecto/schemas/flecto-envelope-2.0.json",
+  "title": "FlectoEnvelope",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "event_id",
+    "batch_id",
+    "event_type",
+    "source",
+    "emitted_at",
+    "file",
+    "changes"
+  ],
+  "properties": {
+    "schema_version": { "const": "2.0" },
+    "event_id": { "type": "string", "minLength": 1 },
+    "batch_id": { "type": "string", "minLength": 1 },
+    "event_type": { "enum": ["changes", "lifecycle"] },
+    "source": { "enum": ["watch", "ci", "diff"] },
+    "emitted_at": { "type": "string", "format": "date-time" },
+    "file": { "type": "string" },
+    "changes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["type", "path"],
+        "properties": {
+          "type": { "enum": ["added", "removed", "changed"] },
+          "path": { "type": "string" },
+          "before": true,
+          "after": true,
+          "note": { "type": "string" }
+        },
+        "additionalProperties": false
+      }
+    },
+    "policies": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "severity", "path", "message"],
+        "properties": {
+          "id": { "type": "string" },
+          "severity": { "enum": ["info", "warn", "error"] },
+          "path": { "type": "string" },
+          "message": { "type": "string" },
+          "pack": { "type": "string" }
+        },
+        "additionalProperties": false
+      }
+    },
+    "lifecycle": {
+      "type": "object",
+      "required": ["type", "message"],
+      "properties": {
+        "type": { "type": "string" },
+        "message": { "type": "string" }
+      },
+      "additionalProperties": false
+    }
+  }
+}