@thejaredwilcurt/csslop 0.0.38 → 0.0.39

package/src/parser/positions.js

@@ -0,0 +1,71 @@
+/**
+ * @file Turns offsets into the stylesheet into the line and column numbers that AST nodes report.
+ */
+
+/**
+ * Records the offset every line of the source begins at, so that any offset
+ * can later be resolved without rescanning the text in front of it.
+ *
+ * @param  {string} source  The raw CSS text.
+ * @return {Array}          The offset each line starts at, in order.
+ */
+function createLineIndex (source) {
+  const lineStartOffsets = [0];
+  let lineBreakIndex = source.indexOf('\n');
+  while (lineBreakIndex !== -1) {
+    lineStartOffsets.push(lineBreakIndex + 1);
+    lineBreakIndex = source.indexOf('\n', lineBreakIndex + 1);
+  }
+  return lineStartOffsets;
+}
+
+/**
+ * Resolves an offset into the stylesheet to the one-based line and column it
+ * falls on, by binary searching the line index for the last line that begins
+ * at or before the offset.
+ *
+ * @param  {Array}  lineStartOffsets  The offset each line starts at.
+ * @param  {number} offset            The offset to resolve.
+ * @return {object}                   The line, column, and offset of that point in the source.
+ */
+function resolveSourceLocation (lineStartOffsets, offset) {
+  let lowestLine = 0;
+  let highestLine = lineStartOffsets.length - 1;
+  while (lowestLine < highestLine) {
+    const middleLine = Math.ceil((lowestLine + highestLine) / 2);
+    if (lineStartOffsets[middleLine] <= offset) {
+      lowestLine = middleLine;
+    } else {
+      highestLine = middleLine - 1;
+    }
+  }
+  return {
+    line: lowestLine + 1,
+    column: offset - lineStartOffsets[lowestLine] + 1,
+    offset
+  };
+}
+
+/**
+ * Builds the position an AST node reports, spanning the text the node was
+ * parsed from.
+ *
+ * @param  {Array}  lineStartOffsets  The offset each line starts at.
+ * @param  {number} startOffset       The offset the node begins at.
+ * @param  {number} endOffset         The offset just past the end of the node.
+ * @param  {string} sourceName        The name of the file the CSS came from.
+ * @return {object}                   The position of the node in the source.
+ */
+function createPosition (lineStartOffsets, startOffset, endOffset, sourceName) {
+  return {
+    start: resolveSourceLocation(lineStartOffsets, startOffset),
+    end: resolveSourceLocation(lineStartOffsets, endOffset),
+    source: sourceName
+  };
+}
+
+export {
+  createLineIndex,
+  createPosition,
+  resolveSourceLocation
+};

package/src/parser/scanner.js

