@sasjs/cli 6.5.0 → 6.7.0

package/build/commands/logcheck/processLogCheck.js

@@ -0,0 +1,242 @@
+"use strict";
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+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) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+var __values = (this && this.__values) || function(o) {
+    var s = typeof Symbol === "function" && Symbol.iterator, m = s && o[s], i = 0;
+    if (m) return m.call(o);
+    if (o && typeof o.length === "number") return {
+        next: function () {
+            if (o && i >= o.length) o = void 0;
+            return { value: o && o[i++], done: !o };
+        }
+    };
+    throw new TypeError(s ? "Object is not iterable." : "Symbol.iterator is not defined.");
+};
+var __read = (this && this.__read) || function (o, n) {
+    var m = typeof Symbol === "function" && o[Symbol.iterator];
+    if (!m) return o;
+    var i = m.call(o), r, ar = [], e;
+    try {
+        while ((n === void 0 || n-- > 0) && !(r = i.next()).done) ar.push(r.value);
+    }
+    catch (error) { e = { error: error }; }
+    finally {
+        try {
+            if (r && !r.done && (m = i["return"])) m.call(i);
+        }
+        finally { if (e) throw e.error; }
+    }
+    return ar;
+};
+var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
+    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
+        if (ar || !(i in from)) {
+            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
+            ar[i] = from[i];
+        }
+    }
+    return to.concat(ar || Array.prototype.slice.call(from));
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.describeFailure = exports.sumTotals = exports.defaultInputPath = exports.processLogCheck = void 0;
+var path_1 = __importDefault(require("path"));
+var collectLogs_1 = require("./collectLogs");
+var logCheckConfig_1 = require("./logCheckConfig");
+var types_1 = require("./types");
+/**
+ * Runs the check: expands the input, parses every log, applies the policy and
+ * says whether the run passes.
+ *
+ * The report is built here rather than in the renderer so that the three
+ * output formats cannot disagree about what was found - the summary is the
+ * single answer, and human, JSON and CI annotations are three ways of printing
+ * it.
+ */
+var processLogCheck = function (_a) { return __awaiter(void 0, [_a], void 0, function (_b) {
+    var inputPaths, searched, _c, files, missing, unreadable, skipped, toScan, files_1, files_1_1, file, displayPath, logs, scanned, totals;
+    var e_1, _d;
+    var _e = _b.paths, paths = _e === void 0 ? [] : _e, config = _b.config;
+    return __generator(this, function (_f) {
+        switch (_f.label) {
+            case 0:
+                inputPaths = paths.length ? paths : [(0, exports.defaultInputPath)(config)];
+                searched = inputPaths.map(function (inputPath) {
+                    return (0, collectLogs_1.toDisplayPath)(path_1.default.resolve(inputPath));
+                });
+                return [4 /*yield*/, (0, collectLogs_1.collectLogFiles)(inputPaths)];
+            case 1:
+                _c = _f.sent(), files = _c.files, missing = _c.missing, unreadable = _c.unreadable;
+                skipped = [];
+                toScan = [];
+                try {
+                    for (files_1 = __values(files), files_1_1 = files_1.next(); !files_1_1.done; files_1_1 = files_1.next()) {
+                        file = files_1_1.value;
+                        displayPath = (0, collectLogs_1.toDisplayPath)(file);
+                        if ((0, logCheckConfig_1.isIgnoredPath)(displayPath, config.ignorePaths)) {
+                            skipped.push({ displayPath: displayPath, reason: 'excluded by ignorePaths' });
+                            continue;
+                        }
+                        toScan.push(file);
+                    }
+                }
+                catch (e_1_1) { e_1 = { error: e_1_1 }; }
+                finally {
+                    try {
+                        if (files_1_1 && !files_1_1.done && (_d = files_1.return)) _d.call(files_1);
+                    }
+                    finally { if (e_1) throw e_1.error; }
+                }
+                return [4 /*yield*/, Promise.all(toScan.map(function (file) { return (0, collectLogs_1.scanLogFile)(file, config); }))];
+            case 2:
+                logs = _f.sent();
+                scanned = logs.filter(function (log) { return !log.skippedReason; });
+                skipped.push.apply(skipped, __spreadArray([], __read(logs.filter(function (log) { return log.skippedReason; }).map(function (log) { return (0, collectLogs_1.toSkippedFile)(log); })), false));
+                totals = (0, exports.sumTotals)(scanned, files.length);
+                return [2 /*return*/, {
+                        logs: logs,
+                        skipped: sortSkipped(skipped),
+                        missing: missing,
+                        unreadable: unreadable,
+                        usedDefaultInput: !paths.length,
+                        searched: searched,
+                        totals: totals,
+                        failure: (0, exports.describeFailure)(totals, config, missing.length, unreadable.length)
+                    }];
+        }
+    });
+}); };
+exports.processLogCheck = processLogCheck;
+/**
+ * Where a run with no arguments looks. The project's results folder is where
+ * `run`, `job run` and `test` leave their logs, which makes the bare command
+ * do the useful thing inside a project.
+ */
+var defaultInputPath = function (config) {
+    var projectDir = process.projectDir || process.cwd();
+    return path_1.default.resolve(projectDir, config.folder || logCheckConfig_1.DEFAULT_FOLDER);
+};
+exports.defaultInputPath = defaultInputPath;
+/**
+ * Adds up what the run found. Skipped logs contribute nothing but are counted
+ * so the report can say how many files it passed over.
+ */
+var sumTotals = function (scanned, fileCount) {
+    var e_2, _a;
+    if (fileCount === void 0) { fileCount = scanned.length; }
+    var totals = __assign(__assign({}, (0, types_1.emptyCounts)()), { suppressed: 0, logs: scanned.length, skipped: fileCount - scanned.length });
+    try {
+        for (var scanned_1 = __values(scanned), scanned_1_1 = scanned_1.next(); !scanned_1_1.done; scanned_1_1 = scanned_1.next()) {
+            var log = scanned_1_1.value;
+            totals.errors += log.counts.errors;
+            totals.warnings += log.counts.warnings;
+            totals.notes += log.counts.notes;
+            totals.suppressed += log.suppressed.length;
+        }
+    }
+    catch (e_2_1) { e_2 = { error: e_2_1 }; }
+    finally {
+        try {
+            if (scanned_1_1 && !scanned_1_1.done && (_a = scanned_1.return)) _a.call(scanned_1);
+        }
+        finally { if (e_2) throw e_2.error; }
+    }
+    return totals;
+};
+exports.sumTotals = sumTotals;
+/**
+ * The verdict, as a phrase for the report.
+ *
+ * An ERROR always fails unless the policy is `never`; warnings and notes fail
+ * only when the policy asks for them, because notable notes are what legacy
+ * code emits in bulk and a gate that is red on its first run is a gate that
+ * gets commented out.
+ *
+ * A warnings budget is checked first and applies even under `never`: writing
+ * `maxWarnings: 0` is a specific instruction, and a specific instruction
+ * outranks a blanket one. `never` therefore means "do not fail on what you
+ * find", not "ignore the budget I also asked for".
+ *
+ * A path that could not be checked fails the run ahead of everything else: the
+ * answer to "is this log clean" is unknown, and unknown is not a pass.
+ */
+var describeFailure = function (totals, config, missingCount, unreadableCount) {
+    if (missingCount === void 0) { missingCount = 0; }
+    if (unreadableCount === void 0) { unreadableCount = 0; }
+    if (missingCount) {
+        return "".concat(missingCount, " path").concat(missingCount === 1 ? '' : 's', " not found");
+    }
+    if (unreadableCount) {
+        return "".concat(unreadableCount, " folder").concat(unreadableCount === 1 ? '' : 's', " could not be read");
+    }
+    if (config.maxWarnings !== undefined &&
+        totals.warnings > config.maxWarnings) {
+        return "".concat(plural(totals.warnings, 'warning'), " (budget ").concat(config.maxWarnings, ")");
+    }
+    if (config.failOn === 'never')
+        return undefined;
+    if (totals.errors)
+        return plural(totals.errors, 'error');
+    if (config.failOn === 'warning' || config.failOn === 'note') {
+        if (totals.warnings)
+            return plural(totals.warnings, 'warning');
+    }
+    if (config.failOn === 'note' && totals.notes) {
+        return plural(totals.notes, 'note');
+    }
+    return undefined;
+};
+exports.describeFailure = describeFailure;
+var plural = function (count, noun) {
+    return "".concat(count, " ").concat(noun).concat(count === 1 ? '' : 's');
+};
+var sortSkipped = function (skipped) {
+    return __spreadArray([], __read(skipped), false).sort(function (a, b) { return a.displayPath.localeCompare(b.displayPath); });
+};

