@codyswann/lisa 2.119.1 → 2.121.0

package/plugins/lisa-agy/scripts/automation-status-contract-drift.mjs

@@ -0,0 +1,392 @@
+#!/usr/bin/env node
+/**
+ * Shared automation-status contract drift helpers.
+ *
+ * Runtime adapters resolve the expected Lisa automation fleet, list the live
+ * scheduler entries, then use this module to find the best observed match for
+ * each expected automation and classify any contract drift.
+ */
+
+const DRIFT_LABELS = {
+  name: "name",
+  cadence: "cadence",
+  command: "command",
+  queue_arguments: "queue arguments",
+};
+
+/**
+ * @typedef {{
+ *   readonly automationId: string
+ *   readonly expectedCadence?: string
+ *   readonly expectedRRule?: string
+ *   readonly expectedCommand: string
+ * }} ExpectedAutomationContract
+ *
+ * @typedef {{
+ *   readonly automationId: string
+ *   readonly observedCadence?: string
+ *   readonly observedRRule?: string
+ *   readonly observedCommand?: string
+ * }} ObservedAutomationContract
+ *
+ * @typedef {{
+ *   readonly status: "HEALTHY" | "MISSING" | "DRIFTED"
+ *   readonly summary: string
+ *   readonly observed: string
+ *   readonly remediation?: string
+ *   readonly driftKinds: readonly ("name" | "cadence" | "command" | "queue_arguments")[]
+ *   readonly observedAutomation: ObservedAutomationContract | null
+ * }} AutomationContractComparison
+ */
+
+/**
+ * Compare the expected automation fleet against observed scheduler entries,
+ * consuming each observed automation at most once.
+ *
+ * @param {{
+ *   readonly expectedAutomations: readonly ExpectedAutomationContract[]
+ *   readonly observedAutomations?: readonly ObservedAutomationContract[]
+ * }} input
+ * @returns {readonly AutomationContractComparison[]}
+ */
+export function compareAutomationFleet(input) {
+  const remainingObserved = [...(input.observedAutomations ?? [])];
+
+  return input.expectedAutomations.map(expected => {
+    const observed = findObservedAutomationMatch(
+      expected,
+      remainingObserved,
+      input.expectedAutomations
+    );
+    const comparison = compareAutomationContract({
+      expected,
+      observedAutomation: observed,
+    });
+
+    if (observed) {
+      const index = remainingObserved.indexOf(observed);
+      if (index >= 0) {
+        remainingObserved.splice(index, 1);
+      }
+    }
+
+    return comparison;
+  });
+}
+
+/**
+ * Find the best observed scheduler entry for an expected automation contract.
+ *
+ * Match order is:
+ * 1. Exact automation id
+ * 2. Exact command shape and cadence
+ * 3. Exact command shape
+ * 4. Same command entrypoint
+ *
+ * @param {ExpectedAutomationContract} expected
+ * @param {readonly ObservedAutomationContract[]} observedAutomations
+ * @param {readonly ExpectedAutomationContract[]} expectedAutomations
+ * @returns {ObservedAutomationContract | null}
+ */
+export function findObservedAutomationMatch(
+  expected,
+  observedAutomations = [],
+  expectedAutomations = [expected]
+) {
+  const exactId = observedAutomations.find(
+    observed => observed.automationId === expected.automationId
+  );
+  if (exactId) {
+    return exactId;
+  }
+
+  const expectedCommand = normalizeAutomationCommand(expected.expectedCommand);
+  const expectedCadence = normalizeCadenceSignature({
+    cadence: expected.expectedCadence,
+    rrule: expected.expectedRRule,
+  });
+
+  const exactContract = observedAutomations.find(observed => {
+    const observedCommand = normalizeAutomationCommand(
+      observed.observedCommand
+    );
+    const observedCadence = normalizeCadenceSignature({
+      cadence: observed.observedCadence,
+      rrule: observed.observedRRule,
+    });
+
+    return (
+      observedCommand.commandSignature === expectedCommand.commandSignature &&
+      observedCadence === expectedCadence
+    );
+  });
+  if (exactContract) {
+    return exactContract;
+  }
+
+  const exactCommand = observedAutomations.find(observed => {
+    const observedCommand = normalizeAutomationCommand(
+      observed.observedCommand
+    );
+    return (
+      observedCommand.commandSignature === expectedCommand.commandSignature
+    );
+  });
+  if (exactCommand) {
+    return exactCommand;
+  }
+
+  if (
+    isSharedExpectedCommandToken(
+      expectedCommand.commandToken,
+      expectedAutomations
+    )
+  ) {
+    return null;
+  }
+
+  return (
+    observedAutomations.find(observed => {
+      const observedCommand = normalizeAutomationCommand(
+        observed.observedCommand
+      );
+      return observedCommand.commandToken === expectedCommand.commandToken;
+    }) ?? null
+  );
+}
+
+/**
+ * Compare one expected automation contract against an observed scheduler entry.
+ *
+ * @param {{
+ *   readonly expected: ExpectedAutomationContract
+ *   readonly observedAutomations?: readonly ObservedAutomationContract[]
+ *   readonly observedAutomation?: ObservedAutomationContract | null
+ * }} input
+ * @returns {AutomationContractComparison}
+ */
+export function compareAutomationContract(input) {
+  const expected = input.expected;
+  const observed =
+    input.observedAutomation ??
+    findObservedAutomationMatch(expected, input.observedAutomations ?? []);
+
+  if (!observed) {
+    return {
+      status: "MISSING",
+      summary: "expected automation is missing",
+      observed: "No live automation matched the expected Lisa contract.",
+      remediation:
+        "Re-run `/lisa:setup-automations` or recreate the missing scheduler entry.",
+      driftKinds: [],
+      observedAutomation: null,
+    };
+  }
+
+  const driftKinds = detectDriftKinds(expected, observed);
+  const observedSummary = describeObservedAutomation(observed);
+
+  if (driftKinds.length === 0) {
+    return {
+      status: "HEALTHY",
+      summary: "expected automation exists and matches the contract",
+      observed: observedSummary,
+      driftKinds,
+      observedAutomation: observed,
+    };
+  }
+
+  return {
+    status: "DRIFTED",
+    summary: formatDriftSummary(driftKinds),
+    observed: observedSummary,
+    remediation:
+      "Re-run `/lisa:setup-automations` or update the scheduler entry to the expected command and cadence.",
+    driftKinds,
+    observedAutomation: observed,
+  };
+}
+
+/**
+ * @param {string} commandToken
+ * @param {readonly ExpectedAutomationContract[]} expectedAutomations
+ * @returns {boolean}
+ */
+function isSharedExpectedCommandToken(commandToken, expectedAutomations) {
+  if (!commandToken) {
+    return false;
+  }
+
+  return (
+    expectedAutomations.filter(expected => {
+      const normalized = normalizeAutomationCommand(expected.expectedCommand);
+      return normalized.commandToken === commandToken;
+    }).length > 1
+  );
+}
+
+/**
+ * @param {ExpectedAutomationContract} expected
+ * @param {ObservedAutomationContract} observed
+ * @returns {readonly ("name" | "cadence" | "command" | "queue_arguments")[]}
+ */
+function detectDriftKinds(expected, observed) {
+  const driftKinds = [];
+
+  if (observed.automationId !== expected.automationId) {
+    driftKinds.push("name");
+  }
+
+  const expectedCadence = normalizeCadenceSignature({
+    cadence: expected.expectedCadence,
+    rrule: expected.expectedRRule,
+  });
+  const observedCadence = normalizeCadenceSignature({
+    cadence: observed.observedCadence,
+    rrule: observed.observedRRule,
+  });
+
+  if (expectedCadence !== observedCadence) {
+    driftKinds.push("cadence");
+  }
+
+  const expectedCommand = normalizeAutomationCommand(expected.expectedCommand);
+  const observedCommand = normalizeAutomationCommand(observed.observedCommand);
+
+  if (expectedCommand.commandToken !== observedCommand.commandToken) {
+    driftKinds.push("command");
+  }
+
+  if (expectedCommand.queueSignature !== observedCommand.queueSignature) {
+    driftKinds.push("queue_arguments");
+  }
+
+  return driftKinds;
+}
+
+/**
+ * @param {ObservedAutomationContract} observed
+ * @returns {string}
+ */
+function describeObservedAutomation(observed) {
+  const name = observed.automationId || "unnamed automation";
+  const cadence =
+    observed.observedCadence ?? observed.observedRRule ?? "cadence unavailable";
+  const command = observed.observedCommand ?? "command unavailable";
+  return `${name} runs ${cadence} -> ${command}`;
+}
+
+/**
+ * @param {readonly ("name" | "cadence" | "command" | "queue_arguments")[]} driftKinds
+ * @returns {string}
+ */
+function formatDriftKinds(driftKinds) {
+  const labels = driftKinds.map(kind => DRIFT_LABELS[kind]);
+  if (labels.length === 0) {
+    return "contract details";
+  }
+  if (labels.length === 1) {
+    return labels[0];
+  }
+  if (labels.length === 2) {
+    return `${labels[0]} and ${labels[1]}`;
+  }
+  return `${labels.slice(0, -1).join(", ")}, and ${labels.at(-1)}`;
+}
+
+/**
+ * @param {readonly ("name" | "cadence" | "command" | "queue_arguments")[]} driftKinds
+ * @returns {string}
+ */
+function formatDriftSummary(driftKinds) {
+  const subject = formatDriftKinds(driftKinds);
+  return driftKinds.length === 1
+    ? `${subject} no longer matches setup`
+    : `${subject} no longer match setup`;
+}
+
+/**
+ * @param {string | undefined} command
+ * @returns {{ readonly commandToken: string, readonly commandSignature: string, readonly queueSignature: string }}
+ */
+function normalizeAutomationCommand(command) {
+  const tokens = tokenizeCommand(command);
+  const [commandToken = "", ...queueTokens] = tokens;
+
+  return {
+    commandToken,
+    commandSignature: serializeCommandTokens(tokens),
+    queueSignature: serializeQueueTokens(queueTokens),
+  };
+}
+
+/**
+ * @param {{ readonly cadence?: string, readonly rrule?: string }} input
+ * @returns {string}
+ */
+function normalizeCadenceSignature(input) {
+  if (typeof input.rrule === "string" && input.rrule.trim().length > 0) {
+    return input.rrule.trim().toUpperCase();
+  }
+
+  if (typeof input.cadence === "string" && input.cadence.trim().length > 0) {
+    return input.cadence.trim().toLowerCase().replace(/\s+/g, " ");
+  }
+
+  return "";
+}
+
+/**
+ * @param {readonly string[]} tokens
+ * @returns {string}
+ */
+function serializeCommandTokens(tokens) {
+  return tokens.join("\u0000");
+}
+
+/**
+ * Positional queue args stay ordered, while key=value arguments are sorted by
+ * key so semantically-equivalent scheduler strings do not false-positive.
+ *
+ * @param {readonly string[]} queueTokens
+ * @returns {string}
+ */
+function serializeQueueTokens(queueTokens) {
+  const positional = [];
+  const keyed = [];
+
+  for (const token of queueTokens) {
+    if (token.includes("=")) {
+      const [key, ...valueParts] = token.split("=");
+      keyed.push(`${key}=${valueParts.join("=")}`);
+      continue;
+    }
+    positional.push(token);
+  }
+
+  keyed.sort((left, right) => left.localeCompare(right));
+  return [...positional, ...keyed].join("\u0000");
+}
+
+/**
+ * Tokenize simple scheduler commands while preserving quoted values.
+ *
+ * @param {string | undefined} command
+ * @returns {readonly string[]}
+ */
+function tokenizeCommand(command) {
+  if (typeof command !== "string" || command.trim().length === 0) {
+    return [];
+  }
+
+  const tokens = [];
+  const pattern = /"([^"]*)"|'([^']*)'|[^\s]+/g;
+  let match = pattern.exec(command);
+
+  while (match) {
+    tokens.push(match[1] ?? match[2] ?? match[0]);
+    match = pattern.exec(command);
+  }
+
+  return tokens;
+}

