burgee 0.0.0 → 0.3.0

package/dist/commander-suggest.js

@@ -0,0 +1,59 @@
+const maxDistance = 3;
+function editDistance(a, b) {
+    if (Math.abs(a.length - b.length) > maxDistance)
+        return Math.max(a.length, b.length);
+    const d = [];
+    for (let i = 0; i <= a.length; i++)
+        d[i] = [i];
+    for (let j = 0; j <= b.length; j++)
+        (d[0] ??= [])[j] = j;
+    for (let j = 1; j <= b.length; j++) {
+        for (let i = 1; i <= a.length; i++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            const row = d[i] ?? [];
+            const prev = d[i - 1] ?? [];
+            row[j] = Math.min((prev[j] ?? 0) + 1, (row[j - 1] ?? 0) + 1, (prev[j - 1] ?? 0) + cost);
+            if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) {
+                row[j] = Math.min(row[j] ?? 0, (d[i - 2]?.[j - 2] ?? 0) + 1);
+            }
+        }
+    }
+    return d[a.length]?.[b.length] ?? 0;
+}
+export function suggestSimilar(word, candidates) {
+    if (!candidates || candidates.length === 0)
+        return '';
+    candidates = Array.from(new Set(candidates));
+    const searchingOptions = word.startsWith('--');
+    if (searchingOptions) {
+        word = word.slice(2);
+        candidates = candidates.map((candidate) => candidate.slice(2));
+    }
+    let similar = [];
+    let bestDistance = maxDistance;
+    const minSimilarity = 0.4;
+    for (const candidate of candidates) {
+        if (candidate.length <= 1)
+            continue;
+        const distance = editDistance(word, candidate);
+        const length = Math.max(word.length, candidate.length);
+        const similarity = (length - distance) / length;
+        if (similarity > minSimilarity) {
+            if (distance < bestDistance) {
+                bestDistance = distance;
+                similar = [candidate];
+            }
+            else if (distance === bestDistance) {
+                similar.push(candidate);
+            }
+        }
+    }
+    similar.sort((a, b) => a.localeCompare(b));
+    if (searchingOptions)
+        similar = similar.map((candidate) => `--${candidate}`);
+    if (similar.length > 1)
+        return `\n(Did you mean one of ${similar.join(', ')}?)`;
+    if (similar.length === 1)
+        return `\n(Did you mean ${similar[0]}?)`;
+    return '';
+}

package/dist/commander.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `burgee/commander` — commander's public surface, implemented over burgee (J9: no
+ * dependency on commander itself). Graded by commander's own suite; see
+ * `.sdlc/intents/commander-compat/design.md` and `npm run compat`.
+ */
+import { Argument } from './commander-argument.js';
+import { Command } from './commander-command.js';
+import { Option } from './commander-option.js';
+export { Argument, humanReadableArgName } from './commander-argument.js';
+export { Command, useColor, type AddHelpTextContext, type AddHelpTextPosition, type BurgeeParseOptions, type CommandOptions, type ErrorOptions, type ExecutableCommandOptions, type HookEvent, type HookListener, type OutputConfiguration, type OutputContext, type ParseOptions, } from './commander-command.js';
+export { CommanderError, InvalidArgumentError, InvalidArgumentError as InvalidOptionArgumentError } from './commander-error.js';
+export { Help, type HelpContext } from './commander-help.js';
+export { DualOptions, Option } from './commander-option.js';
+/** The root command, for programs that never construct their own. */
+export declare const program: Command;
+export declare const createCommand: (name?: string) => Command;
+export declare const createOption: (flags: string, description?: string) => Option;
+export declare const createArgument: (name: string, description?: string) => Argument;

package/dist/commander.js

@@ -0,0 +1,12 @@
+import { Argument } from './commander-argument.js';
+import { Command } from './commander-command.js';
+import { Option } from './commander-option.js';
+export { Argument, humanReadableArgName } from './commander-argument.js';
+export { Command, useColor, } from './commander-command.js';
+export { CommanderError, InvalidArgumentError, InvalidArgumentError as InvalidOptionArgumentError } from './commander-error.js';
+export { Help } from './commander-help.js';
+export { DualOptions, Option } from './commander-option.js';
+export const program = new Command();
+export const createCommand = (name) => new Command(name);
+export const createOption = (flags, description) => new Option(flags, description);
+export const createArgument = (name, description) => new Argument(name, description);

