roundel 0.3.0 → 0.4.0

package/README.md

@@ -176,3 +176,18 @@ colours, [flagstaff](https://www.npmjs.com/package/flagstaff) flies it, and
 none requires the others.
 
 MIT © Ofri Peretz — see [LICENSE](./LICENSE).
+
+## Benchmarks
+
+Every number here is produced by `npm run bench` and published at [/docs/benchmarks](/docs/benchmarks).
+
+Graded by the incumbent's own test suite:
+
+| suite | passing |
+| :-- | --: |
+| `chalk` | 58 / 58 |
+## Where it sits
+
+Plugins register under the `tokens` key, against the one schema the whole family shares.
+
+`burgee` and `flagstaff` build on it, and it builds on nothing in this family.

package/dist/chalk.js

@@ -1,4 +1,5 @@
 import { colorLevel } from './policy.js';
+import { processRuntime } from './runtime.js';
 import { sgr } from './tokens.js';
 const MODIFIERS = {
     reset: [0, 0],
@@ -120,16 +121,13 @@ function builder(root, chain, visible) {
         },
     });
 }
-const proc = globalThis
-    .process;
-const detect = (stream) => colorLevel({ env: proc?.env ?? {}, argv: proc?.argv ?? [], isTTY: { stdout: proc?.[stream]?.isTTY === true } });
-const stdoutLevel = detect('stdout');
-const stderrLevel = detect('stderr');
+const stdoutLevel = colorLevel(processRuntime());
+const stderrLevel = colorLevel(processRuntime('stderr'));
 const info = (level) => (level === 0 ? false : { level, hasBasic: true, has256: level >= 2, has16m: level === 3 });
 function create(options = {}, detected = stdoutLevel) {
-    if (options.level !== undefined)
-        checkLevel(options.level);
-    return builder({ level: options.level ?? detected }, [], false);
+    const { level = detected } = options;
+    checkLevel(level);
+    return builder({ level }, [], false);
 }
 export class Chalk {
     constructor(options) {

package/dist/check.d.ts

@@ -0,0 +1,14 @@
+/**
+ * E1, restated rather than imported: roundel is an independent product and depends on nobody in
+ * the family for its exit contract. `scripts/exit-code-lock.test.ts` keeps the restatements in
+ * step.
+ */
+export declare const EXIT_OK = 0;
+export declare const EXIT_RUNTIME = 1;
+export declare const EXIT_USAGE = 2;
+/**
+ * Every refusal leaves through here, wherever it was raised: `register()`, or a plugin file that
+ * registers itself on import — which throws inside the `import()`, before any line of `inspect`
+ * could catch it, and used to reach the bin as a bare message with no code and no fix (R8).
+ */
+export declare function check(argv: readonly string[], write: (s: string) => void): Promise<number>;

package/dist/check.js

@@ -0,0 +1,45 @@
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { contributions, PluginError, register, reset, validate } from './plugin.js';
+export const EXIT_OK = 0;
+export const EXIT_RUNTIME = 1;
+export const EXIT_USAGE = 2;
+function refuse(code, message, fix, write) {
+    write(`${code}: ${message}\n  fix: ${fix}\n`);
+    return EXIT_RUNTIME;
+}
+const shadows = (names) => (names.length === 0 ? '' : ` (replaces ${names.join(', ')})`);
+export async function check(argv, write) {
+    try {
+        return await inspect(argv, write);
+    }
+    catch (error) {
+        if (!(error instanceof PluginError))
+            throw error;
+        return refuse(error.code, error.message, error.fix, write);
+    }
+}
+async function inspect(argv, write) {
+    const file = argv[0];
+    if (file === undefined) {
+        write('usage: roundel check <plugin-file>\n');
+        return EXIT_USAGE;
+    }
+    const loaded = (await import(pathToFileURL(resolve(file)).href));
+    const plugin = loaded.default ?? loaded;
+    reset();
+    validate(plugin);
+    register(plugin);
+    const name = plugin.name;
+    const rows = contributions()
+        .filter((c) => c.from === plugin.name)
+        .map((c) => `${c.token}  ${c.value}${shadows(c.shadowed)}`);
+    write(`${name} — ${String(rows.length)} tokens\n`);
+    if (rows.length === 0) {
+        return refuse('E_NO_CONTRIBUTION', `${name} registers, but contributes nothing roundel reads`, 'add a `tokens` section — a key another package in the family reads is allowed in the same object, but `roundel check` cannot show it', write);
+    }
+    for (const row of rows)
+        write(`  ${row}\n`);
+    write(`${name}: ok\n`);
+    return EXIT_OK;
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { check, EXIT_RUNTIME } from './check.js';
+const [, , command, ...rest] = process.argv;
+check(command === 'check' ? rest : [command, ...rest].filter((a) => a !== undefined), (s) => void process.stdout.write(s)).then((code) => {
+    process.exitCode = code;
+}, (error) => {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = EXIT_RUNTIME;
+});

package/dist/plugin.d.ts

@@ -33,7 +33,7 @@ export interface Plugin {
     contract?: number;
     tokens?: Record<string, string>;
 }
-export type PluginErrorCode = 'E_PLUGIN_SCHEMA' | 'E_PLUGIN_CONTRACT';
+export type PluginErrorCode = 'E_PLUGIN_SCHEMA' | 'E_PLUGIN_CONTRACT' | 'E_NO_CONTRIBUTION';
 /** A refused plugin says what is wrong and what to do about it — the family's one vocabulary. */
 export declare class PluginError extends Error {
     readonly code: PluginErrorCode;

package/dist/policy.d.ts

@@ -13,21 +13,7 @@
  * 9,370 bytes. Comments are stripped from `dist`, so the prose is free; the statements
  * are not.
  */
-/**
- * The slice of a runtime the policy needs. burgee's `processRuntime` satisfies it, so
- * does a two-line literal in a test; nothing here imports a type from anywhere.
- */
-export interface Runtime {
-    env: Record<string, string | undefined>;
-    isTTY: {
-        stdout: boolean;
-    };
-    /**
-     * The process arguments, when the caller owns them: `--color`, `--no-color` and
-     * `--color=…` are read here and nowhere else. A test literal leaves it out.
-     */
-    argv?: readonly string[];
-}
+import { type Runtime } from './runtime.js';
 export type OutputMode = 'tty' | 'pipe' | 'json' | 'accessible' | 'ci';
 declare const MAX_LEVEL = 3;
 /** chalk's levels: none, 16 colours, 256 colours, truecolor. */
@@ -90,4 +76,13 @@ export declare const flown: {
     level: ColorLevel;
     paint: Partial<Record<TokenName, Paint>>;
 };
-export {};
+/**
+ * The slice of a runtime this file reads is declared in `./runtime.js`, beside the one
+ * function in the package that names the process (Y9), and re-exported here because
+ * `roundel/policy` is the subpath a caller imports it from. One declaration, two doors.
+ *
+ * The import at the top is type-only, so `verbatimModuleSyntax` erases it whole: `policy.js`
+ * reaches no new module, and the weight of every subpath that stands on it is unchanged.
+ * `subpath-isolation.test.ts` is what holds that.
+ */
+export type { Runtime };

package/dist/runtime.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The slice of the world this package needs, and the one file in it that names the process
+ * (Y9). The same seam `paratext/src/runtime.ts` and `burgee/src/runtime.ts` declare, for
+ * the same reason: `policy.ts` answers "where is this output going?" from a `Runtime`, so a
+ * test declares a terminal in two lines and a host can lie about one on purpose.
+ *
+ * The guarded cast below moved here whole from `chalk.ts`, unchanged. It is guarded because
+ * `process` is not a given where a bundle runs, and it is bound to a local because a
+ * textual lock cannot tell `proc?.env` from any other local — the exemption is recorded in
+ * burgee's `process-reference-lock.test.ts` against this file, so a reader looking for it
+ * finds it, but it is the cast and not the entry that keeps roundel honest.
+ *
+ * Nothing is cached here. `./chalk` calls `processRuntime()` twice at import because
+ * chalk's contract is "detect the terminal at import" (R6); every other caller in the
+ * family passes its own `Runtime` and never reaches this file at all.
+ */
+/**
+ * The slice of a runtime the policy needs. burgee's `processRuntime` satisfies it, so does
+ * a two-line literal in a test; nothing here imports a type from anywhere.
+ */
+export interface Runtime {
+    env: Record<string, string | undefined>;
+    isTTY: {
+        stdout: boolean;
+    };
+    /**
+     * The process arguments, when the caller owns them: `--color`, `--no-color` and
+     * `--color=…` are read in `policy.ts` and nowhere else. A test literal leaves it out.
+     */
+    argv?: readonly string[];
+}
+/**
+ * The real process. `stream` names the stream this output is going to — `chalkStderr` and
+ * `supportsColorStderr` detect against stderr, as chalk does — and its `isTTY` lands in
+ * `isTTY.stdout`, which is the policy's name for "the stream this output goes to" rather
+ * than for fd 1 in particular.
+ *
+ * `argv` defaults to empty rather than absent: `exactOptionalPropertyTypes` makes an
+ * optional `argv` mean "the key may be missing", not "the value may be undefined".
+ */
+export declare const processRuntime: (stream?: "stdout" | "stderr") => Runtime;

package/dist/runtime.js

@@ -0,0 +1,2 @@
+const proc = globalThis.process;
+export const processRuntime = (stream = 'stdout') => ({ env: proc?.env ?? {}, argv: proc?.argv ?? [], isTTY: { stdout: proc?.[stream]?.isTTY === true } });

package/dist/schema.json

@@ -1 +1 @@
-{"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://github.com/ofri-peretz/burgee/blob/main/packages/flagstaff/src/schema.json","title":"flagstaff plugin","description":"A plugin is one plain object. Everything in it is data that can be read without running it; the only functions allowed are a component's `static` (required) and `frame` (optional). A spinner or component without a static projection is refused at register().","type":"object","required":["name"],"additionalProperties":true,"properties":{"name":{"type":"string","minLength":1,"description":"The plugin's name; also the prefix a host may use when two plugins contribute the same key."},"contract":{"type":"integer","minimum":1,"description":"The plugin contract this object follows. A host refuses a newer contract than it knows."},"tokens":{"type":"object","description":"A roundel theme: semantic token name to a hex colour, contrast-checked when flown.","additionalProperties":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"}},"glyphs":{"type":"object","description":"Symbols by meaning: `ok`, `fail`, `warn`, `info`, `running`. A plugin that ships glyphs changes every built-in that draws one.","additionalProperties":{"type":"string","minLength":1}},"spinners":{"type":"object","description":"Spinner styles by name, in cli-spinners' shape plus the static projection.","additionalProperties":{"$ref":"#/$defs/spinner"}},"borders":{"type":"object","description":"Border styles a box can be drawn with, by name.","additionalProperties":{"$ref":"#/$defs/border"}},"components":{"type":"object","description":"Components by name: `static(state)` returns the text a pipe, an agent or a screen reader gets; `frame(t, state)` is the optional animated form.","additionalProperties":{"$ref":"#/$defs/component"}}},"$defs":{"spinner":{"type":"object","required":["frames","interval","static"],"properties":{"frames":{"type":"array","items":{"type":"string"},"minItems":1},"interval":{"type":"integer","minimum":1,"description":"Milliseconds between frames on a terminal."},"static":{"type":"string","description":"What a pipe prints instead of the animation."}}},"component":{"type":"object","required":["static"],"properties":{"static":{"description":"(state) => string. Required: the projection every non-terminal mode prints."},"frame":{"description":"(t, state) => string. Optional: the frame at t milliseconds since hoisting."},"sample":{"type":"object","required":["running","done"],"description":"Two states to *show* this component with: `flagstaff check` and the docs gallery render `running` then `done`. Omitted, they assume `{ phase: 'running' }` and `{ phase: 'done' }` and say so in the output. The loop never reads it — a running program's state comes from the program.","properties":{"running":{"description":"The state to open with."},"done":{"description":"The state to close with."}}},"interval":{"type":"integer","minimum":1,"description":"Milliseconds between repaints when `frame` is given; 80 when omitted."}}},"border":{"type":"object","required":["topLeft","top","topRight","left","right","bottomLeft","bottom","bottomRight"],"description":"cli-boxes' shape exactly, so that corpus imports unchanged.","properties":{"topLeft":{"type":"string"},"top":{"type":"string"},"topRight":{"type":"string"},"left":{"type":"string"},"right":{"type":"string"},"bottomLeft":{"type":"string"},"bottom":{"type":"string"},"bottomRight":{"type":"string"}}}}}
+{"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://github.com/ofri-peretz/burgee/blob/main/packages/flagstaff/src/schema.json","title":"flagstaff plugin","description":"A plugin is one plain object. Everything in it is data that can be read without running it; the only functions allowed are a component's `static` (required) and `frame` (optional). A spinner or component without a static projection is refused at register().","type":"object","required":["name"],"additionalProperties":true,"properties":{"name":{"type":"string","minLength":1,"description":"The plugin's name; also the prefix a host may use when two plugins contribute the same key."},"contract":{"type":"integer","minimum":1,"description":"The plugin contract this object follows. A host refuses a newer contract than it knows."},"tokens":{"type":"object","description":"A roundel theme: semantic token name to a hex colour, contrast-checked when flown.","additionalProperties":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"propertyNames":{"enum":["error","warn","ok","hint","muted","command","flag","value","heading","ground"],"description":"roundel's ten semantic tokens, and nothing else — `roundel`'s own validate() refuses any other name."}},"glyphs":{"type":"object","description":"Symbols by meaning: `ok`, `fail`, `warn`, `info`, `running`. A plugin that ships glyphs changes every built-in that draws one.","additionalProperties":{"type":"string","minLength":1}},"spinners":{"type":"object","description":"Spinner styles by name, in cli-spinners' shape plus the static projection.","additionalProperties":{"$ref":"#/$defs/spinner"}},"borders":{"type":"object","description":"Border styles a box can be drawn with, by name.","additionalProperties":{"$ref":"#/$defs/border"}},"components":{"type":"object","description":"Components by name: `static(state)` returns the text a pipe, an agent or a screen reader gets; `frame(t, state)` is the optional animated form.","additionalProperties":{"$ref":"#/$defs/component"}},"capabilities":{"$ref":"#/$defs/capabilities"},"widths":{"$ref":"#/$defs/widths"}},"$defs":{"spinner":{"type":"object","required":["frames","interval","static"],"properties":{"frames":{"type":"array","items":{"type":"string"},"minItems":1},"interval":{"type":"integer","minimum":1,"description":"Milliseconds between frames on a terminal."},"static":{"type":"string","description":"What a pipe prints instead of the animation."}}},"component":{"type":"object","required":["static"],"properties":{"static":{"description":"(state) => string. Required: the projection every non-terminal mode prints."},"frame":{"description":"(t, state) => string. Optional: the frame at t milliseconds since hoisting."},"sample":{"type":"object","required":["running","done"],"description":"Two states to *show* this component with: `flagstaff check` and the docs gallery render `running` then `done`. Omitted, they assume `{ phase: 'running' }` and `{ phase: 'done' }` and say so in the output. The loop never reads it — a running program's state comes from the program.","properties":{"running":{"description":"The state to open with."},"done":{"description":"The state to close with."}}},"interval":{"type":"integer","minimum":1,"description":"Milliseconds between repaints when `frame` is given; 80 when omitted."}}},"border":{"type":"object","required":["topLeft","top","topRight","left","right","bottomLeft","bottom","bottomRight"],"description":"cli-boxes' shape exactly, so that corpus imports unchanged.","properties":{"topLeft":{"type":"string"},"top":{"type":"string"},"topRight":{"type":"string"},"left":{"type":"string"},"right":{"type":"string"},"bottomLeft":{"type":"string"},"bottom":{"type":"string"},"bottomRight":{"type":"string"}}},"capability":{"type":"object","required":["name","osc","when","encode","fallback"],"additionalProperties":false,"description":"One paratext capability: what it says to the terminal, when the terminal is believed to understand it, and what prints when it does not. No functions, so it travels through JSON. `encode` and `fallback` are templates: `{field}` is the field's value, `{field|base64}` is it base64-encoded, and `[ … ]` is emitted only when every field inside it has a value.","properties":{"name":{"type":"string","minLength":1,"description":"How callers name it. Registering an existing name replaces it — how a caller corrects a guess we got wrong."},"osc":{"description":"The OSC code this speaks, or 'BEL' for the bell and for protocols that are not OSC at all, such as Kitty's.","oneOf":[{"type":"integer","minimum":0},{"const":"BEL"}]},"when":{"type":"object","description":"When the terminal is believed to understand it. Every clause must hold; `termProgram` and `envAny` are ORs within themselves. Guesses — no terminal answers 'do you do OSC 1337' — and therefore data a caller can replace.","additionalProperties":false,"properties":{"tty":{"type":"boolean","description":"Refuse a pipe. Almost always true: a file that receives OSC gets control bytes in it."},"termProgram":{"type":"array","items":{"type":"string"},"description":"Any one of these TERM_PROGRAM values."},"envAny":{"type":"array","items":{"type":"string"},"description":"Any one of these environment variables merely being set, as VTE announces itself."},"term":{"type":"string","description":"An exact TERM — Kitty is xterm-kitty."}}},"encode":{"type":"string","minLength":1,"description":"The bytes, as a template, for a terminal that does understand."},"fallback":{"type":"string","description":"What to print when it does not — PRINCIPLES rule 6. '' is a legitimate answer, a window title having nothing to say in a log; absence is not, which is why this is required and may be ''."}},"examples":[{"name":"kitty-image","osc":"BEL","when":{"tty":true,"term":"xterm-kitty"},"encode":"\u001b_Ga=T,f=100;{base64}\u001b\\","fallback":"{caption}"}]},"capabilities":{"type":"object","description":"paratext capabilities by name — the OSC section of a plugin, read the way flagstaff reads `spinners`.","additionalProperties":{"$ref":"#/$defs/capability"}},"capabilityDocument":{"description":"What paratext's `check()` accepts. Two shapes, and only one of them survives 1.0.","oneOf":[{"description":"The family shape: a plugin carrying its capabilities under `capabilities`.","type":"object","required":["name","capabilities"],"properties":{"name":{"type":"string","minLength":1},"contract":{"type":"integer","minimum":1},"capabilities":{"$ref":"#/$defs/capabilities"}}},{"deprecated":true,"description":"Deprecated: one capability as the whole document, the shape paratext's schema had before this one absorbed it. Accepted for one minor release, removed at 1.0 — `check()` validates it and says so.","$ref":"#/$defs/capability"}]},"widthRange":{"type":"array","description":"One inclusive code-point range, as [low, high]. A single code point is written [n, n].","items":{"type":"integer","minimum":0,"maximum":1114111},"minItems":2,"maxItems":2},"widthOverride":{"type":"object","description":"A linegauge width override: the column count a named set of code-point ranges occupies, for a terminal that disagrees with the Unicode tables. Data only — no function, so it can be written in a config file, diffed, and printed by `linegauge check` without running anyone code.","required":["ranges","columns","why"],"additionalProperties":false,"properties":{"ranges":{"type":"array","description":"The code points this override applies to.","items":{"$ref":"#/$defs/widthRange"},"minItems":1},"columns":{"type":"integer","description":"Columns each cluster in those ranges occupies: 0 for a zero-width mark, 1 narrow, 2 wide.","minimum":0,"maximum":2},"why":{"type":"string","description":"The terminal or the reason. Required, because a width table with no provenance is one nobody can audit when it turns out to be wrong — which is the normal outcome for ambiguous width.","minLength":1}}},"widths":{"type":"object","description":"linegauge width overrides by name — the measurement section of a plugin, read the way flagstaff reads `spinners`.","additionalProperties":{"$ref":"#/$defs/widthOverride"}}}}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roundel",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "The colours a CLI carries. One output policy, semantic tokens, a theme, and a chalk migration path lighter than chalk. Zero dependencies.",
   "license": "MIT",
   "type": "module",
@@ -80,6 +80,9 @@
     "styleText"
   ],
   "devDependencies": {
-    "vitest": "^5.0.0"
+    "vitest": "^5.0.1"
+  },
+  "bin": {
+    "roundel": "./dist/cli.js"
   }
 }