@@ -0,0 +1,229 @@
+/**
+ * @file Reads a CSS source string one token at a time, keeping track of how far into the text the parser has gotten.
+ */
+
+/**
+ * The character codes the parser compares against while scanning. Comparing
+ * numeric codes avoids building a one-character string for every character of
+ * the stylesheet.
+ */
+const CHARACTER_CODE = {
+  tab: 9,
+  lineFeed: 10,
+  formFeed: 12,
+  carriageReturn: 13,
+  space: 32,
+  asterisk: 42,
+  comma: 44,
+  slash: 47,
+  colon: 58,
+  semicolon: 59,
+  atSign: 64,
+  openBrace: 123,
+  closeBrace: 125
+};
+
+/**
+ * Determines whether a character code is one of the five characters CSS counts
+ * as whitespace.
+ *
+ * @param  {number}  characterCode  The character code to test.
+ * @return {boolean}                Whether the character is CSS whitespace.
+ */
+function isWhitespaceCode (characterCode) {
+  return (
+    characterCode === CHARACTER_CODE.space ||
+    characterCode === CHARACTER_CODE.lineFeed ||
+    characterCode === CHARACTER_CODE.tab ||
+    characterCode === CHARACTER_CODE.carriageReturn ||
+    characterCode === CHARACTER_CODE.formFeed
+  );
+}
+
+/**
+ * Creates the reader the parser advances through the stylesheet with.
+ *
+ * @param  {string} source  The raw CSS text to read.
+ * @return {object}         The scanner, positioned at the start of the text.
+ */
+function createScanner (source) {
+  return {
+    source,
+    index: 0
+  };
+}
+
+/**
+ * Determines whether the scanner has any text left to read.
+ *
+ * @param  {object}  scanner  The scanner to check.
+ * @return {boolean}          Whether text remains.
+ */
+function hasMoreInput (scanner) {
+  return scanner.index < scanner.source.length;
+}
+
+/**
+ * Reads the character code at an offset from the scanner's position without
+ * advancing it. Reading past the end of the text reports `NaN`, which fails
+ * every comparison, so the end of input needs no separate check.
+ *
+ * @param  {object} scanner  The scanner to read from.
+ * @param  {number} offset   How far ahead of the current position to read.
+ * @return {number}          The character code at that position.
+ */
+function characterCodeAt (scanner, offset = 0) {
+  return scanner.source.charCodeAt(scanner.index + offset);
+}
+
+/**
+ * Advances the scanner past any run of whitespace.
+ *
+ * @param {object} scanner  The scanner to advance.
+ */
+function skipWhitespace (scanner) {
+  while (isWhitespaceCode(scanner.source.charCodeAt(scanner.index))) {
+    scanner.index++;
+  }
+}
+
+/**
+ * Advances the scanner past the semicolons and whitespace that separate a
+ * declaration from whatever follows it.
+ *
+ * @param {object} scanner  The scanner to advance.
+ */
+function skipSemicolonsAndWhitespace (scanner) {
+  let characterCode = scanner.source.charCodeAt(scanner.index);
+  while (isWhitespaceCode(characterCode) || characterCode === CHARACTER_CODE.semicolon) {
+    scanner.index++;
+    characterCode = scanner.source.charCodeAt(scanner.index);
+  }
+}
+
+/**
+ * Advances the scanner to an absolute index, returning the text that was
+ * passed over.
+ *
+ * @param  {object} scanner   The scanner to advance.
+ * @param  {number} endIndex  The index to stop at.
+ * @return {string}           The text between the old and the new position.
+ */
+function consumeTo (scanner, endIndex) {
+  const text = scanner.source.slice(scanner.index, endIndex);
+  scanner.index = endIndex;
+  return text;
+}
+
+/**
+ * Applies a sticky pattern at the scanner's position without advancing it, so
+ * the parser can decide what it is looking at before committing to reading it.
+ *
+ * @param  {object}             scanner  The scanner to read from.
+ * @param  {RegExp}             pattern  A sticky pattern to apply at the current position.
+ * @return {Array<string>|null}          The match, or null when the pattern does not apply.
+ */
+function peekPattern (scanner, pattern) {
+  pattern.lastIndex = scanner.index;
+  return pattern.exec(scanner.source);
+}
+
+/**
+ * Applies a sticky pattern at the scanner's position, advancing past whatever
+ * it matched.
+ *
+ * @param  {object}             scanner  The scanner to read from.
+ * @param  {RegExp}             pattern  A sticky pattern to apply at the current position.
+ * @return {Array<string>|null}          The match, or null when the pattern does not apply.
+ */
+function consumePattern (scanner, pattern) {
+  const match = peekPattern(scanner, pattern);
+  if (match) {
+    scanner.index += match[0].length;
+  }
+  return match;
+}
+
+/**
+ * Consumes a single expected character, reporting whether it was there.
+ *
+ * @param  {object}  scanner        The scanner to advance.
+ * @param  {number}  characterCode  The character code that is expected.
+ * @return {boolean}                Whether the character was found and consumed.
+ */
+function consumeCharacter (scanner, characterCode) {
+  if (scanner.source.charCodeAt(scanner.index) !== characterCode) {
+    return false;
+  }
+  scanner.index++;
+  return true;
+}
+
+/**
+ * Consumes an opening brace along with the whitespace that follows it.
+ *
+ * @param  {object}  scanner  The scanner to advance.
+ * @return {boolean}          Whether a block was opened.
+ */
+function consumeOpenBrace (scanner) {
+  if (!consumeCharacter(scanner, CHARACTER_CODE.openBrace)) {
+    return false;
+  }
+  skipWhitespace(scanner);
+  return true;
+}
+
+/**
+ * Consumes a closing brace.
+ *
+ * @param  {object}  scanner  The scanner to advance.
+ * @return {boolean}          Whether a block was closed.
+ */
+function consumeCloseBrace (scanner) {
+  return consumeCharacter(scanner, CHARACTER_CODE.closeBrace);
+}
+
+/**
+ * Consumes a colon along with the whitespace that follows it.
+ *
+ * @param  {object}  scanner  The scanner to advance.
+ * @return {boolean}          Whether a colon was found and consumed.
+ */
+function consumeColon (scanner) {
+  if (!consumeCharacter(scanner, CHARACTER_CODE.colon)) {
+    return false;
+  }
+  skipWhitespace(scanner);
+  return true;
+}
+
+/**
+ * Consumes a comma along with the whitespace that follows it.
+ *
+ * @param  {object}  scanner  The scanner to advance.
+ * @return {boolean}          Whether a comma was found and consumed.
+ */
+function consumeComma (scanner) {
+  if (!consumeCharacter(scanner, CHARACTER_CODE.comma)) {
+    return false;
+  }
+  skipWhitespace(scanner);
+  return true;
+}
+
+export {
+  CHARACTER_CODE,
+  characterCodeAt,
+  consumeCharacter,
+  consumeCloseBrace,
+  consumeColon,
+  consumeComma,
+  consumeOpenBrace,
+  consumePattern,
+  consumeTo,
+  createScanner,
+  hasMoreInput,
+  peekPattern,
+  skipSemicolonsAndWhitespace,
+  skipWhitespace
+};