package/build/commands/logcheck/renderLogCheck.d.ts

@@ -0,0 +1,128 @@
+import { LogIssue } from '@sasjs/utils/logs';
+import { LogCheckConfig, LogCheckSummary, OutputFormat, ScannedLog } from './types';
+/** Longest message shown in the human report before it is cut short. */
+export declare const MAX_MESSAGE_WIDTH = 110;
+/** An issue as a report states it: line and column counted from one. */
+export interface ReportIssue {
+    line: number;
+    endLine: number;
+    column: number;
+    endColumn: number;
+    severity: LogIssue['severity'];
+    code?: string;
+    message: string;
+}
+export interface RenderOptions {
+    format?: OutputFormat;
+    /** List every file that was skipped, rather than just counting them. */
+    verbose?: boolean;
+}
+/**
+ * Prints the result in the requested format.
+ *
+ * The three formats are three views of one summary, never three scans: the
+ * terminal report, the JSON document and the CI annotations must all be
+ * describing the same parse, or they will disagree about the same log.
+ */
+export declare const renderLogCheck: (summary: LogCheckSummary, config: LogCheckConfig, options?: RenderOptions) => void;
+/**
+ * The human report: what was checked, what was found, and the verdict.
+ *
+ * Colour carries severity and nothing else, so a reader scanning for trouble
+ * has one thing to look at, and the same report pasted into a ticket or
+ * piped into a log file without a terminal is still readable.
+ */
+export declare const renderHuman: (summary: LogCheckSummary, config: LogCheckConfig, verbose?: boolean) => void;
+/** The one-line-per-file table: what each log carried, and whether it failed. */
+export declare const fileSummary: (scanned: ScannedLog[], config?: LogCheckConfig) => string[];
+/**
+ * Whether a single log breaks the policy.
+ *
+ * The warnings budget is deliberately not applied here: it is a budget for the
+ * whole run, so a log carrying three warnings is not the one that broke it.
+ */
+export declare const fileFails: (counts: ScannedLog["counts"], config: LogCheckConfig) => boolean;
+/**
+ * The issues themselves, grouped under the log they came from.
+ *
+ * This is the shape a compiler prints and a reader already knows how to scan:
+ * the file once, then `line:column`, the severity, the SAS code where there is
+ * one, and the message.
+ */
+export declare const issueDetails: (scanned: ScannedLog[]) => string[];
+/**
+ * Lays rows out in aligned columns, with the header underlined by dashes.
+ *
+ * Colour codes take no space on screen, so widths are measured on the text
+ * with the codes removed - otherwise every coloured cell is padded by the
+ * length of its own escape sequences and the table drifts.
+ */
+export declare const columns: (rows: string[][], head: string[], gap?: string, indent?: string) => string[];
+/** `13:5` for a one-line message, `13-15:5` for one SAS wrapped. */
+export declare const lineLabel: (issue: LogIssue) => string;
+export declare const severityLabel: (severity: LogIssue["severity"]) => string;
+/** Trims a message to the report width, on a word boundary where there is one. */
+export declare const truncate: (message: string) => string;
+/**
+ * The one-line answer: what was found, and over how many logs.
+ *
+ * It names the logs that were checked rather than the files that were not,
+ * because the number a reader compares against is the size of the result they
+ * have just looked at.
+ */
+export declare const summarise: (summary: LogCheckSummary, scannedCount: number) => string;
+/**
+ * The machine report.
+ *
+ * Line and column are one-based here, as an editor and a CI annotation count
+ * them, while the parser works in indexes - the conversion happens once, at
+ * this boundary, so no consumer has to remember which convention it holds.
+ */
+export declare const toJson: (summary: LogCheckSummary, config: LogCheckConfig) => {
+    tool: string;
+    version: number;
+    config: {
+        failOn: import("./types").FailOn;
+        maxWarnings: number | null;
+        ignoreCodes: string[];
+        ignorePaths: string[];
+    };
+    summary: {
+        logs: number;
+        skipped: number;
+        errors: number;
+        warnings: number;
+        notes: number;
+        suppressed: number;
+        failed: boolean;
+        failure: string | null;
+    };
+    searched: string[];
+    missing: string[];
+    unreadable: {
+        folder: string;
+        reason: string;
+    }[];
+    logs: {
+        file: string;
+        errors: number;
+        warnings: number;
+        notes: number;
+        suppressed: number;
+        skipped: string | null;
+        issues: ReportIssue[];
+    }[];
+    skipped: {
+        file: string;
+        reason: string;
+    }[];
+};
+export declare const toReportIssue: (issue: LogIssue) => ReportIssue;
+/**
+ * GitHub Actions annotations, one line per issue.
+ *
+ * The workflow commands escape three characters in the message and five in the
+ * properties; doing it here means SAS's own text arrives intact, commas and
+ * colons included.
+ */
+export declare const toAnnotations: (summary: LogCheckSummary) => string[];