@enricai/barnacle 1.3.0 → 1.4.1

package/dist/scripts/recon-generate.js

@@ -19,6 +19,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveStepPayloadField = resolveStepPayloadField;
 exports.inferZodSchemaFromSamples = inferZodSchemaFromSamples;
+exports.selectPayloadAction = selectPayloadAction;
 exports.loadQuestionPromptKeywords = loadQuestionPromptKeywords;
 exports.emitMultiStepExecuteHttp = emitMultiStepExecuteHttp;
 exports.emitContractTs = emitContractTs;
@@ -29,6 +30,8 @@ const node_path_1 = require("node:path");
 const errors_1 = require("../lib/errors");
 const logging_1 = require("../lib/logging");
 const plugin_manifest_envelope_1 = require("../plugins/plugin-manifest-envelope");
+const load_vocabulary_1 = require("../recon/load-vocabulary");
+const vocabulary_1 = require("../recon/vocabulary");
 const recon_shared_1 = require("../scripts/recon-shared");
 const logger = (0, logging_1.getScriptLogger)("recon-generate");
 // ── helpers ──────────────────────────────────────────────────────────────────
@@ -39,46 +42,52 @@ function toPascalCase(siteId) {
         .join("");
 }
 /**
- * Instruction labels that name a NON-candidate field — a reference-contact, an
- * employment-history row, the applicant's signature, etc. When any of these
- * matches we leave the step literal so the generator never splices the primary
- * applicant's PII into a field that must hold someone/something else. Matched
- * against the English label in the instruction, never the recon constant value.
- */
-const PAYLOAD_FIELD_EXCLUSIONS = [
-    /reference\s*#?\s*\d/i,
-    /employment history/i,
-    /\bcompany (name|phone)\b/i,
-    /\bemployer\b/i,
-    /signature/i,
-    /\bfull name\b/i,
-    /today'?s date/i,
-    /school|institution|degree|major|education/i,
-    // Screening-question shapes: "For '<question>' select '<answer>'" and any
-    // step framed around a 'question'. Here the first quoted string is the
-    // question label, not a candidate value — a label word inside the question
-    // (e.g. "...licensed in this state?") must NOT trigger a splice that would
-    // overwrite the question quote. Candidate-fill steps say "fill in the X
-    // field with '...'" / "Select '...' from the X dropdown" instead.
-    /^\s*for\s+'/i,
-    /\bquestion\b/i,
-];
-/**
- * Ordered candidate-field label table. Each entry maps an English-label regex
- * to the PascalCase payload field the generator should splice. Order matters:
- * the first matching row wins, so more-specific labels precede broader ones.
+ * The recruiting vocabulary the engine used to hardcode, kept only so consumers
+ * who have not yet passed `--vocabulary` keep working through the 1.x line.
+ *
+ * @deprecated Pass `--vocabulary <specifier>` instead. The engine cannot know
+ * what any site's forms mean, and guessing mis-fires on every non-recruiting
+ * domain (a cruise site's "Select the departure port from the Country dropdown"
+ * became `${payload.Country}`). Slated for deletion in 2.0.0, after which an
+ * absent vocabulary on a spliceable flow is a hard error. See `src/recon/vocabulary.ts`.
  */
