team 0.1.1 → 0.2.0

package/dist/file/sections/budgets.js

@@ -0,0 +1,180 @@
+import { measureSchema, DURATION, PERCENT } from "./units.js";
+import { valueOf } from "./section.js";
+import { defaultWatch } from "./watch.js";
+export const budgets = {
+    name: 'budgets',
+    owner: true,
+    after: ['watch'],
+    validate(entry, ctx) {
+        const watched = valueOf(ctx, 'watch');
+        return readBudgets(entry, ctx.check, watched.watch.quotaMarks, watched.legacyMarks);
+    },
+    schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+            stale_after: measureSchema(DURATION),
+            check_every: measureSchema(DURATION),
+            marks: { type: 'array', minItems: 1, items: { type: 'number', exclusiveMinimum: 0, maximum: 100 } },
+            accounts: {
+                type: 'object',
+                additionalProperties: {
+                    type: 'object',
+                    additionalProperties: false,
+                    properties: {
+                        kind: { enum: ['subscription', 'spend'] },
+                        shared: { type: 'boolean' },
+                        reserve: measureSchema(PERCENT),
+                        floor: { type: 'string', pattern: '^[0-9]+(?:\\.[0-9]{1,4})? [A-Z]{3}$' },
+                        sources: { type: 'array', minItems: 1, items: { enum: ['check', 'status_line'] } },
+                        check: { type: 'string', pattern: '^\\S+$' },
+                    },
+                    required: ['kind'],
+                    allOf: [
+                        {
+                            if: { properties: { kind: { const: 'subscription' } }, required: ['kind'] },
+                            then: { required: ['reserve'] },
+                            else: { required: ['floor'] },
+                        },
+                    ],
+                },
+                $comment: 'a subscription has a reserve, a spend account a floor; a spend account never reads a screen',
+            },
+        },
+    },
+};
+/**
+ * The budget values a file that sets none runs with — and, since the section is the owner's, the
+ * values a file runs with until the owner approves what it sets instead. No accounts: nothing is
+ * budgeted until the owner names one.
+ */
+export function defaultBudgets() {
+    return { staleAfter: 30 * 60, checkEvery: 10 * 60, marks: defaultWatch().quotaMarks, accounts: {} };
+}
+function readBudgets(entry, check, fallbackMarks, legacyMarks) {
+    const base = { ...defaultBudgets(), marks: fallbackMarks };
+    if (!entry)
+        return { budgets: base, declared: new Set() };
+    const fields = check.fields(entry.value, 'budgets', ['stale_after', 'check_every', 'marks', 'accounts']);
+    // Every name the accounts map writes, whether or not the account itself reads cleanly: a seat
+    // naming one of these is not also told it named nothing.
+    const accounts = fields.get('accounts');
+    const declared = new Set(accounts?.value.kind === 'map' ? accounts.value.entries.map((account) => account.key) : []);
+    const marks = percentList(fields.get('marks'), 'budgets.marks', check);
+    if (marks && legacyMarks) {
+        check.warnings.push({ line: fields.get('marks')?.line ?? entry.line, message: 'budgets.marks replaces watch.quota_marks' });
+    }
+    return {
+        budgets: {
+            staleAfter: check.measure(fields.get('stale_after'), 'budgets.stale_after', DURATION, '30m') ?? base.staleAfter,
+            checkEvery: check.measure(fields.get('check_every'), 'budgets.check_every', DURATION, '10m') ?? base.checkEvery,
+            marks: marks ?? fallbackMarks,
+            accounts: readAccounts(fields.get('accounts'), check),
+        },
+        declared,
+    };
+}
+function percentList(entry, name, check) {
+    if (!entry)
+        return null;
+    const node = entry.value;
+    const numbers = node.kind === 'seq' ? node.items.map((item) => (item.kind === 'scalar' ? item.value : null)) : null;
+    if (numbers && numbers.length > 0 && numbers.every((n) => typeof n === 'number' && n > 0 && n <= 100))
+        return numbers;
+    check.fail(node.line, `${name} must be a list of percentages, such as [50, 75, 90]`);
+    return null;
+}
+function readAccounts(entry, check) {
+    const accounts = {};
+    if (!entry)
+        return accounts;
+    if (entry.value.kind !== 'map') {
+        check.fail(entry.value.line, 'budgets.accounts must be a map');
+        return accounts;
+    }
+    for (const account of entry.value.entries) {
+        const fields = check.fields(account.value, `budgets.accounts.${account.key}`, ['kind', 'shared', 'reserve', 'floor', 'sources', 'check']);
+        const kind = check.oneOf(fields.get('kind'), `budgets.accounts.${account.key}.kind`, ['subscription', 'spend']);
+        if (!kind) {
+            check.fail(account.line, `budgets.accounts.${account.key} needs kind`);
+            continue;
+        }
+        const command = check.text(fields.get('check'), `budgets.accounts.${account.key}.check`) ?? null;
+        if (command && /\s/.test(command)) {
+            check.fail(fields.get('check')?.line ?? account.line, `budgets.accounts.${account.key}.check names one command, with no arguments; use a wrapper`);
+        }
+        const sources = sourcesOf(fields.get('sources'), account.key, kind, Boolean(command) && !/\s/.test(command ?? ''), check, account.line);
+        if (sources.includes('check') && !command)
+            check.fail(account.line, `budgets.accounts.${account.key} needs check`);
+        if (command && !/\s/.test(command) && !sources.includes('check')) {
+            check.fail(fields.get('check')?.line ?? account.line, `budgets.accounts.${account.key}.check needs sources to list check`);
+        }
+        const measured = kind === 'subscription'
+            ? check.measure(fields.get('reserve'), `budgets.accounts.${account.key}.reserve`, PERCENT, '20%')
+            : undefined;
+        const reserve = measured !== undefined && measured > 0 && measured <= 100 ? measured : null;
+        if (kind === 'subscription' && measured !== undefined && (measured <= 0 || measured > 100)) {
+            check.fail(fields.get('reserve')?.line ?? account.line, `budgets.accounts.${account.key}.reserve must be a percentage above 0 and at most 100, such as 20%`);
+        }
+        if (kind === 'subscription' && !fields.get('reserve'))
+            check.fail(account.line, `budgets.accounts.${account.key} needs reserve`);
+        if (kind === 'spend' && fields.get('reserve'))
+            check.fail(fields.get('reserve')?.line ?? account.line, 'a spend account has a floor, not a reserve');
+        const floor = kind === 'spend' ? money(fields.get('floor'), account.key, check) : null;
+        if (kind === 'spend' && !fields.get('floor'))
+            check.fail(account.line, `budgets.accounts.${account.key} needs floor`);
+        if (kind === 'subscription' && fields.get('floor'))
+            check.fail(fields.get('floor')?.line ?? account.line, 'a subscription has a reserve, not a floor');
+        accounts[account.key] = {
+            kind,
+            shared: check.flag(fields.get('shared'), `budgets.accounts.${account.key}.shared`),
+            reserve,
+            floor,
+            sources,
+            check: command,
+        };
+    }
+    return accounts;
+}
+function sourcesOf(entry, account, kind, hasCheck, check, line) {
+    if (!entry) {
+        if (hasCheck)
+            return ['check'];
+        if (kind === 'subscription')
+            return ['status_line'];
+        check.fail(line, `budgets.accounts.${account} needs check`);
+        return [];
+    }
+    const items = check.list(entry, `budgets.accounts.${account}.sources`);
+    if (items.length === 0) {
+        check.fail(entry.line, `budgets.accounts.${account} needs a source`);
+        return [];
+    }
+    const sources = [];
+    for (const item of items) {
+        if (item.value !== 'check' && item.value !== 'status_line') {
+            check.fail(item.line, `budgets.accounts.${account}.sources must be check or status_line`);
+            continue;
+        }
+        if (kind === 'spend' && item.value === 'status_line') {
+            check.fail(item.line, 'a spend account never reads a screen');
+            continue;
+        }
+        if (sources.includes(item.value))
+            check.fail(item.line, `budgets.accounts.${account}.sources lists ${item.value} twice`);
+        else
+            sources.push(item.value);
+    }
+    return sources;
+}
+function money(entry, account, check) {
+    if (!entry)
+        return null;
+    const raw = entry.value.kind === 'scalar' ? entry.value.raw : '';
+    const match = /^([0-9]+(?:\.[0-9]{1,4})?) ([A-Z]{3})$/.exec(raw);
+    if (!match || match[1] === undefined || match[2] === undefined) {
+        check.fail(entry.line, `budgets.accounts.${account}.floor is an amount and a currency, such as 5 USD`);
+        return null;
+    }
+    return { amount: Number(match[1]), currency: match[2] };
+}

