@sasjs/cli 6.8.2 → 6.8.3

package/build/commands/flow/execute.d.ts

@@ -1,3 +1,41 @@
 import { AuthConfig, Target } from '@sasjs/utils';
 import SASjs from '@sasjs/adapter/node';
+import { FlowWave } from '../../types';
+/**
+ * A flow that finished without every job succeeding.
+ *
+ * It carries the jobs that did not, so the command can say which ones rather
+ * than reporting a JavaScript fault two frames later - which is what happened
+ * when `execute()` resolved `false` instead and the command called `.replace`
+ * on it.
+ *
+ * The marker flag rather than `instanceof`: this package compiles to es5, where
+ * a subclass of a built-in loses its prototype chain and `instanceof` answers
+ * false in the built artefact.
+ */
+export declare class FlowExecutionError extends Error {
+    readonly flowFailure = true;
+    readonly csvFilePath?: string;
+    /**
+     * @param message what did not succeed.
+     * @param csvFilePath the flow results file, which records every job and its
+     *   outcome. It is the diagnostic for a failed run, so it belongs in the
+     *   message: without it the failure path says less than the success path,
+     *   which prints the same path.
+     */
+    constructor(message: string, csvFilePath?: string);
+}
+export declare const isFlowFailure: (error: unknown) => error is FlowExecutionError;
+/**
+ * Names the jobs that did not succeed, so the message a pipeline sees is about
+ * the flow rather than about the code that reported it.
+ *
+ * A job with no status never ran - its flow was failed by a predecessor - and is
+ * left out. The test is against `undefined` rather than truthiness: a status
+ * constant added later that happens to be falsy would otherwise be dropped from
+ * the message, and the message is the whole diagnosis.
+ */
+export declare const describeFailedJobs: (flows: {
+    [key: string]: FlowWave;
+}) => string;
 export declare function execute(target: Target, sasjs: SASjs, authConfig: AuthConfig, source: string, logFolder?: string, csvFile?: string, streamLog?: boolean): Promise<unknown>;

package/build/commands/flow/execute.js

@@ -1,4 +1,19 @@
 "use strict";
