@pareto4/pp-core 1.22.0 → 1.23.1

package/pp-core/bin/lib/gate-card.cjs

@@ -0,0 +1,97 @@
+"use strict";
+/**
+ * `pp-tools gate-card <query>`: the stopped-check card in the person's wording
+ * (Phase 43: D-11, TPL-02).
+ *
+ * ADR-457 build-at-publish: this TypeScript file is the SOURCE OF TRUTH. It
+ * compiles to the gitignored `pp-core/bin/lib/gate-card.cjs`; do NOT hand-edit
+ * the compiled output.
+ *
+ * Like `audience fields`, it prints nothing for a developer, so a workflow fence
+ * that calls it prints no extra line for a developer (D-03). Every word comes
+ * from the `gate` catalog slice through `msg()` / `text()` (D-10); this verb never
+ * composes wording. Codes are looked up only through the catalog Map (`has`), and
+ * the query only through `GATE_QUERIES.includes`, so `__proto__`, `constructor`
+ * and an unknown name print nothing (T-43-10). The query argument is never echoed
+ * on any path, including usage errors (T-43-11). The no-state output is one
+ * `JSON.stringify` line, so card text cannot forge a line of its own (T-43-12).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.USAGE = void 0;
+exports.cardsFor = cardsFor;
+exports.cmdGateCard = cmdGateCard;
+const messages_cjs_1 = require("./messages.cjs");
+const gate_cjs_1 = require("./messages/gate.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const io = require("./io.cjs");
+const { output, ERROR_REASON } = io;
+/** Explicitly typed so TypeScript narrows after a failing guard (the destructured `io.error` does not). */
+function error(message, reason) {
+    return io.error(message, reason);
+}
+exports.USAGE = "Usage: pp-tools gate-card <query> [--state blocked|advisory|error] [--details] [--raw] — the stopped-check card in the person's wording; prints nothing for a developer";
+/**
+ * The cards of one query, keyed by state; null for a developer or an unknown query.
+ * Only the states the query defines appear.
+ */
+function cardsFor(query, audience) {
+    if (audience === 'developer')
+        return null;
+    if (!gate_cjs_1.GATE_QUERIES.includes(query))
+        return null;
+    const cards = {};
+    for (const state of gate_cjs_1.GATE_STATES) {
+        const code = `gate.${query}.${state}`;
+        if ((0, messages_cjs_1.has)(code))
+            cards[state] = { code, text: (0, messages_cjs_1.text)(code, {}, { audience }) };
+    }
+    return cards;
+}
+function cmdGateCard(_cwd, args, raw) {
+    let query = null;
+    let state = null;
+    let details = false;
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === '--raw')
+            continue;
+        if (a === '--details') {
+            details = true;
+        }
+        else if (a === '--state') {
+            const next = args[i + 1];
+            if (next === undefined || !gate_cjs_1.GATE_STATES.includes(next))
+                error(exports.USAGE, ERROR_REASON.USAGE);
+            state = next;
+            i++;
+        }
+        else if (a.startsWith('-')) {
+            error(exports.USAGE, ERROR_REASON.USAGE);
+        }
+        else if (query === null) {
+            query = a;
+        }
+        else {
+            error(exports.USAGE, ERROR_REASON.USAGE);
+        }
+    }
+    if (query === null)
+        error(exports.USAGE, ERROR_REASON.USAGE);
+    const audience = (0, messages_cjs_1.audienceOf)(process.env);
+    const cards = cardsFor(query, audience);
+    if (cards === null)
+        return;
+    if (state === null) {
+        output(cards, true, JSON.stringify(cards) + '\n');
+        return;
+    }
+    const card = Object.prototype.hasOwnProperty.call(cards, state) ? cards[state] : undefined;
+    if (card === undefined)
+        return;
+    const body = (0, messages_cjs_1.msg)(card.code, {}, { audience });
+    if (raw) {
+        output({ code: card.code, text: body }, false);
+        return;
+    }
+    output({ code: card.code, text: body }, true, body + (details ? '\nDetails:' : '') + '\n');
+}

package/pp-core/bin/lib/hook-messages.cjs

