@imolko/ultra-agent 0.1.2-beta → 1.0.0-beta

package/scripts/adr-gate/links.mjs

@@ -0,0 +1,59 @@
+/**
+ * Enlaces markdown del registro ADR.
+ *
+ * `resolveLink()` reproduce `resolve_link()` del gate histórico: descarta URLs
+ * externas, autolinks y anclas puras, ignora fragmentos y resuelve contra el
+ * directorio del ADR con la semántica de `Path.resolve()`.
+ */
+
+import path from "node:path";
+
+import {
+  LINK_DEST_RE,
+  joinUnnormalized,
+  pyStrip,
+  resolvePath,
+} from "./text.mjs";
+
+/**
+ * Devuelve los destinos de los enlaces markdown inline `](dest)`.
+ * @param {string} text
+ * @returns {string[]}
+ */
+export function linkTargets(text) {
+  return Array.from(text.matchAll(LINK_DEST_RE), (match) => match[1]);
+}
+
+/**
+ * Resuelve un target de enlace relativo contra el directorio del ADR.
+ * @param {string} adrFile
+ * @param {string} target
+ * @returns {string | null} ruta resuelta, o null si la regla no la considera
+ */
+export function resolveLink(adrFile, target) {
+  let value = pyStrip(target);
+  if (isOutsideGate(value)) {
+    return null;
+  }
+
+  value = value.split("#", 1)[0];
+  if (!value || !value.endsWith(".md")) {
+    return null;
+  }
+
+  return resolvePath(joinUnnormalized(path.dirname(adrFile), value));
+}
+
+/**
+ * ¿El destino queda fuera del gate (URL, autolink o ancla pura)?
+ * @param {string} value
+ * @returns {boolean}
+ */
+function isOutsideGate(value) {
+  return (
+    value.startsWith("<") ||
+    value.startsWith(">") ||
+    value.includes("://") ||
+    value.startsWith("#")
+  );
+}

package/scripts/adr-gate/registry.mjs

@@ -0,0 +1,155 @@
+/**
+ * Registro ADR y orden de recorrido.
+ *
+ * El gate resuelve su raíz desde su propia ubicación (no desde `process.cwd()`),
+ * así que `createRegistry()` recibe esa raíz y deriva las rutas del registro.
+ * Los tiers se recorren siempre en el orden A, T, P.
+ */
+
+import { readdirSync } from "node:fs";
+import path from "node:path";
+
+import { comparePathComponents } from "./text.mjs";
+
+const TIER_DEFINITIONS = Object.freeze([
+  { prefix: "A", segment: "foundational", allowed: new Set(["A", "meta"]) },
+  { prefix: "T", segment: "typescript", allowed: new Set(["A", "T", "meta"]) },
+  { prefix: "P", segment: "python", allowed: new Set(["A", "P", "meta"]) },
+]);
+
+/**
+ * Construye las rutas del registro a partir de la raíz del repositorio.
+ * @param {string} root
+ * @returns {{
+ *   root: string,
+ *   adrDir: string,
+ *   tiers: Array<{ prefix: string, segment: string, allowed: Set<string>, directory: string }>,
+ * }}
+ */
+export function createRegistry(root) {
+  const adrDir = path.join(root, "docs", "adr");
+  const tiers = TIER_DEFINITIONS.map((tier) => ({
+    ...tier,
+    directory: path.join(adrDir, tier.segment),
+  }));
+  return { root, adrDir, tiers };
+}
+
+/**
+ * ¿El prefijo corresponde a un tier con directorio propio?
+ * @param {{ tiers: Array<{ prefix: string }> }} registry
+ * @param {string} prefix
+ * @returns {boolean}
+ */
+export function hasTier(registry, prefix) {
+  return registry.tiers.some((tier) => tier.prefix === prefix);
+}
+
+/**
+ * Lista los ADRs de un tier (`<tier>-*.md`) ordenados por componentes de ruta,
+ * como `sorted(Path.glob(...))` de Python.
+ * @param {{ prefix: string, directory: string }} tier
+ * @returns {string[]}
+ */
+export function tierAdrFiles(tier) {
+  let names;
+  try {
+    names = readdirSync(tier.directory);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return [];
+    }
+    throw error;
+  }
+
+  return names
+    .filter((name) => name.startsWith(`${tier.prefix}-`) && name.endsWith(".md"))
+    .map((name) => path.join(tier.directory, name))
+    .sort(comparePathComponents);
+}
+
+/**
+ * Lista recursivamente los `*.md` de docs/adr, ordenados por componentes de
+ * ruta como el `sorted(ADR_DIR.rglob("*.md"))` del gate original.
+ * @param {string} directory
+ * @returns {string[]}
+ */
+export function markdownFiles(directory) {
+  const files = [];
+  visitDirectory(directory, files);
+  return files.sort(comparePathComponents);
+}
+
+/**
+ * Acumula los `*.md` de un directorio y sus descendientes.
+ * @param {string} directory
+ * @param {string[]} files
+ * @returns {void}
+ */
+function visitDirectory(directory, files) {
+  let entries;
+  try {
+    entries = readdirSync(directory, { withFileTypes: true });
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return;
+    }
+    throw error;
+  }
+
+  for (const entry of entries) {
+    const fullPath = path.join(directory, entry.name);
+    if (entry.isDirectory()) {
+      visitDirectory(fullPath, files);
+    } else if (entry.name.endsWith(".md")) {
+      files.push(fullPath);
+    }
+  }
+}
+
+/**
+ * Clasifica un archivo resuelto en su tier (o null si está fuera del registro).
+ * @param {{ adrDir: string, tiers: Array<{ prefix: string, segment: string }> }} registry
+ * @param {string} resolved
+ * @returns {string | null}
+ */
+export function targetTier(registry, resolved) {
+  const relative = path.relative(registry.adrDir, resolved);
+  if (!isInsideAdrDir(relative)) {
+    return null;
+  }
+
+  const parts = relative === "" ? [] : relative.split(path.sep);
+  if (parts.length >= 2) {
+    const tier = registry.tiers.find(({ segment }) => segment === parts[0]);
+    if (tier) {
+      return tier.prefix;
+    }
+  }
+
+  const name = parts.length > 0 ? parts[parts.length - 1] : "";
+  return isMetaName(name) ? "meta" : "project";
+}
+
+/**
+ * ¿La ruta relativa cae dentro de docs/adr?
+ * @param {string} relative
+ * @returns {boolean}
+ */
+function isInsideAdrDir(relative) {
+  return (
+    relative === "" ||
+    (relative !== ".." &&
+      !relative.startsWith(`..${path.sep}`) &&
+      !path.isAbsolute(relative))
+  );
+}
+
+/**
+ * ¿El nombre pertenece al meta-ADR o a un índice?
+ * @param {string} name
+ * @returns {boolean}
+ */
+function isMetaName(name) {
+  return name.startsWith("ADR-0000") || name === "index.md";
+}

