@stencil/sass - npm Package Compare versions

Comparing version 2.0.3 to 3.0.0-0

dist/diagnostics.d.ts

@@ -1,3 +0,14 @@
-import { SassException } from 'sass';
+import { LegacyException } from 'sass';
 import * as d from './declarations';
-export declare function loadDiagnostic(context: d.PluginCtx, sassError: SassException, filePath: string): d.Diagnostic;
+/**
+ * Generates a diagnostic as a result of an error originating from Sass.
+ *
+ * This function mutates the provided context by pushing the generated diagnostic to the context's collection of
+ * diagnostics.
+ *
+ * @param context the compilation context that the plugin has access to
+ * @param sassError the Sass error to create a diagnostic from
+ * @param filePath the path of the file that led to an error being raised
+ * @returns the created diagnostic, or `null` if one could not be generated
+ */
+export declare function loadDiagnostic(context: d.PluginCtx, sassError: LegacyException, filePath: string): d.Diagnostic | null;

dist/diagnostics.js

@@ -0,1 +1,12 @@
+/**
+ * Generates a diagnostic as a result of an error originating from Sass.
+ *
+ * This function mutates the provided context by pushing the generated diagnostic to the context's collection of
+ * diagnostics.
+ *
+ * @param context the compilation context that the plugin has access to
+ * @param sassError the Sass error to create a diagnostic from
+ * @param filePath the path of the file that led to an error being raised
+ * @returns the created diagnostic, or `null` if one could not be generated
+ */
 export function loadDiagnostic(context, sassError, filePath) {
@@ -84,2 +95,7 @@ if (sassError == null || context == null) {
 }
+/**
+ * Helper function for converting a number error code to a string
+ * @param input the numeric error code to convert
+ * @returns the stringified error code
+ */
 function formatCode(input) {
@@ -92,2 +108,8 @@ let output = '';
 }
+/**
+ * Splits up a message from Sass, returning all input prior to the first '╷' character.
+ * If no such character exists, the entire original message will be returned.
+ * @param input the Sass message to split
+ * @returns the split message
+ */
 function formatMessage(input) {
@@ -100,2 +122,9 @@ let output = '';
 }
+/**
+ * Formats the provided filename, by stripping the provided root directory out of the filename, and limiting the
+ * display string to 80 characters
+ * @param rootDir the root directory to strip out of the provided filename
+ * @param fileName the filename to format for pretty printing
+ * @returns the formatted filename
+ */
 function formatFileName(rootDir, fileName) {
@@ -102,0 +131,0 @@ if (!rootDir || !fileName)

dist/index.d.ts

 import * as d from './declarations';
+/**
+ * The entrypoint of the Stencil Sass plugin
+ *
+ * This function creates & configures the plugin to be used by consuming Stencil projects
+ *
+ * For configuration details, please see the [GitHub README](https://github.com/ionic-team/stencil-sass).
+ *
+ * @param opts options to configure the plugin
+ * @return the configured plugin
+ */
 export declare function sass(opts?: d.PluginOptions): d.Plugin;

dist/util.d.ts

 import * as d from './declarations';
+import { LegacyOptions } from 'sass/types/legacy/options';
+/**
+ * Determine if the Sass plugin should be applied, based on the provided `fileName`
+ *
+ * @param fileName the name of a file to potentially transform
+ * @returns `true` if the name of the file ends with a sass extension (.scss, .sass), case insensitive. `false`
+ * otherwise
+ */
 export declare function usePlugin(fileName: string): boolean;
-export declare function getRenderOptions(opts: d.PluginOptions, sourceText: string, fileName: string, context: d.PluginCtx): d.PluginOptions;
+/**
+ * Build a list of options to provide to Sass' `render` API.
+ * @param opts the options provided to the plugin within a Stencil configuration file
+ * @param sourceText the source text of the file to transform
+ * @param fileName the name of the file to transform
+ * @param context the runtime context being used by the plugin
+ * @returns the generated/normalized plugin options
+ */
+export declare function getRenderOptions(opts: d.PluginOptions, sourceText: string, fileName: string, context: d.PluginCtx): LegacyOptions<'async'>;
+/**
+ * Replaces the extension with the provided file name with 'css'.
+ *
+ * If the file does not have an extension, no transformation will be applied.
+ *
+ * @param fileName the name of the file whose extension should be replaced
+ * @returns the updated filename, using 'css' as the file extension
+ */
 export declare function createResultsId(fileName: string): string;
 export declare function normalizePath(str: string): string;
+/**
+ * Split an import path into a module ID and file path
+ * @param orgImport the import path to split
+ * @returns a module id and the filepath under that module id
+ */
 export declare function getModuleId(orgImport: string): {
@@ -7,0 +36,0 @@ moduleId: string;

dist/util.js

 import * as path from 'path';
+/**
+ * Determine if the Sass plugin should be applied, based on the provided `fileName`
+ *
+ * @param fileName the name of a file to potentially transform
+ * @returns `true` if the name of the file ends with a sass extension (.scss, .sass), case insensitive. `false`
+ * otherwise
+ */
 export function usePlugin(fileName) {
@@ -8,12 +15,22 @@ if (typeof fileName === 'string') {
 }
+/**
+ * Build a list of options to provide to Sass' `render` API.
+ * @param opts the options provided to the plugin within a Stencil configuration file
+ * @param sourceText the source text of the file to transform
+ * @param fileName the name of the file to transform
+ * @param context the runtime context being used by the plugin
+ * @returns the generated/normalized plugin options
+ */
 export function getRenderOptions(opts, sourceText, fileName, context) {
-    // create a copy of the original sass config so we don't change it
-    const renderOpts = Object.assign({}, opts);
-    // always set "data" from the source text
-    renderOpts.data = sourceText;
-    // activate indented syntax if the file extension is .sass
+    // Create a copy of the original sass config, so we don't modify the one provided.
+    // Explicitly add `data` (as it's a required field) to be the source text
+    const renderOpts = Object.assign(Object.assign({}, opts), { data: sourceText });
+    // activate indented syntax if the file extension is .sass.
+    // this needs to be set prior to injecting global sass (as the syntax affects the import terminator)
     renderOpts.indentedSyntax = /(\.sass)$/i.test(fileName);
+    // create a copy of the original path config, so we don't modify the one provided
     renderOpts.includePaths = Array.isArray(opts.includePaths) ? opts.includePaths.slice() : [];
     // add the directory of the source file to includePaths
     renderOpts.includePaths.push(path.dirname(fileName));
+    // ensure each of the includePaths is an absolute path
     renderOpts.includePaths = renderOpts.includePaths.map((includePath) => {
@@ -26,5 +43,8 @@ if (path.isAbsolute(includePath)) {
     });
+    // create a copy of the original global config of paths to inject, so we don't modify the one provided.
+    // this is a Stencil-specific configuration, and not a part of the Sass API.
     const injectGlobalPaths = Array.isArray(opts.injectGlobalPaths) ? opts.injectGlobalPaths.slice() : [];
     if (injectGlobalPaths.length > 0) {
-        // automatically inject each of these paths into the source text
+        // Automatically inject each of these paths into the source text.
+        // This is accomplished by prepending the global stylesheets to the file being processed.
         const injectText = injectGlobalPaths
@@ -61,2 +81,9 @@ .map((injectGlobalPath) => {
         }
+        /**
+         * Create a handler for loading files when a `@use` or `@import` rule is encountered for loading a path prefixed
+         * with a tilde (~). Such imports indicate that the module should be resolved from the `node_modules` directory.
+         * @param url the path to the module to load
+         * @param _prev Unused - typically, this is a string identifying the stylesheet that contained the @use or @import.
+         * @param done a callback to return the path to the resolved path
+         */
         const importer = (url, _prev, done) => {
@@ -102,2 +129,10 @@ if (typeof url === 'string') {
 }
+/**
+ * Replaces the extension with the provided file name with 'css'.
+ *
+ * If the file does not have an extension, no transformation will be applied.
+ *
+ * @param fileName the name of the file whose extension should be replaced
+ * @returns the updated filename, using 'css' as the file extension
+ */
 export function createResultsId(fileName) {
@@ -136,2 +171,7 @@ // create what the new path is post transform (.css)
 }
+/**
+ * Split an import path into a module ID and file path
+ * @param orgImport the import path to split
+ * @returns a module id and the filepath under that module id
+ */
 export function getModuleId(orgImport) {
@@ -147,2 +187,3 @@ if (orgImport.startsWith('~')) {
     if (orgImport.startsWith('@') && splt.length > 1) {
+        // we have a scoped package, it's module includes the word following the first slash
         m.moduleId = splt.slice(0, 2).join('/');
@@ -149,0 +190,0 @@ m.filePath = splt.slice(2).join('/');

package.json

 {
   "name": "@stencil/sass",
-  "version": "2.0.3",
+  "version": "3.0.0-0",
   "license": "MIT",
@@ -31,6 +31,5 @@ "main": "dist/index.js",
     "@rollup/plugin-node-resolve": "^15.0.0",
-    "@stencil/core": "^2.17.3",
+    "@stencil/core": "^3.0.0",
     "@types/jest": "^26.0.15",
     "@types/node": "^16.11.48",
-    "@types/sass": "^1.16.0",
     "jest": "^26.6.3",
@@ -41,3 +40,3 @@ "np": "^7.0.0",
     "rollup": "^3.5.1",
-    "sass": "^1.29.0",
+    "sass": "^1.58.3",
     "terser": "^5.3.8",
@@ -44,0 +43,0 @@ "ts-jest": "^26.4.4",

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

No v1

Quality

Package is not semver >=1. This means it is not stable and does not support ^ ranges.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

5148957

increased by8.21%

Dev dependency count

14

decreased by-6.67%

Lines of code

21049

increased by9.09%

Worsened metrics

Number of low quality alerts

1

increased byInfinity%

No dependency changes