@khanacademy/perseus-linter 0.1.0

package/src/rules/image-alt-text.js

@@ -0,0 +1,21 @@
+// @flow
+import Rule from "../rule.js";
+
+export default (Rule.makeRule({
+    name: "image-alt-text",
+    severity: Rule.Severity.WARNING,
+    selector: "image",
+    lint: function (state, content, nodes, match) {
+        const image = nodes[0];
+        if (!image.alt || !image.alt.trim()) {
+            return `Images should have alt text:
+for accessibility, all images should have alt text.
+Specify alt text inside square brackets after the !.`;
+        }
+        if (image.alt.length < 8) {
+            return `Images should have alt text:
+for accessibility, all images should have descriptive alt text.
+This image's alt text is only ${image.alt.length} characters long.`;
+        }
+    },
+}): Rule);

package/src/rules/image-in-table.js

@@ -0,0 +1,10 @@
+// @flow
+import Rule from "../rule.js";
+
+export default (Rule.makeRule({
+    name: "image-in-table",
+    severity: Rule.Severity.BULK_WARNING,
+    selector: "table image",
+    message: `Image in table:
+do not put images inside of tables.`,
+}): Rule);

package/src/rules/image-spaces-around-urls.js

@@ -0,0 +1,35 @@
+// @flow
+import Rule from "../rule.js";
+
+export default (Rule.makeRule({
+    name: "image-spaces-around-urls",
+    severity: Rule.Severity.ERROR,
+    selector: "image",
+    lint: function (state, content, nodes, match, context) {
+        const image = nodes[0];
+        const url = image.target;
+
+        // The markdown parser strips leading and trailing spaces for us,
+        // but they're still a problem for our translation process, so
+        // we need to go check for them in the unparsed source string
+        // if we have it.
+        if (context && context.content) {
+            // Find the url in the original content and make sure that the
+            // character before is '(' and the character after is ')'
+            const index = context.content.indexOf(url);
+            if (index === -1) {
+                // It is not an error if we didn't find it.
+                return;
+            }
+
+            if (
+                context.content[index - 1] !== "(" ||
+                context.content[index + url.length] !== ")"
+            ) {
+                return `Whitespace before or after image url:
+For images, don't include any space or newlines after '(' or before ')'.
+Whitespace in image URLs causes translation difficulties.`;
+            }
+        }
+    },
+}): Rule);

package/src/rules/image-widget.js

@@ -0,0 +1,50 @@
+// @flow
+import Rule from "../rule.js";
+
+// Normally we have one rule per file. But since our selector class
+// can't match specific widget types directly, this rule implements
+// a number of image widget related rules in one place. This should
+// slightly increase efficiency, but it means that if there is more
+// than one problem with an image widget, the user will only see one
+// problem at a time.
+export default (Rule.makeRule({
+    name: "image-widget",
+    severity: Rule.Severity.WARNING,
+    selector: "widget",
+    lint: function (state, content, nodes, match, context) {
+        // This rule only looks at image widgets
+        if (state.currentNode().widgetType !== "image") {
+            return;
+        }
+
+        // If it can't find a definition for the widget it does nothing
+        const widget =
+            context &&
+            context.widgets &&
+            context.widgets[state.currentNode().id];
+        if (!widget) {
+            return;
+        }
+
+        // Make sure there is alt text
+        const alt = widget.options.alt;
+        if (!alt) {
+            return `Images should have alt text:
+for accessibility, all images should have a text description.
+Add a description in the "Alt Text" box of the image widget.`;
+        }
+
+        // Make sure the alt text it is not trivial
+        if (alt.trim().length < 8) {
+            return `Images should have alt text:
+for accessibility, all images should have descriptive alt text.
+This image's alt text is only ${alt.trim().length} characters long.`;
+        }
+
+        // Make sure there is no math in the caption
+        if (widget.options.caption && widget.options.caption.match(/[^\\]\$/)) {
+            return `No math in image captions:
+Don't include math expressions in image captions.`;
+        }
+    },
+}): Rule);

package/src/rules/link-click-here.js

