Conversation
…command - Add compileDemoScss to build/dev paths for consistent demo SCSS handling - Copy processed README.md to demo directory as readme.md after docs build - Add --watch flag to docs command with chokidar file watcher - Add dedicated demo SCSS watcher in dev watch mode (separate from rollup) - Fix feedback loops by pausing watcher during rebuilds and ignoring output files - Add .min.css to output ignore patterns across all watchers Co-authored-by: Copilot <copilot@github.com>
- Add -r, --readme-template flag to docs/dev/build commands for custom README template - Support both URLs and local file paths for README template input - Extract copyReadmeToDemo to shared util - Extract MODULE_DIRS to shared paths.js - Unify SIGINT shutdown handlers via shared shutdown utility Co-authored-by: Copilot <copilot@github.com>
- Add exports field resolution to Sass node_modules importer - Add loadPaths for monorepo node_modules directory traversal - Properly resolve bare specifiers like @aurodesignsystem/config/demo-styles via the package's exports map instead of hardcoded src/ lookup
Port formkit docProcessor enhancements to auro-cli: - Resolve second-pass AURO-GENERATED-CONTENT tags from inlined partials - Replace template variables in nested partial content - Convert markdown code fences to HTML pre/code blocks - Normalize whitespace for marked.js compatibility
…ars support Co-authored-by: Copilot <copilot@github.com>
Reviewer's GuideExtends the docs build and dev tooling to better support monorepo setups, richer README templating, demo asset compilation, and watch-mode workflows, while improving dev server handling of node_modules assets and CommonJS modules. Sequence diagram for watch mode docs rebuild workflowsequenceDiagram
actor Dev as Developer
participant CLI as docs_command
participant Docs as watchDocs
participant FS as chokidar_watcher
participant Build as runDefaultDocsBuild
participant Copy as copyReadmeToDemo
participant Scss as compileDemoScss
participant Bundle as buildDemoBundle
participant Shutdown as shutdown_utils
Dev->>CLI: run docs --watch --readme-template
CLI->>Docs: watchDocs(options)
Docs->>FS: chokidar.watch(watchPaths, ignored)
Docs->>Shutdown: registerWatcher(watcher)
Docs->>Shutdown: installShutdownHandler()
FS-->>Docs: ready (watching)
FS-->>Docs: file change event
Docs->>Docs: debounce rebuild timer
Docs->>Docs: rebuild(triggerPath)
Docs->>Build: runDefaultDocsBuild(options)
Build-->>Docs: docs markdown and README generated
Docs->>Copy: copyReadmeToDemo()
Copy-->>Docs: demo/readme.md updated
Docs->>Scss: compileDemoScss()
Scss-->>Docs: demo .scss -> .min.css
Docs->>Bundle: buildDemoBundle(options)
Bundle-->>Docs: demo JS bundle updated
Docs-->>CLI: rebuild complete
Dev-->>CLI: SIGINT (Ctrl+C)
CLI->>Shutdown: SIGINT handler invoked
Shutdown->>FS: watcher.close()
Shutdown-->>Dev: "All done! See you next time."
Class diagram for updated docs, build, and utility modulesclassDiagram
class defaultDocsBuild_js {
+ProcessorConfig defaultDocsProcessorConfig
+fileConfigs(config, skipReadme)
+processDocFiles(config, skipReadme)
+runDefaultDocsBuild(options)
-pathFromCwd(pathLike)
-findMonorepoRoot(startDir)
-postProcessMarkdownFile(outputPath, extraVars)
}
class bundleHandlers_js {
+generateDocs(options)
+compileDemoScss(demoDir)
+buildDemoBundle(options)
-createNodeModulesImporter()
}
class docs_index_ts {
+docs(options)
+serve(options)
+api(options)
+cem(options)
+watchDocs(options)
}
class devServerUtils_js {
+startDevelopmentServer(options)
-nodeModulesCssPlugin()
-cjsToEsmPlugin()
-resolveWdsPath(urlPath, rootDir)
}
class watchModeHandlers_js {
+handleWatcherEvents(options, onInitialBuildComplete)
+setupWatchModeListeners(watcher, scssWatcher)
-isOutputFile(filePath)
-runBuildTask(type, fn)
}
class build_index_js {
+runProductionBuild(options)
+setupWatchMode(options)
}
class shutdown_js {
+registerWatcher(watcher)
+installShutdownHandler()
-watchers
-handlerInstalled
}
class copyReadmeToDemo_js {
+copyReadmeToDemo()
}
class paths_js {
+MODULE_DIRS
}
class configUtils_js {
+getPluginsConfig(modulePaths, options)
+getWatcherConfig(watchOptions)
}
class docs_command_ts {
+docsCommand
}
defaultDocsBuild_js --> bundleHandlers_js : uses compileDemoScss
defaultDocsBuild_js --> copyReadmeToDemo_js : uses copyReadmeToDemo
bundleHandlers_js --> paths_js : uses MODULE_DIRS
bundleHandlers_js --> shutdown_js : uses registerWatcher
docs_index_ts --> defaultDocsBuild_js : uses runDefaultDocsBuild
docs_index_ts --> bundleHandlers_js : uses compileDemoScss
docs_index_ts --> bundleHandlers_js : uses buildDemoBundle
docs_index_ts --> copyReadmeToDemo_js : uses copyReadmeToDemo
docs_index_ts --> shutdown_js : uses registerWatcher
devServerUtils_js --> paths_js : uses MODULE_DIRS
watchModeHandlers_js --> bundleHandlers_js : uses generateDocs
watchModeHandlers_js --> bundleHandlers_js : uses compileDemoScss
watchModeHandlers_js --> shutdown_js : uses registerWatcher
build_index_js --> bundleHandlers_js : uses generateDocs
build_index_js --> bundleHandlers_js : uses compileDemoScss
docs_command_ts --> docs_index_ts : invokes docs, serve, api, cem, watchDocs
configUtils_js --> paths_js : uses DEFAULTS.moduleDirectories
Flow diagram for extended docs build pipeline with monorepo supportflowchart TD
subgraph DocsBuild[runDefaultDocsBuild]
A_opts["Options (readmeTemplate, skipReadme)"]
A_proc[processDocFiles]
A_readmeCfg["Determine README input (remote or local)"]
A_monorepo[findMonorepoRoot]
A_pkg["Read monorepo package.json"]
A_vars["Build extraVars (monorepoName + config.extraVars)"]
A_files[fileConfigs]
A_loop{{"for each fileConfig"}}
A_procFile[processContentForFile with extraVars]
A_mdCheck{"output endsWith .md"}
A_post[postProcessMarkdownFile]
A_copy[copyReadmeToDemo]
A_scss[compileDemoScss]
A_js[buildDemoBundle]
A_opts --> A_proc
A_opts --> A_readmeCfg
A_readmeCfg --> A_files
A_proc --> A_monorepo
A_monorepo --> A_pkg
A_pkg --> A_vars
A_vars --> A_files
A_files --> A_loop
A_loop --> A_procFile
A_procFile --> A_mdCheck
A_mdCheck -- yes --> A_post
A_mdCheck -- no --> A_loop
A_post --> A_loop
A_loop -->|all files done| A_copy
A_copy --> A_scss
A_scss --> A_js
end
subgraph PostProcess[postProcessMarkdownFile]
P_read["Read output .md"]
P_tags["Resolve empty AURO-GENERATED-CONTENT tags from FILE/CODE src"]
P_demoDir["Fallback to demo directory for src resolution"]
P_tpl["templateFiller.replaceTemplateValues with extraVars"]
P_fences["Convert ``` fences to <pre><code> blocks"]
P_ws["Normalize whitespace for marked.js (pre code blocks)"]
P_strip["Strip leading whitespace before HTML tags outside <pre>"]
P_write["Write normalized .md"]
P_read --> P_tags
P_tags --> P_demoDir
P_demoDir --> P_tpl
P_tpl --> P_fences
P_fences --> P_ws
P_ws --> P_strip
P_strip --> P_write
end
A_post --> PostProcess
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
jason-capsule42
previously approved these changes
May 6, 2026
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
Hey - I've left some high level feedback:
- The
docscommand runs an initialdocs()build and thenwatchDocs()immediately triggers another fullrunDefaultDocsBuild, so when--watchis used you might want to skip the second initial build inwatchDocs(or skip the first one) to avoid redundant work and duplicated console noise. - In
setupWatchModeListenersandwatchDocs, the shutdown handling and watcher registration now useregisterWatcher/installShutdownHandler; consider centralizing the SIGINT hook at a single entry point to avoid subtle differences in shutdown behavior between build and docs watch flows. - The
postProcessMarkdownFileimplementation currently reads and writes the same file up to three times per run; you could simplify and reduce I/O by chaining the AURO tag expansion, fence conversion, and whitespace normalization in-memory and writing the file once at the end.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- The `docs` command runs an initial `docs()` build and then `watchDocs()` immediately triggers another full `runDefaultDocsBuild`, so when `--watch` is used you might want to skip the second initial build in `watchDocs` (or skip the first one) to avoid redundant work and duplicated console noise.
- In `setupWatchModeListeners` and `watchDocs`, the shutdown handling and watcher registration now use `registerWatcher`/`installShutdownHandler`; consider centralizing the SIGINT hook at a single entry point to avoid subtle differences in shutdown behavior between build and docs watch flows.
- The `postProcessMarkdownFile` implementation currently reads and writes the same file up to three times per run; you could simplify and reduce I/O by chaining the AURO tag expansion, fence conversion, and whitespace normalization in-memory and writing the file once at the end.Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
Co-authored-by: Copilot <copilot@github.com>
jason-capsule42
approved these changes
May 6, 2026
Member
|
🎉 This PR is included in version 3.7.0 🎉 The release is available on: Your semantic-release bot 📦🚀 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Alaska Airlines Pull Request
Release candidate pull request. See issue #287 for details.
Checklist:
By submitting this Pull Request, I confirm that my contribution is made under the terms of the Apache 2.0 license.
Pull Requests will be evaluated by their quality of update and whether it is consistent with the goals and values of this project. Any submission is to be considered a conversation between the submitter and the maintainers of this project and may require changes to your submission.
Thank you for your submission!
-- Auro Design System Team