-const PAYLOAD_FIELD_TABLE = [
-    [/\bfirst name\b/i, "FirstName"],
-    [/\blast name\b/i, "LastName"],
-    [/\b(e-?mail|email address)\b/i, "Email"],
-    [/\b(mobile phone|primary phone|phone number|mobile)\b/i, "MobilePhone"],
-    [/\b(street address|address line 1)\b/i, "AddressLine1"],
-    [/\bcity\b/i, "City"],
-    [/\b(state|province|state\/region)\b/i, "State"],
-    [/\b(zip|postal)\b/i, "PostalCode"],
-    [/\bcountry\b/i, "Country"],
-];
+const DEPRECATED_BUILTIN_ATS_VOCABULARY = {
+    // Naming the subject is what separates "…select the test candidate's state"
+    // (fill with the caller's data) from "…the departure port from the Country
+    // dropdown" (a search facet that merely says Country).
+    subject: /\b(the\s+)?(test\s+)?(candidate|applicant)'?s\b/i,
+    exclusions: [
+        /reference\s*#?\s*\d/i,
+        /employment history/i,
+        /\bcompany (name|phone)\b/i,
+        /\bemployer\b/i,
+        /signature/i,
+        /\bfull name\b/i,
+        /today'?s date/i,
+        /school|institution|degree|major|education/i,
+        // Screening-question shapes: "For '<question>' select '<answer>'" and any
+        // step framed around a 'question'. Here the first quoted string is the
+        // question label, not a candidate value — a label word inside the question
+        // (e.g. "...licensed in this state?") must NOT trigger a splice that would
+        // overwrite the question quote. Candidate-fill steps say "fill in the X
+        // field with '...'" / "Select '...' from the X dropdown" instead.
+        /^\s*for\s+'/i,
+        /\bquestion\b/i,
+        // A secondary phone must not fill the primary MobilePhone field.
+        /\bsecondary\b[^.]*\bphone\b/i,
+    ],
+    table: [
+        [/\bfirst name\b/i, "FirstName"],
+        [/\blast name\b/i, "LastName"],
+        [/\b(e-?mail|email address)\b/i, "Email"],
+        [/\b(mobile phone|primary phone|phone number|mobile)\b/i, "MobilePhone"],
+        [/\b(street address|address line 1)\b/i, "AddressLine1"],
+        [/\bcity\b/i, "City"],
+        [/\b(state|province|state\/region)\b/i, "State"],
+        [/\b(zip|postal)\b/i, "PostalCode"],
+        [/\bcountry\b/i, "Country"],
+    ],
+};
 /**
  * Decide whether a flow step should splice a runtime `payload.<field>` value in
  * place of the frozen recon constant baked into its instruction. Exists so
@@ -91,27 +100,29 @@ const PAYLOAD_FIELD_TABLE = [
  * @param instruction the flow step's plain-English instruction
  * @param explicit an optional flow-authored `payloadField` override (wins outright)
  * @param forceNone when true, force a literal step (the `payloadFieldNone` opt-out)
+ * @param vocabulary the consumer's domain vocabulary; defaults to the deprecated
+ *   built-in recruiting table so 1.x consumers who pass nothing keep working
  * @returns the PascalCase payload field name to splice, or null to keep literal
  */
-function resolveStepPayloadField(instruction, explicit, forceNone) {
+function resolveStepPayloadField(instruction, explicit, forceNone, vocabulary = DEPRECATED_BUILTIN_ATS_VOCABULARY) {
     if (forceNone)
         return null;
     if (explicit)
         return explicit;
-    // Nothing to splice unless the instruction actually carries a recon constant:
-    // a quoted literal, the ${RECON_EMAIL} token, or a dropdown/select phrasing.
-    const hasSpliceable = /'[^']*'/.test(instruction) ||
-        /\$\{RECON_EMAIL\}/.test(instruction) ||
-        /\bdropdown\b/i.test(instruction) ||
-        /\bselect\b[^.]*\bfrom\b/i.test(instruction);
+    // A quoted literal or ${RECON_EMAIL} IS the recon constant this step would
+    // replace, so it is spliceable on its own.
+    const hasQuotedConstant = /'[^']*'/.test(instruction) || /\$\{RECON_EMAIL\}/.test(instruction);
+    // A dropdown step carries no constant to replace, so a label match alone can't
+    // tell "select the test candidate's state" (the caller's data) from "select the
+    // departure port from the Country dropdown" (a facet that merely says Country).
+    // Requiring the subject is what keeps this from mis-firing off-domain.
+    const isDropdownStep = /\bdropdown\b/i.test(instruction) || /\bselect\b[^.]*\bfrom\b/i.test(instruction);
+    const hasSpliceable = hasQuotedConstant || (isDropdownStep && vocabulary.subject.test(instruction));
     if (!hasSpliceable)
         return null;
-    if (PAYLOAD_FIELD_EXCLUSIONS.some((rx) => rx.test(instruction)))
-        return null;
-    // "Secondary Phone Number" must not fill the primary MobilePhone field.
-    if (/\bsecondary\b/i.test(instruction) && /\bphone\b/i.test(instruction))
+    if (vocabulary.exclusions.some((rx) => rx.test(instruction)))
         return null;
-    for (const [rx, field] of PAYLOAD_FIELD_TABLE) {
+    for (const [rx, field] of vocabulary.table) {
         if (rx.test(instruction))
             return field;
     }
@@ -223,6 +234,54 @@ function endpointKey(url) {
         return url;
     }
 }
