@aurodesignsystem/auro-library 5.14.0 → 5.14.2

package/scripts/utils/sharedFileProcessorUtils.mjs

@@ -1,270 +1,4 @@
-import * as mdMagic from 'markdown-magic';
-import fs from 'node:fs/promises';
-import path from "node:path";
-
-import AuroLibraryUtils from "./auroLibraryUtils.mjs";
-import { AuroTemplateFiller } from "./auroTemplateFiller.mjs";
-import { AuroFileHandler } from "./auroFileHandler.mjs";
-import {Logger} from "./logger.mjs";
-
-
-// This JSDoc type trickery is here so you get "decent enough" auto complete
-/** @type {typeof import('markdown-magic').markdownMagic} */
-const applyMarkdownMagic = mdMagic.default
-
-/**
- * Optional output configuration
- * @typedef  {object}   OutputConfig
- * @property {string}   [directory] - Change output path of new content. Default behavior is replacing the original file
- * @property {boolean}  [removeComments = false] - Remove comments from output. Default is false.
- * @property {function} [pathFormatter] - Custom function for altering output paths
- * @property {boolean}  [applyTransformsToSource = false] - Apply transforms to source file. Default is true. This is for when outputDir is set.
- */
-
-/**
- * Configuration for Markdown magic
- *
- * Below is the main config for `markdown-magic` - copy-pasted directly from the library
- *
- * @typedef {object} MarkdownMagicOptions
- * @property {string} matchWord - [v2-only] string to match for variables
- * @property {FilePathsOrGlobs} [files] - Files to process.
- * @property {Array} [transforms = defaultTransforms] - Custom commands to transform block contents, see transforms & custom transforms sections below.
- * @property {OutputConfig} [output] - Output configuration
- * @property {SyntaxType} [syntax = 'md'] - Syntax to parse
- * @property {string} [open = 'doc-gen'] - Opening match word
- * @property {string} [close = 'end-doc-gen'] - Closing match word. If not defined will be same as opening word.
- * @property {string} [cwd = process.cwd() ] - Current working directory. Default process.cwd()
- * @property {boolean} [outputFlatten] - Flatten files that are output
- * @property {boolean} [useGitGlob] - Use git glob for LARGE file directories
- * @property {boolean} [dryRun = false] - See planned execution of matched blocks
- * @property {boolean} [debug = false] - See debug details
- * @property {boolean} [silent = false] - Silence all console output
- * @property {boolean} [applyTransformsToSource = true] - Apply transforms to source file. Default is true.
- * @property {boolean} [failOnMissingTransforms = false] - Fail if transform functions are missing. Default skip blocks.
- * @property {boolean} [failOnMissingRemote = true] - Fail if remote file is missing.
- */
-
-
-// Config
-// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-/** @type {MarkdownMagicOptions} */
-export const MD_MAGIC_CONFIG = {
-  matchWord: "AURO-GENERATED-CONTENT",
-  output: {
-    directory: "./",
-    applyTransformsToSource: true
-  }
-};
-
-// Initialize utility services
-export const auroLibraryUtils = new AuroLibraryUtils();
-export const templateFiller = new AuroTemplateFiller();
-
-// List of components that do not support ESM to determine which README to use
-export const nonEsmComponents = ['combobox', 'datepicker', 'menu', 'pane', 'select'];
-
-
-// Local utils
-/**
- *
- * @param {string} pathLike - Please include the preceding slash! Like so: `/docTemplates/README.md`
- * @return {string}
- */
-// TODO: test this in auro-flight before merging to main
-export function fromAuroComponentRoot(pathLike) {
-  if (pathLike.startsWith('/')) {
-    // remove the first slash
-    return path.join(auroLibraryUtils.getProjectRootPath, pathLike.slice(1))
-  }
-
-  return path.join(auroLibraryUtils.getProjectRootPath, pathLike)
-}
-
-
-// External assets
-// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-/**
- * Generate a URL for the WC Generator README file.
- * @param {string} branchOrTag
- * @param {string} fileNameWithPath
- * @return {string}
- */
-export function generateWCGeneratorUrl(branchOrTag, fileNameWithPath) {
-  const baseRepoUrl = 'https://raw.githubusercontent.com/AlaskaAirlines/WC-Generator'
-
-  // check if tag starts with 'vX' since our tags are `v4.0.0`
-  const isTag = branchOrTag.startsWith('v') &&
-    /^\d+\.\d+\.\d+(-.*)?$/.test(branchOrTag.slice(1));
-
-  if (isTag) {
-    return `${baseRepoUrl}/refs/tags/${branchOrTag}/${fileNameWithPath}`;
-  }
-
-  if (branchOrTag !== 'master') {
-    return `${baseRepoUrl}/refs/heads/${branchOrTag}/${fileNameWithPath}`;
-  }
-
-  return `${baseRepoUrl}/master/${fileNameWithPath}`;
-}
-
-/**
- * @param {string} branchOrTag - the git branch or tag to use for the README source
- * @param {string} [variantOverride] - override the variant string
- * @return {string}
- */
-export function generateReadmeUrl(branchOrTag = 'master', variantOverride = '') {
-  // LEGACY CODE FOR NON-ESM COMPONENTS
-
-  const nameExtractionData = templateFiller.values;
-  let variantString = '';
-
-  if (!nonEsmComponents.includes(nameExtractionData.name)) {
-    variantString = '_esm';
-  }
-
-  // END LEGACY CODE
-
-  if (variantOverride !== '') {
-    variantString = variantOverride;
-  }
-
-  return generateWCGeneratorUrl(branchOrTag, `componentDocs/README${variantString}.md`);
-}
-
-// Main Markdown magic processors
-// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-/**
- * This is the expected object type when passing something other than a string.
- * @typedef {Object} InputFileType
- * @property {string} remoteUrl - The remote template to fetch
- * @property {string} fileName - Path including file name to store
- * @property {boolean} [overwrite] - Default is true. Choose to overwrite the file if it exists
- */
-
-
-/**
- * @typedef {Object} FileProcessorConfig
- * @property {string} identifier - A unique identifier for this file (used for logging).
- * @property {string | InputFileType} input - path to an input file, including filename
- * @property {string} output - path to an output file, including filename
- * @property {Partial<MarkdownMagicOptions>} [mdMagicConfig] - extra configuration options for md magic
- * @property {Array<(contents: string) => string>} [preProcessors] - extra processor functions to run on content AFTER markdownmagic and BEFORE templateFiller
- * @property {Array<(contents: string) => string>} [postProcessors] - extra processor functions to run on content
- * @property {object} [extraVars] - extra variables to use in the template
- */
-
-
-// Individual file processing steps
-// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-/**
- * Retrieve a remote file using a provided configuration and store at a local path.
- * @param {InputFileType} input - the input file configuration
- * @return {Promise<void>}
- */
-export async function retrieveRemoteFileCopy(input) {
-  const bareFileName = input.fileName
-
-  Logger.log(`Retrieving latest "${bareFileName}" file...`);
-
-  // 0b. Attempt to populate from remote file
-  const contents = await fetch(input.remoteUrl, {
-    redirect: 'follow'
-  }).then(r => r.text());
-
-  // 0c. Write remote contents to local folder as cache
-  await AuroFileHandler.tryWriteFile(input.fileName, contents);
-}
-
-
-/**
- * Run markdown magic on a file.
- * @param {string} input
- * @param {string} output
- * @param {Partial<MarkdownMagicOptions>} [extraMdMagicConfig] - extra configuration options for md magic
- * @return {Promise<void>}
- */
-export async function runMarkdownMagicOnFile(input, output, extraMdMagicConfig = {}) {
-  await applyMarkdownMagic(output, {
-    ...MD_MAGIC_CONFIG,
-    ...extraMdMagicConfig
-  });
-}
-
-
-/**
- * Optionally copy a file to a new location.
- * @param {string} input - the input file path
- * @param {string} output - the output file path
- * @param {boolean} overwrite - whether to overwrite the file if it exists (default is true)
- * @return {Promise<void>}
- */
-export async function optionallyCopyFile(input, output, overwrite = true) {
-  if (await AuroFileHandler.exists(output) && !overwrite) {
-    return;
-  }
-
-  if (!await AuroFileHandler.tryCopyFile(input, output)) {
-    throw new Error(`Error copying "${input}" file to output ${output}`);
-  }
-}
-
-/**
- * Process the content of a file.
- *
- * This is a high level function that performs the following via lower functions:
- * - Read contents of file
- * - Run "markdown-magic" on file contents (optional, *.md specific)
- * - Run template variable replacement on file contents
- * @param {FileProcessorConfig} config - the config for this file
- */
-export async function processContentForFile(config) {
-  const { input: rawInput, output, mdMagicConfig, extraVars = {} } = config
-
-  // Helper vars
-  const derivedInputPath = typeof rawInput === 'string' ? rawInput : rawInput.fileName;
-  const segments = derivedInputPath.split("/")
-  const bareFileName = segments[segments.length - 1]
-
-  // 0. Optionally retrieve a remote file
-  if (typeof rawInput === 'object') {
-    await retrieveRemoteFileCopy(rawInput);
-  }
-
-  // 1. Copy input or local input cache to output
-  await optionallyCopyFile(derivedInputPath, output, rawInput.overwrite ?? true);
-
-  // 2. If the file is a Markdown file, run markdown magic to inject contents and perform replacements
-  if (output.endsWith(".md")) {
-    await runMarkdownMagicOnFile(derivedInputPath, output, mdMagicConfig);
-  }
-
-  // 3a. Read the output file contents
-  let fileContents = await fs.readFile(output, {encoding: 'utf-8'});
-
-  // 3b. Run any pre-processors
-  if (config.preProcessors) {
-    for (const processor of config.preProcessors) {
-      fileContents = processor(fileContents)
-    }
-  }
-
-  // 3c. Replace template variables in output file
-  fileContents = templateFiller.replaceTemplateValues(fileContents, extraVars);
-
-  // 3d. Run any post-processors
-  if (config.postProcessors) {
-    for (const processor of config.postProcessors) {
-      fileContents = processor(fileContents)
-    }
-  }
-
-  // 3e. Write the final file contents
-  if (!await AuroFileHandler.tryWriteFile(output, fileContents)) {
-    throw new Error(`Error writing "${bareFileName}" file to output ${output}`);
-  }
-}
+// Shim for the pre-compiled build. Do not edit.
+// Generated by build/bundleDocsScripts.mjs from src/utils/sharedFileProcessorUtils.mjs.
+// Edit that file, then run `npm run build:bundles`.
+export * from "../../dist/utils/sharedFileProcessorUtils.mjs";

