ilib-lint 1.0.0

package/src/Plugin.js

@@ -0,0 +1,99 @@
+/*
+ * Plugin.js - common SPI that all plugins must implement
+ *
+ * Copyright © 2022 JEDLSoft
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * @class common SPI that all plugins must implement
+ * @abstract
+ */
+class Plugin {
+    /**
+     * Construct a new plugin.
+     */
+    constructor(options) {
+    }
+
+    /**
+     * Initialize the current plugin,
+     * @abstract
+     */
+    init() {}
+
+    /**
+     * Return the type of this plugin. This can be one of the
+     * following:
+     *
+     * <ul>
+     * <li>rule - this plugin implements a new rules
+     * <li>parser - this plugin knows how to parse files more deeply
+     * than line-by-line
+     * <li>formatter - this plugin formats results for a particular
+     * type of output
+     * </ul>
+     * 
+     * @returns {String} tells what type of plugin this is
+     * @abstract
+     */
+    getType() {
+    }
+
+    /**
+     * Return the list of extensions of the files that this parser handles.
+     * The extensions are listed without the dot. eg. ["json", "jsn"]
+     *
+     * @returns {Array.<String>} a list of file name extensions
+     */
+    getExtensions() {
+        return [];
+    }
+
+    /**
+     * For a "rule" type of plugin, this returns a list of Rule instances
+     * that this plugin implements.
+     *
+     * @returns {Array.<Rule>} list of Rule instances implemented by this
+     * plugin
+     */
+    getRules() {
+        return [];
+    }
+
+    /**
+     * For a "parser" type of plugin, this returns a list of Parser classes
+     * that this plugin implements.
+     *
+     * @returns {Array.<Parser>} list of Parser classes implemented by this
+     * plugin
+     */
+    getParsers() {
+        return [];
+    }
+
+    /**
+     * For a "formatter" type of plugin, this returns a list of Formatter
+     * instances that this plugin implements.
+     *
+     * @returns {Array.<Formatter>} list of Formatter instances implemented by this
+     * plugin
+     */
+    getFormatters() {
+        return [];
+    }
+};
+
+export default Plugin;

package/src/PluginManager.js

@@ -0,0 +1,56 @@
+/*
+ * PluginManager.js - Load a list of plugins and maintain them
+ *
+ * Copyright © 2022 JEDLSoft
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * @class Represent a plugin manager, which loads a list of plugins
+ * and then maintains references to them
+ */
+class PluginManager {
+    /**
+     * Construct a new plugin manager.
+     */
+    constructor(options) {
+    }
+
+    /**
+     * Load the named plugin.
+     *
+     * @param {String} name plugin to load
+     * @returns {Promise} a promise to load the named plugin.
+     * @accept {Plugin} the loaded plugin
+     * @reject the plugin could not be found or loaded
+     */
+    load(name) {
+        
+    }
+
+    /**
+     * Return an array of handlers that handle the given path name based
+     * on things like the file name extension.
+     *
+     * @param {String} pathName path to a file to match
+     * @param {String} type the type of plugin being sought
+     * @returns {Array.<Plugin>} an array of plugins that claim to handle
+     * the given path name
+     */
+    getHandlers(pathName, type) {
+    }
+};
+
+export default PluginManager;

package/src/Result.js

