@mistriwork/engine 0.0.0-stage → 1.0.0-rc.10

package/dist/shared/suggest.js

@@ -0,0 +1,59 @@
+/*
+ * Near-miss suggestions for error messages: "did you mean", and a list short
+ * enough to read. One copy, because the query language, view paths and the
+ * MCP argument check each grew their own edit distance.
+ */
+/**
+ * Levenshtein distance, capped: names more than three characters apart in
+ * length score 99 without the table being built. Only ever used to suggest
+ * a near miss, where anything that far off is no suggestion at all.
+ */
+export function distance(a, b) {
+    if (Math.abs(a.length - b.length) > 3)
+        return 99;
+    const prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+        let last = prev[0];
+        prev[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const tmp = prev[j];
+            prev[j] = Math.min(prev[j] + 1, prev[j - 1] + 1, last + (a[i - 1] === b[j - 1] ? 0 : 1));
+            last = tmp;
+        }
+    }
+    return prev[b.length];
+}
+/** The candidate closest to `name` ignoring case, if one is within three edits. */
+export function nearest(name, candidates) {
+    const near = candidates.map((c) => ({ c, d: apart(name.toLowerCase(), c.toLowerCase()) })).sort((a, b) => a.d - b.d)[0];
+    return near && near.d <= 3 ? near.c : undefined;
+}
+/* Two letters swapped is the commonest slip and two edits by the distance:
+   it ranks ahead of any one-letter change, so `lable` finds `label`, not
+   `table`. It never brings a name inside the three edits that was not. */
+function apart(a, b) {
+    const d = distance(a, b);
+    return d === 2 && [...a].sort().join('') === [...b].sort().join('') ? 0.5 : d;
+}
+/**
+ * The refusal of a key its place does not take, after the place:
+ * `has no "lable". Did you mean "label"? It takes: …`, the caller ending the
+ * sentence. A key some other place takes (`homes`) is told where it belongs
+ * instead: it is spelled right and put in the wrong place. A key here one
+ * slip away still wins, since a typo is the likelier mistake.
+ */
+export function unknownKey(key, takes, homes = []) {
+    const found = nearest(key, takes);
+    const d = found === undefined ? Infinity : apart(key.toLowerCase(), found.toLowerCase());
+    /* Three edits is near for a long key and another word for a short one:
+       `sql` is not `all`, nor `when` `other`, nor `name` `base`. A slip, or less than half the shorter. */
+    const near = found !== undefined && (d <= 1 || d < Math.min(key.length, found.length) / 2) ? found : undefined;
+    const slip = near !== undefined && d <= 1;
+    const where = homes.length > 1 ? `${homes.slice(0, -1).join(', ')} or ${homes[homes.length - 1]}` : homes[0];
+    const hint = where && !slip ? ` "${key}" belongs ${where}.` : near ? ` Did you mean "${near}"?` : '';
+    return `has no "${key}".${hint} It takes: ${takes.join(', ')}`;
+}
+/** A short list for an error message; long lists help nobody. */
+export function shortList(items) {
+    return items.length > 6 ? `${items.slice(0, 6).join(', ')}, …` : items.join(', ');
+}

package/dist/shared/tableSizing.d.ts

@@ -0,0 +1,4 @@
+export type TableSizing = 'fit' | 'scroll';
+export declare const TABLE_SIZINGS: readonly TableSizing[];
+/** Omission preserves the renderer's fit default without rewriting authored config. */
+export declare function parseTableSizing(value: unknown, at: string): TableSizing | undefined;

package/dist/shared/tableSizing.js

@@ -0,0 +1,9 @@
+export const TABLE_SIZINGS = ['fit', 'scroll'];
+/** Omission preserves the renderer's fit default without rewriting authored config. */
+export function parseTableSizing(value, at) {
+    if (value === undefined)
+        return undefined;
+    if (value !== 'fit' && value !== 'scroll')
+        throw new Error(`${at} has an invalid "sizing". Use "fit" or "scroll".`);
+    return value;
+}

