@khanacademy/perseus-linter 0.1.0

package/src/README.md

@@ -0,0 +1,41 @@
+# perseus-linter
+
+The linter is implemented by the following files:
+
+tree-transformer.js:
+
+  This file defines a TreeTransformer class for traversing (and
+  optionally transforming by inserting, reparenting and removing
+  nodes) markdown parse trees. When traversing a tree, a
+  TreeTransformer calls the function you specify on each node. This is
+  a post-order traversal: the function is called on the way back up,
+  not on the way down. When the function is invoked, it is passed the
+  current node, a state object, and the concatenated content of the
+  node and its descendants.  The state object is the interesting one:
+  it is an instance of TraversalState, which is a class defined in
+  (but not exported by) this same file. TraversalState has an API for
+  querying the ancestors and siblings of the current node, and also an
+  API for replacing the current node with a new one.
+
+selector.js:
+
+  This file defines the Selector class which works like a CSS selector
+  for markdown parse trees. Selector.parse() converts strings like
+  "heading + paragraph > text" to Selector objects. A Selector object
+  has a match() method that tests whether a given node in a parse tree
+  matches. The match() method takes a TraversalState object as its
+  argument, so selectors can only be used during a TreeTransformer
+  traversal.
+
+rule.js:
+
+  This file defines the Rule class which represents a single lint
+  rule. A Rule object has a check() method that takes the same (node,
+  state, content) arguments that a TreeTransformer passes to the
+  traversal callback function. Rules can have a selector, a regular
+  expression, and a function. If a node matches the selector and its
+  content matches the regular expression, then the function is called
+  to check the node and return a warning message if the node does, in
+  fact, have lint.
+
+See the individual file for additional documentation.

package/src/__tests__/matcher_test.js