package/scripts/adr-gate/report.mjs

@@ -0,0 +1,21 @@
+/**
+ * Acumulador de violaciones del gate.
+ *
+ * Las reglas comparten un único reporte para que el orden de ejecución sea
+ * exactamente el de la salida (jerarquia, enlaces, frontmatter, indices,
+ * hardcoded): invertirlo cambia los golden files (T-017).
+ */
+
+/**
+ * Crea el reporte de una ejecución.
+ * @returns {{ add: (rule: string, message: string) => void, violations: string[] }}
+ */
+export function createReport() {
+  const violations = [];
+  return {
+    add(rule, message) {
+      violations.push(`[${rule}] ${message}`);
+    },
+    violations,
+  };
+}

package/scripts/adr-gate/rules/enlaces.mjs

@@ -0,0 +1,33 @@
+/**
+ * Regla `enlaces`: todo enlace markdown interno relativo a un `*.md` resuelve a
+ * un archivo existente.
+ */
+
+import { existsSync } from "node:fs";
+import path from "node:path";
+
+import { linkTargets, resolveLink } from "../links.mjs";
+import { markdownFiles } from "../registry.mjs";
+import { readText } from "../text.mjs";
+
+/**
+ * Ejecuta la regla sobre todos los markdown del registro ADR.
+ * @param {ReturnType<import("../registry.mjs").createRegistry>} registry
+ * @param {ReturnType<import("../report.mjs").createReport>} report
+ * @returns {void}
+ */
+export function ruleEnlaces(registry, report) {
+  for (const md of markdownFiles(registry.adrDir)) {
+    const text = readText(md);
+    for (const target of linkTargets(text)) {
+      const resolved = resolveLink(md, target);
+      if (resolved === null || existsSync(resolved)) {
+        continue;
+      }
+      report.add(
+        "enlaces",
+        `${path.relative(registry.root, md)} enlaza a un archivo inexistente: ${target}`,
+      );
+    }
+  }
+}

package/scripts/adr-gate/rules/frontmatter.mjs