package/dist/shared/tagLists.d.ts

@@ -0,0 +1,57 @@
+/**
+ * A record's tags read like a column: `tags` in a list's `show` draws its
+ * chips, `filters: ['tags']` offers each tag as a choice, and the query
+ * language asks `tags has bug` or `tags has (bug, docs)` — any of them.
+ *
+ * Like a rollup (rollups.ts), the tags are never a column of the table. The
+ * App's catalog carries them beside the columns (`TableMeta.tags`, from the
+ * resource's `tags: { through, to, tone }`, appResourceRules.appTagRules), so
+ * an insert form, a plain read or an export of the table never names them,
+ * and only the view compiler writes them: the list as one JSON array per row
+ * through a correlated subquery, `has` as an EXISTS over the link rows. Both
+ * read the link and tag tables through the statement's own relations
+ * (rowScope.ts), so a row policy or a tenant scope on either narrows the tags
+ * exactly as it narrows a related list of them, and a reader whose catalog
+ * cannot see the link table or the tags is served none (the rule is resolved
+ * against the reader's catalog).
+ */
+import type { ColumnMeta } from './schema.js';
+/** The name a record's tags are read by, in a path, a `show` and a filter. */
+export declare const TAGS_COLUMN = "tags";
+/** The type a record's tags carry where a column's would be: no column has it. */
+export declare const TAGS_TYPE = "tags";
+/** A record's tags as the catalog serves them and a view carries them: no request ever supplies one. */
+export interface TagSet {
+    /** The link table's id. */
+    through: string;
+    /** The link column holding the record's key, and the record's column it points at. */
+    from: string;
+    key: string;
+    /** The tag table's id. */
+    to: string;
+    /** The link column holding the tag's key, and the tag's column it points at. */
+    via: string;
+    tagKey: string;
+    /** The tag's naming column: what a chip says and `has` compares. */
+    label: string;
+    /** The tag's tone column (good | warn | bad | info | neutral), where it has one. */
+    tone?: string;
+}
+/** A view's tags, keyed by path ('tags', or 'project_id.tags'): the set and the prefix of the record it hangs off. */
+export interface TagPath extends TagSet {
+    on: string;
+}
+/** The tags read as a column: never written, never null (a record without tags has none). */
+export declare function tagsColumnMeta(name?: string): ColumnMeta;
+/** One tag as a cell draws it. */
+interface TagChip {
+    label: string;
+    tone?: string;
+}
+/**
+ * A row's tags as the database answered them: a JSON array of [label, tone]
+ * pairs, parsed already (PostgreSQL's json) or as text (SQLite).
+ * Sorted by label, so every engine's answer reads the same; anything else is no tags.
+ */
+export declare function tagChips(value: unknown): TagChip[];
+export {};

package/dist/shared/tagLists.js

@@ -0,0 +1,34 @@
+/** The name a record's tags are read by, in a path, a `show` and a filter. */
+export const TAGS_COLUMN = 'tags';
+/** The type a record's tags carry where a column's would be: no column has it. */
+export const TAGS_TYPE = 'tags';
+/** The tags read as a column: never written, never null (a record without tags has none). */
+export function tagsColumnMeta(name = TAGS_COLUMN) {
+    return { name, type: TAGS_TYPE, nullable: false, primaryKey: false, writable: false };
+}
+/**
+ * A row's tags as the database answered them: a JSON array of [label, tone]
+ * pairs, parsed already (PostgreSQL's json) or as text (SQLite).
+ * Sorted by label, so every engine's answer reads the same; anything else is no tags.
+ */
+export function tagChips(value) {
+    let list = value;
+    if (typeof list === 'string') {
+        try {
+            list = JSON.parse(list);
+        }
+        catch {
+            return [];
+        }
+    }
+    if (!Array.isArray(list))
+        return [];
+    const chips = [];
+    for (const item of list) {
+        const [label, tone] = Array.isArray(item) ? item : [item];
+        if (label === null || label === undefined || label === '')
+            continue;
+        chips.push({ label: String(label), ...(typeof tone === 'string' && tone ? { tone } : {}) });
+    }
+    return chips.sort((a, b) => a.label.localeCompare(b.label));
+}

