@sasjs/lint 5.3.0 → 5.4.0

package/README.md

@@ -59,6 +59,8 @@ Configuration is via a `.sasjslint` file with the following structure (these are
 
 Two keys do not have a section of their own. `requiredMacroOptions` is documented with [`hasRequiredMacroOptions`](#hasrequiredmacrooptions), the rule it configures. The deprecated alias `noTabIndentation` is accepted in place of `noTabs`, and is therefore not listed above - it is an alternative spelling rather than a setting of its own.
 
+The file is read as strict JSON, so it cannot carry comments: a file that does not parse is reported as an error, naming the file, rather than being treated as though no configuration were present. Add `"$schema": "https://cli.sasjs.io/sasjslint-schema.json"` to get completion, hover text and validation for every setting in an editor that understands JSON schemas - `sasjs lint init` and a SASjs Server's seeded drive-root file both write it.
+
 ## SAS Lint Settings
 
 Each setting can have three states:
@@ -331,6 +333,46 @@ In batch mode, long SAS code lines may also be truncated, causing hard-to-detect
 
 We strongly recommend a line length limit, and set the bar at 80. To turn this feature off, set the value to 0.
 
+Saving with the formatter does four things for this rule, in this order.
+
+**It lifts a trailing comment onto its own line** when a line is over the limit and carries code before the comment. The code keeps the line it was on and the comment moves below it at the same indentation, which hands the code to the wrap below and the prose to the reflow - so `, var /* variable name from which to return the format */` becomes two lines, and each is handled by the pass that owns it. The lift happens even when the code alone overruns the limit: each half then reaches the pass that owns it, instead of the line being refused by both.
+
+**It breaks a long line of code** at the last space that still fits, and indents the continuation by the next multiple of [`indentationMultiple`](#indentationmultiple), so a wrap never introduces an indentation warning of its own. A space that follows a `;` is preferred over one inside a statement: the semicolon ends the statement, so a newline there is inert and the line reads as SAS rather than as a slice of one, and for a `put` or `%let` it needs none of the `%trim(` machinery below. It also prefers a space that does not leave a macro keyword such as `%let` or `%then` at the end of the line, and a line is rewritten only when every line it becomes fits the limit - so the pass never trades one warning for another, which also keeps `fixedDiagnosticsCount` from going backwards. The shapes where a break would change what SAS reads, or what another rule parses, are left alone:
+
+- `datalines` / `cards` / `parmcards` records, and the statement that opens them, where a newline ends the record
+- a `%*` comment statement, which is prose
+- any space inside `%str`-family masking or a `%sysfunc` / `%qsysfunc` call, whose argument text is carried as data: measured on a live engine, breaking inside `%sysfunc(fput(...))` wrote `Content-Type:   application/csv` where the macro meant one space
+
+A `put`, `putlog` or `%put` statement (including the `%&var.put` form), the window statements, and a `%let` assignment are broken differently, because a plain newline there is data rather than a delimiter: it is a line of the log for the `put` family, and part of the value for `%let`. The break ends the line with `%trim(` and opens the next with `)`, so the newline and the indentation become the argument of `%trim` - which resolves to nothing - and the blank the break replaced sits after the closing marker:
+
+```sas
+  %put NOTE: the macro could not find the requested%trim(
+    ) table and stopped;
+  %let exp8=MPE_DERIVED:CALLER:VAR_LOGIC may not call%trim(
+    ) a function that;
+```
+
+Leaving the blank at the end of the upper line instead would lose it: measured on a live engine, `requested %trim(` printed `requestedtable`, because SAS drops a blank that sits immediately before a macro call - and a trailing blank is what `noTrailingSpaces` reports anyway. The construct is verified end to end for both forms: a macro holding these statements writes byte-identical log lines, and the `%let` variables hold byte-identical values, before and after a format at a limit of 40 and at 60, several breaks per statement included. A `%let` value built over two statements, and one whose text already carries a `%trim(` of its own, are covered by the same check.
+
+A `%macro` declaration is broken before its parameter commas, and the continuation line starts with the comma, so the parameters read as a list and the declaration stays the one statement the macro rules parse:
+
+```sas
+%macro mf_writefile(fpath
+  ,mode=O,l1=,l2=,l3=,l4=,l5=,l6=,l7=,l8=,l9=,l10=);
+```
+
+**It reflows the prose in a block comment**, paragraph by paragraph: the lines of one paragraph are joined and rewrapped, so the block comes back even rather than ragged. A paragraph breaks at a blank line and before anything line-oriented - an `@li` entry, a `@sasjslint` tag, an `<h4>` heading, a list item, a table row or a macro trigger - and a `@brief` or `@param` line carries the lines under it. Blocks holding a `@example` / `@code` / `@verbatim` body, the `<h4> SAS Macros </h4>` section, a comment that shares a line with code, and a comment inside a `datalines` record are left byte-identical. Prose written with a `*` at the start of every line - the JavaDoc style - is read as a list and left as it is. A reflow normalises the runs of spaces inside the paragraph it rewrites, so two spaces after a full stop become one.
+
+**It raises the file's own exception** for a line neither pass could shorten - a URL in a header, a long quoted literal that generates code, an indented data record - by writing or merging a [`@sasjslint`](#per-file-overrides) block at the end of the header:
+
+```sas
+  @sasjslint {"maxHeaderLineLength": 123}
+```
+
+The value is the exact length the longest such line needs and no more: a header line raises `maxHeaderLineLength`, a data record raises `maxDataLineLength`, and a body line raises `maxLineLength`. An existing exception keeps every key it had, and a value is never lowered.
+
+Nothing is raised for a line whose author can still act on it: a `%*` comment, a `put` whose text holds a word longer than the limit, a `%macro` declaration whose single parameter is too long, or a comment line that a reflow cannot fit. Excusing one of those would relax `maxLineLength` for every line of code in the file, and each is a line the author can rewrite.
+
 - Default: 80
 - Severity: WARNING
 
@@ -688,6 +730,9 @@ We've already implemented the following rules:
 - Remove unused macros from the `<h4> SAS Macros </h4>` section
 - Remove trailing spaces
 - Fix line endings, including adding a missing final newline when [`lineEndings`](#lineendings) is configured
+- Break a line that exceeds [`maxLineLength`](#maxlinelength) at whitespace, where doing so cannot change what SAS reads
+- Reflow the prose in a block comment, paragraph by paragraph
+- Raise the file's own `@sasjslint` exception for a line neither of the above can shorten
 
 The formatter only fixes rules that are in your configuration, so a rule that is off neither warns nor is repaired.
 

package/format/adjustLineLength.d.ts

@@ -0,0 +1,34 @@
+import { LintConfig } from '../types';
+/**
+ * Raises the file's own `@sasjslint` exception so that the lines the passes
+ * could not shorten stop being reported.
+ *
+ * The formatter can break most long lines, and `reflowComments` can reflow
+ * prose, but a single token wider than the limit - a URL in a header, a long
+ * quoted literal that generates code - cannot be shortened at all, and a data
+ * record is not code. The documented way to accept those is the per-file
+ * override, and projects do it by hand today (sasjs/core carries
+ * `{"maxLineLength": 123}` for one documentation URL). This writes it for them,
+ * at the exact length the longest such line needs and no more:
+ *
+ * - a header line raises `maxHeaderLineLength`, which affects header lines only
+ * - a data record raises `maxDataLineLength`, which affects records only
+ * - a body line raises `maxLineLength`, which affects the whole file
+ *
+ * Lines the wrapper declines on purpose - `put`-family statements, where a
+ * break is an extra line of output, and `%macro` / `%mend` declarations - do NOT
+ * raise the limit: they are fixable by hand, and excusing them would hide the
+ * finding for good.
+ *
+ * The value is never lowered, an existing exception keeps every key it had, and
+ * no header means nowhere to write, in which case the text is returned
+ * untouched.
+ *
+ * @param {string} text - the text to adjust.
+ * @param {LintConfig} configuration - the effective configuration, the file's
+ *   own override included.
+ * @returns {string} the text, with its exception raised when one is needed.
+ */
+export declare const adjustLineLength: (text: string, configuration: LintConfig) => string;
+/** The configured line ending, for the rare case a terminator has to be invented. */
+export declare const lineEndingOf: (configuration: LintConfig) => string;

package/format/adjustLineLength.js

@@ -0,0 +1,159 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.lineEndingOf = exports.adjustLineLength = void 0;
+const LineEndings_1 = require("../types/LineEndings");
+const getDataSectionsDetail_1 = require("../utils/getDataSectionsDetail");
+const getHeaderLinesCount_1 = require("../utils/getHeaderLinesCount");
+const parseLintOverride_1 = require("../utils/parseLintOverride");
+const scanLine_1 = require("../utils/scanLine");
+const longLines_1 = require("./longLines");
+const rewrapText_1 = require("./rewrapText");
+/** The line that carries a file's own lint configuration. */
+const overrideTag = /^(\s*)@sasjslint\s*(\{.*\})\s*$/;
+/**
+ * Raises the file's own `@sasjslint` exception so that the lines the passes
+ * could not shorten stop being reported.
+ *
+ * The formatter can break most long lines, and `reflowComments` can reflow
+ * prose, but a single token wider than the limit - a URL in a header, a long
+ * quoted literal that generates code - cannot be shortened at all, and a data
+ * record is not code. The documented way to accept those is the per-file
+ * override, and projects do it by hand today (sasjs/core carries
+ * `{"maxLineLength": 123}` for one documentation URL). This writes it for them,
+ * at the exact length the longest such line needs and no more:
+ *
+ * - a header line raises `maxHeaderLineLength`, which affects header lines only
+ * - a data record raises `maxDataLineLength`, which affects records only
+ * - a body line raises `maxLineLength`, which affects the whole file
+ *
+ * Lines the wrapper declines on purpose - `put`-family statements, where a
+ * break is an extra line of output, and `%macro` / `%mend` declarations - do NOT
+ * raise the limit: they are fixable by hand, and excusing them would hide the
+ * finding for good.
+ *
+ * The value is never lowered, an existing exception keeps every key it had, and
+ * no header means nowhere to write, in which case the text is returned
+ * untouched.
+ *
+ * @param {string} text - the text to adjust.
+ * @param {LintConfig} configuration - the effective configuration, the file's
+ *   own override included.
+ * @returns {string} the text, with its exception raised when one is needed.
+ */
+const adjustLineLength = (text, configuration) => {
+    if (!text)
+        return text;
+    if (!configuration.lineLintRules.some((rule) => rule.name === 'maxLineLength'))
+        return text;
+    const headerLinesCount = (0, getHeaderLinesCount_1.getHeaderLinesCount)(text, configuration);
+    if (!headerLinesCount)
+        return text;
+    const entries = (0, rewrapText_1.splitWithTerminators)(text);
+    const lines = entries.map((entry) => entry.line);
+    const dataSections = (0, getDataSectionsDetail_1.getDataSectionsDetail)(text, configuration);
+    const headerLimit = Math.max(configuration.maxLineLength, configuration.maxHeaderLineLength);
+    const dataLimit = Math.max(configuration.maxLineLength, configuration.maxDataLineLength);
+    const needed = {
+        maxLineLength: 0,
+        maxHeaderLineLength: 0,
+        maxDataLineLength: 0
+    };
+    let state = (0, scanLine_1.cleanState)();
+    let breakAwareOpen = false;
+    lines.forEach((line, index) => {
+        const isHeader = index < headerLinesCount;
+        const isData = (0, getDataSectionsDetail_1.checkIsDataLine)(dataSections, index);
+        // A data record is data, so it is not scanned: a comment marker or an
+        // apostrophe in one would otherwise stay open for the rest of the file, and
+        // every later line would read as a comment that no pass may touch.
+        const scanned = isData ? (0, scanLine_1.noScan)() : (0, scanLine_1.scanLine)(line, state);
+        state = scanned.endState;
+        const breakAware = isData
+            ? { line: false, open: false }
+            : (0, longLines_1.breakAwareState)(scanned.code, breakAwareOpen);
+        breakAwareOpen = breakAware.open;
+        const limit = isData
+            ? dataLimit
+            : isHeader
+                ? headerLimit
+                : configuration.maxLineLength;
+        if (line.length <= limit)
+            return;
+        if (breakAware.line ||
+            longLines_1.macroComment.test(line) ||
+            longLines_1.macroDeclaration.test(line))
+            return;
+        // A comment carries no key of its own, so excusing one would raise the
+        // limit for every line of code in the file: `reflowComments` has already
+        // reflowed the prose, and a paragraph holding a word it cannot fit - a URL -
+        // is left to its author. A header line is the exception, because
+        // `maxHeaderLineLength` scopes the relaxation to the header.
+        //
+        // The guard turns on what makes the line long, not on the comment being
+        // there: a line of code that overruns the limit on its own, with a comment
+        // after it, is excused like any other, because no pass may break it either.
+        const codeEnd = scanned.code.trimEnd().length;
+        if (!isHeader && !isData && scanned.hasComment && codeEnd <= limit)
+            return;
+        const key = isData
+            ? 'maxDataLineLength'
+            : isHeader
+                ? 'maxHeaderLineLength'
+                : 'maxLineLength';
+        needed[key] = Math.max(needed[key], line.length);
+    });
+    const raised = Object.keys(needed).filter((key) => needed[key] > configuration[key]);
+    if (!raised.length)
+        return text;
+    const override = (0, parseLintOverride_1.getLintOverride)(text, configuration);
+    const existing = lines
+        .slice(0, headerLinesCount)
+        .find((line) => overrideTag.test(line));
+    // A tag that does not parse is reported by the linter and belongs to its
+    // author: rewriting it would discard whatever they were trying to say.
+    if (existing && !override)
+        return text;
+    const merged = Object.assign({}, (override !== null && override !== void 0 ? override : {}));
+    raised.forEach((key) => {
+        var _a;
+        merged[key] = Math.max((_a = merged[key]) !== null && _a !== void 0 ? _a : 0, needed[key]);
+    });
+    const json = '{' +
+        Object.keys(merged)
+            .map((key) => `"${key}": ${JSON.stringify(merged[key])}`)
+            .join(', ') +
+        '}';
+    if (existing) {
+        const match = overrideTag.exec(existing);
+        if (match[2] === json)
+            return text;
+        const at = lines.indexOf(existing);
+        const rewritten = [...lines];
+        rewritten[at] = `${match[1]}@sasjslint ${json}`;
+        return rewritten.map((line, index) => line + entries[index].ending).join('');
+    }
+    // No exception yet: write one as the last content line of the header, which
+    // is where sasjs/core keeps them, so the header's own layout is untouched.
+    const closingIndex = headerLinesCount - 1;
+    const closing = lines[closingIndex];
+    if (!/^\s*[*]{2}\/\s*$/.test(closing))
+        return text;
+    const previous = lines[closingIndex - 1];
+    const indent = /^\s*/.exec(previous)[0] || '  ';
+    const ending = entries[closingIndex].ending || (0, exports.lineEndingOf)(configuration);
+    const separator = previous.trim() === '' ? [] : [''];
+    const inserted = [...separator, `${indent}@sasjslint ${json}`];
+    const out = lines
+        .slice(0, closingIndex)
+        .map((line, index) => line + entries[index].ending);
+    inserted.forEach((line) => out.push(line + ending));
+    lines.slice(closingIndex).forEach((line, index) => {
+        out.push(line + entries[closingIndex + index].ending);
+    });
+    return out.join('');
+};
+exports.adjustLineLength = adjustLineLength;
+/** The configured line ending, for the rare case a terminator has to be invented. */
+const lineEndingOf = (configuration) => configuration.lineEndings === LineEndings_1.LineEndings.CRLF ? '\r\n' : '\n';
+exports.lineEndingOf = lineEndingOf;
+//# sourceMappingURL=adjustLineLength.js.map

package/format/adjustLineLength.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adjustLineLength.js","sourceRoot":"","sources":["../../src/format/adjustLineLength.ts"],"names":[],"mappings":"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"}

package/format/longLines.d.ts

@@ -0,0 +1,60 @@
+import { LintConfig } from '../types';
+/** A macro declaration, which the macro rules read as one statement. */
+export declare const macroDeclaration: RegExp;
+/**
+ * A macro comment statement - `%* text ;` - which is prose that happens to start
+ * with a trigger. Breaking it would put the terminator on a line of its own, and
+ * like a block comment it belongs to its author.
+ */
+export declare const macroComment: RegExp;
+/**
+ * A statement whose line breaks are data rather than space between tokens.
+ *
+ * For the DATA step's `put` and `putlog`, and the macro and window statements
+ * that write text a reader sees, a break adds a line to the log or to the file
+ * being written. For `%let` a break lands inside the value, and the value keeps
+ * the newline and the continuation indent - measured on a live engine, where a
+ * wrapped `%let` message compared against a single-spaced one failed.
+ *
+ * Both are broken with the `%trim(` idiom rather than by a plain newline, and
+ * neither is left as it is: a break that carries `%trim(` adds no whitespace and
+ * no output line.
+ */
+export declare const breakAwareStatement: RegExp;
+/**
+ * The index where the text of a `put`-family statement begins, so a break is
+ * never taken before the keyword that names it.
+ *
+ * A continuation line carries no keyword of its own, and its whole content is
+ * text, so there the text begins at the first non-whitespace character.
+ *
+ * @param {string} line - the line to read.
+ * @returns {number} the index of the first character of the statement's text.
+ */
+export declare const putTextStart: (line: string) => number;
+/** The index of the first non-whitespace character at or after `from`. */
+export declare const firstNonSpace: (line: string, from: number) => number;
+/**
+ * The indentation a continuation line takes: the next multiple of
+ * `indentationMultiple` after the line's own, so a break can never introduce an
+ * `indentationMultiple` diagnostic of its own.
+ */
+export declare const continuationIndentFor: (indent: string, multiple: number) => string;
+/** The indentation multiple in force, with the rule's documented default. */
+export declare const indentationMultipleOf: (configuration: LintConfig) => number;
+/**
+ * Reads whether one line opens, or carries the continuation of, a statement
+ * whose line breaks SAS reads as output lines.
+ *
+ * Splitting the code view on `;` gives one entry per statement on the line, the
+ * last entry being the part that has not reached its own terminator.
+ *
+ * @param {string} code - the line with literals and comments blanked.
+ * @param {boolean} open - whether the previous line left such a statement open.
+ * @returns {{ line: boolean, open: boolean }} whether this line belongs to one,
+ *   and whether the next line still does.
+ */
+export declare const breakAwareState: (code: string, open: boolean) => {
+    line: boolean;
+    open: boolean;
+};

package/format/longLines.js

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.breakAwareState = exports.indentationMultipleOf = exports.continuationIndentFor = exports.firstNonSpace = exports.putTextStart = exports.breakAwareStatement = exports.macroComment = exports.macroDeclaration = void 0;
+/** A macro declaration, which the macro rules read as one statement. */
+exports.macroDeclaration = /^\s*%(?:macro|mend)\b/i;
+/**
+ * A macro comment statement - `%* text ;` - which is prose that happens to start
+ * with a trigger. Breaking it would put the terminator on a line of its own, and
+ * like a block comment it belongs to its author.
+ */
+exports.macroComment = /^\s*%\*/;
+/**
+ * A statement whose line breaks are data rather than space between tokens.
+ *
+ * For the DATA step's `put` and `putlog`, and the macro and window statements
+ * that write text a reader sees, a break adds a line to the log or to the file
+ * being written. For `%let` a break lands inside the value, and the value keeps
+ * the newline and the continuation indent - measured on a live engine, where a
+ * wrapped `%let` message compared against a single-spaced one failed.
+ *
+ * Both are broken with the `%trim(` idiom rather than by a plain newline, and
+ * neither is left as it is: a break that carries `%trim(` adds no whitespace and
+ * no output line.
+ */
+exports.breakAwareStatement = /^\s*%?(?:&?[\w.]*\.)?(?:put|putlog|window|display)\b|\b(?:then|else)\s+%?put\b|^\s*%let\b/i;
+/**
+ * The index where the text of a `put`-family statement begins, so a break is
+ * never taken before the keyword that names it.
+ *
+ * A continuation line carries no keyword of its own, and its whole content is
+ * text, so there the text begins at the first non-whitespace character.
+ *
+ * @param {string} line - the line to read.
+ * @returns {number} the index of the first character of the statement's text.
+ */
+const putTextStart = (line) => {
+    const match = exports.breakAwareStatement.exec(line);
+    if (!match)
+        return (0, exports.firstNonSpace)(line, 0);
+    const afterKeyword = match.index + match[0].length;
+    // A `%let` keeps its name out of the value, so the first break belongs after
+    // the `=` rather than between the keyword and the name.
+    if (/^\s*%let\b/i.test(line)) {
+        const equals = line.indexOf('=', afterKeyword);
+        if (equals > -1)
+            return equals + 1;
+    }
+    return afterKeyword;
+};
+exports.putTextStart = putTextStart;
+/** The index of the first non-whitespace character at or after `from`. */
+const firstNonSpace = (line, from) => {
+    const rest = line.slice(from);
+    return from + rest.length - rest.trimStart().length;
+};
+exports.firstNonSpace = firstNonSpace;
+/**
+ * The indentation a continuation line takes: the next multiple of
+ * `indentationMultiple` after the line's own, so a break can never introduce an
+ * `indentationMultiple` diagnostic of its own.
+ */
+const continuationIndentFor = (indent, multiple) => indent + ' '.repeat(multiple - (indent.length % multiple));
+exports.continuationIndentFor = continuationIndentFor;
+/** The indentation multiple in force, with the rule's documented default. */
+const indentationMultipleOf = (configuration) => configuration.indentationMultiple > 0 ? configuration.indentationMultiple : 2;
+exports.indentationMultipleOf = indentationMultipleOf;
+/**
+ * Reads whether one line opens, or carries the continuation of, a statement
+ * whose line breaks SAS reads as output lines.
+ *
+ * Splitting the code view on `;` gives one entry per statement on the line, the
+ * last entry being the part that has not reached its own terminator.
+ *
+ * @param {string} code - the line with literals and comments blanked.
+ * @param {boolean} open - whether the previous line left such a statement open.
+ * @returns {{ line: boolean, open: boolean }} whether this line belongs to one,
+ *   and whether the next line still does.
+ */
+const breakAwareState = (code, open) => {
+    const statements = code.split(';');
+    const at = statements.findIndex((statement) => exports.breakAwareStatement.test(statement));
+    return {
+        line: open || at > -1,
+        open: open
+            ? statements.length === 1
+            : at > -1 && at === statements.length - 1
+    };
+};
+exports.breakAwareState = breakAwareState;
+//# sourceMappingURL=longLines.js.map

package/format/longLines.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"longLines.js","sourceRoot":"","sources":["../../src/format/longLines.ts"],"names":[],"mappings":";;;AAEA,wEAAwE;AAC3D,QAAA,gBAAgB,GAAG,wBAAwB,CAAA;AAExD;;;;GAIG;AACU,QAAA,YAAY,GAAG,SAAS,CAAA;AAErC;;;;;;;;;;;;GAYG;AACU,QAAA,mBAAmB,GAC9B,4FAA4F,CAAA;AAE9F;;;;;;;;;GASG;AACI,MAAM,YAAY,GAAG,CAAC,IAAY,EAAU,EAAE;IACnD,MAAM,KAAK,GAAG,2BAAmB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IAE5C,IAAI,CAAC,KAAK;QAAE,OAAO,IAAA,qBAAa,EAAC,IAAI,EAAE,CAAC,CAAC,CAAA;IAEzC,MAAM,YAAY,GAAG,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAA;IAElD,6EAA6E;IAC7E,wDAAwD;IACxD,IAAI,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAC7B,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,YAAY,CAAC,CAAA;QAE9C,IAAI,MAAM,GAAG,CAAC,CAAC;YAAE,OAAO,MAAM,GAAG,CAAC,CAAA;IACpC,CAAC;IAED,OAAO,YAAY,CAAA;AACrB,CAAC,CAAA;AAhBY,QAAA,YAAY,gBAgBxB;AAED,0EAA0E;AACnE,MAAM,aAAa,GAAG,CAAC,IAAY,EAAE,IAAY,EAAU,EAAE;IAClE,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;IAE7B,OAAO,IAAI,GAAG,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC,MAAM,CAAA;AACrD,CAAC,CAAA;AAJY,QAAA,aAAa,iBAIzB;AAED;;;;GAIG;AACI,MAAM,qBAAqB,GAAG,CACnC,MAAc,EACd,QAAgB,EACR,EAAE,CAAC,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,QAAQ,GAAG,CAAC,MAAM,CAAC,MAAM,GAAG,QAAQ,CAAC,CAAC,CAAA;AAH1D,QAAA,qBAAqB,yBAGqC;AAEvE,6EAA6E;AACtE,MAAM,qBAAqB,GAAG,CAAC,aAAyB,EAAU,EAAE,CACzE,aAAa,CAAC,mBAAmB,GAAG,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAAA;AADlE,QAAA,qBAAqB,yBAC6C;AAE/E;;;;;;;;;;;GAWG;AACI,MAAM,eAAe,GAAG,CAC7B,IAAY,EACZ,IAAa,EACqB,EAAE;IACpC,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;IAClC,MAAM,EAAE,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,SAAS,EAAE,EAAE,CAC5C,2BAAmB,CAAC,IAAI,CAAC,SAAS,CAAC,CACpC,CAAA;IAED,OAAO;QACL,IAAI,EAAE,IAAI,IAAI,EAAE,GAAG,CAAC,CAAC;QACrB,IAAI,EAAE,IAAI;YACR,CAAC,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC;YACzB,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,KAAK,UAAU,CAAC,MAAM,GAAG,CAAC;KAC5C,CAAA;AACH,CAAC,CAAA;AAfY,QAAA,eAAe,mBAe3B"}

package/format/reflowComments.d.ts

@@ -0,0 +1,28 @@
+import { LintConfig } from '../types';
+/**
+ * Reflows the prose inside a file's block comments so that no line exceeds the
+ * limit that applies to it, and leaves every other line byte-identical.
+ *
+ * A paragraph is a run of comment lines at one indentation that carry prose. It
+ * breaks at a blank line and before anything line-oriented: an `@li` entry, a
+ * `@sasjslint` tag, an HTML heading, a list marker, a table row or a macro
+ * trigger. Wrapping one of those - or wrapping one line of a paragraph without
+ * reflowing the rest - is what leaves a header ragged. A `@brief` or `@param`
+ * line is prose, so it carries the lines that follow it.
+ *
+ * Blocks that are left entirely alone: one sharing a line with code, one inside
+ * a `datalines` record, one holding a `@example` / `@code` / `@verbatim` body,
+ * the `<h4> SAS Macros </h4>` section - whose entries other rules read and
+ * rewrite - and any block holding a `@sasjslint` tag, whose object has to stay
+ * on the line the tag opens.
+ *
+ * A paragraph is reflowed only when every line of the result fits, so the pass
+ * never raises the diagnostic count: a word longer than the limit - a URL,
+ * usually - leaves its paragraph as the author wrote it.
+ *
+ * @param {string} text - the text to reflow.
+ * @param {LintConfig} configuration - the configuration in force, header
+ *   override included.
+ * @returns {string} the reflowed text.
+ */
+export declare const reflowComments: (text: string, configuration: LintConfig) => string;