@@ -0,0 +1,11 @@
+// @flow
+import Rule from "../rule.js";
+
+export default (Rule.makeRule({
+    name: "link-click-here",
+    severity: Rule.Severity.WARNING,
+    selector: "link",
+    pattern: /click here/i,
+    message: `Inappropriate link text:
+Do not use the words "click here" in links.`,
+}): Rule);

package/src/rules/lint-utils.js

@@ -0,0 +1,48 @@
+/* eslint-disable no-useless-escape */
+// @flow
+// Return the portion of a URL between // and /. This is the authority
+// portion which is usually just the hostname, but may also include
+// a username, password or port. We don't strip those things out because
+// we typically want to reject any URL that includes them
+const HOSTNAME = /\/\/([^\/]+)/;
+
+// Return the hostname of the URL, with any "www." prefix removed.
+// If this is a relative URL with no hostname, return an empty string.
+export function getHostname(url: string): string {
+    if (!url) {
+        return "";
+    }
+    const match = url.match(HOSTNAME);
+    return match ? match[1] : "";
+}
+
+// This list of domains that count as internal domains is from
+// webapp/content/models.py and webapp/url_util.py
+const internalDomains = {
+    "khanacademy.org": true,
+    "www.khanacademy.org": true,
+    "kasandbox.org": true,
+    "fastly.kastatic.org": true,
+    "cdn.kastatic.org": true, // This isn't a link to cdn.kastatic.org
+    "ka-youtube-converted.storage.googleapis.com": true,
+    "KA-share.s3.amazonaws.com": true,
+    "ka-article-iframes.s3.amazonaws.com": true,
+    "ka-cs-algorithms.s3.amazonaws.com": true,
+    "ka-cs-challenge-images.s3.amazonaws.com": true,
+    "ka-cs-scratchpad-audio.s3.amazonaws.com": true,
+    "ka-exercise-screenshots.s3.amazonaws.com": true,
+    "ka-exercise-screenshots-2.s3.amazonaws.com": true,
+    "ka-exercise-screenshots-3.s3.amazonaws.com": true,
+    "ka-learnstorm.s3.amazonaws.com": true,
+    "ka-mobile.s3.amazonaws.com": true,
+    "ka-perseus-graphie.s3.amazonaws.com": true,
+    "ka-perseus-images.s3.amazonaws.com": true,
+};
+
+// Returns true if this URL is relative, or if it is an absolute
+// URL with one of the domains listed above as its hostname.
+export function isInternalURL(url: string): boolean {
+    const hostname = getHostname(url);
+    // eslint-disable-next-line no-prototype-builtins
+    return hostname === "" || internalDomains.hasOwnProperty(hostname);
+}

package/src/rules/long-paragraph.js

@@ -0,0 +1,14 @@
+// @flow
+import Rule from "../rule.js";
+
+export default (Rule.makeRule({
+    name: "long-paragraph",
+    severity: Rule.Severity.GUIDELINE,
+    selector: "paragraph",
+    pattern: /^.{501,}/,
+    lint: function (state, content, nodes, match) {
+        return `Paragraph too long:
+This paragraph is ${content.length} characters long.
+Shorten it to 500 characters or fewer.`;
+    },
+}): Rule);

package/src/rules/math-adjacent.js

@@ -0,0 +1,10 @@
+// @flow
+import Rule from "../rule.js";
+
+export default (Rule.makeRule({
+    name: "math-adjacent",
+    severity: Rule.Severity.WARNING,
+    selector: "blockMath+blockMath",
+    message: `Adjacent math blocks:
+combine the blocks between \\begin{align} and \\end{align}`,
+}): Rule);

package/src/rules/math-align-extra-break.js

@@ -0,0 +1,11 @@
+// @flow
+import Rule from "../rule.js";
+
+export default (Rule.makeRule({
+    name: "math-align-extra-break",
+    severity: Rule.Severity.WARNING,
+    selector: "blockMath",
+    pattern: /(\\{2,})\s*\\end{align}/,
+    message: `Extra space at end of block:
+Don't end an align block with backslashes`,
+}): Rule);

package/src/rules/math-align-linebreaks.js

