@pugi/cli 0.1.0-beta.10 → 0.1.0-beta.101

package/dist/core/recipes/schema.js

@@ -0,0 +1,587 @@
+/**
+ * Zod schemas + minimal YAML parser for recipes (backlog #62).
+ *
+ * The recipe surface is deliberately tiny — top-level scalars, a flow
+ * map of params, a block sequence of steps. Pulling in `js-yaml` for
+ * this would be ~70 KB of installed weight; the hand-rolled parser
+ * below covers every supported shape in ~150 lines and refuses
+ * anything richer so the operator's recipe stays inside the schema.
+ *
+ * Format spec:
+ *
+ *  schema: 1
+ *  name: deploy-staging
+ *  description: Build, smoke-test, deploy to staging
+ *  params:
+ *    branch: { type: string, default: main, required: false }
+ *    skipTests: { type: boolean, default: false }
+ *  steps:
+ *    - name: build
+ *      run: pnpm build
+ *    - name: test
+ *      run: pnpm test
+ *      when: "!params.skipTests"
+ *    - name: deploy
+ *      run: ./scripts/deploy.sh ${params.branch} staging
+ */
+import { z } from 'zod';
+const RECIPE_ID_RE = /^[a-z][a-z0-9-]*$/;
+/**
+ * Zod schema for the parsed-but-not-yet-augmented recipe. Files are
+ * parsed by `parseRecipeYaml` first, then validated by this schema, then
+ * augmented with `id`, `source`, `origin` by the loader.
+ *
+ * The `passthrough` policy is `strict` — unknown keys raise a clear
+ * error so a typo cannot silently no-op the way YAML's permissive
+ * shape usually allows.
+ */
+export const recipeFileSchema = z
+    .object({
+    schema: z.literal(1),
+    name: z.string().min(1).optional(),
+    description: z.string().min(1).optional(),
+    params: z
+        .record(z.string(), z
+        .object({
+        type: z.enum(['string', 'boolean', 'number']),
+        default: z.union([z.string(), z.number(), z.boolean()]).optional(),
+        required: z.boolean().optional(),
+        description: z.string().optional(),
+    })
+        .strict())
+        .optional(),
+    steps: z
+        .array(z
+        .object({
+        name: z.string().min(1),
+        run: z.string().min(1),
+        when: z.string().min(1).optional(),
+        continueOnError: z.boolean().optional(),
+    })
+        .strict())
+        .min(1),
+})
+    .strict();
+/**
+ * Validate a recipe id derived from its filename. Recipe ids are
+ * the canonical key — the loader uses them for dedup and CLI args
+ * use them verbatim, so they need to be predictable.
+ */
+export function isValidRecipeId(id) {
+    return RECIPE_ID_RE.test(id);
+}
+/**
+ * Parse + validate a recipe file body. Returns the structured Recipe
+ * on success or a single-line operator-readable error on failure.
+ */
+export function parseRecipeFile(body, ctx) {
+    if (!isValidRecipeId(ctx.id)) {
+        return {
+            ok: false,
+            error: `recipe id '${ctx.id}' must match [a-z][a-z0-9-]* (lowercase, kebab-case, leading letter)`,
+        };
+    }
+    let raw;
+    try {
+        raw = parseRecipeYaml(body);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { ok: false, error: `parse error: ${message}` };
+    }
+    const validated = recipeFileSchema.safeParse(raw);
+    if (!validated.success) {
+        const firstIssue = validated.error.issues[0];
+        const path = firstIssue?.path.join('.') || '<root>';
+        const message = firstIssue?.message ?? 'unknown schema error';
+        return { ok: false, error: `schema error at ${path}: ${message}` };
+    }
+    const recipe = augment(validated.data, ctx);
+    // Validate when-expressions at load time so a typo fails fast.
+    for (const step of recipe.steps) {
+        if (step.when !== undefined) {
+            const check = compileWhenExpression(step.when, recipe.params);
+            if (!check.ok) {
+                return {
+                    ok: false,
+                    error: `step '${step.name}': when-clause invalid: ${check.error}`,
+                };
+            }
+        }
+    }
+    return { ok: true, recipe };
+}
+function augment(data, ctx) {
+    const params = [];
+    const paramRecord = data.params ?? {};
+    for (const [name, spec] of Object.entries(paramRecord)) {
+        const param = {
+            name,
+            type: spec.type,
+            required: spec.required ?? false,
+            ...(spec.default !== undefined ? { default: spec.default } : {}),
+            ...(spec.description !== undefined ? { description: spec.description } : {}),
+        };
+        params.push(param);
+    }
+    const steps = data.steps.map((s) => ({
+        name: s.name,
+        run: s.run,
+        continueOnError: s.continueOnError ?? false,
+        ...(s.when !== undefined ? { when: s.when } : {}),
+    }));
+    return {
+        schema: 1,
+        id: ctx.id,
+        name: data.name ?? ctx.id,
+        ...(data.description !== undefined ? { description: data.description } : {}),
+        source: ctx.source,
+        origin: ctx.origin,
+        params,
+        steps,
+    };
+}
+/**
+ * Minimal YAML parser tuned for the recipe schema. Public for direct
+ * test coverage. Supports:
+ *
+ *  - Top-level scalars: `key: value`.
+ *  - Flow mapping: `key: { a: b, c: d }`.
+ *  - Block sequence under `steps:` with `- key: value` continuations.
+ *  - Block mapping under `params:` with nested flow mapping per param.
+ *  - Quoted strings: single and double quotes.
+ *  - Numbers and booleans: `42`, `true`, `false`.
+ *  - Comments after `#` (only when preceded by whitespace, so `pnpm test #x` works).
+ *
+ * Anything else raises with a clear `line N` pointer.
+ */
+export function parseRecipeYaml(body) {
+    const lines = body.split('\n').map((line) => line.replace(/\r$/, ''));
+    const stripped = lines.map(stripComment);
+    const root = {};
+    let i = 0;
+    while (i < stripped.length) {
+        const line = stripped[i] ?? '';
+        if (line.trim() === '') {
+            i += 1;
+            continue;
+        }
+        if (/^\s/.test(line)) {
+            throw new Error(`unexpected indentation at line ${i + 1}: '${line}'`);
+        }
+        const match = /^([a-zA-Z_][a-zA-Z0-9_-]*)\s*:\s*(.*)$/.exec(line);
+        if (!match) {
+            throw new Error(`cannot parse top-level line ${i + 1}: '${line}'`);
+        }
+        const key = match[1];
+        const tail = (match[2] ?? '').trim();
+        if (tail === '') {
+            const block = collectIndentedBlock(stripped, i + 1);
+            i = block.nextIndex;
+            if (key === 'params') {
+                root[key] = parseParamsBlock(block.lines, block.startLine);
+            }
+            else if (key === 'steps') {
+                root[key] = parseStepsBlock(block.lines, block.startLine);
+            }
+            else {
+                throw new Error(`block value at line ${i + 1} is only supported for 'params' / 'steps' (got '${key}')`);
+            }
+            continue;
+        }
+        root[key] = parseScalar(tail, i + 1);
+        i += 1;
+    }
+    return root;
+}
+function stripComment(line) {
+    let inSingle = false;
+    let inDouble = false;
+    for (let i = 0; i < line.length; i += 1) {
+        const ch = line[i];
+        if (ch === "'" && !inDouble)
+            inSingle = !inSingle;
+        else if (ch === '"' && !inSingle)
+            inDouble = !inDouble;
+        else if (ch === '#' && !inSingle && !inDouble) {
+            const prev = line[i - 1];
+            if (prev === undefined || /\s/.test(prev)) {
+                return line.slice(0, i).replace(/\s+$/, '');
+            }
+        }
+    }
+    return line;
+}
+function collectIndentedBlock(lines, start) {
+    const block = [];
+    let i = start;
+    while (i < lines.length) {
+        const line = lines[i] ?? '';
+        if (line.trim() === '') {
+            block.push(line);
+            i += 1;
+            continue;
+        }
+        if (!/^\s/.test(line))
+            break;
+        block.push(line);
+        i += 1;
+    }
+    return { lines: block, startLine: start, nextIndex: i };
+}
+function parseParamsBlock(block, startLine) {
+    const out = {};
+    for (let i = 0; i < block.length; i += 1) {
+        const line = block[i] ?? '';
+        const trimmed = line.trim();
+        if (trimmed === '')
+            continue;
+        const match = /^\s+([a-zA-Z_][a-zA-Z0-9_-]*)\s*:\s*(.*)$/.exec(line);
+        if (!match) {
+            throw new Error(`params: cannot parse line ${startLine + i + 1}: '${line}'`);
+        }
+        const key = match[1];
+        const tail = (match[2] ?? '').trim();
+        if (tail === '' || !tail.startsWith('{')) {
+            throw new Error(`params: each entry must be a flow mapping at line ${startLine + i + 1}: '${line}'`);
+        }
+        out[key] = parseFlowMapping(tail, startLine + i + 1);
+    }
+    return out;
+}
+function parseStepsBlock(block, startLine) {
+    const steps = [];
+    let current = null;
+    for (let i = 0; i < block.length; i += 1) {
+        const line = block[i] ?? '';
+        if (line.trim() === '')
+            continue;
+        const dashMatch = /^(\s+)-\s+(.*)$/.exec(line);
+        if (dashMatch) {
+            if (current !== null)
+                steps.push(current);
+            current = {};
+            const tail = (dashMatch[2] ?? '').trim();
+            const fieldMatch = /^([a-zA-Z_][a-zA-Z0-9_-]*)\s*:\s*(.*)$/.exec(tail);
+            if (!fieldMatch) {
+                throw new Error(`steps: dash entry must start with a field at line ${startLine + i + 1}: '${line}'`);
+            }
+            current[fieldMatch[1]] = parseScalar((fieldMatch[2] ?? '').trim(), startLine + i + 1);
+            continue;
+        }
+        const fieldMatch = /^\s+([a-zA-Z_][a-zA-Z0-9_-]*)\s*:\s*(.*)$/.exec(line);
+        if (fieldMatch && current !== null) {
+            current[fieldMatch[1]] = parseScalar((fieldMatch[2] ?? '').trim(), startLine + i + 1);
+            continue;
+        }
+        throw new Error(`steps: cannot parse line ${startLine + i + 1}: '${line}'`);
+    }
+    if (current !== null)
+        steps.push(current);
+    return steps;
+}
+function parseFlowMapping(text, line) {
+    if (!text.startsWith('{') || !text.endsWith('}')) {
+        throw new Error(`flow mapping must start with '{' and end with '}' at line ${line}: '${text}'`);
+    }
+    const inner = text.slice(1, -1).trim();
+    const out = {};
+    if (inner === '')
+        return out;
+    const parts = splitFlow(inner);
+    for (const part of parts) {
+        const colon = part.indexOf(':');
+        if (colon < 0) {
+            throw new Error(`flow mapping entry needs 'key: value' at line ${line}: '${part}'`);
+        }
+        const key = part.slice(0, colon).trim();
+        const value = part.slice(colon + 1).trim();
+        if (!/^[a-zA-Z_][a-zA-Z0-9_-]*$/.test(key)) {
+            throw new Error(`flow mapping key must match [a-zA-Z_][a-zA-Z0-9_-]* at line ${line}: '${key}'`);
+        }
+        out[key] = parseScalar(value, line);
+    }
+    return out;
+}
+function splitFlow(text) {
+    const out = [];
+    let depth = 0;
+    let inSingle = false;
+    let inDouble = false;
+    let buf = '';
+    for (let i = 0; i < text.length; i += 1) {
+        const ch = text[i];
+        if (ch === "'" && !inDouble) {
+            inSingle = !inSingle;
+            buf += ch;
+            continue;
+        }
+        if (ch === '"' && !inSingle) {
+            inDouble = !inDouble;
+            buf += ch;
+            continue;
+        }
+        if (!inSingle && !inDouble) {
+            if (ch === '{' || ch === '[')
+                depth += 1;
+            else if (ch === '}' || ch === ']')
+                depth -= 1;
+            if (ch === ',' && depth === 0) {
+                out.push(buf);
+                buf = '';
+                continue;
+            }
+        }
+        buf += ch;
+    }
+    if (buf.trim() !== '')
+        out.push(buf);
+    return out;
+}
+function parseScalar(raw, line) {
+    if (raw === '')
+        return '';
+    const first = raw[0];
+    if (first === '"' || first === "'") {
+        const last = raw[raw.length - 1];
+        if (last !== first) {
+            throw new Error(`unterminated quoted string at line ${line}: ${raw}`);
+        }
+        return raw.slice(1, -1);
+    }
+    if (raw === 'true')
+        return true;
+    if (raw === 'false')
+        return false;
+    if (/^-?\d+$/.test(raw))
+        return Number.parseInt(raw, 10);
+    if (/^-?\d+\.\d+$/.test(raw))
+        return Number.parseFloat(raw);
+    return raw;
+}
+export function compileWhenExpression(source, declaredParams) {
+    const declared = new Set(declaredParams.map((p) => p.name));
+    const tokens = tokenizeWhen(source);
+    if (!tokens.ok)
+        return { ok: false, error: tokens.error };
+    const parser = new WhenParser(tokens.tokens, declared);
+    let ast;
+    try {
+        ast = parser.parseExpression();
+        parser.expectEnd();
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { ok: false, error: message };
+    }
+    return {
+        ok: true,
+        evaluate: (params) => evaluateWhen(ast, params),
+    };
+}
+function tokenizeWhen(source) {
+    const tokens = [];
+    let i = 0;
+    while (i < source.length) {
+        const ch = source[i] ?? '';
+        if (/\s/.test(ch)) {
+            i += 1;
+            continue;
+        }
+        if (ch === '(') {
+            tokens.push({ kind: 'LPAREN' });
+            i += 1;
+            continue;
+        }
+        if (ch === ')') {
+            tokens.push({ kind: 'RPAREN' });
+            i += 1;
+            continue;
+        }
+        if (ch === '!' && source[i + 1] === '=' && source[i + 2] === '=') {
+            tokens.push({ kind: 'NEQ' });
+            i += 3;
+            continue;
+        }
+        if (ch === '=' && source[i + 1] === '=' && source[i + 2] === '=') {
+            tokens.push({ kind: 'EQ' });
+            i += 3;
+            continue;
+        }
+        if (ch === '!') {
+            tokens.push({ kind: 'BANG' });
+            i += 1;
+            continue;
+        }
+        if (ch === '&' && source[i + 1] === '&') {
+            tokens.push({ kind: 'AND' });
+            i += 2;
+            continue;
+        }
+        if (ch === '|' && source[i + 1] === '|') {
+            tokens.push({ kind: 'OR' });
+            i += 2;
+            continue;
+        }
+        if (ch === "'" || ch === '"') {
+            const close = source.indexOf(ch, i + 1);
+            if (close < 0) {
+                return { ok: false, error: `unterminated string starting at offset ${i}` };
+            }
+            tokens.push({ kind: 'STRING', value: source.slice(i + 1, close) });
+            i = close + 1;
+            continue;
+        }
+        if (/[0-9-]/.test(ch)) {
+            const start = i;
+            if (ch === '-')
+                i += 1;
+            while (i < source.length && /[0-9.]/.test(source[i] ?? ''))
+                i += 1;
+            const num = Number.parseFloat(source.slice(start, i));
+            if (!Number.isFinite(num)) {
+                return { ok: false, error: `bad number at offset ${start}` };
+            }
+            tokens.push({ kind: 'NUMBER', value: num });
+            continue;
+        }
+        if (/[a-zA-Z_]/.test(ch)) {
+            const start = i;
+            while (i < source.length && /[a-zA-Z0-9_.]/.test(source[i] ?? ''))
+                i += 1;
+            const word = source.slice(start, i);
+            if (word === 'true' || word === 'false') {
+                tokens.push({ kind: 'BOOL', value: word === 'true' });
+                continue;
+            }
+            const refMatch = /^params\.([a-zA-Z_][a-zA-Z0-9_]*)$/.exec(word);
+            if (!refMatch) {
+                return {
+                    ok: false,
+                    error: `unknown identifier '${word}' (only params.<name> is allowed)`,
+                };
+            }
+            tokens.push({ kind: 'REF', name: refMatch[1] });
+            continue;
+        }
+        return { ok: false, error: `unexpected character '${ch}' at offset ${i}` };
+    }
+    return { ok: true, tokens };
+}
+class WhenParser {
+    tokens;
+    declared;
+    pos = 0;
+    constructor(tokens, declared) {
+        this.tokens = tokens;
+        this.declared = declared;
+    }
+    parseExpression() {
+        return this.parseOr();
+    }
+    expectEnd() {
+        if (this.pos !== this.tokens.length) {
+            throw new Error(`unexpected token at position ${this.pos}`);
+        }
+    }
+    parseOr() {
+        let left = this.parseAnd();
+        while (this.peek()?.kind === 'OR') {
+            this.pos += 1;
+            const right = this.parseAnd();
+            left = { kind: 'OR', left, right };
+        }
+        return left;
+    }
+    parseAnd() {
+        let left = this.parseUnary();
+        while (this.peek()?.kind === 'AND') {
+            this.pos += 1;
+            const right = this.parseUnary();
+            left = { kind: 'AND', left, right };
+        }
+        return left;
+    }
+    parseUnary() {
+        if (this.peek()?.kind === 'BANG') {
+            this.pos += 1;
+            const child = this.parseUnary();
+            return { kind: 'NOT', child };
+        }
+        return this.parseAtom();
+    }
+    parseAtom() {
+        const tok = this.peek();
+        if (!tok)
+            throw new Error('unexpected end of expression');
+        if (tok.kind === 'LPAREN') {
+            this.pos += 1;
+            const inner = this.parseOr();
+            const close = this.peek();
+            if (close?.kind !== 'RPAREN')
+                throw new Error('missing closing paren');
+            this.pos += 1;
+            return inner;
+        }
+        if (tok.kind === 'REF') {
+            this.pos += 1;
+            this.assertDeclared(tok.name);
+            const next = this.peek();
+            if (next?.kind === 'EQ' || next?.kind === 'NEQ') {
+                const opKind = next.kind;
+                this.pos += 1;
+                const lit = this.peek();
+                if (!lit ||
+                    (lit.kind !== 'STRING' && lit.kind !== 'BOOL' && lit.kind !== 'NUMBER')) {
+                    throw new Error(`expected literal after ${opKind} for params.${tok.name}`);
+                }
+                this.pos += 1;
+                const literal = lit.kind === 'STRING'
+                    ? lit.value
+                    : lit.kind === 'BOOL'
+                        ? lit.value
+                        : lit.value;
+                return { kind: opKind, ref: tok.name, literal };
+            }
+            return { kind: 'REF', ref: tok.name };
+        }
+        throw new Error(`unexpected token '${tok.kind}'`);
+    }
+    peek() {
+        return this.tokens[this.pos];
+    }
+    assertDeclared(name) {
+        if (!this.declared.has(name)) {
+            throw new Error(`undeclared param 'params.${name}' (declare it in params:)`);
+        }
+    }
+}
+function evaluateWhen(node, params) {
+    switch (node.kind) {
+        case 'OR':
+            return evaluateWhen(node.left, params) || evaluateWhen(node.right, params);
+        case 'AND':
+            return evaluateWhen(node.left, params) && evaluateWhen(node.right, params);
+        case 'NOT':
+            return !evaluateWhen(node.child, params);
+        case 'EQ': {
+            const value = params[node.ref];
+            return value === node.literal;
+        }
+        case 'NEQ': {
+            const value = params[node.ref];
+            return value !== node.literal;
+        }
+        case 'REF': {
+            const value = params[node.ref];
+            if (typeof value === 'boolean')
+                return value;
+            if (typeof value === 'number')
+                return value !== 0;
+            if (typeof value === 'string')
+                return value !== '';
+            return false;
+        }
+    }
+}
+//# sourceMappingURL=schema.js.map