fix/style: Fix positions of styles in sources, refactor typescript parsing, update jsdocs globally

Author: blyedev

src/parse-typescript.js

@@ -1,10 +1,19 @@
-import { Document } from "postcss";
-import { Input } from "postcss";
+import { Document, Input } from "postcss";
 import { AngularParser } from "./parser-angular.js";
 
 /**
- * Parses Angular code and returns a Document.
+ * Represents an object that can be converted to a string.
  *
+ * @typedef {object} Stringifiable
+ * @property {function(): string} toString - Method to convert the object to a string.
+ */
+
+/**
+ * Parses Angular code and generates a PostCSS Document representing the Abstract Syntax Tree (AST).
+ *
+ * @param {string | Stringifiable} angularCode - The Angular source code to be parsed, provided either as a string or as an object implementing the toString() method.
+ * @param {import('postcss').ProcessOptions} opts - The PostCSS processing options.
+ * @returns {Document} A PostCSS Document object representing the parsed AST.
  * @type {import('postcss').Parser<Document>}
  */
 export default function parse(angularCode, opts) {

src/parse.js

@@ -1,12 +1,15 @@
 import { Document, Input } from "postcss";
-import { parseTypescript } from "./parse-typescript.js";
+import { TypescriptParser } from "./parser-typescript.js";
 import { StyleParser } from "./parser-styles.js";
 
+/**
+ * Represents a parser that processes Angular component styles within TypeScript files.
+ */
 export class AngularParser {
   /**
-   * Initializes the parser
+   * Constructs a new instance of the AngularParser.
    *
-   * @param {Input} input The PostCSS wrapper around a file
+   * @param {Input} input - The PostCSS `Input` object wrapping the source file.
    */
   constructor(input) {
     this.input = input;
@@ -16,12 +19,14 @@ export class AngularParser {
   }
 
   /**
-   * Sleeper parser activation phrase ;)
+   * Parses the input TypeScript file to extract and process Angular component styles.
    *
-   * @param {Pick<import("postcss").ProcessOptions, "from" | "map">} opts PostCSS process options
+   * @param {Pick<import("postcss").ProcessOptions, "from" | "map">} opts - The PostCSS processing options.
+   * @returns {Document} The root node of the generated Abstract Syntax Tree (AST).
    */
   parse(opts) {
-    const styleLiterals = parseTypescript(this.input.css, opts && opts.from);
+    const typescriptParser = new TypescriptParser(this.input);
+    const styleLiterals = typescriptParser.parse();
 
     let index = 0;
     styleLiterals.forEach((styleLiteral, idx) => {
@@ -43,5 +48,7 @@ export class AngularParser {
       index = end + 1;
       this.doc.push(stylesRoot);
     });
+
+    return this.doc;
   }
 }

src/parser-angular.js

@@ -1,63 +1,65 @@
 import postcss from "postcss";
+
 /**
- * Class to adjust node locations within the source code.
+ * Represents a parser that adjusts the positions of nodes within the source code.
  */
 export class StyleParser {
   /**
-   * Constructor
+   * Constructs a new instance of the StyleParser class.
    *
-   * @param {postcss.Input} input - An instance of the Locations class.
-   * @param {import("ts-morph").StringLiteral | import("ts-morph").NoSubstitutionTemplateLiteral} styleLiteral - The style literal node.
+   * @param {postcss.Input} input - The input source containing the style information.
+   * @param {import("ts-morph").StringLiteral | import("ts-morph").NoSubstitutionTemplateLiteral} styleLiteral - The style literal node to be processed.
    */
   constructor(input, styleLiteral) {
     this.input = input;
-
-    const { col, line } = input.fromOffset(styleLiteral.getStart());
-    this.column = col - 1;
-    this.line = line - 1;
     this.styleLiteral = styleLiteral;
   }
 
-  _adjustPosition(object) {
-    if (object) {
-      if (object.line === 1) {
-        object.column += this.column;
-      }
-      object.line += this.line;
-      if (typeof object.offset === "number") {
-        object.offset += this.styleLiteral.getStart();
-      }
-      if (typeof object.endLine === "number") {
-        if (object.endLine === 1) {
-          object.endColumn += this.column;
-        }
-        object.endLine += this.line;
-      }
+  /**
+   * Modifies a position object to be relative to the input file instead of the parsed CSS.
+   *
+   * @param {postcss.Position} position - The position object that requires adjustment.
+   */
+  _adjustPosition(position) {
+    const { col, line } = this.input.fromOffset(this.styleLiteral.getStart());
+
+    if (position.line === 1) {
+      position.column += col;
     }
+    position.line += line - 1;
+    position.offset += this.styleLiteral.getStart() + 1;
   }
 
+  /**
+   * Adjusts the positional data of a specific AST node to align with the input file's context.
+   *
+   * @param {postcss.AnyNode} node - The AST node whose position needs to be adjusted.
+   */
   _adjustNode(node) {
     this._adjustPosition(node.source.start);
     this._adjustPosition(node.source.end);
+    node.source.end.column -= 1;
+    node.source.end.offset -= 1;
   }
 
   /**
-   * Adjusts the position of source to be relative to the entire file not input css
+   * Updates the positions of all nodes within the provided root AST to correspond with the input file.
    *
-   * @param {postcss.Root} root The root of all styles to be adjusted
+   * @param {postcss.Root} root - The root node of the stylesheet AST that requires adjustment.
    */
   _adjustAllNodes(root) {
     this._adjustNode(root);
-    root.source = {
-      ...root.source,
-      input: this.input,
-    };
-
     root.walk((node) => {
       this._adjustNode(node);
     });
   }
 
+  /**
+   * Modifies error positions to reflect the context of the input file accurately.
+   *
+   * @param {any} error - The error object that needs positional adjustment.
+   * @returns {any} The error object with updated position information.
+   */
   _adjustError(error) {
     if (error && error.name === "CssSyntaxError") {
       this._adjustPosition(error);
@@ -70,19 +72,28 @@ export class StyleParser {
     return error;
   }
 
+  /**
+   * Parses the style literal and generates the corresponding Abstract Syntax Tree (AST).
+   *
+   * @param {Pick<import("postcss").ProcessOptions, "from" | "map">} opts - The PostCSS processing options.
+   * @returns {postcss.Root} The root node of the generated AST.
+   * @throws Will throw an error if parsing fails, with adjusted error positions.
+   */
   parse(opts) {
     const styleLiteral = this.styleLiteral;
     let root;
     try {
-      root = postcss.parse(
-        styleLiteral.getLiteralText(),
-        Object.assign({}, opts, { map: false }),
-      );
+      root = postcss.parse(styleLiteral.getLiteralText(), opts);
     } catch (error) {
       this._adjustError(error);
       throw error;
     }
+
     this._adjustAllNodes(root);
+    root.source = {
+      ...root.source,
+      input: this.input,
+    };
 
     return root;
   }

src/parser-styles.js

@@ -0,0 +1,103 @@
+import { Project, SyntaxKind } from "ts-morph";
+
+/**
+ * @typedef {import("ts-morph").StringLiteral | import("ts-morph").NoSubstitutionTemplateLiteral} StyleLiteral
+ */
+
+export class TypescriptParser {
+  /**
+   * Creates an instance of TypescriptParser.
+   *
+   * @param {import("postcss").Input} input - The PostCSS input containing the source CSS and its originating file.
+   */
+  constructor(input) {
+    const project = new Project({
+      useInMemoryFileSystem: true,
+    });
+
+    this.sourceFile = project.createSourceFile(input.from, input.css);
+  }
+
+  /**
+   * Parses the TypeScript source file to extract style literals from component decorators.
+   *
+   * @returns {StyleLiteral[]} An array of style literals extracted from the components within the source file.
+   */
+  parse() {
+    return this.sourceFile
+      .getClasses()
+      .flatMap((cls) => cls.getDecorators())
+      .filter(isComponentDecorator)
+      .flatMap((decorator) => decorator.getArguments())
+      .filter(isObjectLiteral)
+      .flatMap(getStylesProperty)
+      .flatMap(getStyleValues)
+      .map(castToStyleLiteral);
+  }
+}
+
+/**
+ * Determines whether a given decorator is a Component decorator.
+ *
+ * @param {import("ts-morph").Decorator} decorator - The decorator to evaluate.
+ * @returns {boolean} `true` if the decorator is named "Component"; otherwise, `false`.
+ */
+function isComponentDecorator(decorator) {
+  return decorator.getName() === "Component";
+}
+
+/**
+ * Checks if the provided expression is an object literal.
+ *
+ * @param {import("ts-morph").Expression} expr - The expression to check.
+ * @returns {boolean} `true` if the expression is an ObjectLiteralExpression; otherwise, `false`.
+ */
+function isObjectLiteral(expr) {
+  return expr.getKind() === SyntaxKind.ObjectLiteralExpression;
+}
+
+/**
+ * Extracts the 'styles' property from an ObjectLiteralExpression.
+ *
+ * @param {import("ts-morph").ObjectLiteralExpression} obj - The object literal representing component metadata.
+ * @returns {import("ts-morph").Expression[]} An array containing the initializer of the 'styles' property, if it exists.
+ */
+function getStylesProperty(obj) {
+  const prop = obj.getProperty("styles");
+  return prop && prop.getKind() === SyntaxKind.PropertyAssignment
+    ? [
+        prop
+          .asKindOrThrow(SyntaxKind.PropertyAssignment)
+          .getInitializerOrThrow(),
+      ]
+    : [];
+}
+
+/**
+ * Retrieves the style values from an expression, handling both single expressions and array literals.
+ *
+ * @param {import("ts-morph").Expression} expr - The initializer expression of the 'styles' property.
+ * @returns {import("ts-morph").Expression[]} An array of expressions representing individual style literals.
+ */
+function getStyleValues(expr) {
+  if (expr.getKind() === SyntaxKind.ArrayLiteralExpression) {
+    return expr.asKindOrThrow(SyntaxKind.ArrayLiteralExpression).getElements();
+  }
+  return [expr];
+}
+
+/**
+ * Converts an expression to a StyleLiteral type, ensuring it is a supported literal.
+ *
+ * @param {import("ts-morph").Expression} expr - The expression to cast.
+ * @returns {StyleLiteral} The expression cast to a StyleLiteral.
+ * @throws {Error} If the expression is not a StringLiteral or NoSubstitutionTemplateLiteral.
+ */
+function castToStyleLiteral(expr) {
+  if (expr.getKind() === SyntaxKind.StringLiteral) {
+    return expr.asKindOrThrow(SyntaxKind.StringLiteral);
+  } else if (expr.getKind() === SyntaxKind.NoSubstitutionTemplateLiteral) {
+    return expr.asKindOrThrow(SyntaxKind.NoSubstitutionTemplateLiteral);
+  }
+  throw new Error("Unsupported style literal type.");
+}