package/dist/file/sections/coordinator.d.ts

@@ -0,0 +1,2 @@
+import type { Section } from './section.ts';
+export declare const coordinator: Section;

package/dist/file/sections/coordinator.js

@@ -0,0 +1,11 @@
+import { valueOf } from "./section.js";
+import { readLead } from "./lead.js";
+export const coordinator = {
+    name: 'coordinator',
+    owner: true,
+    after: ['seats'],
+    validate(entry, ctx) {
+        return readLead(entry, 'coordinator', valueOf(ctx, 'seats'), ctx.broken, ctx.check);
+    },
+    schema: { type: 'string', minLength: 1, $comment: 'must name a declared seat: one, without count, neither parked nor stopped' },
+};

package/dist/file/sections/format.d.ts

@@ -0,0 +1,2 @@
+import type { Section } from './section.ts';
+export declare const format: Section;

package/dist/file/sections/format.js

@@ -0,0 +1,13 @@
+export const format = {
+    name: 'format',
+    owner: false,
+    after: [],
+    validate(entry, ctx) {
+        if (!entry)
+            ctx.check.fail(1, 'format is required: "format: 1"');
+        else if (!(entry.value.kind === 'scalar' && entry.value.value === 1 && !entry.value.quoted)) {
+            ctx.check.fail(entry.line, 'format must be 1: this version of team reads no other');
+        }
+    },
+    schema: { const: 1, $comment: 'unquoted: this version of team reads no other' },
+};

