ilib-lint 2.7.2 → 2.8.0

package/README.md

@@ -20,9 +20,12 @@ This i18n linter differs from other static linters in the following ways:
       a rule that checks that the translations in a resource file of a plural resource
       contain the correct set of plural categories for the target language.
 * It can load plugins
-    * Parsers - you can add parsers for new programming languages or resource file types
-    * Formatters - you can make the output look exactly the way you want
-    * Rules - you can add new rules declaratively or programmatically
+    * Parsers - add parsers for new programming languages or resource file types
+    * Formatters - make the output look exactly the way you want
+    * Rules - add new rules declaratively or programmatically
+    * Fixers - apply auto-fixes to the file
+    * Transformers - transform the file in some way
+    * Serializers - serialize the file to a particular format
 
 See the [release notes](./docs/ReleaseNotes.md) for details on what is
 new and what has changed.
@@ -132,6 +135,17 @@ ilib-lint accepts the following command-line parameters:
   of 2. There is no default minimum, so the linter will not give an exit code
   unless this parameter is specified or unless one of the other limits is
   exceeded.
+* write - if a file is modified in memory during the linter run, write
+  the modified file contents back out to the file system. If the file was not
+  modified, it will not be written out. The file name of the file will be calculated
+  using the template property of the matching file type in the configuration.
+* autoFix - apply any auto-fixes that go along with the rules that were applied to
+  each file. If a file is successfully fixed, it can be written out. The autoFix
+  flag implies the write flag.
+* overwrite - If the file is modified by a Fixer or a Transformer and written
+  out using a Serializer, it will be written back to the original file, overwriting
+  it. The template property of the file type will be ignored. This option implies
+  the write flag.
 
 If multiple limits are exceeded (maximum number of errors, warnings, or suggestions,
 or minimum I18N score), the exit code will be the most severe amongst them
@@ -230,12 +244,15 @@ plugins, which allow the plugin to define multiple plugins. For example, many
 plugins define multiple related rules at the same time which check for
 different aspects of a string.
 
-The linter plugin should override and implement these three methods:
+The linter plugin should override and implement these methods:
 
 - getParsers - return an array of classes that inherit from the Parser class
 - getRules - return an array of classes that inherit from the Rule class
 - getRuleSets - return an array of named rule sets that define which rules to use
+- getFixers - return an array of classes that inherit from the Fixer class
 - getFormatters - return an array of classes that inherit from the Formatter class
+- getTransformers - return an array of classes that inherit from the Transformer class
+- getSerializers - return an array of classes that inherit from the Serializer class
 
 For rules and formatters, each array entry can be either declarative or
 programmatic. See the descriptions below about declarative and programmatic
@@ -570,7 +587,7 @@ ilib-lint plugins from v1 of ilib-lint to v2.
 
 ## License
 
-Copyright © 2022-2024, JEDLSoft
+Copyright © 2022-2025, JEDLSoft
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ilib-lint",
-  "version": "2.7.2",
+  "version": "2.8.0",
   "type": "module",
   "main": "./src/index.js",
   "module": "./src/index.js",
