@aurodesignsystem/auro-library 2.11.0 → 3.0.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Semantic Release Automated Changelog
 
+# [3.0.0](https://github.com/AlaskaAirlines/auro-library/compare/v2.11.0...v3.0.0) (2024-11-05)
+
+
+### Bug Fixes
+
+* add missing logger import ([8258705](https://github.com/AlaskaAirlines/auro-library/commit/8258705385b20950dba442a59fa41b56052955bf))
+* sourcery feedback - change tag detection ([51b134f](https://github.com/AlaskaAirlines/auro-library/commit/51b134fea57c79e9625b6053296049c19959595a))
+
+
+### Features
+
+* add more consistent "component root" path generator ([c88f5a8](https://github.com/AlaskaAirlines/auro-library/commit/c88f5a8018fcbcbc1deefa35a0152c1696681957))
+* add syncGithubFiles.mjs script ([207009d](https://github.com/AlaskaAirlines/auro-library/commit/207009d000565566aed4687ed45ee7e286528856))
+* **build:** new script that generate extended component files for `wca` to be able to analyze [#85](https://github.com/AlaskaAirlines/auro-library/issues/85) ([ae8e6ab](https://github.com/AlaskaAirlines/auro-library/commit/ae8e6ab41db40df05f53562e14692a943c37d796))
+* change API for generateReadmeURL and processDocs ([a1a975c](https://github.com/AlaskaAirlines/auro-library/commit/a1a975c0d9020bdd71c9da0bf165777c54801e8b))
+
+
+### BREAKING CHANGES
+
+* `processDocFiles` no longer accepts individual config arguments
+
 # [2.11.0](https://github.com/AlaskaAirlines/auro-library/compare/v2.10.1...v2.11.0) (2024-11-01)
 
 

package/README.md

@@ -3,10 +3,10 @@
 <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../docs/partials/description.md) -->
 <!-- The below content is automatically added from ./../docs/partials/description.md -->
 This repository holds shared scripts, utilities, and workflows utilized across repositories along the Auro Design System.
-<!-- AURO-GENERATED-CONTENT:END -->
-
-## Scripts
-
+<!-- AURO-GENERATED-CONTENT:END -->
+
+## Scripts
+
 ### Publish Surge Demo
 
 <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../docs/partials/publishDemo.md) -->
@@ -28,8 +28,9 @@ name: Deploy Demo
 
 on:
   pull_request:
-    branches: [ main ]
-
+    branches: [ main ]
+
+
 jobs:
   call-publish-demo-workflow:
     uses: AlaskaAirlines/auro-library/.github/workflows/publishDemo.yml@main
@@ -43,13 +44,14 @@ Afterwards you will want to make sure to update the script tags you want replace
 
 ```diff
 --    <script type="module" src="../index.js"></script>
-++    <script type="module" src="../index.js" data-demo-script="true"></script>
-```
+++    <script type="module" src="../index.js" data-demo-script="true"></script>
+```
 
 > Note: If you fail to do this, the components will fail to register in your demo.
-<!-- AURO-GENERATED-CONTENT:END -->
----
-
+<!-- AURO-GENERATED-CONTENT:END -->
+
+---
+
 ### Surge Demo Teardown
 
 <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../docs/partials/demoTeardown.md) -->
@@ -59,19 +61,20 @@ This workflow works to automatically delete and clear any surge demos that have
 > Note: This workflow executes on a monthly cronjob on the first of each month.
 
 In order to clear all our surge projects we rely on [this GitHub Action](https://github.com/marketplace/actions/surge-sh-teardown) to handle the deletion logic.
-<!-- AURO-GENERATED-CONTENT:END -->
----
-
+<!-- AURO-GENERATED-CONTENT:END -->
+
+---
+
 ### Dependency Tag Versioning
 
 <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../docs/partials/dependencyTagVersioning.md) -->
 <!-- The below content is automatically added from ./../docs/partials/dependencyTagVersioning.md -->
 This is a two part utility for the purpose of generating a custom string for dependency component tag naming. This is important to prevent [version conflicts](https://www.thinktecture.com/en/web-components/web-components-flaws/#elementor-toc__heading-anchor-0) when multiple versions of a given Auro component may be loaded on a single page.
 
-_Note: The example configuration used below in all code samples assumes `auro-dropdown` is the dependency component. Substitute any Auro component in the example code as needed._
-
-#### Part 1: The Build
-
+_Note: The example configuration used below in all code samples assumes `auro-dropdown` is the dependency component. Substitute any Auro component in the example code as needed._
+
+#### Part 1: The Build
+
 ##### Configuration
 
 1. Create a new file `./scripts/version.js` with the following content:
@@ -92,8 +95,8 @@ versionWriter.writeDepVersionFile('@aurodesignsystem/auro-dropdown'); // duplica
 
 ```json
 "build": "npm-run-all build:version ... etc.",
-```
-
+```
+
 ##### Execution
 
 Once configuration is complete, execute `npm run build`. This must be done once before `npm run dev` when developing locally. When Auro dependencies are initially installed or updated to new versions then `npm run build:version` or a complete `npm run build` must be executed.
@@ -111,10 +114,10 @@ versionWriter.writeDepVersionFile('@aurodesignsystem/auro-dropdown');
 Will result in:
 - A new file created: `./src/dropdownVersion.js`
 - File content will export the version of the component installed. In this case:
-`export default '1.0.0'`
-
-#### Part 2: The Runtime
-
+`export default '1.0.0'`
+
+#### Part 2: The Runtime
+
 ##### Configuration
 
 In the main component JS file located in the `./src` directory add the following:
@@ -139,8 +142,8 @@ In the component properties add the following:
  * @private
  */
 dropdownTag: { type: Object }
-```
-
+```
+
 ##### Usage
 
 The new dynamically named version of `auro-dropdown` may now be used in your component template as follows:
@@ -160,11 +163,11 @@ When the component is rendered during runtime the DOM will now show up as follow
 ```html
 <div>
   <auro-dropdown_1_0_0></auro-dropdown_1_0_0>
-</div>
-```
+</div>
+```
+
+_Note: the numbers attached in the tag name will match the version of the dependency that was installed._
 
-_Note: the numbers attached in the tag name will match the version of the dependency that was installed._
-
 ##### Accessing the dynamically named element with JS
 
 The dynamic component is accessible using a the following string in a JS query selector:
@@ -177,18 +180,18 @@ firstUpdated() {
   this.dropdown = this.shadowRoot.querySelector(this.dropdownTag._$litStatic$);
 };
 ```
-<!-- AURO-GENERATED-CONTENT:END -->
----
-
+<!-- AURO-GENERATED-CONTENT:END -->
+
+---
+
 ### Sync All Templates
 
 <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../docs/partials/syncAllTemplates.md) -->
-<!-- The below content is automatically added from ./../docs/partials/syncAllTemplates.md -->
-
+<!-- The below content is automatically added from ./../docs/partials/syncAllTemplates.md -->
 ### How to Run the `syncAllTemplates.mjs` Script
 
-To run the `syncAllTemplates.mjs` script, you will need to add a new node script into the linked component and point that to the `syncAllTemplates.mjs` file. You can individually run the workflow configurations by pointing to the `syncAllTemplates.mjs` file and adding a `--github` parameter after the path. The same can be done for the linter configurations by adding a `--linters` parameter.
-
+To run the `syncAllTemplates.mjs` script, you will need to add a new node script into the linked component and point that to the `syncAllTemplates.mjs` file. You can individually run the workflow configurations by pointing to the `syncAllTemplates.mjs` file and adding a `--github` parameter after the path. The same can be done for the linter configurations by adding a `--linters` parameter.
+
 #### Example Calls
 
 ```
@@ -205,4 +208,28 @@ To run the `syncAllTemplates.mjs` script, you will need to add a new node script
 // Only sync linter configuration templates
 "syncTemplates": "./node_modules/@aurodesignsystem/auro-library/scripts/config/syncAllTemplates.mjs --linters"
 ```
-<!-- AURO-GENERATED-CONTENT:END -->
+<!-- AURO-GENERATED-CONTENT:END -->
+
+
+---
+
+### Prep to build api.md
+
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../docs/partials/generateWcaComponent.md) -->
+<!-- The below content is automatically added from ./../docs/partials/generateWcaComponent.md -->
+# How to Run the `generateWcaComponent.mjs` Script
+
+To run the `generateWcaComponent.mjs` script, you need to provide the file paths for the components you want to process with WCA. This script should be executed only once after adding a new component to the project. Upon running the script, `.js` files will be generated in the `scripts/wca` folder.
+
+## Example Calls
+
+```json
+// Common case: 1 component in 1 project
+"build:api:prepare": "node ./node_modules/@aurodesignsystem/auro-library/scripts/generateWcaComponent.mjs 'src/auro-flight.js'"
+```
+
+```
+// multiple components in 1 project
+"build:api:prepare": "node ./node_modules/@aurodesignsystem/auro-library/scripts/config/syncAllTemplates.mjs 'src/auro-flight*.js'"
+```
+<!-- AURO-GENERATED-CONTENT:END -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aurodesignsystem/auro-library",
-  "version": "2.11.0",
+  "version": "3.0.0",
   "description": "This repository holds shared scripts, utilities, and workflows utilized across repositories along the Auro Design System.",
   "repository": {
     "type": "git",

package/scripts/build/generateDocs.mjs

@@ -1,285 +1,24 @@
-import path from 'path';
-import * as mdMagic from 'markdown-magic';
-import fs from 'node:fs/promises';
-import { fileURLToPath } from 'url';
+// ------------------------------------------------------
+// Docs Generation
+// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+//
+// This script will generate the docs for the component
+// based on example HTML, markdown files, and more.
+//
+// The actions in this file live in:
+// scripts/build/processors/defaultDocsProcessor.mjs
+//
+// This script is intended to be run AS-IS without modification.
+// To run a different processor, please see the defaultDocsProcessor.mjs file
+// and re-create in your repo OR add a new processor file.
+// ------------------------------------------------------
 
-import AuroLibraryUtils from "../utils/auroLibraryUtils.mjs";
-import { AuroTemplateFiller } from "./auroTemplateFiller.mjs";
-import { AuroFileHandler } from "./auroFileHandler.mjs";
 import {Logger} from "../utils/logger.mjs";
+import {processDocFiles} from "./processors/defaultDocsProcessor.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();
-export const auroFileHandler = new AuroFileHandler();
-
-// 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}
- */
-export function fromAuroComponentRoot(pathLike) {
-  const currentDir = fileURLToPath(new URL('.', import.meta.url))
-  return path.join(currentDir, `${auroLibraryUtils.projectRootFromBuildScriptDir}${pathLike}`)
-}
-
-
-// External assets
-// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-/**
- * @param {string} tag - the release version tag to use instead of master
- * @param {string} [variantOverride] - override the variant string
- * @return {string}
- */
-export function generateReadmeUrl(tag = '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;
-  }
-
-  const baseRepoUrl = 'https://raw.githubusercontent.com/AlaskaAirlines/WC-Generator'
-  if (tag !== 'master') {
-    return `${baseRepoUrl}/refs/tags/${tag}/componentDocs/README` + variantString + '.md';
-  }
-
-  return `${baseRepoUrl}/master/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 | InputFileType} input - path to input file, including filename
- * @property {string} output - path to output file, including filename
- * @property {Partial<MarkdownMagicOptions>} [mdMagicConfig] - extra configuration options for md magic
- * @property {Array<(contents: string) => string>} [postProcessors] - extra processor functions to run on content
- */
-
-
-// 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
+processDocFiles().then(() => {
+  Logger.log('Docs processed successfully');
+}).
+  catch((err) => {
+    Logger.error(`Error processing docs: ${err.message}`);
   });
-}
-
-
-/**
- * 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 } = 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. Replace template variables in output file
-  fileContents = templateFiller.replaceTemplateValues(fileContents);
-
-  // 3c. Run any post-processors
-  if (config.postProcessors) {
-    for (const processor of config.postProcessors) {
-      fileContents = processor(fileContents)
-    }
-  }
-
-  // 3d. Write the final file contents
-  if (!await AuroFileHandler.tryWriteFile(output, fileContents)) {
-    throw new Error(`Error writing "${bareFileName}" file to output ${output}`);
-  }
-}
-
-// Finally, the main function
-// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-/**
- *
- * @param {string} remoteReadmeVersion - the release version tag to use instead of master
- * @param {string} [readmeVariant] - the release version tag to use instead of master
- * @return {Promise<void>}
- */
-export async function processDocFiles(remoteReadmeVersion = 'master', readmeVariant = undefined) {
-  // setup
-  await templateFiller.extractNames();
-
-  // process
-  // README.md
-
-  Logger.warn('WARNING: overwrite is set to FALSE for README.md - please update this when template changes are merged');
-  await processContentForFile({
-    input: {
-      remoteUrl: generateReadmeUrl(remoteReadmeVersion, readmeVariant),
-      fileName: fromAuroComponentRoot(`/docTemplates/README.md`),
-      overwrite: false
-    },
-    output: fromAuroComponentRoot("/README.md")
-  })
-
-  // Demo MD file
-  await processContentForFile({
-    input: fromAuroComponentRoot("/docs/partials/index.md"),
-    output: fromAuroComponentRoot("/demo/index.md"),
-    mdMagicConfig: {
-      output: {
-        directory: fromAuroComponentRoot("/demo")
-      }
-    }
-  })
-
-  // API MD file
-  await processContentForFile({
-    input: fromAuroComponentRoot("/docs/partials/api.md"),
-    output: fromAuroComponentRoot("/demo/api.md"),
-    postProcessors: [
-      templateFiller.formatApiTable
-    ]
-  })
-}

package/scripts/build/generateWcaComponent.mjs

@@ -0,0 +1,43 @@
+import fs from 'fs';
+import path from 'path';
+import glob from 'glob';
+import util from 'util';
+import getTemplatedComponentCode from './prepWcaCompatibleCode.mjs';
+
+const promisifiedGlob = util.promisify(glob);
+
+const WAC_DIR = path.resolve(process.cwd(), './scripts/wca');
+
+async function globPath(sources) {
+  try {
+    const fileArrays = await Promise.all(
+      sources.map(source => promisifiedGlob(source))
+    );
+    return fileArrays.flat();
+  } catch (err) {
+    console.error('Error processing glob patterns:', err);
+    throw err; // Re-throw to handle failure at caller
+  }
+}
+
+async function createExtendsFile(filePaths) {
+  if (!fs.existsSync(WAC_DIR)) {
+    await fs.promises.mkdir(WAC_DIR, { recursive: true });
+  }
+
+  for (const filePath of filePaths) {
+    const resolvedPath = path.resolve(process.cwd(), filePath);
+    const fileContent = await fs.promises.readFile(resolvedPath, 'utf-8',);
+    const newPath = path.resolve(WAC_DIR, `${path.basename(filePath)}`);
+    const newCode = getTemplatedComponentCode(fileContent, path.relative(WAC_DIR, filePath));
+    await fs.promises.writeFile(newPath, newCode);
+  }
+}
+
+async function main() {
+  // files to analyze
+  const filePaths = await globPath(process.argv.slice(2));
+  await createExtendsFile(filePaths);
+}
+
+main();

package/scripts/build/prepWcaCompatibleCode.mjs

@@ -0,0 +1,19 @@
+export default (code, sourcePath) => {
+  const defaultTag = (code.match(/static register\(name \= (.+)\)/) || code.match(/customElements.get\((.+?)\)/))[1];
+  const className = code.match(/export class (.+) extends/)?.[1];
+  const classDesc = code.match(/\/\*\*((.|\n)*?)\*\//)?.[1] || '';
+
+  if (!defaultTag || !className) {
+    return code;
+  }
+  return `
+import { ${className} } from '${sourcePath}';
+
+/**${classDesc}*/
+class ${className}WCA extends ${className} {}
+
+if (!customElements.get(${defaultTag})) {
+  customElements.define(${defaultTag}, ${className}WCA);
+}
+`;
+};

package/scripts/build/processors/defaultDocsProcessor.mjs

@@ -0,0 +1,83 @@
+import {Logger} from "../../utils/logger.mjs";
+import {
+  fromAuroComponentRoot,
+  generateReadmeUrl,
+  processContentForFile,
+  templateFiller
+} from "../../utils/sharedFileProcessorUtils.mjs";
+
+/**
+ * Processor config object.
+ * @typedef {Object} ProcessorConfig
+ * @property {boolean} [overwriteLocalCopies=true] - The release version tag to use instead of master.
+ * @property {string} [remoteReadmeVersion="master"] - The release version tag to use instead of master.
+ * @property {string} [remoteReadmeVariant=""] - The variant string to use for the README source.
+ * (like "_esm" to make README_esm.md).
+ */
+
+
+/**
+ * @param {ProcessorConfig} config - The configuration for this processor.
+ */
+export const defaultDocsProcessorConfig = {
+  overwriteLocalCopies: true,
+  remoteReadmeVersion: "master",
+  // eslint-disable-next-line no-warning-comments
+  // TODO: remove this variant when all components are updated to use latest auro-library
+  // AND the default README.md is updated to use the new paths
+  readmeVariant: "_updated_paths"
+};
+
+/**
+ * @param {ProcessorConfig} config - The configuration for this processor.
+ * @returns {import('../utils/sharedFileProcessorUtils').FileProcessorConfig[]}
+ */
+export const fileConfigs = (config = defaultDocsProcessorConfig) => [
+  // README.md
+  {
+    identifier: 'README.md',
+    input: {
+      remoteUrl: generateReadmeUrl(config.remoteReadmeVersion, config.remoteReadmeVariant),
+      fileName: fromAuroComponentRoot(`/docTemplates/README.md`),
+      overwrite: config.overwriteLocalCopies
+    },
+    output: fromAuroComponentRoot("/README.md")
+  },
+  // index.md
+  {
+    identifier: 'index.md',
+    input: fromAuroComponentRoot("/docs/partials/index.md"),
+    output: fromAuroComponentRoot("/demo/index.md"),
+    mdMagicConfig: {
+      output: {
+        directory: fromAuroComponentRoot("/demo")
+      }
+    }
+  },
+  // api.md
+  {
+    identifier: 'api.md',
+    input: fromAuroComponentRoot("/docs/partials/api.md"),
+    output: fromAuroComponentRoot("/demo/api.md"),
+    postProcessors: [templateFiller.formatApiTable],
+  }
+];
+
+/**
+ *
+ * @param {ProcessorConfig} config - The configuration for this processor.
+ * @return {Promise<void>}
+ */
+export async function processDocFiles(config = defaultDocsProcessorConfig) {
+  // setup
+  await templateFiller.extractNames();
+
+  for (const fileConfig of fileConfigs(config)) {
+    try {
+      // eslint-disable-next-line no-await-in-loop
+      await processContentForFile(fileConfig);
+    } catch (err) {
+      Logger.error(`Error processing ${fileConfig.identifier}: ${err.message}`);
+    }
+  }
+}

package/scripts/build/processors/defaultDotGithubSync.mjs

@@ -0,0 +1,83 @@
+import {Logger} from "../../utils/logger.mjs";
+import {
+  fromAuroComponentRoot,
+  generateWCGeneratorUrl,
+  processContentForFile,
+  templateFiller
+} from "../../utils/sharedFileProcessorUtils.mjs";
+
+/**
+ * Processor config object.
+ * @typedef {Object} ProcessorConfig
+ * @property {boolean} [overwriteLocalCopies=true] - The release version tag to use instead of master.
+ * @property {string} [generatorTemplateVersion="master"] - The release version tag to use instead of master.
+ * (like "_esm" to make README_esm.md).
+ */
+
+const DOT_GITHUB_PATH = '.github';
+const ISSUE_TEMPLATE_PATH = `${DOT_GITHUB_PATH}/ISSUE_TEMPLATE`;
+
+/**
+ * @type {ProcessorConfig} config - The default configuration for this processor.
+ */
+const defaultGitHubSyncConfig = {
+  overwriteLocalCopies: true,
+  generatorTemplateVersion: "master",
+};
+
+/**
+ * @param {ProcessorConfig} config - The configuration for this processor.
+ * @returns {import('../utils/sharedFileProcessorUtils').FileProcessorConfig[]}
+ */
+const defaultGitHubTemplateFiles = (config = defaultGitHubSyncConfig) => [
+  // bug_report.yml
+  {
+    identifier: 'bug_report.yml',
+    input: {
+      remoteUrl: generateWCGeneratorUrl(config.generatorTemplateVersion, `templates/${ISSUE_TEMPLATE_PATH}/bug_report.yml`),
+      fileName: fromAuroComponentRoot(`docTemplates/${ISSUE_TEMPLATE_PATH}/bug_report.yml`),
+      overwrite: config.overwriteLocalCopies
+    },
+    output: fromAuroComponentRoot(`${ISSUE_TEMPLATE_PATH}/bug_report.yml`)
+  },
+  // config.yml
+  {
+    identifier: 'config.yml',
+    input: {
+      remoteUrl: generateWCGeneratorUrl(config.generatorTemplateVersion, `templates/${ISSUE_TEMPLATE_PATH}/config.yml`),
+      fileName: fromAuroComponentRoot(`docTemplates/${ISSUE_TEMPLATE_PATH}/config.yml`),
+      overwrite: config.overwriteLocalCopies
+    },
+    output: fromAuroComponentRoot(`${ISSUE_TEMPLATE_PATH}/config.yml`)
+  },
+  // PULL_REQUEST_TEMPLATE.md
+  {
+    identifier: 'PULL_REQUEST_TEMPLATE.md',
+    input: {
+      remoteUrl: generateWCGeneratorUrl(config.generatorTemplateVersion, `templates/${DOT_GITHUB_PATH}/PULL_REQUEST_TEMPLATE.md`),
+      fileName: fromAuroComponentRoot(`docTemplates/${DOT_GITHUB_PATH}/PULL_REQUEST_TEMPLATE.md`),
+      overwrite: config.overwriteLocalCopies
+    },
+    output: fromAuroComponentRoot(`${DOT_GITHUB_PATH}/PULL_REQUEST_TEMPLATE.md`)
+  },
+];
+
+/**
+ *
+ * @param {ProcessorConfig} config - The configuration for this processor.
+ * @return {Promise<void>}
+ */
+export async function syncGithubFiles(config = defaultGitHubSyncConfig) {
+  // setup
+  await templateFiller.extractNames();
+
+  for (const file of defaultGitHubTemplateFiles(config)) {
+    try {
+      Logger.log(`Processing file: ${file.identifier}`);
+      // eslint-disable-next-line no-await-in-loop
+      await processContentForFile(file);
+    } catch (error) {
+      Logger.error(`Error processing file: ${file.identifier}, ${error.message}`);
+    }
+  }
+}

package/scripts/build/syncGithubFiles.mjs

@@ -0,0 +1,25 @@
+// ------------------------------------------------------
+// GitHub Config Sync
+// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+//
+// This script will synchronize shared GitHub config
+// files to the local repo (eventually, anything that lives
+// in the .github directory).
+//
+// The actions in this file live in:
+// scripts/build/processors/defaultDotGithubSync.mjs
+//
+// This script is intended to be run AS-IS without modification.
+// To run a different processor, please see the defaultDotGithubSync.mjs file
+// and re-create in your repo OR add a new processor file.
+// ------------------------------------------------------
+
+import {syncGithubFiles} from "./processors/defaultDotGithubSync.mjs";
+import {Logger} from "../utils/logger.mjs";
+
+syncGithubFiles().then(() => {
+  Logger.log('Docs processed successfully');
+}).
+  catch((err) => {
+    Logger.error(`Error processing docs: ${err.message}`);
+  });

package/scripts/utils/auroLibraryUtils.mjs

@@ -6,15 +6,30 @@
 /* eslint-disable arrow-parens, line-comment-position, no-console, no-inline-comments, no-magic-numbers, prefer-arrow-callback, require-unicode-regexp, jsdoc/require-description-complete-sentence, prefer-named-capture-group */
 
 import * as fs from 'fs';
-import fsAsync from 'node:fs/promises';
 import * as path from 'path';
 import chalk from 'chalk';
+import {Logger} from "./logger.mjs";
 
 export default class AuroLibraryUtils {
-  PROJECT_ROOT_FROM_SCRIPTS__BUILD = "./../../../../.."
+  getDirname() {
+    if (typeof __dirname === 'undefined') {
+      Logger.warn('Unable to determine project root as __dirname is not defined. Assuming current directory is okay!', true);
+      return '';
+    }
+
+    // eslint-disable-next-line no-undef
+    return __dirname;
+  }
+
+  get getProjectRootPath() {
+    const currentDir = this.getDirname();
+
+    if (!currentDir.includes('node_modules')) {
+      Logger.warn(`Unable to determine best project root as node_modules \nis not in the directory path.\n\nAssuming - "${currentDir}"`, true);
+      return currentDir;
+    }
 
-  get projectRootFromBuildScriptDir() {
-    return this.PROJECT_ROOT_FROM_SCRIPTS__BUILD
+    return currentDir.split('node_modules')[0];
   }
 
   /**
@@ -147,8 +162,8 @@ export default class AuroLibraryUtils {
       'name': pName.substring(nameStart + 1),
       'nameCap': pName.substring(nameStart + 1)[0].toUpperCase() + pName.substring(nameStart + 2),
       'version': packageJson.version,
-      'tokensVersion': packageJson.peerDependencies['\@aurodesignsystem/design-tokens'].substring(1),
-      'wcssVersion': packageJson.peerDependencies['\@aurodesignsystem/webcorestylesheets'].substring(1)
+      'tokensVersion': packageJson.peerDependencies['@aurodesignsystem/design-tokens'].substring(1),
+      'wcssVersion': packageJson.peerDependencies['@aurodesignsystem/webcorestylesheets'].substring(1)
 
     };
   }
@@ -191,19 +206,5 @@ export default class AuroLibraryUtils {
      */
     fs.writeFileSync(destination, result, { encoding: 'utf8'});
   }
-
-  /**
-   * Check if a file or directory exists.
-   * @param filePath
-   * @return {Promise<boolean>}
-   */
-  async existsAsync(filePath) {
-    try {
-      await fsAsync.access(filePath);
-      return true;
-    } catch {
-      return false;
-    }
-  }
 }
 

package/scripts/utils/sharedFileProcessorUtils.mjs

@@ -0,0 +1,258 @@
+import path from 'path';
+import * as mdMagic from 'markdown-magic';
+import fs from 'node:fs/promises';
+import { fileURLToPath } from 'url';
+
+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) {
+  const currentDir = fileURLToPath(new URL('.', import.meta.url))
+  return path.join(currentDir, `${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>} [postProcessors] - extra processor functions to run on content
+ */
+
+
+// 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 } = 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. Replace template variables in output file
+  fileContents = templateFiller.replaceTemplateValues(fileContents);
+
+  // 3c. Run any post-processors
+  if (config.postProcessors) {
+    for (const processor of config.postProcessors) {
+      fileContents = processor(fileContents)
+    }
+  }
+
+  // 3d. Write the final file contents
+  if (!await AuroFileHandler.tryWriteFile(output, fileContents)) {
+    throw new Error(`Error writing "${bareFileName}" file to output ${output}`);
+  }
+}