@shrkcrft/cli 0.1.0-alpha.30 → 0.1.0-alpha.31

package/dist/output/rejected-entries-note.js

@@ -0,0 +1,103 @@
+/**
+ * THE list-verb note (round 12, 12.1 — and, since the round-12 review (A-4),
+ * the files that failed to load).
+ *
+ * A contributed entry its loader refused used to vanish: the `list` verb
+ * printed the survivors and exited 0, and nothing said an entry was dropped.
+ * A contribution FILE that failed to import dropped every entry it declares
+ * just as silently — `conventions list` even pointed at that very file as the
+ * place to contribute. Every list verb now prints, after its list, one line
+ * per file:
+ *
+ *   ⚠ sharkcraft/conventions.ts failed to load (boom) — nothing in it is listed → shrk conventions doctor
+ *   ⚠ 2 entries rejected from node_modules/@r12/pack/conventions.ts: 'conv.b' (default[8]) — severity: …; 'conv.j' (default[9]) — … → shrk conventions doctor
+ *
+ * with the wording of THE formatter (`formatEntryRejection`), from THE channel
+ * (`collectKindOutcomes`). A list verb is not a verdict: its exit stays 0.
+ * Under `--json` the stdout array is untouched (a parser never breaks) and the
+ * note goes to stderr, one line per failed file plus one for the rejections.
+ */
+import { collectKindOutcomes, contributionFileLabel, formatEntryRejection, } from '@shrkcrft/inspector';
+/** Narrow to what a `--source local|pack` list shows: a pack record has an owning pack. */
+function bySource(records, source) {
+    if (source === 'pack')
+        return records.filter((r) => r.packageName !== undefined);
+    if (source === 'local')
+        return records.filter((r) => r.packageName === undefined);
+    if (source === 'builtin')
+        return [];
+    return records;
+}
+/** The note lines (text, stdout) — `''` when nothing was rejected. */
+export function rejectedEntriesNote(rejections, projectRoot, next) {
+    if (rejections.length === 0)
+        return '';
+    const byFile = new Map();
+    for (const r of rejections)
+        byFile.set(r.file, [...(byFile.get(r.file) ?? []), r]);
+    const lines = [];
+    for (const [file, list] of byFile) {
+        lines.push(`⚠ ${list.length} ${list.length === 1 ? 'entry' : 'entries'} rejected from ${contributionFileLabel(projectRoot, file)}: ${list
+            .map((r) => formatEntryRejection(r))
+            .join('; ')}${next ? ` → ${next}` : ''}`);
+    }
+    return lines.join('\n') + '\n';
+}
+/** The one-line `--json` stderr form — `''` when nothing was rejected. */
+export function rejectedEntriesStderrNote(rejections, projectRoot, next) {
+    if (rejections.length === 0)
+        return '';
+    const files = [...new Set(rejections.map((r) => contributionFileLabel(projectRoot, r.file)))];
+    return `note: ${rejections.length} ${rejections.length === 1 ? 'entry' : 'entries'} rejected by the loader from ${files.join(', ')} — not listed above${next ? ` (see ${next})` : ''}\n`;
+}
+/** One line per contribution file that failed to load (text, stdout) — `''` when every file loaded. */
+export function loadFailuresNote(failures, projectRoot, next) {
+    if (failures.length === 0)
+        return '';
+    return (failures
+        .map((f) => `⚠ ${contributionFileLabel(projectRoot, f.file)} failed to load (${f.message}) — nothing in it is listed${next ? ` → ${next}` : ''}`)
+        .join('\n') + '\n');
+}
+/** The `--json` stderr form, one line per failed file — `''` when every file loaded. */
+export function loadFailuresStderrNote(failures, projectRoot, next) {
+    if (failures.length === 0)
+        return '';
+    return (failures
+        .map((f) => `note: ${contributionFileLabel(projectRoot, f.file)} failed to load (${f.message}) — nothing in it is listed above${next ? ` (see ${next})` : ''}`)
+        .join('\n') + '\n');
+}
+/**
+ * What `kinds`' loaders reported — refused entries and files that never
+ * loaded — narrowed to `--source`. `loadFailures: false` for a verb that
+ * already reports its own load failures (knowledge list's partial-list WARN,
+ * helper list's broken-file line), so no failure is said twice.
+ */
+export async function collectListVerbNote(inspection, kinds, options = {}) {
+    const outcomes = await collectKindOutcomes(inspection, kinds);
+    return {
+        rejections: bySource(outcomes.rejections, options.source),
+        loadFailures: options.loadFailures === false ? [] : bySource(outcomes.loadFailures, options.source),
+    };
+}
+/** Write a collected note: text after the list on stdout, or stderr lines under `--json`. */
+export function writeListVerbNote(outcomes, projectRoot, options = {}) {
+    const { rejections, loadFailures } = outcomes;
+    if (rejections.length === 0 && loadFailures.length === 0)
+        return;
+    if (options.json) {
+        process.stderr.write(loadFailuresStderrNote(loadFailures, projectRoot, options.next) +
+            rejectedEntriesStderrNote(rejections, projectRoot, options.next));
+        return;
+    }
+    process.stdout.write(`\n${loadFailuresNote(loadFailures, projectRoot, options.next)}${rejectedEntriesNote(rejections, projectRoot, options.next)}`);
+}
+/**
+ * Collect `kinds`' outcomes (THE channel, running only the loaders those
+ * kinds need) and write the note: text after the list on stdout, or stderr
+ * lines under `--json`. Returns the rejections it reported.
+ */
+export async function writeRejectedEntriesNote(inspection, kinds, options = {}) {
+    const outcomes = await collectListVerbNote(inspection, kinds, options);
+    writeListVerbNote(outcomes, inspection.projectRoot, options);
+    return outcomes.rejections;
+}

