ts2workflows 0.1.0

package/dist/ast/validation.js

@@ -0,0 +1,214 @@
+export class WorkflowValidationError extends Error {
+    issues;
+    constructor(issues) {
+        const issueTypes = Array.from(new Set(issues.map((x) => x.type))).join(', ');
+        super(`Workflow validation error: ${issueTypes}`);
+        this.name = this.constructor.name;
+        this.issues = issues;
+    }
+}
+const validators = new Map([
+    ['invalidWorkflowName', validateWorkflowNames],
+    ['duplicatedStepName', validateNoDuplicateStepNames],
+    ['duplicatedSubworkflowName', validateNoDuplicateSubworkflowNames],
+    ['missingJumpTarget', validateJumpTargets],
+    ['wrongNumberOfCallArguments', validateSubworkflowArguments],
+]);
+/**
+ * Execute all syntax validators on a WorkflowApp app.
+ *
+ * Throws a WorkflowValidationError if there are errors.
+ */
+export function validate(app, disabled = []) {
+    const selectedValidators = Array.from(validators.entries()).filter(([name]) => {
+        return !disabled.includes(name);
+    });
+    const issues = [];
+    for (const [, validator] of selectedValidators) {
+        issues.push(...validator(app));
+    }
+    if (issues.length > 0) {
+        throw new WorkflowValidationError(issues);
+    }
+}
+/**
+ * Returns all validator names.
+ */
+export function validatorNames() {
+    return Array.from(validators.keys());
+}
+/**
+ * Check that workflow does not contain duplicated step names.
+ */
+function validateNoDuplicateStepNames(app) {
+    function collectDuplicateStepName(wf) {
+        const seen = new Set();
+        const duplicates = new Set();
+        for (const { name } of wf.iterateStepsDepthFirst()) {
+            if (seen.has(name)) {
+                duplicates.add(name);
+            }
+            else {
+                seen.add(name);
+            }
+        }
+        return Array.from(duplicates.values());
+    }
+    const issues = [];
+    for (const subworkflow of app.subworkflows) {
+        const duplicatesInSub = collectDuplicateStepName(subworkflow);
+        if (duplicatesInSub.length > 0) {
+            const message = `Duplicated step names in the subworkflow ${subworkflow.name}: ${duplicatesInSub.join(', ')}`;
+            issues.push({ type: 'duplicatedStepName', message: message });
+        }
+    }
+    return issues;
+}
+/**
+ * Check that there are no two subworkflows sharing a name.
+ */
+function validateNoDuplicateSubworkflowNames(app) {
+    const seen = new Set();
+    const duplicates = new Set();
+    const names = app.subworkflows.map((w) => w.name);
+    for (const name of names) {
+        if (seen.has(name)) {
+            duplicates.add(name);
+        }
+        else {
+            seen.add(name);
+        }
+    }
+    if (duplicates.size > 0) {
+        const dup = Array.from(duplicates);
+        return [
+            {
+                type: 'duplicatedSubworkflowName',
+                message: `Duplicated subworkflow names: ${dup.join(', ')}`,
+            },
+        ];
+    }
+    else {
+        return [];
+    }
+}
+/**
+ * Check that the subworkflow names are valid.
+ */
+function validateWorkflowNames(app) {
+    const issues = [];
+    const names = app.subworkflows.map((w) => w.name);
+    if (names.some((x) => x === '')) {
+        issues.push({
+            type: 'invalidWorkflowName',
+            message: 'Subworkflow must have a non-empty name',
+        });
+    }
+    return issues;
+}
+/**
+ * Check that there are no jumps (calls, nexts) to non-existing steps or subworkflows
+ */
+function validateJumpTargets(app) {
+    const subworkflowNames = app.subworkflows.map((w) => w.name);
+    return app.subworkflows.flatMap((subworkflow) => {
+        return validateJumpTargetsInWorkflow(subworkflow, subworkflowNames);
+    });
+}
+function validateJumpTargetsInWorkflow(workflow, subworkflowNames) {
+    const issues = [];
+    const stepNames = [];
+    for (const { name } of workflow.iterateStepsDepthFirst()) {
+        stepNames.push(name);
+    }
+    function validCallTarget(name) {
+        return (isRuntimeFunction(name) ||
+            stepNames.includes(name) ||
+            subworkflowNames.includes(name));
+    }
+    function validNextTarget(name) {
+        return stepNames.includes(name) || name === 'end'; // accepts "next: end"
+    }
+    for (const { name, step } of workflow.iterateStepsDepthFirst()) {
+        if (step.tag === 'call') {
+            if (!validCallTarget(step.call))
+                issues.push({
+                    type: 'missingJumpTarget',
+                    message: `Call target "${step.call}" in step "${name}" not found`,
+                });
+        }
+        else if (step.tag === 'switch') {
+            if (step.next && !validNextTarget(step.next)) {
+                issues.push({
+                    type: 'missingJumpTarget',
+                    message: `Next target "${step.next}" in step "${name}" not found`,
+                });
+            }
+            step.conditions.forEach((cond) => {
+                if (cond.next && !validNextTarget(cond.next)) {
+                    issues.push({
+                        type: 'missingJumpTarget',
+                        message: `Next target "${cond.next}" in step "${name}" not found`,
+                    });
+                }
+            });
+        }
+    }
+    return issues;
+}
+/**
+ * Check that call steps provide a correct number of argument in subworkflow calls
+ */
+function validateSubworkflowArguments(app) {
+    const issues = [];
+    const paramsBySubworkflow = new Map(app.subworkflows.map((x) => [
+        x.name,
+        {
+            required: x.params
+                ?.filter((x) => typeof x.default === 'undefined')
+                .map((x) => x.name) ?? [],
+            optional: x.params
+                ?.filter((x) => typeof x.default !== 'undefined')
+                .map((x) => x.name) ?? [],
+        },
+    ]));
+    app.subworkflows.forEach((subw) => {
+        issues.push(...findIssuesInCallArguments(subw, paramsBySubworkflow));
+    });
+    return issues;
+}
+function findIssuesInCallArguments(wf, argumentBySubworkflowName) {
+    const issues = [];
+    for (const { name, step } of wf.iterateStepsDepthFirst()) {
+        if (step.tag === 'call' && argumentBySubworkflowName.has(step.call)) {
+            const requiredArgs = argumentBySubworkflowName.get(step.call)?.required ?? [];
+            const optionalArgs = argumentBySubworkflowName.get(step.call)?.optional ?? [];
+            const requiredAndOptionalArgs = requiredArgs.concat(optionalArgs);
+            const providedArgs = Object.keys(step.args ?? {});
+            const requiredButNotProvided = requiredArgs.filter((x) => !providedArgs.includes(x));
+            const providedButNotRequired = providedArgs.filter((x) => !requiredAndOptionalArgs.includes(x));
+            if (requiredButNotProvided.length > 0) {
+                issues.push({
+                    type: 'wrongNumberOfCallArguments',
+                    message: `Required parameters not provided on call step "${name}": ${JSON.stringify(requiredButNotProvided)}`,
+                });
+            }
+            if (providedButNotRequired.length > 0) {
+                issues.push({
+                    type: 'wrongNumberOfCallArguments',
+                    message: `Extra arguments provided on call step "${name}": ${JSON.stringify(providedButNotRequired)}`,
+                });
+            }
+        }
+    }
+    return issues;
+}
+/**
+ * Returns true if functionName is a standard library or connector function.
+ *
+ * Current version does a minimalistic checking and assumes that a name is a
+ * standard library function if it contains a dot.
+ */
+function isRuntimeFunction(functionName) {
+    return functionName.includes('.');
+}

