@nac3/forge-cli 1.23.6 → 1.24.0

package/dist/core/ci_gaps.js

@@ -0,0 +1,352 @@
+/**
+ * LO QUE LA CADENA NO CORRIO -- F-14 / F-15 (pedido del dueno, 2026-11-01).
+ *
+ * EL DEFECTO. Medido en el repositorio: `.github/workflows/ci.yml` instala y
+ * corre `typecheck`, nada mas; `prepublishOnly` corre SEIS compuertas (build,
+ * typecheck, catalog:lint, test, brain-matrix:gate, hito4:lint). Asi que un
+ * VERDE en el badge de CI no significa "la bateria paso" -- significa "los
+ * tipos compilan" -- y nada en la salida de la corrida lo dice. Esta forma ya
+ * costo una vez: 1.20.1 salio publicada con un bug adentro.
+ *
+ * El dueno NO pidio mover las compuertas pesadas a la cadena (es una decision
+ * suya, con su motivo: la matriz multi-OS consumia la cuota en una rafaga).
+ * Pidio que la corrida DECLARE lo que no corrio. Es la misma regla que el
+ * metodo aplica a un recibo: una corrida que no mide algo tiene que decir que
+ * no lo midio, porque el que lee un verde no tiene otra forma de saberlo.
+ *
+ * Y LA PAREJA QUE EL DUENO SOSPECHO Y RESULTO PEOR (F-15). `lefthook.yml`
+ * declaraba un `pre-push` con `pnpm test` + `brain-matrix:gate`: dos
+ * compuertas, no las seis del publish. Pero antes de eso: el gancho no
+ * estaba instalado y no podia estarlo -- `.git/hooks` vacio,
+ * `core.hooksPath` sin poner, `lefthook` no era dependencia. Asi que la
+ * "preflight local" a la que el comentario de ci.yml remite no la corria
+ * ningun mecanismo: era un habito. Y el circulo se cerraba solo: ci.yml
+ * decia que lo pesado corre local, y lefthook.yml decia "CI is the real
+ * gate". Cada uno senalaba al otro y ninguno lo hacia.
+ *
+ * ARREGLADO EL 2026-11-01, con la decision del dueno: `lefthook` es
+ * devDependency, el ciclo `prepare` lo instala, y el pre-push corre el
+ * paquete de 24,8 s (todo `prepublishOnly` menos la bateria). La cadena NO
+ * se ensancha -- se mantiene liviana por cuota -- asi que para el trabajo en
+ * rama el gancho es la UNICA puerta. De ahi los dos agregados de este
+ * modulo: `triggers`, porque una cadena que solo dispara en main no es una
+ * segunda puerta para una rama; y la cobertura POR EQUIVALENCIA, porque el
+ * gancho invoca los scripts directo (arranca mas rapido) y `build` corre el
+ * mismo `tsc` que `typecheck` -- decir "no corre typecheck" ahi seria una
+ * falsa alarma, y una falsa alarma termina con el instrumento apagado.
+ *
+ * POR QUE ESTO SE DERIVA Y NO SE ESCRIBE A MANO. Una lista fija de "lo que
+ * no corre" es una segunda fuente de verdad, y se desincroniza el dia que
+ * alguien agrega una compuerta al publish -- el mismo defecto que este
+ * modulo esta reportando. Asi que las tres listas salen de los archivos que
+ * YA son la verdad (package.json, el workflow, lefthook.yml) y la diferencia
+ * se calcula. Si una de las tres no se puede leer, esto FALLA: una medicion
+ * que no se pudo hacer no se reporta como "no falta nada".
+ *
+ * ASCII-only.
+ */
+/** Los nombres de script que una linea de comandos invoca. Cubre las formas
+ *  que este repositorio usa de verdad (`pnpm run x`, `pnpm x`, `npm run x`)
+ *  y nada mas: inventar formas que nadie escribe es ruido. */
+export function scriptsInvoked(command) {
+    const out = [];
+    const re = /(?:pnpm|npm|yarn)\s+(?:run\s+)?([a-z0-9][a-z0-9:_-]*)/gi;
+    let m;
+    while ((m = re.exec(command)) !== null) {
+        const name = m[1];
+        /* `pnpm install` / `pnpm exec` no son scripts del paquete. */
+        if (['install', 'exec', 'dlx', 'add', 'why', 'ls', 'publish', 'pack'].includes(name))
+            continue;
+        if (!out.includes(name))
+            out.push(name);
+    }
+    return out;
+}
+/** Los PROGRAMAS que una linea de comandos invoca de verdad, expandiendo
+ *  los scripts del paquete. Es lo que permite decir "el gancho cubre
+ *  `typecheck` porque corre `build`, que corre el mismo tsc" sin escribirlo
+ *  a mano en ninguna lista.
+ *
+ *  La forma de cada invocacion: el programa, y para `node` tambien el
+ *  archivo (`node:scripts/catalog_lint.mjs`) -- dos scripts de node
+ *  distintos no son la misma compuerta. */
+export function invocationsOf(command, scripts = {}, seen = new Set()) {
+    const out = [];
+    const add = (v) => { if (v && !out.includes(v))
+        out.push(v); };
+    for (const rawSegment of command.split(/&&|\|\||;/)) {
+        const seg = rawSegment.trim();
+        if (!seg)
+            continue;
+        const tokens = seg.split(/\s+/).filter(Boolean);
+        let i = 0;
+        let head = tokens[i];
+        if (!head)
+            continue;
+        /* `pnpm run x` / `pnpm x` / `npm run x`: se expande al script. */
+        if (/^(pnpm|npm|yarn)$/.test(head)) {
+            i++;
+            while (tokens[i] && (tokens[i].startsWith('-') || tokens[i] === 'run'))
+                i++;
+            const next = tokens[i];
+            if (!next)
+                continue;
+            if (next === 'exec' || next === 'dlx') {
+                const bin = tokens[i + 1];
+                if (bin)
+                    add(bin);
+                continue;
+            }
+            if (['install', 'add', 'why', 'ls', 'publish', 'pack'].includes(next))
+                continue;
+            if (scripts[next] !== undefined && !seen.has(next)) {
+                const nextSeen = new Set(seen);
+                nextSeen.add(next);
+                for (const v of invocationsOf(scripts[next], scripts, nextSeen))
+                    add(v);
+            }
+            else {
+                add(next);
+            }
+            continue;
+        }
+        if (head === 'npx') {
+            const bin = tokens[1];
+            if (bin)
+                add(bin);
+            continue;
+        }
+        if (head === 'node' || head === 'tsx') {
+            const file = tokens.slice(1).find((t) => !t.startsWith('-'));
+            add(file ? head + ':' + file.replace(/\\/g, '/') : head);
+            continue;
+        }
+        add(head);
+    }
+    return out;
+}
+/** Las lineas `run:` de un workflow, sin parsear YAML entero. Un parser
+ *  completo seria una dependencia nueva para leer tres lineas; lo que hace
+ *  seguro al atajo es que el caso de la bateria corre sobre el archivo REAL
+ *  del repositorio, asi que un cambio de forma que esto no entienda sale
+ *  rojo en vez de salir en silencio. */
+function runLines(yaml) {
+    const out = [];
+    const lines = yaml.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        /* Un `#` al principio de la linea (despues de la sangria) es un
+         * comentario: el NOTE al pie de ci.yml nombra justamente las compuertas
+         * que NO corren, y contarlas como ejecutadas seria leer la confesion
+         * como si fuera el hecho. */
+        if (/^\s*#/.test(line))
+            continue;
+        const m = /^\s*(?:-\s+)?run:\s*(.*)$/.exec(line);
+        if (!m)
+            continue;
+        const rest = m[1].trim();
+        if (rest === '|' || rest === '>' || rest === '|-' || rest === '>-') {
+            /* Bloque: todo lo que sigue con mas sangria. */
+            const indent = (/^(\s*)/.exec(line)[1] ?? '').length;
+            for (let j = i + 1; j < lines.length; j++) {
+                const l = lines[j];
+                if (!l.trim())
+                    continue;
+                const ind = (/^(\s*)/.exec(l)[1] ?? '').length;
+                if (ind <= indent)
+                    break;
+                if (!/^\s*#/.test(l))
+                    out.push(l.trim());
+                i = j;
+            }
+            continue;
+        }
+        out.push(rest);
+    }
+    return out;
+}
+/** Los valores de una clave escalar repetida (`runs-on:`, `node-version:`),
+ *  deduplicados y sin comillas. */
+function scalarValues(yaml, key) {
+    const out = [];
+    const re = new RegExp('^\\s*' + key + ':\\s*([^\\n#]+)$', 'gim');
+    let m;
+    while ((m = re.exec(yaml)) !== null) {
+        const v = m[1].trim().replace(/^['"]|['"]$/g, '');
+        if (v && !v.startsWith('$') && !out.includes(v))
+            out.push(v);
+    }
+    return out;
+}
+/** El `on:` del workflow: en que ramas dispara cada evento. Atajo sobre el
+ *  YAML, igual que `runLines`, y por el mismo motivo: un parser completo
+ *  seria una dependencia nueva para leer cuatro lineas, y el caso corre
+ *  sobre el archivo real, asi que una forma que esto no entienda sale roja
+ *  en vez de salir en silencio. */
+export function readTriggers(yaml) {
+    const lines = yaml.split(/\r?\n/);
+    const start = lines.findIndex((l) => /^on:\s*$/.test(l) || /^on:\s*\S/.test(l));
+    const res = { push: [], pull_request: [], other: [] };
+    if (start < 0)
+        return res;
+    /* `on: [push]` en una linea. */
+    const inline = /^on:\s*\[([^\]]*)\]/.exec(lines[start]);
+    if (inline) {
+        for (const ev of inline[1].split(',').map((s) => s.trim()).filter(Boolean))
+            res.other.push(ev);
+        return res;
+    }
+    let event = null;
+    for (let i = start + 1; i < lines.length; i++) {
+        const l = lines[i];
+        if (/^\S/.test(l) && l.trim())
+            break;
+        if (/^\s*#/.test(l))
+            continue;
+        const ev = /^\s{2}([a-z_]+):/.exec(l);
+        if (ev) {
+            const name = ev[1];
+            event = name === 'push' || name === 'pull_request' ? name : null;
+            if (!event && !res.other.includes(name))
+                res.other.push(name);
+            continue;
+        }
+        const br = /^\s*branches:\s*\[([^\]]*)\]/.exec(l);
+        if (br && event) {
+            for (const b of br[1].split(',').map((s) => s.trim().replace(/^['"]|['"]$/g, '')).filter(Boolean)) {
+                res[event].push(b);
+            }
+        }
+    }
+    return res;
+}
+/** Derivar las tres listas y su diferencia. Tira cuando no puede medir: una
+ *  medicion imposible no se reporta como "no falta nada". */
+export function deriveCiGaps(input) {
+    const publishCmd = input.pkg.scripts?.['prepublishOnly'];
+    if (!publishCmd) {
+        throw new Error('no se puede medir: package.json no tiene `prepublishOnly`, '
+            + 'que es la lista de compuertas contra la que se compara la cadena');
+    }
+    if (!input.workflow.trim()) {
+        throw new Error('no se puede medir: el workflow de CI vino vacio');
+    }
+    const scripts = input.pkg.scripts ?? {};
+    const publishGates = scriptsInvoked(publishCmd);
+    const ran = [...new Set(runLines(input.workflow).flatMap(scriptsInvoked))];
+    /* Lo que el gancho CORRE, en programas (no en nombres de script): asi un
+     * `node scripts/catalog_lint.mjs` en el gancho cuenta como la compuerta
+     * `catalog:lint`, y `build` cuenta como `typecheck` porque corre el mismo
+     * tsc. El gancho invoca los scripts directo a proposito (arranca mas
+     * rapido que `pnpm run`), y eso no puede costarle credito en la
+     * declaracion -- ni ganarselo sin que se pueda explicar cual lo cubre. */
+    const hookLines = input.lefthook
+        ? runLines(preprocessLefthookPrePush(input.lefthook))
+        : [];
+    const hookInvocations = new Set(hookLines.flatMap((l) => invocationsOf(l, scripts)));
+    const lineSets = hookLines.map((l) => invocationsOf(l, scripts));
+    const sameSet = (a, b) => a.length === b.length && a.every((x) => b.includes(x));
+    const byEquivalence = [];
+    const hookDeclares = [];
+    for (const gate of publishGates) {
+        const needed = invocationsOf(scripts[gate] ?? gate, scripts);
+        if (!needed.length)
+            continue;
+        if (!needed.every((n) => hookInvocations.has(n)))
+            continue;
+        hookDeclares.push(gate);
+        /* DIRECTO: alguna linea del gancho corre exactamente eso. Si no, hay
+         * que poder decir QUIEN lo cubre -- un "lo cubre otro" sin nombre es la
+         * clase de afirmacion que este modulo existe para no repetir. */
+        if (lineSets.some((set) => sameSet(set, needed)))
+            continue;
+        const via = publishGates.find((other) => other !== gate
+            && needed.every((n) => invocationsOf(scripts[other] ?? other, scripts).includes(n))
+            && lineSets.some((set) => sameSet(set, invocationsOf(scripts[other] ?? other, scripts))));
+        byEquivalence.push({ gate, via: via ?? '(otro comando del gancho)' });
+    }
+    const notRun = publishGates.filter((g) => !ran.includes(g));
+    const hookNotRun = publishGates.filter((g) => !hookDeclares.includes(g));
+    return {
+        ran, not_run: notRun,
+        hook_declares: hookDeclares,
+        hook_covers_by_equivalence: byEquivalence,
+        hook_not_run: hookNotRun,
+        os: scalarValues(input.workflow, 'runs-on'),
+        node: scalarValues(input.workflow, 'node-version'),
+        nobody_runs: publishGates.filter((g) => !ran.includes(g) && !hookDeclares.includes(g)),
+        triggers: readTriggers(input.workflow),
+    };
+}
+/** Solo la seccion `pre-push` de lefthook.yml. El `pre-commit` corre en otro
+ *  momento y meterlo aca diria que el push verifica mas de lo que verifica,
+ *  que es el defecto, al revez. */
+export function preprocessLefthookPrePush(yaml) {
+    const lines = yaml.split(/\r?\n/);
+    const start = lines.findIndex((l) => /^pre-push:/.test(l));
+    if (start < 0)
+        return '';
+    const out = [];
+    for (let i = start + 1; i < lines.length; i++) {
+        const l = lines[i];
+        if (/^\S/.test(l) && l.trim())
+            break;
+        out.push(l);
+    }
+    return out.join('\n');
+}
+/** LA DECLARACION, con el formato que el dueno pidio textualmente.
+ *
+ *  Primero lo que SI se verifico y despues lo que NO, en ese orden y en la
+ *  misma salida: una lista de ausencias al final de un log de 300 lineas no
+ *  la lee nadie. */
+export function renderCiGaps(r) {
+    const out = [];
+    out.push('Esta corrida verifico: ' + (r.ran.length ? r.ran.join(', ') : '(ningun script del paquete)') + '.');
+    out.push('Plataforma cubierta: ' + (r.os.join(', ') || 'sin declarar')
+        + ' / Node ' + (r.node.join(', ') || 'sin declarar') + '.');
+    if (r.not_run.length) {
+        out.push('NO corrio: ' + r.not_run.join(', ')
+            + ' -- mas la matriz multi-OS y el barrido multi-Node (esta corrida es un solo par).');
+        out.push('Un verde aca NO significa que la bateria paso. La lista completa de compuertas');
+        out.push('es `prepublishOnly` en package.json; la directiva esta en docs/PROGRAMMING_NORMS.md.');
+    }
+    else {
+        out.push('NO corrio: nada -- la cadena cubre todas las compuertas de `prepublishOnly`.');
+    }
+    /* CUANDO dispara esta cadena. El cuarto hueco de F-15: si solo dispara en
+     * main y en PR a main, en una rama sin PR la cadena no es una segunda
+     * puerta -- no corre ninguna vez, y el gancho local es la UNICA puerta
+     * que tiene el trabajo en rama. Decirlo aca es el punto: el que lee esto
+     * esta mirando justamente una corrida que si existio. */
+    const t = r.triggers;
+    if (t.push.length || t.pull_request.length) {
+        out.push('Esta cadena dispara en: '
+            + [t.push.length ? 'push a ' + t.push.join('/') : '',
+                t.pull_request.length ? 'pull_request a ' + t.pull_request.join('/') : '',
+                ...t.other].filter(Boolean).join(' y ') + '.');
+        out.push('En una rama SIN PR no corre ninguna vez: ahi la unica puerta es el gancho');
+        out.push('local (a proposito -- la cadena se mantiene liviana por cuota; el motivo');
+        out.push('esta en docs/PROGRAMMING_NORMS.md).');
+    }
+    if (r.hook_declares.length) {
+        out.push('El gancho pre-push cubre: ' + r.hook_declares.join(', ')
+            + (r.hook_not_run.length ? ' (NO corre: ' + r.hook_not_run.join(', ') + ')' : ''));
+        for (const e of r.hook_covers_by_equivalence) {
+            out.push('  ' + e.gate + ' lo cubre `' + e.via + '`, que invoca el mismo programa.');
+        }
+    }
+    else {
+        out.push('El gancho pre-push no declara ninguna compuerta: lo pesado depende del habito, '
+            + 'no de un mecanismo.');
+    }
+    if (r.nobody_runs.length) {
+        out.push('NINGUNA de las dos puertas corre: ' + r.nobody_runs.join(', ')
+            + ' -- solo las corre `prepublishOnly`, es decir recien al publicar.');
+        out.push('Para eso esta el sello de la bateria (.forge/battery-stamp.json): antes de');
+        out.push('empaquetar, `scripts/battery_freshness.mjs` dice si lo que se publica es lo');
+        out.push('que la bateria vio.');
+    }
+    return out.join('\n');
+}
+//# sourceMappingURL=ci_gaps.js.map

package/dist/core/ci_gaps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ci_gaps.js","sourceRoot":"","sources":["../../src/core/ci_gaps.ts"],"names":[],"mappings":"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"}

package/dist/core/doc_citations.d.ts

@@ -0,0 +1,133 @@
+/**
+ * LAS CITAS A LA NADA -- la compuerta que el dueno pidio (2026-11-01).
+ *
+ * EL DEFECTO, en sus palabras: "un documento que afirma una compuerta con
+ * confianza es mas convincente que uno que falta. La ausencia se nota; la
+ * afirmacion falsa no." Van tres citas a la nada medidas en dos lotes
+ * -- `docs/PROGRAMMING_NORMS.md` citado por `.github/workflows/ci.yml` cinco
+ * meses sin existir, cuatro jobs y dos crons descritos en
+ * `docs/CI_PIPELINE.md` que nunca existieron, y un comentario de
+ * `.github/workflows/ci.yml` al que remitia `CLAUDE.md` -- y las tres
+ * describian compuertas. Esta compuerta cierra la familia: todo archivo de
+ * este repositorio citado en un documento VIGENTE tiene que existir.
+ *
+ * POR QUE EL DETECTOR ES CONSERVADOR. Una compuerta ruidosa se desactiva, y
+ * un gancho desactivado es peor que ninguno porque figura como existente
+ * (el mismo argumento con el que el dueno acoto F-15). Asi que esto NO
+ * intenta encontrar toda cita: encuentra las que son inequivocamente una
+ * afirmacion sobre ESTE repositorio HOY. Las reglas, en orden:
+ *
+ *   1. Los bloques de codigo cercados no se miran. Un `ls docs/FOO.md` de
+ *      ejemplo no es una afirmacion sobre el repositorio.
+ *   2. Solo cuentan los tramos entre acentos graves y los destinos de los
+ *      enlaces markdown. Una ruta en prosa suelta no se toca.
+ *   3. Con `/`: el primer segmento tiene que ser un directorio que EXISTE en
+ *      la raiz y no ser generado (`dist/`, `test-results/`, `.forge/`...).
+ *      La cita afirma una UBICACION, asi que se verifica tal cual.
+ *      Sin `/`: es un NOMBRE, no una ubicacion, y se verifica como tal --
+ *      basta que un archivo con ese nombre exista en algun lugar del
+ *      repositorio. Medido: tratar `claude.ts` como archivo de la raiz daba
+ *      cientos de falsos positivos, y descartarlo del todo dejaba pasar
+ *      nombres que ya no existen en ninguna parte (`relay_error.ts`).
+ *   4. Nada con comodin (`*`, `?`), hueco (`<x>`, `{x}`, `$x`), dos puntos
+ *      (rutas de Windows, `repo:ruta`) ni esquema (`http://`). Son formas
+ *      que no afirman un archivo concreto.
+ *
+ * Y LOS DOCUMENTOS HISTORICOS NO ENTRAN, por una razon que no es comodidad:
+ * un changelog, un traspaso o un informe fechado describen el estado del
+ * repositorio EN SU FECHA, y un archivo que existia entonces y se renombro
+ * despues es historia correcta, no una cita a la nada. Medido: de 2378 citas
+ * verificables, 762 estaban muertas y la enorme mayoria vivia justamente
+ * ahi. Meterlas obligaria a una lista de permisos de cientos de entradas sin
+ * motivo real, que es la misma afirmacion sin respaldo que esto persigue. La
+ * exclusion se DECLARA (`isHistoricalDoc`) y la corrida dice cuantos
+ * documentos salteo, nunca en silencio.
+ *
+ * ASCII-only.
+ */
+export interface DocCitation {
+    /** Linea 1-indexada donde aparece la cita. */
+    line: number;
+    /** La ruta citada, relativa a la raiz del repositorio, sin ancla. */
+    target: string;
+    /** El texto tal como estaba, para el mensaje de error. */
+    raw: string;
+    /** `path` se verifica en su ubicacion; `name` por nombre en cualquier
+     *  lugar del repositorio. */
+    shape: 'path' | 'name';
+}
+/** Directorios de la raiz que existen pero NO son fuente: lo que hay dentro
+ *  lo genera una corrida o lo escribe un producto en ejecucion, asi que un
+ *  documento puede nombrarlos legitimamente sin que esten en disco. */
+export declare const GENERATED_ROOTS: string[];
+/** La forma de la cita, o el motivo por el que no es una cita verificable. */
+export declare function classifyToken(token: string, rootDirs: string[]): 'path' | 'name' | {
+    reject: string;
+};
+/** Las citas verificables de un documento markdown. */
+export declare function extractCitations(md: string, rootDirs: string[]): DocCitation[];
+/** Un documento que describe el estado del repositorio en su fecha, no hoy.
+ *  La lista es de FORMAS de nombre, no de rutas: una lista de rutas se
+ *  desactualiza con cada documento nuevo y acaba siendo una lista de
+ *  permisos. */
+export declare function isHistoricalDoc(rel: string): boolean;
+/** Las citas de un archivo de MAQUINARIA (workflow, lefthook, manifiesto):
+ *  ahi una ruta no viene entre acentos graves, viene en un comentario o en
+ *  un valor. Se buscan por forma y se pasan por el mismo clasificador.
+ *
+ *  Esto NO se usa sobre fuentes TypeScript a proposito: un especificador de
+ *  import (`./tools/x.js`) tiene forma de ruta, es relativo al archivo y
+ *  apunta al transpilado, asi que daria cientos de falsos positivos.
+ *  Medido antes de acotar: 307.
+ *
+ *  Y aca la cita tiene que llevar EXTENSION. En un archivo de maquinaria no
+ *  hay acentos graves que delimiten el token, asi que un tramo sin extension
+ *  suele ser otra cosa con forma de ruta -- medido: `src/version\.ts` dentro
+ *  de una expresion regular de `lefthook.yml` se lee como `src/version`. Las
+ *  tres citas a la nada que este repositorio ya pago llevaban extension. */
+export declare function extractMachineryCitations(text: string, rootDirs: string[]): DocCitation[];
+/** EL ALCANCE QUE BLOQUEA, y por que es este y no "todos los documentos".
+ *
+ *  Medido en este repositorio: de 1331 citas verificables en documentos
+ *  vigentes, 206 apuntan a archivos que no existen -- y casi todas son
+ *  correctas. El espacio `docs/` esta SOBRECARGADO: `docs/SQ.md` exige
+ *  `docs/USER_MANUAL.md` al proyecto ADOPTANTE, `src/urazuke/catalog.ts`
+ *  nombra `docs/GATES.md` como artefacto que produce el proyecto que corre
+ *  el metodo, y `docs/worker/README.md` cita `src/relay.js` relativo a su
+ *  propio componente. Prescribir rutas para otros proyectos es el negocio
+ *  de este repositorio, asi que "toda ruta citada existe" es FALSO como
+ *  regla general y una compuerta que lo exija pide una lista de permisos de
+ *  cientos de entradas -- que es la misma afirmacion sin respaldo que esto
+ *  persigue.
+ *
+ *  Lo que si se puede exigir sin excepciones es este conjunto: los archivos
+ *  que se leen como AUTORIDAD sobre la maquinaria de este repositorio. Es
+ *  donde vivieron los tres defectos medidos y es chico y verificable. El
+ *  resto se MIDE y se informa en la misma salida, nunca en silencio.
+ *
+ *  Y dentro de ese conjunto bloquean solo las citas con forma de RUTA. Un
+ *  nombre suelto (`nac-bridge.js`, `pilot.bundle.js` en el README) no afirma
+ *  una ubicacion de este repositorio: nombra un artefacto de otro paquete.
+ *  Una ruta si afirma: dice "esta aca". Esa es la afirmacion que las tres
+ *  citas a la nada hicieron y la que esto verifica. */
+export declare const AUTHORITY_SCOPE: string[];
+export interface CitationViolation extends DocCitation {
+    /** El documento que contiene la cita, relativo a la raiz. */
+    doc: string;
+}
+/** El resultado de la compuerta. `checked` y `skipped` son load-bearing: una
+ *  corrida que no miro nada NO es una corrida sin violaciones. */
+export interface CitationReport {
+    /** El alcance que bloquea. */
+    authority_files: number;
+    authority_checked: number;
+    violations: CitationViolation[];
+    allowed: number;
+    /** El relevamiento informativo sobre los documentos vigentes. */
+    survey_docs: number;
+    survey_skipped_historical: number;
+    survey_checked: number;
+    survey_dead: number;
+}
+export declare function renderCitationReport(r: CitationReport): string;
+//# sourceMappingURL=doc_citations.d.ts.map

package/dist/core/doc_citations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doc_citations.d.ts","sourceRoot":"","sources":["../../src/core/doc_citations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAEH,MAAM,WAAW,WAAW;IAC1B,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,qEAAqE;IACrE,MAAM,EAAE,MAAM,CAAC;IACf,0DAA0D;IAC1D,GAAG,EAAE,MAAM,CAAC;IACZ;iCAC6B;IAC7B,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;CACxB;AAED;;uEAEuE;AACvE,eAAO,MAAM,eAAe,UAE3B,CAAC;AAcF,8EAA8E;AAC9E,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,MAAM,GAAG;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CA8BrG;AAED,uDAAuD;AACvD,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,WAAW,EAAE,CAgC9E;AAED;;;gBAGgB;AAChB,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAepD;AAED;;;;;;;;;;;;;4EAa4E;AAC5E,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,WAAW,EAAE,CAezF;AAED;;;;;;;;;;;;;;;;;;;;;;;uDAuBuD;AACvD,eAAO,MAAM,eAAe,UAS3B,CAAC;AAEF,MAAM,WAAW,iBAAkB,SAAQ,WAAW;IACpD,6DAA6D;IAC7D,GAAG,EAAE,MAAM,CAAC;CACb;AAED;kEACkE;AAClE,MAAM,WAAW,cAAc;IAC7B,8BAA8B;IAC9B,eAAe,EAAE,MAAM,CAAC;IACxB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,UAAU,EAAE,iBAAiB,EAAE,CAAC;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,WAAW,EAAE,MAAM,CAAC;IACpB,yBAAyB,EAAE,MAAM,CAAC;IAClC,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,cAAc,GAAG,MAAM,CAyB9D"}