@@ -0,0 +1,62 @@
+/*
+ * Result.js - Represent an ilib-lint rule check result
+ *
+ * Copyright © 2022 JEDLSoft
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * @class Represent an ilib-lint rule check result
+ * @abstract
+ */
+class Result {
+    /**
+     * Construct an ilib-lint rule check result. Rules should return this
+     * type when reporting issues in the source files. The fields can
+     * contain any of the following properties:
+     *
+     * - severity {String}: "warning" or "error" (required)
+     * - description {String}: description of the problem in the source file
+     *   (required)
+     * - pathName {String}: name of the file that the issue was found in (required)
+     * - rule {Rule}: the rule that generated this issue (required)
+     * - id {String}: key of a resource being checked
+     * - source {String}: for resource problems, this is the original source string
+     * - highlight {String}: highlighted text from the source file indicating
+     *   where the issue was. For resources, this is either the source or target
+     *   string, where-ever the problem occurred
+     * - lineNumber {Number}: line number in the source fie where the issue
+     *   was found
+     * - locale {String}: locale of associated with this issue
+     *
+     * Only the severity, description, pathName, and rule are required. All other
+     * properties are optional.
+     *
+     * @param {Object} fields result fields
+     */
+    constructor(fields) {
+        if (!fields || !fields.severity || !fields.description || !fields.pathName || !fields.rule) {
+            throw "Missing fields in Result constructor";
+        }
+        this.severity = (fields.severity === "error" || fields.severity === "warning") ?
+            fields.severity :
+            "warning";
+        ["description", "pathName", "rule", "id", "highlight", "lineNumber", "locale", "source"].forEach(property => {
+            if (fields[property]) this[property] = fields[property];
+        });
+    }
+}
+
+export default Result;

package/src/Rule.js

@@ -0,0 +1,162 @@
+/*
+ * Rule.js - Represent an ilib-lint rule
+ *
+ * Copyright © 2022 JEDLSoft
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * @class Represent an ilib-lint rule.
+ * @abstract
+ */
+class Rule {
+    /**
+     * Construct an ilib-lint rule. Rules in plugins should implement this
+     * abstract class.
+     */
+    constructor() {
+        if (this.constructor === Rule) {
+            throw new Error("Cannot instantiate abstract class Rule!");
+        }
+    }
+
+    /**
+     * Get the name of the rule. This should be a string with a dash-separated
+     * set of words (kebab or dash case). Example: "resource-match-whitespace"
+     *
+     * @returns {String} the name of this rule
+     */
+    getName() {
+        // make sure to define this.name in your implementation
+        return this.name;
+    }
+
+    /**
+     * Return a general description of the type of problems that this rule is
+     * testing for. This description is not related to particular matches, so
+     * it cannot be more specific. Examples:
+     *
+     * "translation should use the appropriate quote style"
+     * "parameters to the translation wrapper function must not be concatenated"
+     * "translation should match the whitespace of the source string"
+     *
+     * @returns {String} a general description of the type of problems that this rule is
+     * testing for
+     */
+    getDescription() {
+        return this.description;
+    }
+
+    /**
+     * Return the type of this rule. Rules can be organized into the following
+     * types:
+     *
+     * - A resource rule. This checks a translated resource with a source string
+     *   and a translation to a given locale. eg. a rule that checks that
+     *   substitution parameters that exist in the source string also are
+     *   given in the target string.
+     * - A line rule. This rule checks single lines of a file. eg. a rule to
+     *   check the parameters to a function call.
+     * - A multiline rule. This rule checks multiple lines at once to find
+     *   problems that may span multiple lines. For example, a rule to enforce
+     *   a policy that all translatable strings in a source file have an appropriate
+     *   translator's comment on them.
+     * - A multifile rule. This rule checks problems across multiple files. eg.
+     *   a rule to check that ids for translatable strings are unique across all
+     *   files.
+     *
+     * @returns {String} a string with either "resource", "line", "multiline", or
+     * "multifile".
+     */
+    getRuleType() {
+        // default rule type. If your rule is different, override this method.
+        return "line";
+    }
+
+    getSourceLocale() {
+        return this.sourceLocale || "en-US";
+    }
+
+    /**
+     * Return whether or not this rule matches the input. The options object can
+     * contain any of the following properties:
+     *
+     * <ul>
+     * <li>locale - the locale against which this rule should be checked. Some rules
+     * are locale-sensitive, others not.
+     * <li>resource - the resource to test this rule against. For resource rules, this
+     * is a required property.
+     * <li>line - a single line of a file to test this rule against (for line rules)
+     * <li>lines - all the lines of a file to test this rule against (for multiline rules
+     * and multifile rules)
+     * <li>pathName - the name of the current file being matched in multifile rules.
+     * <li>parameters - (optional) parameters for this rule from the configuration file
+     * </ul>
+     *
+     * The return value from this method when a rule matches is an object with the
+     * following properties:
+     *
+     * <ul>
+     * <li>severity - the severity of this match. This can be one of the following:
+     *   <ul>
+     *   <li>suggestion - a suggestion of a better way to do things. The current way is
+     *   not incorrect, but probably not optimal
+     *   <li>warning - a problem that should be fixed, but which does not prevent
+     *   your app from operating internationally. This is more severe than a suggestion.
+     *   <li>error - a problem that must be fixed. This type of problem will prevent
+     *   your app from operating properly internationally and could possibly even
+     *   crash your app in some cases.
+     *   </ul>
+     * <li>description - a description of the problem to display to the user. In order
+     * to make the ilib-lint output useful, this description should attempt to make the
+     * following things clear:
+     *   <ul>
+     *   <li>What part is wrong
+     *   <li>Why it is wrong
+     *   <li>Suggestions on how to fix it
+     *   </ul>
+     * <li>lineNumber - the line number where the match occurred in multiline rules
+     * <li>highlight - the line where the problem occurred, highlighted with XML syntax
+     * (see below)
+     * </ul>
+     *
+     * For the `highlight` property, the line that has a problem is reproduced with
+     * XML tags around the problem part, if it is known. The tags are of the form
+     * &lt;eX&gt; where X is a digit starting with 0 and progressing to 9 for each
+     * subsequent problem. If the file type is XML already, the rest of the line will
+     * be XML-escaped first.<p>
+     *
+     * Example:<p>
+     *
+     * "const str = rb.getString(<e0>id</e0>);"<p>
+     *
+     * In this rule, `getString()` must be called with a static string in order for the
+     * loctool to be able to extract that string. The line above calls `getString()`
+     * with a variable named "id" as a parameter. The variable is highlighted with the
+     * e0 tag. Callers can then translate the open and close tags appropriately for
+     * the output device, such as ASCII escapes for a regular terminal, or HTML tags
+     * for a web-based device.
+     *
+     * @param {Object} options The options object as per the description above
+     * @returns {Object|Array.<Object>|undefined} an object describing the problem if the rule
+     * does match for this locale, or an array of such Objects if there are multiple
+     * problems with the same input, or undefined if the rule does not match
+     */
+    match(options) {
+        throw new Error("Cannot call Rule.match() directly.");
+    }
+}
+
+export default Rule;