package/dist/completions.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Completions, generated statically from the manifest (D2): bash, zsh, fish and
+ * PowerShell scripts that never run Node on TAB (D3), plus a Fig spec from the same walk
+ * (D5). Every script is deterministic for a manifest, so a snapshot pins it and the shell
+ * itself exercises it in CI (D4).
+ */
+import { type Manifest, type OptionSpec } from './manifest.js';
+export type Shell = 'bash' | 'zsh' | 'fish' | 'pwsh';
+export declare const SHELLS: readonly Shell[];
+interface Node {
+    /** Typed path, e.g. `['config', 'get']`; empty for the root. */
+    path: string[];
+    description: string;
+    options: Record<string, OptionSpec>;
+    children: Node[];
+}
+/** The tree the templates walk; the root's own name is the program name. */
+export declare function completionTree(manifest: Manifest): {
+    program: string;
+    root: Node;
+};
+interface FigOption {
+    name: string[];
+    description?: string;
+    args?: {
+        name: string;
+        suggestions?: string[];
+    };
+}
+interface FigSubcommand {
+    name: string;
+    description?: string;
+    subcommands?: FigSubcommand[];
+    options?: FigOption[];
+}
+/** A Fig spec (`Fig.Spec`) from the same walk (D5): one entry per node, children attached by path. */
+export declare function renderFigSpec(manifest: Manifest): FigSubcommand;
+export declare function renderCompletion(manifest: Manifest, shell: Shell): string;
+export {};

package/dist/completions.js

