Conversation
Reviewer's GuideThis PR implements a series of feature expansions and refactors across documentation generation, commit analysis, CLI commands, CI/CIX migrations, and adds Azure DevOps integration by reorganizing static methods, adding new flags, and introducing new scripts for syncing and migrating configurations. Sequence diagram for new ADO item creation from GitHub issuesequenceDiagram
actor User
participant CLI
participant "ADOIntegration (createADOItem)"
participant "GitHub API"
participant "Azure DevOps API"
User->>CLI: Run `auro ado --gh-issue <issue>`
CLI->>ADOIntegration: createADOItem(ghIssue)
ADOIntegration->>GitHub API: fetchGitHubIssue(ghIssue)
GitHub API-->>ADOIntegration: GitHubIssue
ADOIntegration->>GitHub API: getExistingADOLink(GitHubIssue)
GitHub API-->>ADOIntegration: ADO link or null
alt ADO link exists
ADOIntegration->>CLI: Output ADO link
else No ADO link
ADOIntegration->>Azure DevOps API: createADOWorkItem(GitHubIssue)
Azure DevOps API-->>ADOIntegration: WorkItem
ADOIntegration->>GitHub API: updateGitHubProject(GitHubIssue, WorkItem link)
GitHub API-->>ADOIntegration: Success
ADOIntegration->>CLI: Output WorkItem link
end
Sequence diagram for new sync command with ref optionsequenceDiagram
actor User
participant CLI
participant "SyncDotGithubDir"
participant "GitHub API"
User->>CLI: Run `auro sync --ref <branch/tag/commit>`
CLI->>SyncDotGithubDir: syncDotGithubDir(cwd, ref)
SyncDotGithubDir->>GitHub API: getFolderItemsFromRelativeRepoPath(path, ref)
GitHub API-->>SyncDotGithubDir: Folder items
SyncDotGithubDir->>SyncDotGithubDir: processFolderItemsIntoFileConfigs(...)
SyncDotGithubDir->>SyncDotGithubDir: removeDirectory(.github)
SyncDotGithubDir->>SyncDotGithubDir: processContentForFile(config)
SyncDotGithubDir->>SyncDotGithubDir: generateDirectoryTree(.github)
SyncDotGithubDir->>CLI: Output tree structure
Sequence diagram for commit analyzer release notes generationsequenceDiagram
actor User
participant CLI
participant "CommitAnalyzer"
participant "Git API"
User->>CLI: Run `auro check-commits --release-notes`
CLI->>CommitAnalyzer: analyzeCommits(debug, setLabel, releaseNotes=true)
CommitAnalyzer->>Git API: getCommitMessages()
Git API-->>CommitAnalyzer: commitList
CommitAnalyzer->>CommitAnalyzer: generateReleaseNotes(commitList)
CommitAnalyzer->>CLI: Output release notes
Class diagram for Docs refactor in docs-generator.tsclassDiagram
class Docs {
+manifest: Package
+constructor(options)
+static getElements(): CustomElementDeclaration[]
+static isWcaModule(module: Module): boolean
+static renderAllElements(elements: CustomElementDeclaration[]): string
+static renderElement(element: CustomElementDeclaration, includeTitle = true): string
+static renderPropertiesAttributesTable(element: CustomElementDeclaration): string
+static renderParameters(parameters?: Parameter[]): string
+static renderTable(title, properties, data?): string
+static getType(obj): string
+static escapeMarkdown(str): string
+static get(obj, path): any
+static capitalize(str): string
}
Docs : manifest
Docs : getElements()
Docs : isWcaModule(module)
Docs : renderAllElements(elements)
Docs : renderElement(element, includeTitle)
Docs : renderPropertiesAttributesTable(element)
Docs : renderParameters(parameters)
Docs : renderTable(title, properties, data)
Docs : getType(obj)
Docs : escapeMarkdown(str)
Docs : get(obj, path)
Docs : capitalize(str)
class MergedTableData {
+name: string
+properties: string
+attributes: string
+modifiers: string
+type: string
+default: string
+description: string
}
Docs --> MergedTableData
Class diagram for Azure DevOps integration (ado/index.ts)classDiagram
class GitHubIssue {
+title: string
+body: string | null
+html_url: string
+number: number
+repository_owner_login: string
+repository_name: string
}
class WorkItem {
<<interface>>
+id: number
+_links_html_href: string
...
}
class AzureDevOps {
+createADOWorkItem(issue: GitHubIssue): WorkItem
}
class GitHub {
+fetchGitHubIssue(issueUrl: string): GitHubIssue
+getExistingADOLink(issue: GitHubIssue): string | null
+updateGitHubProject(issue: GitHubIssue, adoWorkItemUrl: string): void
}
class ADOIntegration {
+createADOItem(ghIssue: string): void
}
ADOIntegration --> GitHub
ADOIntegration --> AzureDevOps
AzureDevOps --> WorkItem
GitHub --> GitHubIssue
Class diagram for migration script (package-json-update-oidc/migration.js)classDiagram
class Migration {
+updatePackageJson()
+createNvmrcFile()
+run()
}
Migration --> Logger
Migration --> PackageJson
Class diagram for commit analyzer refactor (check-commits/commit-analyzer.ts)classDiagram
class CommitInfo {
+type: string
+hash: string
+subject: string
+body: string
}
class CommitAnalyzer {
+generateReleaseNotes(commitList: CommitInfo[]): void
+analyzeCommits(debug: boolean, setLabel: boolean, releaseNotes: boolean): Promise<void>
}
CommitAnalyzer --> CommitInfo
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
Closed
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
Hey there - I've reviewed your changes - here's some feedback:
- In renderAllElements you replaced the
---separators with just blank lines—please confirm this still renders clear section breaks or reintroduce a visible delimiter if needed. - The new syncDotGithubDir script is very large and handles fetching templates, file processing, and directory tree generation—consider breaking it into smaller modules or helper utilities to improve readability and testability.
- The ADO integration code uses hard-coded project number (19) and org details—consider making these values configurable via env vars or CLI options to avoid inflexible deployments.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- In renderAllElements you replaced the `---` separators with just blank lines—please confirm this still renders clear section breaks or reintroduce a visible delimiter if needed.
- The new syncDotGithubDir script is very large and handles fetching templates, file processing, and directory tree generation—consider breaking it into smaller modules or helper utilities to improve readability and testability.
- The ADO integration code uses hard-coded project number (19) and org details—consider making these values configurable via env vars or CLI options to avoid inflexible deployments.
## Individual Comments
### Comment 1
<location> `src/scripts/docs/docs-generator.ts:225` </location>
<code_context>
properties: prop.name,
attributes: ('attribute' in prop ? prop.attribute as string : '') || "",
- type: this.getType(prop) || "",
+ modifiers: ('readonly' in prop && prop.readonly ? 'readonly' : ''),
+ type: displayType,
default: ('default' in prop ? prop.default as string : '') || "",
</code_context>
<issue_to_address>
**suggestion:** Only 'readonly' modifier is considered; other possible modifiers are ignored.
Consider updating the logic to include other relevant modifiers, such as 'static' and 'private', for more complete documentation.
```suggestion
modifiers: [
('readonly' in prop && prop.readonly ? 'readonly' : ''),
('static' in prop && prop.static ? 'static' : ''),
('private' in prop && prop.private ? 'private' : '')
].filter(Boolean).join(' '),
```
</issue_to_address>
### Comment 2
<location> `src/scripts/docs/docs-generator.ts:396-399` </location>
<code_context>
// Fallback to string representation
- return String(type);
+ const result = String(type);
+
+ // Normalize all | separators to have spaces
+ return result.replace(/\s*\|\s*/g, ' | ');
}
</code_context>
<issue_to_address>
**suggestion:** Fallback type stringification may produce non-informative output for complex objects.
For objects with nested properties, consider implementing a fallback that serializes or extracts key details, rather than relying on String(type), which returns '[object Object]'.
</issue_to_address>
### Comment 3
<location> `src/scripts/check-commits/commit-analyzer.ts:53-63` </location>
<code_context>
+ let formattedLine = line;
+
+ // Add spaces before issue references like AlaskaAirlines/auro-cli#108
+ formattedLine = formattedLine.replace(
+ /([^\s])(AlaskaAirlines\/[a-zA-Z0-9-]+#\d+)/g,
+ '$1 $2'
+ );
+
+ // Add spaces between consecutive issue references
</code_context>
<issue_to_address>
**suggestion:** Regex for issue references may not cover all possible repository name formats.
Consider updating the regex to include underscores and other valid characters in repository names to ensure all references are matched.
```suggestion
// Add spaces before issue references like AlaskaAirlines/auro-cli#108
formattedLine = formattedLine.replace(
/([^\s])(AlaskaAirlines\/[a-zA-Z0-9._-]+#\d+)/g,
'$1 $2'
);
// Add spaces between consecutive issue references
formattedLine = formattedLine.replace(
/(AlaskaAirlines\/[a-zA-Z0-9._-]+#\d+)([^\s])/g,
'$1 $2'
);
```
</issue_to_address>
### Comment 4
<location> `src/scripts/syncDotGithubDir.ts:195` </location>
<code_context>
- }
-
- // Remove .github directory if it exists
- const githubPath = ".github";
-
- try {
</code_context>
<issue_to_address>
**suggestion:** Hardcoded .github path may not work if rootDir is not the current working directory.
Use path.join(rootDir, '.github') to construct the directory path, ensuring compatibility regardless of the current working directory.
Suggested implementation:
```typescript
import path from "path";
/**
* Remove the .github directory inside the specified rootDir.
*/
export async function syncDotGithubDir(rootDir: string, ref = 'main') {
```
```typescript
// Remove .github directory if it exists
const dirPath = path.join(rootDir, ".github");
try {
await fs.rm(dirPath, { recursive: true, force: true });
const successSpinner = ora().start();
successSpinner.succeed(`Successfully removed directory: ${dirPath}`);
} catch (error: any) {
const errorSpinner = ora().start();
errorSpinner.fail(`Error removing directory ${dirPath}: ${error.message}`);
throw error;
}
}
```
</issue_to_address>
### Comment 5
<location> `src/commands/sync.js:10` </location>
<code_context>
export default program
.command("sync")
+ .option("-r, --ref <branch/tag/commit>", "Git reference (branch/tag/commit) to use", "main")
.description(
"Script runner to synchronize local repository configuration files",
</code_context>
<issue_to_address>
**suggestion:** Default ref is set to 'main', which may not exist in all repositories.
If the repository's default branch is not 'main', this may lead to errors. Allow users to specify the branch or detect the default automatically.
Suggested implementation:
```javascript
.option("-r, --ref <branch/tag/commit>", "Git reference (branch/tag/commit) to use")
```
```javascript
.action(async (options) => {
Logger.info("Synchronizing repository configuration files...");
const cwd = process.cwd();
// Determine ref: use user input or detect default branch
let ref = options.ref;
if (!ref) {
const { execSync } = await import("child_process");
try {
// This returns something like: "refs/remotes/origin/main"
const symbolicRef = execSync(
"git symbolic-ref refs/remotes/origin/HEAD",
{ cwd, encoding: "utf8" }
).trim();
ref = symbolicRef.split("/").pop(); // Get the branch name
Logger.info(`No ref provided, using repository default branch: ${ref}`);
} catch (err) {
Logger.error("Could not detect default branch. Please specify --ref.");
process.exit(1);
}
}
// Use `ref` variable in the rest of your sync logic
```
</issue_to_address>
### Comment 6
<location> `src/utils/pathUtils.js:29` </location>
<code_context>
+
export const configPath = (file) => fromCliRoot("configs",file)
+
+export const migrationPath = (path) => fromCliRoot("migrations",path)
</code_context>
<issue_to_address>
**nitpick:** Parameter name 'path' may shadow the imported 'path' module.
Consider renaming the parameter to prevent confusion and possible bugs from shadowing the imported module.
</issue_to_address>Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
DukeFerdinand
approved these changes
Nov 7, 2025
Member
|
🎉 This PR is included in version 3.2.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
4 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
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
Summary by Sourcery
Extend documentation tooling, CLI commands, and CI migration support by enhancing the docs generator, enriching commit analysis with release notes, adding ADO integration for issue tracking, implementing a syncable
.githubtemplate directory, and providing migration scripts for OIDC configuration.New Features:
adocommand to create and link Azure DevOps work items from GitHub issuessynccommand option to pull and populate a template.githubdirectory from a remote repoEnhancements:
Build:
Chores:
@aurodesignsystem/auro-configdev dependency version