@@ -0,0 +1,132 @@
+"use strict";
+/**
+ * The hooks' light catalog entry (Phase 43, MSG-06; D-18, D-20).
+ *
+ * ADR-457 build-at-publish: this TypeScript file is the SOURCE OF TRUTH. It
+ * compiles to the gitignored `pp-core/bin/lib/hook-messages.cjs`; do NOT
+ * hand-edit the compiled output.
+ *
+ * The statusline runs on every prompt, so it cannot load the whole catalog
+ * (`messages.cjs` pulls in every slice, ~73 KB). This module imports only
+ * `./audience.cjs`, `./message-labels.cjs` and `./messages/hook.cjs`, plus
+ * `import type { CatalogEntry } from './messages.cjs'`, which compiles away.
+ * It carries its own copy of the engine's control-character regex, slot regex,
+ * ECHO_CAP, sanitise, fill and pick (about 25 lines), kept equal to
+ * `src/messages.cts` by the parity test in tests/hook-messages.test.cjs
+ * (PITFALLS #19).
+ *
+ * Its functions never throw: an unknown code, a bad param or an unreadable
+ * person file returns the fallback text. The hooks wrap their calls in
+ * try/catch as well and fall back to today's text when this module cannot load
+ * (D-20).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.audienceOf = audienceOf;
+exports.developerText = developerText;
+exports.text = text;
+exports.msg = msg;
+exports.label = label;
+exports.statusWord = statusWord;
+const audience_cjs_1 = require("./audience.cjs");
+const message_labels_cjs_1 = require("./message-labels.cjs");
+const hook_cjs_1 = require("./messages/hook.cjs");
+// Copies of the engine's constants; see the header.
+const CONTROL_CHARS_RE = /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f-\x9f\p{Cf}]/gu;
+const SLOT_RE = /\{([a-z][a-z0-9_]*)\}/g;
+const ECHO_CAP = 120;
+/** The shape ship.md writes into the STATE.md status: `Phase N shipped — PR #N`. Anchored, linear. */
+const SHIPPED_STATUS_RE = /^Phase (\S+) shipped — PR #(\d+)$/;
+// Lookup only: a Map, so `__proto__` and `constructor` are unknown codes.
+const ENTRIES = new Map(Object.entries(hook_cjs_1.hook));
+function sanitize(value) {
+    let raw;
+    if (typeof value === 'number')
+        raw = String(value);
+    else if (typeof value === 'string')
+        raw = value;
+    else
+        return '';
+    const collapsed = raw.replace(CONTROL_CHARS_RE, '').replace(/\s+/g, ' ').trim();
+    return collapsed.length <= ECHO_CAP ? collapsed : `${collapsed.slice(0, ECHO_CAP)}…`;
+}
+function fill(template, params, clean) {
+    return template.replace(SLOT_RE, (match, name) => {
+        if (!Object.hasOwn(params, name))
+            return clean ? match : '';
+        const value = params[name];
+        if (!clean)
+            return typeof value === 'string' || typeof value === 'number' ? String(value) : '';
+        return sanitize(value);
+    });
+}
+function pick(entry, audience) {
+    if (audience === 'business')
+        return entry.business ?? entry.engineer ?? entry.developer;
+    if (audience === 'engineer')
+        return entry.engineer ?? entry.developer;
+    return entry.developer;
+}
+/** The audience for this process; developer on any failure. */
+function audienceOf(env = process.env) {
+    try {
+        return (0, audience_cjs_1.resolveAudience)(env, (0, audience_cjs_1.readPerson)(env)).audience;
+    }
+    catch {
+        return 'developer';
+    }
+}
+/** The developer text, params untouched. An unknown code returns the code. */
+function developerText(code, params = {}) {
+    const entry = ENTRIES.get(code);
+    if (entry === undefined)
+        return code;
+    return fill(entry.developer, params ?? {}, false);
+}
+/** The text for an audience with no Ref line. An unknown code returns the code. */
+function text(code, params = {}, audience = 'developer') {
+    const entry = ENTRIES.get(code);
+    if (entry === undefined)
+        return code;
+    if (audience === 'developer')
+        return developerText(code, params);
+    return fill(pick(entry, audience), params ?? {}, true);
+}
+/**
+ * The message for an audience: business and engineer messages that are not
+ * parts end with the Ref line. An unknown code returns `fallback` when it is a
+ * string, else the code.
+ */
+function msg(code, params = {}, audience = 'developer', fallback) {
+    const entry = ENTRIES.get(code);
+    if (entry === undefined)
+        return typeof fallback === 'string' ? fallback : code;
+    if (audience === 'developer')
+        return developerText(code, params);
+    const body = text(code, params, audience);
+    return entry.part === true ? body : `${body}\nRef: ${code}`;
+}
+/** The display word for a canonical value; the value itself for a developer, an unknown domain or an unknown value. */
+function label(domain, canonical, audience = 'developer') {
+    try {
+        return (0, message_labels_cjs_1.label)(domain, canonical, { audience });
+    }
+    catch {
+        return canonical;
+    }
+}
+/**
+ * The display text for a STATE.md `status`. A lifecycle word is relabelled
+ * through `state.status`; the ship shape renders through
+ * `hook.statusline.status_shipped`; anything else shows as written. A non-string
+ * returns ''.
+ */
+function statusWord(status, audience = 'developer') {
+    if (typeof status !== 'string')
+        return '';
+    if (audience === 'developer')
+        return status;
+    const shipped = SHIPPED_STATUS_RE.exec(status);
+    if (shipped !== null)
+        return text('hook.statusline.status_shipped', { number: shipped[1], pr: shipped[2] }, audience);
+    return label('state.status', status, audience);
+}