scss analyzer - improve origin reporting and display

Author: cscheid

src/core/sass.ts

@@ -20,6 +20,7 @@ import { cssVarsBlock } from "./sass/add-css-vars.ts";
 import { md5HashBytes } from "./hash.ts";
 import { kSourceMappingRegexes } from "../config/constants.ts";
 import { writeTextFileSyncPreserveMode } from "./write.ts";
+import { quartoConfig } from "../core/quarto.ts";
 
 export interface SassVariable {
   name: string;
@@ -107,6 +108,7 @@ export async function compileSass(
   // * Rules may use functions, variables, and mixins
   //   (theme follows framework so it can override the framework rules)
   let scssInput = [
+    `// quarto-scss-analysis-annotation { "quarto-version": "${quartoConfig.version()}" }`,
     '// quarto-scss-analysis-annotation { "origin": "\'use\' section from format" }',
     ...frameWorkUses,
     '// quarto-scss-analysis-annotation { "origin": "\'use\' section from Quarto" }',
@@ -119,11 +121,11 @@ export async function compileSass(
     ...quartoFunctions,
     '// quarto-scss-analysis-annotation { "origin": "\'functions\' section from user-defined SCSS" }',
     ...userFunctions,
-    '// quarto-scss-analysis-annotation { "origin": "user-defined defaults" }',
+    '// quarto-scss-analysis-annotation { "origin": "Defaults from user-defined SCSS" }',
     ...userDefaults.reverse(),
-    '// quarto-scss-analysis-annotation { "origin": "quarto-specific defaults" }',
+    '// quarto-scss-analysis-annotation { "origin": "Defaults from Quarto\'s SCSS" }',
     ...quartoDefaults.reverse(),
-    '// quarto-scss-analysis-annotation { "origin": "format framework defaults" }',
+    '// quarto-scss-analysis-annotation { "origin": "Defaults from the format SCSS" }',
     ...frameworkDefaults.reverse(),
     '// quarto-scss-analysis-annotation { "origin": "\'mixins\' section from format" }',
     ...frameworkMixins,

src/core/sass/analyzer/forward-annotations.ts

@@ -1,9 +1,10 @@
-import { annotateNode } from './ast-utils.ts';
+import { annotateNode } from "./ast-utils.ts";
 
 export const forwardAnnotations = (ast: any) => {
   const pragmaAnnotation = "quarto-scss-analysis-annotation";
-  const currentAnnotation: Record<string, unknown> = {};
-  let hasAnnotations: boolean = false
+  const annotationStack: Record<string, string>[] = [{}];
+  let currentAnnotation: Record<string, unknown> = annotationStack[0];
+  let hasAnnotations: boolean = false;
   for (const node of ast.children) {
     if (node.type === "comment_singleline") {
       const value = node?.value?.trim();
@@ -15,7 +16,18 @@ export const forwardAnnotations = (ast: any) => {
           console.error("Could not parse annotation payload", e);
           continue;
         }
+        if (payload.action === "push") {
+          annotationStack.push(JSON.parse(JSON.stringify(currentAnnotation)));
+          currentAnnotation = annotationStack[annotationStack.length - 1];
+        } else if (payload.action === "pop" && annotationStack.length) {
+          annotationStack.pop();
+          currentAnnotation = annotationStack[annotationStack.length - 1];
+        }
+
         for (const [key, value] of Object.entries(payload)) {
+          if (key === "action") {
+            continue;
+          }
           if (value === null) {
             delete currentAnnotation[key];
           } else {
@@ -30,4 +42,4 @@ export const forwardAnnotations = (ast: any) => {
     }
   }
   return ast;
-}
+};

src/core/sass/brand.ts

@@ -180,7 +180,10 @@ const brandColorBundle = (
   key: string,
   nameMap: Record<string, string>,
 ): SassBundleLayers => {
-  const colorVariables: string[] = ["/* color variables from _brand.yml */"];
+  const colorVariables: string[] = [
+    "/* color variables from _brand.yml */",
+    '// quarto-scss-analysis-annotation { "action": "push", "origin": "_brand.yml color" }',
+  ];
   for (const colorKey of Object.keys(brand.data?.color?.palette ?? {})) {
     colorVariables.push(
       `$${colorKey}: ${brand.getColor(colorKey)} !default;`,
@@ -204,6 +207,7 @@ const brandColorBundle = (
     }
   }
   // const colorEntries = Object.keys(brand.color);
+  colorVariables.push('// quarto-scss-analysis-annotation { "action": "pop" }');
   const colorBundle: SassBundleLayers = {
     key,
     // dependency: "bootstrap",
@@ -224,6 +228,7 @@ const brandTypographyBundle = (
 ): SassBundleLayers => {
   const typographyVariables: string[] = [
     "/* typography variables from _brand.yml */",
+    '// quarto-scss-analysis-annotation { "action": "push", "origin": "_brand.yml typography" }',
   ];
   const typographyImports: string[] = [];
   const fonts = brand.data?.typography?.fonts ?? [];
@@ -422,6 +427,9 @@ const brandTypographyBundle = (
     }
   }
 
+  typographyVariables.push(
+    '// quarto-scss-analysis-annotation { "action": "pop" }',
+  );
   const typographyBundle: SassBundleLayers = {
     key,
     // dependency: "bootstrap",

tools/sass-variable-explainer/forward-annotations.ts

@@ -2,8 +2,9 @@ import { annotateNode } from './ast-utils.ts';
 
 export const forwardAnnotations = (ast: any) => {
   const pragmaAnnotation = "quarto-scss-analysis-annotation";
-  const currentAnnotation: Record<string, unknown> = {};
-  let hasAnnotations: boolean = false
+  const annotationStack: Record<string, string>[] = [{}];
+  let currentAnnotation: Record<string, unknown> = annotationStack[0];
+  let hasAnnotations: boolean = false;
   for (const node of ast.children) {
     if (node.type === "comment_singleline") {
       const value = node?.value?.trim();
@@ -15,7 +16,17 @@ export const forwardAnnotations = (ast: any) => {
           console.error("Could not parse annotation payload", e);
           continue;
         }
+        if (payload.action === "push") {
+          annotationStack.push(JSON.parse(JSON.stringify(currentAnnotation)));
+          currentAnnotation = annotationStack[annotationStack.length - 1];
+        } else if (payload.action === "pop" && annotationStack.length) {
+          annotationStack.pop();
+          currentAnnotation = annotationStack[annotationStack.length - 1];
+        }
         for (const [key, value] of Object.entries(payload)) {
+          if (key === "action") {
+            continue;
+          }
           if (value === null) {
             delete currentAnnotation[key];
           } else {

tools/sass-variable-explainer/sass-ui.qmd

@@ -105,13 +105,13 @@ selectedDependencyTitle = {
   if (selectedDependency === undefined) {
     return htl.html`<h5>Select a single variable to analyze</h5>`;
   } else {
-    return htl.html`<h5>Variable analysis for ${selectedDependency?.node?.property?.variable?.value ?? "<i>unknown</i>"}</h5>`;
+    return htl.html`<h5>Variable analysis for <code>${selectedDependency?.node?.property?.variable?.value ?? "<i>unknown</i>"}</code></h5>`;
     }
 }
 renderedAnalysis = {
   deps;
   debugger;
-  const result = htl.html`<div style="padding-left: 20px"></div>`;
+  const result = htl.html`<div style="padding-left: 20px; padding-top: 20px"></div>`;
   if (!selectedDependencyChains.length) {
     return result;
   }
@@ -124,7 +124,7 @@ renderedAnalysis = {
   }
 
   if (selectedDependency?.node?.annotation?.origin) {
-    result.appendChild(htl.html`<div><b>Origin</b>: ${selectedDependency?.node?.annotation?.origin}</div>`);
+    result.appendChild(htl.html`<div style="padding-bottom:1em"><b>Origin</b>: ${selectedDependency?.node?.annotation?.origin}</div>`);
   }
 
   const lineEnd = Math.max(
@@ -133,14 +133,14 @@ renderedAnalysis = {
     selectedDependency?.node?.value?.lineEnd ?? -Infinity,
   );
   if (selectedDependency?.node?.line !== undefined && lineEnd !== -Infinity) {
-    result.appendChild(htl.html`<div><b>SCSS source<b></div>`);
+    result.appendChild(htl.html`<div><b>SCSS source:<b></div>`);
     const snippet = sourceLines.slice(selectedDependency?.node?.line - 1, lineEnd).join("\n");
     result.appendChild(htl.html`<div><pre style='padding-left: 20px; padding-top:1em'>${snippet}</pre></div>`)
   }
 
   
   // Dependencies
-  result.appendChild(htl.html`<div>Dependencies:</div>`);
+  result.appendChild(htl.html`<div><b>Dependencies:</b></div>`);
   const depsDiv = htl.html`<div style="padding-left: 20px"></div>`;
   result.appendChild(depsDiv);
   const seenDependencies = new Set([]);