package/dist/ast/workflows.d.ts

@@ -0,0 +1,28 @@
+import { VariableName, LiteralValueOrLiteralExpression } from './expressions.js';
+import { NamedWorkflowStep } from './steps.js';
+export interface WorkflowParameter {
+    name: VariableName;
+    default?: LiteralValueOrLiteralExpression;
+}
+/**
+ * This is the main container class that brings together all subworkflows in a program
+ */
+export declare class WorkflowApp {
+    readonly subworkflows: Subworkflow[];
+    constructor(subworkflows?: Subworkflow[]);
+    render(): Record<string, unknown>;
+}
+export declare class Subworkflow {
+    readonly name: string;
+    readonly steps: NamedWorkflowStep[];
+    readonly params?: WorkflowParameter[];
+    constructor(name: string, steps: NamedWorkflowStep[], params?: WorkflowParameter[]);
+    render(): Record<string, unknown>;
+    renderBody(): Record<string, unknown>;
+    iterateStepsDepthFirst(): IterableIterator<NamedWorkflowStep>;
+}
+/**
+ * Print the workflow as a YAML string.
+ */
+export declare function toYAMLString(workflow: WorkflowApp): string;
+//# sourceMappingURL=workflows.d.ts.map

package/dist/ast/workflows.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflows.d.ts","sourceRoot":"","sources":["../../src/ast/workflows.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,+BAA+B,EAAE,MAAM,kBAAkB,CAAA;AAChF,OAAO,EAAE,iBAAiB,EAA2B,MAAM,YAAY,CAAA;AAEvE,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,YAAY,CAAA;IAClB,OAAO,CAAC,EAAE,+BAA+B,CAAA;CAC1C;AAED;;GAEG;AACH,qBAAa,WAAW;IACtB,QAAQ,CAAC,YAAY,EAAE,WAAW,EAAE,CAAA;gBAExB,YAAY,GAAE,WAAW,EAAO;IAI5C,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAKlC;AAGD,qBAAa,WAAW;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,KAAK,EAAE,iBAAiB,EAAE,CAAA;IACnC,QAAQ,CAAC,MAAM,CAAC,EAAE,iBAAiB,EAAE,CAAA;gBAGnC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,iBAAiB,EAAE,EAC1B,MAAM,CAAC,EAAE,iBAAiB,EAAE;IAO9B,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAMjC,UAAU,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAuBpC,sBAAsB,IAAI,gBAAgB,CAAC,iBAAiB,CAAC;CAqB/D;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,WAAW,GAAG,MAAM,CAI1D"}