package/dist/shared/textRules.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Text rules on a column: how long a value may be and what form it takes,
+ * in the words a command's text input already uses (packages/mistri/schema/command.d.ts):
+ *
+ *   text: { code: { pattern: '^[A-Z]{3}$', message: 'Three capital letters' }, name: { min: 2, max: 80 } }
+ *
+ * Two places say them. The App, on the resource (`text`), and the database
+ * itself: a `varchar(80)` holds at most 80 characters, and on PostgreSQL a
+ * `CHECK (char_length(name) >= 2)` or `CHECK (code ~ '^[A-Z]{3}$')` in that
+ * simple form says the rest (adapters read them into `ColumnMeta.text`). A
+ * schema-first App gets the database's words free; what the App says wins,
+ * key by key.
+ *
+ * The browser judges a value as it is typed and says the rule under the
+ * field; the server judges the stored row on every write (appValidation.ts),
+ * whichever door the write came through. Pure: both sides read this one
+ * judgement, so they cannot disagree about what "at least 2" counts.
+ */
+import { type ColumnMeta } from './schema.js';
+/** A column's rule: fewest and most characters, a regular expression the whole value matches, and what to say. */
+export interface TextRule {
+    /** Fewest characters, after trimming. */
+    min?: number;
+    /** Most characters. */
+    max?: number;
+    /** A regular expression the whole value must match, as its source text. */
+    pattern?: string;
+    /** What the form says when the rule is not met; a generic sentence otherwise. */
+    message?: string;
+}
+/** Which part of a rule a value breaks. */
+type TextRuleBreak = 'min' | 'max' | 'pattern';
+/**
+ * `resources.<name>.text`, read: an object of the resource's own columns, each
+ * { min?, max?, pattern?, message? } with something to check. Throws the
+ * sentence the author reads.
+ */
+export declare function parseTextRules(raw: unknown, at: string): Record<string, TextRule>;
+/** Why a resource's text rules cannot run on this table, or undefined. Each must name a text column. */
+export declare function textRulesProblem(rules: Readonly<Record<string, TextRule>>, columns: readonly ColumnMeta[], table: string): string | undefined;
+/**
+ * The rule a column is held to: the database's (`ColumnMeta.text`) with the
+ * App's on top, key by key. Undefined where neither says anything.
+ */
+export declare function columnTextRule(column: Pick<ColumnMeta, 'text'>, authored?: TextRule): TextRule | undefined;
+/** What a value breaks of its rule, or undefined. An empty value breaks nothing: whether one is needed is NOT NULL's to say. */
+export declare function textRuleBreak(rule: TextRule, value: unknown): TextRuleBreak | undefined;
+/** A column's catalog rule as the database states it, for `ColumnMeta.text`; undefined where it states none. */
+export declare function catalogTextRule(parts: {
+    max?: number | null;
+    min?: number;
+    pattern?: string;
+}): ColumnMeta['text'];
+export {};

package/dist/shared/textRules.js

