#!/usr/bin/env node

/**
 * ats-payload.mjs — ATS payload transform: one safe fold, three lints (#3251).
 *
 * Follows from #3202, whose conclusion was that an ATS variant is not a template
 * swap. A template owns the DOM; it does not own what is IN the payload, and some
 * of what an ATS parser mishandles is in the payload. By the time a template sees
 * `competencies: [...]` the decision that breaks parsing has already been made.
 *
 * THE FOLD (applied — pure data movement, no text invented, fully reversible)
 *
 *   `build-cv-html.mjs` renders competencies as bare tag spans into a container
 *   whose separation is entirely visual (`.competencies-grid { gap: 8px }`).
 *   There is no delimiter CHARACTER between one competency and the next — the gap
 *   is CSS. Extract the text layer and adjacent competencies run together into a
 *   single token. On top of that the block ships under `Core Competencies`, which
 *   is not a section name parsers recognise, so it is frequently dropped whole
 *   rather than merely mangled.
 *
 *   `Skills` IS recognised, and already renders through `buildSkills()` as
 *   `<span class="skill-category">Cat:</span> a, b, c` — comma-delimited, under a
 *   header parsers look for. So the same facts, expressed two ways, survive or
 *   don't depending on which array they sit in. This script moves them into the
 *   array that survives. Nothing is rewritten, nothing is invented.
 *
 * THE THREE LINTS (reported, never applied — each needs a decision only the
 * author can make, which is where AGENTS.md's no-fabrication rule draws the line)
 *
 *   employer-in-role       An employer name inside `role` yields a phantom
 *                          employer in the parsed record — the trap for
 *                          consulting and agency work. Detecting "this substring
 *                          is an employer" is not something a script should be
 *                          confident about, and silently rewriting a job title is
 *                          worse than the mangling it prevents.
 *   parenthetical-in-company
 *                          `(Cloud Platform Division)` is kept verbatim as part of
 *                          the employer name, giving a record no search matches.
 *                          Stripping it is easy; deciding where that detail GOES
 *                          instead is authoring.
 *   multiple-date-ranges   Two stints at one employer parse as one. Splitting them
 *                          needs someone to decide which bullets belong to which
 *                          stint. A script can see the second range; it cannot
 *                          allocate the bullets.
 *
 * A tool that reported four findings and applied one is trustworthy; a tool that
 * applied four would be guessing three times per run.
 *
 * CONTRACT: payload JSON in, payload JSON out on stdout, findings on stderr.
 * Zero-LLM, deterministic, offline, and read-only with respect to user-layer
 * files — it consumes a payload and emits a new one, and never writes back to
 * `cv.md` or `config/profile.yml`. Same family as `jd-skill-gap.mjs` and
 * `verify-cv-facts.mjs`. The input object is never mutated.
 *
 * Usage:
 *   node ats-payload.mjs cv.json > cv-ats.json
 *   node ats-payload.mjs cv.json --summary > cv-ats.json
 *   cat cv.json | node ats-payload.mjs - > cv-ats.json
 *   node build-cv-html.mjs cv-ats.json out.html templates/ats/cv-template.ats.html
 *   node ats-payload.mjs --self-test
 *
 * Exit 0 whenever the transform succeeded, findings or not: the lints are
 * advisory by design and the payload on stdout is always usable. Exit 1 only for
 * an unreadable or malformed input.
 */

import { readFileSync } from 'fs';
import { validateFlags } from './lib/cli-flags.mjs';
import { isMainModule } from './lib/is-main-module.mjs';

// Mirrors DEFAULT_SECTION_TITLES.competencies in build-cv-html.mjs. Used only
// when the payload carries no `sections.competencies` of its own — a localized
// payload keeps its own label, because relabelling the user's section title
// would be inventing text rather than moving it.
const DEFAULT_COMPETENCIES_TITLE = 'Core Competencies';

// ── Helpers ─────────────────────────────────────────────────────────────────

/** Trimmed non-empty strings from a payload array (numbers coerced, as the
 *  builder's own `escapeHtml(String(tag))` does). Objects/null are structural
 *  noise and are dropped rather than stringified into "[object Object]". */
function toItemList(value) {
  const raw = Array.isArray(value)
    ? value
    : typeof value === 'string' ? value.split(',') : [];
  return raw
    .filter((v) => v !== null && v !== undefined && typeof v !== 'object')
    .map((v) => String(v).trim())
    .filter(Boolean);
}

/** Category-name identity for the idempotency check: case- and
 *  whitespace-insensitive, trailing colon ignored (the template renders the
 *  colon, but a hand-written payload sometimes carries it). */
function categoryKey(name) {
  return String(name ?? '')
    .replace(/\s+/g, ' ')
    .replace(/:\s*$/, '')
    .trim()
    .toLowerCase();
}