package/dist/file/sections/identity.d.ts

@@ -0,0 +1,2 @@
+import type { Section } from './section.ts';
+export declare const identity: Section;

package/dist/file/sections/identity.js

@@ -0,0 +1,103 @@
+import { DEFAULT_COMMIT_TEMPLATE, DEFAULT_FORBIDDEN, DEFAULT_PR_TEMPLATE, isTrailerTemplate, templateProblem, } from "../signature.js";
+const POSITIONS = ['last-line', 'trailer', 'anywhere'];
+export const identity = {
+    name: 'identity',
+    owner: true,
+    after: [],
+    validate(entry, ctx) {
+        return readIdentity(entry, ctx.check);
+    },
+    schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+            signature: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    template: { type: 'string' },
+                    commits: {
+                        type: 'object',
+                        additionalProperties: false,
+                        properties: {
+                            template: { type: 'string' },
+                            position: { enum: POSITIONS },
+                            exempt: { type: 'array', items: { const: 'merge' } },
+                        },
+                    },
+                    pull_requests: {
+                        type: 'object',
+                        additionalProperties: false,
+                        properties: {
+                            template: { type: 'string' },
+                            position: { enum: POSITIONS },
+                        },
+                    },
+                },
+            },
+            humans: { type: 'array', items: { type: 'string', minLength: 1 } },
+            since: { type: 'string' },
+            forbidden: { type: 'array', items: { type: 'string' } },
+            forbidden_public: { type: 'array', items: { type: 'string' } },
+        },
+        $comment: 'forbidden and forbidden_public are regular expressions; a template in the position "trailer" must read as a git trailer',
+    },
+};
+function readIdentity(entry, check) {
+    const identity = check.fields(entry?.value, 'identity', ['signature', 'humans', 'since', 'forbidden', 'forbidden_public']);
+    const signature = check.fields(identity.get('signature')?.value, 'identity.signature', ['template', 'commits', 'pull_requests']);
+    const commits = check.fields(signature.get('commits')?.value, 'identity.signature.commits', ['template', 'position', 'exempt']);
+    const prs = check.fields(signature.get('pull_requests')?.value, 'identity.signature.pull_requests', ['template', 'position', 'exempt']);
+    const base = readTemplate(signature.get('template'), 'identity.signature.template', check) ?? DEFAULT_COMMIT_TEMPLATE;
+    const commitTemplate = readTemplate(commits.get('template'), 'identity.signature.commits.template', check) ?? base;
+    const prTemplate = readTemplate(prs.get('template'), 'identity.signature.pull_requests.template', check) ?? DEFAULT_PR_TEMPLATE;
+    const commitPosition = check.oneOf(commits.get('position'), 'identity.signature.commits.position', POSITIONS) ?? 'trailer';
+    const prPosition = check.oneOf(prs.get('position'), 'identity.signature.pull_requests.position', POSITIONS) ?? 'last-line';
+    if (commitPosition === 'trailer' && !isTrailerTemplate(commitTemplate)) {
+        const line = commits.get('position')?.line ?? commits.get('template')?.line ?? signature.get('template')?.line ?? entry?.line ?? 1;
+        check.fail(line, 'position "trailer" needs a template git reads as a trailer: "<token>: <value>", the token without spaces');
+    }
+    const exemptEntry = commits.get('exempt');
+    const exempt = exemptEntry ? check.list(exemptEntry, 'identity.signature.commits.exempt') : [{ value: 'merge', line: 0 }];
+    for (const item of exempt) {
+        if (item.value !== 'merge')
+            check.fail(item.line, `exempt takes only "merge" in this version, found "${item.value}"`);
+    }
+    const prExempt = prs.get('exempt');
+    if (prExempt)
+        check.fail(prExempt.line, 'pull_requests has no exempt: it applies to commits only');
+    const forbidden = readPatterns(identity.get('forbidden'), 'identity.forbidden', check);
+    const forbiddenPublic = readPatterns(identity.get('forbidden_public'), 'identity.forbidden_public', check);
+    return {
+        signature: {
+            commits: { template: commitTemplate, position: commitPosition, exempt: exempt.some((item) => item.value === 'merge') ? ['merge'] : [] },
+            pullRequests: { template: prTemplate, position: prPosition },
+        },
+        humans: check.list(identity.get('humans'), 'identity.humans').map((item) => item.value),
+        since: check.text(identity.get('since'), 'identity.since') ?? null,
+        forbidden: [...DEFAULT_FORBIDDEN, ...forbidden.filter((pattern) => !DEFAULT_FORBIDDEN.includes(pattern))],
+        forbiddenPublic,
+    };
+}
+function readTemplate(entry, name, check) {
+    const template = check.text(entry, name);
+    if (template === undefined || !entry)
+        return undefined;
+    const problem = templateProblem(template);
+    if (problem)
+        check.fail(entry.value.line, `${name}: ${problem}`);
+    return template;
+}
+function readPatterns(entry, name, check) {
+    const out = [];
+    for (const item of check.list(entry, name)) {
+        try {
+            new RegExp(item.value);
+            out.push(item.value);
+        }
+        catch (error) {
+            check.fail(item.line, `${name}: not a regular expression (${error.message})`);
+        }
+    }
+    return out;
+}