package/scripts/build/deprecatedProseToFieldPlugin.spec.js

@@ -1,188 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { deprecatedProseToFieldPlugin } from "./deprecatedProseToFieldPlugin.mjs";
-
-/**
- * Wrap one or more `entries` (events or slots) in a minimal Custom Elements
- * Manifest shape, run the plugin's `packageLinkPhase` over it, and return the
- * mutated entries so assertions can read their `deprecated` field.
- */
-const run = (kind, entries) => {
-  const manifest = {
-    modules: [
-      {
-        declarations: [{ [kind]: entries }],
-      },
-    ],
-  };
-  deprecatedProseToFieldPlugin().packageLinkPhase({
-    customElementsManifest: manifest,
-  });
-  return manifest.modules[0].declarations[0][kind];
-};
-
-describe("deprecatedProseToFieldPlugin", () => {
-  it("has the expected plugin name", () => {
-    expect(deprecatedProseToFieldPlugin().name).toBe(
-      "deprecated-prose-to-field",
-    );
-  });
-
-  describe("marker + guidance -> string message", () => {
-    it('extracts guidance following a "(deprecated) -" marker', () => {
-      const [entry] = run("events", [
-        {
-          name: "change",
-          description: "(Deprecated) - Use the `input` event instead.",
-        },
-      ]);
-      expect(entry.deprecated).toBe("Use the `input` event instead.");
-    });
-
-    it("extracts guidance for each supported separator (- : – —)", () => {
-      const separators = ["-", ":", "–", "—"];
-      separators.forEach((sep) => {
-        const [entry] = run("events", [
-          {
-            name: "change",
-            description: `**DEPRECATED** ${sep} Use \`input\` instead.`,
-          },
-        ]);
-        expect(entry.deprecated).toBe("Use `input` instead.");
-      });
-    });
-
-    it("trims surrounding whitespace from the guidance text", () => {
-      const [entry] = run("slots", [
-        {
-          name: "legacy",
-          description: "deprecated:   Use the `default` slot instead.   ",
-        },
-      ]);
-      expect(entry.deprecated).toBe("Use the `default` slot instead.");
-    });
-  });
-
-  describe("marker with no guidance -> boolean true", () => {
-    it('flags a "**DEPRECATED**" prose with no replacement guidance', () => {
-      const [entry] = run("slots", [
-        { name: "legacy", description: "**DEPRECATED** legacy slot" },
-      ]);
-      expect(entry.deprecated).toBe(true);
-    });
-
-    it('flags a bare "(deprecated)" marker as true', () => {
-      const [entry] = run("events", [
-        { name: "change", description: "(deprecated)" },
-      ]);
-      expect(entry.deprecated).toBe(true);
-    });
-  });
-
-  describe("non-deprecated entries are untouched", () => {
-    it("does not add a deprecated field when no marker is present", () => {
-      const [entry] = run("events", [
-        { name: "input", description: "Fires when the value changes." },
-      ]);
-      expect(entry).not.toHaveProperty("deprecated");
-    });
-
-    it('does not match unrelated words containing "deprecated" as a substring', () => {
-      const [entry] = run("events", [
-        { name: "input", description: "This is undeprecated behavior." },
-      ]);
-      expect(entry).not.toHaveProperty("deprecated");
-    });
-  });
-
-  describe("pre-existing deprecated values are preserved", () => {
-    it("does not overwrite an already-set string message", () => {
-      const [entry] = run("events", [
-        {
-          name: "change",
-          description: "(Deprecated) - Use `input`.",
-          deprecated: "existing guidance",
-        },
-      ]);
-      expect(entry.deprecated).toBe("existing guidance");
-    });
-
-    it("does not overwrite an already-set boolean false", () => {
-      const [entry] = run("events", [
-        {
-          name: "change",
-          description: "(Deprecated) - Use `input`.",
-          deprecated: false,
-        },
-      ]);
-      expect(entry.deprecated).toBe(false);
-    });
-  });
-
-  describe("malformed / missing descriptions are skipped safely", () => {
-    it("skips entries whose description is not a string", () => {
-      const [noDesc, objDesc] = run("slots", [
-        { name: "a" },
-        { name: "b", description: { text: "deprecated" } },
-      ]);
-      expect(noDesc).not.toHaveProperty("deprecated");
-      expect(objDesc).not.toHaveProperty("deprecated");
-    });
-  });
-
-  describe("applies to both events and slots, leaves other fields alone", () => {
-    it("promotes both events and slots on the same declaration", () => {
-      const manifest = {
-        modules: [
-          {
-            declarations: [
-              {
-                events: [
-                  { name: "change", description: "deprecated - Use `input`." },
-                ],
-                slots: [
-                  { name: "legacy", description: "(Deprecated) legacy slot" },
-                ],
-                attributes: [
-                  {
-                    name: "value",
-                    description: "deprecated - do not touch me",
-                  },
-                ],
-                members: [
-                  { name: "reset", description: "(deprecated) leave me alone" },
-                ],
-              },
-            ],
-          },
-        ],
-      };
-      deprecatedProseToFieldPlugin().packageLinkPhase({
-        customElementsManifest: manifest,
-      });
-      const [decl] = manifest.modules[0].declarations;
-      expect(decl.events[0].deprecated).toBe("Use `input`.");
-      expect(decl.slots[0].deprecated).toBe(true);
-      expect(decl.attributes[0]).not.toHaveProperty("deprecated");
-      expect(decl.members[0]).not.toHaveProperty("deprecated");
-    });
-  });
-
-  describe("does not throw on empty or absent manifest structures", () => {
-    it("handles a manifest with no modules", () => {
-      expect(() =>
-        deprecatedProseToFieldPlugin().packageLinkPhase({
-          customElementsManifest: {},
-        }),
-      ).not.toThrow();
-    });
-
-    it("handles declarations without events or slots arrays", () => {
-      const manifest = { modules: [{ declarations: [{}] }] };
-      expect(() =>
-        deprecatedProseToFieldPlugin().packageLinkPhase({
-          customElementsManifest: manifest,
-        }),
-      ).not.toThrow();
-    });
-  });
-});