Merge pull request joshjohanning#63 from joshjohanning/lint-scripts-readme

joshjohanning · web-flow · commit 4e54cc4d1fa9 · 2024-02-10T12:14:37.000-06:00
feat: lint ./scripts/README.md
diff --git a/.github/scripts/lint-readme.js b/.github/scripts/lint-readme.js
@@ -1,11 +1,17 @@
-// Call manually via: node ./.github/scripts/lint-gh-cli-readme.js
+// Call manually via: node ./.github/scripts/lint-readme.js
+// Defaults to the `./gh-cli` directory
+// Check `./scripts` directory by calling: node ./.github/scripts/lint-readme.js ./scripts '##' '# scripts'
+
 // note this is only looking in files committed / staged, not all files in the directory
 
 const fs = require('fs');
 const path = require('path');
 const { execSync } = require('child_process');
 
-const directoryPath = './gh-cli';
+const directoryPath = process.argv[2] || './gh-cli';
+const headingLevel = process.argv[3] || '###';
+const parentHeading = process.argv[4] || '## Scripts';
+
 const readmePath = path.join(directoryPath, 'README.md');
 
 // Read README.md content
@@ -18,29 +24,49 @@ const gitFiles = execSync('git ls-files', { cwd: directoryPath, encoding: 'utf-8
 const files = gitFiles.split('\n');
 
 // Filter out .sh files in the root directory (excluding those in subdirectories)
-const shFiles = files.filter(file => file.endsWith('.sh') && !file.includes('/'));
+const fileExtensions = ['.sh', '.ps1', '.js', '.mjs', '.py'];
+
+const filteredFiles = files.filter(file => {
+  return fileExtensions.some(extension => file.endsWith(extension)) && !file.includes('/');
+});
+
+const subdirectories = files.reduce((acc, file) => {
+  if (file.includes('/')) {
+    const subdirectory = file.split('/')[0];
+    if (subdirectory !== 'internal' && !acc.includes(subdirectory)) {
+      acc.push(subdirectory);
+    }
+  }
+  return acc;
+}, []);
+
+const allScripts = filteredFiles.concat(subdirectories);
 
 // Initialize a counter for the number of issues
 let issueCount = 0;
 
 // Check if each .sh file is mentioned in the README.md
-shFiles.forEach(file => {
-  if (!readme.includes(`### ${file}`)) {
+allScripts.forEach(file => {
+  if (!readme.includes(`${headingLevel} ${file}`)) {
     console.log(`The file ${file} is not mentioned in the README.md`);
     issueCount++;
   }
 });
 
-// Check that all .sh files follow the kebab-case naming convention
-shFiles.forEach(file => {
-  if (!/^([a-z0-9]+-)*[a-z0-9]+\.sh$/.test(file)) {
+// Check that all files follow the kebab-case naming convention
+allScripts.forEach(file => {
+  if (!/^([a-z0-9]+-)*[a-z0-9]+(\.[a-z0-9]+)*$/.test(file)) {
     console.log(`The file ${file} does not follow the kebab-case naming convention`);
     issueCount++;
   }
 });
 
 // Check that all .sh files have execution permissions
-shFiles.forEach(file => {
+allScripts.forEach(file => {
+  if (!file.endsWith('.sh')) {
+    return;
+  }
+
   const filePath = path.join(directoryPath, file);
   const stats = fs.statSync(filePath);
   const isExecutable = (stats.mode & fs.constants.X_OK) !== 0;
@@ -52,15 +78,16 @@ shFiles.forEach(file => {
 });
 
 // Extract the part of the README under the ## Scripts heading
-const scriptsSection = readme.split('## Scripts\n')[1];
+const scriptsSection = readme.split(`${parentHeading}\n`)[1];
 
 // Extract all ### headings from the scripts section
-const headings = scriptsSection.match(/### .*/g);
+const regex = new RegExp(`${headingLevel} .*`, 'g');
+const headings = scriptsSection.match(regex);
 
 // Check that all scripts mentioned in the README.md actually exist in the repository
 headings.forEach(heading => {
-  const script = heading.slice(4); // Remove the '### ' prefix
-  if (!shFiles.includes(script)) {
+  const script = heading.slice(headingLevel.length + 1); // Remove the '### ' prefix
+  if (!allScripts.includes(script)) {
     console.log(`The script ${script} is mentioned in the README.md but does not exist in the repository`);
     issueCount++;
   }
@@ -74,7 +101,7 @@ const shortWords = {
   'orgs': 'organizations'
 };
 
-shFiles.forEach(file => {
+allScripts.forEach(file => {
   Object.keys(shortWords).forEach(word => {
     const regex = new RegExp(`\\b${word}\\b`, 'g');
     if (regex.test(file)) {
diff --git a/.github/workflows/lint-readme.yml b/.github/workflows/lint-readme.yml
@@ -15,4 +15,15 @@ jobs:
         uses: actions/checkout@v4
 
       - name: Lint ./gh-cli/README.md
-        run: node ./.github/scripts/lint-gh-cli-readme.js
+        run: node ./.github/scripts/lint-readme.js
+
+  lint-scripts-readme:
+    name: Lint ./scripts/README.md
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Lint ./scripts/README.md
+        run: node ./.github/scripts/lint-readme.js ./scripts '##' '# scripts'
diff --git a/scripts/README.md b/scripts/README.md
@@ -32,7 +32,7 @@ Configuration values to change in the script:
 - `gitEmail` = If using a GitHub App, combine the App's user ID (&#9888;&#65039; this is different than App ID!) and name to form an email like: `149130343+josh-issueops-bot[bot]@users.noreply.github.com`. You can find the App's user ID number by calling: `gh api '/users/josh-issueops-bot[bot]' --jq .id`
 - `overwrite`: use `false` or `true` on whether it should overwrite the existing `dependabot.yml` file
 
-## ado_workitems_to_github_issues.ps1
+## ado-workitems-to-github-issues.ps1
 
 Migrate work items from Azure DevOps to GitHub issues - this just links out to a [separate repo](https://github.com/joshjohanning/ado_workitems_to_github_issues)
 
@@ -87,7 +87,7 @@ My use case is to use this list to determine who needs to be added to a organiza
 1. Run: `./new-users-to-add-to-project.sh <org> <repo> <file>`
 2. Don't delete the `<file>` as it functions as your user database
 
-## migrate-maven-packages-between-github-instances
+## migrate-maven-packages-between-github-instances.sh
 
 Migrate Maven packages in GitHub Packages from one GitHub organization to another.
 
@@ -103,7 +103,7 @@ Migrate npm packages in GitHub Packages from one GitHub organization to another.
 2. Define the target GitHub PAT env var: `export GH_TARGET_PAT=ghp_abc` (must have at least `write:packages`, `read:org`, `repo` scope)
 3. Run: `./migrate-maven-packages-between-github-instances.sh joshjohanning-org github.com joshjohanning-emu github.com`
 
-## migrate-nuget-packages-between-github-instances
+## migrate-nuget-packages-between-github-instances.sh
 
 Migrate NuGet packages in GitHub Packages from one GitHub organization to another. Runs script from upstream [source](https://github.com/joshjohanning/github-packages-migrate-nuget-packages-between-github-instances). 
 
diff --git a/scripts/ado-workitems-to-github-issues.ps1 b/scripts/ado-workitems-to-github-issues.ps1
@@ -1 +1 @@
-# see: https://github.com/joshjohanning/ado_workitems_to_github_issues/blob/main/ado_workitems_to_github_issues.ps1
+# see: https://github.com/joshjohanning/ado_workitems_to_github_issues/blob/main/ado_workitems_to_github_issues.ps1

Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-# see: https://github.com/joshjohanning/ado_workitems_to_github_issues/blob/main/ado_workitems_to_github_issues.ps1`
	`1`	`+# see: https://github.com/joshjohanning/ado_workitems_to_github_issues/blob/main/ado_workitems_to_github_issues.ps1`