/** The label the fold uses for the category it writes. A payload carrying its
 *  own localized `sections.competencies` keeps it — relabelling the user's
 *  section title would be inventing text rather than moving it. */
function resolveCompetenciesCategory(payload) {
  return (typeof payload?.sections?.competencies === 'string'
    && payload.sections.competencies.trim())
    || DEFAULT_COMPETENCIES_TITLE;
}

/**
 * Members `toItemList()` DROPS rather than coerces, reported with their index.
 *
 * The line is drawn at what is actually lost, not at what is not a string.
 * `toItemList()` passes every scalar through `String()`, so a numeric or boolean
 * member survives with its value intact — and that is a deliberate, tested
 * position in this repo, not an accident: `build-cv-html.mjs`'s `escapeHtml()`
 * used to `return ''` for anything non-string, which silently dropped numeric
 * years and dates from shipped CVs (see tests/cv-numeric-scalars.test.mjs), and
 * `buildCompetencies()` renders `escapeHtml(String(tag))` for exactly that
 * reason. Rejecting a numeric member here would make this script stricter than
 * the builder it feeds and refuse a payload that renders correctly today.
 *
 * Objects, arrays, `null` and `undefined` have no scalar value to carry, are
 * dropped outright, and are what this exists to catch.
 *
 * @param {unknown[]} list - Array whose members would go through toItemList().
 * @returns {Array<{index: number, type: string}>} One entry per dropped member.
 */
function lostMembers(list) {
  const lost = [];
  list.forEach((value, index) => {
    if (value === null || value === undefined || typeof value === 'object') {
      lost.push({ index, type: Array.isArray(value) ? 'array' : value === null ? 'null' : typeof value });
    }
  });
  return lost;
}

// ── Payload shape validation ────────────────────────────────────────────────

/**
 * Check the three fields this script reads, and refuse a payload whose shape
 * would make the run quietly wrong (CodeRabbit, PR #3422).
 *
 * Both failures this catches are silent, and silence is what makes them worse
 * than a crash:
 *
 *   `skills` non-array — `foldCompetencies()` starts from `[]`, so a payload
 *   carrying `"skills": "Python, Go"` has that value DISCARDED and is handed
 *   back a well-formed-looking artifact with the skills gone. A transform whose
 *   entire claim is "pure data movement, nothing invented, fully reversible"
 *   must not be the thing that loses data, and it must not lose it into output
 *   that looks correct.
 *
 *   `experience` non-array — `lintPayload()` iterates `[]` and reports nothing,
 *   which prints as "✅ No lint findings" and reads exactly like a clean
 *   payload. That is the same shape `jd-skill-gap.mjs` added diagnoseExtraction()
 *   for: an empty result is indistinguishable from a clean bill of health, and
 *   the caller acts on the wrong one.
 *
 * Refusing rather than coercing is the point. There is no honest place to put a
 * string `skills` value inside `skills[]`, and inventing the structure to hold
 * it is exactly the authoring this script refuses to do everywhere else — so
 * the malformed payload is the user's to fix, loudly, before anything is
 * written.
 *
 * A `competencies` STRING is accepted rather than refused: `toItemList()` splits
 * it on commas, mirroring the string-or-array `items` the builder's `joinItems()`
 * already takes for a skills category. Absent and `null` both mean "not
 * supplied" and are always fine.
 *
 * @param {object} payload - Parsed CV payload.
 * @returns {string[]} One message per problem; empty when the shape is usable.
 */
