@aurodesignsystem-dev/auro-library 0.0.0-pr187.0

package/scripts/utils/sharedFileProcessorUtils.mjs

@@ -0,0 +1,270 @@
+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}`);
+  }
+}

package/shellScripts/README.md

@@ -0,0 +1,58 @@
+# Automated shell scripts
+
+In this repo is a single shell script that contains functions designed to do automated tasks locally, prepare those updates and push them to their individual remote repos.
+
+### Install shell script
+
+This shell script, and others, can be installed anywhere in your local environment. If you chose, installing the npm in a global space is acceptable as well.
+
+To access the script(s) from your command line, it is required to source the file when a new shell is opened.
+
+With BASH, it is common to add a `source` command in the `~./bash_profile` config file. In the following code example the `automation.sh` shell script was placed into the `~/.bash_resources` directory.
+
+```shell
+source ~/.bash_resources/automation.sh
+```
+
+### What's in the script?
+
+`gitVersion`
+
+This is a simple function that when within a repo's directory, from the CLI you can run `gitVersion` and it will print out the version number from the repo's package.json file.
+
+This is handy for things like having an alias to a repo's directory. For example, you could have an alias for the `auro-menu` component that takes you to the repo's directory and prints out the package version.
+
+```shell
+alias menu="cd ~/src/auro/menu && gitVersion"
+```
+
+`updateRepos`
+
+This function takes an array of all the repo directories in your local setup that you want to loop through, determine what the HEAD branch is, check it out and perform a `git pull`.
+
+With this one command you can ensure that all your local repos have the latest versions from the remote.
+
+`addToRepo`
+
+This function is like a sandwich. There is the first part that ensures that the repo is up to date. Much like the `updateRepos` function, and then it ends with a commit and a push.
+
+In the middle is the part where custom actions can be written that allow for simple repetitive updates to be scripted.
+
+Need to add a new file to all the repos?
+
+```shell
+command cp ../WC-Generator/.github/workflows/addToProject.yml .github/workflows/addToProject.yml
+```
+
+Need to do a search and replace of content in a specific file and delete the temp resource created?
+
+```shell
+command sed -i -e 's/@v3/@v4/g' .github/workflows/testPublish.yml
+command rm .github/workflows/testPublish.yml-e
+```
+
+`openActions`
+
+This really simple function takes an array and constructs a URL on the fly to be opened by your default browser.
+
+This function specifically opens all the Auro element actions page. This is a great way to do a quick scan of all the repos to ensure that actions are working as expected and there are no unknown blocked releases because you missed a notification from Github.

package/shellScripts/automation.sh

@@ -0,0 +1,104 @@
+#!/bin/bash
+
+# Simple function that looks into a repo's package.json and print out
+# the current verison released.
+function gitVersion {
+  # Version key/value should be on his own line
+  PACKAGE_VERSION=$(cat package.json \
+    | grep version \
+    | head -1 \
+    | awk -F: '{ print $2 }' \
+    | sed 's/[",^|]//g')
+
+  echo -e "Package version -$PACKAGE_VERSION"
+}
+
+# This function will loop through all the repos listed
+# and do a `git pull` for each repo before moving on.
+function updateRepos {
+  ## declare an array variable
+  declare -a arr=("alert" "WC-Generator/" "drawer/" "wcss/" "hyperlink/" "auro-lockup/" "icons/" "flight/" "dialog/" "banner/" "card/" "nav/" "datepicker/" "popover/" "dropdown/" "radio/" "checkbox/" "button/" "loader/" "flightline/" "b2top/" "combobox/" "carousel/" "table/" "toast/" "icon/" "select/" "sidenav/" "pane/" "header/" "datetime/" "input/" "avatar/" "badge/" "background/" "interruption/" "skeleton/" "menu/" "eslint-config/" "tokens/"
+ )
+
+  ## now loop through the above array
+  for i in "${arr[@]}"
+  do
+    echo -e "\n$i\n"
+    command cd ~/src/auro/"$i"
+    echo "look at me in '$i'"
+    gitVersion
+    branch=$(git symbolic-ref --short HEAD)
+    echo -e "making sure on $branch branch"
+    command git checkout $branch
+    echo -e "updating repo from remote"
+    command git pull
+
+  done
+}
+
+
+function addToRepo {
+  ## declare an array variable
+  declare -a arr=("wcss/" "icons/" "banner/" "card/" "radio/" "checkbox/" "button/" "loader/" "flightline/" "b2top/" "combobox/" "carousel/" "table/" "toast/" "icon/" "select/" "sidenav/" "pane/" "header/" "datetime/" "input/" "avatar/" "badge/" "background/" "interruption/" "skeleton/" "menu/" "eslint-config/" "tokens/")
+
+  ## now loop through the above array
+  for i in "${arr[@]}"
+  do
+    # CD into dir and ensure that the repo is
+    # up to date with a `git pull`
+    # -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
+    echo -e "\n$i\n"
+    command cd ~/src/auro/"$i"
+    echo "look at me in '$i'"
+    sleep 1
+    gitVersion
+    branch=$(git symbolic-ref --short HEAD) # determins if the head is `master` or `main`
+    echo -e "making sure on $branch branch" # uses variable
+    command git checkout $branch # uses variable
+    echo -e "updating repo from remote"
+    command git pull
+    sleep 1
+
+    # Customize the action to be performed
+    # -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
+    # This action will copy a resource from one dir to another
+    # to update the repo
+    command cp ../WC-Generator/.github/workflows/addToProject.yml .github/workflows/addToProject.yml
+    echo -e "Copied file to '$i' repo.\n"
+
+    # This action will look for `@v3` and replace with @v4
+    # in .github/workflows/testPublish.yml, then delete the
+    # temporary file that was created.
+    command sed -i -e 's/@v3/@v4/g' .github/workflows/testPublish.yml
+    command rm .github/workflows/testPublish.yml-e
+    echo -e "Updated workflow script\n"
+
+    # Perform git functions to add, commit and push
+    # -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
+    sleep 1
+    command git add --all
+    sleep 1
+    command git commit -m "build: add auto-assign to project script"
+    echo -e "Commit added to Git\n"
+    echo -e "Pushing to the remote\n"
+    sleep 2
+    command git push
+    echo -e "Update pushed to the remote\n"
+    sleep 2
+
+  done
+}
+
+# This function will loop through the array to construct a URL for each repo's
+# actions landing page. This is great for validating that actions have
+# run successfully.
+function openActions {
+  ## declare an array variable
+  declare -a arr=("auro-alert" "WC-Generator/" "auro-drawer/" "webcorestylesheets/" "auro-hyperlink/" "auro-lockup/" "icons/" "auro-flight/" "auro-dialog/" "auro-banner/" "auro-card/" "auro-nav/" "auro-datepicker/" "auro-popover/" "auro-dropdown/" "auro-radio/" "auro-checkbox/" "auro-button/" "auro-loader/" "auro-flightline/" "auro-backtotop/" "auro-combobox/" "auro-carousel/" "auro-table/" "auro-toast/" "auro-icon/" "auro-select/" "auro-sidenav/" "auro-pane/" "auro-header/" "auro-datetime/" "auro-input/" "auro-avatar/" "auro-badge/" "auro-background/" "auro-interruption/" "auro-skeleton/" "auro-menu/" "eslint-config-auro/" "aurodesigntokens/")
+
+  ## now loop through the above array
+  for i in "${arr[@]}"
+  do
+    command open https://github.com/AlaskaAirlines/"$i"actions
+  done
+}