@canonical/pragma-cli 0.35.0 → 0.37.0

package/dist/src/kernel/render/vocabulary.js

@@ -0,0 +1,174 @@
+/**
+ * The rendering vocabulary — the ONE place a state and the word for it meet.
+ *
+ * `doctor` reports states, `setup` plans and applies them, and both speak to
+ * the same reader about the same machine. For as long as each surface spelled
+ * the states itself — three glyph tables, two scope-label maps, two indent
+ * constants — the type layer and the copy layer were free to disagree, and a
+ * copy pass could rename a scope in every sentence while the model underneath
+ * kept the old word. This module ends that freedom: the statuses, their
+ * glyphs, the scope names, and the shared layout markers are each defined
+ * once, here, and every renderer reads them.
+ *
+ * The SCOPES are **global** and **local project**, chosen because they are the
+ * words the user already typed: `--global` and `--local`. Reading `Local
+ * project` above a row whose fix is `pragma setup mcp --local` is the whole
+ * point — the report names the flag that repairs it. (Earlier these surfaces
+ * said MACHINE/PROJECT, and later "global band"/"project band": a third and a
+ * fourth term for the same two things, and "band" is a word nobody outside
+ * this repository has ever used for a config scope. The type layer carried
+ * "band" longest — `ScopeBand`, `PlanRow.band`, a `bands.ts` — and the render
+ * tests now guard against either spelling coming back.)
+ *
+ * The GLYPHS are one small alphabet with fixed meanings, so the same mark
+ * never says two things: `✓` is work done or verified, `✗` is a real fault,
+ * `◇` is available-but-not-set-up, `○` is inert (nothing to act on), and `·`
+ * is neutral punctuation — a sub-item bullet, or a row that never ran. Doctor
+ * and setup map their own status tiers onto that alphabet below, which is what
+ * keeps a failed setup row and a failed doctor row — the same finding seen
+ * twice — wearing the same mark.
+ *
+ * This is the RENDERING vocabulary; the graph-domain vocabulary a distribution
+ * declares (`kernel/vocabulary.ts`) is a different thing with the same good
+ * reason for existing. Like the rest of `kernel/render/`, this module is
+ * statically reachable from the `--help`/`__complete` fast paths, so it
+ * imports NOTHING — it is inert data plus two pure one-line functions.
+ */
+/** The user-facing display label for each of the two config scopes. */
+export const SCOPE_LABELS = {
+    global: "Global",
+    project: "Local project",
+};
+/**
+ * The scope phrase in running text — the lowercase form of
+ * {@link SCOPE_LABELS}, plus the word for "both". Authored here rather than
+ * lowercased at the call site so a reader grepping for either spelling lands
+ * in one file.
+ */
+export const SCOPE_PHRASES = {
+    global: "global",
+    project: "local project",
+    both: "global and local project",
+};
+// =============================================================================
+// The glyph alphabet
+// =============================================================================
+/**
+ * The five marks, by meaning. Uncolored — every glyph is tinted at render
+ * time, never baked at module load. `summon-core`'s Ink wizard renders the
+ * same `success`/`failure` marks for the same meanings; the two packages
+ * cannot share this module (the dependency runs the other way, and the
+ * fast-path covenants forbid the import), so `renderVocabularySync.test.ts`
+ * pins the two alphabets to byte equality instead.
+ */
+export const GLYPHS = {
+    /** Work done, or a state verified healthy. */
+    success: "✓",
+    /** A real fault — something set up that no longer works, or a failed row. */
+    failure: "✗",
+    /** Detected and installable, but not set up — an invitation, not a fault. */
+    available: "◇",
+    /** Inert: nothing to act on here, and nothing wrong either. */
+    inert: "○",
+    /** Neutral punctuation — a sub-item bullet, or a row that never ran. */
+    neutral: "·",
+};
+/** The arrow in front of an inline instruction (`↳ fix: …`). */
+export const FIX_ARROW = "↳";
+/** The bullet a check's indented sub-items carry. */
+export const SUB_BULLET = GLYPHS.neutral;
+/**
+ * The marker for a row that carries NO outcome — one the user deselected, so
+ * it was neither done nor skipped-for-cause. It must not be a ✓: a green check
+ * against work that never ran is the same lie the old recap told when it
+ * reported "Setup complete" over a target it had dropped.
+ */
+export const NOT_RUN_GLYPH = GLYPHS.neutral;
+// =============================================================================
+// Indents
+// =============================================================================
+/** One indent step — every list body row starts two spaces in. */
+export const INDENT = "  ";
+/**
+ * The indent that aligns a check's sub-lines under its name: the row's own
+ * {@link INDENT}, plus one glyph column, plus the two-space gap after it.
+ */
+export const SUB_INDENT = "     ";
+/**
+ * Each check status's mark. `available` gets its own glyph, distinct from ✗:
+ * an opt-in integration that is not set up is not a fault, and rendering it as
+ * one would train users to ignore the failure count. The glyph pairs with the
+ * word in the tally, so the distinction survives with color stripped.
+ */
+export const CHECK_GLYPHS = {
+    pass: GLYPHS.success,
+    fail: GLYPHS.failure,
+    available: GLYPHS.available,
+    skip: GLYPHS.inert,
+};
+/**
+ * The word in front of a check row's instruction, chosen by what the row IS.
+ *
+ * A `fail` and an `available` are things to repair or switch on, so they read
+ * `fix`. A `skip` is neither — nothing is wrong and nothing is off; the row
+ * simply has nothing to act on yet — so labelling its instruction `fix` would
+ * be the same "a skip is a fault" reading the `available` glyph exists to
+ * prevent. It reads `next`, which is what the line actually is.
+ */
+export const checkRemedyWord = (status) => status === "skip" ? "next" : "fix";
+/**
+ * Each outcome's mark. The three ways work can be complete — `done`, `noop`
+ * (already current), `removed` — all read ✓; the two ways a row can stand
+ * aside — `kept`, `skipped` — read the inert ○; only `failed` earns ✗.
+ */
+export const OUTCOME_GLYPHS = {
+    done: GLYPHS.success,
+    noop: GLYPHS.success,
+    removed: GLYPHS.success,
+    kept: GLYPHS.inert,
+    skipped: GLYPHS.inert,
+    failed: GLYPHS.failure,
+};
+/**
+ * The word in front of a row outcome's instruction — `fix` for a row that
+ * failed, `next` for one that skipped. Same rule as {@link checkRemedyWord}: a
+ * skip is not a fault, and labelling its instruction as a repair is what
+ * teaches a reader to treat skips as failures.
+ */
+export const outcomeRemedyWord = (status) => status === "failed" ? "fix" : "next";
+/**
+ * The display label for an install source, e.g. `npm (global)`, `bun link
+ * (development checkout)`, `npx (ephemeral)`, `unknown (node runtime)`. The
+ * `via` word is the manager/runner/runtime name the detector resolved —
+ * absent only for a `workspace`/`linked` install whose manager could not be
+ * told, which then reads as the bare state.
+ */
+export const installSourceLabel = (kind, via) => {
+    switch (kind) {
+        case "global":
+            return `${via} (global)`;
+        case "workspace":
+            return via ? `${via} (local project)` : "local project dependency";
+        case "linked":
+            return via
+                ? `${via} link (development checkout)`
+                : "linked (development checkout)";
+        case "ephemeral":
+            return `${via} (ephemeral)`;
+        case "unknown":
+            return `unknown (${via} runtime)`;
+    }
+};
+/**
+ * What each command-less install state says when a newer release exists —
+ * honest guidance in place of a command that would be wrong to run. The
+ * `linked` sentence is the load-bearing one: it replaces the `npm i -g` that
+ * would clobber the development link.
+ */
+export const INSTALL_UPDATE_GUIDANCE = {
+    workspace: "Installed as a project dependency — update it through the project's package.json.",
+    linked: "Linked development checkout — update it from its source tree, or unlink it before installing a release.",
+    ephemeral: "Ephemeral run — invoke it again with an explicit @latest version to pick up the newest release.",
+    unknown: "The install method cannot be determined — update it the same way it was installed.",
+};
+//# sourceMappingURL=vocabulary.js.map

package/dist/src/kernel/render/vocabulary.js.map

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