cloving 1.2.0 → 1.4.0

package/dist/tools/template-copy.js

@@ -0,0 +1,130 @@
+import { link, mkdir, mkdtemp, readFile, rm, writeFile, } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import ts from "typescript";
+import { record } from "../src/protocol.js";
+import { readTemplate, templateName } from "./template-files.js";
+export async function copyTemplate(input) {
+    if (!templateName.test(input.id) || input.id.length > 64)
+        throw new Error(`invalid-workflow-id: ${input.id}`);
+    const template = await readTemplate(input.root, input.name);
+    const sources = await Promise.all(template.files.map(async (file) => ({
+        file,
+        text: await readFile(join(input.root, input.name, file), "utf8"),
+    })));
+    const renaming = functionRenaming(sources, input);
+    const plan = sources.map(({ file, text }) => ({
+        target: input.id + file.slice(input.name.length),
+        content: copiedContent({ file, text }, renaming),
+    }));
+    await writePlan(input.folder, plan);
+    return { template, files: plan.map((item) => item.target) };
+}
+function camelName(id) {
+    return id.replace(/-([a-z0-9])/g, (_, letter) => letter.toUpperCase());
+}
+function functionRenaming(sources, input) {
+    const from = camelName(input.name);
+    const names = new Set(sources
+        .filter(({ file }) => file.endsWith(".ts"))
+        .flatMap(({ text }) => text.match(/[A-Za-z_$][\w$]*/g) ?? []));
+    for (const name of input.takenNames)
+        names.add(name);
+    let to = camelName(input.id);
+    while (to !== from && (names.has(to) || reservedWord(to)))
+        to += "Workflow";
+    return { template: input.name, id: input.id, from, to };
+}
+function reservedWord(name) {
+    const scanner = ts.createScanner(ts.ScriptTarget.Latest, true);
+    scanner.setText(name);
+    const kind = scanner.scan();
+    return ((kind >= ts.SyntaxKind.FirstReservedWord &&
+        kind <= ts.SyntaxKind.LastFutureReservedWord) ||
+        ["await", "eval", "arguments"].includes(name));
+}
+function copiedContent(source, renaming) {
+    const { file, text } = source;
+    if (file.endsWith(".declaration.json"))
+        return copiedDeclaration(text, renaming);
+    if (!file.endsWith(".ts") || renaming.id === renaming.template)
+        return text;
+    return renamedSource(source, renaming);
+}
+function copiedDeclaration(text, renaming) {
+    const declaration = record(JSON.parse(text));
+    const workflow = record(declaration?.["workflow"]);
+    if (declaration === undefined || workflow === undefined)
+        throw new Error(`invalid-template: ${renaming.template}`);
+    return (JSON.stringify({
+        template: renaming.template,
+        ...declaration,
+        workflow: { ...workflow, workflowId: renaming.id },
+    }, null, 2) + "\n");
+}
+function renamedSource(input, renaming) {
+    const { file, text } = input;
+    const source = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true);
+    const edits = [];
+    const prefix = new RegExp(`^(\\.\\.?/)${renaming.template}(?=[./])`);
+    const visit = (node) => {
+        if (ts.isIdentifier(node) && node.text === renaming.from)
+            edits.push({ start: node.getStart(), end: node.end, text: renaming.to });
+        if (ts.isStringLiteral(node) &&
+            (ts.isImportDeclaration(node.parent) ||
+                ts.isExportDeclaration(node.parent)) &&
+            prefix.test(node.text))
+            edits.push({
+                start: node.getStart() + 1,
+                end: node.end - 1,
+                text: node.text.replace(prefix, `$1${renaming.id}`),
+            });
+        ts.forEachChild(node, visit);
+    };
+    visit(source);
+    return edits
+        .sort((left, right) => right.start - left.start)
+        .reduce((current, edit) => current.slice(0, edit.start) + edit.text + current.slice(edit.end), text);
+}
+async function writePlan(folder, plan) {
+    await mkdir(folder, { recursive: true });
+    const staging = await mkdtemp(join(dirname(folder), ".template-copy-"));
+    const created = [];
+    try {
+        for (const item of plan) {
+            await mkdir(dirname(join(staging, item.target)), { recursive: true });
+            await writeFile(join(staging, item.target), item.content);
+        }
+        for (const item of plan)
+            await placed({ folder, staging, item }, created);
+    }
+    catch (error) {
+        for (const path of created.reverse())
+            await rm(path, { recursive: true, force: true });
+        throw error;
+    }
+    finally {
+        await rm(staging, { recursive: true, force: true });
+    }
+}
+async function placed(input, created) {
+    const parts = input.item.target.split("/");
+    for (let depth = 1; depth < parts.length; depth += 1) {
+        const directory = join(input.folder, ...parts.slice(0, depth));
+        if (created.includes(directory))
+            continue;
+        await mkdir(directory).catch((error) => {
+            throw present(error, parts.slice(0, depth).join("/"));
+        });
+        created.push(directory);
+    }
+    const target = join(input.folder, input.item.target);
+    await link(join(input.staging, input.item.target), target).catch((error) => {
+        throw present(error, input.item.target);
+    });
+    created.push(target);
+}
+function present(error, target) {
+    return error instanceof Error && "code" in error && error.code === "EEXIST"
+        ? new Error(`workflow-exists: ${target}`)
+        : error;
+}