package/dist/output/stdout-is-pipe.d.ts

@@ -0,0 +1,13 @@
+/**
+ * True when stdout (`fd`, default 1) feeds ANOTHER PROCESS — a pipe (FIFO) or
+ * a socket — so a downstream command's `$?` masks shrk's. False for a TTY, a
+ * plain file redirect (`shrk check boundaries > out.log`), `/dev/null`, or an
+ * fd that cannot be stat'ed.
+ *
+ * Round 13: the "stdout is piped" note keyed on `!process.stdout.isTTY`, which
+ * is true for a file redirect too — `… > log 2>&1; echo $?` printed exit 1
+ * correctly and still wrote "note: stdout is piped — $? reflects the
+ * downstream command" into the log, where there was no downstream command.
+ */
+export declare function isStdoutPipe(fd?: number): boolean;
+//# sourceMappingURL=stdout-is-pipe.d.ts.map

package/dist/output/stdout-is-pipe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdout-is-pipe.d.ts","sourceRoot":"","sources":["../../src/output/stdout-is-pipe.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,EAAE,GAAE,MAAU,GAAG,OAAO,CAOpD"}

package/dist/output/stdout-is-pipe.js

@@ -0,0 +1,21 @@
+import { fstatSync } from 'node:fs';
+/**
+ * True when stdout (`fd`, default 1) feeds ANOTHER PROCESS — a pipe (FIFO) or
+ * a socket — so a downstream command's `$?` masks shrk's. False for a TTY, a
+ * plain file redirect (`shrk check boundaries > out.log`), `/dev/null`, or an
+ * fd that cannot be stat'ed.
+ *
+ * Round 13: the "stdout is piped" note keyed on `!process.stdout.isTTY`, which
+ * is true for a file redirect too — `… > log 2>&1; echo $?` printed exit 1
+ * correctly and still wrote "note: stdout is piped — $? reflects the
+ * downstream command" into the log, where there was no downstream command.
+ */
+export function isStdoutPipe(fd = 1) {
+    try {
+        const st = fstatSync(fd);
+        return st.isFIFO() || st.isSocket();
+    }
+    catch {
+        return false;
+    }
+}