@@ -0,0 +1,133 @@
+/**
+ * Text rules on a column: how long a value may be and what form it takes,
+ * in the words a command's text input already uses (packages/mistri/schema/command.d.ts):
+ *
+ *   text: { code: { pattern: '^[A-Z]{3}$', message: 'Three capital letters' }, name: { min: 2, max: 80 } }
+ *
+ * Two places say them. The App, on the resource (`text`), and the database
+ * itself: a `varchar(80)` holds at most 80 characters, and on PostgreSQL a
+ * `CHECK (char_length(name) >= 2)` or `CHECK (code ~ '^[A-Z]{3}$')` in that
+ * simple form says the rest (adapters read them into `ColumnMeta.text`). A
+ * schema-first App gets the database's words free; what the App says wins,
+ * key by key.
+ *
+ * The browser judges a value as it is typed and says the rule under the
+ * field; the server judges the stored row on every write (appValidation.ts),
+ * whichever door the write came through. Pure: both sides read this one
+ * judgement, so they cannot disagree about what "at least 2" counts.
+ */
+import { columnKind } from './schema.js';
+const TEXT_RULE_KEYS = ['min', 'max', 'pattern', 'message'];
+/** The most characters a rule may name, as a command's text input. */
+const TEXT_RULE_MOST = 16384;
+const MESSAGE_MOST = 200;
+const PATTERN_MOST = 500;
+const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** A pattern's source as a whole-value test, or undefined where JavaScript cannot read it. */
+function wholePattern(source) {
+    try {
+        return new RegExp(`^(?:${source})$`, 'u');
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * `resources.<name>.text`, read: an object of the resource's own columns, each
+ * { min?, max?, pattern?, message? } with something to check. Throws the
+ * sentence the author reads.
+ */
+export function parseTextRules(raw, at) {
+    const shape = `${at} has a "text" that is not an object of the resource's own column → { min?, max?, pattern?, message? }, like text: { code: { pattern: '^[A-Z]{3}$' } }.`;
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw) || !Object.keys(raw).length)
+        throw new Error(shape);
+    const rules = {};
+    for (const [column, value] of Object.entries(raw)) {
+        const here = `${at}, text "${column}"`;
+        if (!IDENTIFIER.test(column))
+            throw new Error(`${here}: a text rule is keyed by the resource's own column, never a path.`);
+        if (!value || typeof value !== 'object' || Array.isArray(value))
+            throw new Error(shape);
+        const given = value;
+        const unknown = Object.keys(given).find((key) => !TEXT_RULE_KEYS.includes(key));
+        if (unknown)
+            throw new Error(`${here} has "${unknown}"; a text rule takes min, max, pattern and message.`);
+        const rule = {};
+        for (const key of ['min', 'max']) {
+            if (given[key] === undefined)
+                continue;
+            const n = given[key];
+            if (typeof n !== 'number' || !Number.isInteger(n) || n < 1 || n > TEXT_RULE_MOST) {
+                throw new Error(`${here}: "${key}" must be a whole number of characters from 1 to ${TEXT_RULE_MOST}.`);
+            }
+            rule[key] = n;
+        }
+        if (rule.min !== undefined && rule.max !== undefined && rule.min > rule.max)
+            throw new Error(`${here}: "min" is more than "max".`);
+        if (given.pattern !== undefined) {
+            const source = given.pattern;
+            if (typeof source !== 'string' || !source || source.length > PATTERN_MOST) {
+                throw new Error(`${here}: "pattern" must be a regular expression's source text, at most ${PATTERN_MOST} characters.`);
+            }
+            if (!wholePattern(source))
+                throw new Error(`${here}: "pattern" is not a regular expression JavaScript can read: ${source}`);
+            rule.pattern = source;
+        }
+        if (given.message !== undefined) {
+            if (typeof given.message !== 'string' || !given.message.trim() || given.message.length > MESSAGE_MOST) {
+                throw new Error(`${here}: "message" must be a sentence of 1 to ${MESSAGE_MOST} characters.`);
+            }
+            rule.message = given.message.trim();
+        }
+        if (rule.min === undefined && rule.max === undefined && rule.pattern === undefined) {
+            throw new Error(`${here} checks nothing; give it a "min", a "max" or a "pattern".`);
+        }
+        rules[column] = rule;
+    }
+    return rules;
+}
+/** Why a resource's text rules cannot run on this table, or undefined. Each must name a text column. */
+export function textRulesProblem(rules, columns, table) {
+    for (const name of Object.keys(rules)) {
+        const column = columns.find((candidate) => candidate.name === name);
+        if (!column)
+            return `text "${name}": "${table}" has no column "${name}".`;
+        if (columnKind(column.type) !== 'text' || column.allowed?.length) {
+            return `text "${name}" is ${column.allowed?.length ? 'a vocabulary' : column.type || 'untyped'}; a text rule checks a text column.`;
+        }
+    }
+    return undefined;
+}
+/**
+ * The rule a column is held to: the database's (`ColumnMeta.text`) with the
+ * App's on top, key by key. Undefined where neither says anything.
+ */
+export function columnTextRule(column, authored) {
+    const rule = { ...(column.text ?? {}), ...(authored ?? {}) };
+    return rule.min === undefined && rule.max === undefined && rule.pattern === undefined ? undefined : rule;
+}
+/** Characters as a person counts them, and as `char_length` does: code points, not UTF-16 units. */
+const length = (text) => [...text].length;
+/** What a value breaks of its rule, or undefined. An empty value breaks nothing: whether one is needed is NOT NULL's to say. */
+export function textRuleBreak(rule, value) {
+    if (typeof value !== 'string' || value === '')
+        return undefined;
+    if (rule.min !== undefined && length(value.trim()) < rule.min)
+        return 'min';
+    if (rule.max !== undefined && length(value) > rule.max)
+        return 'max';
+    if (rule.pattern !== undefined && !wholePattern(rule.pattern)?.test(value))
+        return 'pattern';
+    return undefined;
+}
+/** A column's catalog rule as the database states it, for `ColumnMeta.text`; undefined where it states none. */
+export function catalogTextRule(parts) {
+    const rule = {};
+    if (typeof parts.max === 'number' && Number.isInteger(parts.max) && parts.max > 0)
+        rule.max = parts.max;
+    if (parts.min !== undefined && parts.min > 0)
+        rule.min = parts.min;
+    if (parts.pattern !== undefined)
+        rule.pattern = parts.pattern;
+    return Object.keys(rule).length ? rule : undefined;
+}

