cloving 1.0.1 → 1.2.0

package/dist/tools/workflow-candidate-program.d.ts

@@ -0,0 +1,11 @@
+import ts from "typescript";
+export declare const candidatePackageRoot: string;
+export interface CandidatePackageOptions {
+    readonly packageRoot?: string;
+}
+export declare function resolvedSymbol(checker: ts.TypeChecker, symbol: ts.Symbol | undefined): ts.Symbol | undefined;
+export declare function candidateProgram(text: string, installed?: CandidatePackageOptions): {
+    readonly program: ts.Program;
+    readonly source: ts.SourceFile;
+    readonly modules: ReadonlyMap<string, ts.SourceFile>;
+};

package/dist/tools/workflow-candidate-program.js

@@ -0,0 +1,78 @@
+import { dirname, join, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import ts from "typescript";
+import metadata from "#package" with { type: "json" };
+export const candidatePackageRoot = dirname(fileURLToPath(import.meta.resolve("#package")));
+export function resolvedSymbol(checker, symbol) {
+    if (!symbol || (symbol.flags & ts.SymbolFlags.Alias) === 0)
+        return symbol;
+    return checker.getAliasedSymbol(symbol);
+}
+export function candidateProgram(text, installed = {}) {
+    const packageRoot = resolve(installed.packageRoot ?? candidatePackageRoot);
+    const candidate = join(packageRoot, "candidate.ts");
+    const entries = new Map(Object.entries(metadata.exports).map(([name, entry]) => [
+        `cloving${name.slice(1)}`,
+        resolve(packageRoot, entry.types),
+    ]));
+    const options = {
+        target: ts.ScriptTarget.ES2024,
+        module: ts.ModuleKind.ESNext,
+        moduleResolution: ts.ModuleResolutionKind.Bundler,
+        lib: ["lib.es2024.d.ts", "lib.dom.d.ts"],
+        types: [],
+        strict: true,
+        noEmit: true,
+    };
+    const host = trustedHost({ candidate, text, options, entries, packageRoot });
+    const program = ts.createProgram([candidate, ...entries.values()], options, host);
+    const source = program.getSourceFile(candidate);
+    if (!source)
+        throw new Error("candidate-analysis-unavailable");
+    const modules = new Map();
+    for (const [name, file] of entries) {
+        const declaration = program.getSourceFile(file);
+        if (!declaration)
+            throw new Error("candidate-surface-unavailable");
+        modules.set(name, declaration);
+    }
+    return { program, source, modules };
+}
+function trustedHost(input) {
+    const { candidate, text, options, entries, packageRoot } = input;
+    const libraries = dirname(ts.getDefaultLibFilePath(options)) + sep;
+    const declarations = join(packageRoot, "dist/src") + sep;
+    const readFile = (file) => {
+        if (file === candidate)
+            return text;
+        const absolute = resolve(file);
+        if (!absolute.endsWith(".d.ts"))
+            return undefined;
+        if (!absolute.startsWith(libraries) && !absolute.startsWith(declarations))
+            return undefined;
+        return ts.sys.readFile(absolute);
+    };
+    const host = ts.createCompilerHost(options);
+    host.readFile = readFile;
+    host.fileExists = (file) => readFile(file) !== undefined;
+    host.getSourceFile = (file, languageVersion) => {
+        const content = readFile(file);
+        return content === undefined
+            ? undefined
+            : ts.createSourceFile(file, content, languageVersion, true);
+    };
+    host.resolveModuleNameLiterals = (names, containingFile) => names.map(({ text: name }) => {
+        const installed = entries.get(name);
+        if (installed)
+            return {
+                resolvedModule: {
+                    resolvedFileName: installed,
+                    extension: ts.Extension.Dts,
+                },
+            };
+        if (containingFile === candidate)
+            return { resolvedModule: undefined };
+        return ts.resolveModuleName(name, containingFile, options, host);
+    });
+    return host;
+}

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

@@ -0,0 +1,6 @@
+import { type CandidatePackageOptions } from "./workflow-candidate-program.ts";
+import type { CandidateAnalysis, InstalledWorkflowExports } from "../src/workflow-candidate.ts";
+export declare function analyzeWorkflowCandidate(text: string, installed?: CandidatePackageOptions): {
+    readonly analysis: CandidateAnalysis;
+    readonly installedExports: InstalledWorkflowExports;
+};

package/dist/tools/workflow-candidate-source.js

@@ -0,0 +1,107 @@
+import ts from "typescript";
+import { candidateProgram, resolvedSymbol, } from "./workflow-candidate-program.js";
+import { protectedEffectFact, passiveCandidateModule, unsupportedCandidateNode, workflowShape, } from "./workflow-candidate-syntax.js";
+import { sourceEffectNodes } from "./workflow-source-effects.js";
+import { candidateEffectTotals } from "./workflow-candidate-counts.js";
+function exportSnapshot(modules, checker) {
+    return Object.fromEntries([...modules].map(([name, declaration]) => {
+        const symbol = checker.getSymbolAtLocation(declaration);
+        return [
+            name,
+            symbol
+                ? checker
+                    .getExportsOfModule(symbol)
+                    .map((entry) => entry.name)
+                    .sort()
+                : [],
+        ];
+    }));
+}
+function protectedHelper(modules, options) {
+    const { checker } = options;
+    const protectedModule = modules.get(options.subpath);
+    const moduleSymbol = protectedModule && checker.getSymbolAtLocation(protectedModule);
+    return (moduleSymbol &&
+        resolvedSymbol(checker, checker
+            .getExportsOfModule(moduleSymbol)
+            .find((entry) => entry.name === options.name)));
+}
+function sourceFacts(symbols) {
+    const { source } = symbols;
+    const imports = [];
+    const effects = [];
+    const unsupportedForms = [];
+    function visit(node) {
+        const imported = sourceImport(node);
+        if (imported)
+            imports.push(imported);
+        const effect = protectedEffectFact(node, symbols);
+        if (effect)
+            effects.push(effect);
+        if (unsupportedCandidateNode(node, symbols))
+            unsupportedForms.push("unsupported-syntax");
+        ts.forEachChild(node, visit);
+    }
+    visit(source);
+    return {
+        imports,
+        effects,
+        directEffects: sourceEffectNodes(source, {
+            checker: symbols.checker,
+            profile: "candidate",
+        })
+            .filter((node) => !ts.isIdentifier(node) || node.text !== "require")
+            .map(() => "restricted-effect"),
+        unsupportedForms,
+        ...candidateEffectTotals(source, symbols),
+    };
+}
+function sourceImport(node) {
+    if (!ts.isImportDeclaration(node) ||
+        !ts.isStringLiteral(node.moduleSpecifier))
+        return undefined;
+    const bindings = node.importClause?.namedBindings;
+    return {
+        module: node.moduleSpecifier.text,
+        names: bindings && ts.isNamedImports(bindings)
+            ? bindings.elements.map((entry) => entry.propertyName?.text ?? entry.name.text)
+            : [],
+    };
+}
+export function analyzeWorkflowCandidate(text, installed = {}) {
+    const { program, source, modules } = candidateProgram(text, installed);
+    const checker = program.getTypeChecker();
+    const symbols = {
+        checker,
+        source,
+        protectedSymbol: protectedHelper(modules, {
+            checker,
+            subpath: "cloving/workflows/steps/protected-effect",
+            name: "protectedEffect",
+        }),
+        handoffSymbol: protectedHelper(modules, {
+            checker,
+            subpath: "cloving/workflows/steps/handoff",
+            name: "handoff",
+        }),
+    };
+    const facts = sourceFacts(symbols);
+    const invalid = !workflowShape(source) ||
+        source.referencedFiles.length > 0 ||
+        source.typeReferenceDirectives.length > 0 ||
+        source.libReferenceDirectives.length > 0 ||
+        program.getSyntacticDiagnostics(source).length > 0;
+    return {
+        analysis: {
+            ...facts,
+            unsupportedForms: [
+                ...facts.unsupportedForms,
+                ...(invalid ? ["workflow-shape"] : []),
+                ...(facts.directEffects.length === 0 && !passiveCandidateModule(source)
+                    ? ["module-initialization"]
+                    : []),
+            ],
+        },
+        installedExports: exportSnapshot(modules, checker),
+    };
+}

package/dist/tools/workflow-candidate-syntax.d.ts

@@ -0,0 +1,15 @@
+import ts from "typescript";
+import type { CandidateEffect } from "../src/workflow-candidate.ts";
+export interface CandidateSymbols {
+    readonly checker: ts.TypeChecker;
+    readonly source: ts.SourceFile;
+    readonly protectedSymbol: ts.Symbol | undefined;
+    readonly handoffSymbol: ts.Symbol | undefined;
+}
+export declare function propertyName(name: ts.PropertyName): string | undefined;
+export declare function protectedCall(node: ts.Node, symbols: CandidateSymbols): node is ts.CallExpression;
+export declare function handoffCall(node: ts.CallExpression, symbols: CandidateSymbols): boolean;
+export declare function protectedEffectFact(node: ts.Node, symbols: CandidateSymbols): CandidateEffect | undefined;
+export declare function unsupportedCandidateNode(node: ts.Node, symbols: CandidateSymbols): boolean;
+export declare function workflowShape(source: ts.SourceFile): boolean;
+export declare function passiveCandidateModule(source: ts.SourceFile): boolean;

package/dist/tools/workflow-candidate-syntax.js

@@ -0,0 +1,219 @@
+import ts from "typescript";
+import { resolvedSymbol } from "./workflow-candidate-program.js";
+import { referenceSymbol } from "./workflow-source-effects.js";
+export function propertyName(name) {
+    if (ts.isIdentifier(name) || ts.isStringLiteral(name))
+        return name.text;
+    return undefined;
+}
+export function protectedCall(node, symbols) {
+    if (!ts.isCallExpression(node) || !ts.isIdentifier(node.expression))
+        return false;
+    const symbol = resolvedSymbol(symbols.checker, symbols.checker.getSymbolAtLocation(node.expression));
+    return (symbol !== undefined &&
+        [symbols.protectedSymbol, symbols.handoffSymbol].includes(symbol));
+}
+export function handoffCall(node, symbols) {
+    return (symbols.handoffSymbol !== undefined &&
+        resolvedSymbol(symbols.checker, symbols.checker.getSymbolAtLocation(node.expression)) === symbols.handoffSymbol);
+}
+function literalField(node, field) {
+    const property = node.properties.find((entry) => entry.name && propertyName(entry.name) === field);
+    if (!property || !ts.isPropertyAssignment(property))
+        return null;
+    return ts.isStringLiteral(property.initializer)
+        ? property.initializer.text
+        : null;
+}
+export function protectedEffectFact(node, symbols) {
+    if (!protectedCall(node, symbols))
+        return undefined;
+    if (handoffCall(node, symbols))
+        return undefined;
+    const argument = node.arguments[0];
+    if (!argument || !ts.isObjectLiteralExpression(argument))
+        return undefined;
+    return {
+        capability: literalField(argument, "capability"),
+        method: literalField(argument, "method"),
+    };
+}
+function escapedHelper(node, symbols) {
+    if (!ts.isIdentifier(node))
+        return false;
+    const symbol = resolvedSymbol(symbols.checker, referenceSymbol(node, { parent: node.parent, checker: symbols.checker }));
+    if (symbol === undefined ||
+        ![symbols.protectedSymbol, symbols.handoffSymbol].includes(symbol))
+        return false;
+    if (ts.isImportSpecifier(node.parent))
+        return false;
+    return (!ts.isCallExpression(node.parent) ||
+        node.parent.expression !== node ||
+        node.parent.questionDotToken !== undefined);
+}
+function invalidImport(node) {
+    if (!ts.isImportDeclaration(node))
+        return false;
+    const clause = node.importClause;
+    return (!clause ||
+        clause.name !== undefined ||
+        !clause.namedBindings ||
+        !ts.isNamedImports(clause.namedBindings) ||
+        node.attributes !== undefined);
+}
+function invalidRequest(node, symbols) {
+    if (!protectedCall(node, symbols))
+        return false;
+    if (!workflowBodyCall(node))
+        return true;
+    const argument = node.arguments[0];
+    if (node.arguments.length !== 1 ||
+        !argument ||
+        !ts.isObjectLiteralExpression(argument))
+        return true;
+    const names = argument.properties.map((entry) => entry.name && propertyName(entry.name));
+    return (names.includes(undefined) ||
+        new Set(names).size !== names.length ||
+        argument.properties.some((entry) => !ts.isPropertyAssignment(entry)));
+}
+function workflowBodyCall(node) {
+    let child = node;
+    let parent = node.parent;
+    while (!ts.isFunctionLike(parent)) {
+        if (ts.isSourceFile(parent) || ts.isClassLike(parent))
+            return false;
+        child = parent;
+        parent = parent.parent;
+    }
+    if (!ts.isFunctionDeclaration(parent) || !ts.isSourceFile(parent.parent))
+        return false;
+    return (parent.body === child &&
+        (ts.getCombinedModifierFlags(parent) & ts.ModifierFlags.Export) !== 0);
+}
+function dynamicLoading(node, symbols) {
+    if (node.kind === ts.SyntaxKind.ImportKeyword ||
+        ts.isImportEqualsDeclaration(node) ||
+        ts.isImportTypeNode(node) ||
+        ts.isMetaProperty(node))
+        return true;
+    if (!ts.isIdentifier(node) || node.text !== "require")
+        return false;
+    const symbol = symbols.checker.getSymbolAtLocation(node);
+    return !symbol?.declarations?.some((entry) => entry.getSourceFile() === symbols.source);
+}
+function ambientDeclaration(node) {
+    if (ts.isModuleDeclaration(node))
+        return true;
+    return (ts.canHaveModifiers(node) &&
+        (ts.getModifiers(node) ?? []).some((modifier) => modifier.kind === ts.SyntaxKind.DeclareKeyword));
+}
+function computedAccess(node) {
+    if (ts.isComputedPropertyName(node))
+        return true;
+    return (ts.isElementAccessExpression(node) &&
+        !ts.isStringLiteral(node.argumentExpression) &&
+        !ts.isNumericLiteral(node.argumentExpression));
+}
+export function unsupportedCandidateNode(node, symbols) {
+    const checks = [
+        escapedHelper(node, symbols),
+        invalidImport(node),
+        invalidRequest(node, symbols),
+        dynamicLoading(node, symbols),
+        ambientDeclaration(node),
+        computedAccess(node),
+        ts.isExportDeclaration(node) || ts.isExportAssignment(node),
+        ts.isSpreadAssignment(node) || ts.isSpreadElement(node),
+        node.kind === ts.SyntaxKind.ThisKeyword || ts.isWithStatement(node),
+        ts.isStringLiteral(node) && node.text === "use step",
+    ];
+    return checks.some(Boolean);
+}
+export function workflowShape(source) {
+    const exported = source.statements.filter((node) => ts.isFunctionDeclaration(node) &&
+        (ts.getModifiers(node) ?? []).some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword));
+    const candidate = exported[0];
+    if (exported.length !== 1 ||
+        !candidate ||
+        !ts.isFunctionDeclaration(candidate))
+        return false;
+    if (!workflowFunction(candidate))
+        return false;
+    const directives = [];
+    function visit(node) {
+        if (ts.isStringLiteral(node) && node.text === "use workflow")
+            directives.push(node);
+        ts.forEachChild(node, visit);
+    }
+    visit(source);
+    return directives.length === 1;
+}
+function workflowFunction(candidate) {
+    if (!candidate.name || !candidate.body || candidate.asteriskToken)
+        return false;
+    const modifiers = ts.getModifiers(candidate) ?? [];
+    if (!modifiers.some((modifier) => modifier.kind === ts.SyntaxKind.AsyncKeyword) ||
+        modifiers.some((modifier) => modifier.kind === ts.SyntaxKind.DefaultKeyword))
+        return false;
+    const first = candidate.body.statements[0];
+    return first !== undefined && workflowDirective(first);
+}
+function workflowDirective(node) {
+    return (ts.isExpressionStatement(node) &&
+        ts.isStringLiteral(node.expression) &&
+        node.expression.text === "use workflow");
+}
+function unwrappedInitializer(node) {
+    if (ts.isParenthesizedExpression(node) ||
+        ts.isAsExpression(node) ||
+        ts.isSatisfiesExpression(node) ||
+        ts.isTypeAssertionExpression(node))
+        return node.expression;
+    return undefined;
+}
+function passiveCompound(node) {
+    if (ts.isArrayLiteralExpression(node))
+        return node.elements.every((element) => ts.isOmittedExpression(element) || passiveInitializer(element));
+    if (ts.isObjectLiteralExpression(node))
+        return node.properties.every((property) => ts.isPropertyAssignment(property) &&
+            !ts.isComputedPropertyName(property.name) &&
+            passiveInitializer(property.initializer));
+    return false;
+}
+function passiveInitializer(node) {
+    if (!node)
+        return false;
+    if (ts.isLiteralExpression(node))
+        return true;
+    if ([
+        ts.SyntaxKind.TrueKeyword,
+        ts.SyntaxKind.FalseKeyword,
+        ts.SyntaxKind.NullKeyword,
+    ].includes(node.kind))
+        return true;
+    if (ts.isArrowFunction(node) || ts.isFunctionExpression(node))
+        return true;
+    if (ts.isPrefixUnaryExpression(node))
+        return ([ts.SyntaxKind.PlusToken, ts.SyntaxKind.MinusToken].includes(node.operator) && ts.isNumericLiteral(node.operand));
+    const inner = unwrappedInitializer(node);
+    return inner ? passiveInitializer(inner) : passiveCompound(node);
+}
+function passiveStatement(node) {
+    if (ts.isVariableStatement(node))
+        return ((node.declarationList.flags & ts.NodeFlags.Const) !== 0 &&
+            node.declarationList.declarations.every((declaration) => (ts.getCombinedModifierFlags(declaration) &
+                ts.ModifierFlags.Export) ===
+                0 &&
+                ts.isIdentifier(declaration.name) &&
+                passiveInitializer(declaration.initializer)));
+    if (ts.isExpressionStatement(node))
+        return ts.isStringLiteral(node.expression);
+    return (ts.isImportDeclaration(node) ||
+        ts.isTypeAliasDeclaration(node) ||
+        ts.isInterfaceDeclaration(node) ||
+        ts.isFunctionDeclaration(node) ||
+        ts.isEmptyStatement(node));
+}
+export function passiveCandidateModule(source) {
+    return source.statements.every(passiveStatement);
+}

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

@@ -0,0 +1,17 @@
+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;
+    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,216 @@
+import { constants } from "node:fs";
+import { lstat, open, readdir, realpath, } from "node:fs/promises";
+import { isAbsolute, join, relative, sep } from "node:path";
+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 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 };
+}
+async function captureFile(folder, file) {
+    const { stats } = file;
+    const handle = await openSource(folder, file.name).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) {
+        if (!sameSnapshot(file.stats, await capturedStats(file.path)))
+            throw new Error("workflow-source-changed");
+    }
+    return { captured, codes };
+}
+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,
+    ]);
+    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,
+        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;
+}