@@ -50,6 +50,7 @@
   },
   "devDependencies": {
     "@tsconfig/node14": "^14.1.2",
+    "@types/jest": "^29.5.14",
     "@types/node": "^14.0.0",
     "docdash": "^2.0.2",
     "i18nlint-plugin-test-old": "file:test/i18nlint-plugin-test-old",
@@ -62,7 +63,6 @@
   },
   "dependencies": {
     "@formatjs/intl": "^2.10.4",
-    "ilib-locale": "^1.2.2",
     "ilib-localeinfo": "^1.1.0",
     "intl-messageformat": "^10.5",
     "json5": "^2.2.3",
@@ -70,11 +70,13 @@
     "micromatch": "^4.0.7",
     "options-parser": "^0.4.0",
     "xml-js": "^1.6.11",
+    "ilib-lint-common": "^3.2.0",
     "ilib-common": "^1.1.6",
-    "ilib-tools-common": "^1.12.2",
-    "ilib-lint-common": "^3.1.2"
+    "ilib-locale": "^1.2.4",
+    "ilib-tools-common": "^1.14.0"
   },
   "scripts": {
+    "coverage": "pnpm test -- --coverage",
     "test": "pnpm test:jest",
     "test:jest": "LANG=en_US.UTF8 node --trace-warnings --experimental-vm-modules node_modules/jest/bin/jest.js",
     "test:watch": "pnpm test:jest --watch",

package/src/FileType.js

@@ -1,7 +1,7 @@
 /*
  * FileType.js - Represents a type of file in an ilib-lint project
  *
- * Copyright © 2023-2024 JEDLSoft
+ * Copyright © 2023-2025 JEDLSoft
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -33,33 +33,79 @@ const logger = log4js.getLogger("ilib-lint.FileType");
  */
 class FileType {
     /**
-     * Contructor a new instance of a file type. The options
-     * for a file type must contain the following properties:
-     *
-     * - name - the name or glob spec for this file type
-     * - project - the Project that this file type is a part of
-     *
-     * Additionally, the options may optionally contain the
-     * following properties:
-     *
-     * - locales (Array of String) - list of locales to use with this file type,
-     *   which overrides the global locales for the project
-     * - type (String) - specifies the way that files of this file type
-     *   are parsed. This can be one of "resource", "source", "line", or
-     *   "ast".
-     * - template (String) - the path name template for this file type
-     *   which shows how to extract the locale from the path
-     *   name if the path includes it. Many file types do not
-     *   include the locale in the path, and in those cases,
-     *   the template can be left out.
-     * - ruleset (Array of String) - a list of rule set names
-     *   to use with this file type
-     * - parsers (Array of String) - an array of names of parsers to
-     *   apply to this file type. This is mainly useful when the source
-     *   code is in a file with an unexpected or ambiguous file
-     *   name extension. For example, a ".js" file may contain
-     *   regular Javascript code, but it may also be React JSX
-     *   code, or even Javascript with JSX and Flow type definitions.
+     * The lint project that this file is a part of.
+     * @type {Project}
+     */
+    project;
+
+    /**
+     * The name or glob spec for this file type
+     * @type {String|undefined}
+     */
+    name;
+
+    /**
+     * The list of locales to use with this file type
+     * @type {Array.<String>|undefined}
+     */
+    locales;
+
+    /**
+     * The intermediate representation type of this file type.
+     * @type {String}
+     */
+    type;
+
+    /**
+     * The array of names of classes of parsers to use with this file type.
+     * @type {Array.<String>|undefined}
+     */
+    parsers = undefined;
+
+    /**
+     * The array of classes of parsers to use with this file type.
+     * @type {Array.<Class>|undefined}
+     */
+    parserClasses = undefined;
+
+    /**
+     * The array of names of transformers to use with this file type.
+     * @type {Array.<String>|undefined}
+     */
+    transformers = undefined;
+
+    /**
+     * The array of instances of transformers to use with this file type.
+     * @type {Array.<Transformer>|undefined}
+     */
+    transformerInstances = undefined;
+
+    /**
+     * The serializer to use with this file type.
+     * @type {String|undefined}
+     */
+    serializer = undefined;
+
+    /**
+     * The instance of the serializer to use with this file type.
+     * @type {Serializer|undefined}
+     */
+    serializerInst = undefined;
+
+    /**
+     * The array of rule sets to apply to files of this type.
+     * @type {Array<String>|undefined}
+     */
+    ruleset = undefined;
+
+    /**
+     * The path template for this file type.
+     * @type {String|undefined}
+     */
+    template = undefined;
+
+    /**
+     * Contructor a new instance of a file type.
      *
      * The array of parsers will be used to attempt to parse each
      * source file. If a parser throws an exception/error while parsing,
@@ -70,19 +116,59 @@ class FileType {
      *
      * @param {Object} options the options governing the construction
      * of this file type as documented above
+     * @param {String} options.name the name or glob spec for this file type
+     * @param {Project} options.project the Project that this file type is a part of
+     * @param {Array.<String>} [options.locales] list of locales to use with this file type
+     * @param {String} [options.template] the path name template for this file type
+     * which shows how to extract the locale from the path
+     * name if the path includes it. Many file types
+     * do not include the locale in the path, and in those cases,
+     * the template can be left out. If a serializer is specified, then the template
+     * is also used by the serializer to determine how to name the output files.
+     * @param {Array.<String>} [options.parsers] an array of names of parsers to
+     * apply to this file type. The first parser is the most important one, as its
+     * type will be used to determine the type of intermediate representation, the
+     * type of the rules, and the type of the transformers and serializer. If no
+     * parsers are specified, then the parser manager will be asked to find all
+     * parsers that can parse files of this type.
+     * @param {Array.<String>} [options.ruleset] a list of rule set names
+     * to use with this file type. Only rules in these rule sets that operate
+     * on the same type of intermediate representation as the parsers will
+     * be applied to the file.
+     * @param {Array.<String>} [options.transformers] an array of transformer names
+     * to apply to files of this type after the rules have been applied. Every transformer
+     * must operate on the same type of intermediate representation as the parser.
+     * @param {String|Object} [options.serializer] the name of the serializer to use if
+     * the file has been modified by a transformer or a fixer. The serializer must
+     * operate on the same type of intermediate representation as the parser.
      * @constructor
+     * @throws {Error} if a transformer or serializer is specified that does not
+     * operate on the same type of intermediate representation as the parser, or
+     * if a parser, transformer, or serializer cannot be found.
      */
     constructor(options) {
         if (!options || !options.name || !options.project) {
             throw "Missing required options to the FileType constructor";
         }
-        ["name", "project", "locales", "ruleset", "template", "type", "parsers"].forEach(prop => {
+        ["name", "project", "locales", "ruleset", "template", "parsers", "transformers", "serializer"].forEach(prop => {
             if (typeof(options[prop]) !== 'undefined') {
                 this[prop] = options[prop];
             }
         });
 
-        this.type = this.type || "string";
+        if (this.parsers) {
+            const parserMgr = this.project.getParserManager();
+            this.parserClasses = this.parsers.map(parserName => {
+                const parser = parserMgr.getByName(parserName);
+                if (!parser) {
+                    throw `Could not find parser ${parserName} named in the configuration for filetype ${this.name}`;
+                }
+                if (!this.type) {
+                    this.type = parserMgr.getType(parserName);
+                }
+                return parser;
+            });
+        }
 
         if (this.ruleset) {
             if (typeof(this.ruleset) === 'string') {
@@ -100,16 +186,44 @@ class FileType {
             }
         }
 
-        if (this.parsers) {
-            const parserMgr = this.project.getParserManager();
-            this.parserClasses = this.parsers.map(parserName => {
-                const parser = parserMgr.getByName(parserName);
-                if (!parser) {
-                    throw `Could not find parser ${parserName} named in the configuration for filetype ${this.name}`;
+        if (this.transformers) {
+            const names = Array.isArray(this.transformers) ? this.transformers : [ this.transformers ];
+            const transformerMgr = this.project.getTransformerManager();
+            this.transformerInstances = names.map(transformerName => {
+                const transformer = transformerMgr.get(transformerName);
+                if (!transformer) {
+                    throw `Could not find transformer ${transformerName} named in the configuration for filetype ${this.name}`;
                 }
-                return parser;
+                const transformerType = transformer.getType();
+                if (!this.type) {
+                    this.type = transformerType;
+                } else if (transformerType !== this.type) {
+                     throw new Error(`The transformer ${transformerName} processes representations of type ${transformerType}, but the filetype ${this.name} handles representations of type ${this.type}. The two types must match.`);
+                }
+                return transformer;
             });
         }
+
+        if (this.serializer) {
+            // if it is a string, then that string is the name of the serializer. If it is an object,
+            // then it the name and the settings to pass to the the serializer constructor.
+            const name = typeof(this.serializer) === 'string' ? this.serializer : this.serializer.name;
+            const serializerMgr = this.project.getSerializerManager();
+            this.serializerInst = serializerMgr.get(name, this.serializer);
+            if (!this.serializerInst) {
+                throw new Error(`Could not find or instantiate serializer ${this.serializer} named in the configuration for filetype ${this.name}`);
+            }
+            const serializerType = this.serializerInst.getType();
+            if (!this.type) {
+                this.type = serializerType;
+            } else if (serializerType !== this.type) {
+                throw new Error(`The serializer ${name} processes representations of type ${serializerType}, but the filetype ${this.name} handles representations of type ${this.type}. The two types must match.`);
+            }
+        }
+
+        if (!this.type) {
+            this.type = "string";
+        }
     }
 
     getName() {
@@ -195,6 +309,26 @@ class FileType {
         this.rules = set.getRules();
         return this.rules;
     }
+
+    /**
+     * Return the list of transformers to use with this file type.
+     *
+     * @returns {Array.<Transformer>|undefined} an array of transformer instances to use
+     * with this file type, or undefined if there are none.
+     */
+    getTransformers() {
+        return this.transformerInstances;
+    }
+
+    /**
+     * Return an instance of the serializer class for this file type.
+     *
+     * @returns {Serializer|undefined} an instance of the serializer class for this
+     * file type or undefined if there is no serializer for this file type.
+     */
+    getSerializer() {
+        return this.serializerInst;
+    }
 }
 
-export default FileType;
+export default FileType;

package/src/LintableFile.js

@@ -1,7 +1,7 @@
 /*
  * LintableFile.js - Represent a lintable source file
  *
- * Copyright © 2022-2024 JEDLSoft
+ * Copyright © 2022-2025 JEDLSoft
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -31,6 +31,36 @@ const logger = log4js.getLogger("ilib-lint.root.LintableFile");
  * @class Represent a source file
  */
 class LintableFile extends DirItem {
+    /**
+     * Whether the file has been modified since it was last written or since it was read.
+     * @type {boolean}
+     */
+    dirty = false;
+
+    /**
+     * The list of parsers that can parse this file.
+     * @type {Parser[]}
+     */
+    parsers = [];
+
+    /**
+     * The serializer for this file type.
+     * @type {Serializer|undefined}
+     */
+    serializer;
+
+    /**
+     * The file type of this source file
+     * @type {FileType}
+     */
+    filetype;
+
+    /**
+     * The intermediate representations of this file
+     * @type {IntermediateRepresentation[]}
+     */
+    irs = [];
+
     /**
      * Construct a source file instance
      * The options parameter can contain any of the following properties:
@@ -66,6 +96,8 @@ class LintableFile extends DirItem {
             extension = extension.substring(1);
             this.parsers = this.filetype.getParserClasses(extension);
         }
+        this.transformers = this.filetype.getTransformers();
+        this.serializer = this.filetype.getSerializer();
     }
 
     /**
@@ -169,7 +201,7 @@ class LintableFile extends DirItem {
                             // and that any fixable results were produced
                             fixable.length > 0 &&
                             // and that the current parser is able to write
-                            parser.canWrite &&
+                            this.serializer &&
                             // and that the fixer for this type of IR is avaliable
                             (fixer = this.project.getFixerManager().get(ir.getType()))
                         ) {
@@ -179,9 +211,13 @@ class LintableFile extends DirItem {
 
                             // check if anything had been applied
                             if (fixes.some((fix) => fix.applied)) {
+                                // remember that a fix modified the file and that it needs to be
+                                // written out to disk again after all fixes have been applied
+                                this.dirty = true;
+
                                 // fixer should modify the provided IR
                                 // so tell current parser to write out the modified representation
-                                parser.write(ir);
+                                this.sourceFile = this.serializer.serialize(irs);
 
                                 // after writing out the fixed content, we want to reparse to see if any new issues appeared,
                                 // while preserving the results that have been fixed so far;
@@ -238,6 +274,37 @@ class LintableFile extends DirItem {
         return this.irs;
     }
 
+    /**
+     * Set the intermediate representations of this file.
+     * @param {Array.<IntermediateRepresentation>} irs the intermediate representations
+     * of this file
+     */
+    setIRs(irs) {
+        if (irs.every(ir => ir instanceof IntermediateRepresentation)) {
+            this.irs = irs;
+        } else {
+            // should never happen
+            throw new Error("Invalid intermediate representations provided to setIRs");
+        }
+    }
+
+    /**
+     * Return whether or not the file has been modified since it was last written
+     * or since it was read.
+     * @returns {boolean} true if the file is dirty, false otherwise
+     */
+    isDirty() {
+        return this.dirty;
+    }
+
+    /**
+     * Return the source file of this lintable file.
+     * @returns {SourceFile} the source file
+     */
+    getSourceFile() {
+        return this.sourceFile;
+    }
+
     /**
      * Return the stats for the file after issues were found.
      * @returns {FileStats} the stats for the current file
@@ -253,6 +320,41 @@ class LintableFile extends DirItem {
         }
         return fileStats;
     }
+
+    /**
+     * Return the file type of this file.
+     * @returns {FileType} the file type of this file
+     */
+    getFileType() {
+        return this.filetype;
+    }
+
+    /**
+     * Apply the available transformers to the intermediate representations of this file.
+     * @param {Array.<Result>} results the results of the rules that were applied earlier
+     *   in the pipeline, or undefined if there are no results or if the rules have not been
+     *   applied yet
+     */
+    applyTransformers(results) {
+        const transformers = this.filetype.getTransformers();
+        if (this.irs && this.irs.length > 0 && transformers && transformers.length > 0) {
+            // For each intermediate representation, attempt to apply every transformer.
+            // However, only those transformers that have the same type as the intermediate
+            // representation can be applied.
+            for (let i = 0; i < this.irs.length; i++) {
+                if (!this.irs[i]) continue;
+                transformers.forEach(transformer => {
+                    if (this.irs[i].getType() === transformer.getType()) {
+                        const newIR = transformer.transform(this.irs[i], results);
+                        if (newIR) {
+                            this.irs[i] = newIR;
+                            this.dirty = true;
+                        }
+                    }
+                });
+            }
+        }
+    }
 }
 
 export default LintableFile;

package/src/ParserManager.js

@@ -1,7 +1,7 @@
 /*
  * ParserManager.js - Factory to create and return the right parser for the file
  *
- * Copyright © 2022-2024 JEDLSoft
+ * Copyright © 2022-2025 JEDLSoft
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -32,6 +32,21 @@ function getSuperClassName(obj) {
  * knows about.
  */
 class ParserManager {
+    /**
+     * Information about the parsers that this instance of ilib-lint knows about.
+     * Each entry in the object is a parser name and the value is an object
+     * with the properties:
+     * <ul>
+     * <li>description - a description of the parser</li>
+     * <li>type - the type of parser</li>
+     * <li>extensions - an array of file name extensions that this parser can handle</li>
+     * </ul>
+     *
+     * @type {Object}
+     * @private
+     */
+    parserInfo = {};
+
     /**
      * Create a new parser manager instance.
      * @params {Object} options options controlling the construction of this object
@@ -79,13 +94,22 @@ class ParserManager {
                 const p = new parser({
                     getLogger: log4js.getLogger.bind(log4js)
                 });
+                const name = p.getName();
+                if (this.parserInfo[name]) {
+                    logger.debug(`Parser ${name} already exists. Cannot add twice. Ignoring.`);
+                    continue;
+                }
+                this.parserInfo[name] = {
+                    description: p.getDescription(),
+                    type: p.getType(),
+                    extensions: p.getExtensions()
+                };
                 for (const extension of p.getExtensions()) {
                     if (!this.parserCache[extension]) {
                         this.parserCache[extension] = [];
                     }
                     this.parserCache[extension].push(p);
                 }
-                this.descriptions[p.getName()] = p.getDescription();
                 this.parserByName[p.getName()] = p;
 
                 logger.trace(`Added parser to the parser manager.`);
@@ -102,10 +126,29 @@ class ParserManager {
      * @returns {Object} the parser names and descriptions
      */
     getDescriptions() {
-        return this.descriptions;
+        let json = {};
+        Object.keys(this.parserInfo).forEach((name) => {
+            json[name] = this.parserInfo[name].description;
+        });
+        return json;
+    }
+
+    /**
+     * Return the type of the parser with the given name. The type is
+     * the type of intermediate represetnation that the parser produces.
+     *
+     * @param {String} name the name of the parser to get the type for
+     * @returns {String} the type of parser with the given name
+     */
+    getType(name) {
+        return this.parserInfo[name].type;
     }
 
-    // for use with the unit tests
+    /**
+     * Clear the parsers from the factory. This is only intended
+     * for use with the unit tests
+     * @private
+     */
     clear() {
         this.parserCache = {};
     }