cloving 1.1.0 → 1.3.0

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

@@ -0,0 +1,106 @@
+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)
+        return symbol;
+    return checker.getAliasedSymbol(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),
+    ]));
+    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({ 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");
+    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,
+        sources: [...sources.keys()].map((name) => {
+            const entry = program.getSourceFile(name);
+            if (!entry)
+                throw new Error("candidate-analysis-unavailable");
+            return entry;
+        }),
+    };
+}
+function trustedHost(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 (sources.has(file))
+            return sources.get(file);
+        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 (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-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,169 @@
+import ts from "typescript";
+import { dirname, relative, sep } from "node:path";
+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";
+import { helperEffectTotals } from "./workflow-candidate-helper-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)
+            : [],
+    };
+}
+function mergeHelpers(modules, checker) {
+    return [
+        ["merge-when-green", "mergeWhenGreen"],
+        ["merge-by-person", "mergeByPerson"],
+    ].flatMap(([module, name]) => {
+        const symbol = protectedHelper(modules, {
+            checker,
+            subpath: `cloving/workflows/steps/${String(module)}`,
+            name: String(name),
+        });
+        return symbol === undefined ? [] : [symbol];
+    });
+}
+export function analyzeWorkflowCandidate(text, installed = {}) {
+    const { program, source, sources, 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",
+        }),
+        commandSymbol: protectedHelper(modules, {
+            checker,
+            subpath: "cloving/workflows/steps/run-command",
+            name: "runCommand",
+        }),
+        reviewSymbol: protectedHelper(modules, {
+            checker,
+            subpath: "cloving/workflows/steps/review-by-agent",
+            name: "reviewByAgent",
+        }),
+        mergeSymbols: mergeHelpers(modules, checker),
+    };
+    const facts = sources.map((entry) => analyzedSource({ ...symbols, source: entry }, { program, workflow: source }));
+    return {
+        analysis: combineFacts({
+            localSources: Object.keys(installed.helpers ?? {}),
+            facts,
+            expanded: helperEffectTotals({
+                symbols: { ...symbols, source },
+                sources,
+            }),
+        }),
+        installedExports: exportSnapshot(modules, checker),
+    };
+}
+function analyzedSource(symbols, input) {
+    const { source } = symbols;
+    const facts = sourceFacts(symbols);
+    const kind = source === input.workflow ? "workflow" : "helper";
+    const path = relative(dirname(input.workflow.fileName), source.fileName)
+        .split(sep)
+        .join("/");
+    const invalid = source.referencedFiles.length > 0 ||
+        source.typeReferenceDirectives.length > 0 ||
+        source.libReferenceDirectives.length > 0 ||
+        input.program.getSyntacticDiagnostics(source).length > 0;
+    return {
+        ...facts,
+        imports: facts.imports.map((entry) => kind === "workflow" ? entry : { ...entry, source: path }),
+        unsupportedForms: [
+            ...facts.unsupportedForms,
+            ...(invalid || (kind === "workflow" && !workflowShape(source))
+                ? ["workflow-shape"]
+                : []),
+            ...(facts.directEffects.length === 0 &&
+                !passiveCandidateModule(source, kind)
+                ? ["module-initialization"]
+                : []),
+        ],
+    };
+}
+function combineFacts(input) {
+    const { localSources, facts } = input;
+    return {
+        localSources,
+        imports: facts.flatMap((entry) => entry.imports),
+        effects: facts.flatMap((entry) => entry.effects),
+        directEffects: facts.flatMap((entry) => entry.directEffects),
+        unsupportedForms: [
+            ...facts.flatMap((entry) => entry.unsupportedForms),
+            ...input.expanded.unsupportedForms,
+        ],
+        knownCallCount: input.expanded.totals?.knownCallCount ??
+            facts.reduce((total, entry) => total + entry.knownCallCount, 0),
+        knownUnitTotal: input.expanded.totals?.knownUnitTotal ??
+            facts.reduce((total, entry) => total + entry.knownUnitTotal, 0),
+    };
+}

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