package/dist/packs/stale-build-warning.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The CLI startup warning for a pack serving compiled contributions built from
+ * an OLDER source — "shrk is serving the previous build". Read from the
+ * inspection's `packAssetFreshness` (THE pack-asset freshness authority,
+ * content digests, never mtimes); printed once per process, to stderr, only
+ * for a real divergence (`build.state === 'stale'`). An unrecorded build is a
+ * doctor / `packs doctor` / `packs dev-status` finding, not a startup banner.
+ */
+import { type ISharkcraftInspection } from '@shrkcrft/inspector';
+export declare function warnStaleCompiledPacks(inspection: Pick<ISharkcraftInspection, 'packAssetFreshness'>, write?: (s: string) => void): void;
+//# sourceMappingURL=stale-build-warning.d.ts.map

package/dist/packs/stale-build-warning.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stale-build-warning.d.ts","sourceRoot":"","sources":["../../src/packs/stale-build-warning.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAA8B,KAAK,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAI7F,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,IAAI,CAAC,qBAAqB,EAAE,oBAAoB,CAAC,EAC7D,KAAK,GAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAA0C,GAC/D,IAAI,CASN"}

package/dist/packs/stale-build-warning.js

@@ -0,0 +1,23 @@
+/**
+ * The CLI startup warning for a pack serving compiled contributions built from
+ * an OLDER source — "shrk is serving the previous build". Read from the
+ * inspection's `packAssetFreshness` (THE pack-asset freshness authority,
+ * content digests, never mtimes); printed once per process, to stderr, only
+ * for a real divergence (`build.state === 'stale'`). An unrecorded build is a
+ * doctor / `packs doctor` / `packs dev-status` finding, not a startup banner.
+ */
+import { describePackAssetFreshness } from '@shrkcrft/inspector';
+let warned = false;
+export function warnStaleCompiledPacks(inspection, write = (s) => void process.stderr.write(s)) {
+    if (warned)
+        return;
+    const lines = (inspection.packAssetFreshness ?? [])
+        .filter((f) => f.build.state === 'stale')
+        .map((f) => describePackAssetFreshness(f).build)
+        .filter((l) => Boolean(l));
+    if (lines.length === 0)
+        return;
+    warned = true;
+    for (const l of lines)
+        write(`⚠ ${l}\n`);
+}

package/dist/quality/run-quality.d.ts