@@ -0,0 +1,43 @@
+// @flow
+import Rule from "../rule.js";
+
+export default (Rule.makeRule({
+    name: "math-align-linebreaks",
+    severity: Rule.Severity.WARNING,
+    selector: "blockMath",
+    // Match any align block with double backslashes in it
+    // Use [\s\S]* instead of .* so we match newlines as well.
+    pattern: /\\begin{align}[\s\S]*\\\\[\s\S]+\\end{align}/,
+    // Look for double backslashes and ensure that they are
+    // followed by optional space and another pair of backslashes.
+    // Note that this rule can't know where line breaks belong so
+    // it can't tell whether backslashes are completely missing. It just
+    // enforces that you don't have the wrong number of pairs of backslashes.
+    lint: function (state, content, nodes, match) {
+        let text = match[0];
+        while (text.length) {
+            const index = text.indexOf("\\\\");
+            if (index === -1) {
+                // No more backslash pairs, so we found no lint
+                return null;
+            }
+            text = text.substring(index + 2);
+
+            // Now we expect to find optional spaces, another pair of
+            // backslashes, and more optional spaces not followed immediately
+            // by another pair of backslashes.
+            const nextpair = text.match(/^\s*\\\\\s*(?!\\\\)/);
+
+            // If that does not match then we either have too few or too
+            // many pairs of backslashes.
+            if (!nextpair) {
+                return "Use four backslashes between lines of an align block";
+            }
+
+            // If it did match, then, shorten the string and continue looping
+            // (because a single align block may have multiple lines that
+            // all must be separated by two sets of double backslashes).
+            text = text.substring(nextpair[0].length);
+        }
+    },
+}): Rule);

package/src/rules/math-empty.js

@@ -0,0 +1,10 @@
+// @flow
+import Rule from "../rule.js";
+
+export default (Rule.makeRule({
+    name: "math-empty",
+    severity: Rule.Severity.WARNING,
+    selector: "math, blockMath",
+    pattern: /^$/,
+    message: "Empty math: don't use $$ in your markdown.",
+}): Rule);

package/src/rules/math-font-size.js

@@ -0,0 +1,12 @@
+// @flow
+import Rule from "../rule.js";
+
+export default (Rule.makeRule({
+    name: "math-font-size",
+    severity: Rule.Severity.GUIDELINE,
+    selector: "math, blockMath",
+    pattern:
+        /\\(tiny|Tiny|small|large|Large|LARGE|huge|Huge|scriptsize|normalsize)\s*{/,
+    message: `Math font size:
+Don't change the default font size with \\Large{} or similar commands`,
+}): Rule);

package/src/rules/math-frac.js

@@ -0,0 +1,10 @@
+// @flow
+import Rule from "../rule.js";
+
+export default (Rule.makeRule({
+    name: "math-frac",
+    severity: Rule.Severity.GUIDELINE,
+    selector: "math, blockMath",
+    pattern: /\\frac[ {]/,
+    message: "Use \\dfrac instead of \\frac in your math expressions.",
+}): Rule);

package/src/rules/math-nested.js

@@ -0,0 +1,11 @@
+// @flow
+import Rule from "../rule.js";
+
+export default (Rule.makeRule({
+    name: "math-nested",
+    severity: Rule.Severity.ERROR,
+    selector: "math, blockMath",
+    pattern: /\\text{[^$}]*\$[^$}]*\$[^}]*}/,
+    message: `Nested math:
+Don't nest math expressions inside \\text{} blocks`,
+}): Rule);

package/src/rules/math-starts-with-space.js

@@ -0,0 +1,12 @@
+// @flow
+import Rule from "../rule.js";
+
+export default (Rule.makeRule({
+    name: "math-starts-with-space",
+    severity: Rule.Severity.GUIDELINE,
+    selector: "math, blockMath",
+    pattern: /^\s*(~|\\qquad|\\quad|\\,|\\;|\\:|\\ |\\!|\\enspace|\\phantom)/,
+    message: `Math starts with space:
+math should not be indented. Do not begin math expressions with
+LaTeX space commands like ~, \\;, \\quad, or \\phantom`,
+}): Rule);

package/src/rules/math-text-empty.js