package/dist/shared/theme.d.ts

@@ -0,0 +1,94 @@
+import type { ThemeDefinition, ThemePalette, ThemeRecipes } from '../../schema/theme.js';
+import { type AppAccent } from './themePresets.js';
+import { HEAT_TOP, heatTop } from './themeColor.js';
+export { FONT_TOKENS, PALETTE_TOKENS, RADIUS_TOKENS, shapeTokens, THEME_BASES } from './themeTokens.js';
+export type { ThemeBase, ThemeDefinition, ThemePalette, ThemePaletteVariant } from '../../schema/theme.js';
+export declare function parseThemes(raw: unknown, where: string, key?: string): ThemeDefinition[] | undefined;
+/**
+ * What a theme's shape says that `check` warns of (theme-radius): a panel squarer than the controls it holds, its
+ * corner cutting under theirs. A round control is a pill, not a corner, so it is never measured against a panel.
+ */
+export declare function themeShapeWarnings(themes: readonly ThemeDefinition[]): string[];
+/**
+ * What a theme's shadow says that `check` warns of (theme-shadow, the contract's C2): a shadow lighter than the ground
+ * it falls on, which draws a glow round a card or a menu rather than lifting it off the page — the edge the lift was
+ * for is lost. The theme still wears.
+ */
+export declare function themeShadowWarnings(themes: readonly ThemeDefinition[]): string[];
+/**
+ * What a banded table's parts say that `check` warns of (theme-band, the contract's C13): a `status` or `tag` part
+ * given an opaque ground. Part rules live in the `theme` cascade layer, above the `look` layer's band, so the chip
+ * keeps its own ground on every other row and shows as a pale column. The author's color is not touched: a
+ * translucent ground lets the band through, and so does the default.
+ */
+export declare function themeBandWarnings(themes: readonly ThemeDefinition[]): string[];
+/**
+ * What a theme's type says that `check` warns of (theme-type, the contract's C8): a role heavier than 700 whose face
+ * leads with a family the theme does not ship at that weight. design.md keeps titles at 700 or under for this: a
+ * heavier weight a family has no file for is drawn by the browser as a smeared 700, or resolves a book face to its
+ * Black cut, a masthead where a title was meant.
+ */
+export declare function themeTypeWarnings(themes: readonly ThemeDefinition[]): string[];
+export declare function contrastRatio(a: string, b: string): number;
+/**
+ * The least luminance ratio a field's fill may be from the ground and the surface it sits on, when the field draws
+ * no edge. 1.08:1 is Lintel's Hearth (a warm #eeede7 well on a #f7f6f2 page, 1.085, and on white, 1.173): the faintest
+ * field we ship that still reads as a well, and the faintest a calibrated laptop screen shows in daylight. Below it
+ * (white on #fcfbf8, 1.03) the field is gone. WCAG 1.4.11 asks 3:1 of a control's boundary unless it is identified
+ * some other way; the label stands over the field and the focus ring draws a 2px edge, which is that other way.
+ */
+export declare const EDGELESS_FIELD_DELTA = 1.08;
+export { HEAT_TOP, heatTop };
+/**
+ * The colours a platform component mixes from a theme's series and its ink rather than wears as a token: no pair of
+ * tokens is what it draws, so each is measured as drawn, and named by the series it comes from. A board card's
+ * category chip (TriageBoard.css: 45% of its series in the ink, except under the `strip` board, which says it in words, on a 13% tint of it over the card), a person's
+ * initials on their avatar (features.css: 45% in the ink, on a 15% tint over a 7% ink wash), and under the `icon`
+ * stat recipe, a stat card's mark (lumenLook.css: 80% in the ink on a 12% tint, a graphic at 3:1). `check` holds a
+ * theme to each, and `grade` names the series behind a reading of one.
+ */
+export declare function componentInks(palette: ThemePalette, recipes?: Partial<ThemeRecipes>): Array<{
+    role: keyof ThemePalette;
+    what: string;
+    fg: string;
+    bg: string;
+    needs: number;
+}>;
+/**
+ * The pairs a role is read in (CONTRAST_PAIRS), measured with `value` drawn in its place: what an author wrote for a
+ * colour the page wears as another (a link written as the accent is drawn in the accent's ink), so the colour as
+ * written is held to the rule its role is.
+ */
+export declare function rolePairs(palette: ThemePalette, role: keyof ThemePalette, value: string): Array<{
+    background: keyof ThemePalette;
+    needs: number;
+    what?: string;
+    ratio: number;
+}>;
+/** One failed check: which theme, palette and mode, the role it is about, and the sentence for it. */
+export interface ThemeFinding {
+    themeId: string;
+    paletteId: string;
+    mode: 'light' | 'dark';
+    /** The role (`accent`, `navMuted`, `chart3`); rolePath gives the spec's name for it (`nav.muted`, `chart[2]`). */
+    token: keyof ThemePalette;
+    /** What the check measures, in a few words: "accent on surface", "chart2 beside chart3 for deuteranopia". */
+    check: string;
+    ratio: number;
+    needs: number;
+    message: string;
+}
+export declare function themeWarnings(themes: readonly ThemeDefinition[], own?: {
+    accent?: AppAccent;
+}): string[];
+/** Every failed check of the themes; with `all`, every check measured, passed or not (a fix reads what it reaches). */
+export declare function themeFindings(themes: readonly ThemeDefinition[], own?: {
+    accent?: AppAccent;
+}, all?: boolean): ThemeFinding[];
+/** Readers can select any offered look, so App-wide overrides are checked on
+    built-ins too. Without overrides retain the registered-theme warning scope. */
+export declare function appThemeWarnings(themes: readonly ThemeDefinition[], own?: {
+    accent?: AppAccent;
+    radius?: string;
+    font?: string;
+}): string[];