@khanacademy/perseus-linter 1.3.7 → 3.0.0

package/dist/es/index.js

@@ -4,6 +4,93 @@ import { addLibraryVersionToPerseusDebug } from '@khanacademy/perseus-utils';
 import PropTypes from 'prop-types';
 
 /* eslint-disable no-useless-escape */
+/**
+ * The Selector class implements a CSS-like system for matching nodes in a
+ * parse tree based on the structure of the tree. Create a Selector object by
+ * calling the static Selector.parse() method on a string that describes the
+ * tree structure you want to match. For example, if you want to find text
+ * nodes that are direct children of paragraph nodes that immediately follow
+ * heading nodes, you could create an appropriate selector like this:
+ *
+ *   selector = Selector.parse("heading + paragraph > text");
+ *
+ * Recall from the TreeTransformer class, that we consider any object with a
+ * string-valued `type` property to be a tree node. The words "heading",
+ * "paragraph" and "text" in the selector string above specify node types and
+ * will match nodes in a parse tree that have `type` properties with those
+ * values.
+ *
+ * Selectors are designed for use during tree traversals done with the
+ * TreeTransformer traverse() method. To test whether the node currently being
+ * traversed matches a selector, simply pass the TraversalState object to the
+ * match() method of the Selector object. If the node does not match the
+ * selector, match() returns null. If it does match, then match() returns an
+ * array of nodes that match the selector. In the example above the first
+ * element of the array would be the node the heading node, the second would
+ * be the paragraph node that follows it, and the third would be the text node
+ * that is a child of the paragraph.  The last element of a returned array of
+ * nodes is always equal to the current node of the tree traversal.
+ *
+ * Code that uses a selector might look like this:
+ *
+ *   matchingNodes = selector.match(state);
+ *   if (matchingNodes) {
+ *       let heading = matchingNodes[0];
+ *       let text = matchingNodes[2];
+ *       // do something with those nodes
+ *   }
+ *
+ * The Selector.parse() method recognizes a grammar that is similar to CSS
+ * selectors:
+ *
+ * selector := treeSelector (, treeSelector)*
+ *
+ *    A selector is one or more comma-separated treeSelectors. A node matches
+ *    the selector if it matches any of the treeSelectors.
+ *
+ * treeSelector := (treeSelector combinator)? nodeSelector
+ *
+ *    A treeSelector is a nodeSelector optionally preceeded by a combinator
+ *    and another tree selector. The tree selector matches if the current node
+ *    matches the node selector and a sibling or ancestor (depending on the
+ *    combinator) of the current node matches the optional treeSelector.
+ *
+ * combinator := ' ' | '>' | '+' | '~'   // standard CSS3 combinators
+ *
+ *    A combinator is a space or punctuation character that specifies the
+ *    relationship between two nodeSelectors. A space between two
+ *    nodeSelectors means that the first selector much match an ancestor of
+ *    the node that matches the second selector. A '>' character means that
+ *    the first selector must match the parent of the node matched by the
+ *    second. The '~' combinator means that the first selector must match a
+ *    previous sibling of the node matched by the second. And the '+' selector
+ *    means that first selector must match the immediate previous sibling of
+ *    the node that matched the second.
+ *
+ * nodeSelector := <IDENTIFIER> | '*'
+ *
+ *    A nodeSelector is simply an identifier (a letter followed by any number
+ *    of letters, digits, hypens, and underscores) or the wildcard asterisk
+ *    character. A wildcard node selector matches any node. An identifier
+ *    selector matches any node that has a `type` property whose value matches
+ *    the identifier.
+ *
+ * If you call Selector.parse() on a string that does not match this grammar,
+ * it will throw an exception
+ *
+ * TODO(davidflanagan): it might be useful to allow more sophsticated node
+ * selector matching with attribute matches and pseudo-classes, like
+ * "heading[level=2]" or "paragraph:first-child"
+ *
+ * Implementation Note: this file exports a very simple Selector class but all
+ * the actual work is done in various internal classes. The Parser class
+ * parses the string representation of a selector into a parse tree that
+ * consists of instances of various subclasses of the Selector class. It is
+ * these subclasses that implement the selector matching logic, often
+ * depending on features of the TraversalState object from the TreeTransformer
+ * traversal.
+ */
+
 /**
  * This is the base class for all Selector types. The key method that all
  * selector subclasses must implement is match(). It takes a TraversalState
@@ -519,6 +606,7 @@ class SiblingCombinator extends SelectorCombinator {
  * the Perseus article or exercise that is being linted.
  */
 
+
 // This represents the type returned by String.match(). It is an
 // array of strings, but also has index:number and input:string properties.
 // TypeScript doesn't handle it well, so we punt and just use any.
@@ -628,6 +716,8 @@ class Rule {
       // If we get here, then the selector and pattern have matched
       // so now we call the lint function to see if there is lint.
       const error = this.lint(traversalState, content, selectorMatch, patternMatch, context);
+
+      // eslint-disable-next-line @typescript-eslint/strict-boolean-expressions
       if (!error) {
         return null; // No lint; we're done
       }
@@ -699,6 +789,7 @@ ${e.stack}`,
   //   input "/foo/i"  ==> output /foo/i
   //
   static makePattern(pattern) {
+    // eslint-disable-next-line @typescript-eslint/strict-boolean-expressions
     if (!pattern) {
       return null;
     }
@@ -1058,6 +1149,7 @@ var ImageWidget = Rule.makeRule({
     }
 
     // If it can't find a definition for the widget it does nothing
+    // eslint-disable-next-line @typescript-eslint/strict-boolean-expressions
     const widget = context && context.widgets && context.widgets[nodeId];
     if (!widget) {
       return;
@@ -1302,6 +1394,11 @@ do not put widgets inside of tables.`
 });
 
 // TODO(davidflanagan):