+/** Empty or absent response bodies carry no evidence of an endpoint's purpose. */
+function isVoidResponse(body) {
+    if (body === null || body === undefined || body === "")
+        return true;
+    if (typeof body !== "object")
+        return false;
+    if (Array.isArray(body))
+        return body.length === 0;
+    return Object.keys(body).length === 0;
+}
+/**
+ * Picks the action whose request body should define the payload schema.
+ *
+ * Defaults to the first action, which is right for a transactional flow: the
+ * caller's data goes in with the opening POST and later steps only carry the
+ * transaction forward. It is wrong when the flow's real subject is a query the
+ * page issues repeatedly — a search or inventory endpoint is re-hit on every
+ * filter change, while whatever happened to fire first was incidental (a
+ * feature-toggle fetch, a config read). Re-issuing the same endpoint with a
+ * different body is the signature of the parameters a caller would want to
+ * control, so that wins. Anything less clear-cut falls through to first-action
+ * behavior rather than guessing.
+ *
+ * A transactional flow can re-issue an endpoint too — an applicant record built
+ * up across several writes — and lands on those writes for the same reason: the
+ * call that merely opened the flow carries none of the caller's fields.
+ */
+function selectPayloadAction(steps) {
+    const first = steps[0];
+    if (!first)
+        return null;
+    const bodiesByEndpoint = new Map();
+    for (const step of steps) {
+        const key = endpointKey(step.capture.url);
+        const bodies = bodiesByEndpoint.get(key) ?? new Set();
+        bodies.add(step.capture.requestPostData ?? "");
+        bodiesByEndpoint.set(key, bodies);
+    }
+    const requeried = steps.filter((step) => {
+        const bodies = bodiesByEndpoint.get(endpointKey(step.capture.url));
+        if (!bodies || bodies.size < 2)
+            return false;
+        // An endpoint re-hit with varying bodies but nothing to show for it is
+        // chatter — client-side error reporting, beacons — not the flow's subject.
+        return !isVoidResponse(step.capture.responseBody);
+    });
+    return requeried[0] ?? first;
+}
 function deriveBaseUrl(captures) {
     for (const c of captures) {
         try {
@@ -2113,12 +2172,12 @@ function buildManifestInstruction(instruction, field) {
  * omitted; a site that needs it keeps the `.ts` path or wires `spec.httpModule`.
  */
 function emitConfigManifest(opts) {
-    const { siteId, displayName, baseUrl, flowSteps } = opts;
+    const { siteId, displayName, baseUrl, flowSteps, vocabulary } = opts;
     const payloadFieldNames = new Set();
     const steps = flowSteps.map((step) => {
         const isObj = typeof step !== "string";
         const instruction = isObj ? step.step : step;
-        const field = resolveStepPayloadField(instruction, isObj ? step.payloadField : undefined, isObj ? step.payloadFieldNone : undefined);
+        const field = resolveStepPayloadField(instruction, isObj ? step.payloadField : undefined, isObj ? step.payloadFieldNone : undefined, vocabulary);
         if (field !== null)
             payloadFieldNames.add(field);
         const rewritten = buildManifestInstruction(instruction, field);
@@ -2162,13 +2221,13 @@ function emitConfigManifest(opts) {
  * payload schema (both are driven by this same set).
  */
 function emitBrowserFlowTs(opts) {
-    const { siteId, pascal, flowSteps, isSubmissionFlow, hasMultipartStep = false } = opts;
+    const { siteId, pascal, flowSteps, isSubmissionFlow, hasMultipartStep = false, vocabulary, } = opts;
     const payloadFieldNames = new Set();
     const hasUploadStep = flowSteps.some((s) => typeof s !== "string" && s.upload === true);
     const stepLiterals = flowSteps.map((step) => {
         const isObj = typeof step !== "string";
         const instruction = isObj ? step.step : step;
-        const field = resolveStepPayloadField(instruction, isObj ? step.payloadField : undefined, isObj ? step.payloadFieldNone : undefined);
+        const field = resolveStepPayloadField(instruction, isObj ? step.payloadField : undefined, isObj ? step.payloadFieldNone : undefined, vocabulary);
         if (field !== null)
             payloadFieldNames.add(field);
         const instructionExpr = buildStepInstructionExpr(instruction, field);
@@ -2289,14 +2348,51 @@ export { ${camel}Plugin } from "@/sites/${siteId}/contract";
 `;
 }
 // ── main ──────────────────────────────────────────────────────────────────────
+/**
+ * Resolves the vocabulary for this run and reports which one is in play.
+ *
+ * The deprecation warning is the whole point of the 1.x window: removing a
+ * built-in default that consumers silently depend on is only safe if the
+ * transition is loud. It fires only when the built-in would actually change the
+ * output — a flow with nothing to splice gets no nag it can't act on.
+ */
+async function resolveVocabulary(specifier, flowSteps) {
+    if (specifier) {
+        const vocabulary = await (0, load_vocabulary_1.loadReconVocabulary)(specifier, process.cwd());
+        logger.info(`vocabulary: ${specifier === load_vocabulary_1.VOCABULARY_NONE ? "none (splicing disabled)" : `${vocabulary.table.length} row(s) from ${specifier}`}`);
+        return vocabulary;
+    }
+    // Warn only when the built-in table itself changes the outcome. A step with an
+    // explicit payloadField resolves the same under any vocabulary, so nagging
+    // about it would send consumers to fix something that isn't broken.
+    const builtinChangesOutcome = flowSteps.some((step) => {
+        const isObj = typeof step !== "string";
+        const instruction = isObj ? step.step : step;
+        const explicit = isObj ? step.payloadField : undefined;
+        const forceNone = isObj ? step.payloadFieldNone : undefined;
+        const withBuiltin = resolveStepPayloadField(instruction, explicit, forceNone, DEPRECATED_BUILTIN_ATS_VOCABULARY);
+        const withNothing = resolveStepPayloadField(instruction, explicit, forceNone, vocabulary_1.EMPTY_VOCABULARY);
+        return withBuiltin !== withNothing;
+    });
+    if (builtinChangesOutcome) {
+        logger.warn(`DeprecationWarning: no --vocabulary given, falling back to the built-in recruiting table. ` +
+            `It is removed in 2.0.0, after which this is an error. Fix: create a vocabulary module ` +
+            `exporting a ReconVocabulary (see @enricai/barnacle/recon/vocabulary) and pass ` +
+            `--vocabulary ./src/recon/<name>.ts, or --vocabulary none if this site splices no caller data.`);
+    }
+    return DEPRECATED_BUILTIN_ATS_VOCABULARY;
+}
 async function main() {
     const args = process.argv.slice(2);
     let siteId = "";
     let force = false;
     let emit = "ts";
+    let vocabularySpecifier = "";
     for (let i = 0; i < args.length; i++) {
         if (args[i] === "--site-id" && args[i + 1])
             siteId = args[++i];
+        else if (args[i] === "--vocabulary" && args[i + 1])
+            vocabularySpecifier = args[++i];
         else if (args[i] === "--force")
             force = true;
         else if (args[i] === "--emit" && args[i + 1]) {
@@ -2363,6 +2459,10 @@ async function main() {
             return [];
         }
     })();
+    // Resolved once and threaded down, never captured into a module const: a
+    // module-level const would freeze at import time, which is the bug that makes
+    // RECON_QUESTION_KEYWORDS silently inert for anyone setting it after load.
+    const vocabulary = await resolveVocabulary(vocabularySpecifier, flowSteps);
     const pascal = toPascalCase(siteId);
     const baseUrl = deriveBaseUrl(captures);
     const baseHeaders = deriveRequestHeaders(captures, replays, baseUrl);
@@ -2426,7 +2526,8 @@ async function main() {
     const inputBody = isSubmissionFlow
         ? (() => {
             try {
-                return JSON.parse(actionSteps[0].capture.requestPostData ?? "null");
+                const payloadAction = selectPayloadAction(actionSteps);
+                return JSON.parse(payloadAction?.capture.requestPostData ?? "null");
             }
             catch {
                 return null;
@@ -2582,6 +2683,7 @@ async function main() {
             displayName: pascal,
             baseUrl,
             flowSteps,
+            vocabulary,
         }));
         logger.info(`wrote ${manifestPath}`);
         logger.info(`done — review ${manifestPath}, fill in response/extract schemas, then load via BARNACLE_PLUGINS or BARNACLE_PLUGINS_CONFIG_DIR (no compile step)`);
@@ -2598,6 +2700,7 @@ async function main() {
         flowSteps,
         isSubmissionFlow,
         hasMultipartStep,
+        vocabulary,
     });
     (0, node_fs_1.writeFileSync)(`${outDir}/contract.ts`, emitContractTs({
         siteId,