@@ -0,0 +1,126 @@
+/**
+ * Regla `frontmatter`: el título H1 sigue `# <TIER>-<NNN>: Título` y los campos
+ * `originally` / `Enriquecido desde` usan la ortografía exacta.
+ */
+
+import path from "node:path";
+
+import { tierAdrFiles } from "../registry.mjs";
+import {
+  ENRICHED_RE,
+  ENRICHED_WRONG_RE,
+  H1_RE,
+  ORIGINALLY_RE,
+  ORIGINALLY_WRONG_RE,
+  pyStrip,
+  readText,
+  splitLines,
+} from "../text.mjs";
+
+/**
+ * Ejecuta la regla sobre los tres tiers.
+ * @param {ReturnType<import("../registry.mjs").createRegistry>} registry
+ * @param {ReturnType<import("../report.mjs").createReport>} report
+ * @returns {void}
+ */
+export function ruleFrontmatter(registry, report) {
+  for (const tier of registry.tiers) {
+    for (const adr of tierAdrFiles(tier)) {
+      checkFrontmatter({ registry, adr, report });
+    }
+  }
+}
+
+/**
+ * Comprueba el H1 y los campos del frontmatter de un ADR.
+ * @param {{ registry: object, adr: string, report: object }} parent
+ * @returns {void}
+ */
+function checkFrontmatter(parent) {
+  const text = readText(parent.adr);
+  const lines = splitLines(text);
+  const context = {
+    ...parent,
+    text,
+    lines,
+    rel: path.relative(parent.registry.root, parent.adr),
+    firstLine: lines[0] ?? "",
+  };
+
+  checkTitle(context);
+  checkOriginally(context);
+  checkEnriched(context);
+}
+
+/**
+ * Comprueba que el H1 siga `# <TIER>-<NNN>: Título`.
+ * @param {object} context
+ * @returns {void}
+ */
+function checkTitle(context) {
+  if (!H1_RE.test(context.firstLine)) {
+    context.report.add(
+      "frontmatter",
+      `${context.rel}: el título H1 no sigue \`# <TIER>-<NNN>: Título\``,
+    );
+  }
+}
+
+/**
+ * Comprueba que `originally` exista y esté en minúsculas.
+ * @param {object} context
+ * @returns {void}
+ */
+function checkOriginally(context) {
+  if (!ORIGINALLY_RE.test(context.text)) {
+    context.report.add(
+      "frontmatter",
+      `${context.rel}: falta el campo \`**originally**:\` (minúsculas)`,
+    );
+  }
+
+  const spelling = {
+    wrong: ORIGINALLY_WRONG_RE,
+    right: ORIGINALLY_RE,
+  };
+  if (hasWrongSpelling(context.lines, spelling)) {
+    context.report.add(
+      "frontmatter",
+      `${context.rel}: \`originally\` debe ir en minúsculas`,
+    );
+  }
+}
+
+/**
+ * Comprueba la ortografía del campo opcional `Enriquecido desde`.
+ * @param {object} context
+ * @returns {void}
+ */
+function checkEnriched(context) {
+  const spelling = {
+    wrong: ENRICHED_WRONG_RE,
+    right: ENRICHED_RE,
+  };
+  if (hasWrongSpelling(context.lines, spelling)) {
+    context.report.add(
+      "frontmatter",
+      `${context.rel}: el campo opcional debe escribirse \`**Enriquecido desde**:\``,
+    );
+  }
+}
+
+/**
+ * ¿Alguna línea usa la variante incorrecta sin la correcta?
+ * @param {string[]} lines
+ * @param {{ wrong: RegExp, right: RegExp }} spelling
+ * @returns {boolean}
+ */
+function hasWrongSpelling(lines, spelling) {
+  for (const line of lines) {
+    const stripped = pyStrip(line);
+    if (spelling.wrong.test(stripped) && !spelling.right.test(stripped)) {
+      return true;
+    }
+  }
+  return false;
+}

package/scripts/adr-gate/rules/hardcoded.mjs