export function validatePayloadShape(payload) {
  const errors = [];
  const shapeOf = (v) => (Array.isArray(v) ? 'array' : typeof v);
  const present = (v) => v !== undefined && v !== null;

  if (present(payload.skills) && !Array.isArray(payload.skills)) {
    errors.push(`\`skills\` must be an array of {category, items} objects, got ${shapeOf(payload.skills)}. `
      + 'Folding into it would silently discard the value you supplied.');
  }
  if (present(payload.competencies)
      && !Array.isArray(payload.competencies)
      && typeof payload.competencies !== 'string') {
    errors.push(`\`competencies\` must be an array of strings (a comma-separated string is also accepted), `
      + `got ${shapeOf(payload.competencies)}.`);
  }
  if (present(payload.experience) && !Array.isArray(payload.experience)) {
    errors.push(`\`experience\` must be an array of entries, got ${shapeOf(payload.experience)}. `
      + 'The lints would report nothing, which is indistinguishable from a clean payload.');
  }

  // Member level, same defect one layer down (CodeRabbit, PR #3422). The array
  // container being right is not enough: `["AWS", {"name":"Kubernetes"}]` passed
  // every check above while toItemList() dropped the object on the way through,
  // so the fold emitted `items: "AWS"` and the second competency was gone from a
  // payload that looked fine.
  const describe = (lost) => lost.map((l) => `[${l.index}] (${l.type})`).join(', ');
  if (Array.isArray(payload.competencies)) {
    const lost = lostMembers(payload.competencies);
    if (lost.length > 0) {
      errors.push(`\`competencies\` has ${lost.length} member(s) with no scalar value to move: `
        + `${describe(lost)}. They would be dropped rather than folded. `
        + 'Strings are expected; numbers and booleans are coerced.');
    }
  }

  // The same loss in the field the fold WRITES to. When a competency category
  // already exists, the fold re-joins its items through toItemList() to union
  // them, and a non-scalar member there disappears exactly the same way.
  //
  // Guarded on a fold actually happening, and on the one category it would touch,
  // so a payload this script would otherwise pass through untouched is never
  // rejected for a field it was never going to rewrite.
  if (toItemList(payload.competencies).length > 0 && Array.isArray(payload.skills)) {
    const category = resolveCompetenciesCategory(payload);
    const target = payload.skills.find(
      (entry) => entry && typeof entry === 'object' && categoryKey(entry.category) === categoryKey(category),
    );
    if (target && Array.isArray(target.items)) {
      const lost = lostMembers(target.items);
      if (lost.length > 0) {
        errors.push(`the existing \`${category}\` skills category has ${lost.length} member(s) in \`items\` `
          + `with no scalar value: ${describe(lost)}. Merging the competencies into it would drop them.`);
      }
    } else if (target && present(target.items) && typeof target.items !== 'string') {
      // A merge target whose `items` is neither a string nor an array: the merge
      // reads it through toItemList(), gets `[]`, and REPLACES it with the folded
      // competencies — the supplied value silently overwritten.
      //
      // Note the asymmetry with the competency members above, which is real and
      // not an inconsistency. A member is coerced by `String()` on both sides
      // (here and in `buildCompetencies()`'s `escapeHtml(String(tag))`), so a
      // number carries its value through. An `items` CONTAINER is not: the
      // builder's `joinItems()` returns `''` for anything that is neither string
      // nor array, so a numeric `items` has no value-preserving path in either
      // tool. With no way to carry it and no honest way to invent one, refusing
      // is the only non-destructive answer.
      errors.push(`the existing \`${category}\` skills category has \`items\` of type `
        + `${shapeOf(target.items)}; a string or array is expected. Merging the competencies `
        + 'into it would overwrite that value.');
    }
  }

  return errors;
}

// ── The transform: fold competencies[] into skills[] ─────────────────────────

/**
 * Move `competencies[]` into `skills[]` as one comma-delimited category and
 * empty the source array.
 *
 * IDEMPOTENT (the edge santifer asked to have pinned by a test): running this on
 * an already-folded payload is a no-op, not a duplicate category. Two mechanisms
 * carry that, because either alone is incomplete:
 *
 *   1. An empty/absent `competencies` returns the payload untouched — the second
 *      run of a plain `transform | transform` pipeline.
 *   2. When a skills category with the same name already exists, its items are
 *      UNIONed in place (order preserved, exact duplicates dropped) instead of a
 *      second category being prepended — the case where a payload was re-edited
 *      with some competencies re-added after a first fold.
 *
 * Callers are expected to have run `validatePayloadShape()` first: this function
 * normalizes a non-array `skills` to `[]`, which DISCARDS it. The CLI validates
 * at its boundary so that path is unreachable there.
 *
 * @param {object} payload - Parsed CV payload. Never mutated.
 * @returns {{payload: object, transform: object}} New payload + what was done.
 */
export function foldCompetencies(payload) {
  const source = payload && typeof payload === 'object' ? payload : {};
  const competencies = toItemList(source.competencies);
  const category = resolveCompetenciesCategory(source);

  if (competencies.length === 0) {
    return {
      payload: source,
      transform: {
        name: 'fold-competencies-into-skills',
        applied: false,
        reason: 'no competencies to fold',
        category,
        moved: 0,
      },
    };
  }

  const skills = Array.isArray(source.skills) ? source.skills : [];
  const existingIndex = skills.findIndex(
    (s) => s && typeof s === 'object' && categoryKey(s.category) === categoryKey(category),
  );

  let nextSkills;
  let merged;
  if (existingIndex === -1) {
    // Prepend: competencies are the keyword block a parser should hit first,
    // and prepending keeps them ahead of the language/framework categories.
    nextSkills = [{ category, items: competencies.join(', ') }, ...skills];
    merged = false;
  } else {
    const existing = skills[existingIndex];
    const existingItems = toItemList(existing.items);
    const seen = new Set(existingItems.map((i) => i.toLowerCase()));
    const added = competencies.filter((i) => {
      const key = i.toLowerCase();
      if (seen.has(key)) return false;
      seen.add(key);
      return true;
    });
    nextSkills = skills.slice();
    nextSkills[existingIndex] = {
      ...existing,
      items: [...existingItems, ...added].join(', '),
    };
    merged = true;
  }

  return {
    // `competencies: []` rather than a deleted key: build-cv-html.mjs and
    // stripEmptySections() both already treat an empty array as "drop the whole
    // block, header included", and keeping the key makes the fold obvious to a
    // human diffing the two payloads.
    payload: { ...source, competencies: [], skills: nextSkills },
    transform: {
      name: 'fold-competencies-into-skills',
      applied: true,
      merged,
      category,
      moved: competencies.length,
      items: competencies,
    },
  };
}