+var __extends = (this && this.__extends) || (function () {
+    var extendStatics = function (d, b) {
+        extendStatics = Object.setPrototypeOf ||
+            ({ __proto__: [] } instanceof Array && function (d, b) { d.__proto__ = b; }) ||
+            function (d, b) { for (var p in b) if (Object.prototype.hasOwnProperty.call(b, p)) d[p] = b[p]; };
+        return extendStatics(d, b);
+    };
+    return function (d, b) {
+        if (typeof b !== "function" && b !== null)
+            throw new TypeError("Class extends value " + String(b) + " is not a constructor or null");
+        extendStatics(d, b);
+        function __() { this.constructor = d; }
+        d.prototype = b === null ? Object.create(b) : (__.prototype = b.prototype, new __());
+    };
+})();
 var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
     function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
     return new (P || (P = Promise))(function (resolve, reject) {
@@ -50,10 +65,71 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.describeFailedJobs = exports.isFlowFailure = exports.FlowExecutionError = void 0;
 exports.execute = execute;
 var displayResult_1 = require("../../utils/displayResult");
 var examples_1 = __importDefault(require("./internal/examples"));
 var internal_1 = require("./internal");
+var flow_1 = require("../../types/flow");
+/**
+ * A flow that finished without every job succeeding.
+ *
+ * It carries the jobs that did not, so the command can say which ones rather
+ * than reporting a JavaScript fault two frames later - which is what happened
+ * when `execute()` resolved `false` instead and the command called `.replace`
+ * on it.
+ *
+ * The marker flag rather than `instanceof`: this package compiles to es5, where
+ * a subclass of a built-in loses its prototype chain and `instanceof` answers
+ * false in the built artefact.
+ */
+var FlowExecutionError = /** @class */ (function (_super) {
+    __extends(FlowExecutionError, _super);
+    /**
+     * @param message what did not succeed.
+     * @param csvFilePath the flow results file, which records every job and its
+     *   outcome. It is the diagnostic for a failed run, so it belongs in the
+     *   message: without it the failure path says less than the success path,
+     *   which prints the same path.
+     */
+    function FlowExecutionError(message, csvFilePath) {
+        var _this = _super.call(this, csvFilePath
+            ? "".concat(message, " The flow results were written to ").concat(csvFilePath, ".")
+            : message) || this;
+        _this.flowFailure = true;
+        _this.name = 'FlowExecutionError';
+        _this.csvFilePath = csvFilePath;
+        return _this;
+    }
+    return FlowExecutionError;
+}(Error));
+exports.FlowExecutionError = FlowExecutionError;
+var isFlowFailure = function (error) {
+    return (error === null || error === void 0 ? void 0 : error.flowFailure) === true;
+};
+exports.isFlowFailure = isFlowFailure;
+/**
+ * Names the jobs that did not succeed, so the message a pipeline sees is about
+ * the flow rather than about the code that reported it.
+ *
+ * A job with no status never ran - its flow was failed by a predecessor - and is
+ * left out. The test is against `undefined` rather than truthiness: a status
+ * constant added later that happens to be falsy would otherwise be dropped from
+ * the message, and the message is the whole diagnosis.
+ */
+var describeFailedJobs = function (flows) {
+    var failed = Object.values(flows).flatMap(function (flow) {
+        return flow.jobs
+            .filter(function (job) {
+            return job.status !== undefined && job.status !== flow_1.FlowWaveJobStatus.Success;
+        })
+            .map(function (job) { return "".concat(job.location, " (").concat(job.status, ")"); });
+    });
+    return failed.length
+        ? "The flow did not complete with all jobs successful: ".concat(failed.join(', '), ".")
+        : 'The flow did not complete with all jobs successful.';
+};
+exports.describeFailedJobs = describeFailedJobs;
 function execute(target_1, sasjs_1, authConfig_1, source_1, logFolder_1, csvFile_1) {
     return __awaiter(this, arguments, void 0, function (target, sasjs, authConfig, source, logFolder, csvFile, streamLog) {
         var _this = this;
@@ -146,10 +222,13 @@ function execute(target_1, sasjs_1, authConfig_1, source_1, logFolder_1, csvFile
                                                     reject(flowStatus.message);
                                                 _b = (0, internal_1.allFlowsCompleted)(flows), completed = _b.completed, completedWithAllSuccess = _b.completedWithAllSuccess;
                                                 if (completed) {
+                                                    // a flow that did not succeed is a failure of the flow, not of the CLI:
+                                                    // reject with what did not run, so the command can report it and exit
+                                                    // with a code that means "the flow failed"
                                                     if (completedWithAllSuccess)
                                                         resolve(csvFileRealPath);
                                                     else
-                                                        resolve(false);
+                                                        reject(new FlowExecutionError((0, exports.describeFailedJobs)(flows), csvFileRealPath));
                                                 }
                                                 return [2 /*return*/];
                                         }

package/build/commands/flow/flowCommand.d.ts

@@ -4,6 +4,6 @@ import { ReturnCode } from '../../types/command';
 import { TargetCommand } from '../../types/command/targetCommand';
 export declare class FlowCommand extends TargetCommand {
     constructor(args: string[]);
-    execute(): Promise<ReturnCode>;
-    executeFlow(target: Target, sasjs: SASjs, authConfig: AuthConfig): Promise<ReturnCode>;
+    execute(): Promise<ReturnCode.Success | ReturnCode.InvalidCommand | ReturnCode.InternalError | ReturnCode.LogCheckError | ReturnCode.FlowError>;
+    executeFlow(target: Target, sasjs: SASjs, authConfig: AuthConfig): Promise<ReturnCode.Success | ReturnCode.InternalError | ReturnCode.LogCheckError | ReturnCode.FlowError>;
 }

package/build/commands/flow/flowCommand.js

@@ -67,7 +67,8 @@ var FlowSubCommand;
 })(FlowSubCommand || (FlowSubCommand = {}));
 var syntax = 'flow <subCommand> [options]';
 var usage = 'sasjs flow <execute> --source <flowPath> [options]';
-var description = 'Performs operations on flows of jobs.';
+var description = 'Performs operations on flows of jobs.\n' +
+    'Exits non-zero when a flow does not complete: 6 when a job did not succeed, 2 when the flow could not be executed at all.';
 var examples = [
     {
         command: 'sasjs flow execute --source /local/flow.json --logFolder /local/log/folder --csvFile /local/some.csv --target myTarget --streamLog',
@@ -163,6 +164,14 @@ var FlowCommand = /** @class */ (function (_super) {
                         return [4 /*yield*/, (0, execute_1.execute)(target, sasjs, authConfig, source, logFolder, csvFile, streamLog)
                                 .then(function (csvFilePath) {
                                 var _a;
+                                // execute() resolves a path or rejects. Anything else is a contract
+                                // violation, and reporting it as a successful flow would hide it - the
+                                // shape that used to arrive here was `false` for a failed flow, which is
+                                // what turned a failure into a TypeError
+                                if (typeof csvFilePath !== 'string') {
+                                    (0, utils_1.displayError)(new Error("The flow reported completion without a CSV path (resolved ".concat(typeof csvFilePath, ").")), 'An error has occurred when executing this flow.');
+                                    return command_1.ReturnCode.InternalError;
+                                }
                                 var pathSepRegExp = new RegExp(path_1.default.sep.replace(/\\/g, '\\\\'), 'g');
                                 (_a = process.logger) === null || _a === void 0 ? void 0 : _a.info("CSV file located at: ".concat(csvFilePath.replace(pathSepRegExp, '/')));
                                 return command_1.ReturnCode.Success;
@@ -170,6 +179,10 @@ var FlowCommand = /** @class */ (function (_super) {
                                 .catch(function (err) {
                                 if ((0, logcheck_1.isLogCheckFailure)(err))
                                     return command_1.ReturnCode.LogCheckError;
+                                if ((0, execute_1.isFlowFailure)(err)) {
+                                    (0, utils_1.displayError)(err, 'The flow did not complete successfully.');
+                                    return command_1.ReturnCode.FlowError;
+                                }
                                 (0, utils_1.displayError)(err, 'An error has occurred when executing this flow.');
                                 return command_1.ReturnCode.InternalError;
                             })];

package/build/commands/flow/spec/flow.spec.js

@@ -207,9 +207,104 @@ describe('sasjs flow', function () {
                 }
             });
         }); });
+        it('rejects with the failing job rather than resolving a value', function () { return __awaiter(void 0, void 0, void 0, function () {
+            var flows, error;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        flows = {
+                            flow1: {
+                                jobs: [{ location: 'goodJob' }, { location: 'badJob' }],
+                                predecessors: []
+                            }
+                        };
+                        setupMocks(flows, 'badJob');
+                        return [4 /*yield*/, executeFlowWrapper().catch(function (thrown) { return thrown; })
+                            // the marker, not `instanceof`: the built artefact is es5, where an Error
+                            // subclass loses its prototype chain, so the assertion has to be the one
+                            // that holds in both places
+                        ];
+                    case 1:
+                        error = _a.sent();
+                        // the marker, not `instanceof`: the built artefact is es5, where an Error
+                        // subclass loses its prototype chain, so the assertion has to be the one
+                        // that holds in both places
+                        expect((0, execute_1.isFlowFailure)(error)).toBe(true);
+                        expect(error.message).toEqual('The flow did not complete with all jobs successful: badJob (failure).');
+                        return [2 /*return*/];
+                }
+            });
+        }); });
+        it('rejects with a flow error a caller can recognise', function () { return __awaiter(void 0, void 0, void 0, function () {
+            var flows;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        flows = {
+                            flow1: { jobs: [{ location: 'badJob' }], predecessors: [] }
+                        };
+                        setupMocks(flows, 'badJob');
+                        return [4 /*yield*/, expect(executeFlowWrapper()).rejects.toSatisfy(execute_1.isFlowFailure)];
+                    case 1:
+                        _a.sent();
+                        return [2 /*return*/];
+                }
+            });
+        }); });
+    });
+});
+describe('FlowExecutionError', function () {
+    it('carries the flow results path, and says where they are', function () {
+        var error = new execute_1.FlowExecutionError('The flow did not complete with all jobs successful: /b (failure).', '/project/sasjsresults/flow-results.csv');
+        expect(error.csvFilePath).toEqual('/project/sasjsresults/flow-results.csv');
+        expect(error.message).toEqual('The flow did not complete with all jobs successful: /b (failure). ' +
+            'The flow results were written to /project/sasjsresults/flow-results.csv.');
+        expect((0, execute_1.isFlowFailure)(error)).toBe(true);
+    });
+    it('says nothing about a path it was not given', function () {
+        expect(new execute_1.FlowExecutionError('The flow failed.').message).toEqual('The flow failed.');
+    });
+});
+describe('describeFailedJobs', function () {
+    it('names every job that did not succeed, across flows', function () {
+        var flows = {
+            flow1: {
+                jobs: [
+                    { location: '/a', status: flow_1.FlowWaveJobStatus.Success },
+                    { location: '/b', status: flow_1.FlowWaveJobStatus.Failure }
+                ]
+            },
+            flow2: {
+                jobs: [{ location: '/c', status: flow_1.FlowWaveJobStatus.Failure }]
+            }
+        };
+        expect((0, execute_1.describeFailedJobs)(flows)).toEqual('The flow did not complete with all jobs successful: /b (failure), /c (failure).');
+    });
+    it('leaves out jobs that did not run', function () {
+        var flows = {
+            flow1: {
+                jobs: [
+                    { location: '/never-ran' },
+                    { location: '/b', status: flow_1.FlowWaveJobStatus.Failure }
+                ]
+            }
+        };
+        expect((0, execute_1.describeFailedJobs)(flows)).toEqual('The flow did not complete with all jobs successful: /b (failure).');
+    });
+    it('names a job whose status is falsy rather than dropping it', function () {
+        // a status constant added later could be falsy; truthiness would silently
+        // omit that job from the only diagnosis the caller gets
+        var flows = {
+            flow1: { jobs: [{ location: '/zero', status: 0 }] }
+        };
+        expect((0, execute_1.describeFailedJobs)(flows)).toEqual('The flow did not complete with all jobs successful: /zero (0).');
+    });
+    it('states the failure without a list when no job carries a status', function () {
+        var flows = { flow1: { jobs: [{ location: '/a' }] } };
+        expect((0, execute_1.describeFailedJobs)(flows)).toEqual('The flow did not complete with all jobs successful.');
     });
 });
