config-audit/scanners/posture.mjs

#!/usr/bin/env node

/**
 * Config-Audit Posture Assessment CLI
 * Runs all scanners + scoring in a single Node.js process.
 * Usage: node posture.mjs <target-path> [--json] [--global] [--output-file path]
 * Zero external dependencies.
 */

import { resolve } from 'node:path';
import { writeOutputFile } from './lib/write-output.mjs';
import { requireTargetDir } from './lib/require-target-dir.mjs';
import { runAllScanners } from './scan-orchestrator.mjs';
import { humanizeEnvelope } from './lib/humanizer.mjs';
import { requireValidArgs } from './lib/cli-args.mjs';
import {
  calculateUtilization,
  determineMaturityLevel,
  determineSegment,
  scoreByArea,
  topActions,
  generateScorecard,
  generateHealthScorecard,
} from './lib/scoring.mjs';

/** Flag surface, measured 2026-08-09. Anything else is exit 3. */
const ARG_SPEC = {
  boolean: ['--json', '--raw', '--global', '--full-machine', '--include-fixtures'],
  value: ['--output-file', '--context-window'],
};

/**
 * Run posture assessment and return structured result.
 * @param {string} targetPath
 * @param {object} [opts]
 * @param {boolean} [opts.includeGlobal=false]
 * @param {boolean} [opts.fullMachine=false] - Scan all known locations across the machine
 * @returns {Promise<object>}
 */
export async function runPosture(targetPath, opts = {}) {
  const envelope = await runAllScanners(targetPath, opts);

  // Extract GAP scanner results
  const gapScanner = envelope.scanners.find(s => s.scanner === 'GAP');
  const gapFindings = gapScanner ? gapScanner.findings : [];

  // Calculate scores
  const utilization = calculateUtilization(gapFindings);
  const maturity = determineMaturityLevel(gapFindings, { files: [] });
  const segment = determineSegment(utilization.score);
  const areaScores = scoreByArea(envelope.scanners);
  const actions = topActions(gapFindings);

  return {
    utilization,
    maturity,
    segment,
    areas: areaScores.areas,
    overallGrade: areaScores.overallGrade,
    topActions: actions,
    opportunityCount: gapFindings.length,
    scannerEnvelope: envelope,
  };
}

// --- CLI entry point ---
async function main() {
  const args = process.argv.slice(2);
  if (!requireValidArgs(args, ARG_SPEC)) return;
  let targetPath = '.';
  let outputFile = null;
  let jsonMode = false;
  let rawMode = false;
  let includeGlobal = false;
  let fullMachine = false;
  let contextWindow = null;

  for (let i = 0; i < args.length; i++) {
    if (args[i] === '--output-file' && args[i + 1]) {
      outputFile = args[++i];
    } else if (args[i] === '--context-window' && args[i + 1]) {
      contextWindow = args[++i];
    } else if (args[i] === '--json') {
      jsonMode = true;
    } else if (args[i] === '--raw') {
      rawMode = true;
    } else if (args[i] === '--global') {
      includeGlobal = true;
    } else if (args[i] === '--full-machine') {
      fullMachine = true;
    } else if (args[i] === '--include-fixtures') {
      // handled below
    } else if (!args[i].startsWith('-')) {
      targetPath = args[i];
    }
  }

  if (!(await requireTargetDir(resolve(targetPath)))) {
    process.exitCode = 3;
    return;
  }

  const filterFixtures = !args.includes('--include-fixtures');
  const humanizedProgress = !jsonMode && !rawMode;
  const result = await runPosture(targetPath, {
    includeGlobal,
    fullMachine,
    filterFixtures,
    humanizedProgress,
    contextWindow,
  });

  // stdout JSON path: --json and --raw both write the v5.0.0-shape result
  // (byte-identical). Default mode writes nothing to stdout.
  if (jsonMode || rawMode) {
    const json = JSON.stringify(result, null, 2);
    process.stdout.write(json + '\n');
  }

  // stderr scorecard path: --json suppresses; --raw renders v5.0.0 verbatim
  // (humanized=false); default renders humanized scorecard.
  if (!jsonMode) {
    const scorecard = generateHealthScorecard(
      { areas: result.areas, overallGrade: result.overallGrade },
      result.opportunityCount,
      { humanized: !rawMode },
    );
    process.stderr.write('\n' + scorecard + '\n');
  }

  if (outputFile) {
    // Consumers (feature-gap.md, posture.md) read scannerEnvelope.scanners[].findings
    // and group on humanizer fields. posture's result nests the envelope under
    // `scannerEnvelope`, so humanize THAT (not `result`, which has no top-level
    // `scanners` array — humanizeEnvelope would no-op). --json/--raw stay raw.
    const fileEnv = (jsonMode || rawMode)
      ? result
      : { ...result, scannerEnvelope: humanizeEnvelope(result.scannerEnvelope) };
    const json = JSON.stringify(fileEnv, null, 2);
    await writeOutputFile(outputFile, json, 'utf-8');
    process.stderr.write(`\nResults written to ${outputFile}\n`);
  }
}

// Only run CLI if invoked directly
const isDirectRun = process.argv[1] && resolve(process.argv[1]) === resolve(new URL(import.meta.url).pathname);
if (isDirectRun) {
  main().catch(err => {
    process.stderr.write(`Fatal: ${err.message}\n`);
    // 3, not 1. Every command in this plugin is told that 0/1/2 are normal grades
    // (PASS/WARNING/FAIL) and only 3 is a real error, so exiting 1 here made a crash
    // indistinguishable from a WARNING — and the command went on to Read a payload file
    // that was never written.
    process.exitCode = 3;
  });
}