package/dist/file/sections/index.d.ts

@@ -0,0 +1,9 @@
+import type { Section } from './section.ts';
+/**
+ * Every section of the team file, in one order. The owner-only list is generated from this order
+ * (`SECTIONS.filter(s => s.owner).map(s => s.name)`), and that order feeds the approval digest,
+ * so it is part of the contract: the owner sections appear here exactly as the digest reads them.
+ * The validator walks the list running each section once every section it names in `after` has
+ * run, which is the order `validate.ts` read them in before the sections were modules.
+ */
+export declare const SECTIONS: readonly Section[];

package/dist/file/sections/index.js

@@ -0,0 +1,43 @@
+import { format } from "./format.js";
+import { project } from "./project.js";
+import { trust } from "./trust.js";
+import { limits } from "./limits.js";
+import { machine } from "./machine.js";
+import { rules } from "./rules.js";
+import { identity } from "./identity.js";
+import { workspace } from "./workspace.js";
+import { coordinator } from "./coordinator.js";
+import { operator } from "./operator.js";
+import { session } from "./session.js";
+import { visibility } from "./visibility.js";
+import { tools } from "./tools.js";
+import { budgets } from "./budgets.js";
+import { watch } from "./watch.js";
+import { watchChecks } from "./watch-checks.js";
+import { seats } from "./seats.js";
+/**
+ * Every section of the team file, in one order. The owner-only list is generated from this order
+ * (`SECTIONS.filter(s => s.owner).map(s => s.name)`), and that order feeds the approval digest,
+ * so it is part of the contract: the owner sections appear here exactly as the digest reads them.
+ * The validator walks the list running each section once every section it names in `after` has
+ * run, which is the order `validate.ts` read them in before the sections were modules.
+ */
+export const SECTIONS = [
+    format,
+    project,
+    trust,
+    limits,
+    machine,
+    rules,
+    identity,
+    workspace,
+    coordinator,
+    operator,
+    session,
+    visibility,
+    tools,
+    budgets,
+    watch,
+    watchChecks,
+    seats,
+];