-var setupMocks = function (flows) {
+var setupMocks = function (flows, failingJob) {
     jest.restoreAllMocks();
     jest.mock('../internal/validateParams');
     jest.mock('../internal/executeFlow');
@@ -223,9 +318,14 @@ var setupMocks = function (flows) {
     jest.spyOn(executeFlowModule, 'executeFlow').mockImplementation(function (flow) { return __awaiter(void 0, void 0, void 0, function () {
         return __generator(this, function (_a) {
             flow.execution = 'started';
-            flow.jobs.forEach(function (job) { return (job.status = flow_1.FlowWaveJobStatus.Success); });
+            flow.jobs.forEach(function (job) {
+                job.status =
+                    job.location === failingJob
+                        ? flow_1.FlowWaveJobStatus.Failure
+                        : flow_1.FlowWaveJobStatus.Success;
+            });
             return [2 /*return*/, {
-                    jobStatus: true,
+                    jobStatus: !failingJob,
                     flowStatus: { terminate: false, message: '' }
                 }];
         });

package/build/commands/flow/spec/flowCommand.spec.js

@@ -95,6 +95,7 @@ var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 var executeModule = __importStar(require("../execute"));
+var execute_1 = require("../execute");
 var flowCommand_1 = require("../flowCommand");
 var utils_1 = require("@sasjs/utils");
 var configUtils = __importStar(require("../../../utils/config"));
@@ -264,6 +265,54 @@ describe('FlowCommand', function () {
             }
         });
     }); });
+    it('should return the flow code when the flow did not succeed', function () { return __awaiter(void 0, void 0, void 0, function () {
+        var command, _a;
+        return __generator(this, function (_b) {
+            switch (_b.label) {
+                case 0:
+                    jest
+                        .spyOn(executeModule, 'execute')
+                        .mockImplementation(function () {
+                        return Promise.reject(new execute_1.FlowExecutionError('badJob (failure)'));
+                    });
+                    command = new flowCommand_1.FlowCommand(__spreadArray(__spreadArray([], __read(defaultArgs), false), [
+                        'flow',
+                        'execute',
+                        '--source',
+                        source
+                    ], false));
+                    _a = expect;
+                    return [4 /*yield*/, command.execute()];
+                case 1:
+                    _a.apply(void 0, [_b.sent()]).toEqual(command_1.ReturnCode.FlowError);
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    it('should treat a resolve without a CSV path as an internal error', function () { return __awaiter(void 0, void 0, void 0, function () {
+        var command, _a;
+        return __generator(this, function (_b) {
+            switch (_b.label) {
+                case 0:
+                    // execute() resolves a path or rejects; anything else is a contract
+                    // violation, and must not be reported as a green flow
+                    jest
+                        .spyOn(executeModule, 'execute')
+                        .mockImplementation(function () { return Promise.resolve(false); });
+                    command = new flowCommand_1.FlowCommand(__spreadArray(__spreadArray([], __read(defaultArgs), false), [
+                        'flow',
+                        'execute',
+                        '--source',
+                        source
+                    ], false));
+                    _a = expect;
+                    return [4 /*yield*/, command.execute()];
+                case 1:
+                    _a.apply(void 0, [_b.sent()]).toEqual(command_1.ReturnCode.InternalError);
+                    return [2 /*return*/];
+            }
+        });
+    }); });
     it('should log the error and return the error code when execution is unsuccessful', function () { return __awaiter(void 0, void 0, void 0, function () {
         var args, command, returnCode;
         return __generator(this, function (_a) {

package/build/types/command/returnCode.d.ts

@@ -4,5 +4,6 @@ export declare enum ReturnCode {
     InternalError = 2,
     LintError = 3,
     AlreadyInitialised = 4,
-    LogCheckError = 5
+    LogCheckError = 5,
+    FlowError = 6
 }

package/build/types/command/returnCode.js

@@ -13,6 +13,10 @@ var ReturnCode;
     ReturnCode[ReturnCode["AlreadyInitialised"] = 4] = "AlreadyInitialised";
     // `logcheck` found issues at or above the configured failure policy. Kept
     // apart from LintError so a pipeline can tell a code-quality failure from a
-    // run that SAS complained about.
+    // run SAS complained about.
     ReturnCode[ReturnCode["LogCheckError"] = 5] = "LogCheckError";
+    // A flow finished without every job succeeding. Distinct from InternalError,
+    // which also covers a bad source file or an unreachable server, so a pipeline
+    // can tell "the flow failed" from "the CLI could not run the flow".
+    ReturnCode[ReturnCode["FlowError"] = 6] = "FlowError";
 })(ReturnCode || (exports.ReturnCode = ReturnCode = {}));

package/package.json

@@ -123,5 +123,5 @@
     "ws": "8.21.0",
     "nanoid": "3.3.18"
   },
-  "version": "6.8.2"
+  "version": "6.8.3"
 }