linegauge/plugin

import { setOverrides, overrides, problems, … } from 'linegauge/plugin';

FunctionsCopy Anchor Link

overridesCopy Anchor Link

Every override currently registered, by plugin name — what linegauge check prints.

function overrides(): ReadonlyMap<string, Record<string, WidthOverride>>;

Returns ReadonlyMap<string, Record<string, WidthOverride>>

problemsCopy Anchor Link

Everything wrong with a plugin document, in the family's vocabulary. Empty means it registers.

function problems(plugin: unknown): Problem[];

Returns Problem[]

registerCopy Anchor Link

Register a plugin's width overrides. Later registrations win over earlier ones, and over the built-in tables — which is the point: the built-in answer is right for most terminals and the user is the authority on theirs.

function register(plugin: unknown): void;

Returns void

setOverridesCopy Anchor Link

Later registrations win, which is the point: the user is the authority on their terminal.

An empty table removes the plugin rather than recording that it contributes nothing. overrides() is what linegauge check prints and what a caller inspects, and a name in it with no ranges under it reads as this plugin is active when the truth is the opposite.

The seam in width.ts is installed only while something is registered, so the last plugin leaving puts measure back on the path with no call in it at all.

function setOverrides(name: string, widths: Record<string, WidthOverride>): void;

Returns void

validateCopy Anchor Link

Throws on the first problem, in the family's vocabulary.

function validate(plugin: unknown): asserts plugin is Plugin;

Returns asserts plugin is Plugin

ClassesCopy Anchor Link

PluginErrorCopy Anchor Link

A refused plugin says what is wrong and what to do about it — the family's one vocabulary.

class PluginError extends Error {
    readonly code: PluginErrorCode;
    readonly fix: string;
    constructor(code: PluginErrorCode, message: string, fix: string);
}

ConstantsCopy Anchor Link

CONTRACTCopy Anchor Link

The plugin contract version. One number for the family — the same 1 flagstaff, caique, closeout and paratext declare, written out rather than imported for the reason above.

const CONTRACT = 1;

InterfacesCopy Anchor Link

PluginCopy Anchor Link

The keys linegauge reads. Declared structurally: any object with these fields is a plugin here, whatever else it carries.

interface Plugin {
    name: string;
    contract?: number;
    /** Width overrides by name. The key is the author's label; see {@link validate}. */
    widths?: Record<string, WidthOverride>;
}

WidthOverrideCopy Anchor Link

One plugin-supplied width override: the column count a set of code-point ranges occupies.

interface WidthOverride {
    /** Inclusive `[low, high]` code-point pairs. */
    ranges: readonly (readonly [number, number])[];
    /** 0 for a zero-width mark, 1 narrow, 2 wide. */
    columns: number;
    /** Which terminal or font disagrees, and how it was measured. Required; see the file comment. */
    why: string;
}

TypesCopy Anchor Link

PluginErrorCodeCopy Anchor Link

Two codes, both already in the family's vocabulary (scripts/plugin-error-vocabulary-lock.test.ts).

type PluginErrorCode = 'E_PLUGIN_SCHEMA' | 'E_PLUGIN_CONTRACT' | 'E_NO_CONTRIBUTION';