package/dist/file/sections/lead.d.ts

@@ -0,0 +1,4 @@
+import type { YamlEntry } from '../../yaml.ts';
+import type { Check } from '../check.ts';
+import type { DraftSeat } from './seats.ts';
+export declare function readLead(entry: YamlEntry | undefined, field: 'coordinator' | 'operator', seats: DraftSeat[], broken: Set<string>, check: Check): string;

package/dist/file/sections/lead.js

@@ -0,0 +1,18 @@
+export function readLead(entry, field, seats, broken, check) {
+    const name = check.required(entry, field, 1);
+    if (!name || !entry)
+        return '';
+    const seat = seats.find((candidate) => candidate.name === name);
+    const line = entry.value.line;
+    if (!seat) {
+        if (!broken.has(name))
+            check.fail(line, `${field} "${name}" names no declared seat`);
+    }
+    else if (seat.count > 1)
+        check.fail(line, `${field} "${name}" can't be a seat with count`);
+    else if (seat.parked)
+        check.fail(line, `${field} "${name}" can't be a parked seat`);
+    else if (seat.stopped)
+        check.fail(line, `${field} "${name}" can't be a stopped seat`);
+    return name;
+}

package/dist/file/sections/limits.d.ts

@@ -0,0 +1,2 @@
+import type { Section } from './section.ts';
+export declare const limits: Section;

package/dist/file/sections/limits.js

@@ -0,0 +1,43 @@
+import { valueOf } from "./section.js";
+export const limits = {
+    name: 'limits',
+    owner: true,
+    after: ['seats'],
+    validate(entry, ctx) {
+        const declared = valueOf(ctx, 'seats').length;
+        return readLimits(entry, ctx.check, declared);
+    },
+    schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+            seats: { type: 'integer', minimum: 1 },
+            temporary: { type: 'integer', minimum: 0 },
+            vendors: { type: 'object', additionalProperties: { type: 'integer', minimum: 0 } },
+        },
+        $comment: 'seats defaults to the declared seats plus temporary',
+    },
+};
+function readLimits(entry, check, declared) {
+    const fields = check.fields(entry?.value, 'limits', ['seats', 'temporary', 'vendors']);
+    const temporary = check.whole(fields.get('temporary'), 'limits.temporary', 0) ?? 2;
+    const vendors = {};
+    const vendorsEntry = fields.get('vendors');
+    if (vendorsEntry) {
+        const node = vendorsEntry.value;
+        if (node.kind !== 'map')
+            check.fail(node.line, 'limits.vendors must be a map: a vendor, then its ceiling');
+        else {
+            for (const vendor of node.entries) {
+                const ceiling = check.whole(vendor, `limits.vendors.${vendor.key}`, 0);
+                if (ceiling !== undefined)
+                    vendors[vendor.key] = ceiling;
+            }
+        }
+    }
+    return {
+        seats: check.whole(fields.get('seats'), 'limits.seats', 1) ?? declared + temporary,
+        temporary,
+        vendors,
+    };
+}

package/dist/file/sections/machine.d.ts

@@ -0,0 +1,2 @@
+import type { Section } from './section.ts';
+export declare const machine: Section;

package/dist/file/sections/machine.js

