folder structure validator

Author: earlduque

.github/scripts/validate-structure.js

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+
+const { execSync } = require('child_process');
+
+const allowedCategories = new Set([
+  'Core ServiceNow APIs',
+  'Server-Side Components',
+  'Client-Side Components',
+  'Modern Development',
+  'Integration',
+  'Specialized Areas'
+]);
+
+function resolveDiffRange() {
+  if (process.argv[2]) {
+    return process.argv[2];
+  }
+
+  const inCI = process.env.GITHUB_ACTIONS === 'true';
+  if (!inCI) {
+    return 'origin/main...HEAD';
+  }
+
+  const base = process.env.GITHUB_BASE_REF ? `origin/${process.env.GITHUB_BASE_REF}` : 'origin/main';
+  const head = process.env.GITHUB_SHA || 'HEAD';
+  return `${base}...${head}`;
+}
+
+function getChangedFiles(diffRange) {
+  let output;
+  try {
+    output = execSync(`git diff --name-only --diff-filter=ACMR ${diffRange}`, {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe']
+    });
+  } catch (error) {
+    console.error('Failed to collect changed files. Ensure the base branch is fetched.');
+    console.error(error.stderr?.toString() || error.message);
+    process.exit(1);
+  }
+
+  return output
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean);
+}
+
+function validateFilePath(filePath) {
+  const normalized = filePath.replace(/\\/g, '/');
+  const segments = normalized.split('/');
+
+  if (!allowedCategories.has(segments[0])) {
+    return null;
+  }
+
+  // Files must live under: Category/Subcategory/SpecificUseCase/<file>
+  if (segments.length < 4) {
+    return `Move '${normalized}' under a valid folder hierarchy (Category/Subcategory/Use-Case/your-file). Files directly inside '${segments[0]}' or its subcategories are not allowed.`;
+  }
+
+  return null;
+}
+
+function main() {
+  const diffRange = resolveDiffRange();
+  const changedFiles = getChangedFiles(diffRange);
+
+  if (changedFiles.length === 0) {
+    console.log('No relevant file changes detected.');
+    return;
+  }
+
+  const problems = [];
+
+  for (const filePath of changedFiles) {
+    const issue = validateFilePath(filePath);
+    if (issue) {
+      problems.push(issue);
+    }
+  }
+
+  if (problems.length > 0) {
+    console.error('Folder structure violations found:');
+    for (const msg of problems) {
+      console.error(` - ${msg}`);
+    }
+    process.exit(1);
+  }
+
+  console.log('Folder structure looks good.');
+}
+
+main();

.github/workflows/validate-structure.yml

@@ -0,0 +1,27 @@
+name: Validate Folder Structure
+
+on:
+  pull_request:
+    branches:
+      - main
+
+concurrency:
+  group: folder-structure-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  structure:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Use Node.js 18
+        uses: actions/setup-node@v4
+        with:
+          node-version: 18
+
+      - name: Validate folder layout
+        run: node .github/scripts/validate-structure.js