@xano/cli 1.3.4 → 1.3.5-beta.1

package/dist/utils/policy/coverage.js

@@ -0,0 +1,93 @@
+import { coverageFindingLines } from './findings.js';
+/** An object as findings name it, `type:id` (`query:42`), or `null` when the text is not one. */
+export function parseObjectRef(text) {
+    const match = /^([a-z_]+):(\d+)$/i.exec(text.trim());
+    if (!match)
+        return null;
+    const id = Number(match[2]);
+    return Number.isSafeInteger(id) && id > 0 ? { id, type: match[1].toLowerCase() } : null;
+}
+const count = (value) => value ?? 0;
+/** The object coverage chip, worded as Studio's object panel words it. */
+export function coverageChip(summary) {
+    switch (summary?.state) {
+        case 'check_failed': {
+            return 'Policies · Last check failed';
+        }
+        case 'findings': {
+            return `Policies ${count(summary.blocking)} blocking · ${count(summary.advisory)} advisory`;
+        }
+        case 'none_apply': {
+            return 'Policies · None apply';
+        }
+        case 'not_checked': {
+            return `Policies · ${count(summary.applies)} apply · not checked yet`;
+        }
+        case 'pass': {
+            return `Policies ✓ ${count(summary.passing)} pass`;
+        }
+        default: {
+            return `Policies · ${summary?.state ?? 'unknown'}`;
+        }
+    }
+}
+const STATUS = {
+    could_not_check: "couldn't check",
+    failing: 'failing',
+    not_checked: 'not checked yet',
+    passing: 'passing',
+};
+/**
+ * The policies that apply with no finding here, counted from the summary as Studio's panel words its
+ * line under the findings: "6 passing · 1 couldn't check · 1 not checked yet". Empty when it counts none.
+ */
+export function coverageCounts(summary) {
+    const counted = [
+        [summary?.passing, 'passing'],
+        [summary?.could_not_check, "couldn't check"],
+        [summary?.not_checked, 'not checked yet'],
+    ];
+    return counted
+        .filter(([value]) => count(value) > 0)
+        .map(([value, label]) => `${value} ${label}`)
+        .join(' · ');
+}
+function policyLines(policy) {
+    const enforcement = policy.blocking ? 'Blocking' : 'Advisory';
+    const status = STATUS[policy.status ?? ''] ?? policy.status ?? '';
+    return [
+        `  ${[policy.key, enforcement, status, policy.title].filter(Boolean).join('  ')}`,
+        ...(policy.reasons ?? []).map(reason => `    Applies: ${reason}`),
+    ];
+}
+function objectName(object) {
+    if (!object)
+        return 'object';
+    const name = object.name ? ` ${object.name}` : '';
+    return `${object.type ?? 'object'}${name}${object.id ? ` (id ${object.id})` : ''}`;
+}
+/**
+ * An object's coverage on stdout: the chip, the run it reads, the findings Blocking then Advisory,
+ * each with its fix, the policies that apply (counted, then each with its status and why), and the
+ * platform's note.
+ */
+export function coverageLines(answer) {
+    const lines = [`${objectName(answer.object)}: ${coverageChip(answer.summary)}`];
+    lines.push(answer.run
+        ? `Latest run: ${answer.run.started_at ?? 'unknown time'} (${answer.run.status ?? 'unknown'}); changes made since are not included.`
+        : 'No run yet: the branch has never been checked.');
+    const findings = answer.findings ?? [];
+    const blocking = findings.filter(finding => finding.blocking === true);
+    const advisory = findings.filter(finding => finding.blocking !== true);
+    if (blocking.length > 0)
+        lines.push(`Blocking findings (${blocking.length}):`, ...blocking.flatMap(finding => coverageFindingLines(finding)));
+    if (advisory.length > 0)
+        lines.push(`Advisory findings (${advisory.length}):`, ...advisory.flatMap(finding => coverageFindingLines(finding)));
+    const policies = answer.policies ?? [];
+    const counts = coverageCounts(answer.summary);
+    if (policies.length > 0)
+        lines.push(`Policies that apply (${policies.length}):${counts ? ` ${counts}` : ''}`, ...policies.flatMap(policy => policyLines(policy)));
+    if (answer.note?.trim())
+        lines.push(answer.note.trim());
+    return lines;
+}