@@ -0,0 +1,38 @@
+import { measureSchema, DURATION, PERCENT, SIZE } from "./units.js";
+export const machine = {
+    name: 'machine',
+    owner: true,
+    after: [],
+    validate(entry, ctx) {
+        return readMachine(entry, ctx.check);
+    },
+    schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+            load_start: { type: 'number', exclusiveMinimum: 0 },
+            load_max: { type: 'number', exclusiveMinimum: 0 },
+            memory_start: measureSchema(PERCENT),
+            memory_min: measureSchema(PERCENT),
+            disk_min: measureSchema(SIZE),
+            swap_free_min: measureSchema(SIZE),
+            swap_growth_max: measureSchema(SIZE),
+            swap_growth_window: measureSchema(DURATION),
+        },
+    },
+};
+function readMachine(entry, check) {
+    const fields = check.fields(entry?.value, 'machine', [
+        'load_start', 'load_max', 'memory_start', 'memory_min', 'disk_min', 'swap_free_min', 'swap_growth_max', 'swap_growth_window',
+    ]);
+    return {
+        loadStart: check.number(fields.get('load_start'), 'machine.load_start') ?? 3,
+        loadMax: check.number(fields.get('load_max'), 'machine.load_max') ?? 6,
+        memoryStart: check.measure(fields.get('memory_start'), 'machine.memory_start', PERCENT, '25%') ?? 25,
+        memoryMin: check.measure(fields.get('memory_min'), 'machine.memory_min', PERCENT, '15%') ?? 15,
+        diskMin: check.measure(fields.get('disk_min'), 'machine.disk_min', SIZE, '10GB') ?? 10e9,
+        swapFreeMin: check.measure(fields.get('swap_free_min'), 'machine.swap_free_min', SIZE, '2GB') ?? 2e9,
+        swapGrowthMax: check.measure(fields.get('swap_growth_max'), 'machine.swap_growth_max', SIZE, '1GB') ?? 1e9,
+        swapGrowthWindow: check.measure(fields.get('swap_growth_window'), 'machine.swap_growth_window', DURATION, '10m') ?? 600,
+    };
+}

package/dist/file/sections/operator.d.ts

@@ -0,0 +1,2 @@
+import type { Section } from './section.ts';
+export declare const operator: Section;

package/dist/file/sections/operator.js

@@ -0,0 +1,11 @@
+import { valueOf } from "./section.js";
+import { readLead } from "./lead.js";
+export const operator = {
+    name: 'operator',
+    owner: true,
+    after: ['seats'],
+    validate(entry, ctx) {
+        return readLead(entry, 'operator', valueOf(ctx, 'seats'), ctx.broken, ctx.check);
+    },
+    schema: { type: 'string', minLength: 1, $comment: 'must name a declared seat: one, without count, neither parked nor stopped' },
+};

package/dist/file/sections/project.d.ts

@@ -0,0 +1,2 @@
+import type { Section } from './section.ts';
+export declare const project: Section;

package/dist/file/sections/project.js

@@ -0,0 +1,13 @@
+export const project = {
+    name: 'project',
+    owner: false,
+    after: [],
+    validate(entry, ctx) {
+        const project = ctx.check.required(entry, 'project', 1) ?? '';
+        if (project && !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(project)) {
+            ctx.check.fail(entry?.line ?? 1, 'project must be a short name: letters, digits, ".", "_" and "-"');
+        }
+        return project;
+    },
+    schema: { type: 'string', minLength: 1, pattern: '^[A-Za-z0-9][A-Za-z0-9._-]*$' },
+};

package/dist/file/sections/rules.d.ts

@@ -0,0 +1,2 @@
+import type { Section } from './section.ts';
+export declare const rules: Section;

package/dist/file/sections/rules.js

@@ -0,0 +1,9 @@
+export const rules = {
+    name: 'rules',
+    owner: true,
+    after: [],
+    validate(entry, ctx) {
+        return ctx.check.list(entry, 'rules').map((item) => item.value);
+    },
+    schema: { type: 'array', items: { type: 'string', minLength: 1 } },
+};

package/dist/file/sections/seats.d.ts

@@ -0,0 +1,7 @@
+import type { Mode, Seat } from '../types.ts';
+import type { Section } from './section.ts';
+export type DraftSeat = Omit<Seat, 'mode'> & {
+    mode?: Mode;
+};
+export declare const seats: Section;
+export declare function defaultLabel(model: string, version: string): string;