@@ -0,0 +1,63 @@
+/**
+ * Regla `hardcoded`: los ADRs activos no duplican anclas cuya fuente canónica
+ * vive en el paquete o en docs/agents/.
+ */
+
+import path from "node:path";
+
+import { tierAdrFiles } from "../registry.mjs";
+import { ESTADO_RE, pyStrip, readText } from "../text.mjs";
+
+/** Anchors caducados: la fuente canónica pasó al paquete y a docs/agents/ (A-052). */
+const STALE_ANCHORS = [".pi/skills/", ".pi/repo-config.md"];
+
+/**
+ * Ejecuta la regla sobre los ADRs activos de los tres tiers.
+ * @param {ReturnType<import("../registry.mjs").createRegistry>} registry
+ * @param {ReturnType<import("../report.mjs").createReport>} report
+ * @returns {void}
+ */
+export function ruleHardcoded(registry, report) {
+  for (const tier of registry.tiers) {
+    for (const adr of tierAdrFiles(tier)) {
+      checkHardcoded({ registry, adr, report });
+    }
+  }
+}
+
+/**
+ * Comprueba las anclas caducadas de un ADR activo.
+ * @param {{ registry: object, adr: string, report: object }} context
+ * @returns {void}
+ */
+function checkHardcoded(context) {
+  const text = readText(context.adr);
+  if (!isActiveAdr(text)) {
+    return;
+  }
+
+  for (const anchor of STALE_ANCHORS) {
+    if (text.includes(anchor)) {
+      const rel = path.relative(context.registry.root, context.adr);
+      context.report.add(
+        "hardcoded",
+        `${rel} duplica el ancla caducada \`${anchor}\` (fuente canónica: paquete/docs/agents)`,
+      );
+    }
+  }
+}
+
+/**
+ * Marca un ADR como activo salvo que su `**Estado**` sea `Reemplazado` o
+ * `Deprecado`; la ausencia del campo se trata como activo.
+ * @param {string} text
+ * @returns {boolean}
+ */
+function isActiveAdr(text) {
+  const match = ESTADO_RE.exec(text);
+  if (!match) {
+    return true;
+  }
+  const state = pyStrip(match[1]);
+  return state !== "Reemplazado" && state !== "Deprecado";
+}

package/scripts/adr-gate/rules/indices.mjs

@@ -0,0 +1,100 @@
+/**
+ * Regla `indices`: cada ADR aparece en el índice de su tier y el índice no lista
+ * ADRs inexistentes.
+ *
+ * Los destinos inexistentes se comprueban en orden canónico por code point. El
+ * gate histórico iteraba un `set` de Python, cuyo orden dependía de
+ * `PYTHONHASHSEED`; fijar el orden hace reproducible el golden (T-017).
+ */
+
+import { existsSync } from "node:fs";
+import path from "node:path";
+
+import { linkTargets } from "../links.mjs";
+import { tierAdrFiles } from "../registry.mjs";
+import {
+  joinUnnormalized,
+  readText,
+  resolvePath,
+  sortByCodePoint,
+} from "../text.mjs";
+
+const LOCAL_LINK_PREFIX = "./";
+
+/**
+ * Ejecuta la regla sobre los tres tiers.
+ * @param {ReturnType<import("../registry.mjs").createRegistry>} registry
+ * @param {ReturnType<import("../report.mjs").createReport>} report
+ * @returns {void}
+ */
+export function ruleIndices(registry, report) {
+  for (const tier of registry.tiers) {
+    checkTierIndex({ registry, tier, report });
+  }
+}
+
+/**
+ * Comprueba el índice de un tier en sus dos direcciones.
+ * @param {{ registry: object, tier: object, report: object }} context
+ * @returns {void}
+ */
+function checkTierIndex(context) {
+  const index = path.join(context.tier.directory, "index.md");
+  if (!existsSync(index)) {
+    const rel = path.relative(context.registry.root, index);
+    context.report.add(
+      "indices",
+      `falta el índice del tier ${context.tier.prefix}: ${rel}`,
+    );
+    return;
+  }
+
+  const indexTargets = new Set(
+    linkTargets(readText(index)).filter(
+      (target) =>
+        target.startsWith(LOCAL_LINK_PREFIX) && target.endsWith(".md"),
+    ),
+  );
+
+  checkListedAdrs({ ...context, indexTargets });
+  checkExistingTargets({ ...context, index, indexTargets });
+}
+
+/**
+ * Reporta los ADRs del tier que no aparecen en su índice.
+ * @param {{ registry: object, tier: object, report: object, indexTargets: Set<string> }} context
+ * @returns {void}
+ */
+function checkListedAdrs(context) {
+  for (const adr of tierAdrFiles(context.tier)) {
+    const target = `${LOCAL_LINK_PREFIX}${path.basename(adr)}`;
+    if (!context.indexTargets.has(target)) {
+      const rel = path.relative(context.registry.root, adr);
+      context.report.add(
+        "indices",
+        `${rel} no aparece en el índice de su tier`,
+      );
+    }
+  }
+}
+
+/**
+ * Reporta los destinos del índice que no existen, en orden canónico.
+ * @param {{ registry: object, tier: object, report: object, index: string, indexTargets: Set<string> }} context
+ * @returns {void}
+ */
+function checkExistingTargets(context) {
+  for (const target of sortByCodePoint([...context.indexTargets])) {
+    const relative = target.slice(LOCAL_LINK_PREFIX.length);
+    const resolved = resolvePath(
+      joinUnnormalized(context.tier.directory, relative),
+    );
+    if (!existsSync(resolved)) {
+      const rel = path.relative(context.registry.root, context.index);
+      context.report.add(
+        "indices",
+        `el índice ${rel} lista un ADR inexistente: ${target}`,
+      );
+    }
+  }
+}