package/dist/tools/template-files.d.ts

@@ -0,0 +1,17 @@
+import { type Fields } from "../src/protocol.ts";
+export interface TemplateSummary {
+    readonly name: string;
+    readonly summary: string;
+    readonly points: number;
+}
+export interface Template {
+    readonly name: string;
+    readonly description: Fields;
+    readonly points: readonly unknown[];
+    readonly files: readonly string[];
+}
+export declare const templateName: RegExp;
+export declare function templateRoot(start?: string): string;
+export declare function templateList(root: string): Promise<readonly TemplateSummary[]>;
+export declare function readTemplate(root: string, name: string): Promise<Template>;
+export declare function exportedFunctions(folders: readonly string[]): Promise<ReadonlySet<string>>;

package/dist/tools/template-files.js

@@ -0,0 +1,74 @@
+import { existsSync } from "node:fs";
+import { readdir, readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { record } from "../src/protocol.js";
+export const templateName = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+const descriptionFiles = ["template.json", "README.md"];
+export function templateRoot(start = import.meta.dirname) {
+    let directory = start;
+    while (!existsSync(join(directory, "package.json"))) {
+        const parent = dirname(directory);
+        if (parent === directory)
+            throw new Error("templates-not-found");
+        directory = parent;
+    }
+    return join(directory, "templates");
+}
+export async function templateList(root) {
+    const entries = await readdir(root, { withFileTypes: true });
+    const names = entries
+        .filter((entry) => entry.isDirectory() && templateName.test(entry.name))
+        .map((entry) => entry.name)
+        .sort();
+    const templates = await Promise.all(names.map((name) => readTemplate(root, name).catch(() => undefined)));
+    return templates.flatMap((template) => template === undefined
+        ? []
+        : [
+            {
+                name: template.name,
+                summary: String(template.description["summary"]),
+                points: template.points.length,
+            },
+        ]);
+}
+export async function readTemplate(root, name) {
+    if (!templateName.test(name))
+        throw new Error(`unknown-template: ${name}`);
+    const folder = join(root, name);
+    const text = await readFile(join(folder, "template.json"), "utf8").catch(() => {
+        throw new Error(`unknown-template: ${name}`);
+    });
+    const description = record(JSON.parse(text));
+    const points = description?.["points"];
+    if (description === undefined ||
+        typeof description["summary"] !== "string" ||
+        !Array.isArray(points))
+        throw new Error(`invalid-template: ${name}`);
+    return { name, description, points, files: await workflowFiles(folder) };
+}
+export async function exportedFunctions(folders) {
+    const names = new Set();
+    for (const folder of folders) {
+        const files = await readdir(folder).catch(() => []);
+        for (const file of files.filter((name) => /^[^.].*(?<!\.test|\.d)\.[jt]s$/.test(name))) {
+            const text = await readFile(join(folder, file), "utf8").catch(() => "");
+            for (const match of text.matchAll(/export\s+(?:async\s+)?function\s*\*?\s*([A-Za-z_$][\w$]*)/g))
+                names.add(String(match[1]));
+        }
+    }
+    return names;
+}
+async function workflowFiles(folder) {
+    const entries = await readdir(folder, {
+        recursive: true,
+        withFileTypes: true,
+    });
+    return entries
+        .filter((entry) => entry.isFile())
+        .map((entry) => join(entry.parentPath, entry.name)
+        .slice(folder.length + 1)
+        .split("\\")
+        .join("/"))
+        .filter((file) => !descriptionFiles.includes(file))
+        .sort();
+}

package/dist/tools/workflow-bundles.js

@@ -153,6 +153,7 @@ export async function retainWorkflowBundle(input) {
     }
     const temporary = await mkdtemp(join(input.directory, ".pending-"));
     try {
+        await mkdir(join(temporary, "workflows"), { mode: 0o700 });
         for (const { name, bytes } of files) {
             const path = join(temporary, name);
             await mkdir(dirname(path), { recursive: true, mode: 0o700 });

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

@@ -1,8 +1,12 @@
 import ts from "typescript";
 import { type CandidateSymbols } from "./workflow-candidate-syntax.ts";
-interface Totals {
+export interface Totals {
     readonly knownCallCount: number;
     readonly knownUnitTotal: number;
 }
-export declare function candidateEffectTotals(source: ts.SourceFile, symbols: CandidateSymbols): Totals;
+interface CountSymbols extends CandidateSymbols {
+    readonly localTotals?: (node: ts.Node) => Totals | undefined;
+}
+export declare function candidateEffectTotals(source: ts.Node, symbols: CountSymbols): Totals;
+export declare function candidateLoopRepetitions(node: ts.IterationStatement, symbols: CandidateSymbols): number | undefined;
 export {};

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

@@ -1,5 +1,6 @@
 import ts from "typescript";
-import { protectedCall, handoffCall, propertyName, } from "./workflow-candidate-syntax.js";
+import { protectedCall, commandWaitCall, helperCall, } from "./workflow-candidate-syntax.js";
+import { propertyName } from "./workflow-candidate-fields.js";
 import { referenceSymbol } from "./workflow-source-effects.js";
 const zero = { knownCallCount: 0, knownUnitTotal: 0 };
 function add(first, second) {
@@ -21,7 +22,7 @@ function multiply(total, repetitions) {
     };
 }
 function units(node, symbols) {
-    if (handoffCall(node, symbols))
+    if (helperCall(node, symbols))
         return 1;
     const argument = node.arguments[0];
     if (!argument || !ts.isObjectLiteralExpression(argument))
@@ -29,10 +30,8 @@ function units(node, symbols) {
     const property = argument.properties.find((entry) => entry.name && propertyName(entry.name) === "units");
     if (!property || !ts.isPropertyAssignment(property))
         return 0;
-    const value = constantNumber(property.initializer);
-    return value !== undefined && Number.isSafeInteger(value) && value > 0
-        ? value
-        : 0;
+    const value = Number(constantNumber(property.initializer));
+    return Number.isSafeInteger(value) && value > 0 ? value : 0;
 }
 function loopIncrement(node, variable) {
     if ((ts.isPostfixUnaryExpression(node) || ts.isPrefixUnaryExpression(node)) &&
@@ -210,19 +209,35 @@ export function candidateEffectTotals(source, symbols) {
             return add(count(node.expression), multiply(add(count(node.initializer), count(node.statement)), arrayIterations(node, symbols)));
         if (ts.isSwitchStatement(node))
             return add(count(node.expression), switchTotals(node.caseBlock, count));
-        let total = protectedCall(node, symbols)
-            ? {
-                knownCallCount: 1,
-                knownUnitTotal: units(node, symbols),
-            }
-            : zero;
-        ts.forEachChild(node, (child) => {
-            total = add(total, count(child));
-        });
-        return total;
+        return nodeTotals(node, { symbols, count });
     }
     return count(source);
 }
+function nodeTotals(node, input) {
+    const local = input.symbols.localTotals?.(node);
+    if (local && ts.isFunctionLike(node))
+        return local;
+    let total = local ??
+        (protectedCall(node, input.symbols) && !commandWaitCall(node, input.symbols)
+            ? { knownCallCount: 1, knownUnitTotal: units(node, input.symbols) }
+            : zero);
+    ts.forEachChild(node, (child) => {
+        total = add(total, input.count(child));
+    });
+    return total;
+}
+export function candidateLoopRepetitions(node, symbols) {
+    if (ts.isForStatement(node))
+        return loopIterations(node, symbols);
+    if (ts.isForOfStatement(node) &&
+        ts.isArrayLiteralExpression(node.expression) &&
+        !uncertainLoopBody(node.statement, {
+            checker: symbols.checker,
+            counter: undefined,
+        }))
+        return node.expression.elements.length;
+    return undefined;
+}
 function arrayIterations(node, symbols) {
     if (!ts.isArrayLiteralExpression(node.expression))
         return 1;

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

@@ -0,0 +1,5 @@
+import ts from "typescript";
+export declare function propertyName(name: ts.PropertyName): string | undefined;
+export declare function propertyInitializer(node: ts.Node | undefined, field: string): ts.Expression | undefined;
+export declare function literalField(node: ts.Node | undefined, field: string): string | null;
+export declare function invalidFields(object: ts.ObjectLiteralExpression): boolean;

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

@@ -0,0 +1,24 @@
+import ts from "typescript";
+export function propertyName(name) {
+    if (ts.isIdentifier(name) || ts.isStringLiteral(name))
+        return name.text;
+    return undefined;
+}
+export function propertyInitializer(node, field) {
+    if (!node || !ts.isObjectLiteralExpression(node))
+        return undefined;
+    const property = node.properties.find((entry) => entry.name && propertyName(entry.name) === field);
+    return property && ts.isPropertyAssignment(property)
+        ? property.initializer
+        : undefined;
+}
+export function literalField(node, field) {
+    const value = propertyInitializer(node, field);
+    return value && ts.isStringLiteral(value) ? value.text : null;
+}
+export function invalidFields(object) {
+    const names = object.properties.map((entry) => entry.name && propertyName(entry.name));
+    return (names.includes(undefined) ||
+        new Set(names).size !== names.length ||
+        object.properties.some((entry) => !ts.isPropertyAssignment(entry)));
+}

package/dist/tools/workflow-candidate-helper-counts.d.ts

@@ -0,0 +1,10 @@
+import ts from "typescript";
+import { type Totals } from "./workflow-candidate-counts.ts";
+import { type CandidateSymbols } from "./workflow-candidate-syntax.ts";
+export declare function helperEffectTotals(input: {
+    readonly symbols: CandidateSymbols;
+    readonly sources: readonly ts.SourceFile[];
+}): {
+    readonly totals?: Totals;
+    readonly unsupportedForms: readonly string[];
+};

package/dist/tools/workflow-candidate-helper-counts.js

@@ -0,0 +1,129 @@
+import ts from "typescript";
+import { candidateEffectTotals, candidateLoopRepetitions, } from "./workflow-candidate-counts.js";
+import { protectedCall, } from "./workflow-candidate-syntax.js";
+import { resolvedSymbol } from "./workflow-candidate-program.js";
+import { referenceSymbol, typeOnlyEffectNode, } from "./workflow-source-effects.js";
+const zero = { knownCallCount: 0, knownUnitTotal: 0 };
+export function helperEffectTotals(input) {
+    const { symbols, sources } = input;
+    const unsupportedForms = [];
+    if (sources.length === 1)
+        return { unsupportedForms };
+    const active = new Set();
+    const totals = new Map();
+    const functions = localFunctions(sources);
+    const functionAt = (node) => localFunctionAt(node, { checker: symbols.checker, functions });
+    function count(declaration) {
+        const cached = totals.get(declaration);
+        if (cached)
+            return cached;
+        if (active.has(declaration)) {
+            unsupportedForms.push("recursive-helper-effects");
+            return zero;
+        }
+        active.add(declaration);
+        const result = candidateEffectTotals(declaration, {
+            ...symbols,
+            localTotals: (node) => {
+                if (ts.isFunctionLike(node) && node !== declaration)
+                    return zero;
+                if (!ts.isCallExpression(node) || !ts.isIdentifier(node.expression))
+                    return undefined;
+                const called = functionAt(node.expression);
+                return called && effectful.has(called) ? count(called) : undefined;
+            },
+        });
+        active.delete(declaration);
+        totals.set(declaration, result);
+        return result;
+    }
+    const effectful = effectfulFunctions({ functions, functionAt, symbols });
+    if ([...effectful].every((entry) => entry.getSourceFile() === symbols.source))
+        return { unsupportedForms };
+    for (const source of sources)
+        inspectHelperReferences(source, {
+            functionAt,
+            effectful,
+            symbols,
+            unsupportedForms,
+        });
+    for (const declaration of effectful)
+        count(declaration);
+    const workflow = [...functions].find((entry) => entry.getSourceFile() === symbols.source &&
+        (ts.getCombinedModifierFlags(entry) & ts.ModifierFlags.Export) !== 0);
+    return { totals: workflow ? count(workflow) : zero, unsupportedForms };
+}
+function localFunctions(sources) {
+    return new Set(sources.flatMap((source) => source.statements.filter((node) => ts.isFunctionDeclaration(node) && node.body !== undefined)));
+}
+function localFunctionAt(node, input) {
+    const symbol = resolvedSymbol(input.checker, referenceSymbol(node, {
+        parent: node.parent,
+        checker: input.checker,
+    }));
+    return symbol?.declarations?.find((entry) => ts.isFunctionDeclaration(entry) && input.functions.has(entry));
+}
+function effectfulFunctions(input) {
+    const effectful = new Set();
+    const calls = (node) => {
+        if (typeOnlyEffectNode(node))
+            return false;
+        if (protectedCall(node, input.symbols))
+            return true;
+        const called = ts.isIdentifier(node) ? input.functionAt(node) : undefined;
+        if (called && effectful.has(called))
+            return true;
+        return ts.forEachChild(node, (child) => calls(child) || undefined) ?? false;
+    };
+    let previous = -1;
+    while (previous !== effectful.size) {
+        previous = effectful.size;
+        for (const declaration of input.functions)
+            if (calls(declaration))
+                effectful.add(declaration);
+    }
+    return effectful;
+}
+function inspectHelperReferences(source, input) {
+    function visit(node) {
+        if (typeOnlyEffectNode(node))
+            return;
+        if (source !== input.symbols.source &&
+            protectedCall(node, input.symbols) &&
+            !checkedHelperContext(node, input.symbols))
+            input.unsupportedForms.push("uncheckable-helper-effects");
+        const declaration = ts.isIdentifier(node)
+            ? input.functionAt(node)
+            : undefined;
+        if (declaration &&
+            input.effectful.has(declaration) &&
+            ts.isIdentifier(node) &&
+            !checkedHelperReference(node, input.symbols))
+            input.unsupportedForms.push("uncheckable-helper-effects");
+        ts.forEachChild(node, visit);
+    }
+    visit(source);
+}
+function checkedHelperReference(node, symbols) {
+    if (ts.isFunctionDeclaration(node.parent) && node.parent.name === node)
+        return true;
+    if (ts.isImportSpecifier(node.parent))
+        return true;
+    if (!ts.isCallExpression(node.parent) ||
+        node.parent.expression !== node ||
+        node.parent.questionDotToken !== undefined)
+        return false;
+    return checkedHelperContext(node.parent, symbols);
+}
+function checkedHelperContext(node, symbols) {
+    let parent = node;
+    while (!ts.isFunctionLike(parent)) {
+        if (ts.isSourceFile(parent))
+            return false;
+        if (ts.isIterationStatement(parent, false) &&
+            candidateLoopRepetitions(parent, symbols) === undefined)
+            return false;
+        parent = parent.parent;
+    }
+    return ts.isFunctionDeclaration(parent) && ts.isSourceFile(parent.parent);
+}

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

@@ -2,10 +2,12 @@ import ts from "typescript";
 export declare const candidatePackageRoot: string;
 export interface CandidatePackageOptions {
     readonly packageRoot?: string;
+    readonly helpers?: Readonly<Record<string, 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 sources: readonly ts.SourceFile[];
     readonly modules: ReadonlyMap<string, ts.SourceFile>;
 };

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

@@ -2,6 +2,7 @@ import { dirname, join, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import ts from "typescript";
 import metadata from "#package" with { type: "json" };
+import { workflowHelperPath } from "../src/workflow-candidate.js";
 export const candidatePackageRoot = dirname(fileURLToPath(import.meta.resolve("#package")));
 export function resolvedSymbol(checker, symbol) {
     if (!symbol || (symbol.flags & ts.SymbolFlags.Alias) === 0)
@@ -11,6 +12,12 @@ export function resolvedSymbol(checker, symbol) {
 export function candidateProgram(text, installed = {}) {
     const packageRoot = resolve(installed.packageRoot ?? candidatePackageRoot);
     const candidate = join(packageRoot, "candidate.ts");
+    const sources = new Map([[candidate, text]]);
+    for (const [name, content] of Object.entries(installed.helpers ?? {})) {
+        if (workflowHelperPath("candidate.ts", `./${name}`) !== name)
+            throw new Error("invalid-workflow-helper");
+        sources.set(join(packageRoot, name), content);
+    }
     const entries = new Map(Object.entries(metadata.exports).map(([name, entry]) => [
         `cloving${name.slice(1)}`,
         resolve(packageRoot, entry.types),
@@ -24,8 +31,8 @@ export function candidateProgram(text, installed = {}) {
         strict: true,
         noEmit: true,
     };
-    const host = trustedHost({ candidate, text, options, entries, packageRoot });
-    const program = ts.createProgram([candidate, ...entries.values()], options, host);
+    const host = trustedHost({ sources, options, entries, packageRoot });
+    const program = ts.createProgram([...sources.keys(), ...entries.values()], options, host);
     const source = program.getSourceFile(candidate);
     if (!source)
         throw new Error("candidate-analysis-unavailable");
@@ -36,15 +43,25 @@ export function candidateProgram(text, installed = {}) {
             throw new Error("candidate-surface-unavailable");
         modules.set(name, declaration);
     }
-    return { program, source, modules };
+    return {
+        program,
+        source,
+        modules,
+        sources: [...sources.keys()].map((name) => {
+            const entry = program.getSourceFile(name);
+            if (!entry)
+                throw new Error("candidate-analysis-unavailable");
+            return entry;
+        }),
+    };
 }
 function trustedHost(input) {
-    const { candidate, text, options, entries, packageRoot } = input;
+    const { sources, 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;
+        if (sources.has(file))
+            return sources.get(file);
         const absolute = resolve(file);
         if (!absolute.endsWith(".d.ts"))
             return undefined;
@@ -70,8 +87,19 @@ function trustedHost(input) {
                     extension: ts.Extension.Dts,
                 },
             };
-        if (containingFile === candidate)
-            return { resolvedModule: undefined };
+        if (sources.has(containingFile)) {
+            const importer = containingFile
+                .slice(packageRoot.length + 1)
+                .split(sep)
+                .join("/");
+            const local = workflowHelperPath(importer, name);
+            const target = local && join(packageRoot, local);
+            return {
+                resolvedModule: target && sources.has(target)
+                    ? { resolvedFileName: target, extension: ts.Extension.Ts }
+                    : undefined,
+            };
+        }
         return ts.resolveModuleName(name, containingFile, options, host);
     });
     return host;

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

@@ -0,0 +1,3 @@
+import ts from "typescript";
+export declare function workflowShape(source: ts.SourceFile): boolean;
+export declare function passiveCandidateModule(source: ts.SourceFile, kind?: "workflow" | "helper"): boolean;