@@ -0,0 +1,21 @@
+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;
+    readonly commandSymbol: ts.Symbol | undefined;
+    readonly reviewSymbol: ts.Symbol | undefined;
+    readonly mergeSymbols: readonly ts.Symbol[];
+}
+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 commandCall(node: ts.CallExpression, symbols: CandidateSymbols): boolean;
+export declare function reviewCall(node: ts.CallExpression, symbols: CandidateSymbols): boolean;
+export declare function helperCall(node: ts.CallExpression, symbols: CandidateSymbols): boolean;
+export declare function mergeCall(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, kind?: "workflow" | "helper"): boolean;

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

@@ -0,0 +1,263 @@
+import ts from "typescript";
+import { resolvedSymbol } from "./workflow-candidate-program.js";
+import { referenceSymbol } from "./workflow-source-effects.js";
+import { invalidFields, literalField, propertyInitializer, } from "./workflow-candidate-fields.js";
+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,
+            symbols.commandSymbol,
+            symbols.reviewSymbol,
+            ...symbols.mergeSymbols,
+        ].includes(symbol));
+}
+function calledSymbol(node, symbols) {
+    return resolvedSymbol(symbols.checker, symbols.checker.getSymbolAtLocation(node.expression));
+}
+export function handoffCall(node, symbols) {
+    const symbol = symbols.handoffSymbol;
+    return symbol !== undefined && calledSymbol(node, symbols) === symbol;
+}
+export function commandCall(node, symbols) {
+    const symbol = symbols.commandSymbol;
+    return symbol !== undefined && calledSymbol(node, symbols) === symbol;
+}
+export function reviewCall(node, symbols) {
+    const symbol = symbols.reviewSymbol;
+    return symbol !== undefined && calledSymbol(node, symbols) === symbol;
+}
+export function helperCall(node, symbols) {
+    return [handoffCall, commandCall, reviewCall, mergeCall].some((call) => call(node, symbols));
+}
+export function mergeCall(node, symbols) {
+    const symbol = calledSymbol(node, symbols);
+    return symbol !== undefined && symbols.mergeSymbols.includes(symbol);
+}
+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;
+    if (reviewCall(node, symbols))
+        return reviewEffectFact(propertyInitializer(argument, "reviewer"));
+    if (mergeCall(node, symbols))
+        return { capability: "github", method: "merge" };
+    if (commandCall(node, symbols)) {
+        const name = literalField(argument, "name");
+        return {
+            capability: "command",
+            method: name === null ? null : `run:${name}`,
+        };
+    }
+    return {
+        capability: literalField(argument, "capability"),
+        method: literalField(argument, "method"),
+    };
+}
+function reviewEffectFact(reviewer) {
+    const kind = literalField(reviewer, "kind");
+    if (kind === "greptile")
+        return { capability: "github", method: "wait-review" };
+    const profile = literalField(reviewer, "profile");
+    if (kind === "turn" &&
+        profile !== null &&
+        /^[A-Za-z0-9_-]{1,119}$/.test(profile))
+        return { capability: "claude", method: `run-turn:${profile}` };
+    return { capability: null, method: null };
+}
+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,
+            symbols.commandSymbol,
+            symbols.reviewSymbol,
+            ...symbols.mergeSymbols,
+        ].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 reviewer = reviewCall(node, symbols)
+        ? propertyInitializer(argument, "reviewer")
+        : undefined;
+    return (invalidFields(argument) ||
+        (reviewer !== undefined &&
+            ts.isObjectLiteralExpression(reviewer) &&
+            invalidFields(reviewer)));
+}
+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, kind) {
+    if (ts.isVariableStatement(node))
+        return ((node.declarationList.flags & ts.NodeFlags.Const) !== 0 &&
+            node.declarationList.declarations.every((declaration) => (kind === "helper" ||
+                (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, kind = "workflow") {
+    return source.statements.every((node) => passiveStatement(node, kind));
+}

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

@@ -0,0 +1 @@
+export declare function workflowCommand(argumentsList: readonly string[]): Promise<number>;