@secureci/cli 0.0.0-stage → 0.1.0

package/dist/parser/pipeline-contract-validator.js

@@ -0,0 +1,448 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validatePipelineContract = validatePipelineContract;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const job_plan_1 = require("../runner/job-plan");
+const workflow_parser_1 = require("./workflow-parser");
+const repository_1 = require("../utils/repository");
+const action_fetcher_1 = require("../runner/action-fetcher");
+/** Maximum nesting of composite actions / reusable workflows. */
+const MAX_DEPTH = 10;
+/**
+ * Validate a workflow's job/step sequence against a central pipeline
+ * contract: a minimum set of required actions (optionally ordered) and a
+ * deny-list of forbidden actions.
+ *
+ * Composite actions (`uses: ./path`) and reusable workflows
+ * (`jobs.<id>.uses: ./path.yml`) are resolved recursively, so wrapping an
+ * action doesn't hide it: local ones by default, remote ones too with
+ * `recurse: 'all'`. Ordering follows
+ * what GitHub guarantees: steps of a job run in order, and a job runs after
+ * the jobs it (transitively) `needs:`; jobs with no such relationship may
+ * run in parallel, so neither is "before" the other.
+ */
+async function validatePipelineContract(parsed, spec, options = {}) {
+    const graph = await buildGraph(parsed, options.recurse ?? 'local');
+    const { sequence, nodes } = graph;
+    const errors = [...graph.errors];
+    const ordering = spec.ordering ?? 'relative';
+    for (const entry of spec.forbidden ?? []) {
+        for (const usage of sequence) {
+            if (usage.name === normalizeActionName(entry.uses) &&
+                (entry.version === undefined || usage.version === entry.version)) {
+                errors.push({
+                    path: usage.path,
+                    message: entry.version
+                        ? `Forbidden action "${entry.uses}@${entry.version}" is used`
+                        : `Forbidden action "${entry.uses}" is used (any version)`,
+                    severity: 'error'
+                });
+            }
+        }
+    }
+    const matchedPositions = [];
+    (spec.required ?? []).forEach((entry, idx) => {
+        const path = `required[${idx}]`;
+        const name = normalizeActionName(entry.uses);
+        const candidates = sequence.filter((u) => u.name === name);
+        if (candidates.length > 0 && candidates.every((c) => c.conditional)) {
+            errors.push({
+                path,
+                message: `Required action "${entry.uses}" only runs under an if: condition (on its step or job), so it may be skipped`,
+                severity: 'warning'
+            });
+        }
+        if (candidates.length === 0) {
+            errors.push({
+                path,
+                message: `Required action "${entry.uses}" was not found in the pipeline`,
+                severity: 'error'
+            });
+            return;
+        }
+        if (!entry['min-version']) {
+            matchedPositions.push({ entry, usage: candidates[0], index: idx });
+            return;
+        }
+        const satisfying = candidates.find((c) => c.version && isVersionAtLeast(c.version, entry['min-version']));
+        if (satisfying) {
+            matchedPositions.push({ entry, usage: satisfying, index: idx });
+            return;
+        }
+        // Present but too old (or not comparable): still check its ordering,
+        // using its first occurrence.
+        matchedPositions.push({ entry, usage: candidates[0], index: idx });
+        const comparable = candidates.find((c) => c.version &&
+            isVersionAtLeast(c.version, entry['min-version']) === false);
+        if (comparable) {
+            errors.push({
+                path,
+                message: `Required action "${entry.uses}" is used at version "${comparable.version}", which is below the required minimum "${entry['min-version']}"`,
+                severity: 'error'
+            });
+        }
+        else {
+            errors.push({
+                path,
+                message: `Required action "${entry.uses}" was found, but its version could not be compared against the required minimum "${entry['min-version']}"`,
+                severity: 'warning'
+            });
+        }
+    });
+    /** Whether `a` is guaranteed to have finished before `b` starts. */
+    const runsBefore = (a, b) => a.node === b.node
+        ? a.index < b.index
+        : needsTransitively(nodes, b.node, a.node);
+    for (let i = 1; i < matchedPositions.length; i++) {
+        const prev = matchedPositions[i - 1];
+        const curr = matchedPositions[i];
+        const path = `required[${curr.index}]`;
+        if (ordering === 'strict') {
+            const a = prev.usage;
+            const b = curr.usage;
+            const adjacent = a.node === b.node
+                ? b.index === a.index + 1
+                : a.index === (nodes.get(a.node)?.length ?? 0) - 1 &&
+                    b.index === 0 &&
+                    (nodes.get(b.node)?.needs.has(a.node) ?? false);
+            if (!adjacent) {
+                errors.push({
+                    path,
+                    message: `Required action "${curr.entry.uses}" must run immediately after "${prev.entry.uses}" (ordering: strict), but other steps appear in between`,
+                    severity: 'error'
+                });
+            }
+        }
+        else if (!runsBefore(prev.usage, curr.usage)) {
+            const parallel = !runsBefore(curr.usage, prev.usage);
+            errors.push({
+                path,
+                message: `Required action "${curr.entry.uses}" must run after "${prev.entry.uses}", but it does not` +
+                    (parallel
+                        ? ` (jobs "${nodes.get(prev.usage.node)?.label}" and "${nodes.get(curr.usage.node)?.label}" have no needs: relationship, so they may run in parallel)`
+                        : ''),
+                severity: 'error'
+            });
+        }
+    }
+    // Supply-chain rules over the same flattened sequence (recursion
+    // included), so a wrapper can't hide an unpinned or disallowed action.
+    const FULL_SHA = /^[0-9a-f]{40}$/i;
+    const isRemote = (u) => !u.name.startsWith('.') && !u.name.startsWith('docker://');
+    if (spec.pins?.required) {
+        const allow = new Set((spec.pins.allow ?? []).map((a) => normalizeActionName(a)));
+        for (const usage of sequence) {
+            if (!isRemote(usage))
+                continue;
+            const owner = usage.name.split('/')[0];
+            if (allow.has(usage.name) || allow.has(owner))
+                continue;
+            if (!usage.version || !FULL_SHA.test(usage.version)) {
+                errors.push({
+                    path: usage.path,
+                    message: `Action "${usage.name}${usage.version ? '@' + usage.version : ''}" must be pinned to a full commit SHA`,
+                    severity: 'error'
+                });
+            }
+        }
+    }
+    if (spec.allowedOwners && spec.allowedOwners.length > 0) {
+        const allowed = new Set(spec.allowedOwners.map((o) => o.split('/')[0].toLowerCase()));
+        for (const usage of sequence) {
+            if (!isRemote(usage))
+                continue;
+            const owner = usage.name.split('/')[0];
+            if (!allowed.has(owner)) {
+                errors.push({
+                    path: usage.path,
+                    message: `Action owner "${owner}" is not allowed (allowed owners: ${[...allowed].join(', ')})`,
+                    severity: 'error'
+                });
+            }
+        }
+    }
+    return {
+        valid: errors.every((e) => e.severity !== 'error'),
+        errors
+    };
+}
+/** Whether job `from` (transitively) needs job `to`. */
+function needsTransitively(nodes, from, to) {
+    const seen = new Set();
+    const queue = [...(nodes.get(from)?.needs ?? [])];
+    while (queue.length > 0) {
+        const id = queue.shift();
+        if (id === to)
+            return true;
+        if (seen.has(id))
+            continue;
+        seen.add(id);
+        queue.push(...(nodes.get(id)?.needs ?? []));
+    }
+    return false;
+}
+async function buildGraph(parsed, recurse) {
+    const graph = { sequence: [], nodes: new Map(), errors: [] };
+    const root = (0, repository_1.repositoryRoot)(parsed.path);
+    const isLocal = (uses) => uses.startsWith('./') || uses.startsWith('../');
+    /**
+     * The file behind a composite action / reusable workflow reference, or
+     * null (with a warning) if it can't be found. Local actions resolve
+     * against the workspace, local workflows against their own repository.
+     * Returns undefined for references that aren't followed.
+     */
+    const resolveRef = async (uses, kind, workflowRoot, at) => {
+        if (isLocal(uses)) {
+            if (recurse === 'none')
+                return undefined;
+            const target = path.resolve(kind === 'action' ? root : workflowRoot, uses);
+            const names = kind === 'action' ? ['action.yml', 'action.yaml'] : [];
+            for (const candidate of [
+                target,
+                ...names.map((n) => path.join(target, n))
+            ]) {
+                if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) {
+                    return candidate;
+                }
+            }
+            graph.errors.push({
+                path: at,
+                message: kind === 'action'
+                    ? `Local action "${uses}" could not be resolved, so its steps were not checked`
+                    : `Local reusable workflow "${uses}" could not be resolved, so its jobs were not checked`,
+                severity: 'warning'
+            });
+            return null;
+        }
+        if (recurse !== 'all' || uses.startsWith('docker://'))
+            return undefined;
+        const file = kind === 'action' ? await (0, action_fetcher_1.fetchAction)(uses) : await (0, action_fetcher_1.fetchRepoFile)(uses);
+        if (!file) {
+            graph.errors.push({
+                path: at,
+                message: `Remote ${kind} "${uses}" could not be fetched, so its ${kind === 'action' ? 'steps' : 'jobs'} were not checked`,
+                severity: 'warning'
+            });
+        }
+        return file;
+    };
+    /** Parse an action/workflow file, recording an error if it's invalid. */
+    const parse = (file, at) => {
+        try {
+            return (0, workflow_parser_1.parseFile)(file);
+        }
+        catch (error) {
+            graph.errors.push({
+                path: at,
+                message: `Could not parse ${path.relative(root, file)}: ${error instanceof Error ? error.message : String(error)}`,
+                severity: 'error'
+            });
+            return null;
+        }
+    };
+    /** Check recursion limits; returns false (with an error) to stop. */
+    const canEnter = (file, stack, at) => {
+        if (stack.includes(file)) {
+            graph.errors.push({
+                path: at,
+                message: `Action/workflow cycle: ${[...stack, file]
+                    .map((f) => path.relative(root, f))
+                    .join(' -> ')}`,
+                severity: 'error'
+            });
+            return false;
+        }
+        if (stack.length >= MAX_DEPTH) {
+            graph.errors.push({
+                path: at,
+                message: `Actions/workflows exceed the maximum nesting depth (${MAX_DEPTH})`,
+                severity: 'error'
+            });
+            return false;
+        }
+        return true;
+    };
+    const addUsage = (node, index, at, uses, conditional) => {
+        graph.sequence.push({
+            node,
+            index,
+            path: at,
+            conditional,
+            ...splitActionRef(uses)
+        });
+    };
+    /** Flatten a job's steps (and composite action steps) into `node`. */
+    const addSteps = async (steps, node, at, counter, stack, workflowRoot, conditional) => {
+        for (const [i, step] of steps.entries()) {
+            const stepPath = `${at}steps[${i}]`;
+            if (!step.uses) {
+                counter.next++;
+                continue;
+            }
+            const stepConditional = conditional || hasCondition(step.if);
+            addUsage(node, counter.next++, stepPath, step.uses, stepConditional);
+            const file = await resolveRef(step.uses, 'action', workflowRoot, stepPath);
+            if (!file || !canEnter(file, stack, stepPath))
+                continue;
+            const action = parse(file, stepPath);
+            if (action?.type === 'action' && action.file.runs.using === 'composite') {
+                await addSteps(action.file.runs.steps ?? [], node, `${stepPath} > ${step.uses} > `, counter, [...stack, file], workflowRoot, stepConditional);
+            }
+        }
+    };
+    /**
+     * Add a workflow's jobs. Every job also runs after `after` (the jobs the
+     * reusable-workflow call itself needs, plus the call). Returns the ids
+     * of the added jobs.
+     */
+    const addWorkflow = async (workflow, workflowRoot, prefix, labelPrefix, at, after, stack, conditional) => {
+        const added = [];
+        // A job id -> the graph nodes standing for it (a reusable-workflow call
+        // stands for the call and all of its called jobs).
+        const alias = new Map();
+        for (const jobId of (0, job_plan_1.topologicalJobOrder)(workflow.jobs)) {
+            const job = workflow.jobs[jobId];
+            const node = `${prefix}${jobId}`;
+            const needs = new Set(after);
+            for (const dep of [job.needs ?? []].flat()) {
+                for (const id of alias.get(dep) ?? [])
+                    needs.add(id);
+            }
+            graph.nodes.set(node, {
+                label: `${labelPrefix}${jobId}`,
+                needs,
+                length: 0
+            });
+            added.push(node);
+            const jobPath = `${at}jobs.${jobId}`;
+            const jobConditional = conditional || hasCondition(job.if);
+            if (job.uses) {
+                // The call itself is a one-step "job" its called jobs run after.
+                addUsage(node, 0, jobPath, job.uses, jobConditional);
+                graph.nodes.get(node).length = 1;
+                const ids = [node];
+                const file = await resolveRef(job.uses, 'workflow', workflowRoot, jobPath);
+                if (file && canEnter(file, stack, jobPath)) {
+                    const called = parse(file, jobPath);
+                    if (called?.type === 'workflow') {
+                        ids.push(...(await addWorkflow(called.file, (0, repository_1.repositoryRoot)(file), `${node}>`, `${labelPrefix}${jobId} > ${job.uses} > `, `${jobPath} > ${job.uses} > `, [...needs, node], [...stack, file], jobConditional)));
+                    }
+                }
+                alias.set(jobId, ids);
+                added.push(...ids.slice(1));
+                continue;
+            }
+            alias.set(jobId, [node]);
+            const counter = { next: 0 };
+            await addSteps(job.steps ?? [], node, `${jobPath}.`, counter, stack, workflowRoot, jobConditional);
+            graph.nodes.get(node).length = counter.next;
+        }
+        return added;
+    };
+    await addWorkflow(parsed.file, root, '', '', '', [], [path.resolve(parsed.path)], false);
+    return graph;
+}
+/**
+ * Whether an `if:` can skip the step/job: anything but a missing value,
+ * `true`, `success()` (the default) or `always()`.
+ */
+function hasCondition(condition) {
+    if (condition === undefined || condition === null || condition === true) {
+        return false;
+    }
+    const text = String(condition)
+        .trim()
+        .replace(/^\$\{\{([\s\S]*)\}\}$/, '$1')
+        .trim();
+    return !['', 'true', 'success()', 'always()'].includes(text);
+}
+function splitActionRef(uses) {
+    const atIndex = uses.lastIndexOf('@');
+    if (atIndex === -1 || uses.startsWith('docker://')) {
+        return { name: normalizeActionName(uses) };
+    }
+    return {
+        name: normalizeActionName(uses.slice(0, atIndex)),
+        version: uses.slice(atIndex + 1)
+    };
+}
+/**
+ * Lower-case the `owner/repo` part of a marketplace-style reference, which
+ * GitHub resolves case-insensitively. A path inside the repo, local paths
+ * (`./...`) and `docker://` references (whose tags are case-sensitive) are
+ * kept as they are.
+ */
+function normalizeActionName(name) {
+    if (name.startsWith('.') || name.startsWith('docker://'))
+        return name;
+    const parts = name.split('/');
+    return [
+        ...parts.slice(0, 2).map((p) => p.toLowerCase()),
+        ...parts.slice(2)
+    ].join('/');
+}
+/**
+ * Best-effort numeric semver-style comparison (ignoring a leading "v").
+ * Returns undefined when either version string isn't numeric dot-notation
+ * (e.g. a branch name or commit SHA), since it can't be meaningfully compared.
+ */
+function isVersionAtLeast(actual, min) {
+    const a = parseVersionParts(actual);
+    const m = parseVersionParts(min);
+    if (!a || !m)
+        return undefined;
+    const len = Math.max(a.length, m.length);
+    for (let i = 0; i < len; i++) {
+        const av = a[i] ?? 0;
+        const mv = m[i] ?? 0;
+        if (av > mv)
+            return true;
+        if (av < mv)
+            return false;
+    }
+    return true;
+}
+function parseVersionParts(version) {
+    const cleaned = version.trim().replace(/^v/i, '');
+    if (!cleaned)
+        return null;
+    const parts = cleaned.split('.').map(Number);
+    if (parts.some((n) => Number.isNaN(n)))
+        return null;
+    return parts;
+}
+//# sourceMappingURL=pipeline-contract-validator.js.map

