seniority/plugin

The plugin host for seniority's half of the contract (plugin-contract R1, R5a, R6, R7, R8).

import { validate, register, reset, … } from 'seniority/plugin';

FunctionsCopy Anchor Link

registerCopy Anchor Link

Register a plugin. Later wins at an equal rank, like ESLint flat config: the array is ordered, a caller reads it top to bottom, and the last word on a source is the one nearest the program.

function register(plugin: unknown): void;

Returns void

registeredCopy Anchor Link

The plugins registered, in registration order — oldest first, which is the order a reader reads them in.

function registered(): readonly Plugin[];

Returns readonly Plugin[]

resetCopy Anchor Link

Forget every registered plugin. For tests, and for a program that re-registers at runtime.

function reset(): void;

Returns void

sourcesCopy Anchor Link

Every registered source, read against this runtime and sorted by rank — the array resolve takes as layers.sources.

function sources(runtime: SourceRuntime): SourceLayer[];

Returns SourceLayer[]

validateCopy Anchor Link

Refuse a plugin that cannot contribute a source, at the door.

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 declares, written out rather than imported for the reason in the file comment above.

const CONTRACT = 1;

InterfacesCopy Anchor Link

PluginCopy Anchor Link

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

interface Plugin {
    name: string;
    contract?: number;
    sources?: Record<string, SourceSpec>;
}

SourceReadCopy Anchor Link

What a read returns when it has something to say.

interface SourceRead {
    values: Record<string, unknown>;
    /** Where a person would look. Falls back to the source's `location`, then to its name. */
    location?: string;
}

SourceRuntimeCopy Anchor Link

What a source is handed. Declared structurally and deliberately small: env and cwd are what a vault, a CI variable set or a remote config needs, and anything a plugin could do with process directly it should be given instead (R11, Y9).

interface SourceRuntime {
    env: Record<string, string | undefined>;
    cwd: string;
}

SourceSpecCopy Anchor Link

One source a plugin contributes, keyed in sources by the name --explain prints.

interface SourceSpec {
    /** Against `RANK`: strictly between `RANK.flag` and `RANK.default`. */
    rank: number;
    values?: Record<string, unknown>;
    location?: string;
    read?: (runtime: SourceRuntime) => SourceRead | undefined;
}

TypesCopy Anchor Link

PluginErrorCodeCopy Anchor Link

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