// ── The three lints ─────────────────────────────────────────────────────────

// Legal-form tokens that mark a substring as an organisation name rather than a
// job title. Deliberately narrow: a suffix is near-conclusive evidence, whereas
// a bare capitalized noun in a title is not.
const CORPORATE_SUFFIX_RE = /\b(?:inc|llc|l\.l\.c|ltd|limited|gmbh|mbh|ag|s\.?a\.?s|sarl|s\.?a|s\.?l|b\.?v|n\.?v|plc|corp|corporation|co|company|pty|oy|ab|a\/s|aps|kk|k\.k|holdings|group)\b\.?/i;

// Prepositions that attach an employer to a title. `at` and `@` only: " for "
// reads just as naturally as a team or product ("Engineer for Payments"), and a
// lint that cries wolf on ordinary titles gets ignored, which costs more than
// the case it would have caught.
const EMPLOYER_PREPOSITION_RE = /(?:\s(?:at|@)\s|\s@|^@)/i;

// Explicit client framing — the consulting/agency shape this lint exists for.
const CLIENT_MARKER_RE = /\b(?:client|customer|on behalf of|seconded to|via|through)\s*[:—–-]?\s*\S/i;

// A parenthetical inside `company`. Both ASCII and CJK full-width brackets: a
// ja/zh payload writes （云平台事业部）and the parser keeps it verbatim just the same.
const PARENTHETICAL_RE = /[(（]\s*([^)）]*?)\s*[)）]/;

// One date range: an endpoint, a separator, an endpoint. Endpoint forms cover
// "June 2022", "Jun. 2022", "06/2022", "2022" and the open end ("Present").
const DATE_POINT = '(?:(?:jan|feb|mar|apr|may|jun|jul|aug|sep|sept|oct|nov|dec)[a-z]*\\.?\\s*,?\\s*\\d{4}'
  + '|\\d{1,2}\\s*[/.]\\s*\\d{4}'
  + '|\\d{4}'
  + '|present|current|now|ongoing|date)';
const DATE_SEPARATOR = '\\s*(?:[-–—]{1,2}|\\bto\\b|\\buntil\\b|\\bthrough\\b)\\s*';
const DATE_RANGE_RE = new RegExp(`${DATE_POINT}${DATE_SEPARATOR}${DATE_POINT}`, 'gi');

/** Non-overlapping date ranges in a `dates` string. */
export function countDateRanges(dates) {
  if (typeof dates !== 'string') return 0;
  // Fresh lastIndex per call: the regex is module-level and /g is stateful.
  DATE_RANGE_RE.lastIndex = 0;
  return (dates.match(DATE_RANGE_RE) || []).length;
}

/** True when `needle` appears in `haystack` on non-alphanumeric boundaries, so
 *  "Acme" matches "Acme Cloud Engineer" but not "Acmerica". */
function containsAsToken(haystack, needle) {
  const hay = String(haystack).toLowerCase();
  const need = String(needle).trim().toLowerCase();
  if (need.length < 3) return false;
  let from = 0;
  for (;;) {
    const at = hay.indexOf(need, from);
    if (at === -1) return false;
    const before = at === 0 ? '' : hay[at - 1];
    const after = hay[at + need.length] ?? '';
    if (!/[a-z0-9]/i.test(before) && !/[a-z0-9]/i.test(after)) return true;
    from = at + 1;
  }
}

/**
 * Report the three judgement calls. Never edits anything.
 *
 * @param {object} payload - Parsed CV payload (pre- or post-fold; the lints read
 *   only `experience[]`, which the fold does not touch).
 * @returns {Array<object>} Findings, in payload order.
 */