package/dist/parser/validator.js

@@ -0,0 +1,232 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.workflowExpressionErrors = workflowExpressionErrors;
+exports.actionExpressionErrors = actionExpressionErrors;
+exports.validateWorkflow = validateWorkflow;
+exports.validateAction = validateAction;
+const workflow_parser_1 = require("./workflow-parser");
+const expression_1 = require("../runner/expression");
+/**
+ * Invalid `if:` expressions in a workflow: syntax errors, or contexts and
+ * functions not available where they're used. GitHub rejects such a
+ * workflow before running any job.
+ */
+function workflowExpressionErrors(workflow) {
+    const errors = [];
+    const check = (condition, location, at) => {
+        const message = (0, expression_1.validateExpression)(condition, location);
+        if (message)
+            errors.push({ path: at, message, severity: 'error' });
+    };
+    for (const [jobId, job] of Object.entries(workflow.jobs ?? {})) {
+        check(job.if, 'job-if', `jobs.${jobId}.if`);
+        (job.steps ?? []).forEach((step, i) => check(step.if, 'step-if', `jobs.${jobId}.steps[${i}].if`));
+    }
+    return errors;
+}
+/** Invalid `if:` expressions in a composite action's steps. */
+function actionExpressionErrors(action) {
+    const errors = [];
+    (action.runs?.steps ?? []).forEach((step, i) => {
+        const message = (0, expression_1.validateExpression)(step.if, 'composite-step-if');
+        if (message) {
+            errors.push({ path: `runs.steps[${i}].if`, message, severity: 'error' });
+        }
+    });
+    return errors;
+}
+/**
+ * Validate a workflow file
+ */
+function validateWorkflow(filePath) {
+    const errors = [];
+    try {
+        const parsed = (0, workflow_parser_1.parseWorkflow)(filePath);
+        const workflow = parsed.file;
+        // Validate name
+        if (!workflow.name || workflow.name.trim() === '') {
+            errors.push({
+                path: 'name',
+                message: 'Workflow name is required',
+                severity: 'error'
+            });
+        }
+        // Validate trigger
+        if (!workflow.on) {
+            errors.push({
+                path: 'on',
+                message: 'Workflow trigger (on) is required',
+                severity: 'error'
+            });
+        }
+        // Validate jobs
+        if (!workflow.jobs || Object.keys(workflow.jobs).length === 0) {
+            errors.push({
+                path: 'jobs',
+                message: 'At least one job is required',
+                severity: 'error'
+            });
+        }
+        else {
+            // Validate each job
+            Object.entries(workflow.jobs).forEach(([jobId, job]) => {
+                // Check if it's a reusable workflow call
+                if (job.uses) {
+                    // Reusable workflow - only needs 'uses'
+                    if (!job.uses.trim()) {
+                        errors.push({
+                            path: `jobs.${jobId}.uses`,
+                            message: 'Reusable workflow path cannot be empty',
+                            severity: 'error'
+                        });
+                    }
+                }
+                else {
+                    // Regular job - needs runs-on and steps
+                    if (!job['runs-on']) {
+                        errors.push({
+                            path: `jobs.${jobId}.runs-on`,
+                            message: 'Job must specify runs-on',
+                            severity: 'error'
+                        });
+                    }
+                    if (!job.steps || job.steps.length === 0) {
+                        errors.push({
+                            path: `jobs.${jobId}.steps`,
+                            message: 'Job must have at least one step',
+                            severity: 'error'
+                        });
+                    }
+                    else {
+                        // Validate each step
+                        job.steps.forEach((step, idx) => {
+                            if (!step.uses && !step.run) {
+                                errors.push({
+                                    path: `jobs.${jobId}.steps[${idx}]`,
+                                    message: 'Step must have either "uses" or "run"',
+                                    severity: 'error'
+                                });
+                            }
+                            if (step.uses && step.run) {
+                                errors.push({
+                                    path: `jobs.${jobId}.steps[${idx}]`,
+                                    message: 'Step cannot have both "uses" and "run"',
+                                    severity: 'error'
+                                });
+                            }
+                        });
+                    }
+                }
+            });
+        }
+        errors.push(...workflowExpressionErrors(workflow));
+    }
+    catch (error) {
+        errors.push({
+            path: 'root',
+            message: error instanceof Error ? error.message : 'Unknown error',
+            severity: 'error'
+        });
+    }
+    return {
+        valid: errors.length === 0,
+        errors
+    };
+}
+/**
+ * Validate an action file
+ */
+function validateAction(filePath) {
+    const errors = [];
+    try {
+        const parsed = (0, workflow_parser_1.parseAction)(filePath);
+        const action = parsed.file;
+        // Validate name
+        if (!action.name || action.name.trim() === '') {
+            errors.push({
+                path: 'name',
+                message: 'Action name is required',
+                severity: 'error'
+            });
+        }
+        // Validate description
+        if (!action.description || action.description.trim() === '') {
+            errors.push({
+                path: 'description',
+                message: 'Action description is required',
+                severity: 'error'
+            });
+        }
+        // Validate runs
+        if (!action.runs) {
+            errors.push({
+                path: 'runs',
+                message: 'Action must have a runs section',
+                severity: 'error'
+            });
+        }
+        else {
+            if (!action.runs.using) {
+                errors.push({
+                    path: 'runs.using',
+                    message: 'Action must specify runs.using',
+                    severity: 'error'
+                });
+            }
+            // Validate composite actions
+            if (action.runs.using === 'composite') {
+                if (!action.runs.steps || action.runs.steps.length === 0) {
+                    errors.push({
+                        path: 'runs.steps',
+                        message: 'Composite action must have at least one step',
+                        severity: 'error'
+                    });
+                }
+                else {
+                    // Validate each step
+                    action.runs.steps.forEach((step, idx) => {
+                        if (!step.uses && !step.run) {
+                            errors.push({
+                                path: `runs.steps[${idx}]`,
+                                message: 'Step must have either "uses" or "run"',
+                                severity: 'error'
+                            });
+                        }
+                        if (step.run && !step.shell) {
+                            errors.push({
+                                path: `runs.steps[${idx}]`,
+                                message: 'Composite action step with "run" must specify shell',
+                                severity: 'error'
+                            });
+                        }
+                    });
+                    errors.push(...actionExpressionErrors(action));
+                }
+            }
+        }
+        // Validate inputs
+        if (action.inputs) {
+            Object.entries(action.inputs).forEach(([inputName, input]) => {
+                if (!input.description) {
+                    errors.push({
+                        path: `inputs.${inputName}.description`,
+                        message: 'Input description is required',
+                        severity: 'warning'
+                    });
+                }
+            });
+        }
+    }
+    catch (error) {
+        errors.push({
+            path: 'root',
+            message: error instanceof Error ? error.message : 'Unknown error',
+            severity: 'error'
+        });
+    }
+    return {
+        valid: errors.length === 0 || errors.every((e) => e.severity === 'warning'),
+        errors
+    };
+}
+//# sourceMappingURL=validator.js.map