@sasjs/lint 3.0.0 → 4.1.0

package/README.md

@@ -17,16 +17,18 @@ Our goal is to help SAS developers everywhere spend less time on code reviews, b
 - [@sasjs/vscode-extension](https://github.com/sasjs/vscode-extension) - just download SASjs in the VSCode marketplace, and select view/problems in the menu bar.
 - [@sasjs/cli](https://cli.sasjs.io/lint) - run `sasjs lint` to get a list of all files with their problems, along with line and column indexes.
 
-Configuration is via a `.sasjslint` file with the following structure (these are also the defaults if no .sasjslint file is found):
+Configuration is via a `.sasjslint` file with the following structure (these are also the defaults - a setting that is absent, and a project with no `.sasjslint` file at all, uses the value below):
 
 ```json
 {
+  "allowedGremlins": [],
+  "defaultHeader": "/**{lineEnding}  @file{lineEnding}  @brief <Your brief here>{lineEnding}{lineEnding}  <h4> SAS Macros </h4>{lineEnding}{lineEnding}**/",
   "hasDoxygenHeader": true,
   "hasMacroNameInMend": true,
   "hasMacroParentheses": true,
   "hasRequiredMacroOptions": false,
-  "requiredMacroOptions": ["SECURE", "SRC"],
-  "ignoreList": ["sasjsbuild/", "sasjsresults/"],
+  "ignoreList": [],
+  "ignoredLibnames": [],
   "indentationMultiple": 2,
   "lineEndings": "off",
   "lowerCaseFileNames": true,
@@ -34,18 +36,23 @@ Configuration is via a `.sasjslint` file with the following structure (these are
   "maxHeaderLineLength": 80,
   "maxLineLength": 80,
   "noEncodedPasswords": true,
+  "noGremlins": true,
   "noNestedMacros": true,
   "noSingleAsteriskComments": false,
-  "noGremlins": true,
   "noSpacesInFileNames": true,
   "noTabs": true,
   "noTrailingSpaces": true,
   "noUndeclaredMacros": true,
+  "noUnusedLibnames": false,
   "noUnusedMacros": true,
-  "defaultHeader": "/**{lineEnding}  @file{lineEnding}  @brief <Your brief here>{lineEnding}{lineEnding}  <h4> SAS Macros </h4>{lineEnding}{lineEnding}**/"
+  "requiredMacroOptions": [],
+  "severityLevel": {},
+  "strictMacroDefinition": true
 }
 ```
 
+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.
+
 ## SAS Lint Settings
 
 Each setting can have three states:
@@ -54,10 +61,33 @@ Each setting can have three states:
 - WARN - a warning is written to the log, but the return code will be 0
 - ERROR - an error is written to the log, and the return code is 1
 
-For more details, and the default state, see the description of each rule below. It is also possible to change whether a rule returns ERROR or WARN using the `severityLevels` object.
+For more details, and the default state, see the description of each rule below. It is also possible to change whether a rule returns ERROR or WARN using the `severityLevel` object.
 
 Configuring a non-zero return code (ERROR) is helpful when running `sasjs lint` as part of a git pre-commit hook.  An example is available [here](https://github.com/sasjs/template_jobs/blob/main/.git-hooks/pre-commit).
 
+## Per-file overrides
+
+A file can adjust the configuration for itself, with a `@sasjslint` block in its Doxygen header:
+
+```sas
+/**
+  @file
+  @brief Calls the settlement API
+
+  @sasjslint {"maxHeaderLineLength": 200, "noUndeclaredMacros": false}
+**/
+```
+
+The block holds a JSON object that is merged over the resolved `.sasjslint`:
+
+- scalars replace, so a file can switch a rule off, switch one on, or raise a limit for itself;
+- arrays are additive, so `allowedGremlins` and `requiredMacroOptions` gain entries rather than replacing the project's;
+- objects merge key by key, so a file can set one `severityLevel` without dropping the others.
+
+The override applies to the whole file, and to the formatter, so `sasjs lint fix` and format-on-save honour it - a file that switches `noUnusedMacros` off keeps the entries it would otherwise lose. Only the header is read, so an override cannot be hidden in the body of a file, and a block that is malformed is ignored rather than raised. Place it outside the `<h4> SAS Macros </h4>` section, which the formatter rewrites.
+
+One exception: `ignoreList` is evaluated before a file is read, so an entry a header adds cannot exclude the file it sits in.
+
 ### allowedGremlins
 
 An array of hex codes that represents allowed gremlins (invisible / undesirable characters). To allow all gremlins, you can also set the `noGremlins` rule to `false`.  The full gremlin list is [here](https://github.com/sasjs/lint/blob/main/src/utils/gremlinCharacters.ts).
@@ -137,6 +167,21 @@ Example
 
 There may be specific files (or folders) that are not good candidates for linting. Simply list them in this array and they will be ignored. In addition, any files in the project `.gitignore` file will also be ignored.
 
+### ignoredLibnames
+
+The librefs that `noUnusedLibnames` leaves alone. List the librefs that a file assigns but does not use itself - because the connection is used by an autoexec, by `%include`d code, or by another file in the same flow:
+
+```json
+{
+  "ignoredLibnames": ["outData", "TESTWORK"]
+}
+```
+
+A single file can add to this list with the `ignoredLibnames` key of its [`@sasjslint`](#per-file-overrides) header block, which is the per-file escape hatch for the rule.
+
+- Default: []
+- Used by: `noUnusedLibnames`
+
 ### indentationMultiple
 
 This will check each line to ensure that the count of leading spaces can be divided cleanly by this multiple.
@@ -306,6 +351,50 @@ The warning is resolved by adding the macro name to the header. Running `sasjs l
 - Default: true
 - Severity: WARNING
 
+### noUnusedLibnames
+
+Assigning a libref opens a connection, and on a remote engine that costs time, so a `LIBNAME` statement that a file never uses is worth knowing about.
+
+This rule reports a warning for each libref a file assigns and never mentions again. A mention is any occurrence of the libref outside the `LIBNAME` statement, which covers the indirect forms SAS accepts as well as two-level names:
+
+```sas
+libname outData "&dirOut.";
+libname TESTWORK "&work";
+libname path2 "&sasjswork/path2";
+
+libText = pathname("outData", "L");        /* the libref as a string */
+%let dir = %sysfunc(pathname(TESTWORK));   /* the libref unquoted */
+proc format library=path2;                 /* the libref as an option value */
+options insert=(fmtsearch=(path1 path2));
+```
+
+The test is deliberately generous, because a use that is missed becomes a false positive. A `LIBNAME` statement that deassigns (`libname foo;`), clears (`libname foo clear;`) or reports (`libname foo list;`) assigns nothing, so it is never reported - and it counts as a use, since it refers to a libref assigned elsewhere. The reporting form `libname _all_ list;` names no libref. A libref built at runtime (`libname &lib;`) is not a literal, so there is nothing to check.
+
+The rule is **off by default**. A `.sas` file is not a complete job, so a libref it assigns can be used by:
+
+- an `autoexec.sas` that pre-assigns librefs
+- macros, functions or `%include`d programs that the linter never sees
+- another file in the same flow - in the SASjs framework, a secondary artefact
+
+Enable it per project with `"noUnusedLibnames": true`, and list the librefs it should leave alone in [`ignoredLibnames`](#ignoredlibnames). An individual file can exempt its own librefs, or enable the rule for itself, in its `@sasjslint` header block:
+
+```sas
+/**
+  @file
+  @brief Loads the settlement feed
+
+  <h4> SAS Macros </h4>
+  @li mf_trim.sas
+
+  @sasjslint {"noUnusedLibnames": true, "ignoredLibnames": ["outData"]}
+**/
+```
+
+There is no fix. `sasjs lint fix` leaves the file alone, because the formatter cannot see the rest of the job - removing the statement could break it, and silencing every warning into the ignore list would make the rule pointless.
+
+- Default: false
+- Severity: WARNING
+
 ### noUnusedMacros
 
 The counterpart of `noUndeclaredMacros`. This rule reports a warning for each macro listed under `<h4> SAS Macros </h4>` that the file itself never invokes, which usually means the header is out of date.
@@ -317,6 +406,18 @@ Running `sasjs lint fix` (or saving in the SASjs VS Code extension with `formatO
 - Default: true
 - Severity: WARNING
 
+### strictMacroDefinition
+
+This will check the syntax of a macro definition, and warn about two things:
+
+- a parameter name that contains a space, as in `%macro myMacro(my var);`
+- an option that SAS does not recognise, as in `%macro myMacro()/nonsense;`
+
+The options SAS accepts are `CMD`, `DES`, `MINDELIMITER`, `MINOPERATOR`, `NOMINOPERATOR`, `PARMBUFF`, `SECURE`, `NOSECURE`, `STMT`, `SOURCE`, `SRC` and `STORE`.
+
+- Default: true
+- Severity: WARNING
+
 ## severityLevel
 
 This setting allows the default severity to be adjusted. This is helpful when running the lint in a pipeline or git hook. Simply list the rules you would like to adjust along with the desired setting ("warn" or "error"), eg as follows:

package/format/formatFile.js

@@ -12,6 +12,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.formatFile = void 0;
 const file_1 = require("@sasjs/utils/file");
 const lint_1 = require("../lint");
+const parseLintOverride_1 = require("../utils/parseLintOverride");
 const getLintConfig_1 = require("../utils/getLintConfig");
 const shared_1 = require("./shared");
 /**
@@ -25,7 +26,7 @@ const formatFile = (filePath, configuration) => __awaiter(void 0, void 0, void 0
     const diagnosticsBeforeFormat = yield (0, lint_1.lintFile)(filePath, config);
     const diagnosticsCountBeforeFormat = diagnosticsBeforeFormat.length;
     const text = yield (0, file_1.readFile)(filePath);
-    const formattedText = (0, shared_1.processText)(text, config);
+    const formattedText = (0, shared_1.processText)(text, (0, parseLintOverride_1.applyLintOverride)(text, config));
     yield (0, file_1.createFile)(filePath, formattedText);
     const diagnosticsAfterFormat = yield (0, lint_1.lintFile)(filePath, config);
     const diagnosticsCountAfterFormat = diagnosticsAfterFormat.length;

package/format/formatFile.js.map

@@ -1 +1 @@
-{"version":3,"file":"formatFile.js","sourceRoot":"","sources":["../../src/format/formatFile.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,4CAAwD;AACxD,kCAAkC;AAGlC,0DAAsD;AACtD,qCAAsC;AAEtC;;;;;GAKG;AACI,MAAM,UAAU,GAAG,CACxB,QAAgB,EAChB,aAA0B,EACH,EAAE;IACzB,MAAM,MAAM,GAAG,aAAa,IAAI,CAAC,MAAM,IAAA,6BAAa,GAAE,CAAC,CAAA;IACvD,MAAM,uBAAuB,GAAG,MAAM,IAAA,eAAQ,EAAC,QAAQ,EAAE,MAAM,CAAC,CAAA;IAChE,MAAM,4BAA4B,GAAG,uBAAuB,CAAC,MAAM,CAAA;IAEnE,MAAM,IAAI,GAAG,MAAM,IAAA,eAAQ,EAAC,QAAQ,CAAC,CAAA;IAErC,MAAM,aAAa,GAAG,IAAA,oBAAW,EAAC,IAAI,EAAE,MAAM,CAAC,CAAA;IAE/C,MAAM,IAAA,iBAAU,EAAC,QAAQ,EAAE,aAAa,CAAC,CAAA;IAEzC,MAAM,sBAAsB,GAAG,MAAM,IAAA,eAAQ,EAAC,QAAQ,EAAE,MAAM,CAAC,CAAA;IAC/D,MAAM,2BAA2B,GAAG,sBAAsB,CAAC,MAAM,CAAA;IAEjE,MAAM,qBAAqB,GACzB,4BAA4B,GAAG,2BAA2B,CAAA;IAE5D,MAAM,gBAAgB,GAAa,EAAE,CAAA;IAErC,IAAI,qBAAqB,EAAE,CAAC;QAC1B,gBAAgB,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;IACjC,CAAC;IAED,OAAO;QACL,gBAAgB;QAChB,qBAAqB;QACrB,kBAAkB,EAAE,sBAAsB;KAC3C,CAAA;AACH,CAAC,CAAA,CAAA;AA/BY,QAAA,UAAU,cA+BtB"}
+{"version":3,"file":"formatFile.js","sourceRoot":"","sources":["../../src/format/formatFile.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,4CAAwD;AACxD,kCAAkC;AAGlC,kEAA8D;AAC9D,0DAAsD;AACtD,qCAAsC;AAEtC;;;;;GAKG;AACI,MAAM,UAAU,GAAG,CACxB,QAAgB,EAChB,aAA0B,EACH,EAAE;IACzB,MAAM,MAAM,GAAG,aAAa,IAAI,CAAC,MAAM,IAAA,6BAAa,GAAE,CAAC,CAAA;IACvD,MAAM,uBAAuB,GAAG,MAAM,IAAA,eAAQ,EAAC,QAAQ,EAAE,MAAM,CAAC,CAAA;IAChE,MAAM,4BAA4B,GAAG,uBAAuB,CAAC,MAAM,CAAA;IAEnE,MAAM,IAAI,GAAG,MAAM,IAAA,eAAQ,EAAC,QAAQ,CAAC,CAAA;IAErC,MAAM,aAAa,GAAG,IAAA,oBAAW,EAAC,IAAI,EAAE,IAAA,qCAAiB,EAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAA;IAExE,MAAM,IAAA,iBAAU,EAAC,QAAQ,EAAE,aAAa,CAAC,CAAA;IAEzC,MAAM,sBAAsB,GAAG,MAAM,IAAA,eAAQ,EAAC,QAAQ,EAAE,MAAM,CAAC,CAAA;IAC/D,MAAM,2BAA2B,GAAG,sBAAsB,CAAC,MAAM,CAAA;IAEjE,MAAM,qBAAqB,GACzB,4BAA4B,GAAG,2BAA2B,CAAA;IAE5D,MAAM,gBAAgB,GAAa,EAAE,CAAA;IAErC,IAAI,qBAAqB,EAAE,CAAC;QAC1B,gBAAgB,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;IACjC,CAAC;IAED,OAAO;QACL,gBAAgB;QAChB,qBAAqB;QACrB,kBAAkB,EAAE,sBAAsB;KAC3C,CAAA;AACH,CAAC,CAAA,CAAA;AA/BY,QAAA,UAAU,cA+BtB"}

package/format/formatText.js

@@ -14,7 +14,7 @@ const utils_1 = require("../utils");
 const shared_1 = require("./shared");
 const formatText = (text, configuration) => __awaiter(void 0, void 0, void 0, function* () {
     const config = configuration || (yield (0, utils_1.getLintConfig)());
-    return (0, shared_1.processText)(text, config);
+    return (0, shared_1.processText)(text, (0, utils_1.applyLintOverride)(text, config));
 });
 exports.formatText = formatText;
 //# sourceMappingURL=formatText.js.map

package/format/formatText.js.map

@@ -1 +1 @@
-{"version":3,"file":"formatText.js","sourceRoot":"","sources":["../../src/format/formatText.ts"],"names":[],"mappings":";;;;;;;;;;;;AACA,oCAAwC;AACxC,qCAAsC;AAE/B,MAAM,UAAU,GAAG,CAAO,IAAY,EAAE,aAA0B,EAAE,EAAE;IAC3E,MAAM,MAAM,GAAG,aAAa,IAAI,CAAC,MAAM,IAAA,qBAAa,GAAE,CAAC,CAAA;IACvD,OAAO,IAAA,oBAAW,EAAC,IAAI,EAAE,MAAM,CAAC,CAAA;AAClC,CAAC,CAAA,CAAA;AAHY,QAAA,UAAU,cAGtB"}
+{"version":3,"file":"formatText.js","sourceRoot":"","sources":["../../src/format/formatText.ts"],"names":[],"mappings":";;;;;;;;;;;;AACA,oCAA2D;AAC3D,qCAAsC;AAE/B,MAAM,UAAU,GAAG,CAAO,IAAY,EAAE,aAA0B,EAAE,EAAE;IAC3E,MAAM,MAAM,GAAG,aAAa,IAAI,CAAC,MAAM,IAAA,qBAAa,GAAE,CAAC,CAAA;IACvD,OAAO,IAAA,oBAAW,EAAC,IAAI,EAAE,IAAA,yBAAiB,EAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAA;AAC3D,CAAC,CAAA,CAAA;AAHY,QAAA,UAAU,cAGtB"}

package/lint/lintFile.js

@@ -24,8 +24,9 @@ const lintFile = (filePath, configuration) => __awaiter(void 0, void 0, void 0,
         return [];
     const config = configuration || (yield (0, utils_1.getLintConfig)());
     const text = yield (0, file_1.readFile)(filePath);
-    const fileDiagnostics = (0, shared_1.processFile)(filePath, config);
-    const textDiagnostics = (0, shared_1.processText)(text, config);
+    const effectiveConfig = (0, utils_1.applyLintOverride)(text, config);
+    const fileDiagnostics = (0, shared_1.processFile)(filePath, effectiveConfig);
+    const textDiagnostics = (0, shared_1.processText)(text, effectiveConfig);
     return [...fileDiagnostics, ...textDiagnostics];
 });
 exports.lintFile = lintFile;

package/lint/lintFile.js.map

@@ -1 +1 @@
-{"version":3,"file":"lintFile.js","sourceRoot":"","sources":["../../src/lint/lintFile.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,4CAA4C;AAE5C,oCAAmD;AACnD,qCAAmD;AAEnD;;;;;GAKG;AACI,MAAM,QAAQ,GAAG,CACtB,QAAgB,EAChB,aAA0B,EACH,EAAE;IACzB,IAAI,MAAM,IAAA,iBAAS,EAAC,QAAQ,EAAE,aAAa,CAAC;QAAE,OAAO,EAAE,CAAA;IAEvD,MAAM,MAAM,GAAG,aAAa,IAAI,CAAC,MAAM,IAAA,qBAAa,GAAE,CAAC,CAAA;IACvD,MAAM,IAAI,GAAG,MAAM,IAAA,eAAQ,EAAC,QAAQ,CAAC,CAAA;IAErC,MAAM,eAAe,GAAG,IAAA,oBAAW,EAAC,QAAQ,EAAE,MAAM,CAAC,CAAA;IACrD,MAAM,eAAe,GAAG,IAAA,oBAAW,EAAC,IAAI,EAAE,MAAM,CAAC,CAAA;IAEjD,OAAO,CAAC,GAAG,eAAe,EAAE,GAAG,eAAe,CAAC,CAAA;AACjD,CAAC,CAAA,CAAA;AAbY,QAAA,QAAQ,YAapB"}
+{"version":3,"file":"lintFile.js","sourceRoot":"","sources":["../../src/lint/lintFile.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,4CAA4C;AAE5C,oCAAsE;AACtE,qCAAmD;AAEnD;;;;;GAKG;AACI,MAAM,QAAQ,GAAG,CACtB,QAAgB,EAChB,aAA0B,EACH,EAAE;IACzB,IAAI,MAAM,IAAA,iBAAS,EAAC,QAAQ,EAAE,aAAa,CAAC;QAAE,OAAO,EAAE,CAAA;IAEvD,MAAM,MAAM,GAAG,aAAa,IAAI,CAAC,MAAM,IAAA,qBAAa,GAAE,CAAC,CAAA;IACvD,MAAM,IAAI,GAAG,MAAM,IAAA,eAAQ,EAAC,QAAQ,CAAC,CAAA;IACrC,MAAM,eAAe,GAAG,IAAA,yBAAiB,EAAC,IAAI,EAAE,MAAM,CAAC,CAAA;IAEvD,MAAM,eAAe,GAAG,IAAA,oBAAW,EAAC,QAAQ,EAAE,eAAe,CAAC,CAAA;IAC9D,MAAM,eAAe,GAAG,IAAA,oBAAW,EAAC,IAAI,EAAE,eAAe,CAAC,CAAA;IAE1D,OAAO,CAAC,GAAG,eAAe,EAAE,GAAG,eAAe,CAAC,CAAA;AACjD,CAAC,CAAA,CAAA;AAdY,QAAA,QAAQ,YAcpB"}

package/lint/lintText.js

@@ -22,7 +22,7 @@ const shared_1 = require("./shared");
  */
 const lintText = (text, configuration) => __awaiter(void 0, void 0, void 0, function* () {
     const config = configuration || (yield (0, utils_1.getLintConfig)());
-    return (0, shared_1.processText)(text, config);
+    return (0, shared_1.processText)(text, (0, utils_1.applyLintOverride)(text, config));
 });
 exports.lintText = lintText;
 //# sourceMappingURL=lintText.js.map

package/lint/lintText.js.map

@@ -1 +1 @@
-{"version":3,"file":"lintText.js","sourceRoot":"","sources":["../../src/lint/lintText.ts"],"names":[],"mappings":";;;;;;;;;;;;AACA,oCAAwC;AACxC,qCAAsC;AAEtC;;;;;;;GAOG;AACI,MAAM,QAAQ,GAAG,CACtB,IAAY,EACZ,aAA0B,EACH,EAAE;IACzB,MAAM,MAAM,GAAG,aAAa,IAAI,CAAC,MAAM,IAAA,qBAAa,GAAE,CAAC,CAAA;IACvD,OAAO,IAAA,oBAAW,EAAC,IAAI,EAAE,MAAM,CAAC,CAAA;AAClC,CAAC,CAAA,CAAA;AANY,QAAA,QAAQ,YAMpB"}
+{"version":3,"file":"lintText.js","sourceRoot":"","sources":["../../src/lint/lintText.ts"],"names":[],"mappings":";;;;;;;;;;;;AACA,oCAA2D;AAC3D,qCAAsC;AAEtC;;;;;;;GAOG;AACI,MAAM,QAAQ,GAAG,CACtB,IAAY,EACZ,aAA0B,EACH,EAAE;IACzB,MAAM,MAAM,GAAG,aAAa,IAAI,CAAC,MAAM,IAAA,qBAAa,GAAE,CAAC,CAAA;IACvD,OAAO,IAAA,oBAAW,EAAC,IAAI,EAAE,IAAA,yBAAiB,EAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAA;AAC3D,CAAC,CAAA,CAAA;AANY,QAAA,QAAQ,YAMpB"}

package/package.json

@@ -72,5 +72,5 @@
     "@sasjs/utils": "3.6.2",
     "ignore": "7.0.11"
   },
-  "version": "3.0.0"
+  "version": "4.1.0"
 }

package/rules/file/index.d.ts

@@ -5,6 +5,7 @@ export { lineEndings } from './lineEndings';
 export { noNestedMacros } from './noNestedMacros';
 export { noUndeclaredMacros } from './noUndeclaredMacros';
 export { noUnusedMacros } from './noUnusedMacros';
+export { noUnusedLibnames } from './noUnusedLibnames';
 export { strictMacroDefinition } from './strictMacroDefinition';
 export { hasRequiredMacroOptions } from './hasRequiredMacroOptions';
 export { noSingleAsteriskComments } from './noSingleAsteriskComments';

package/rules/file/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.noSingleAsteriskComments = exports.hasRequiredMacroOptions = exports.strictMacroDefinition = exports.noUnusedMacros = exports.noUndeclaredMacros = exports.noNestedMacros = exports.lineEndings = exports.hasMacroParentheses = exports.hasMacroNameInMend = exports.hasDoxygenHeader = void 0;
+exports.noSingleAsteriskComments = exports.hasRequiredMacroOptions = exports.strictMacroDefinition = exports.noUnusedLibnames = exports.noUnusedMacros = exports.noUndeclaredMacros = exports.noNestedMacros = exports.lineEndings = exports.hasMacroParentheses = exports.hasMacroNameInMend = exports.hasDoxygenHeader = void 0;
 var hasDoxygenHeader_1 = require("./hasDoxygenHeader");
 Object.defineProperty(exports, "hasDoxygenHeader", { enumerable: true, get: function () { return hasDoxygenHeader_1.hasDoxygenHeader; } });
 var hasMacroNameInMend_1 = require("./hasMacroNameInMend");
@@ -15,6 +15,8 @@ var noUndeclaredMacros_1 = require("./noUndeclaredMacros");
 Object.defineProperty(exports, "noUndeclaredMacros", { enumerable: true, get: function () { return noUndeclaredMacros_1.noUndeclaredMacros; } });
 var noUnusedMacros_1 = require("./noUnusedMacros");
 Object.defineProperty(exports, "noUnusedMacros", { enumerable: true, get: function () { return noUnusedMacros_1.noUnusedMacros; } });
+var noUnusedLibnames_1 = require("./noUnusedLibnames");
+Object.defineProperty(exports, "noUnusedLibnames", { enumerable: true, get: function () { return noUnusedLibnames_1.noUnusedLibnames; } });
 var strictMacroDefinition_1 = require("./strictMacroDefinition");
 Object.defineProperty(exports, "strictMacroDefinition", { enumerable: true, get: function () { return strictMacroDefinition_1.strictMacroDefinition; } });
 var hasRequiredMacroOptions_1 = require("./hasRequiredMacroOptions");

package/rules/file/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/rules/file/index.ts"],"names":[],"mappings":";;;AAAA,uDAAqD;AAA5C,oHAAA,gBAAgB,OAAA;AACzB,2DAAyD;AAAhD,wHAAA,kBAAkB,OAAA;AAC3B,6DAA2D;AAAlD,0HAAA,mBAAmB,OAAA;AAC5B,6CAA2C;AAAlC,0GAAA,WAAW,OAAA;AACpB,mDAAiD;AAAxC,gHAAA,cAAc,OAAA;AACvB,2DAAyD;AAAhD,wHAAA,kBAAkB,OAAA;AAC3B,mDAAiD;AAAxC,gHAAA,cAAc,OAAA;AACvB,iEAA+D;AAAtD,8HAAA,qBAAqB,OAAA;AAC9B,qEAAmE;AAA1D,kIAAA,uBAAuB,OAAA;AAChC,uEAAqE;AAA5D,oIAAA,wBAAwB,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/rules/file/index.ts"],"names":[],"mappings":";;;AAAA,uDAAqD;AAA5C,oHAAA,gBAAgB,OAAA;AACzB,2DAAyD;AAAhD,wHAAA,kBAAkB,OAAA;AAC3B,6DAA2D;AAAlD,0HAAA,mBAAmB,OAAA;AAC5B,6CAA2C;AAAlC,0GAAA,WAAW,OAAA;AACpB,mDAAiD;AAAxC,gHAAA,cAAc,OAAA;AACvB,2DAAyD;AAAhD,wHAAA,kBAAkB,OAAA;AAC3B,mDAAiD;AAAxC,gHAAA,cAAc,OAAA;AACvB,uDAAqD;AAA5C,oHAAA,gBAAgB,OAAA;AACzB,iEAA+D;AAAtD,8HAAA,qBAAqB,OAAA;AAC9B,qEAAmE;AAA1D,kIAAA,uBAAuB,OAAA;AAChC,uEAAqE;AAA5D,oIAAA,wBAAwB,OAAA"}

package/rules/file/noUnusedLibnames.d.ts

@@ -0,0 +1,15 @@
+import { FileLintRule } from '../../types/LintRule';
+/**
+ * Lint rule that reports each libref a file assigns and never uses.
+ *
+ * The rule is off by default. A file is not a complete job, so a libref it
+ * assigns can be used by an autoexec, by `%include`d code, or by another file
+ * in the same SASjs flow - in the framework, by a secondary artefact. Enable it
+ * per project with `noUnusedLibnames`, and list the librefs it should leave
+ * alone in `ignoredLibnames`, or in the `@sasjslint` block of one file.
+ *
+ * There is no fix. The formatter cannot see the rest of the job, so the safe
+ * correction is not knowable, and silencing every warning into the ignore list
+ * would make the rule pointless.
+ */
+export declare const noUnusedLibnames: FileLintRule;

package/rules/file/noUnusedLibnames.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.noUnusedLibnames = void 0;
+const types_1 = require("../../types");
+const LintRuleType_1 = require("../../types/LintRuleType");
+const Severity_1 = require("../../types/Severity");
+const parseLibnames_1 = require("../../utils/parseLibnames");
+const name = 'noUnusedLibnames';
+const description = 'Report librefs that a file assigns and never uses in that file.';
+const message = `Libref '{libref}' is assigned but never used in this file - remove the LIBNAME statement, or list the libref in 'ignoredLibnames'`;
+/**
+ * Collects the librefs the file assigns and never mentions, leaving out the
+ * ones the configuration lists in `ignoredLibnames`.
+ *
+ * A libref can be used by a file the linter never sees - an autoexec, an
+ * `%include`d program, or another file in the same job - which is why the rule
+ * is off by default and why the ignore list exists.
+ */
+const getUnused = (value, config) => {
+    if (!value)
+        return [];
+    const ignored = new Set(config.ignoredLibnames.map((libref) => libref.toLowerCase()));
+    return (0, parseLibnames_1.getUnusedLibnames)(value, config).filter(({ libref }) => !ignored.has(libref.toLowerCase()));
+};
+const test = (value, config) => {
+    const cfg = config || new types_1.LintConfig();
+    const severity = cfg.severityLevel[name] || Severity_1.Severity.Warning;
+    return getUnused(value, cfg).map((assignment) => ({
+        message: message.replace('{libref}', assignment.libref),
+        lineNumber: assignment.lineNumber,
+        startColumnNumber: assignment.startColumnNumber,
+        endColumnNumber: assignment.endColumnNumber,
+        severity
+    }));
+};
+/**
+ * Lint rule that reports each libref a file assigns and never uses.
+ *
+ * The rule is off by default. A file is not a complete job, so a libref it
+ * assigns can be used by an autoexec, by `%include`d code, or by another file
+ * in the same SASjs flow - in the framework, by a secondary artefact. Enable it
+ * per project with `noUnusedLibnames`, and list the librefs it should leave
+ * alone in `ignoredLibnames`, or in the `@sasjslint` block of one file.
+ *
+ * There is no fix. The formatter cannot see the rest of the job, so the safe
+ * correction is not knowable, and silencing every warning into the ignore list
+ * would make the rule pointless.
+ */
+exports.noUnusedLibnames = {
+    type: LintRuleType_1.LintRuleType.File,
+    name,
+    description,
+    message,
+    test
+};
+//# sourceMappingURL=noUnusedLibnames.js.map

package/rules/file/noUnusedLibnames.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"noUnusedLibnames.js","sourceRoot":"","sources":["../../../src/rules/file/noUnusedLibnames.ts"],"names":[],"mappings":";;;AAAA,uCAAoD;AAEpD,2DAAuD;AACvD,mDAA+C;AAC/C,6DAAgF;AAEhF,MAAM,IAAI,GAAG,kBAAkB,CAAA;AAC/B,MAAM,WAAW,GACf,iEAAiE,CAAA;AACnE,MAAM,OAAO,GAAG,mIAAmI,CAAA;AAEnJ;;;;;;;GAOG;AACH,MAAM,SAAS,GAAG,CAAC,KAAa,EAAE,MAAkB,EAAuB,EAAE;IAC3E,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,CAAA;IAErB,MAAM,OAAO,GAAG,IAAI,GAAG,CACrB,MAAM,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC,CAC7D,CAAA;IAED,OAAO,IAAA,iCAAiB,EAAC,KAAK,EAAE,MAAM,CAAC,CAAC,MAAM,CAC5C,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC,CACnD,CAAA;AACH,CAAC,CAAA;AAED,MAAM,IAAI,GAAG,CAAC,KAAa,EAAE,MAAmB,EAAgB,EAAE;IAChE,MAAM,GAAG,GAAG,MAAM,IAAI,IAAI,kBAAU,EAAE,CAAA;IACtC,MAAM,QAAQ,GAAG,GAAG,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,mBAAQ,CAAC,OAAO,CAAA;IAE5D,OAAO,SAAS,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;QAChD,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,UAAU,EAAE,UAAU,CAAC,MAAM,CAAC;QACvD,UAAU,EAAE,UAAU,CAAC,UAAU;QACjC,iBAAiB,EAAE,UAAU,CAAC,iBAAiB;QAC/C,eAAe,EAAE,UAAU,CAAC,eAAe;QAC3C,QAAQ;KACT,CAAC,CAAC,CAAA;AACL,CAAC,CAAA;AAED;;;;;;;;;;;;GAYG;AACU,QAAA,gBAAgB,GAAiB;IAC5C,IAAI,EAAE,2BAAY,CAAC,IAAI;IACvB,IAAI;IACJ,WAAW;IACX,OAAO;IACP,IAAI;CACL,CAAA"}

package/sasjslint-schema.json

@@ -3,18 +3,23 @@
   "$id": "https://github.com/sasjs/lint/blob/main/sasjslint-schema.json",
   "type": "object",
   "title": "SASjs Lint Config File",
-  "description": "The SASjs Lint Config file provides the settings for customising SAS code style in your project.",
+  "description": "The SASjs Lint Config file provides the settings for customising SAS code style in your project. A SAS file can override these settings for itself with a `@sasjslint` block in its Doxygen header.",
   "default": {
-    "noEncodedPasswords": true,
-    "hasDoxygenHeader": true,
+    "allowedGremlins": [],
     "defaultHeader": "/**{lineEnding}  @file{lineEnding}  @brief <Your brief here>{lineEnding}{lineEnding}  <h4> SAS Macros </h4>{lineEnding}{lineEnding}**/",
-    "hasMacroNameInMend": false,
+    "hasDoxygenHeader": true,
+    "hasMacroNameInMend": true,
     "hasMacroParentheses": true,
+    "hasRequiredMacroOptions": false,
+    "ignoreList": [],
+    "ignoredLibnames": [],
     "indentationMultiple": 2,
+    "lineEndings": "off",
     "lowerCaseFileNames": true,
-    "maxLineLength": 80,
-    "maxHeaderLineLength": 80,
     "maxDataLineLength": 80,
+    "maxHeaderLineLength": 80,
+    "maxLineLength": 80,
+    "noEncodedPasswords": true,
     "noGremlins": true,
     "noNestedMacros": true,
     "noSingleAsteriskComments": false,
@@ -22,12 +27,11 @@
     "noTabs": true,
     "noTrailingSpaces": true,
     "noUndeclaredMacros": true,
+    "noUnusedLibnames": false,
     "noUnusedMacros": true,
-    "lineEndings": "off",
-    "strictMacroDefinition": true,
-    "ignoreList": ["sajsbuild", "sasjsresults"],
-    "hasRequiredMacroOptions": false,
-    "requiredMacroOptions": []
+    "requiredMacroOptions": [],
+    "severityLevel": {},
+    "strictMacroDefinition": true
   },
   "examples": [
     {
@@ -106,7 +110,7 @@
       "type": "boolean",
       "title": "hasMacroNameInMend",
       "description": "Enforces the presence of macro names in %mend statements. Shows a warning for %mend statements with missing or mismatched macro names.",
-      "default": false,
+      "default": true,
       "examples": [true, false]
     },
     "hasMacroParentheses": {
@@ -213,6 +217,14 @@
       "default": true,
       "examples": [true, false]
     },
+    "noUnusedLibnames": {
+      "$id": "#/properties/noUnusedLibnames",
+      "type": "boolean",
+      "title": "noUnusedLibnames",
+      "description": "Reports a warning for each libref a file assigns with a LIBNAME statement and never uses in that file. A mention of the libref anywhere else counts as a use, including the indirect forms SAS accepts, such as `pathname(TESTWORK)`, `library=path2` and `fmtsearch=(path1 path2)`. Off by default, because a file is not a complete job - the libref can be used by an autoexec, by `%include`d code, or by another file in the same flow. There is no fix; list the librefs to leave alone in `ignoredLibnames`.",
+      "default": false,
+      "examples": [true, false]
+    },
     "lineEndings": {
       "$id": "#/properties/lineEndings",
       "type": "string",
@@ -235,8 +247,16 @@
       "type": "array",
       "title": "ignoreList",
       "description": "An array of paths or path patterns to ignore when linting. Any files or matching patterns in the .gitignore file will also be ignored.",
-      "default": ["sasjsbuild/", "sasjsresults/"],
-      "examples": ["sasjs/tests", "tmp/scratch.sas"]
+      "default": [],
+      "examples": [["sasjsbuild/", "sasjsresults/"], ["sasjs/tests", "tmp/scratch.sas"]]
+    },
+    "ignoredLibnames": {
+      "$id": "#/properties/ignoredLibnames",
+      "type": "array",
+      "title": "ignoredLibnames",
+      "description": "An array of librefs that `noUnusedLibnames` leaves alone. A single file can add to this list with the `ignoredLibnames` key of its `@sasjslint` header block.",
+      "default": [],
+      "examples": [["outData", "TESTWORK"]]
     },
     "hasRequiredMacroOptions": {
       "$id": "#/properties/hasRequiredMacroOptions",
@@ -378,6 +398,13 @@
           "enum": ["error", "warn"],
           "default": "warn"
         },
+        "noUnusedLibnames": {
+          "$id": "#/properties/severityLevel/noUnusedLibnames",
+          "title": "noUnusedLibnames",
+          "type": "string",
+          "enum": ["error", "warn"],
+          "default": "warn"
+        },
         "lineEndings": {
           "$id": "#/properties/severityLevel/lineEndings",
           "title": "lineEndings",

package/types/LintConfig.d.ts

@@ -9,6 +9,8 @@ import { Severity } from './Severity';
  * More types of rules, when available, will be added here.
  */
 export declare class LintConfig {
+    /** The JSON this configuration was built from, so it can be overridden. */
+    readonly source: any;
     readonly ignoreList: string[];
     readonly allowedGremlins: string[];
     readonly lineLintRules: LineLintRule[];
@@ -24,5 +26,17 @@ export declare class LintConfig {
         [key: string]: Severity;
     };
     readonly requiredMacroOptions: string[];
+    readonly ignoredLibnames: string[];
     constructor(json?: any);
+    /**
+     * Returns a new configuration with an override merged over this one, so a
+     * file can adjust the rules that apply to it.
+     *
+     * Scalars replace, arrays are additive and objects merge key by key - see
+     * `mergeLintConfig`.
+     *
+     * @param {object} json - the override, as read from a `@sasjslint` block.
+     * @returns {LintConfig} a new configuration; this one is unchanged.
+     */
+    override(json: any): LintConfig;
 }

package/types/LintConfig.js

@@ -6,6 +6,7 @@ const line_1 = require("../rules/line");
 const path_1 = require("../rules/path");
 const LineEndings_1 = require("./LineEndings");
 const utils_1 = require("../utils");
+const mergeLintConfig_1 = require("../utils/mergeLintConfig");
 const Severity_1 = require("./Severity");
 /**
  * LintConfig is the logical representation of the .sasjslint file.
@@ -29,6 +30,8 @@ class LintConfig {
         this.defaultHeader = (0, utils_1.getDefaultHeader)();
         this.severityLevel = {};
         this.requiredMacroOptions = [];
+        this.ignoredLibnames = [];
+        this.source = json !== null && json !== void 0 ? json : {};
         if (json === null || json === void 0 ? void 0 : json.ignoreList) {
             if (Array.isArray(json.ignoreList)) {
                 json.ignoreList.forEach((item) => {
@@ -52,9 +55,13 @@ class LintConfig {
         if ((json === null || json === void 0 ? void 0 : json.noTabs) === false || (json === null || json === void 0 ? void 0 : json.noTabIndentation) === false) {
             this.lineLintRules.pop();
         }
-        if ((json === null || json === void 0 ? void 0 : json.maxLineLength) > 0) {
+        // An absent setting falls back to the default, so the rule is on unless the
+        // value switches it off (0 or a negative number).
+        if ((json === null || json === void 0 ? void 0 : json.maxLineLength) === undefined || (json === null || json === void 0 ? void 0 : json.maxLineLength) > 0) {
             this.lineLintRules.push(line_1.maxLineLength);
-            this.maxLineLength = json.maxLineLength;
+            if (!isNaN(json === null || json === void 0 ? void 0 : json.maxLineLength)) {
+                this.maxLineLength = json.maxLineLength;
+            }
             if (!isNaN(json === null || json === void 0 ? void 0 : json.maxHeaderLineLength)) {
                 this.maxHeaderLineLength = json.maxHeaderLineLength;
             }
@@ -86,7 +93,7 @@ class LintConfig {
         if ((json === null || json === void 0 ? void 0 : json.lowerCaseFileNames) !== false) {
             this.pathLintRules.push(path_1.lowerCaseFileNames);
         }
-        if (json === null || json === void 0 ? void 0 : json.hasMacroNameInMend) {
+        if ((json === null || json === void 0 ? void 0 : json.hasMacroNameInMend) !== false) {
             this.fileLintRules.push(file_1.hasMacroNameInMend);
         }
         if ((json === null || json === void 0 ? void 0 : json.noNestedMacros) !== false) {
@@ -101,20 +108,17 @@ class LintConfig {
         if (json === null || json === void 0 ? void 0 : json.hasRequiredMacroOptions) {
             this.fileLintRules.push(file_1.hasRequiredMacroOptions);
             if (json === null || json === void 0 ? void 0 : json.requiredMacroOptions) {
-                if (Array.isArray(json.requiredMacroOptions) &&
-                    json.requiredMacroOptions.length > 0) {
-                    json.requiredMacroOptions.forEach((item) => {
-                        if (typeof item === 'string') {
-                            this.requiredMacroOptions.push(item);
-                        }
-                        else {
-                            throw new Error(`Property "requiredMacroOptions" has invalid type of values. It can only contain strings.`);
-                        }
-                    });
-                }
-                else {
+                if (!Array.isArray(json.requiredMacroOptions)) {
                     throw new Error(`Property "requiredMacroOptions" can only be an array of strings.`);
                 }
+                json.requiredMacroOptions.forEach((item) => {
+                    if (typeof item === 'string') {
+                        this.requiredMacroOptions.push(item);
+                    }
+                    else {
+                        throw new Error(`Property "requiredMacroOptions" has invalid type of values. It can only contain strings.`);
+                    }
+                });
             }
         }
         if (json === null || json === void 0 ? void 0 : json.noSingleAsteriskComments) {
@@ -126,6 +130,23 @@ class LintConfig {
         if ((json === null || json === void 0 ? void 0 : json.noUnusedMacros) !== false) {
             this.fileLintRules.push(file_1.noUnusedMacros);
         }
+        // Off by default: a libref a file assigns can be used by another file.
+        if (json === null || json === void 0 ? void 0 : json.noUnusedLibnames) {
+            this.fileLintRules.push(file_1.noUnusedLibnames);
+            if (json === null || json === void 0 ? void 0 : json.ignoredLibnames) {
+                if (!Array.isArray(json.ignoredLibnames)) {
+                    throw new Error(`Property "ignoredLibnames" can only be an array of strings.`);
+                }
+                json.ignoredLibnames.forEach((item) => {
+                    if (typeof item === 'string') {
+                        this.ignoredLibnames.push(item);
+                    }
+                    else {
+                        throw new Error(`Property "ignoredLibnames" has invalid type of values. It can only contain strings.`);
+                    }
+                });
+            }
+        }
         if ((json === null || json === void 0 ? void 0 : json.noGremlins) !== false) {
             this.lineLintRules.push(line_1.noGremlins);
             if (json === null || json === void 0 ? void 0 : json.allowedGremlins) {
@@ -151,6 +172,19 @@ class LintConfig {
             }
         }
     }
+    /**
+     * Returns a new configuration with an override merged over this one, so a
+     * file can adjust the rules that apply to it.
+     *
+     * Scalars replace, arrays are additive and objects merge key by key - see
+     * `mergeLintConfig`.
+     *
+     * @param {object} json - the override, as read from a `@sasjslint` block.
+     * @returns {LintConfig} a new configuration; this one is unchanged.
+     */
+    override(json) {
+        return new LintConfig((0, mergeLintConfig_1.mergeLintConfig)(this.source, json));
+    }
 }
 exports.LintConfig = LintConfig;
 //# sourceMappingURL=LintConfig.js.map