package/scripts/adr-gate/rules/jerarquia.mjs

@@ -0,0 +1,102 @@
+/**
+ * Regla `jerarquia`: un ADR A/T/P no referencia tiers prohibidos, ni por enlace
+ * markdown ni por cita en texto plano. Los IDs citados por un enlace prohibido
+ * quedan cubiertos por esa violación y no se reportan otra vez.
+ */
+
+import path from "node:path";
+
+import { resolveLink } from "../links.mjs";
+import { hasTier, targetTier, tierAdrFiles } from "../registry.mjs";
+import { LINK_RE, LINK_TARGET_RE, PLAIN_ID_RE, readText } from "../text.mjs";
+
+/**
+ * Ejecuta la regla sobre los tres tiers.
+ * @param {ReturnType<import("../registry.mjs").createRegistry>} registry
+ * @param {ReturnType<import("../report.mjs").createReport>} report
+ * @returns {void}
+ */
+export function ruleJerarquia(registry, report) {
+  for (const tier of registry.tiers) {
+    const allowedPrefixes = new Set(
+      [...tier.allowed].filter((target) => hasTier(registry, target)),
+    );
+
+    for (const adr of tierAdrFiles(tier)) {
+      const text = readText(adr);
+      const context = {
+        registry,
+        tier,
+        adr,
+        report,
+        allowedPrefixes,
+        reportedIds: new Set(),
+      };
+
+      scanLinks(context, text);
+      scanPlainIds(context, text.replace(LINK_TARGET_RE, ""));
+    }
+  }
+}
+
+/**
+ * Reporta los enlaces markdown a tiers prohibidos.
+ * @param {object} context
+ * @param {string} text
+ * @returns {void}
+ */
+function scanLinks(context, text) {
+  for (const match of text.matchAll(LINK_RE)) {
+    const label = match[1];
+    const target = match[2];
+    const resolved = resolveLink(context.adr, target);
+    if (resolved === null) {
+      continue;
+    }
+
+    const resolvedTier = targetTier(context.registry, resolved);
+    if (resolvedTier === null || context.tier.allowed.has(resolvedTier)) {
+      continue;
+    }
+
+    addReportedIds(context.reportedIds, `${label} ${target}`);
+    context.report.add(
+      "jerarquia",
+      `${path.relative(context.registry.root, context.adr)} referencia al tier ${resolvedTier} (${target}), prohibido para el tier ${context.tier.prefix}`,
+    );
+  }
+}
+
+/**
+ * Reporta las citas en texto plano con un prefijo no permitido para el tier.
+ * @param {object} context
+ * @param {string} text
+ * @returns {void}
+ */
+function scanPlainIds(context, text) {
+  for (const match of text.matchAll(PLAIN_ID_RE)) {
+    const prefix = match[1];
+    const ident = match[0];
+    if (context.allowedPrefixes.has(prefix) || context.reportedIds.has(ident)) {
+      continue;
+    }
+    context.reportedIds.add(ident);
+    context.report.add(
+      "jerarquia",
+      `${path.relative(context.registry.root, context.adr)} cita en texto plano ${ident} (prefijo ${prefix}), prohibido para el tier ${context.tier.prefix}`,
+    );
+  }
+}
+
+/**
+ * Marca los IDs citados por un enlace prohibido —en la etiqueta o el destino—
+ * para no reportarlos también como cita en texto plano.
+ * @param {Set<string>} reportedIds
+ * @param {string} text
+ * @returns {void}
+ */
+function addReportedIds(reportedIds, text) {
+  for (const match of text.matchAll(PLAIN_ID_RE)) {
+    reportedIds.add(match[0]);
+  }
+}