+// This should probably be converted to use import and to export
+// and object that maps rule names to rules. Also, maybe this should
+// be an auto-generated file with a script that updates it any time
+// we add a new rule?
+
 var AllRules = [AbsoluteUrl, BlockquotedMath, BlockquotedWidget, DoubleSpacingAfterTerminal, ImageUrlEmpty, ExpressionWidget, ExtraContentSpacing, HeadingLevel1, HeadingLevelSkip, HeadingSentenceCase, HeadingTitleCase, ImageAltText, ImageInTable, LinkClickHere, LongParagraph, MathAdjacent, MathAlignExtraBreak, MathAlignLinebreaks, MathEmpty, MathFrac, MathNested, MathStartsWithSpace, MathTextEmpty, NestedLists, StaticWidgetInQuestionStem, TableMissingCells, UnescapedDollar, WidgetInTable, MathWithoutDollars, UnbalancedCodeDelimiters, ImageSpacesAroundUrls, ImageWidget];
 
 /**
@@ -1362,6 +1459,7 @@ var AllRules = [AbsoluteUrl, BlockquotedMath, BlockquotedWidget, DoubleSpacingAf
  * methods are available to the traversal callback.
  **/
 
+
 // TreeNode is the type of a node in a parse tree. The only real requirement is
 // that every node has a string-valued `type` property
 
@@ -1594,6 +1692,7 @@ class TraversalState {
 
     // If we're at the root of the tree or if the parent is an
     // object instead of an array, then there are no siblings.
+    // eslint-disable-next-line @typescript-eslint/strict-boolean-expressions
     if (!siblings || !Array.isArray(siblings)) {
       return null;
     }
@@ -1615,6 +1714,7 @@ class TraversalState {
 
     // If we're at the root of the tree or if the parent is an
     // object instead of an array, then there are no siblings.
+    // eslint-disable-next-line @typescript-eslint/strict-boolean-expressions
     if (!siblings || !Array.isArray(siblings)) {
       return null;
     }
@@ -1634,6 +1734,7 @@ class TraversalState {
    */
   removeNextSibling() {
     const siblings = this._containers.top();
+    // eslint-disable-next-line @typescript-eslint/strict-boolean-expressions
     if (siblings && Array.isArray(siblings)) {
       // top index is a number because top container is an array
       const index = this._indexes.top();
@@ -1657,6 +1758,7 @@ class TraversalState {
    */
   replace(...replacements) {
     const parent = this._containers.top();
+    // eslint-disable-next-line @typescript-eslint/strict-boolean-expressions
     if (!parent) {
       throw new PerseusError("Can't replace the root of the tree", Errors.Internal);
     }
@@ -1746,7 +1848,9 @@ class TraversalState {
     // and more as needed until we restore the invariant that
     // this._containers.top()[this.indexes.top()] === this._currentNode
     //
-    while (this._containers.size() && this._containers.top()[this._indexes.top()] !== this._currentNode) {
+    while (
+    // eslint-disable-next-line @typescript-eslint/strict-boolean-expressions
+    this._containers.size() && this._containers.top()[this._indexes.top()] !== this._currentNode) {
       this._containers.pop();
       this._indexes.pop();
     }
@@ -1831,6 +1935,7 @@ class Stack {
    * the two arrays are the same.
    */
   equals(that) {
+    // eslint-disable-next-line @typescript-eslint/strict-boolean-expressions
     if (!that || !that.stack || that.stack.length !== this.stack.length) {
       return false;
     }
@@ -1844,11 +1949,15 @@ class Stack {
 }
 
 // This file is processed by a Rollup plugin (replace) to inject the production
+// version number during the release build.
+// In dev, you'll never see the version number.
+
 const libName = "@khanacademy/perseus-linter";
-const libVersion = "1.3.7";
+const libVersion = "3.0.0";
 addLibraryVersionToPerseusDebug(libName, libVersion);
 
 // Define the shape of the linter context object that is passed through the
+// tree with additional information about what we are checking.
 const linterContextProps = PropTypes.shape({
   contentType: PropTypes.string,
   highlightLint: PropTypes.bool,
@@ -1977,6 +2086,7 @@ function runLinter(tree, context, highlight, rules = allLintRules) {
     // If the node we are currently at is a table, and there was lint
     // inside the table, then we want to add that lint here
     if (node.type === "table") {
+      // eslint-disable-next-line @typescript-eslint/strict-boolean-expressions
       if (tableWarnings.length) {
         nodeWarnings.push(...tableWarnings);
       }
@@ -1998,6 +2108,7 @@ function runLinter(tree, context, highlight, rules = allLintRules) {
     // If we are inside a table and there were any warnings on
     // this node, then we need to save the warnings for display
     // on the table itself
+    // eslint-disable-next-line @typescript-eslint/strict-boolean-expressions
     if (insideTable && nodeWarnings.length) {
       // @ts-expect-error - TS2345 - Argument of type 'any' is not assignable to parameter of type 'never'.
       tableWarnings.push(...nodeWarnings);
@@ -2016,6 +2127,7 @@ function runLinter(tree, context, highlight, rules = allLintRules) {
     // Note that even if we're inside a table, we still reparent the
     // linty node so that it can be highlighted. We just make a note
     // of whether this lint is inside a table or not.
+    // eslint-disable-next-line @typescript-eslint/strict-boolean-expressions
     if (nodeWarnings.length) {
       nodeWarnings.sort((a, b) => {
         return a.severity - b.severity;