pumuki 6.3.44 → 6.3.46

package/scripts/watch-consumer-backlog-fleet-tick.ts

@@ -0,0 +1,225 @@
+import { randomUUID } from 'node:crypto';
+import { existsSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { resolve } from 'node:path';
+import {
+  buildWatchActionRequiredReasons,
+  formatActionReasonsForHuman,
+} from './backlog-action-reasons-lib';
+import {
+  BACKLOG_JSON_COMPAT_CONTRACT_ID,
+  BACKLOG_JSON_COMPAT_MIN_READER_VERSION,
+  BACKLOG_JSON_SCHEMA_VERSION,
+} from './backlog-json-contract-lib';
+import { runBacklogWatch } from './watch-consumer-backlog-lib';
+
+type FleetTarget = {
+  key: 'saas' | 'ruralgo' | 'flux';
+  filePath: string;
+  repo?: string;
+};
+
+type ParsedArgs = {
+  json: boolean;
+  failOnFindings: boolean;
+  targets: ReadonlyArray<FleetTarget>;
+};
+
+const JSON_TOOL_NAME = 'backlog-watch-fleet-tick';
+const DEFAULT_REPO = 'SwiftEnProfundidad/ast-intelligence-hooks';
+const DEFAULT_TARGETS = {
+  saas: resolve(
+    homedir(),
+    'Developer/Projects/SAAS:APP_SUPERMERCADOS/docs/pumuki/PUMUKI_BUGS_MEJORAS.md'
+  ),
+  ruralgo: resolve(
+    homedir(),
+    'Developer/Projects/R_GO/docs/technical/08-validation/refactor/pumuki-integration-feedback.md'
+  ),
+  flux: resolve(homedir(), 'Developer/Projects/Flux_training/docs/BUGS_Y_MEJORAS_PUMUKI.md'),
+} as const;
+
+const HELP_TEXT = `Usage:
+  npx --yes tsx@4.21.0 scripts/watch-consumer-backlog-fleet-tick.ts [--json] [--no-fail]
+    [--saas=<path>] [--ruralgo=<path>] [--flux=<path>] [--repo=<owner/name>]
+
+Defaults:
+  --saas=${DEFAULT_TARGETS.saas}
+  --ruralgo=${DEFAULT_TARGETS.ruralgo}
+  --flux=${DEFAULT_TARGETS.flux}
+  --repo=${DEFAULT_REPO}
+
+Options:
+  --json        Imprime salida consolidada JSON.
+  --no-fail     No devuelve exit code 1 aunque existan findings accionables.
+  --saas=PATH   Override ruta backlog SAAS.
+  --ruralgo=PATH Override ruta backlog RuralGo.
+  --flux=PATH   Override ruta backlog Flux.
+  --repo=NAME   Override repo para targets que consultan upstream.
+`;
+
+class HelpRequestedError extends Error {
+  constructor() {
+    super(HELP_TEXT);
+    this.name = 'HelpRequestedError';
+  }
+}
+
+const parseArgs = (argv: ReadonlyArray<string>): ParsedArgs => {
+  let json = false;
+  let failOnFindings = true;
+  let saasPath = DEFAULT_TARGETS.saas;
+  let ruralgoPath = DEFAULT_TARGETS.ruralgo;
+  let fluxPath = DEFAULT_TARGETS.flux;
+  let repo = DEFAULT_REPO;
+
+  for (const arg of argv) {
+    if (arg === '--help' || arg === '-h') {
+      throw new HelpRequestedError();
+    }
+    if (arg === '--json') {
+      json = true;
+      continue;
+    }
+    if (arg === '--no-fail') {
+      failOnFindings = false;
+      continue;
+    }
+    if (arg.startsWith('--saas=')) {
+      saasPath = resolve(arg.slice('--saas='.length).trim());
+      continue;
+    }
+    if (arg.startsWith('--ruralgo=')) {
+      ruralgoPath = resolve(arg.slice('--ruralgo='.length).trim());
+      continue;
+    }
+    if (arg.startsWith('--flux=')) {
+      fluxPath = resolve(arg.slice('--flux='.length).trim());
+      continue;
+    }
+    if (arg.startsWith('--repo=')) {
+      const value = arg.slice('--repo='.length).trim();
+      repo = value.length > 0 ? value : DEFAULT_REPO;
+      continue;
+    }
+    throw new Error(`Unknown argument "${arg}"\n\n${HELP_TEXT}`);
+  }
+
+  const targets: FleetTarget[] = [
+    { key: 'saas', filePath: saasPath, repo },
+    { key: 'ruralgo', filePath: ruralgoPath, repo },
+    { key: 'flux', filePath: fluxPath },
+  ];
+
+  for (const target of targets) {
+    if (!existsSync(target.filePath)) {
+      throw new Error(
+        `Target backlog not found for ${target.key}: ${target.filePath}\n` +
+          `Use --${target.key}=<path> to override.\n\n${HELP_TEXT}`
+      );
+    }
+  }
+
+  return {
+    json,
+    failOnFindings,
+    targets,
+  };
+};
+
+const formatHumanOutput = (
+  targets: ReadonlyArray<
+    Awaited<ReturnType<typeof runBacklogWatch>> & {
+      key: FleetTarget['key'];
+      actionRequiredReasons: ReadonlyArray<string>;
+    }
+  >
+): string => {
+  const lines: string[] = [];
+  const actionRequiredTargets = targets.filter((item) => item.hasActionRequired).length;
+  const entriesTotal = targets.reduce((acc, item) => acc + item.entriesScanned, 0);
+  const nonClosedTotal = targets.reduce((acc, item) => acc + item.nonClosedEntries, 0);
+  lines.push(
+    `[pumuki][backlog-watch-fleet-tick] targets=${targets.length} entries_total=${entriesTotal} non_closed_total=${nonClosedTotal} action_required_targets=${actionRequiredTargets}`
+  );
+  for (const target of targets) {
+    lines.push(
+      `[pumuki][backlog-watch-fleet-tick] key=${target.key} target=${target.filePath} entries=${target.entriesScanned} non_closed=${target.nonClosedEntries} action_required=${target.hasActionRequired ? 'yes' : 'no'} reasons=${formatActionReasonsForHuman(target.actionRequiredReasons)}`
+    );
+  }
+  return `${lines.join('\n')}\n`;
+};
+
+const main = async (): Promise<void> => {
+  const parsed = parseArgs(process.argv.slice(2));
+  const results = await Promise.all(
+    parsed.targets.map(async (target) => {
+      const watchResult = await runBacklogWatch({
+        filePath: target.filePath,
+        repo: target.repo,
+      });
+      const actionRequiredReasons = buildWatchActionRequiredReasons({
+        needsIssueCount: watchResult.classification.needsIssue.length,
+        driftClosedIssueCount: watchResult.classification.driftClosedIssue.length,
+        headingDriftCount: watchResult.headingDrift.length,
+      });
+      return {
+        ...watchResult,
+        key: target.key,
+        actionRequiredReasons,
+      };
+    })
+  );
+
+  const hasActionRequired = results.some((item) => item.hasActionRequired);
+  const actionRequiredTargets = results.filter((item) => item.hasActionRequired).length;
+  const entriesScannedTotal = results.reduce((acc, item) => acc + item.entriesScanned, 0);
+  const nonClosedTotal = results.reduce((acc, item) => acc + item.nonClosedEntries, 0);
+
+  if (parsed.json) {
+    writeFileSync(
+      process.stdout.fd,
+      `${JSON.stringify(
+        {
+          tool: JSON_TOOL_NAME,
+          schema_version: BACKLOG_JSON_SCHEMA_VERSION,
+          generated_at: new Date().toISOString(),
+          run_id: randomUUID(),
+          compat: {
+            contract_id: BACKLOG_JSON_COMPAT_CONTRACT_ID,
+            min_reader_version: BACKLOG_JSON_COMPAT_MIN_READER_VERSION,
+            is_backward_compatible: true,
+            breaking_changes: [],
+          },
+          summary: {
+            targets: parsed.targets.length,
+            entries_scanned_total: entriesScannedTotal,
+            non_closed_total: nonClosedTotal,
+            action_required_targets: actionRequiredTargets,
+            has_action_required: hasActionRequired,
+          },
+          results,
+        },
+        null,
+        2
+      )}\n`
+    );
+  } else {
+    writeFileSync(process.stdout.fd, formatHumanOutput(results));
+  }
+
+  if (parsed.failOnFindings && hasActionRequired) {
+    process.exitCode = 1;
+  }
+};
+
+main().catch((error: unknown) => {
+  if (error instanceof HelpRequestedError) {
+    writeFileSync(process.stdout.fd, `${HELP_TEXT}\n`);
+    process.exitCode = 0;
+    return;
+  }
+  const message = error instanceof Error ? error.message : String(error);
+  writeFileSync(process.stderr.fd, `${message}\n`);
+  process.exitCode = 1;
+});

package/scripts/watch-consumer-backlog-fleet.ts

@@ -0,0 +1,200 @@
+import { randomUUID } from 'node:crypto';
+import { writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import {
+  buildWatchActionRequiredReasons,
+  formatActionReasonsForHuman,
+} from './backlog-action-reasons-lib';
+import {
+  BACKLOG_JSON_COMPAT_CONTRACT_ID,
+  BACKLOG_JSON_COMPAT_MIN_READER_VERSION,
+  BACKLOG_JSON_SCHEMA_VERSION,
+} from './backlog-json-contract-lib';
+import { runBacklogWatch } from './watch-consumer-backlog-lib';
+
+type FleetTarget = {
+  filePath: string;
+  repo?: string;
+};
+
+type ParsedArgs = {
+  targets: ReadonlyArray<FleetTarget>;
+  json: boolean;
+  failOnFindings: boolean;
+};
+
+const JSON_TOOL_NAME = 'backlog-watch-fleet';
+
+const HELP_TEXT = `Usage:
+  npx --yes tsx@4.21.0 scripts/watch-consumer-backlog-fleet.ts --target=<markdown-path>[::owner/name] [--target=<markdown-path>[::owner/name] ...] [--json] [--no-fail]
+
+Options:
+  --target=<path>[::repo]  Backlog markdown consumidor a vigilar. Puedes repetir el flag.
+                           Ejemplo: --target=/repo/docs/backlog.md::owner/name
+  --json                   Imprime resultado consolidado en JSON.
+  --no-fail                No devuelve exit code 1 aunque existan findings accionables.
+`;
+
+class HelpRequestedError extends Error {
+  constructor() {
+    super(HELP_TEXT);
+    this.name = 'HelpRequestedError';
+  }
+}
+
+const parseTarget = (rawTarget: string): FleetTarget => {
+  const trimmed = rawTarget.trim();
+  const separatorIndex = trimmed.indexOf('::');
+  if (separatorIndex === -1) {
+    return {
+      filePath: resolve(trimmed),
+    };
+  }
+  const filePath = trimmed.slice(0, separatorIndex).trim();
+  const repo = trimmed.slice(separatorIndex + 2).trim();
+  return {
+    filePath: resolve(filePath),
+    repo: repo.length > 0 ? repo : undefined,
+  };
+};
+
+const parseArgs = (argv: ReadonlyArray<string>): ParsedArgs => {
+  const targets: FleetTarget[] = [];
+  let json = false;
+  let failOnFindings = true;
+
+  for (const arg of argv) {
+    if (arg === '--help' || arg === '-h') {
+      throw new HelpRequestedError();
+    }
+    if (arg === '--json') {
+      json = true;
+      continue;
+    }
+    if (arg === '--no-fail') {
+      failOnFindings = false;
+      continue;
+    }
+    if (arg.startsWith('--target=')) {
+      const rawTarget = arg.slice('--target='.length);
+      if (rawTarget.trim().length === 0) {
+        throw new Error(`Invalid --target (empty value)\n\n${HELP_TEXT}`);
+      }
+      targets.push(parseTarget(rawTarget));
+      continue;
+    }
+    throw new Error(`Unknown argument "${arg}"\n\n${HELP_TEXT}`);
+  }
+
+  if (targets.length === 0) {
+    throw new Error(`Missing --target\n\n${HELP_TEXT}`);
+  }
+
+  return {
+    targets,
+    json,
+    failOnFindings,
+  };
+};
+
+const formatHumanOutput = (
+  targets: ReadonlyArray<
+    Awaited<ReturnType<typeof runBacklogWatch>> & {
+      actionRequiredReasons: ReadonlyArray<string>;
+    }
+  >
+): string => {
+  const lines: string[] = [];
+  const actionRequiredTargets = targets.filter((item) => item.hasActionRequired).length;
+  const entriesTotal = targets.reduce((acc, item) => acc + item.entriesScanned, 0);
+  const nonClosedTotal = targets.reduce((acc, item) => acc + item.nonClosedEntries, 0);
+
+  lines.push(
+    `[pumuki][backlog-watch-fleet] targets=${targets.length} entries_total=${entriesTotal} non_closed_total=${nonClosedTotal} action_required_targets=${actionRequiredTargets}`
+  );
+  for (const target of targets) {
+    lines.push(
+      `[pumuki][backlog-watch-fleet] target=${target.filePath} repo=${target.repo ?? '-'} entries=${target.entriesScanned} non_closed=${target.nonClosedEntries} action_required=${target.hasActionRequired ? 'yes' : 'no'} reasons=${formatActionReasonsForHuman(target.actionRequiredReasons)}`
+    );
+  }
+  return `${lines.join('\n')}\n`;
+};
+
+const main = async (): Promise<void> => {
+  const parsed = parseArgs(process.argv.slice(2));
+  const results = await Promise.all(
+    parsed.targets.map(async (target) => {
+      const watchResult = await runBacklogWatch({
+        filePath: target.filePath,
+        repo: target.repo,
+      });
+      const actionRequiredReasons = buildWatchActionRequiredReasons({
+        needsIssueCount: watchResult.classification.needsIssue.length,
+        driftClosedIssueCount: watchResult.classification.driftClosedIssue.length,
+        headingDriftCount: watchResult.headingDrift.length,
+      });
+      return {
+        ...watchResult,
+        actionRequiredReasons,
+      };
+    })
+  );
+
+  const hasActionRequired = results.some((item) => item.hasActionRequired);
+  const actionRequiredTargets = results.filter((item) => item.hasActionRequired).length;
+  const entriesScannedTotal = results.reduce((acc, item) => acc + item.entriesScanned, 0);
+  const nonClosedTotal = results.reduce((acc, item) => acc + item.nonClosedEntries, 0);
+
+  if (parsed.json) {
+    const generatedAt = new Date().toISOString();
+    const runId = randomUUID();
+    writeFileSync(
+      process.stdout.fd,
+      `${JSON.stringify(
+        {
+          tool: JSON_TOOL_NAME,
+          schema_version: BACKLOG_JSON_SCHEMA_VERSION,
+          generated_at: generatedAt,
+          run_id: runId,
+          invocation: {
+            mode: 'json',
+            targets_count: parsed.targets.length,
+          },
+          compat: {
+            contract_id: BACKLOG_JSON_COMPAT_CONTRACT_ID,
+            min_reader_version: BACKLOG_JSON_COMPAT_MIN_READER_VERSION,
+            is_backward_compatible: true,
+            breaking_changes: [],
+          },
+          summary: {
+            targets: parsed.targets.length,
+            entries_scanned_total: entriesScannedTotal,
+            non_closed_total: nonClosedTotal,
+            action_required_targets: actionRequiredTargets,
+            has_action_required: hasActionRequired,
+          },
+          results,
+        },
+        null,
+        2
+      )}\n`
+    );
+  } else {
+    writeFileSync(process.stdout.fd, formatHumanOutput(results));
+  }
+
+  if (parsed.failOnFindings && hasActionRequired) {
+    process.exitCode = 1;
+  }
+};
+
+main().catch((error: unknown) => {
+  if (error instanceof HelpRequestedError) {
+    writeFileSync(process.stdout.fd, `${HELP_TEXT}\n`);
+    process.exitCode = 0;
+    return;
+  }
+  const message = error instanceof Error ? error.message : String(error);
+  writeFileSync(process.stderr.fd, `${message}\n`);
+  process.exitCode = 1;
+});

package/scripts/watch-consumer-backlog-lib.ts

@@ -53,10 +53,10 @@ export type BacklogIssueNumberResolver = (
 
 const STATUS_EMOJI_PATTERN = /(✅|🚧|⏳|⛔)/;
 const ISSUE_REF_PATTERN = /#(\d+)/;
-const BACKLOG_ID_PATTERN = /^(PUMUKI-(?:M)?\d+|PUMUKI-INC-\d+|FP-\d+|AST-GAP-\d+)$/;
+const BACKLOG_ID_PATTERN = /^(PUMUKI-(?:M)?\d+|PUM-\d+|PUMUKI-INC-\d+|FP-\d+|AST-GAP-\d+)$/;
 const STATUS_TEXT_PATTERN = /^(OPEN|PENDING|REPORTED|IN_PROGRESS|BLOCKED|FIXED|CLOSED)\b/i;
 const BACKLOG_SECTION_HEADING_PATTERN =
-  /^(\s*###\s*)(✅|🚧|⏳|⛔)(\s+)(PUMUKI-(?:M)?\d+|PUMUKI-INC-\d+|FP-\d+|AST-GAP-\d+)\b/;
+  /^(\s*###\s*)(✅|🚧|⏳|⛔)(\s+)(PUMUKI-(?:M)?\d+|PUM-\d+|PUMUKI-INC-\d+|FP-\d+|AST-GAP-\d+)\b/;
 const STATUS_TEXT_TO_EMOJI: Record<string, BacklogStatusEmoji> = {
   OPEN: '⏳',
   PENDING: '⏳',