export function lintPayload(payload) {
  const entries = Array.isArray(payload?.experience) ? payload.experience : [];
  const findings = [];

  // Every company named anywhere in the payload. A client name that leaked into
  // a title is very often another entry's employer, and that cross-entry match
  // is the one high-confidence signal available without a company database.
  const knownCompanies = entries
    .filter((e) => e && typeof e === 'object' && typeof e.company === 'string')
    .map((e) => e.company.trim())
    .filter((c) => c.length >= 3);

  entries.forEach((entry, index) => {
    if (!entry || typeof entry !== 'object') return;

    // ── 1. employer-in-role ──────────────────────────────────────────────
    const role = typeof entry.role === 'string' ? entry.role : '';
    if (role) {
      const signals = [];
      if (CORPORATE_SUFFIX_RE.test(role)) signals.push('corporate-suffix');
      if (EMPLOYER_PREPOSITION_RE.test(role)) signals.push('employer-preposition');
      if (CLIENT_MARKER_RE.test(role)) signals.push('client-marker');
      const matchedCompany = knownCompanies.find((c) => containsAsToken(role, c));
      if (matchedCompany) signals.push('known-company-name');
      if (signals.length > 0) {
        findings.push({
          code: 'employer-in-role',
          severity: 'review',
          path: `experience[${index}].role`,
          value: role,
          signals,
          ...(matchedCompany ? { matchedCompany } : {}),
          message: `Role reads as if it carries an employer name (${signals.join(', ')}). `
            + 'A parser lifts that into the employer field and the record gains a phantom '
            + 'employer. Rewriting a job title is authoring, not cleanup — decide yourself '
            + 'whether the employer belongs in `company` instead.',
        });
      }
    }

    // ── 2. parenthetical-in-company ──────────────────────────────────────
    const company = typeof entry.company === 'string' ? entry.company : '';
    const paren = company.match(PARENTHETICAL_RE);
    if (paren) {
      findings.push({
        code: 'parenthetical-in-company',
        severity: 'review',
        path: `experience[${index}].company`,
        value: company,
        parenthetical: paren[1],
        message: `The parenthetical "${paren[1]}" is kept verbatim as part of the employer `
          + 'name, so the record matches no search for the employer. Stripping it is easy; '
          + 'deciding where that detail goes instead (role, location, a bullet) is yours.',
      });
    }

    // ── 3. multiple-date-ranges ──────────────────────────────────────────
    const dates = typeof entry.dates === 'string' ? entry.dates : '';
    const ranges = countDateRanges(dates);
    if (ranges > 1) {
      findings.push({
        code: 'multiple-date-ranges',
        severity: 'review',
        path: `experience[${index}].dates`,
        value: dates,
        ranges,
        message: `${ranges} date ranges in one entry parse as one continuous stint. Splitting `
          + 'them into separate entries needs someone to decide which bullets belong to which '
          + 'stint — this script can see the second range, it cannot allocate the bullets.',
      });
    }
  });

  return findings;
}

// ── Orchestration ───────────────────────────────────────────────────────────

/**
 * The whole contract: one transform applied, three lints reported.
 *
 * @param {object} payload - Parsed CV payload. Never mutated.
 * @returns {{payload: object, transform: object, findings: Array<object>}}
 */
export function transformPayload(payload) {
  const { payload: folded, transform } = foldCompetencies(payload);
  return { payload: folded, transform, findings: lintPayload(folded) };
}

// ── Human summary ───────────────────────────────────────────────────────────

function formatSummary({ transform, findings }) {
  const lines = [];
  lines.push('');
  lines.push('ATS Payload Transform');
  lines.push('─'.repeat(60));
  if (transform.applied) {
    lines.push(`  ✅ Folded ${transform.moved} competenc${transform.moved === 1 ? 'y' : 'ies'} `
      + `into skills[] as "${transform.category}" (${transform.merged ? 'merged into existing category' : 'new category'}).`);
  } else {
    lines.push(`  ⏭️  No fold applied — ${transform.reason}.`);
  }
  lines.push('');
  if (findings.length === 0) {
    lines.push('  ✅ No lint findings.');
  } else {
    lines.push(`  ⚠️  ${findings.length} finding${findings.length === 1 ? '' : 's'} — reported, NOT applied:`);
    for (const f of findings) {
      lines.push('');
      lines.push(`  [${f.code}] ${f.path}`);
      lines.push(`     value: ${f.value}`);
      lines.push(`     ${f.message}`);
    }
  }
  lines.push('');
  lines.push('  The transformed payload is on stdout; these findings are yours to decide on.');
  lines.push('');
  return lines.join('\n');
}

// ── Self-test ───────────────────────────────────────────────────────────────