package/dist/utils/policy/errors.d.ts

@@ -0,0 +1,20 @@
+/** Guidance appended to a refusal whose `payload.code` the CLI has advice for, or `''`. */
+export declare function policyCodeGuidance(payload: unknown): string;
+/**
+ * The CLI's own sentence for a refusal that names policies, keyed on the platform's `payload.code`,
+ * or `null` to print the platform's coded message (also when the payload lacks the names):
+ *
+ *   policy_duplicate   a new policy's rules exactly match a policy the branch has
+ *   policy_key_taken   another live policy of the branch holds the key
+ */
+export declare function policyRefusal(payload: unknown): null | string;
+/** A failed policy-route response: one message to print, and the refusal's payload. */
+export interface PolicyError {
+    message: string;
+    payload?: unknown;
+}
+/**
+ * A failed policy-route response as one message: the platform's code and message, and where a parse
+ * error is. Traces are dropped, and an empty 404 names the branch the request selected.
+ */
+export declare function describePolicyError(text: string, status: number, requestUrl: string): PolicyError;

package/dist/utils/policy/errors.js

@@ -0,0 +1,93 @@
+/** Keep backend implementation details out of ordinary command errors. */
+function withoutStack(text) {
+    return text.split(/\n\s*(?:Stack trace:|#\d+\s|at\s|file:\s*\/)/i, 1)[0];
+}
+/** Where a parse error is: the payload's 1-based `line` and `col`, printed as served, and the offending text. */
+function positionLine(payload) {
+    const text = [payload.error_line, payload.error_snippet, payload.snippet]
+        .find(value => typeof value === 'string' && value.trim() !== '');
+    const where = typeof payload.line === 'number' && Number.isFinite(payload.line)
+        ? `line ${payload.line}${typeof payload.col === 'number' && Number.isFinite(payload.col) ? `, col ${payload.col}` : ''}`
+        : '';
+    if (!where && text === undefined)
+        return '';
+    return `\n  ${where ? `at ${where}` : 'at'}${text === undefined ? '' : `: ${text}`}`;
+}
+/** An empty 404 from a branch-scoped request means the branch it named does not exist. */
+function missingBranch(requestUrl) {
+    const url = new URL(requestUrl);
+    const workspace = url.pathname.match(/\/workspace\/([^/]+)/)?.[1];
+    const branch = url.searchParams.get('branch');
+    return workspace && branch ? `Branch "${branch}" was not found in workspace ${decodeURIComponent(workspace)}.` : '';
+}
+/**
+ * What to do about a refusal of the request itself, keyed on the platform's `payload.code`:
+ *
+ *   policy_unknown_check   a rule names a check id this instance does not have
+ *   policy_stale           the policy changed after the command read it
+ *
+ * Permission refusals are explained by `policyPermissionGuidance`.
+ */
+const CODE_GUIDANCE = {
+    policy_stale: '\nThe policy changed after this command read it, so nothing was changed. Run the command again to act on its current version.',
+    policy_unknown_check: '\nRun `xano policy catalogue` to list every check id this instance has.',
+};
+/** Guidance appended to a refusal whose `payload.code` the CLI has advice for, or `''`. */
+export function policyCodeGuidance(payload) {
+    const code = payload && typeof payload === 'object' && !Array.isArray(payload) ? payload.code : undefined;
+    return typeof code === 'string' && Object.hasOwn(CODE_GUIDANCE, code) ? CODE_GUIDANCE[code] : '';
+}
+/** A payload string worth naming, trimmed, or `''`. */
+function named(value) {
+    return typeof value === 'string' ? value.trim() : '';
+}
+/**
+ * The CLI's own sentence for a refusal that names policies, keyed on the platform's `payload.code`,
+ * or `null` to print the platform's coded message (also when the payload lacks the names):
+ *
+ *   policy_duplicate   a new policy's rules exactly match a policy the branch has
+ *   policy_key_taken   another live policy of the branch holds the key
+ */
+export function policyRefusal(payload) {
+    if (!payload || typeof payload !== 'object' || Array.isArray(payload))
+        return null;
+    const refusal = payload;
+    const existing = named(refusal.existing_key);
+    if (!existing)
+        return null;
+    if (refusal.code === 'policy_duplicate') {
+        const copies = Array.isArray(refusal.policies) ? refusal.policies : [];
+        const tried = named(copies[0]?.key);
+        return `${tried ? `Policy ${tried}` : 'The policy'} was not created: its rules exactly match ${existing}, which this branch already has. `
+            + 'Change a parameter or scope to add a different policy (for policy create, --param N.path=JSON); its key does not count.';
+    }
+    if (refusal.code === 'policy_key_taken') {
+        const tried = named(refusal.key) || existing;
+        const id = typeof refusal.existing_id === 'number' ? ` (policy id ${refusal.existing_id})` : '';
+        return `Policy ${tried} was not saved: this branch already has ${existing}${id}. `
+            + `Choose a key no policy has (for policy create, --key), or update ${existing} with policy publish.`;
+    }
+    return null;
+}
+/**
+ * A failed policy-route response as one message: the platform's code and message, and where a parse
+ * error is. Traces are dropped, and an empty 404 names the branch the request selected.
+ */
+export function describePolicyError(text, status, requestUrl) {
+    let data;
+    try {
+        data = JSON.parse(text.trim() || '{}');
+    }
+    catch {
+        return { message: withoutStack(text) };
+    }
+    if (!data || typeof data !== 'object' || Array.isArray(data))
+        return { message: withoutStack(text) };
+    const { code, message: raw, payload } = data;
+    let message = typeof raw === 'string' ? withoutStack(raw) : '';
+    if (status === 404 && !message.trim())
+        message = missingBranch(requestUrl);
+    const headline = [typeof code === 'string' ? code : '', message].filter(Boolean).join(': ');
+    const position = payload && typeof payload === 'object' ? positionLine(payload) : '';
+    return { message: `${headline}${position}` || 'The server returned no message.', payload };
+}

package/dist/utils/policy/feedback.d.ts

@@ -0,0 +1,90 @@
+import type { PolicyEvaluation, PolicyFinding, PolicyRuleResult, PolicySnapshotPolicy, PolicyVerdict, PushPolicyCheck } from './types.js';
+/** 2 whenever the platform says a finding blocks, whatever the status; every other outcome is 0. */
+export declare function policyExitCode(check?: PolicyVerdict): number;
+/**
+ * The one warning line for feedback without a headline (`disabled`, `unavailable`, `error`, an
+ * unknown status such as an older platform's `forbidden`, or a pass or fail that does not say whether
+ * it blocks): the server's own status and message, or that none came back. `null` for headlined
+ * feedback.
+ */
+export declare function policyCheckWarning(check?: PolicyVerdict): null | string;
+/**
+ * What happened to the policy documents a push carried. The preview says, per policy, whether it was
+ * created, updated or left unchanged. Without a preview only the number sent is known: the import
+ * response reports an unchanged policy exactly as it reports a saved one.
+ */
+export declare function policyDocumentSummary(preview: null | {
+    operations: Array<{
+        action: string;
+        name: string;
+        type: string;
+    }>;
+}, sentPolicies: number): string[];
+/** What a verdict is about: its findings, which of them block, and the rule results. */
+export interface PolicyEvidence {
+    /** The ids of the findings that block. */
+    blocking: Set<string>;
+    /**
+     * When the answer lists only the first findings: how many there are in all, and how many block.
+     * The stored run (`runId`, 0 when nothing was stored) has them all.
+     */
+    cut?: {
+        blocking: number;
+        findings: number;
+        runId: number;
+    };
+    /** In the platform's order: blocking first, then by severity. */
+    findings: PolicyFinding[];
+    results: PolicyRuleResult[];
+    /** The run's own `policies[]`, which names unnamed rules; a push answers none. */
+    snapshot: PolicySnapshotPolicy[];
+    /**
+     * The answer to a caller without `workspace:policy` read (`access: "coverage"`): its own findings
+     * on the pushed objects, trimmed, with no run to read (`run_id` 0) and no rule results, the
+     * platform's `note` on what it leaves out, how many rules could not run on the branch, and how
+     * many findings there are on the objects it does not list (`elsewhere`, never named): those the
+     * push introduced when `basis` is `introduced`, otherwise every one (no baseline, or an older platform).
+     */
+    trimmed?: {
+        elsewhere: {
+            blocking: number;
+            introduced: boolean;
+            total: number;
+        };
+        errors: number;
+        note: string;
+    };
+}
+/**
+ * A push answers no run, so its `policy_check` carries the findings and results itself: the first
+ * 100 of each list, with `counts` and `total` saying what they are out of.
+ */
+export declare function pushEvidence(check?: PushPolicyCheck): PolicyEvidence;
+/**
+ * A push's `policy_check` for a caller without `workspace:policy` read: only that caller's findings
+ * on the objects the push carried, and no run it may read.
+ */
+export declare function isCoverageCheck(check?: PushPolicyCheck): boolean;
+/**
+ * An evaluation answers the run, and its verdict names the blocking findings by id. Its summary
+ * answer (`--summary`) lists the first findings, and its counts say what they are out of.
+ */
+export declare function evaluationEvidence(evaluation: PolicyEvaluation): PolicyEvidence;
+/**
+ * The feedback on stdout: a headline with the server's message, then any findings, errors and
+ * warnings. Feedback without a headline is reported by `policyCheckWarning` instead.
+ */
+export declare function policySummary(check: PolicyVerdict | undefined, evidence: PolicyEvidence): string[];
+/**
+ * The platform's one notice that a push or its dry run left policy files out
+ * (`policies_skipped.message`): a push to a remote tenant or to a tenant without a policy table, a
+ * `release push` by a caller without `workspace:policy` create and update (its release carries the
+ * live branch's policies instead), and any push while the Policies feature is off. `null` when it
+ * left none out.
+ */
+export declare function policiesSkippedNotice(answer: unknown): null | string;
+/**
+ * The line for an evaluation that ran but was not recorded (the credential may read, not write), or
+ * `null`. A branch with nothing to evaluate stores nothing either, and its headline says so.
+ */
+export declare function notStoredLine(evaluation: PolicyEvaluation): null | string;

package/dist/utils/policy/feedback.js

@@ -0,0 +1,210 @@
+import { coverageFindingLines, findingLine, hasNoObjects, policyResultSummary, snapshotRules } from './findings.js';
+/**
+ * Feedback printed as a headline: a pass or fail that says whether its findings block, or a branch
+ * with no active policy to evaluate. Everything else is reported by `policyCheckWarning`.
+ */
+function isHeadlined(check) {
+    if (check.status === 'not_applicable')
+        return true;
+    return ['fail', 'pass'].includes(check.status ?? '') && typeof check.blocking === 'boolean';
+}
+/** 2 whenever the platform says a finding blocks, whatever the status; every other outcome is 0. */
+export function policyExitCode(check) {
+    return check?.blocking === true ? 2 : 0;
+}
+/**
+ * The one warning line for feedback without a headline (`disabled`, `unavailable`, `error`, an
+ * unknown status such as an older platform's `forbidden`, or a pass or fail that does not say whether
+ * it blocks): the server's own status and message, or that none came back. `null` for headlined
+ * feedback.
+ */
+export function policyCheckWarning(check) {
+    if (!check)
+        return 'Policy check: no policy feedback returned.';
+    if (isHeadlined(check))
+        return null;
+    const status = typeof check.status === 'string' && check.status.trim() !== '' ? check.status.trim() : 'unknown';
+    const message = typeof check.message === 'string' && check.message.trim() !== ''
+        ? check.message.trim()
+        : (['fail', 'pass'].includes(status) ? 'the server did not say whether its findings block.' : 'no message returned.');
+    return `Policy check ${status}: ${message}`;
+}
+/**
+ * What happened to the policy documents a push carried. The preview says, per policy, whether it was
+ * created, updated or left unchanged. Without a preview only the number sent is known: the import
+ * response reports an unchanged policy exactly as it reports a saved one.
+ */
+export function policyDocumentSummary(preview, sentPolicies) {
+    const operations = (preview?.operations ?? []).filter((op) => op.type === 'policy');
+    if (operations.length === 0) {
+        return sentPolicies > 0
+            ? [`Policy documents: ${sentPolicies} sent without a preview, so which of them changed is not known`]
+            : [];
+    }
+    const named = (action) => operations.filter((op) => op.action === action).map((op) => op.name).sort();
+    const created = named('create');
+    const updated = named('update');
+    const unchanged = named('unchanged');
+    const parts = [
+        created.length > 0 && `${created.length} created (${created.join(', ')})`,
+        updated.length > 0 && `${updated.length} updated (${updated.join(', ')})`,
+        unchanged.length > 0 && `${unchanged.length} unchanged`,
+    ].filter(Boolean);
+    return parts.length > 0 ? [`Policy documents: ${parts.join(', ')}`] : [];
+}
+/** A count the platform served, or 0. */
+function count(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : 0;
+}
+/** What a trimmed answer (`access: "coverage"`) says beyond its findings. */
+function trimmedEvidence(check) {
+    return {
+        elsewhere: {
+            blocking: count(check.elsewhere?.blocking),
+            introduced: check.elsewhere?.basis === 'introduced',
+            total: count(check.elsewhere?.total),
+        },
+        errors: check.counts?.errors ?? 0,
+        note: typeof check.note === 'string' ? check.note.trim() : '',
+    };
+}
+/** A trimmed answer's closing lines: what it counted elsewhere, the branch's rule errors, its note. */
+function trimmedLines(trimmed) {
+    const { elsewhere } = trimmed;
+    return [
+        // Counted, never named: the objects are not the caller's to be told about.
+        ...(elsewhere.total > 0
+            // "new" only when the platform compared with the branch before the push (`basis: introduced`).
+            ? [`On objects this push did not list: ${elsewhere.total} ${elsewhere.introduced ? 'new ' : ''}finding${elsewhere.total === 1 ? '' : 's'} (${elsewhere.blocking} blocking), counted, not named.`]
+            : []),
+        ...(trimmed.errors > 0 ? [`Rules that could not run on the branch: ${trimmed.errors}.`] : []),
+        ...(trimmed.note ? [trimmed.note] : []),
+    ];
+}
+/**
+ * A push answers no run, so its `policy_check` carries the findings and results itself: the first
+ * 100 of each list, with `counts` and `total` saying what they are out of.
+ */
+export function pushEvidence(check) {
+    const trimmed = check && isCoverageCheck(check) ? { trimmed: trimmedEvidence(check) } : {};
+    return {
+        blocking: new Set((check?.blocking_findings ?? []).map(finding => finding.id ?? '').filter(Boolean)),
+        ...(check?.truncated && check.counts
+            ? { cut: { blocking: check.counts.blocking, findings: check.total ?? check.counts.findings, runId: check.run_id ?? 0 } }
+            : {}),
+        findings: check?.findings ?? [],
+        results: check?.results ?? [],
+        snapshot: [],
+        ...trimmed,
+    };
+}
+/**
+ * A push's `policy_check` for a caller without `workspace:policy` read: only that caller's findings
+ * on the objects the push carried, and no run it may read.
+ */
+export function isCoverageCheck(check) {
+    return check?.access === 'coverage';
+}
+/**
+ * An evaluation answers the run, and its verdict names the blocking findings by id. Its summary
+ * answer (`--summary`) lists the first findings, and its counts say what they are out of.
+ */
+export function evaluationEvidence(evaluation) {
+    const { counts } = evaluation;
+    return {
+        blocking: new Set(evaluation.policy_check?.blocking_finding_ids ?? []),
+        ...(evaluation.truncated && counts
+            ? { cut: { blocking: counts.blocking, findings: evaluation.total ?? counts.findings, runId: evaluation.stored === false ? 0 : (evaluation.id ?? 0) } }
+            : {}),
+        findings: evaluation.findings ?? [],
+        results: evaluation.results ?? [],
+        snapshot: evaluation.policies ?? [],
+    };
+}
+/** A list's count, or `first N of M` when the answer lists only the first of them. */
+function listed(count, all) {
+    return all !== undefined && all > count ? `first ${count} of ${all}` : String(count);
+}
+/** The headline's outcome. A pass whose rules inspected no object is never headlined as a plain pass. */
+function outcome(check, results) {
+    if (check.status === 'fail')
+        return check.blocking ? 'fail (blocking findings)' : 'advisory findings (not blocking)';
+    if (check.status !== 'pass')
+        return check.status ?? '';
+    const unchecked = results.filter((result) => hasNoObjects(result)).length;
+    if (unchecked === 0)
+        return 'pass';
+    return unchecked === results.length
+        ? 'pass, but no objects were checked'
+        : `pass, but ${unchecked} rule${unchecked === 1 ? '' : 's'} checked no objects`;
+}
+/**
+ * The feedback on stdout: a headline with the server's message, then any findings, errors and
+ * warnings. Feedback without a headline is reported by `policyCheckWarning` instead.
+ */
+export function policySummary(check, evidence) {
+    if (!check)
+        return [];
+    const lines = [];
+    if (isHeadlined(check)) {
+        lines.push(`Policy check: ${outcome(check, evidence.results)}`);
+        if (check.message)
+            lines.push(check.message);
+    }
+    const rules = snapshotRules(evidence.snapshot);
+    const { blocking, cut, findings, trimmed } = evidence;
+    const render = (finding) => trimmed ? coverageFindingLines(finding) : [findingLine(finding, rules)];
+    // A cut list is out of the counts; the ones the answer lists come first, blocking first.
+    const allBlocking = cut?.blocking;
+    const allAdvisory = cut ? cut.findings - cut.blocking : undefined;
+    if (cut)
+        lines.push(`Findings: ${cut.findings} (${cut.blocking} blocking, ${allAdvisory} advisory)`);
+    // The list splits only when some findings block and others do not.
+    const separated = blocking.size > 0 && findings.some(finding => !blocking.has(finding.id ?? ''));
+    if (separated) {
+        const blocked = findings.filter(finding => blocking.has(finding.id ?? ''));
+        const advisory = findings.filter(finding => !blocking.has(finding.id ?? ''));
+        lines.push(`Blocking findings (${listed(blocked.length, allBlocking)}) — active blocking policies; a gate refuses a change that introduces one or changes its object:`, ...blocked.flatMap(finding => render(finding)), `Advisory findings (${listed(advisory.length, allAdvisory)}) — reported, not blocking:`, ...advisory.flatMap(finding => render(finding)));
+    }
+    else {
+        if (blocking.size > 0 && findings.length > 0)
+            lines.push(`Blocking findings (${listed(findings.length, allBlocking)}) — active blocking policies; a gate refuses a change that introduces one or changes its object:`);
+        // Without a headline (an `error` status, say) nothing else says what these findings are.
+        else if (findings.length > 0 && !isHeadlined(check))
+            lines.push(`Advisory findings (${listed(findings.length, allAdvisory)}) — reported, not blocking:`);
+        lines.push(...findings.flatMap(finding => render(finding)));
+    }
+    if (cut) {
+        // A trimmed answer names no run: the caller may not read one.
+        lines.push(trimmed
+            ? `Listed: the first ${findings.length} of ${cut.findings}.`
+            : `Listed: the first ${findings.length} of ${cut.findings}; ${cut.runId > 0
+                ? `\`xano policy runs ${cut.runId}\` has them all.`
+                : 'this evaluation was not stored, so the rest cannot be listed.'}`);
+    }
+    lines.push(...policyResultSummary(evidence.results));
+    if (trimmed)
+        lines.push(...trimmedLines(trimmed));
+    return lines;
+}
+/**
+ * The platform's one notice that a push or its dry run left policy files out
+ * (`policies_skipped.message`): a push to a remote tenant or to a tenant without a policy table, a
+ * `release push` by a caller without `workspace:policy` create and update (its release carries the
+ * live branch's policies instead), and any push while the Policies feature is off. `null` when it
+ * left none out.
+ */
+export function policiesSkippedNotice(answer) {
+    const skipped = answer && typeof answer === 'object' ? answer.policies_skipped : undefined;
+    const message = skipped && typeof skipped === 'object' ? skipped.message : undefined;
+    return typeof message === 'string' && message.trim() !== '' ? message.trim() : null;
+}
+/**
+ * The line for an evaluation that ran but was not recorded (the credential may read, not write), or
+ * `null`. A branch with nothing to evaluate stores nothing either, and its headline says so.
+ */
+export function notStoredLine(evaluation) {
+    if (evaluation.stored !== false || !['error', 'fail', 'pass'].includes(evaluation.policy_check?.status ?? ''))
+        return null;
+    return 'Not stored: this credential can run checks but not record runs, so `xano policy status` and `xano policy runs` will not show this one.';
+}

package/dist/utils/policy/findings.d.ts

@@ -0,0 +1,29 @@
+import type { CoverageFinding, PolicyFinding, PolicyRuleResult, PolicySnapshotPolicy, PolicySnapshotRule } from './types.js';
+/**
+ * The platform's naming rule, shared with Studio: the author's title, then the check's human
+ * label, then the rule id. Pass `label` from the run snapshot, or from the catalogue entry for
+ * `check` when the caller already holds the catalogue; never fetch one just to name a rule.
+ */
+export declare function policyRuleName(rule: PolicySnapshotRule): string;
+/** Collision-free regardless of what a key or rule id contains. */
+export declare const ruleKey: (policyKey?: string, ruleId?: string) => string;
+export declare function snapshotRules(policies: PolicySnapshotPolicy[]): Map<string, PolicySnapshotRule>;
+/**
+ * One finding line. The rule id leads it, because the check's label is shared by every
+ * rule that uses that check — with two rules of one policy failing, the labels alone do
+ * not tell them apart, and the id is what `--run-detail` and the JSON cite.
+ */
+export declare function findingLine(finding: PolicyFinding, rules: Map<string, PolicySnapshotRule>): string;
+/**
+ * A finding as a caller without `workspace:policy` read is told it (`access: "coverage"`): its rule's
+ * name, its policy's key and title, its object and message, then the check's fix hint on a line of
+ * its own. Such a finding has no rule id or severity, and a deleted policy's finding has no fix.
+ */
+export declare function coverageFindingLines(finding: CoverageFinding): string[];
+/** A completed rule with no objects checked, including older stored pass + checked 0 results. */
+export declare function hasNoObjects(result: PolicyRuleResult): boolean;
+/**
+ * Rule errors ("this rule could not run") and scope warnings ("part of your scope selected
+ * nothing") under their own headings, then the rules that inspected nothing.
+ */
+export declare function policyResultSummary(results?: PolicyRuleResult[]): string[];

package/dist/utils/policy/findings.js

@@ -0,0 +1,82 @@
+/**
+ * The platform's naming rule, shared with Studio: the author's title, then the check's human
+ * label, then the rule id. Pass `label` from the run snapshot, or from the catalogue entry for
+ * `check` when the caller already holds the catalogue; never fetch one just to name a rule.
+ */
+export function policyRuleName(rule) {
+    return rule.title?.trim() || rule.label?.trim() || rule.id?.trim() || '';
+}
+/** Collision-free regardless of what a key or rule id contains. */
+export const ruleKey = (policyKey = '', ruleId = '') => JSON.stringify([policyKey, ruleId]);
+export function snapshotRules(policies) {
+    return new Map(policies.flatMap(policy => (policy.rules ?? []).map(rule => [ruleKey(policy.key, rule.id), rule])));
+}
+/** A finding names its rule the way the platform does, falling back to what the run recorded. */
+function findingName(finding, rules) {
+    const recorded = rules.get(ruleKey(finding.policy_key, finding.rule_id)) ?? {};
+    return policyRuleName({
+        ...recorded,
+        id: finding.rule_id ?? recorded.id,
+        title: finding.rule_title || recorded.title,
+    }) || 'finding';
+}
+/**
+ * One finding line. The rule id leads it, because the check's label is shared by every
+ * rule that uses that check — with two rules of one policy failing, the labels alone do
+ * not tell them apart, and the id is what `--run-detail` and the JSON cite.
+ */
+export function findingLine(finding, rules) {
+    // A rule the author left unnamed is called by its check's label, and only then by its id.
+    const rule = findingName(finding, rules);
+    const id = finding.rule_id?.trim();
+    const policy = finding.policy_title || finding.policy_key || 'policy';
+    const severity = finding.severity?.trim() ? ` [${finding.severity.trim()}]` : '';
+    return `  ${[id, id === rule ? '' : rule].filter(Boolean).join('  ')}${severity} (${policy})  ${finding.object?.type ?? ''} ${finding.object?.name ?? ''}: ${finding.message ?? ''}`;
+}
+/**
+ * A finding as a caller without `workspace:policy` read is told it (`access: "coverage"`): its rule's
+ * name, its policy's key and title, its object and message, then the check's fix hint on a line of
+ * its own. Such a finding has no rule id or severity, and a deleted policy's finding has no fix.
+ */
+export function coverageFindingLines(finding) {
+    const key = finding.policy_key?.trim() || 'policy';
+    const title = finding.policy_title?.trim();
+    const rule = finding.rule_title?.trim() || finding.check?.label?.trim() || 'finding';
+    const object = [finding.object?.type, finding.object?.name].filter(Boolean).join(' ');
+    const deleted = finding.deleted ? ' [policy deleted]' : '';
+    const lines = [`  ${rule} (${title ? `${key} ${title}` : key})${deleted}  ${object}: ${finding.message ?? ''}`];
+    const fix = finding.deleted ? '' : finding.check?.fix_hint?.trim();
+    if (fix)
+        lines.push(`    Fix: ${fix}`);
+    return lines;
+}
+/** A completed rule with no objects checked, including older stored pass + checked 0 results. */
+export function hasNoObjects(result) {
+    return ['no_objects', 'pass'].includes(result.status ?? '') && (result.checked ?? 0) === 0;
+}
+/**
+ * Rule errors ("this rule could not run") and scope warnings ("part of your scope selected
+ * nothing") under their own headings, then the rules that inspected nothing.
+ */
+export function policyResultSummary(results = []) {
+    const where = (result) => `${result.policy_key ?? 'policy'} ${result.check_id ?? 'rule'}`;
+    const errors = results.filter(result => result.status === 'error')
+        .map(result => `  ${where(result)}: ${result.message ?? 'No diagnostic returned.'}`);
+    const warnings = results.flatMap(result => (result.warnings ?? []).map(warning => `  ${where(result)}: ${warning}`));
+    const lines = [];
+    if (errors.length > 0)
+        lines.push('Errors:', ...errors);
+    if (warnings.length > 0)
+        lines.push('Warnings:', ...warnings);
+    const checked = results.reduce((sum, result) => sum + (result.checked ?? 0), 0);
+    // When no rule checked anything, one sentence about the run says it all.
+    if (results.length > 0 && checked === 0) {
+        lines.push('No objects checked; this run does not demonstrate coverage.');
+        return lines;
+    }
+    const empty = results.filter(result => hasNoObjects(result));
+    if (empty.length > 0) {
+        lines.push('No objects checked (proves nothing about coverage):', ...empty.map(result => `  ${where(result)}: no objects checked`));
+    }
+    return lines;
+}