@@ -0,0 +1,123 @@
+import { type IVerdictCoverage } from '@shrkcrft/core';
+import type { IQualityConfig, ISharkcraftInspection } from '@shrkcrft/inspector';
+import { type GatePlane, type IGateRuleView } from '../gates/gate-rule-view.js';
+import { type IGateRuleResult } from '../gates/gate-envelope.js';
+export declare const QUALITY_RUN_SCHEMA: "sharkcraft.quality-run/v1";
+/**
+ * Outcome of ONE gate in the pre-push bundle.
+ *
+ * `error` is deliberately distinct from `failed`: a gate that could not run
+ * proved nothing, and folding it into either a pass or a violation is how an
+ * unmeasured verdict ships as a green one.
+ */
+export type QualityItemStatus = 'passed' | 'failed' | 'skipped' | 'error';
+export interface IQualityItem {
+    readonly id: string;
+    readonly label: string;
+    readonly status: QualityItemStatus;
+    /** `error` severity blocks the exit code; `warning` reports without failing. */
+    readonly severity: 'error' | 'warning';
+    readonly notes: readonly string[];
+    /**
+     * The exact command that reproduces THIS gate on its own.
+     *
+     * The aggregate exists to collapse a multi-round CI cascade into one local
+     * run, and that only pays off if each failure is immediately actionable —
+     * otherwise the developer's next step is to re-derive which verb produced the
+     * line, which is the round-trip the aggregate was supposed to remove.
+     */
+    readonly repro: string;
+    /** True when the skip was REQUESTED (scope / fail-fast), not accidental. */
+    readonly skippedDeliberately?: boolean;
+    /**
+     * True when the gate RAN but examined only part of its scope (a plane rule
+     * the envelope settled `partial`, or an inspector gate reporting
+     * `data.partial`). Its status is `skipped` (accidental, so never a pass);
+     * this flag names it PARTIAL instead of SKIP in every rendering.
+     */
+    readonly partial?: boolean;
+    /**
+     * The gate's own structured payload — drift counts, boundary error totals, a
+     * rule's declared/registered sizes.
+     *
+     * Carried per item rather than hoisted into one-off top-level fields: a
+     * bundle that grows a `drift` key for the drift gate cannot keep doing that
+     * as gates are added, and a CI consumer then has to know which gates got a
+     * field and which did not.
+     */
+    readonly data?: Record<string, unknown>;
+}
+export interface IQualityRun {
+    readonly schema: typeof QUALITY_RUN_SCHEMA;
+    readonly items: readonly IQualityItem[];
+    readonly passed: number;
+    /** BLOCKING failures — an error-severity gate that ran and found violations. */
+    readonly failed: number;
+    /**
+     * Failures that do NOT block, because the gate is warning-severity.
+     *
+     * Reported separately rather than folded into either bucket: a summary line
+     * reading "0 failed" above a list containing FAIL rows is the kind of
+     * self-contradiction that teaches people to stop trusting the summary.
+     * `--strict` promotes these into {@link failed}.
+     */
+    readonly failedWarnings: number;
+    readonly skipped: number;
+    readonly errored: number;
+    /** Gates that ran a real check (not skipped, not errored). */
+    readonly evaluated: number;
+    readonly verdict: 'pass' | 'fail' | 'not-verified';
+    /** The settled exit — never `0` while {@link shortfalls} is non-empty. */
+    readonly exit: number;
+    /**
+     * Gates examined of gates the run was asked to check. A DELIBERATE skip (out
+     * of the changeset, stopped by `--fail-fast`, an optional gate with nothing
+     * to examine) is excluded from `expected`; an accidental one (an error, a
+     * required gate that examined nothing, a rule that passed over part of its
+     * scope) is an unexamined unit.
+     */
+    readonly coverage: IVerdictCoverage;
+    /** The scope gaps that kept the verdict off `pass` (empty on a clean run). */
+    readonly shortfalls: readonly string[];
+    /** Gaps an explicit acceptance waived (reserved; quality accepts none today). */
+    readonly accepted: readonly string[];
+    /** Set when the run was narrowed to a changeset. */
+    readonly scopedFiles?: number;
+    readonly failFast: boolean;
+    readonly diagnostics: readonly string[];
+}
+export interface IRunQualityInput {
+    readonly inspection: ISharkcraftInspection;
+    readonly config: IQualityConfig;
+    readonly strict: boolean;
+    readonly failFast: boolean;
+    /** Data-defined rules already narrowed to scope by the caller. */
+    readonly gateRules: readonly IGateRuleView[];
+    readonly cwd: string;
+    readonly excludeDirs: readonly string[];
+    readonly changedFiles?: readonly string[];
+    /** Rules dropped because their footprint is outside the changeset. */
+    readonly skippedByScope?: readonly IGateRuleView[];
+    readonly planeDiagnostics?: readonly string[];
+    /**
+     * Pack rules the merge seam rejected (`seamRejectedRules`, the rows `gates
+     * check` fails on) — configured rules that never ran. Each is a FAILED item
+     * and an errored coverage row, never out of the count (round 12 review, R12-X1).
+     */
+    readonly rejectedRules?: readonly (IGateRuleResult & {
+        readonly type: GatePlane;
+    })[];
+}
+/**
+ * Run EVERY configured gate to completion and report every failure.
+ *
+ * A CI job that chains gates as separate steps stops at the first failing step,
+ * so N independent failures cost N round-trips to discover — the classic case
+ * being a first-ever run on a long-lived branch, where fixing gate A only
+ * reveals gate B. The default here is therefore exhaustive: the point is to
+ * surface the whole backlog in one local pass. `failFast` is available for the
+ * opposite, CI-like behaviour, and says so in the report rather than making the
+ * remaining gates look clean.
+ */
+export declare function runQuality(input: IRunQualityInput): Promise<IQualityRun>;
+//# sourceMappingURL=run-quality.d.ts.map

package/dist/quality/run-quality.d.ts.map

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