@@ -0,0 +1,10 @@
+// @flow
+import Rule from "../rule.js";
+
+export default (Rule.makeRule({
+    name: "math-text-empty",
+    severity: Rule.Severity.WARNING,
+    selector: "math, blockMath",
+    pattern: /\\text{\s*}/,
+    message: "Empty \\text{} block in math expression",
+}): Rule);

package/src/rules/math-without-dollars.js

@@ -0,0 +1,14 @@
+// @flow
+import Rule from "../rule.js";
+
+// Because no selector is specified, this rule only applies to text nodes.
+// Math and code hold their content directly and do not have text nodes
+// beneath them (unlike the HTML DOM) so this rule automatically does not
+// apply inside $$ or ``.
+export default (Rule.makeRule({
+    name: "math-without-dollars",
+    severity: Rule.Severity.GUIDELINE,
+    pattern: /\\\w+{[^}]*}|{|}/,
+    message: `This looks like LaTeX:
+did you mean to put it inside dollar signs?`,
+}): Rule);

package/src/rules/nested-lists.js

@@ -0,0 +1,11 @@
+// @flow
+import Rule from "../rule.js";
+
+export default (Rule.makeRule({
+    name: "nested-lists",
+    severity: Rule.Severity.WARNING,
+    selector: "list list",
+    message: `Nested lists:
+nested lists are hard to read on mobile devices;
+do not use additional indentation.`,
+}): Rule);

package/src/rules/profanity.js

@@ -0,0 +1,10 @@
+// @flow
+import Rule from "../rule.js";
+
+export default (Rule.makeRule({
+    name: "profanity",
+    // This list could obviously be expanded a lot, but I figured we
+    // could start with https://en.wikipedia.org/wiki/Seven_dirty_words
+    pattern: /\b(shit|piss|fuck|cunt|cocksucker|motherfucker|tits)\b/i,
+    message: "Avoid profanity",
+}): Rule);

package/src/rules/table-missing-cells.js

@@ -0,0 +1,20 @@
+// @flow
+import Rule from "../rule.js";
+
+export default (Rule.makeRule({
+    name: "table-missing-cells",
+    severity: Rule.Severity.WARNING,
+    selector: "table",
+    lint: function (state, content, nodes, match) {
+        const table = nodes[0];
+        const headerLength = table.header.length;
+        const rowLengths = table.cells.map((r) => r.length);
+        for (let r = 0; r < rowLengths.length; r++) {
+            if (rowLengths[r] !== headerLength) {
+                return `Table rows don't match header:
+The table header has ${headerLength} cells, but
+Row ${r + 1} has ${rowLengths[r]} cells.`;
+            }
+        }
+    },
+}): Rule);

package/src/rules/unbalanced-code-delimiters.js

@@ -0,0 +1,14 @@
+// @flow
+import Rule from "../rule.js";
+
+// Because no selector is specified, this rule only applies to text nodes.
+// Math and code hold their content directly and do not have text nodes
+// beneath them (unlike the HTML DOM) so this rule automatically does not
+// apply inside $$ or ``.
+export default (Rule.makeRule({
+    name: "unbalanced-code-delimiters",
+    severity: Rule.Severity.ERROR,
+    pattern: /[`~]+/,
+    message: `Unbalanced code delimiters:
+code blocks should begin and end with the same type and number of delimiters`,
+}): Rule);

package/src/rules/unescaped-dollar.js

@@ -0,0 +1,10 @@
+// @flow
+import Rule from "../rule.js";
+
+export default (Rule.makeRule({
+    name: "unescaped-dollar",
+    severity: Rule.Severity.ERROR,
+    selector: "unescapedDollar",
+    message: `Unescaped dollar sign:
+Dollar signs must appear in pairs or be escaped as \\$`,
+}): Rule);

package/src/rules/widget-in-table.js

@@ -0,0 +1,10 @@
+// @flow
+import Rule from "../rule.js";
+
+export default (Rule.makeRule({
+    name: "widget-in-table",
+    severity: Rule.Severity.BULK_WARNING,
+    selector: "table widget",
+    message: `Widget in table:
+do not put widgets inside of tables.`,
+}): Rule);