package/src/RuleSet.js

@@ -0,0 +1,84 @@
+/*
+ * RuleSet.js - Represent a set of ilib-lint rules
+ *
+ * Copyright © 2022 JEDLSoft
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import Rule from './Rule.js';
+
+/**
+ * @class Represent a set of ilib-lint rules.
+ */
+class RuleSet {
+    /**
+     * Construct an ilib-lint rule set.
+     */
+    constructor(rules) {
+        this.rules = {};
+        this.byname = {};
+        if (rules) {
+            rules.forEach(rule => {
+                this.addRule(rule);
+            });
+        }
+    }
+
+    /**
+     * @param {Rule} rule
+     */
+    addRule(rule) {
+        if (!rule || !(rule instanceof Rule)) return;
+        const name = rule.getName();
+        if (this.byname[name]) return; // already added
+        this.byname[name] = rule;
+        const type = rule.getRuleType();
+        if (!this.rules[type]) {
+            this.rules[type] = [rule];
+        } else {
+            this.rules[type].push(rule);
+        }
+    }
+
+    /**
+     * Return the rule with the given name.
+     *
+     * @param {String} name name to search for
+     * @returns {Rule|undefined} the rule with the given name or
+     * undefined if the rule is not known
+     */
+    getRule(name) {
+        return this.byname[name];
+    }
+
+    /**
+     * Return all the rules of the given type in this set.
+     * @param {String} type to search for
+     * @returns {Array.<Rule>} the list of rules of the requested type
+     */
+    getRules(type) {
+        return this.rules[type] || [];
+    }
+
+    /**
+     * Return the number of rules in this set.
+     * @returns {Number} the number of rules in this set
+     */
+    getSize() {
+        return Object.keys(this.byname).length;
+    }
+};
+
+export default RuleSet;

package/src/SourceFile.js

