cloving 1.1.0 → 1.3.0

package/dist/tools/workflow-command.js

@@ -0,0 +1,143 @@
+import { absoluteWorkflowFolder } from "../src/project-settings.js";
+import { projectConfiguration, projectRoot } from "./project-configuration.js";
+import { spawn } from "node:child_process";
+import { lstat, mkdtemp, rm } from "node:fs/promises";
+import { homedir, tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { workflowTestLoader } from "./workflow-test-loader.js";
+import { preparedProject } from "./self-host-project.js";
+const usage = "Usage: cloving workflows list [--json] [--repository <directory>]\n       cloving workflows test [<id>] [--repository <directory>]\n";
+function invocation(argumentsList) {
+    const { values, positionals } = parseArgs({
+        args: [...argumentsList],
+        allowPositionals: true,
+        options: {
+            json: { type: "boolean" },
+            repository: { type: "string" },
+            help: { type: "boolean", short: "h" },
+        },
+    });
+    const [command, id, ...extra] = positionals;
+    if (extra.length > 0 || (command === "list" && id !== undefined))
+        throw new Error("unexpected-argument");
+    if (command !== "list" && command !== "test")
+        throw new Error("unknown-command");
+    if (command === "test" && values.json)
+        throw new Error("unexpected-option");
+    return { ...values, command, id };
+}
+export async function workflowCommand(argumentsList) {
+    let selected;
+    try {
+        selected = invocation(argumentsList);
+    }
+    catch {
+        process.stderr.write("invalid-invocation: " + usage);
+        return 2;
+    }
+    if (selected.help) {
+        process.stdout.write(usage);
+        return 0;
+    }
+    const temporary = await mkdtemp(join(tmpdir(), "cloving-workflows-"));
+    try {
+        const repository = resolve(selected.repository ?? process.cwd());
+        const result = await preparedProject({
+            product: resolve(import.meta.dirname, ".."),
+            project: join(temporary, "project"),
+            repository,
+            home: homedir(),
+            xdgConfigHome: process.env["XDG_CONFIG_HOME"],
+            userFolder: absoluteWorkflowFolder((await projectConfiguration(await projectRoot(repository), process.env))
+                .environment["CLOVING_WORKFLOW_FOLDER"]),
+        });
+        if (selected.command === "test")
+            return await testWorkflows(result.workflows, {
+                id: selected.id,
+                repository,
+            });
+        presentWorkflows(result.workflows, { json: selected.json === true });
+        return 0;
+    }
+    catch (error) {
+        process.stderr.write("workflow-inspection-failed: " +
+            (error instanceof Error ? error.message : "unavailable") +
+            "\n");
+        return 1;
+    }
+    finally {
+        await rm(temporary, { recursive: true, force: true });
+    }
+}
+function presentWorkflows(workflows, options) {
+    if (options.json) {
+        process.stdout.write(JSON.stringify(workflows) + "\n");
+        return;
+    }
+    for (const workflow of workflows)
+        process.stdout.write(`${workflow.workflowId ?? "unknown"} (${workflow.scope}, ${workflow.admitted ? "admitted" : "refused: " + workflow.codes.join(", ")}) ${JSON.stringify(workflow.file)}\n`);
+}
+async function testWorkflows(workflows, options) {
+    const { id, repository } = options;
+    const selected = workflows.filter((workflow) => workflow.scope !== "bundled" &&
+        (id === undefined || workflow.workflowId === id));
+    if (id !== undefined &&
+        !workflows.some((workflow) => workflow.workflowId === id)) {
+        process.stderr.write("unknown-workflow: " + id + "\n");
+        return 1;
+    }
+    const files = [];
+    for (const workflow of selected) {
+        const file = workflow.file.replace(/\.ts$/, ".test.ts");
+        const exists = await lstat(file).catch((error) => {
+            if (error instanceof Error && "code" in error && error.code === "ENOENT")
+                return undefined;
+            throw error;
+        });
+        if (exists?.isFile())
+            files.push(file);
+    }
+    if (files.length === 0) {
+        process.stderr.write("workflow-test-missing: " + (id ?? "no project or user tests") + "\n");
+        return 1;
+    }
+    return await runTests(files, repository);
+}
+function runTests(files, repository) {
+    return new Promise((settle, reject) => {
+        const child = spawn(process.execPath, [
+            "--experimental-strip-types",
+            "--import",
+            workflowTestLoader(),
+            "--test",
+            ...files,
+        ], {
+            cwd: repository,
+            stdio: "inherit",
+            env: { ...process.env, NODE_TEST_CONTEXT: undefined },
+        });
+        const interrupt = () => {
+            child.kill("SIGINT");
+        };
+        const terminate = () => {
+            child.kill("SIGTERM");
+        };
+        process.on("SIGINT", interrupt);
+        process.on("SIGTERM", terminate);
+        const cleanup = () => {
+            process.off("SIGINT", interrupt);
+            process.off("SIGTERM", terminate);
+        };
+        child.once("error", (error) => {
+            cleanup();
+            reject(error);
+        });
+        child.once("close", (code) => {
+            cleanup();
+            settle(code ?? 1);
+        });
+    });
+}
+if (process.argv[1] === import.meta.filename)
+    process.exitCode = await workflowCommand(process.argv.slice(2));

package/dist/tools/workflow-folder-capture.d.ts

@@ -0,0 +1,18 @@
+import { type BigIntStats } from "node:fs";
+export type WorkflowCaptureCode = "unsafe-workflow-path" | "workflow-read-failed" | "workflow-source-changed" | "unsupported-source" | "invalid-declaration";
+export interface WorkflowFolder {
+    readonly path: string;
+    readonly components: readonly {
+        readonly path: string;
+        readonly stats: BigIntStats;
+    }[];
+}
+export declare function inspectWorkflowFolder(root: string, parts: readonly string[]): Promise<WorkflowFolder>;
+export declare function captureWorkflowCandidate(folder: WorkflowFolder, name: string): Promise<{
+    source: string | undefined;
+    declaration: string | undefined;
+    helpers: Record<string, string>;
+    codes: WorkflowCaptureCode[];
+}>;
+export declare function workflowCaptureFailure(error: unknown): WorkflowCaptureCode;
+export declare function workflowFolderEntries(folder: WorkflowFolder): Promise<string[]>;

package/dist/tools/workflow-folder-capture.js

@@ -0,0 +1,261 @@
+import { constants } from "node:fs";
+import { lstat, open, readdir, realpath, } from "node:fs/promises";
+import { isAbsolute, join, relative, sep } from "node:path";
+import ts from "typescript";
+import { workflowHelperPath } from "../src/workflow-candidate.js";
+function contained(root, path) {
+    const suffix = relative(root, path);
+    return (!isAbsolute(suffix) && suffix !== ".." && !suffix.startsWith(`..${sep}`));
+}
+function safeComponent(name) {
+    return (name.length > 0 &&
+        name !== "." &&
+        name !== ".." &&
+        !/[/\\:]/.test(name) &&
+        !name.startsWith("~"));
+}
+export async function inspectWorkflowFolder(root, parts) {
+    const canonical = await realpath(root);
+    if (parts.some((part) => !safeComponent(part)))
+        throw new Error("unsafe-workflow-path");
+    const components = [];
+    let path = canonical;
+    for (const part of ["", ...parts]) {
+        path = join(path, part);
+        const stats = await lstat(path, { bigint: true }).catch(async (error) => {
+            await verifyFolder({ path, components });
+            throw error;
+        });
+        if (stats.isSymbolicLink())
+            throw new Error("unsafe-workflow-path");
+        if (!stats.isDirectory())
+            throw new Error("workflow-read-failed");
+        components.push({ path, stats });
+    }
+    const resolved = await realpath(path).catch(changedPathError);
+    const folder = { path, components };
+    await verifyFolder(folder);
+    if (!contained(canonical, resolved))
+        throw new Error("unsafe-workflow-path");
+    return folder;
+}
+function sameIdentity(left, right) {
+    return (left.dev === right.dev && left.ino === right.ino && left.mode === right.mode);
+}
+function sameSnapshot(left, right) {
+    return (sameIdentity(left, right) &&
+        left.size === right.size &&
+        left.mtimeNs === right.mtimeNs &&
+        left.ctimeNs === right.ctimeNs);
+}
+async function verifyFolder(folder) {
+    for (const component of folder.components) {
+        const compare = component.path === folder.path ? sameSnapshot : sameIdentity;
+        if (!compare(component.stats, await capturedStats(component.path)))
+            throw new Error("workflow-source-changed");
+    }
+}
+function capturedStats(path) {
+    return lstat(path, { bigint: true }).catch(changedPathError);
+}
+function changedPathError(error) {
+    if (error instanceof Error &&
+        "code" in error &&
+        (error.code === "ENOENT" ||
+            error.code === "ENOTDIR" ||
+            error.code === "ELOOP"))
+        throw new Error("workflow-source-changed");
+    throw error;
+}
+async function openSource(folder, name) {
+    const flags = constants.O_RDONLY | constants.O_NONBLOCK;
+    if (process.platform === "darwin")
+        return open(join(folder.path, name), flags | 0x20000000);
+    if (process.platform !== "linux")
+        throw new Error("workflow-read-failed");
+    const handles = [];
+    try {
+        let path = folder.components[0]?.path;
+        if (!path)
+            throw new Error("workflow-read-failed");
+        for (const component of folder.components) {
+            const handle = await open(path, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+            handles.push(handle);
+            if (!sameIdentity(component.stats, await handle.stat({ bigint: true })))
+                throw new Error("workflow-source-changed");
+            const next = folder.components[handles.length];
+            path = `/proc/self/fd/${String(handle.fd)}/${next ? relative(component.path, next.path) : name}`;
+        }
+        return await open(path, flags | constants.O_NOFOLLOW);
+    }
+    finally {
+        for (const handle of handles.reverse())
+            await handle.close();
+    }
+}
+async function inspectFile(folder, name) {
+    const parts = name.split("/");
+    const fileName = parts.pop();
+    if (!fileName || parts.some((part) => !safeComponent(part)))
+        throw new Error("unsafe-workflow-path");
+    let parent = folder;
+    for (const part of parts) {
+        const path = join(parent.path, part);
+        const stats = await lstat(path, { bigint: true });
+        if (!stats.isDirectory())
+            throw new Error("unsafe-workflow-path");
+        parent = { path, components: [...parent.components, { path, stats }] };
+    }
+    await verifyFolder(parent);
+    const path = join(folder.path, name);
+    const stats = await lstat(path, { bigint: true });
+    if (!stats.isFile())
+        throw new Error("unsafe-workflow-path");
+    const resolved = await realpath(path).catch(changedPathError);
+    if (!sameSnapshot(stats, await capturedStats(path)))
+        throw new Error("workflow-source-changed");
+    if (!contained(folder.path, resolved))
+        throw new Error("unsafe-workflow-path");
+    return { path, name, stats, folder: parent, fileName };
+}
+async function captureFile(folder, file) {
+    const { stats } = file;
+    await verifyFolder(folder);
+    const handle = await openSource(file.folder, file.fileName).catch(changedPathError);
+    try {
+        if (!sameSnapshot(stats, await handle.stat({ bigint: true })))
+            throw new Error("workflow-source-changed");
+        const bytes = await handle.readFile();
+        if (!sameSnapshot(stats, await handle.stat({ bigint: true })) ||
+            BigInt(bytes.length) !== stats.size)
+            throw new Error("workflow-source-changed");
+        return { ...file, bytes };
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function captureFiles(folder, names) {
+    const inspected = [];
+    const captured = [];
+    const codes = [];
+    for (const name of names) {
+        try {
+            inspected.push(await inspectFile(folder, name));
+        }
+        catch (error) {
+            codes.push(workflowCaptureFailure(error));
+        }
+    }
+    for (const file of inspected) {
+        try {
+            captured.push(await captureFile(folder, file));
+        }
+        catch (error) {
+            codes.push(workflowCaptureFailure(error));
+        }
+    }
+    for (const file of captured) {
+        await verifyFolder(file.folder);
+        if (!sameSnapshot(file.stats, await capturedStats(file.path)))
+            throw new Error("workflow-source-changed");
+    }
+    return { captured, codes };
+}
+async function captureImports(folder, snapshot) {
+    const { captured, codes } = snapshot;
+    const helpers = {};
+    for (const source of captured) {
+        if (!source.name.endsWith(".ts"))
+            continue;
+        for (const imported of ts.preProcessFile(source.bytes.toString("utf8"))
+            .importedFiles) {
+            const name = workflowHelperPath(source.name, imported.fileName);
+            if (!name || captured.some((file) => file.name === name))
+                continue;
+            const result = await captureFiles(folder, [name]);
+            codes.push(...result.codes);
+            captured.push(...result.captured);
+            const text = decodedFile({ bytes: result.captured[0]?.bytes, code: "unsupported-source" }, codes);
+            if (text !== undefined)
+                helpers[name] = text;
+        }
+    }
+    for (const file of captured) {
+        await verifyFolder(file.folder);
+        if (!sameSnapshot(file.stats, await capturedStats(file.path)))
+            throw new Error("workflow-source-changed");
+    }
+    return helpers;
+}
+function decodedFile(input, codes) {
+    if (input.bytes === undefined)
+        return undefined;
+    const text = input.bytes.toString("utf8");
+    if (input.bytes.equals(Buffer.from(text)))
+        return text;
+    codes.push(input.code);
+    return undefined;
+}
+export async function captureWorkflowCandidate(folder, name) {
+    if (!safeComponent(name) || !name.endsWith(".ts") || name.endsWith(".d.ts"))
+        throw new Error("unsafe-workflow-path");
+    await verifyFolder(folder);
+    const declarationName = name.slice(0, -3) + ".declaration.json";
+    const { captured, codes } = await captureFiles(folder, [
+        name,
+        declarationName,
+    ]);
+    const helpers = await captureImports(folder, { captured, codes });
+    await verifyFolder(folder);
+    const source = decodedFile({
+        bytes: captured.find((file) => file.name === name)?.bytes,
+        code: "unsupported-source",
+    }, codes);
+    const declaration = decodedFile({
+        bytes: captured.find((file) => file.name === declarationName)?.bytes,
+        code: "invalid-declaration",
+    }, codes);
+    return {
+        source,
+        declaration,
+        helpers,
+        codes: [
+            ...new Set(codes.includes("unsafe-workflow-path")
+                ? codes.filter((code) => code !== "workflow-read-failed")
+                : codes),
+        ].sort(),
+    };
+}
+export function workflowCaptureFailure(error) {
+    const code = error instanceof Error && "code" in error ? error.code : undefined;
+    if (code === "ELOOP")
+        return "unsafe-workflow-path";
+    const message = error instanceof Error ? error.message : "";
+    if (message === "unsafe-workflow-path" ||
+        message === "workflow-source-changed" ||
+        message === "unsupported-source" ||
+        message === "invalid-declaration")
+        return message;
+    return "workflow-read-failed";
+}
+async function descriptorEntries(folder) {
+    const handle = await openSource(folder, ".").catch(changedPathError);
+    try {
+        const expected = folder.components.at(-1)?.stats;
+        if (!expected ||
+            !sameIdentity(expected, await handle.stat({ bigint: true })))
+            throw new Error("workflow-source-changed");
+        return await readdir(`/proc/self/fd/${String(handle.fd)}`);
+    }
+    finally {
+        await handle.close();
+    }
+}
+export async function workflowFolderEntries(folder) {
+    const entries = process.platform === "darwin"
+        ? await readdir(`/.nofollow${folder.path}`).catch(changedPathError)
+        : await descriptorEntries(folder);
+    await verifyFolder(folder);
+    return entries;
+}

package/dist/tools/workflow-folders.d.ts

@@ -0,0 +1,49 @@
+import type { WorkflowDeclaration } from "../src/workflow-declaration.ts";
+import { type CandidateDeclaration, type WorkflowCandidateCode } from "../src/workflow-candidate.ts";
+import { type WorkflowConflictCode, type WorkflowReservation } from "../src/workflow-discovery.ts";
+import type { CandidatePackageOptions } from "./workflow-candidate-program.ts";
+import { type WorkflowCaptureCode } from "./workflow-folder-capture.ts";
+export interface WorkflowFolderInput {
+    readonly repository: string;
+    readonly home: string;
+    readonly xdgConfigHome?: string | undefined;
+    readonly userFolder?: string | undefined;
+    readonly bundled: readonly WorkflowReservation[];
+}
+interface WorkflowLabel {
+    readonly scope: "project" | "user";
+    readonly label: string;
+}
+interface WorkflowSnapshot extends WorkflowLabel {
+    readonly baseName: string;
+    readonly source: string;
+    readonly declaration: string;
+    readonly helpers: Readonly<Record<string, string>>;
+}
+export interface WorkflowFolderCandidate extends WorkflowSnapshot {
+    readonly repository: string;
+    readonly artifactDigest: string;
+}
+export interface WorkflowFolderRefusal extends WorkflowLabel {
+    readonly codes: readonly (WorkflowCandidateCode | WorkflowCaptureCode | WorkflowConflictCode | "compile-failed")[];
+}
+export interface WorkflowListing {
+    readonly scope: "bundled" | "project" | "user";
+    readonly workflowId: string | null;
+    readonly file: string;
+    readonly admitted: boolean;
+    readonly codes: readonly string[];
+    readonly declaration?: CandidateDeclaration | WorkflowDeclaration;
+}
+export interface WorkflowFolderResult {
+    readonly workflows: readonly WorkflowListing[];
+    readonly repository: string;
+    readonly candidates: readonly WorkflowFolderCandidate[];
+    readonly refusals: readonly WorkflowFolderRefusal[];
+}
+export declare function userLocation(input: Pick<WorkflowFolderInput, "home" | "xdgConfigHome" | "userFolder">): {
+    readonly root: string;
+    readonly parts: readonly string[];
+};
+export declare function loadWorkflowFolders(input: WorkflowFolderInput, installed?: CandidatePackageOptions): Promise<WorkflowFolderResult>;
+export {};

package/dist/tools/workflow-folders.js

@@ -0,0 +1,203 @@
+import { absoluteWorkflowFolder } from "../src/project-settings.js";
+import { createHash } from "node:crypto";
+import { realpath } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join } from "node:path";
+import ts from "typescript";
+import { isCandidateDeclaration, } from "../src/workflow-candidate.js";
+import { record } from "../src/protocol.js";
+import { workflowConflicts, } from "../src/workflow-discovery.js";
+import { admitWorkflowCandidate } from "./admit-workflow.js";
+import { captureWorkflowCandidate, inspectWorkflowFolder, workflowCaptureFailure, workflowFolderEntries, } from "./workflow-folder-capture.js";
+function fileLabel(name) {
+    return /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}\.ts$/.test(name)
+        ? name
+        : "file-" + createHash("sha256").update(name).digest("hex").slice(0, 16);
+}
+function parsedDeclaration(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+function identity(entry) {
+    const snapshot = entry.kind === "captured" ? entry.snapshot : entry;
+    const source = ts.createSourceFile("candidate.ts", snapshot.source ?? "", ts.ScriptTarget.Latest, true);
+    const parsed = parsedDeclaration(snapshot.declaration ?? "");
+    const declaration = record(record(parsed)?.["workflow"]);
+    const workflowId = declaration?.["workflowId"];
+    return {
+        queue: isCandidateDeclaration(parsed) && parsed.workflow.queue === true,
+        baseName: snapshot.baseName,
+        workflowId: typeof workflowId === "string" ? workflowId : undefined,
+        functionNames: source.statements
+            .filter(ts.isFunctionDeclaration)
+            .filter((node) => (ts.getCombinedModifierFlags(node) & ts.ModifierFlags.Export) !== 0)
+            .flatMap((node) => (node.name ? [node.name.text] : [])),
+    };
+}
+function compareLabels(left, right) {
+    const a = `${left.scope}\0${left.label}`;
+    const b = `${right.scope}\0${right.label}`;
+    return a < b ? -1 : Number(a > b);
+}
+async function scanFolder(location, refusals) {
+    let folder;
+    let entries;
+    try {
+        folder = await inspectWorkflowFolder(location.root, location.parts);
+        entries = await workflowFolderEntries(folder);
+    }
+    catch (error) {
+        if (!(error instanceof Error && "code" in error && error.code === "ENOENT"))
+            refusals.push({
+                scope: location.scope,
+                label: "workflows/",
+                codes: [workflowCaptureFailure(error)],
+            });
+        return [];
+    }
+    const snapshots = [];
+    for (const name of entries
+        .filter((name) => name.endsWith(".ts") &&
+        !name.endsWith(".d.ts") &&
+        !name.endsWith(".test.ts"))
+        .sort()) {
+        snapshots.push(await captureEntry(folder, {
+            scope: location.scope,
+            label: fileLabel(name),
+            name,
+        }));
+    }
+    return snapshots;
+}
+async function captureEntry(folder, file) {
+    const label = {
+        scope: file.scope,
+        label: file.label,
+        baseName: file.name.slice(0, -3),
+    };
+    try {
+        const capture = await captureWorkflowCandidate(folder, file.name);
+        if (capture.source === undefined ||
+            capture.declaration === undefined ||
+            capture.codes.length > 0)
+            return { kind: "refused", ...label, ...capture };
+        return {
+            kind: "captured",
+            snapshot: {
+                ...label,
+                source: capture.source,
+                declaration: capture.declaration,
+                helpers: capture.helpers,
+            },
+        };
+    }
+    catch (error) {
+        return {
+            kind: "refused",
+            ...label,
+            codes: [workflowCaptureFailure(error)],
+            source: undefined,
+            declaration: undefined,
+        };
+    }
+}
+export function userLocation(input) {
+    const folder = absoluteWorkflowFolder(input.userFolder);
+    if (folder !== undefined)
+        return { root: dirname(folder), parts: [basename(folder)] };
+    const configuration = input.xdgConfigHome && isAbsolute(input.xdgConfigHome)
+        ? input.xdgConfigHome
+        : join(input.home, ".config");
+    return { root: configuration, parts: ["cloving", "workflows"] };
+}
+async function scanFolders(input, refusals) {
+    const repository = await realpath(input.repository);
+    const snapshots = [
+        ...(await scanFolder({ scope: "project", root: repository, parts: [".cloving", "workflows"] }, refusals)),
+        ...(await scanFolder({ scope: "user", ...userLocation(input) }, refusals)),
+    ];
+    return { repository, snapshots };
+}
+function workflowFolder(input, scope) {
+    if (scope === "project")
+        return join(input.repository, ".cloving", "workflows");
+    const { root, parts } = userLocation(input);
+    return join(root, ...parts);
+}
+function folderListings(input, found) {
+    const { repository, snapshots, refusals } = found;
+    const workflows = snapshots.map((entry) => {
+        const snapshot = entry.kind === "captured" ? entry.snapshot : entry;
+        const declaration = parsedDeclaration(snapshot.declaration ?? "");
+        const refusal = refusals.find((item) => item.scope === snapshot.scope && item.label === snapshot.label);
+        const folder = workflowFolder({ ...input, repository }, snapshot.scope);
+        return {
+            scope: snapshot.scope,
+            workflowId: isCandidateDeclaration(declaration)
+                ? declaration.workflow.workflowId
+                : null,
+            file: join(folder, snapshot.baseName + ".ts"),
+            admitted: refusal === undefined,
+            codes: refusal?.codes ?? [],
+            ...(isCandidateDeclaration(declaration) ? { declaration } : {}),
+        };
+    });
+    return [
+        ...workflows,
+        ...refusals
+            .filter((refusal) => refusal.label === "workflows/")
+            .map((refusal) => ({
+            scope: refusal.scope,
+            workflowId: null,
+            file: workflowFolder({ ...input, repository }, refusal.scope),
+            admitted: false,
+            codes: refusal.codes,
+        })),
+    ];
+}
+export async function loadWorkflowFolders(input, installed = {}) {
+    const candidates = [];
+    const refusals = [];
+    const { repository, snapshots } = await scanFolders(input, refusals);
+    const conflicts = workflowConflicts(snapshots.map(identity), input.bundled);
+    for (const [index, entry] of snapshots.entries()) {
+        const label = entry.kind === "captured" ? entry.snapshot : entry;
+        const codes = [
+            ...new Set([
+                ...(entry.kind === "refused" ? entry.codes : []),
+                ...(conflicts[index] ?? []),
+            ]),
+        ].sort();
+        if (entry.kind === "refused" || codes.length > 0) {
+            refusals.push({ scope: label.scope, label: label.label, codes });
+            continue;
+        }
+        const { snapshot } = entry;
+        const result = await admitWorkflowCandidate({
+            source: snapshot.source,
+            declaration: parsedDeclaration(snapshot.declaration),
+            helpers: snapshot.helpers,
+        }, installed);
+        if (result.kind === "refused")
+            refusals.push({
+                scope: snapshot.scope,
+                label: snapshot.label,
+                codes: result.codes,
+            });
+        else
+            candidates.push({
+                ...snapshot,
+                repository,
+                artifactDigest: result.artifactDigest,
+            });
+    }
+    return {
+        workflows: folderListings(input, { repository, snapshots, refusals }),
+        repository,
+        candidates: candidates.sort(compareLabels),
+        refusals: refusals.sort(compareLabels),
+    };
+}

package/dist/tools/workflow-source-effects.d.ts

@@ -0,0 +1,10 @@
+import ts from "typescript";
+export interface ReferenceContext {
+    readonly parent: ts.Node | undefined;
+    readonly checker: ts.TypeChecker;
+    readonly profile?: "candidate";
+}
+export declare function referenceSymbol(node: ts.Identifier, context: ReferenceContext): ts.Symbol | undefined;
+export declare function typeOnlyEffectNode(node: ts.Node): boolean;
+export declare function restrictedEffect(node: ts.Node, context: ReferenceContext): boolean;
+export declare function sourceEffectNodes(source: ts.SourceFile, context: Omit<ReferenceContext, "parent">): readonly ts.Node[];