@@ -0,0 +1,498 @@
+// @flow
+/* These tests exercise the Selector.match() method and also test that we
+ * can integrate ../../perseus-markdown.js with ../tree-transform.js and
+ * ../selector.js
+ */
+import * as PureMarkdown from "@khanacademy/pure-markdown";
+
+import Selector from "../selector.js";
+import TreeTransformer from "../tree-transformer.js";
+
+describe("Gorgon selector matching:", () => {
+    const markdown = `
+### A
+
+B
+
+C
+
+- D
+- E
+- F
+
+*G*H
+`;
+
+    function parseTree() {
+        return PureMarkdown.parse(markdown);
+    }
+
+    it("wildcards match every node", () => {
+        const tree = parseTree();
+        const selector = Selector.parse("*");
+        const tt = new TreeTransformer(tree);
+        tt.traverse((n, state, content) => {
+            // The wildcard selector should match at every node
+            // $FlowFixMe[incompatible-use]
+            expect(selector.match(state)[0]).toEqual(n);
+        });
+    });
+
+    it("type-based matching works", () => {
+        const tree = parseTree();
+        const selectors = {};
+        const tt = new TreeTransformer(tree);
+
+        // Traverse the tree once and create a selector for every type
+        // of node we find
+        tt.traverse((n, state, content) => {
+            if (!selectors[n.type]) {
+                selectors[n.type] = Selector.parse(n.type);
+            }
+        });
+
+        const types = Object.keys(selectors);
+
+        // Now traverse the tree again. At each node run all of the
+        // selectors we've created. Only those with matching types
+        // should match.
+        tt.traverse((n, state, content) => {
+            types.forEach((type) => {
+                const selector = selectors[type];
+                const match = selector.match(state);
+                if (n.type === type) {
+                    expect(match[0]).toEqual(n);
+                } else {
+                    expect(match).toEqual(null);
+                }
+            });
+
+            if (!selectors[n.type]) {
+                selectors[n.type] = Selector.parse(n.type);
+            }
+        });
+    });
+
+    it("parent combinator", () => {
+        const selector = Selector.parse("paragraph > text");
+        const tree = parseTree();
+        const tt = new TreeTransformer(tree);
+        let numMatches = 0;
+        let matchedText = "";
+
+        tt.traverse((n, state, content) => {
+            const match = selector.match(state);
+            const parent = state.parent();
+            // $FlowFixMe[incompatible-use]
+            // $FlowFixMe[incompatible-type]
+            if (n.type === "text" && parent.type === "paragraph") {
+                expect(Array.isArray(match)).toBeTruthy();
+                expect(match).toHaveLength(2);
+                // $FlowFixMe[incompatible-use]
+                expect(match[0]).toEqual(parent);
+                // $FlowFixMe[incompatible-use]
+                expect(match[1]).toEqual(n);
+                matchedText += content;
+                numMatches++;
+            } else {
+                expect(match).toEqual(null);
+            }
+        });
+
+        expect(numMatches).toEqual(3);
+        expect(matchedText).toEqual("BCH");
+    });
+
+    it("double parent combinator", () => {
+        const selector = Selector.parse("paragraph > em > text");
+        const tree = parseTree();
+        const tt = new TreeTransformer(tree);
+        let numMatches = 0;
+        let matchedText = "";
+
+        tt.traverse((n, state, content) => {
+            const match = selector.match(state);
+            // Make a mutable copy before popping.
+            const ancestors = [...state.ancestors()];
+            const parent = ancestors.pop();
+            const grandparent = ancestors.pop();
+            if (
+                n.type === "text" &&
+                parent.type === "em" &&
+                grandparent.type === "paragraph"
+            ) {
+                expect(Array.isArray(match)).toBeTruthy();
+                expect(match).toHaveLength(3);
+                // $FlowFixMe[incompatible-use]
+                expect(match[0]).toEqual(grandparent);
+                // $FlowFixMe[incompatible-use]
+                expect(match[1]).toEqual(parent);
+                // $FlowFixMe[incompatible-use]
+                expect(match[2]).toEqual(n);
+                matchedText += content;
+                numMatches++;
+            } else {
+                expect(match).toEqual(null);
+            }
+        });
+
+        expect(numMatches).toEqual(1);
+        expect(matchedText).toEqual("G");
+    });
+
+    it("ancestor combinator", () => {
+        const selector = Selector.parse("paragraph text");
+        const tree = parseTree();
+        const tt = new TreeTransformer(tree);
+        let numMatches = 0;
+        let matchedText = "";
+
+        tt.traverse((n, state, content) => {
+            const match = selector.match(state);
+            if (match !== null) {
+                expect(Array.isArray(match)).toBeTruthy();
+                expect(match).toHaveLength(2);
+                // $FlowFixMe[incompatible-use]
+                expect(match[0].type).toEqual("paragraph");
+                // $FlowFixMe[incompatible-use]
+                expect(match[1].type).toEqual("text");
+                // $FlowFixMe[incompatible-use]
+                expect(match[1]).toEqual(n);
+                matchedText += content;
+                numMatches++;
+            }
+        });
+
+        expect(numMatches).toEqual(4);
+        expect(matchedText).toEqual("BCGH");
+    });
+
+    it("double ancestor combinator", () => {
+        const selector = Selector.parse("paragraph em text");
+        const tree = parseTree();
+        const tt = new TreeTransformer(tree);
+        let numMatches = 0;
+        let matchedText = "";
+
+        tt.traverse((n, state, content) => {
+            const match = selector.match(state);
+            if (match !== null) {
+                expect(Array.isArray(match)).toBeTruthy();
+                expect(match).toHaveLength(3);
+                // $FlowFixMe[incompatible-use]
+                expect(match[0].type).toEqual("paragraph");
+                // $FlowFixMe[incompatible-use]
+                expect(match[1].type).toEqual("em");
+                // $FlowFixMe[incompatible-use]
+                expect(match[2].type).toEqual("text");
+                // $FlowFixMe[incompatible-use]
+                expect(match[2]).toEqual(n);
+                matchedText += content;
+                numMatches++;
+            }
+        });
+
+        expect(numMatches).toEqual(1);
+        expect(matchedText).toEqual("G");
+    });
+
+    it("previous combinator", () => {
+        const selector = Selector.parse("heading + paragraph");
+        const tree = parseTree();
+        const tt = new TreeTransformer(tree);
+        let numMatches = 0;
+        let matchedText = "";
+
+        tt.traverse((n, state, content) => {
+            const match = selector.match(state);
+            if (match !== null) {
+                expect(Array.isArray(match)).toBeTruthy();
+                expect(match).toHaveLength(2);
+                // $FlowFixMe[incompatible-use]
+                expect(match[0].type).toEqual("heading");
+                // $FlowFixMe[incompatible-use]
+                expect(match[0]).toEqual(state.previousSibling());
+                // $FlowFixMe[incompatible-use]
+                expect(match[1].type).toEqual("paragraph");
+                // $FlowFixMe[incompatible-use]
+                expect(match[1]).toEqual(n);
+                matchedText += content;
+                numMatches++;
+            }
+        });
+
+        expect(numMatches).toEqual(1);
+        expect(matchedText).toEqual("B");
+    });
+
+    it("double previous combinator", () => {
+        const selector = Selector.parse("heading + paragraph + paragraph");
+        const tree = parseTree();
+        const tt = new TreeTransformer(tree);
+        let numMatches = 0;
+        let matchedText = "";
+
+        tt.traverse((n, state, content) => {
+            const match = selector.match(state);
+            if (match !== null) {
+                expect(Array.isArray(match)).toBeTruthy();
+                expect(match).toHaveLength(3);
+                // $FlowFixMe[incompatible-use]
+                expect(match[0].type).toEqual("heading");
+                // $FlowFixMe[incompatible-use]
+                expect(match[1].type).toEqual("paragraph");
+                // $FlowFixMe[incompatible-use]
+                expect(match[1]).toEqual(state.previousSibling());
+                // $FlowFixMe[incompatible-use]
+                expect(match[2].type).toEqual("paragraph");
+                // $FlowFixMe[incompatible-use]
+                expect(match[2]).toEqual(n);
+                matchedText += content;
+                numMatches++;
+            }
+        });
+
+        expect(numMatches).toEqual(1);
+        expect(matchedText).toEqual("C");
+    });
+
+    it("sibling combinator", () => {
+        const selector = Selector.parse("heading ~ paragraph");
+        const tree = parseTree();
+        const tt = new TreeTransformer(tree);
+        let numMatches = 0;
+        let matchedText = "";
+
+        tt.traverse((n, state, content) => {
+            const match = selector.match(state);
+            if (match !== null) {
+                expect(Array.isArray(match)).toBeTruthy();
+                expect(match).toHaveLength(2);
+                // $FlowFixMe[incompatible-use]
+                expect(match[0].type).toEqual("heading");
+                // $FlowFixMe[incompatible-use]
+                expect(match[1].type).toEqual("paragraph");
+                // $FlowFixMe[incompatible-use]
+                expect(match[1]).toEqual(n);
+                matchedText += content;
+                numMatches++;
+            }
+        });
+
+        expect(numMatches).toEqual(3);
+        expect(matchedText).toEqual("BCGH");
+    });
+
+    it("double sibling combinator", () => {
+        const selector = Selector.parse("heading ~ paragraph ~ paragraph");
+        const tree = parseTree();
+        const tt = new TreeTransformer(tree);
+        let numMatches = 0;
+        let matchedText = "";
+
+        tt.traverse((n, state, content) => {
+            const match = selector.match(state);
+            if (match !== null) {
+                expect(Array.isArray(match)).toBeTruthy();
+                expect(match).toHaveLength(3);
+                // $FlowFixMe[incompatible-use]
+                expect(match[0].type).toEqual("heading");
+                // $FlowFixMe[incompatible-use]
+                expect(match[1].type).toEqual("paragraph");
+                // $FlowFixMe[incompatible-use]
+                expect(match[2].type).toEqual("paragraph");
+                // $FlowFixMe[incompatible-use]
+                expect(match[2]).toEqual(n);
+                matchedText += content;
+                numMatches++;
+            }
+        });
+
+        expect(numMatches).toEqual(2);
+        expect(matchedText).toEqual("CGH");
+    });
+
+    it("mixed combinators", () => {
+        const selector = Selector.parse("list + paragraph > em");
+        const tree = parseTree();
+        const tt = new TreeTransformer(tree);
+        let numMatches = 0;
+        let matchedText = "";
+
+        tt.traverse((n, state, content) => {
+            const match = selector.match(state);
+            if (match !== null) {
+                expect(Array.isArray(match)).toBeTruthy();
+                expect(match).toHaveLength(3);
+                // $FlowFixMe[incompatible-use]
+                expect(match[0].type).toEqual("list");
+                // $FlowFixMe[incompatible-use]
+                expect(match[1].type).toEqual("paragraph");
+                // $FlowFixMe[incompatible-use]
+                expect(match[1]).toEqual(state.parent());
+                // $FlowFixMe[incompatible-use]
+                expect(match[2].type).toEqual("em");
+                // $FlowFixMe[incompatible-use]
+                expect(match[2]).toEqual(n);
+                matchedText += content;
+                numMatches++;
+            }
+        });
+
+        expect(numMatches).toEqual(1);
+        expect(matchedText).toEqual("G");
+    });
+
+    it("mixed combinators 2", () => {
+        const selector = Selector.parse("list ~ paragraph em");
+        const tree = parseTree();
+        const tt = new TreeTransformer(tree);
+        let numMatches = 0;
+        let matchedText = "";
+
+        tt.traverse((n, state, content) => {
+            const match = selector.match(state);
+            if (match !== null) {
+                expect(Array.isArray(match)).toBeTruthy();
+                expect(match).toHaveLength(3);
+                // $FlowFixMe[incompatible-use]
+                expect(match[0].type).toEqual("list");
+                // $FlowFixMe[incompatible-use]
+                expect(match[1].type).toEqual("paragraph");
+                // $FlowFixMe[incompatible-use]
+                expect(match[1]).toEqual(state.parent());
+                // $FlowFixMe[incompatible-use]
+                expect(match[2].type).toEqual("em");
+                // $FlowFixMe[incompatible-use]
+                expect(match[2]).toEqual(n);
+                matchedText += content;
+                numMatches++;
+            }
+        });
+
+        expect(numMatches).toEqual(1);
+        expect(matchedText).toEqual("G");
+    });
+
+    it("mixed combinators 3", () => {
+        const selector = Selector.parse("paragraph > em + text");
+        const tree = parseTree();
+        const tt = new TreeTransformer(tree);
+        let numMatches = 0;
+        let matchedText = "";
+
+        tt.traverse((n, state, content) => {
+            const match = selector.match(state);
+            if (match !== null) {
+                expect(Array.isArray(match)).toBeTruthy();
+                expect(match).toHaveLength(3);
+                // $FlowFixMe[incompatible-use]
+                expect(match[0].type).toEqual("paragraph");
+                // $FlowFixMe[incompatible-use]
+                expect(match[0]).toEqual(state.parent());
+                // $FlowFixMe[incompatible-use]
+                expect(match[1].type).toEqual("em");
+                // $FlowFixMe[incompatible-use]
+                expect(match[1]).toEqual(state.previousSibling());
+                // $FlowFixMe[incompatible-use]
+                expect(match[2].type).toEqual("text");
+                // $FlowFixMe[incompatible-use]
+                expect(match[2]).toEqual(n);
+                matchedText += content;
+                numMatches++;
+            }
+        });
+
+        expect(numMatches).toEqual(1);
+        expect(matchedText).toEqual("H");
+    });
+
+    it("mixed combinators 4", () => {
+        const selector = Selector.parse("paragraph em ~ text");
+        const tree = parseTree();
+        const tt = new TreeTransformer(tree);
+        let numMatches = 0;
+        let matchedText = "";
+
+        tt.traverse((n, state, content) => {
+            const match = selector.match(state);
+            if (match !== null) {
+                expect(Array.isArray(match)).toBeTruthy();
+                expect(match).toHaveLength(3);
+                // $FlowFixMe[incompatible-use]
+                expect(match[0].type).toEqual("paragraph");
+                // $FlowFixMe[incompatible-use]
+                expect(match[0]).toEqual(state.parent());
+                // $FlowFixMe[incompatible-use]
+                expect(match[1].type).toEqual("em");
+                // $FlowFixMe[incompatible-use]
+                expect(match[1]).toEqual(state.previousSibling());
+                // $FlowFixMe[incompatible-use]
+                expect(match[2].type).toEqual("text");
+                // $FlowFixMe[incompatible-use]
+                expect(match[2]).toEqual(n);
+                matchedText += content;
+                numMatches++;
+            }
+        });
+
+        expect(numMatches).toEqual(1);
+        expect(matchedText).toEqual("H");
+    });
+
+    it("selector list", () => {
+        const selector = Selector.parse("paragraph, list");
+        const tree = parseTree();
+        const tt = new TreeTransformer(tree);
+        let numMatches = 0;
+        let matchedText = "";
+
+        tt.traverse((n, state, content) => {
+            const match = selector.match(state);
+            if (match !== null) {
+                expect(Array.isArray(match)).toBeTruthy();
+                expect(match).toHaveLength(1);
+                // $FlowFixMe[incompatible-use]
+                expect(match[0]).toEqual(n);
+                expect(
+                    n.type === "paragraph" || n.type === "list",
+                ).toBeTruthy();
+                matchedText += content;
+                numMatches++;
+            }
+        });
+
+        expect(numMatches).toEqual(4);
+        expect(matchedText).toEqual("BCDEFGH");
+    });
+
+    it("selector list 2", () => {
+        const selector = Selector.parse("heading, paragraph text, list>text");
+        const tree = parseTree();
+        const tt = new TreeTransformer(tree);
+        let numMatches = 0;
+        let matchedText = "";
+
+        tt.traverse((n, state, content) => {
+            const match = selector.match(state);
+            if (match !== null) {
+                expect(Array.isArray(match)).toBeTruthy();
+                if (n.type === "heading") {
+                    expect(match).toHaveLength(1);
+                    // $FlowFixMe[incompatible-use]
+                    expect(match[0]).toEqual(n);
+                } else {
+                    expect(match).toHaveLength(2);
+                    // $FlowFixMe[incompatible-use]
+                    expect(match[1]).toEqual(n);
+                    expect(n.type).toEqual("text");
+                }
+                matchedText += content;
+                numMatches++;
+            }
+        });
+
+        expect(numMatches).toEqual(8);
+        expect(matchedText).toEqual("ABCDEFGH");
+    });
+});

