@khanacademy/perseus-linter 0.0.0-PR789-20231101163312 → 0.0.0-PR790-20231103191602

package/CHANGELOG.md

@@ -1,12 +1,12 @@
 # @khanacademy/perseus-linter
 
-## 0.0.0-PR789-20231101163312
+## 0.0.0-PR790-20231103191602
 
 ### Patch Changes
 
 -   Updated dependencies [[`79403e06`](https://github.com/Khan/perseus/commit/79403e06eedb597d7818d6c858bbba6f51ff3fe1)]:
-    -   @khanacademy/perseus-core@0.0.0-PR789-20231101163312
-    -   @khanacademy/perseus-error@0.0.0-PR789-20231101163312
+    -   @khanacademy/perseus-core@0.0.0-PR790-20231103191602
+    -   @khanacademy/perseus-error@0.0.0-PR790-20231103191602
 
 ## 0.3.7
 

package/dist/es/index.js

@@ -61,12 +61,12 @@ class Selector {
  * Instead call the static Selector.parse() method.
  */
 class Parser {
-  // We do lexing with a simple regular expression
-  // The array of tokens
   // Which token in the array we're looking at now
 
   constructor(s) {
+    // We do lexing with a simple regular expression
     this.tokens = void 0;
+    // The array of tokens
     this.tokenIndex = void 0;
     // Normalize whitespace:
     // - remove leading and trailing whitespace
@@ -535,28 +535,46 @@ class SiblingCombinator extends SelectorCombinator {
  * object associated with that content string in the JSON object that defines
  * 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.
+// This is the return type of the check() method of a Rule object
+// This is the return type of the lint detection function passed as the 4th
+// argument to the Rule() constructor. It can return null or a string or an
+// object containing a string and two numbers.
+// prettier-ignore
+// (prettier formats this in a way that ka-lint does not like)
+// This is the type of the lint detection function that the Rule() constructor
+// expects as its fourth argument. It is passed the TraversalState object and
+// content string that were passed to check(), and is also passed the array of
+// nodes returned by the selector match and the array of strings returned by
+// the pattern match. It should return null if no lint is detected or an
+// error message or an object contining an error message.
+// An optional check to verify whether or not a particular rule should
+// be checked by context. For example, some rules only apply in exercises,
+// and should never be applied to articles. Defaults to true, so if we
+// omit the applies function in a rule, it'll be tested everywhere.
 /**
  * A Rule object describes a Perseus lint rule. See the comment at the top of
  * this file for detailed description.
  */
 class Rule {
-  // The name of the rule
-  // The severity of the rule
-  // The specified selector or the DEFAULT_SELECTOR
-  // A regular expression if one was specified
-  // The lint-testing function or a default
-  // Checks to see if we should apply a rule or not
-  // The error message for use with the default function
-
   // The comment at the top of this file has detailed docs for
   // this constructor and its arguments
   constructor(name, severity, selector, pattern, lint, applies) {
     this.name = void 0;
+    // The name of the rule
     this.severity = void 0;
+    // The severity of the rule
     this.selector = void 0;
+    // The specified selector or the DEFAULT_SELECTOR
     this.pattern = void 0;
+    // A regular expression if one was specified
     this.lint = void 0;
+    // The lint-testing function or a default
     this.applies = void 0;
+    // Checks to see if we should apply a rule or not
     this.message = void 0;
     if (!selector && !pattern) {
       throw new PerseusError("Lint rules must have a selector or pattern", Errors.InvalidInput, {
@@ -721,6 +739,7 @@ ${e.stack}`,
     return result;
   }
 }
+// The error message for use with the default function
 Rule.DEFAULT_SELECTOR = void 0;
 Rule.Severity = {
   ERROR: 1,
@@ -1273,7 +1292,9 @@ var AllRules = [AbsoluteUrl, BlockquotedMath, BlockquotedWidget, DoubleSpacingAf
 
 // 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
-
+// TraversalCallback is the type of the callback function passed to the
+// traverse() method. It is invoked with node, state, and content arguments
+// and is expected to return nothing.
 // This is the TreeTransformer class described in detail at the
 // top of this file.
 class TreeTransformer {
@@ -1424,18 +1445,16 @@ class TreeTransformer {
  * type annotaions.
  **/
 class TraversalState {
-  // The root node of the tree being traversed
-
-  // These are internal state properties. Use the accessor methods defined
-  // below instead of using these properties directly. Note that the
-  // _containers and _indexes stacks can have two different types of
-  // elements, depending on whether we just recursed on an array or on a
-  // node. This is hard for TypeScript to deal with, so you'll see a number of
-  // type casts through the any type when working with these two properties.
-
   // The constructor just stores the root node and creates empty stacks.
   constructor(root) {
+    // The root node of the tree being traversed
     this.root = void 0;
+    // These are internal state properties. Use the accessor methods defined
+    // below instead of using these properties directly. Note that the
+    // _containers and _indexes stacks can have two different types of
+    // elements, depending on whether we just recursed on an array or on a
+    // node. This is hard for TypeScript to deal with, so you'll see a number of
+    // type casts through the any type when working with these two properties.
     this._currentNode = void 0;
     this._containers = void 0;
     this._indexes = void 0;