package/src/parser/source-search.js

@@ -0,0 +1,287 @@
+/**
+ * @file Locates the delimiters, groups, and tokens of raw CSS text, ignoring the delimiters that sit inside strings, escapes, or the parentheses and brackets of a group.
+ */
+
+/**
+ * The characters that separate the top-level components of a CSS value: the
+ * five characters CSS counts as whitespace, and the hash that always begins a
+ * token of its own.
+ *
+ * @type {string}
+ */
+const COMPONENT_SEPARATORS = ' \t\n\r\f#';
+
+/**
+ * Determines whether a character opens a quoted string.
+ *
+ * @param  {string}  character  The character to test.
+ * @return {boolean}            Whether a quoted string starts here.
+ */
+function isQuote (character) {
+  return character === '"' || character === '\'';
+}
+
+/**
+ * Reads past a quoted string, starting at its opening quote, so that the
+ * delimiters written inside the string are never mistaken for CSS syntax.
+ * An unterminated string runs to the end of the text.
+ *
+ * @param  {string} source     The raw CSS text being scanned.
+ * @param  {number} openIndex  The index of the opening quote character.
+ * @return {number}            The index just past the closing quote.
+ */
+function skipQuotedString (source, openIndex) {
+  const quoteCharacter = source[openIndex];
+  let index = openIndex + 1;
+  while (index < source.length) {
+    const character = source[index];
+    if (character === '\\') {
+      index += 2;
+      continue;
+    }
+    if (character === quoteCharacter) {
+      return index + 1;
+    }
+    index++;
+  }
+  return index;
+}
+
+/**
+ * Finds the character that closes the group opened at the given index, so that
+ * the delimiters written inside a group such as `url(a;b)` stay part of it.
+ * Strings, escapes, and groups of the same kind nested within it are read past
+ * on the way.
+ *
+ * @param  {string} source          The raw CSS text being scanned.
+ * @param  {number} openIndex       The index of the character that opens the group.
+ * @param  {string} closeCharacter  The character that closes the group.
+ * @return {number}                 The index of the closing character, or -1 when the group never closes.
+ */
+function findGroupClose (source, openIndex, closeCharacter) {
+  const openCharacter = source[openIndex];
+  let depth = 1;
+  let index = openIndex + 1;
+  while (index < source.length) {
+    const character = source[index];
+    if (character === '\\') {
+      index += 2;
+      continue;
+    }
+    if (isQuote(character)) {
+      index = skipQuotedString(source, index);
+      continue;
+    }
+    if (character === openCharacter) {
+      depth++;
+    } else if (character === closeCharacter) {
+      depth--;
+      if (!depth) {
+        return index;
+      }
+    }
+    index++;
+  }
+  return -1;
+}
+
+/**
+ * Finds the parenthesis closing the one at the given index.
+ *
+ * @param  {string} source     The raw CSS text being scanned.
+ * @param  {number} openIndex  The index of the opening parenthesis.
+ * @return {number}            The index of the matching closing parenthesis, or -1 when it never closes.
+ */
+function findMatchingParenthesis (source, openIndex) {
+  return findGroupClose(source, openIndex, ')');
+}
+
+/**
+ * Finds the bracket closing the one at the given index.
+ *
+ * @param  {string} source     The raw CSS text being scanned.
+ * @param  {number} openIndex  The index of the opening bracket.
+ * @return {number}            The index of the matching closing bracket, or -1 when it never closes.
+ */
+function findMatchingBracket (source, openIndex) {
+  return findGroupClose(source, openIndex, ']');
+}
+
+/**
+ * Reads past a group, starting at the character that opens it. A group that
+ * never closes runs to the end of the text.
+ *
+ * @param  {string} source          The raw CSS text being scanned.
+ * @param  {number} openIndex       The index of the character that opens the group.
+ * @param  {string} closeCharacter  The character that closes the group.
+ * @return {number}                 The index just past the end of the group.
+ */
+function skipGroup (source, openIndex, closeCharacter) {
+  const closeIndex = findGroupClose(source, openIndex, closeCharacter);
+  if (closeIndex === -1) {
+    return source.length;
+  }
+  return closeIndex + 1;
+}
+
+/**
+ * Reads past a parenthesized group, such as the arguments of a function.
+ *
+ * @param  {string} source     The raw CSS text being scanned.
+ * @param  {number} openIndex  The index of the opening parenthesis.
+ * @return {number}            The index just past the matching closing parenthesis.
+ */
+function skipParenthesizedGroup (source, openIndex) {
+  return skipGroup(source, openIndex, ')');
+}
+
+/**
+ * Reads past a bracketed group, which in a selector is an attribute selector
+ * and in a value is a set of grid line names.
+ *
+ * @param  {string} source     The raw CSS text being scanned.
+ * @param  {number} openIndex  The index of the opening bracket.
+ * @return {number}            The index just past the matching closing bracket.
+ */
+function skipBracketedGroup (source, openIndex) {
+  return skipGroup(source, openIndex, ']');
+}
+
+/**
+ * Determines whether a `url()` token begins at the given index. The contents
+ * of one are a URL rather than CSS syntax, so a pass that rewrites a value
+ * reads past a `url()` instead of into it.
+ *
+ * @param  {string}  source  The raw CSS text being scanned.
+ * @param  {number}  index   The index to test.
+ * @return {boolean}         Whether a `url()` token starts here.
+ */
+function startsUrlToken (source, index) {
+  return source.slice(index, index + 4).toLowerCase() === 'url(';
+}
+
+/**
+ * Finds the first of several delimiter characters that is written at the top
+ * level of the text, meaning it is not escaped, quoted, or nested inside a
+ * group.
+ *
+ * @param  {string} source      The raw CSS text being scanned.
+ * @param  {string} delimiters  The delimiter characters to look for.
+ * @param  {number} startIndex  The index to start scanning from.
+ * @return {number}             The index of the first top-level delimiter, or -1 when there is none.
+ */
+function findTopLevelDelimiter (source, delimiters, startIndex) {
+  let index = startIndex;
+  while (index < source.length) {
+    const character = source[index];
+    if (character === '\\') {
+      index += 2;
+      continue;
+    }
+    if (isQuote(character)) {
+      index = skipQuotedString(source, index);
+      continue;
+    }
+    if (character === '(') {
+      index = skipParenthesizedGroup(source, index);
+      continue;
+    }
+    if (character === '[') {
+      index = skipBracketedGroup(source, index);
+      continue;
+    }
+    if (delimiters.includes(character)) {
+      return index;
+    }
+    index++;
+  }
+  return -1;
+}
+
+/**
+ * Splits text on every top-level occurrence of any of the delimiters, keeping
+ * the delimiters that are escaped, quoted, or nested inside a group within
+ * their part.
+ *
+ * @param  {string} text        The text to split.
+ * @param  {string} delimiters  The delimiter characters to split on.
+ * @return {Array}              The parts of the text, without the delimiters.
+ */
+function splitTopLevel (text, delimiters) {
+  const parts = [];
+  let partStart = 0;
+  let index = findTopLevelDelimiter(text, delimiters, 0);
+  while (index !== -1) {
+    parts.push(text.slice(partStart, index));
+    partStart = index + 1;
+    index = findTopLevelDelimiter(text, delimiters, partStart);
+  }
+  parts.push(text.slice(partStart));
+  return parts;
+}
+
+/**
+ * Splits a comma-separated list, such as the arguments of a function or the
+ * selectors of a rule, into its trimmed parts. A list with nothing in it has
+ * no parts at all.
+ *
+ * @param  {string} text  The comma-separated text to split.
+ * @return {Array}        The parts of the list, trimmed of the whitespace written around them.
+ */
+function splitTopLevelCommaList (text) {
+  if (!text.trim()) {
+    return [];
+  }
+  return splitTopLevel(text, ',').map((part) => {
+    return part.trim();
+  });
+}
+
+/**
+ * Splits a CSS value into its top-level components, keeping the arguments of a
+ * function and the contents of a quoted string intact. Components are
+ * separated by whitespace, or by a `#`, which always starts a hash token and
+ * therefore ends any component already in progress.
+ *
+ * For example, `rgb(0 0 0) red` yields `["rgb(0 0 0)", "red"]`, and the
+ * minified `red#00f` yields `["red", "#00f"]`.
+ *
+ * @param  {string} value  The CSS value to split.
+ * @return {Array}         The top-level components of the value.
+ */
+function splitTopLevelComponents (value) {
+  const components = [];
+  let componentStart = 0;
+  let separatorIndex = findTopLevelDelimiter(value, COMPONENT_SEPARATORS, 0);
+  while (separatorIndex !== -1) {
+    const component = value.slice(componentStart, separatorIndex);
+    if (component) {
+      components.push(component);
+    }
+    // A hash belongs to the token it starts, so it is not consumed as a separator
+    if (value[separatorIndex] === '#') {
+      componentStart = separatorIndex;
+    } else {
+      componentStart = separatorIndex + 1;
+    }
+    separatorIndex = findTopLevelDelimiter(value, COMPONENT_SEPARATORS, separatorIndex + 1);
+  }
+  const lastComponent = value.slice(componentStart);
+  if (lastComponent) {
+    components.push(lastComponent);
+  }
+  return components;
+}
+
+export {
+  findMatchingBracket,
+  findMatchingParenthesis,
+  findTopLevelDelimiter,
+  skipBracketedGroup,
+  skipParenthesizedGroup,
+  skipQuotedString,
+  splitTopLevel,
+  splitTopLevelCommaList,
+  splitTopLevelComponents,
+  startsUrlToken
+};