@@ -0,0 +1,163 @@
+/*
+ * SourceFile.js - Represent a source file
+ *
+ * Copyright © 2022 JEDLSoft
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import path from 'node:path';
+import fs from 'node:fs';
+import { getLocaleFromPath } from 'ilib-tools-common';
+
+import ParserFactory from './ParserFactory.js';
+
+/**
+ * @class Represent a set of ilib-lint rules.
+ */
+class SourceFile {
+    /**
+     * Construct a source file instance
+     * The options parameter can contain any of the following properties:
+     *
+     * - filePath {String} path to the file
+     * - settings {Object} the settings from the ilib-lint config that
+     *   apply to this file
+     */
+    constructor(options) {
+        if (!options || !options.filePath) {
+            throw "Incorrect options given to SourceFile constructor";
+        }
+        this.filePath = options.filePath;
+        this.settings = options.settings;
+    }
+
+    /**
+     * Return the file path for this source file.
+     *
+     * @returns {String} the file path for this source file
+     */
+    getFilePath() {
+        return this.filePath;
+    }
+
+    /**
+     * Return the locale gleaned from the file path using the template in
+     * the settings, or undefined if no locale could be found.
+     *
+     * @returns {String} the locale gleaned from the path, or the empty
+     * string if no locale could be found.
+     */
+    getLocaleFromPath() {
+        if (this.settings && this.settings.template) {
+            return getLocaleFromPath(this.settings.template, this.filePath);
+        }
+        return "";
+    }
+
+    /**
+     * Parse the current source file into a list of resources (in the case of
+     * resource files, or lines in the case of other types of files.
+     * @returns {Object} the parsed representation of this file
+     */
+    parse() {
+        if (!this.filePath) return;
+        let extension = path.extname(this.filePath);
+        if (extension) {
+            // remove the dot
+            extension = extension.substring(1);
+            const parserClasses = ParserFactory({extension});
+            if (parserClasses && parserClasses.length) {
+                const parser = new parserClasses[0]({
+                    filePath: this.filePath
+                });
+                parser.parse();
+                this.resources = parser.getResources();
+                this.type = "resource";
+                
+                return this.resources;
+            }
+        }
+
+        const data = fs.readFileSync(this.filePath, "utf-8");
+        this.lines = data.split(/\n/g);
+        this.type = "line";
+
+        return this.lines;
+    }
+    
+    /**
+     * Return the type of this file, resource or line.
+     * @returns {String} the type of this file
+     */
+    getType() {
+        return this.type;
+    }
+
+    /**
+     * Check the current file and return a list of issues found in this file.
+     * This method parses the source file and applies each rule in turn
+     * using the given locales.
+     *
+     * @param {RuleSet} ruleset a set of rules to apply
+     * @param {Array.<Locale>} locales a set of locales to apply
+     * @returns {Array.<Result>} a list of natch results
+     */
+    findIssues(ruleset, locales) {
+        let issues = [], rules;
+        const detectedLocale = this.getLocaleFromPath();
+
+        if (detectedLocale && locales.indexOf(detectedLocale) < -1) {
+            // not one of the locales we need to check
+            return issues;
+        }
+
+        switch (this.type) {
+        case "line":
+            rules = ruleset.getRules("line");
+            if (rules && rules.length) {
+                for (let i = 0; i < this.lines.length; i++) {
+                    rules.forEach(rule => {
+                        const result = rule.match({
+                            line: this.lines[i],
+                            locale: detectedLocale,
+                            file: this.filePath
+                        });
+                        if (result) issues = issues.concat(result);
+                    });
+                }
+            }
+            break;
+        case "resource":
+            rules = ruleset.getRules("resource");
+            if (rules && rules.length) {
+                this.resources.forEach(resource => {
+                    rules.forEach(rule => {
+                        const result = rule.match({
+                            locale: resource.getTargetLocale(),
+                            resource,
+                            file: this.filePath
+                        });
+                        if (result) issues = issues.concat(result);
+                    });
+                });
+            }
+            break;
+        }
+
+        return issues;
+    }
+};
+
+export default SourceFile;