package/plugins/lisa-agy/scripts/automation-status-expected-fleet.mjs

@@ -0,0 +1,319 @@
+#!/usr/bin/env node
+/**
+ * Shared automation-status expected-fleet helpers.
+ *
+ * This module resolves the same naming, queue arguments, cadence, and
+ * exploratory support decisions documented by `/lisa:setup-automations`, so
+ * automation-status and later runtime adapters do not invent a second source of
+ * truth.
+ */
+
+import {
+  resolveBuildQueueArgument,
+  resolveGithubRepoRef,
+  resolvePrdQueueArgument,
+  resolvePrdSource,
+} from "./queue-contract-resolution.mjs";
+
+export const AUTOMATION_EXPECTED_CADENCES = {
+  "intake-repair": {
+    human: "every 60 minutes",
+    rrule: "FREQ=HOURLY;INTERVAL=1",
+  },
+  "intake-prd": {
+    human: "every 60 minutes",
+    rrule: "FREQ=HOURLY;INTERVAL=1",
+  },
+  "intake-tickets": {
+    human: "every 10 minutes",
+    rrule: "FREQ=MINUTELY;INTERVAL=10",
+  },
+  "exploratory-bugs": {
+    human: "once a day",
+    rrule: "FREQ=DAILY;INTERVAL=1",
+  },
+  "exploratory-prds": {
+    human: "once a day",
+    rrule: "FREQ=DAILY;INTERVAL=1",
+  },
+};
+
+export const EXPLORATORY_QA_STACK_PRIORITY = ["expo", "rails", "harper-fabric"];
+
+/**
+ * @typedef {{
+ *   readonly id: string
+ *   readonly automationId: string
+ *   readonly expectedCadence: string
+ *   readonly expectedRRule: string
+ *   readonly expectedCommand: string
+ *   readonly group: "core" | "exploratory"
+ * }} ExpectedAutomationEntry
+ *
+ * @typedef {{
+ *   readonly id: string
+ *   readonly automationId: string
+ *   readonly group: "core" | "exploratory"
+ *   readonly reason: string
+ *   readonly expectedCadence: string
+ *   readonly expectedRRule: string
+ * }} UnsupportedAutomationEntry
+ */
+
+/**
+ * Resolve the stable project identifier and automation prefix used by
+ * `/lisa:setup-automations`.
+ *
+ * @param {{
+ *   readonly config?: Record<string, any>
+ *   readonly gitRemoteUrl?: string
+ * }} input
+ * @returns {{ readonly owner: string, readonly repo: string, readonly project: string, readonly automationPrefix: string }}
+ */
+export function resolveAutomationProjectIdentity(input = {}) {
+  const githubRef = resolveGithubRepoRef(
+    input.config ?? {},
+    input.gitRemoteUrl
+  );
+
+  if (!githubRef) {
+    throw new Error(
+      "Unable to resolve repo identity for automation naming. Configure github.org/github.repo or provide a GitHub origin remote."
+    );
+  }
+
+  const project = slugifyProjectToken(`${githubRef.owner}-${githubRef.repo}`);
+
+  return {
+    ...githubRef,
+    project,
+    automationPrefix: `lisa-auto-${project}-`,
+  };
+}
+
+/**
+ * Resolve the expected Lisa automation fleet for the current repo.
+ *
+ * @param {{
+ *   readonly config?: Record<string, any>
+ *   readonly gitRemoteUrl?: string
+ *   readonly detectedTypes?: readonly string[]
+ *   readonly autoStartPrds?: boolean | string
+ *   readonly autoStartTickets?: boolean | string
+ * }} input
+ * @returns {{
+ *   readonly owner: string
+ *   readonly repo: string
+ *   readonly project: string
+ *   readonly automationPrefix: string
+ *   readonly expected: readonly ExpectedAutomationEntry[]
+ *   readonly unsupported: readonly UnsupportedAutomationEntry[]
+ * }}
+ */
+export function resolveExpectedAutomationFleet(input = {}) {
+  const config = input.config ?? {};
+  const identity = resolveAutomationProjectIdentity(input);
+  const autoStartPrds = normalizeBooleanFlag(input.autoStartPrds);
+  const autoStartTickets = normalizeBooleanFlag(input.autoStartTickets);
+  const detectedTypes = input.detectedTypes ?? [];
+
+  const tracker = config.tracker;
+  const source = resolvePrdSource(config);
+  const prdQueue = resolvePrdQueueArgument(config, source);
+  const buildQueue = resolveBuildQueueArgument(config, tracker);
+  const repairQueue = resolveRepairQueueArgument(config, source, tracker);
+
+  const expected = [
+    createExpectedEntry(
+      identity,
+      "intake-repair",
+      `/lisa:repair-intake ${repairQueue}`,
+      "core"
+    ),
+    createExpectedEntry(
+      identity,
+      "intake-prd",
+      `/lisa:intake ${prdQueue}`,
+      "core"
+    ),
+    createExpectedEntry(
+      identity,
+      "intake-tickets",
+      `/lisa:intake ${buildQueue}`,
+      "core"
+    ),
+    createExpectedEntry(
+      identity,
+      "exploratory-prds",
+      `/lisa:project-ideation prd_ready=${String(autoStartPrds)}`,
+      "exploratory"
+    ),
+  ];
+
+  const exploratoryStack = resolveExploratoryQaStack(detectedTypes);
+  const unsupported = [];
+
+  if (exploratoryStack) {
+    expected.push(
+      createExpectedEntry(
+        identity,
+        "exploratory-bugs",
+        `/lisa-${exploratoryStack}:exploratory-qa ready=${String(autoStartTickets)}`,
+        "exploratory"
+      )
+    );
+  } else {
+    unsupported.push(
+      createUnsupportedEntry(
+        identity,
+        "exploratory-bugs",
+        "This repository does not ship an exploratory-qa command surface."
+      )
+    );
+  }
+
+  return {
+    ...identity,
+    expected,
+    unsupported,
+  };
+}
+
+/**
+ * Return the supported exploratory-qa surface for the detected host stacks.
+ *
+ * @param {readonly string[]} detectedTypes
+ * @returns {string | null}
+ */
+export function resolveExploratoryQaStack(detectedTypes = []) {
+  for (const stack of EXPLORATORY_QA_STACK_PRIORITY) {
+    if (detectedTypes.includes(stack)) {
+      return stack;
+    }
+  }
+  return null;
+}
+
+/**
+ * @param {{ readonly automationPrefix: string }} identity
+ * @param {string} id
+ * @param {string} expectedCommand
+ * @param {"core" | "exploratory"} group
+ * @returns {ExpectedAutomationEntry}
+ */
+function createExpectedEntry(identity, id, expectedCommand, group) {
+  const cadence = AUTOMATION_EXPECTED_CADENCES[id];
+  return {
+    id,
+    automationId: `${identity.automationPrefix}${id}`,
+    expectedCadence: cadence.human,
+    expectedRRule: cadence.rrule,
+    expectedCommand,
+    group,
+  };
+}
+
+/**
+ * @param {{ readonly automationPrefix: string }} identity
+ * @param {string} id
+ * @param {string} reason
+ * @returns {UnsupportedAutomationEntry}
+ */
+function createUnsupportedEntry(identity, id, reason) {
+  const cadence = AUTOMATION_EXPECTED_CADENCES[id];
+  return {
+    id,
+    automationId: `${identity.automationPrefix}${id}`,
+    expectedCadence: cadence.human,
+    expectedRRule: cadence.rrule,
+    group: "exploratory",
+    reason,
+  };
+}
+
+/**
+ * @param {Record<string, any>} config
+ * @param {string | undefined} source
+ * @param {string | undefined} tracker
+ * @returns {string}
+ */
+function resolveRepairQueueArgument(config, source, tracker) {
+  if (tracker === "github" && source === "github") {
+    requireGithubRepo(config);
+    return "github intake_mode=both";
+  }
+
+  if (tracker === "linear" && source === "linear") {
+    requireLinearWorkspace(config);
+    return "linear";
+  }
+
+  if (tracker === "jira" && source === "jira") {
+    const project = config.jira?.project;
+    if (!project) {
+      throw new Error(
+        "Unable to resolve the repair queue: jira.project is required when tracker=jira and source=jira."
+      );
+    }
+    return project;
+  }
+
+  if (tracker === "github" && source === undefined) {
+    requireGithubRepo(config);
+    return "github intake_mode=both";
+  }
+
+  throw new Error(
+    `Unable to resolve a single repair-intake queue for tracker=${String(tracker)} and source=${String(source)} without guessing.`
+  );
+}
+
+/**
+ * @param {Record<string, any>} config
+ */
+function requireGithubRepo(config) {
+  if (!config.github?.org || !config.github?.repo) {
+    throw new Error(
+      "Unable to resolve the GitHub queue: github.org and github.repo are required."
+    );
+  }
+}
+
+/**
+ * @param {Record<string, any>} config
+ */
+function requireLinearWorkspace(config) {
+  if (!config.linear?.workspace) {
+    throw new Error(
+      "Unable to resolve the Linear queue: linear.workspace is required."
+    );
+  }
+}
+
+/**
+ * @param {boolean | string | undefined} value
+ * @returns {boolean}
+ */
+function normalizeBooleanFlag(value) {
+  if (typeof value === "boolean") {
+    return value;
+  }
+
+  if (typeof value === "string") {
+    return value.toLowerCase() === "true";
+  }
+
+  return false;
+}
+
+/**
+ * @param {string} value
+ * @returns {string}
+ */
+function slugifyProjectToken(value) {
+  return value
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}