package/src/__tests__/rule_test.js

@@ -0,0 +1,102 @@
+// @flow
+import * as PureMarkdown from "@khanacademy/pure-markdown";
+
+import Rule from "../rule.js";
+import TreeTransformer from "../tree-transformer.js";
+
+describe("Gorgon lint Rules class", () => {
+    const markdown = `
+## This Heading is in Title Case
+
+This paragraph contains forbidden words. Poop!
+
+This paragraph contains an unescaped $ sign.
+
+#### This heading skipped a level
+`;
+
+    const ruleDescriptions = [
+        {
+            name: "heading-title-case",
+            selector: "heading",
+            pattern: "\\s[A-Z][a-z]",
+            message: `Title case in heading:
+Only capitalize the first word of headings.`,
+        },
+        {
+            name: "profanity",
+            pattern: "/poop|crap/i",
+            message: `Profanity:
+this is a family website!`,
+        },
+        {
+            name: "unescaped-dollar",
+            selector: "unescapedDollar",
+            message: `Unescaped '$':
+If writing math, pair with another $.
+Otherwise escape it by writing \\$.`,
+        },
+        {
+            name: "heading-level-skip",
+            selector: "heading ~ heading",
+            lint: function (state, content, nodes) {
+                const currentHeading = nodes[1];
+                const previousHeading = nodes[0];
+
+                expect(nodes).toHaveLength(2);
+                expect(nodes[1]).toEqual(state.currentNode());
+
+                // A heading can have a level less than, the same as
+                // or one more than the previous heading. But going up
+                // by 2 or more levels is not right
+                if (currentHeading.level > previousHeading.level + 1) {
+                    return `Skipped heading level:
+this heading is level ${currentHeading.level} but
+the previous heading was level ${previousHeading.level}`;
+                }
+                return false;
+            },
+        },
+    ];
+
+    let rules = [];
+
+    function parseTree() {
+        return PureMarkdown.parse(markdown);
+    }
+
+    it("makeRules() factory method", () => {
+        rules = ruleDescriptions.map((r) => Rule.makeRule(r));
+        expect(rules).toHaveLength(ruleDescriptions.length);
+        rules.forEach((r) => expect(r instanceof Rule).toBeTruthy());
+    });
+
+    it("check() method", () => {
+        const tree = parseTree();
+        const tt = new TreeTransformer(tree);
+        const warnings = [];
+
+        tt.traverse((node, state, content) => {
+            rules.forEach((r) => {
+                const lint = r.check(node, state, content);
+                if (lint) {
+                    warnings.push(lint);
+                }
+            });
+        });
+
+        expect(warnings).toHaveLength(4);
+        expect(warnings[0].rule).toEqual(ruleDescriptions[0].name);
+        expect(warnings[0].message).toEqual(ruleDescriptions[0].message);
+
+        expect(warnings[1].rule).toEqual(ruleDescriptions[1].name);
+        expect(warnings[1].message).toEqual(ruleDescriptions[1].message);
+        expect(warnings[1].start).toEqual(2);
+        expect(warnings[1].end).toEqual(6);
+
+        expect(warnings[2].rule).toEqual(ruleDescriptions[2].name);
+        expect(warnings[2].message).toEqual(ruleDescriptions[2].message);
+
+        expect(warnings[3].rule).toEqual(ruleDescriptions[3].name);
+    });
+});