@doneisbetter/gds-compliance 2.6.1

package/bin/gds-compliance.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+import { ensureManifestExists, formatReport, runComplianceCheck } from '../index.js';
+
+const [, , command, ...rest] = process.argv;
+
+function getArg(name, fallback) {
+  const flagIndex = rest.findIndex((arg) => arg === name);
+  if (flagIndex === -1) {
+    return fallback;
+  }
+  return rest[flagIndex + 1] ?? fallback;
+}
+
+const manifestPath = getArg('--manifest', './gds-adoption.json');
+const format = getArg('--format', 'text');
+
+try {
+  ensureManifestExists(manifestPath);
+} catch (error) {
+  console.error(String(error));
+  process.exit(1);
+}
+
+if (command !== 'check' && command !== 'validate-manifest') {
+  console.error('Usage: gds-compliance <check|validate-manifest> --manifest ./gds-adoption.json [--format text|json]');
+  process.exit(1);
+}
+
+const report = runComplianceCheck({ manifestPath });
+const output = formatReport(report, format);
+if (output) {
+  console.log(output);
+}
+
+const hasErrors = report.findings.some((finding) => finding.severity === 'error');
+process.exit(hasErrors ? 1 : 0);

package/index.js

@@ -0,0 +1,279 @@
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { extname, dirname, join, resolve } from 'node:path';
+
+const SOURCE_EXTENSIONS = new Set(['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs']);
+const IGNORED_DIRS = new Set(['node_modules', '.git', '.next', 'dist', 'coverage']);
+const RAW_COLOR_PATTERN = /#(?:[0-9a-fA-F]{3,8})\b|rgb[a]?\s*\(/;
+const IMPORT_SOURCE_PATTERN = /(?:import\s+[^'"]*?from\s*|import\s*)['"]([^'"]+)['"]/g;
+const DEFAULT_FORBIDDEN_IMPORTS = ['@/components/ui/', '@radix-ui/', 'tailwindcss', 'lucide-react'];
+const DEFAULT_STALE_DOCUMENTATION_REFERENCES = [
+  '/Users/Shared/Projects/GENERAL_DESIGN_SYSTEM',
+  'GENERAL_DESIGN_SYSTEM',
+];
+
+export function validateManifest(manifest) {
+  const findings = [];
+
+  const requiredFields = [
+    'schemaVersion',
+    'gdsVersion',
+    'productArchetype',
+    'requiredContracts',
+    'localAdapters',
+    'approvedExceptions',
+    'migrationStatus',
+    'owner',
+    'lastReviewedAt',
+  ];
+
+  for (const field of requiredFields) {
+    if (!(field in manifest)) {
+      findings.push({
+        rule: 'manifest.missingField',
+        severity: 'error',
+        message: `Missing required manifest field: ${field}`,
+      });
+    }
+  }
+
+  for (const exception of manifest.approvedExceptions ?? []) {
+    for (const field of ['surface', 'reason', 'owner', 'reviewDate']) {
+      if (!exception[field]) {
+        findings.push({
+          rule: 'manifest.invalidException',
+          severity: 'error',
+          message: `Approved exception is missing ${field}.`,
+        });
+      }
+    }
+  }
+
+  for (const [field, value] of Object.entries({
+    documentationPaths: manifest.compliance?.documentationPaths ?? [],
+    staleDocumentationReferences: manifest.compliance?.staleDocumentationReferences ?? [],
+    protectedSurfacePaths: manifest.compliance?.protectedSurfacePaths ?? [],
+    bannedImports: manifest.compliance?.bannedImports ?? [],
+  })) {
+    if (!Array.isArray(value)) {
+      findings.push({
+        rule: 'manifest.invalidComplianceConfig',
+        severity: 'error',
+        message: `compliance.${field} must be an array when provided.`,
+      });
+    }
+  }
+
+  return findings;
+}
+
+function walk(dir, files = []) {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isDirectory()) {
+      if (IGNORED_DIRS.has(entry.name)) {
+        continue;
+      }
+      walk(join(dir, entry.name), files);
+      continue;
+    }
+
+    if (SOURCE_EXTENSIONS.has(extname(entry.name))) {
+      files.push(join(dir, entry.name));
+    }
+  }
+
+  return files;
+}
+
+function normalizePath(value) {
+  return value.replace(/\\/g, '/');
+}
+
+function isForbiddenImport(source, allowedImports, forbiddenImports) {
+  if (allowedImports.has(source)) {
+    return false;
+  }
+
+  return forbiddenImports.some((entry) => {
+    if (entry.endsWith('/')) {
+      return source.startsWith(entry);
+    }
+    if (entry === 'tailwindcss') {
+      return source === 'tailwindcss' || source.startsWith('tailwindcss/');
+    }
+    return source === entry;
+  });
+}
+
+function scanSourceFile(filePath, allowedImports, forbiddenImports) {
+  const findings = [];
+  const content = readFileSync(filePath, 'utf8');
+
+  if (!/(?:^|\/)(?:theme|tokens)\//.test(filePath) && RAW_COLOR_PATTERN.test(content)) {
+    findings.push({
+      rule: 'forbidden-color',
+      severity: 'error',
+      file: filePath,
+      message: 'Raw color literal found outside approved theme/token files.',
+    });
+  }
+
+  for (const match of content.matchAll(IMPORT_SOURCE_PATTERN)) {
+    const source = match[1];
+    if (source && isForbiddenImport(source, allowedImports, forbiddenImports)) {
+      findings.push({
+        rule: 'forbidden-import',
+        severity: 'error',
+        file: filePath,
+        message: `Forbidden UI import detected (${source}); use canonical GDS surfaces instead.`,
+      });
+    }
+  }
+
+  return findings;
+}
+
+function scanDocumentationFile(filePath, staleReferences) {
+  const findings = [];
+  const content = readFileSync(filePath, 'utf8');
+
+  for (const staleReference of staleReferences) {
+    if (staleReference && content.includes(staleReference)) {
+      findings.push({
+        rule: 'stale-documentation-reference',
+        severity: 'error',
+        file: filePath,
+        message: `Stale GDS reference detected (${staleReference}). Update local docs to the active SSOT structure.`,
+      });
+    }
+  }
+
+  return findings;
+}
+
+export function runComplianceCheck({ manifestPath }) {
+  const absoluteManifestPath = resolve(manifestPath);
+  const manifestRoot = dirname(absoluteManifestPath);
+  const manifest = JSON.parse(readFileSync(absoluteManifestPath, 'utf8'));
+  const findings = validateManifest(manifest);
+  const allowedImports = new Set();
+  const documentationPaths = manifest.compliance?.documentationPaths ?? [];
+  const staleDocumentationReferences = [
+    ...DEFAULT_STALE_DOCUMENTATION_REFERENCES,
+    ...(manifest.compliance?.staleDocumentationReferences ?? []),
+  ];
+  const protectedSurfacePaths = manifest.compliance?.protectedSurfacePaths ?? [];
+  const forbiddenImports = [
+    ...DEFAULT_FORBIDDEN_IMPORTS,
+    ...(manifest.compliance?.bannedImports ?? []),
+  ];
+
+  for (const exception of manifest.approvedExceptions ?? []) {
+    if (exception.dependency) {
+      allowedImports.add(exception.dependency);
+    }
+    for (const value of exception.allowImports ?? []) {
+      allowedImports.add(value);
+    }
+  }
+
+  for (const adapter of manifest.localAdapters ?? []) {
+    if (adapter.status === 'active' || adapter.status === 'exception') {
+      const adapterPath = resolve(manifestRoot, adapter.path);
+      if (!existsSync(adapterPath)) {
+        findings.push({
+          rule: 'missing-adapter',
+          severity: 'error',
+          file: adapter.path,
+          message: `Declared adapter path does not exist: ${adapter.path}`,
+        });
+      }
+    }
+  }
+
+  for (const documentationPath of documentationPaths) {
+    const absoluteDocumentationPath = resolve(manifestRoot, documentationPath);
+    if (!existsSync(absoluteDocumentationPath)) {
+      findings.push({
+        rule: 'missing-documentation-path',
+        severity: 'error',
+        file: documentationPath,
+        message: `Declared documentation path does not exist: ${documentationPath}`,
+      });
+      continue;
+    }
+
+    findings.push(...scanDocumentationFile(absoluteDocumentationPath, staleDocumentationReferences));
+  }
+
+  for (const protectedSurfacePath of protectedSurfacePaths) {
+    const absoluteProtectedSurfacePath = resolve(manifestRoot, protectedSurfacePath);
+    if (!existsSync(absoluteProtectedSurfacePath)) {
+      findings.push({
+        rule: 'missing-protected-surface',
+        severity: 'error',
+        file: protectedSurfacePath,
+        message: `Declared protected surface path does not exist: ${protectedSurfacePath}`,
+      });
+    }
+  }
+
+  const sourceFiles = walk(manifestRoot);
+  for (const filePath of sourceFiles) {
+    findings.push(...scanSourceFile(filePath, allowedImports, forbiddenImports));
+  }
+
+  if (protectedSurfacePaths.length) {
+    const normalizedProtectedSurfacePaths = protectedSurfacePaths.map((value) => normalizePath(resolve(manifestRoot, value)));
+
+    for (const filePath of sourceFiles) {
+      const normalizedFilePath = normalizePath(filePath);
+      const isProtectedSurface = normalizedProtectedSurfacePaths.some((protectedSurfacePath) =>
+        normalizedFilePath === protectedSurfacePath || normalizedFilePath.startsWith(`${protectedSurfacePath}/`));
+
+      if (!isProtectedSurface) {
+        continue;
+      }
+
+      const content = readFileSync(filePath, 'utf8');
+      if (/className\s*=\s*["'`][^"'`]*(?:bg-|text-|border-|rounded-|shadow-|grid |flex |px-|py-|mx-|my-)/.test(content)) {
+        findings.push({
+          rule: 'protected-surface-utility-drift',
+          severity: 'warn',
+          file: filePath,
+          message: 'Protected surface contains utility-style className tokens. Prefer canonical GDS surfaces or Mantine-native styling for governed files.',
+        });
+      }
+    }
+  }
+
+  return {
+    manifest,
+    findings,
+  };
+}
+
+export function formatReport(report, format = 'text') {
+  if (format === 'json') {
+    return JSON.stringify(report, null, 2);
+  }
+
+  if (!report.findings.length) {
+    return `GDS compliance check passed for ${report.manifest.owner}.`;
+  }
+
+  return [
+    `GDS compliance check found ${report.findings.length} issue(s):`,
+    ...report.findings.map((finding) => {
+      const location = finding.file ? ` (${finding.file})` : '';
+      return `- [${finding.severity}] ${finding.rule}${location}: ${finding.message}`;
+    }),
+  ].join('\n');
+}
+
+export function ensureManifestExists(manifestPath) {
+  const absoluteManifestPath = resolve(manifestPath);
+  if (!existsSync(absoluteManifestPath) || !statSync(absoluteManifestPath).isFile()) {
+    throw new Error(`Manifest not found: ${manifestPath}`);
+  }
+  return absoluteManifestPath;
+}

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@doneisbetter/gds-compliance",
+  "version": "2.6.1",
+  "type": "module",
+  "main": "./index.js",
+  "bin": {
+    "gds-compliance": "bin/gds-compliance.js"
+  },
+  "exports": {
+    ".": "./index.js"
+  },
+  "files": [
+    "bin",
+    "index.js"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sovereignsquad/general-design-system.git",
+    "directory": "packages/gds-compliance"
+  }
+}