package/dist/ast/workflows.js

@@ -0,0 +1,74 @@
+import * as YAML from 'yaml';
+import { nestedSteps, renderStep } from './steps.js';
+/**
+ * This is the main container class that brings together all subworkflows in a program
+ */
+export class WorkflowApp {
+    subworkflows;
+    constructor(subworkflows = []) {
+        this.subworkflows = subworkflows;
+    }
+    render() {
+        return Object.fromEntries(new Map(this.subworkflows.map((wf) => [wf.name, wf.renderBody()])));
+    }
+}
+// https://cloud.google.com/workflows/docs/reference/syntax/subworkflows
+export class Subworkflow {
+    name;
+    steps;
+    params;
+    constructor(name, steps, params) {
+        this.name = name;
+        this.steps = steps;
+        this.params = params;
+    }
+    render() {
+        return {
+            [this.name]: this.renderBody(),
+        };
+    }
+    renderBody() {
+        const body = {};
+        if (this.params && this.params.length > 0) {
+            Object.assign(body, {
+                params: this.params.map((x) => {
+                    if (x.default) {
+                        return { [x.name]: x.default };
+                    }
+                    else {
+                        return x.name;
+                    }
+                }),
+            });
+        }
+        Object.assign(body, {
+            steps: this.steps.map(({ name, step }) => {
+                return { [name]: renderStep(step) };
+            }),
+        });
+        return body;
+    }
+    *iterateStepsDepthFirst() {
+        const visited = new Set();
+        function* visitPreOrder(step) {
+            if (!visited.has(step)) {
+                visited.add(step);
+                yield step;
+                for (const x of nestedSteps(step.step).flat()) {
+                    yield* visitPreOrder(x);
+                }
+            }
+        }
+        for (const step of this.steps) {
+            yield* visitPreOrder(step);
+        }
+    }
+}
+/**
+ * Print the workflow as a YAML string.
+ */
+export function toYAMLString(workflow) {
+    return YAML.stringify(workflow.render(), {
+        lineWidth: 100,
+    });
+}

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+import * as fs from 'node:fs';
+import { program } from 'commander';
+import { transpile } from './transpiler/index.js';
+import { WorkflowSyntaxError } from './errors.js';
+import { TSError } from '@typescript-eslint/typescript-estree';
+function parseArgs() {
+    program
+        .name('ts2workflow')
+        .version('0.1.0')
+        .description('Transpile a Typescript program into GCP Workflows YAML syntax.')
+        .argument('[FILES]', 'Path to source file(s) to compile. If not given, reads from stdin.');
+    program.parse();
+    return {
+        sourceFiles: program.args,
+    };
+}
+function cliMain() {
+    const args = parseArgs();
+    let files = [];
+    if (args.sourceFiles.length === 0) {
+        files = ['-'];
+    }
+    else {
+        files = args.sourceFiles;
+    }
+    files.forEach((inputFile) => {
+        const inp = inputFile === '-' ? process.stdin.fd : inputFile;
+        let sourceCode = '';
+        try {
+            sourceCode = fs.readFileSync(inp, 'utf8');
+            console.log(transpile(sourceCode));
+        }
+        catch (err) {
+            if (isIoError(err, 'ENOENT')) {
+                console.error(`Error: "${inp}" not found`);
+                process.exit(1);
+            }
+            else if (isIoError(err, 'EISDIR')) {
+                console.error(`Error: "${inp}" is a directory`);
+                process.exit(1);
+            }
+            else if (isIoError(err, 'EAGAIN') && inp === process.stdin.fd) {
+                // Reading from stdin if there's no input causes error. This is a bug in node
+                console.error('Error: Failed to read from stdin');
+                process.exit(1);
+            }
+            else if (err instanceof WorkflowSyntaxError) {
+                prettyPrintSyntaxError(err, inputFile, sourceCode);
+                process.exit(1);
+            }
+            else if (err instanceof TSError) {
+                prettyPrintSyntaxError(err, inputFile, sourceCode);
+                process.exit(1);
+            }
+            else {
+                throw err;
+            }
+        }
+    });
+}
+function isIoError(err, errorCode) {
+    return err instanceof Error && 'code' in err && err.code == errorCode;
+}
+function prettyPrintSyntaxError(exception, inputFile, sourceCode) {
+    console.error(errorDisplay(inputFile, sourceCode, exception.location));
+    console.error(`${exception.message}`);
+}
+function errorDisplay(filename, sourceCode, location) {
+    const lines = [];
+    const prettyFilename = filename === '-' ? '<stdin>' : filename;
+    if (typeof location?.start === 'undefined' ||
+        typeof location?.end === 'undefined' ||
+        isNaN(location?.start.line) ||
+        isNaN(location?.end.line)) {
+        lines.push(`File ${prettyFilename}:`);
+    }
+    else {
+        lines.push(`File ${prettyFilename}, line ${location.start.line}, column ${location.start.column + 1}:`);
+    }
+    const highlightedLine = highlightedSourceCodeLine(sourceCode, location?.start?.line, location?.start?.column, location?.start?.line === location?.end?.line
+        ? location?.end?.column
+        : undefined);
+    if (highlightedLine.length > 0) {
+        lines.push(highlightedLine);
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+function highlightedSourceCodeLine(sourceCode, lineNumber, start, end) {
+    if (typeof lineNumber === 'undefined' ||
+        typeof start === 'undefined' ||
+        isNaN(start)) {
+        return '';
+    }
+    const lines = sourceCode.split('\n');
+    const sourceLine = lines[lineNumber - 1];
+    if (typeof sourceLine === 'undefined') {
+        return '';
+    }
+    let markerLength;
+    if (typeof end === 'undefined') {
+        markerLength = sourceLine.length - start;
+    }
+    else {
+        markerLength = Math.min(end - start + 1, sourceLine.length - start);
+    }
+    const markerLine = `${' '.repeat(start)}${'^'.repeat(markerLength)}`;
+    return `${sourceLine}\n${markerLine}`;
+}
+if (import.meta.url.endsWith(process.argv[1]) ||
+    process.argv[1].endsWith('/ts2workflows')) {
+    cliMain();
+}

package/dist/errors.d.ts

@@ -0,0 +1,18 @@
+export interface SourceCodeLocation {
+    start: {
+        line: number;
+        column: number;
+    };
+    end: {
+        line: number;
+        column: number;
+    };
+}
+export declare class WorkflowSyntaxError extends Error {
+    location: SourceCodeLocation;
+    constructor(message: string, location: SourceCodeLocation);
+}
+export declare class InternalTranspilingError extends Error {
+    constructor(message: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAA;IACvC,GAAG,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAA;CACtC;AAED,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,EAAE,kBAAkB,CAAA;gBAEhB,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,kBAAkB;CAI1D;AAED,qBAAa,wBAAyB,SAAQ,KAAK;gBACrC,OAAO,EAAE,MAAM;CAG5B"}

package/dist/errors.js

@@ -0,0 +1,12 @@
+export class WorkflowSyntaxError extends Error {
+    location;
+    constructor(message, location) {
+        super(message);
+        this.location = location;
+    }
+}
+export class InternalTranspilingError extends Error {
+    constructor(message) {
+        super(`Internal error: ${message}`);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { transpile } from './transpiler/index.js';
+export { WorkflowSyntaxError, InternalTranspilingError, SourceCodeLocation, } from './errors.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAA;AACjD,OAAO,EACL,mBAAmB,EACnB,wBAAwB,EACxB,kBAAkB,GACnB,MAAM,aAAa,CAAA"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { transpile } from './transpiler/index.js';
+export { WorkflowSyntaxError, InternalTranspilingError, } from './errors.js';

package/dist/transpiler/asserts.d.ts

@@ -0,0 +1,7 @@
+export declare function assertType(node: {
+    type: string;
+}, expectedType: string): void;
+export declare function assertOneOfManyTypes(node: {
+    type: string;
+}, expectAnyOfTheseTypes: string[]): void;
+//# sourceMappingURL=asserts.d.ts.map

package/dist/transpiler/asserts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"asserts.d.ts","sourceRoot":"","sources":["../../src/transpiler/asserts.ts"],"names":[],"mappings":"AAEA,wBAAgB,UAAU,CAAC,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI,CAM7E;AAED,wBAAgB,oBAAoB,CAClC,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,EACtB,qBAAqB,EAAE,MAAM,EAAE,GAC9B,IAAI,CAMN"}

package/dist/transpiler/asserts.js

@@ -0,0 +1,11 @@
+import { InternalTranspilingError } from '../errors.js';
+export function assertType(node, expectedType) {
+    if (node?.type !== expectedType) {
+        throw new InternalTranspilingError(`Expected ${expectedType}, got ${node?.type}`);
+    }
+}
+export function assertOneOfManyTypes(node, expectAnyOfTheseTypes) {
+    if (!expectAnyOfTheseTypes.includes(node?.type)) {
+        throw new InternalTranspilingError(`Expected ${expectAnyOfTheseTypes.join(' or ')}, got ${node?.type}`);
+    }
+}

package/dist/transpiler/expressions.d.ts

@@ -0,0 +1,6 @@
+import { Expression, Primitive } from '../ast/expressions.js';
+export declare function convertExpression(instance: any): Expression;
+export declare function convertObjectExpression(node: any): Record<string, Primitive | Expression>;
+export declare function convertObjectAsExpressionValues(node: any): Record<string, Expression>;
+export declare function convertMemberExpression(node: any): Expression;
+//# sourceMappingURL=expressions.d.ts.map

package/dist/transpiler/expressions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expressions.d.ts","sourceRoot":"","sources":["../../src/transpiler/expressions.ts"],"names":[],"mappings":"AAEA,OAAO,EAGL,UAAU,EAGV,SAAS,EAMV,MAAM,uBAAuB,CAAA;AAiB9B,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,GAAG,GAAG,UAAU,CAO3D;AAED,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,GAAG,GACR,MAAM,CAAC,MAAM,EAAE,SAAS,GAAG,UAAU,CAAC,CAgCxC;AAED,wBAAgB,+BAA+B,CAC7C,IAAI,EAAE,GAAG,GACR,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAU5B;AAwKD,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,GAAG,GAAG,UAAU,CAS7D"}