@@ -0,0 +1,224 @@
+import { kebab } from './names.js';
+export const SHELLS = ['bash', 'zsh', 'fish', 'pwsh'];
+const GLOBAL = {
+    json: { type: 'boolean', description: 'machine-readable output' },
+    help: { type: 'boolean', description: 'show this help' },
+};
+const ROOT_ONLY = {
+    schema: { type: 'boolean', description: 'the program as data' },
+    mcp: { type: 'boolean', description: 'serve the program as MCP tools' },
+};
+function children(manifest, at) {
+    return manifest.commands
+        .filter((c) => c.hidden !== true && c.path.length === at.length + 1 && at.every((seg, i) => c.path[i] === seg))
+        .map((c) => nodeOf(manifest, c));
+}
+function nodeOf(manifest, c) {
+    const visible = Object.fromEntries(Object.entries(c.options).filter(([, spec]) => spec.hidden !== true));
+    const isRoot = c.path.length === manifest.rootPath.length;
+    return {
+        path: c.path.slice(manifest.rootPath.length),
+        description: c.summary ?? c.description ?? '',
+        options: { ...visible, ...GLOBAL, ...(isRoot ? ROOT_ONLY : {}) },
+        children: children(manifest, c.path),
+    };
+}
+export function completionTree(manifest) {
+    const root = manifest.find(manifest.rootPath) ?? { path: manifest.rootPath, options: {} };
+    return { program: manifest.rootPath.join('-') || 'program', root: nodeOf(manifest, root) };
+}
+function walk(root) {
+    const out = [];
+    const stack = [root];
+    while (stack.length > 0) {
+        const node = stack.pop();
+        if (node !== undefined) {
+            out.push(node);
+            stack.push(...[...node.children].reverse());
+        }
+    }
+    return out;
+}
+const sq = (s) => `'${s.replaceAll("'", "'\\''")}'`;
+const flags = (name, spec) => (spec.short === undefined ? [`--${kebab(name)}`] : [`-${spec.short}`, `--${kebab(name)}`]);
+const takesValue = (spec) => spec.type !== 'boolean';
+const fname = (program, path) => `_${[program, ...path].join('_').replaceAll(/[^A-Za-z0-9_]/g, '_')}`;
+function bashCase(program, node) {
+    const opts = Object.entries(node.options).flatMap(([n, s]) => flags(n, s));
+    const subs = node.children.map((c) => c.path[c.path.length - 1] ?? '');
+    const valued = Object.entries(node.options)
+        .filter(([, s]) => takesValue(s))
+        .map(([n, s]) => `      ${flags(n, s).join('|')}) COMPREPLY=($(compgen -W ${sq((s.choices ?? []).join(' '))} -- "$cur")); return ;;`)
+        .join('\n');
+    return `  ${fname(program, node.path)}() {
+    case "$prev" in
+${valued === '' ? '      *) ;;' : `${valued}\n      *) ;;`}
+    esac
+    if [[ "$cur" == -* ]]; then COMPREPLY=($(compgen -W ${sq(opts.join(' '))} -- "$cur")); return; fi
+    COMPREPLY=($(compgen -W ${sq(subs.join(' '))} -- "$cur"))
+  }`;
+}
+function bash(program, root) {
+    const nodes = walk(root);
+    const dispatch = nodes
+        .filter((n) => n.path.length > 0)
+        .map((n) => `      ${sq(n.path.join(' '))}) ${fname(program, n.path)}; return ;;`)
+        .join('\n');
+    return `# ${program} completion for bash, generated by burgee — never runs ${program} on TAB.
+# Install: ${program} completion bash > ~/.local/share/bash-completion/completions/${program}
+_${program}_main() {
+  local cur prev words cword
+  _get_comp_words_by_ref -n : cur prev words cword 2>/dev/null || { cur="\${COMP_WORDS[COMP_CWORD]}"; prev="\${COMP_WORDS[COMP_CWORD-1]}"; words=("\${COMP_WORDS[@]}"); cword=$COMP_CWORD; }
+${nodes.map((n) => bashCase(program, n)).join('\n')}
+  # The deepest command named by the words before the cursor decides what to offer.
+  local path="" i
+  for ((i = 1; i < cword; i++)); do
+    case "\${words[i]}" in -*) continue ;; esac
+    case "\${path:+$path }\${words[i]}" in
+${nodes
+        .filter((n) => n.path.length > 0)
+        .map((n) => `      ${sq(n.path.join(' '))}) path="\${path:+$path }\${words[i]}" ;;`)
+        .join('\n')}
+    esac
+  done
+  case "$path" in
+${dispatch}
+      *) ${fname(program, [])} ;;
+  esac
+}
+complete -F _${program}_main ${program}
+`;
+}
+function zshOptionSpec(name, spec) {
+    const desc = (spec.description ?? '').replaceAll(/[[\]:]/g, ' ');
+    const action = spec.choices === undefined ? ' ' : `(${spec.choices.join(' ')})`;
+    const value = takesValue(spec) ? `:${name}:${action}` : '';
+    return flags(name, spec)
+        .map((f) => sq(`${f}[${desc}]${value}`))
+        .join(' ');
+}
+function zshFunction(program, node) {
+    const options = Object.entries(node.options).map(([n, s]) => zshOptionSpec(n, s));
+    if (node.children.length === 0) {
+        return `${fname(program, node.path)}() {\n  _arguments -s ${options.join(' ')} '*: :_files'\n}`;
+    }
+    const subs = node.children.map((c) => sq(`${c.path[c.path.length - 1] ?? ''}[${c.description.replaceAll(/[[\]:]/g, ' ')}]`)).join(' ');
+    const dispatch = node.children.map((c) => `      ${c.path[c.path.length - 1] ?? ''}) ${fname(program, c.path)} ;;`).join('\n');
+    return `${fname(program, node.path)}() {
+  local context state state_descr line
+  typeset -A opt_args
+  _arguments -s -C ${options.join(' ')} '1: :->command' '*:: :->args'
+  case $state in
+    command) _values 'command' ${subs} ;;
+    args) case $line[1] in
+${dispatch}
+    esac ;;
+  esac
+}`;
+}
+function zsh(program, root) {
+    return `#compdef ${program}
+# ${program} completion for zsh, generated by burgee — never runs ${program} on TAB.
+# Install: ${program} completion zsh > "\${fpath[1]}/_${program}" && compinit
+${walk(root).map((n) => zshFunction(program, n)).join('\n')}
+if [[ $zsh_eval_context[-1] == loadautofunc ]]; then ${fname(program, [])} "$@"; else compdef ${fname(program, [])} ${program}; fi
+`;
+}
+function fishCondition(node) {
+    if (node.path.length === 0)
+        return '__fish_use_subcommand';
+    return node.path.map((seg) => `__fish_seen_subcommand_from ${seg}`).join('; and ');
+}
+function fishOption(program, cond, name, spec) {
+    const short = spec.short === undefined ? '' : ` -s ${spec.short}`;
+    const choices = spec.choices === undefined ? '' : ` -f -a ${sq(spec.choices.join(' '))}`;
+    const value = takesValue(spec) ? ` -r${choices}` : '';
+    return `complete -c ${program} -n ${cond}${short} -l ${name}${value} -d ${sq(spec.description ?? '')}`;
+}
+function fish(program, root) {
+    const lines = [];
+    for (const node of walk(root)) {
+        const cond = sq(fishCondition(node));
+        for (const c of node.children)
+            lines.push(`complete -c ${program} -n ${cond} -f -a ${c.path[c.path.length - 1] ?? ''} -d ${sq(c.description)}`);
+        for (const [name, spec] of Object.entries(node.options))
+            lines.push(fishOption(program, cond, name, spec));
+    }
+    return `# ${program} completion for fish, generated by burgee — never runs ${program} on TAB.
+# Install: ${program} completion fish > ~/.config/fish/completions/${program}.fish
+${lines.join('\n')}
+`;
+}
+function pwshEntry(node) {
+    const subs = node.children.map((c) => `@('${c.path[c.path.length - 1] ?? ''}', 'Command', '${c.description.replaceAll("'", "''")}')`);
+    const opts = Object.entries(node.options).flatMap(([n, s]) => flags(n, s).map((f) => `@('${f}', 'ParameterName', '${(s.description ?? '').replaceAll("'", "''")}')`));
+    const values = Object.entries(node.options)
+        .filter(([, s]) => s.choices !== undefined)
+        .map(([n, s]) => `'--${n}' = @(${(s.choices ?? []).map((c) => `'${c}'`).join(', ')})`);
+    return `    '${node.path.join(' ')}' = @{ Items = @(${[...subs, ...opts].join(', ')}); Values = @{ ${values.join('; ')} } }`;
+}
+function pwsh(program, root) {
+    return `# ${program} completion for PowerShell, generated by burgee — never runs ${program} on TAB.
+# Install: ${program} completion pwsh > ${program}-completion.ps1, then dot-source it from $PROFILE
+Register-ArgumentCompleter -Native -CommandName '${program}' -ScriptBlock {
+  param($wordToComplete, $commandAst, $cursorPosition)
+  $table = @{
+${walk(root).map(pwshEntry).join('\n')}
+  }
+  $words = @($commandAst.CommandElements | ForEach-Object { $_.Extent.Text } | Select-Object -Skip 1)
+  if ($wordToComplete -ne '' -and $words.Count -gt 0) { $words = $words[0..($words.Count - 2)] }
+  $path = ''
+  foreach ($w in $words) {
+    if ($w -like '-*') { continue }
+    $candidate = if ($path -eq '') { $w } else { "$path $w" }
+    if ($table.ContainsKey($candidate)) { $path = $candidate }
+  }
+  $entry = $table[$path]
+  $prev = if ($words.Count -gt 0) { $words[$words.Count - 1] } else { '' }
+  if ($entry.Values.ContainsKey($prev)) {
+    $entry.Values[$prev] | Where-Object { $_ -like "$wordToComplete*" } | ForEach-Object { [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_) }
+    return
+  }
+  $entry.Items | Where-Object { $_[0] -like "$wordToComplete*" } | ForEach-Object { [System.Management.Automation.CompletionResult]::new($_[0], $_[0], $_[1], $(if ($_[2] -eq '') { $_[0] } else { $_[2] })) }
+}
+`;
+}
+function figOptions(node) {
+    return Object.entries(node.options).map(([n, s]) => {
+        const o = { name: flags(n, s) };
+        if (s.description !== undefined)
+            o.description = s.description;
+        if (takesValue(s))
+            o.args = { name: s.placeholder ?? 'value', ...(s.choices === undefined ? {} : { suggestions: [...s.choices] }) };
+        return o;
+    });
+}
+export function renderFigSpec(manifest) {
+    const { program, root } = completionTree(manifest);
+    const entries = new Map();
+    for (const node of walk(root)) {
+        const entry = { name: node.path[node.path.length - 1] ?? program, options: figOptions(node) };
+        if (node.description !== '')
+            entry.description = node.description;
+        entries.set(node.path.join(' '), entry);
+        if (node.path.length === 0)
+            continue;
+        const parent = entries.get(node.path.slice(0, -1).join(' '));
+        if (parent !== undefined)
+            (parent.subcommands ??= []).push(entry);
+    }
+    return entries.get('') ?? { name: program, options: [] };
+}
+export function renderCompletion(manifest, shell) {
+    const { program, root } = completionTree(manifest);
+    switch (shell) {
+        case 'bash':
+            return bash(program, root);
+        case 'zsh':
+            return zsh(program, root);
+        case 'fish':
+            return fish(program, root);
+        case 'pwsh':
+            return pwsh(program, root);
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,28 @@
+import { type Layer } from './precedence.js';
+export interface Discovery {
+    name: string;
+    cwd: string;
+    env: Record<string, string | undefined>;
+    /** `--config <path>`. */
+    explicit?: string;
+    /** `--no-config`. */
+    disabled?: boolean;
+}
+export interface Loaded extends Layer {
+    /** The files merged, outermost first — what `--explain` shows. */
+    chain: string[];
+}
+/** Objects merge recursively; anything else, the later value wins. */
+export declare function deepMerge(base: Record<string, unknown>, over: Record<string, unknown>): Record<string, unknown>;
+/** Load a file and everything it extends, outermost first, the file's own keys winning. */
+export declare function loadWithExtends(path: string, seen?: string[]): Promise<Loaded>;
+/** The discovery order as candidate paths, first hit wins; each entry says why it was tried. */
+export declare function candidates(d: Discovery): {
+    path: string;
+    reason: string;
+}[];
+/**
+ * Discover and load. `package.json#<name>` is not a file here — the engine reads the
+ * owning package.json itself and treats the field as its own layer, below config.
+ */
+export declare function discover(d: Discovery): Promise<Loaded | undefined>;

package/dist/config.js

@@ -0,0 +1,98 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { ConfigError } from './precedence.js';
+const EXTENSIONS = ['.json', '.mjs', '.js', '.cjs'];
+const isObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+export function deepMerge(base, over) {
+    const out = new Map(Object.entries(base));
+    for (const [k, v] of Object.entries(over)) {
+        const prev = out.get(k);
+        out.set(k, isObject(prev) && isObject(v) ? deepMerge(prev, v) : v);
+    }
+    return Object.fromEntries(out);
+}
+async function loadFile(path) {
+    if (path.endsWith('.json')) {
+        try {
+            const parsed = JSON.parse(readFileSync(path, 'utf8'));
+            if (!isObject(parsed))
+                throw new ConfigError(`${path} must contain an object`);
+            return parsed;
+        }
+        catch (cause) {
+            if (cause instanceof ConfigError)
+                throw cause;
+            throw new ConfigError(`${path} is not valid JSON`, cause instanceof Error ? cause.message : undefined);
+        }
+    }
+    const mod = (await import(pathToFileURL(path).href));
+    const value = typeof mod.default === 'function' ? await mod.default() : mod.default;
+    if (!isObject(value))
+        throw new ConfigError(`${path} must export an object (or a function returning one)`);
+    return value;
+}
+function resolveExtends(spec, from) {
+    if (spec.startsWith('.') || isAbsolute(spec))
+        return resolve(dirname(from), spec);
+    try {
+        return createRequire(from).resolve(spec);
+    }
+    catch {
+        throw new ConfigError(`${from} extends "${spec}", which cannot be resolved`, 'use a relative path or an installed package');
+    }
+}
+function extendsList(value) {
+    if (typeof value === 'string')
+        return [value];
+    return Array.isArray(value) ? value.map(String) : [];
+}
+export async function loadWithExtends(path, seen = []) {
+    if (seen.includes(path))
+        throw new ConfigError(`config extends itself: ${[...seen, path].join(' → ')}`);
+    const own = await loadFile(path);
+    const parents = own['extends'];
+    const specs = extendsList(parents);
+    let data = {};
+    const chain = [];
+    for (const spec of specs) {
+        const parent = await loadWithExtends(resolveExtends(spec, path), [...seen, path]);
+        data = deepMerge(data, parent.data);
+        chain.push(...parent.chain);
+    }
+    const { extends: _ignored, ...rest } = own;
+    return { path, data: deepMerge(data, rest), chain: [...chain, path] };
+}
+const userConfigDir = (env) => {
+    const base = env['XDG_CONFIG_HOME'] ?? (env['HOME'] === undefined ? undefined : join(env['HOME'], '.config'));
+    return base;
+};
+export function candidates(d) {
+    const out = [];
+    const fromEnv = d.env[`${d.name.toUpperCase().replaceAll('-', '_')}_CONFIG`];
+    if (fromEnv !== undefined)
+        out.push({ path: resolve(d.cwd, fromEnv), reason: `${d.name.toUpperCase().replaceAll('-', '_')}_CONFIG` });
+    for (const ext of EXTENSIONS)
+        out.push({ path: join(d.cwd, `${d.name}.config${ext}`), reason: 'current directory' });
+    const user = userConfigDir(d.env);
+    if (user !== undefined)
+        out.push({ path: join(user, d.name, 'config.json'), reason: 'user config directory' });
+    return out;
+}
+export async function discover(d) {
+    if (d.disabled === true)
+        return undefined;
+    if (d.explicit !== undefined) {
+        const path = resolve(d.cwd, d.explicit);
+        if (!existsSync(path))
+            throw new ConfigError(`config file not found: ${path}`, 'check --config, or drop it to use discovery');
+        return await loadWithExtends(path);
+    }
+    const found = candidates(d)
+        .map((c) => c.path)
+        .find((path) => existsSync(path));
+    if (found === undefined)
+        return undefined;
+    return await loadWithExtends(found);
+}

package/dist/contrast.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Contrast, as a thing the package checks rather than a thing someone remembers.
+ *
+ * A burgee is a mark whose charge sits ON its own field, and whose field sits on
+ * a page nobody here controls. Both of those are contrast relationships, and
+ * both are easy to get wrong in a way that looks fine at 512px and fails at 24.
+ * This module measures them, so `burgee brand` can refuse to emit a flag that
+ * would not clear the floor and CI can hold ours to the same line.
+ *
+ * WCAG 2.2 sets 4.5:1 for body text and 3:1 for large text and for the parts of
+ * a graphic you need in order to understand it. A logo's bars are the latter, so
+ * 3:1 is the floor used here — see `AA`.
+ */
+/** The floors WCAG 2.2 sets, as ratios. */
+export declare const AA: {
+    /** Body text against its background. */
+    readonly TEXT: 4.5;
+    /** Large text, UI components, and meaningful parts of a graphic. */
+    readonly GRAPHIC: 3;
+};
+/** WCAG relative luminance. */
+export declare function luminance(hex: string): number;
+/** The WCAG contrast ratio between two colours. Order does not matter. */
+export declare function contrast(a: string, b: string): number;
+/** Mix two colours in sRGB. Enough for reading a gradient stop, not for colour science. */
+export declare function mix(a: string, b: string, t: number): string;
+export interface ContrastFinding {
+    /** What was compared, in the words someone fixing it would use. */
+    what: string;
+    a: string;
+    b: string;
+    ratio: number;
+    required: number;
+    passes: boolean;
+}
+export declare function ratio(a: string, b: string): number;
+export declare function check(what: string, a: string, b: string, required?: 3): ContrastFinding;
+/** One line per finding, aligned, for a terminal or a failing test. */
+export declare function report(findings: readonly ContrastFinding[]): string;
+/** The field colour at a point along the gradient axis, for stops given in order. */
+export declare function fieldColorAt(stops: ReadonlyArray<{
+    offset: number;
+    color: string;
+}>, at: number): string;
+export interface AuditInput {
+    mark: {
+        lead: string;
+        follow: string;
+    };
+    field: ReadonlyArray<{
+        offset: number;
+        color: string;
+    }>;
+    bordure?: {
+        color: string;
+        width: number;
+    } | ReadonlyArray<{
+        color: string;
+        width: number;
+    }>;
+}
+/**
+ * Every contrast relationship a burgee has to survive.
+ *
+ * Two are intrinsic — each bar against the field beneath it — and hold wherever
+ * the flag is used. The rest depend on where it is placed, so pass the grounds
+ * the flag will actually fly on and they are checked too. A flag that passes the
+ * intrinsic pair and fails a ground has a page problem, not a logo problem.
+ */
+export declare function auditBurgee(brand: AuditInput, grounds?: readonly string[]): ContrastFinding[];

package/dist/contrast.js

@@ -0,0 +1,93 @@
+export const AA = {
+    TEXT: 4.5,
+    GRAPHIC: 3,
+};
+const SRGB_MAX = 255;
+const LINEAR_THRESHOLD = 0.03928;
+const LINEAR_DIVISOR = 12.92;
+const GAMMA_OFFSET = 0.055;
+const GAMMA_SCALE = 1.055;
+const GAMMA_EXPONENT = 2.4;
+const LUMA = { r: 0.2126, g: 0.7152, b: 0.0722 };
+const CONTRAST_OFFSET = 0.05;
+const RED_AT = 1;
+const GREEN_AT = 3;
+const BLUE_AT = 5;
+const HEX_PAIRS = [RED_AT, GREEN_AT, BLUE_AT];
+const HEX_RADIX = 16;
+const SHORT_HEX_LENGTH = 4;
+function channels(hex) {
+    const full = hex.length === SHORT_HEX_LENGTH
+        ? `#${hex[1]}${hex[1]}${hex[2]}${hex[2]}${hex[3]}${hex[3]}`
+        : hex;
+    if (!/^#[0-9a-fA-F]{6}$/.test(full))
+        throw new Error(`burgee: "${hex}" is not a hex colour`);
+    const parsed = HEX_PAIRS.map((i) => Number.parseInt(full.slice(i, i + 2), HEX_RADIX) / SRGB_MAX);
+    return parsed;
+}
+export function luminance(hex) {
+    const [r, g, b] = channels(hex).map((v) => v <= LINEAR_THRESHOLD ? v / LINEAR_DIVISOR : ((v + GAMMA_OFFSET) / GAMMA_SCALE) ** GAMMA_EXPONENT);
+    return LUMA.r * r + LUMA.g * g + LUMA.b * b;
+}
+export function contrast(a, b) {
+    const [hi, lo] = [luminance(a), luminance(b)].sort((x, y) => y - x);
+    return (hi + CONTRAST_OFFSET) / (lo + CONTRAST_OFFSET);
+}
+export function mix(a, b, t) {
+    const [ca, cb] = [channels(a), channels(b)];
+    const hex = ca
+        .map((v, i) => Math.round((v + (cb[i] - v) * t) * SRGB_MAX))
+        .map((v) => v.toString(HEX_RADIX).padStart(2, '0'))
+        .join('');
+    return `#${hex}`;
+}
+const CENTS = 100;
+export function ratio(a, b) {
+    return Math.round(contrast(a, b) * CENTS) / CENTS;
+}
+export function check(what, a, b, required = AA.GRAPHIC) {
+    const value = ratio(a, b);
+    return { what, a, b, ratio: value, required, passes: value >= required };
+}
+export function report(findings) {
+    const width = Math.max(...findings.map((f) => f.what.length));
+    return findings
+        .map((f) => `${f.passes ? 'pass' : 'FAIL'}  ${f.what.padEnd(width)}  ` +
+        `${f.a} on ${f.b}  ${f.ratio.toFixed(2)}:1 (needs ${f.required}:1)`)
+        .join('\n');
+}
+export function fieldColorAt(stops, at) {
+    const ordered = [...stops].sort((x, y) => x.offset - y.offset);
+    const first = ordered[0];
+    const last = ordered.at(-1);
+    if (first === undefined || last === undefined)
+        throw new Error('burgee: a field needs at least one stop');
+    if (at <= first.offset)
+        return first.color;
+    if (at >= last.offset)
+        return last.color;
+    for (let i = 1; i < ordered.length; i++) {
+        const lo = ordered[i - 1];
+        const hi = ordered[i];
+        if (at <= hi.offset) {
+            const span = hi.offset - lo.offset;
+            return span === 0 ? hi.color : mix(lo.color, hi.color, (at - lo.offset) / span);
+        }
+    }
+    return last.color;
+}
+const CHARGE_AT = 0.5;
+export function auditBurgee(brand, grounds = []) {
+    const under = fieldColorAt(brand.field, CHARGE_AT);
+    const findings = [
+        check('leading bar on its field', brand.mark.lead, under),
+        check('following bar on its field', brand.mark.follow, under),
+    ];
+    const edges = [fieldColorAt(brand.field, 0), fieldColorAt(brand.field, 1)];
+    for (const ground of grounds) {
+        for (const edge of edges) {
+            findings.push(check(`flag edge on ${ground}`, edge, ground));
+        }
+    }
+    return findings;
+}