function runSelfTest() {
  let passed = 0;
  let failed = 0;
  const eq = (label, actual, expected) => {
    const ok = JSON.stringify(actual) === JSON.stringify(expected);
    if (ok) { passed++; console.log(`  ✅ ${label}`); }
    else { failed++; console.log(`  ❌ ${label}\n     expected: ${JSON.stringify(expected)}\n     actual:   ${JSON.stringify(actual)}`); }
  };

  // ── The fold ──
  const base = {
    competencies: ['RAG Pipelines', 'LLMOps', 'Kubernetes & Docker'],
    skills: [{ category: 'Languages', items: 'Python, Go' }],
  };
  const once = transformPayload(base);
  eq('competencies are emptied', once.payload.competencies, []);
  eq('competencies become a comma-delimited skills category',
    once.payload.skills[0], { category: 'Core Competencies', items: 'RAG Pipelines, LLMOps, Kubernetes & Docker' });
  eq('the existing skills categories survive after it', once.payload.skills[1], base.skills[0]);
  eq('the input payload is not mutated', base.competencies.length, 3);

  // Idempotency — the edge #3251 asked to have pinned.
  const twice = transformPayload(once.payload);
  eq('a second run is a no-op on skills', twice.payload.skills, once.payload.skills);
  eq('a second run applies no fold', twice.transform.applied, false);
  eq('a second run leaves competencies empty', twice.payload.competencies, []);

  // Idempotency, harder case: competencies re-added after a fold must merge
  // into the existing category, not create a duplicate one.
  const reAdded = { ...once.payload, competencies: ['LLMOps', 'Evaluation Harnesses'] };
  const remerged = transformPayload(reAdded);
  eq('a re-added competency merges instead of duplicating the category',
    remerged.payload.skills.filter((s) => s.category === 'Core Competencies').length, 1);
  eq('the merge unions items and drops the duplicate',
    remerged.payload.skills[0].items, 'RAG Pipelines, LLMOps, Kubernetes & Docker, Evaluation Harnesses');
  eq('the merge is reported as a merge', remerged.transform.merged, true);

  // A localized payload keeps its own section title as the category label.
  const localized = transformPayload({
    sections: { competencies: 'Competencias Clave' },
    competencies: ['Arquitectura Cloud'],
  });
  eq('a localized section title becomes the category label',
    localized.payload.skills[0].category, 'Competencias Clave');

  // Absent/empty inputs.
  eq('an absent competencies key applies no fold', foldCompetencies({}).transform.applied, false);
  eq('an empty competencies array applies no fold', foldCompetencies({ competencies: [] }).transform.applied, false);
  eq('a payload with no skills key still gets the folded category',
    foldCompetencies({ competencies: ['A'] }).payload.skills.length, 1);

  // ── Shape validation (PR #3422) ──
  // The exact input CodeRabbit asked to have covered: a present-but-non-array
  // `skills` alongside competencies to fold. Before the guard this silently
  // discarded "Python" and returned a clean-looking payload.
  eq('a string skills field is refused, naming the field',
    validatePayloadShape({ competencies: ['AWS'], skills: 'Python' }).length, 1);
  eq('the skills error says the value would be discarded',
    /skills.*discard/is.test(validatePayloadShape({ competencies: ['AWS'], skills: 'Python' })[0]), true);
  eq('a non-array experience is refused',
    validatePayloadShape({ experience: { company: 'Acme' } }).length, 1);
  eq('an object competencies field is refused',
    validatePayloadShape({ competencies: { a: 1 } }).length, 1);

  eq('a valid payload passes validation',
    validatePayloadShape({ competencies: ['AWS'], skills: [{ category: 'L', items: 'Go' }], experience: [] }), []);
  eq('absent fields pass validation', validatePayloadShape({}), []);
  eq('null fields mean "not supplied" and pass validation',
    validatePayloadShape({ skills: null, competencies: null, experience: null }), []);
  eq('a comma-separated competencies string is accepted, not refused',
    validatePayloadShape({ competencies: 'AWS, GCP' }), []);
  eq('and that string still folds into a category',
    foldCompetencies({ competencies: 'AWS, GCP' }).payload.skills[0].items, 'AWS, GCP');

  // Member level (PR #3422, second pass). The reported input: the array
  // container is right, but a member has no scalar value and toItemList() drops
  // it, so the fold emitted `items: "AWS"` and lost the second competency.
  const mixed = { competencies: ['AWS', { name: 'Kubernetes' }] };
  eq('a mixed-type competencies array is refused', validatePayloadShape(mixed).length, 1);
  eq('the error names the offending index and type',
    /\[1\] \(object\)/.test(validatePayloadShape(mixed)[0]), true);
  eq('and that member really was being dropped before the guard',
    foldCompetencies(mixed).payload.skills[0].items, 'AWS');
  eq('a null member is refused too',
    validatePayloadShape({ competencies: ['AWS', null] }).length, 1);
  eq('a nested-array member is refused too',
    validatePayloadShape({ competencies: ['AWS', ['GCP']] }).length, 1);

  // The line is at what is LOST, not at what is non-string. A numeric scalar
  // survives String() with its value intact, and build-cv-html.mjs renders it
  // (tests/cv-numeric-scalars.test.mjs) — rejecting it here would make this
  // script stricter than the builder it feeds.
  eq('a numeric competency is accepted, not refused',
    validatePayloadShape({ competencies: ['AWS', 2024] }), []);
  eq('and it keeps its value through the fold',
    foldCompetencies({ competencies: ['AWS', 2024] }).payload.skills[0].items, 'AWS, 2024');
  eq('a boolean competency is accepted too',
    validatePayloadShape({ competencies: [true] }), []);

  // The same loss in the field the fold writes to, guarded on a fold happening.
  eq('a non-scalar in the merged-into skills category is refused',
    validatePayloadShape({
      competencies: ['A'],
      skills: [{ category: 'Core Competencies', items: ['X', { y: 1 }] }],
    }).length, 1);
  eq('an untouched skills category is not policed for it',
    validatePayloadShape({
      competencies: ['A'],
      skills: [{ category: 'Languages', items: ['X', { y: 1 }] }],
    }), []);
  eq('and neither is it when no fold will happen',
    validatePayloadShape({
      skills: [{ category: 'Core Competencies', items: ['X', { y: 1 }] }],
    }), []);

  // Merge target whose `items` is a scalar (PR #3422, third pass). toItemList()
  // returns [] for it and the merge REPLACES the value — silently overwritten.
  const scalarItems = (items) => ({ competencies: ['A'], skills: [{ category: 'Core Competencies', items }] });
  eq('a numeric items on the merge target is refused', validatePayloadShape(scalarItems(2024)).length, 1);
  eq('a boolean items on the merge target is refused', validatePayloadShape(scalarItems(true)).length, 1);
  eq('an object items on the merge target is refused', validatePayloadShape(scalarItems({ a: 1 })).length, 1);
  eq('the error names the offending type',
    /items` of type number/.test(validatePayloadShape(scalarItems(2024))[0]), true);
  eq('and that value really was being overwritten before the guard',
    foldCompetencies(scalarItems(2024)).payload.skills[0].items, 'A');

  // The container forms the merge can actually carry, and the absent case.
  eq('a string items on the merge target is accepted', validatePayloadShape(scalarItems('X')), []);
  eq('and it merges rather than being replaced',
    foldCompetencies(scalarItems('X')).payload.skills[0].items, 'X, A');
  eq('an array items on the merge target is accepted', validatePayloadShape(scalarItems(['X'])), []);
  eq('an absent items on the merge target is accepted',
    validatePayloadShape({ competencies: ['A'], skills: [{ category: 'Core Competencies' }] }), []);

  // Same rule as before: only the category the fold touches is policed.
  eq('a scalar items on an untouched category is not policed',
    validatePayloadShape({ competencies: ['A'], skills: [{ category: 'Languages', items: 2024 }] }), []);

  // ── The lints ──
  const codes = (p) => lintPayload(p).map((f) => f.code);

  eq('a clean entry produces no findings', codes({
    experience: [{ company: 'Acme', role: 'Senior Engineer', dates: 'June 2022 - Present' }],
  }), []);

  eq('an employer preposition in the role is reported', codes({
    experience: [{ company: 'Consultancy', role: 'Lead Engineer at Globex', dates: '2020 - 2022' }],
  }), ['employer-in-role']);

  eq('a corporate suffix in the role is reported', codes({
    experience: [{ company: 'Consultancy', role: 'Platform Lead, Initech Inc.', dates: '2020 - 2022' }],
  }), ['employer-in-role']);

  eq("another entry's employer appearing in a role is reported", codes({
    experience: [
      { company: 'Globex', role: 'Staff Engineer', dates: '2018 - 2020' },
      { company: 'Consultancy', role: 'Globex Platform Lead', dates: '2020 - 2022' },
    ],
  }), ['employer-in-role']);

  eq('a company substring inside a longer word is not reported', codes({
    experience: [
      { company: 'Acme', role: 'Staff Engineer', dates: '2018 - 2020' },
      { company: 'Consultancy', role: 'Acmerican Studies Lead', dates: '2020 - 2022' },
    ],
  }), []);

  eq('a team named with "for" is not mistaken for an employer', codes({
    experience: [{ company: 'Acme', role: 'Engineer for Payments Platform', dates: '2020 - 2022' }],
  }), []);

  eq('a parenthetical in the company is reported', codes({
    experience: [{ company: 'Globex (Cloud Platform Division)', role: 'Engineer', dates: '2020 - 2022' }],
  }), ['parenthetical-in-company']);

  eq('a full-width parenthetical is reported too', codes({
    experience: [{ company: '日立製作所（クラウド事業部）', role: 'エンジニア', dates: '2020 - 2022' }],
  }), ['parenthetical-in-company']);

  eq('one date range is not reported', countDateRanges('June 2022 - Present'), 1);
  eq('a numeric single range is not reported', countDateRanges('06/2018 - 09/2020'), 1);
  eq('two comma-separated ranges are counted', countDateRanges('2016 - 2019, 2021 - Present'), 2);
  eq('two ranges joined by "and" are counted', countDateRanges('Jan 2016 to Dec 2018 and Mar 2021 until Present'), 2);
  eq('two date ranges in one entry are reported', codes({
    experience: [{ company: 'Acme', role: 'Engineer', dates: '2016 - 2019, 2021 - Present' }],
  }), ['multiple-date-ranges']);

  // The whole contract in one run: exactly one transform, three findings.
  const full = transformPayload({
    competencies: ['RAG Pipelines'],
    experience: [{
      company: 'Globex (Cloud Platform Division)',
      role: 'Lead Engineer at Initech',
      dates: '2016 - 2019, 2021 - Present',
    }],
  });
  eq('one transform applied', full.transform.applied, true);
  eq('three lints reported, none applied', full.findings.map((f) => f.code),
    ['employer-in-role', 'parenthetical-in-company', 'multiple-date-ranges']);
  eq('every finding is advisory', full.findings.every((f) => f.severity === 'review'), true);
  eq('the lints changed nothing in the payload',
    full.payload.experience[0], {
      company: 'Globex (Cloud Platform Division)',
      role: 'Lead Engineer at Initech',
      dates: '2016 - 2019, 2021 - Present',
    });

  console.log(`\nats-payload self-test: ${passed} passed, ${failed} failed`);
  if (failed > 0) process.exit(1);
}

// ── CLI ─────────────────────────────────────────────────────────────────────

const USAGE = `Usage: node ats-payload.mjs <payload.json|-> [--summary] > payload-ats.json
       node ats-payload.mjs --self-test

Applies ONE safe transform and reports THREE lints on a build-cv-html.mjs payload.

  transform  fold competencies[] into skills[] as one comma-delimited category
             under a header ATS parsers recognise (idempotent, reversible)
  lints      employer-in-role · parenthetical-in-company · multiple-date-ranges
             — reported only, because each needs a decision only you can make

The transformed payload goes to STDOUT; findings go to STDERR (JSON by default,
a human summary with --summary). Read-only: nothing is written back to cv.md or
config/profile.yml. Exits 0 whenever the transform succeeded, findings or not.`;

if (isMainModule(import.meta.url)) {
  const args = process.argv.slice(2);
  // `-` is the stdin OPERAND, not a flag. validateFlags() rejects any token
  // starting with `-` that it does not know, so it has to be withheld here —
  // listing it as a known flag instead would print it in the "Valid flags:"
  // line of every typo message, which is where a reader looks for flags.
  validateFlags(args.filter((a) => a !== '-'), ['--summary', '--self-test', '--help', '-h'], USAGE);

  if (args.includes('--self-test')) {
    runSelfTest();
  } else {
    const summaryMode = args.includes('--summary');
    const positional = args.filter((a) => !a.startsWith('-') || a === '-');
    if (positional.length > 1) {
      console.error(`Error: unexpected extra positional argument: ${positional[1]}`);
      console.error(USAGE);
      process.exit(1);
    }

    const source = positional[0] ?? '-';
    let raw;
    try {
      raw = readFileSync(source === '-' ? 0 : source, 'utf-8');
    } catch (err) {
      console.error(`Error: cannot read payload: ${source} (${err.code || err.message})`);
      process.exit(1);
    }

    let payload;
    try {
      payload = JSON.parse(raw);
    } catch (err) {
      console.error(`Error: ${source === '-' ? 'stdin' : source} is not valid JSON (${err.message})`);
      process.exit(1);
    }
    if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
      console.error(`Error: ${source === '-' ? 'stdin' : source} is not a CV payload object`);
      process.exit(1);
    }

    // Before anything is transformed or reported: a payload whose shape would
    // make the run quietly wrong is refused, not accommodated. Nothing reaches
    // stdout, so a shell redirect cannot capture a half-right artifact.
    const shapeErrors = validatePayloadShape(payload);
    if (shapeErrors.length > 0) {
      console.error(`Error: ${source === '-' ? 'stdin' : source} has an unusable payload shape:`);
      for (const message of shapeErrors) console.error(`  - ${message}`);
      process.exit(1);
    }

    const result = transformPayload(payload);
    // stdout is the payload and ONLY the payload, so `> cv-ats.json` is safe and
    // the script composes into a pipe. Everything human goes to stderr.
    console.log(JSON.stringify(result.payload, null, 2));
    if (summaryMode) {
      console.error(formatSummary(result));
    } else {
      console.error(JSON.stringify({ transform: result.transform, findings: result.findings }, null, 2));
    }
  }
}