@doneisbetter/gds-compliance 2.6.1 → 2.6.4

package/index.js

@@ -10,6 +10,29 @@ const DEFAULT_STALE_DOCUMENTATION_REFERENCES = [
   '/Users/Shared/Projects/GENERAL_DESIGN_SYSTEM',
   'GENERAL_DESIGN_SYSTEM',
 ];
+const STRICT_COMPLIANCE_FIELDS = [
+  'approvedShellPrimitives',
+  'approvedDetailPrimitives',
+  'approvedListingPrimitives',
+  'approvedActionPrimitives',
+  'approvedTemporaryExceptions',
+];
+const EXCEPTION_CATEGORIES = new Set([
+  'runtime-constraint',
+  'product-authored-experience',
+  'package-coverage-gap',
+  'migration-bridge',
+]);
+const EXCEPTION_STATUSES = new Set(['temporary', 'approved', 'deprecated', 'removed']);
+const EXCEPTION_REQUIRED_FIELDS = [
+  'category',
+  'scope',
+  'allowedImplementation',
+  'mustStillUse',
+  'mustNotDo',
+  'exitCondition',
+  'status',
+];
 
 export function validateManifest(manifest) {
   const findings = [];
@@ -63,6 +86,83 @@ export function validateManifest(manifest) {
     }
   }
 
+  if (manifest.compliance?.strictMode != null && typeof manifest.compliance.strictMode !== 'boolean') {
+    findings.push({
+      rule: 'manifest.invalidComplianceConfig',
+      severity: 'error',
+      message: 'compliance.strictMode must be a boolean when provided.',
+    });
+  }
+
+  for (const field of STRICT_COMPLIANCE_FIELDS) {
+    const value = manifest.compliance?.[field];
+    if (value != null && !Array.isArray(value)) {
+      findings.push({
+        rule: 'manifest.invalidComplianceConfig',
+        severity: 'error',
+        message: `compliance.${field} must be an array when provided.`,
+      });
+    }
+  }
+
+  return findings;
+}
+
+function hasBroadScope(scope) {
+  return scope.some((entry) =>
+    ['*', '**', 'app/**', 'src/**', './**', '/**'].includes(entry) || /(^|\/)\*\*$/.test(entry));
+}
+
+function validateApprovedExceptions(manifest) {
+  const findings = [];
+
+  for (const exception of manifest.approvedExceptions ?? []) {
+    const missingFields = EXCEPTION_REQUIRED_FIELDS.filter((field) => {
+      const value = exception[field];
+      if (Array.isArray(value)) {
+        return value.length === 0;
+      }
+      return !value;
+    });
+
+    if (missingFields.length > 0) {
+      findings.push({
+        rule: 'exception-required-fields',
+        severity: 'error',
+        file: exception.surface,
+        message: `Approved exception "${exception.surface}" must define ${missingFields.join(', ')}. Upgrade legacy exception entries to the canonical exception-surface contract.`,
+      });
+      continue;
+    }
+
+    if (!EXCEPTION_CATEGORIES.has(exception.category)) {
+      findings.push({
+        rule: 'exception-invalid-category',
+        severity: 'error',
+        file: exception.surface,
+        message: `Approved exception "${exception.surface}" uses unsupported category "${exception.category}".`,
+      });
+    }
+
+    if (!EXCEPTION_STATUSES.has(exception.status)) {
+      findings.push({
+        rule: 'exception-invalid-status',
+        severity: 'error',
+        file: exception.surface,
+        message: `Approved exception "${exception.surface}" uses unsupported status "${exception.status}".`,
+      });
+    }
+
+    if (hasBroadScope(exception.scope ?? [])) {
+      findings.push({
+        rule: 'exception-broad-scope',
+        severity: 'error',
+        file: exception.surface,
+        message: `Approved exception "${exception.surface}" has an over-broad scope. Exception scopes must stay narrow and reviewable.`,
+      });
+    }
+  }
+
   return findings;
 }
 
@@ -150,6 +250,75 @@ function scanDocumentationFile(filePath, staleReferences) {
   return findings;
 }
 
+function inferStrictSurface(contract) {
+  const normalized = contract.toLowerCase();
+  if (normalized.includes('shell')) return 'shell';
+  if (normalized.includes('detail') || normalized.includes('profile')) return 'detail';
+  if (normalized.includes('card') || normalized.includes('listing')) return 'listing';
+  if (normalized.includes('action') || normalized.includes('button')) return 'action';
+  return null;
+}
+
+function runStrictCompliance({ manifest, manifestRoot, sourceFiles }) {
+  const findings = [];
+  const strict = manifest.compliance ?? {};
+  const approvedBySurface = {
+    shell: new Set(strict.approvedShellPrimitives ?? []),
+    detail: new Set(strict.approvedDetailPrimitives ?? []),
+    listing: new Set(strict.approvedListingPrimitives ?? []),
+    action: new Set(strict.approvedActionPrimitives ?? []),
+  };
+  const approvedTemporaryExceptions = new Set(strict.approvedTemporaryExceptions ?? []);
+
+  for (const adapter of manifest.localAdapters ?? []) {
+    if (!['active', 'exception'].includes(adapter.status)) {
+      continue;
+    }
+
+    const surface = inferStrictSurface(adapter.contract);
+    if (!surface) {
+      continue;
+    }
+
+    if (approvedBySurface[surface].has(adapter.contract) || approvedTemporaryExceptions.has(adapter.contract)) {
+      continue;
+    }
+
+    findings.push({
+      rule: `strict.${surface}.local-adapter`,
+      severity: 'error',
+      file: adapter.path,
+      message: `Strict mode forbids local ${surface} adapter "${adapter.contract}". Migrate to the approved GDS primitive or declare a reviewed temporary exception.`,
+    });
+  }
+
+  for (const filePath of sourceFiles) {
+    const content = readFileSync(filePath, 'utf8');
+
+    if (/AppShell\s+as\s+MantineAppShell|<MantineAppShell\b|from\s+['"]@mantine\/core['"][\s\S]{0,120}AppShell/.test(content)) {
+      findings.push({
+        rule: 'strict.shell.mantine-app-shell',
+        severity: 'error',
+        file: filePath,
+        message: 'Strict mode forbids local Mantine AppShell wrappers. Use DiscoveryShell or the approved GDS shell wrapper.',
+      });
+    }
+
+    if (/(interface|type)\s+\w*(ActionBar|ButtonGroup|ButtonStack|Cta)\w*\s*[\{=]|export function \w*(ActionBar|ButtonGroup|ButtonStack|Cta)\w*/.test(content)
+      && /from\s+['"]@mantine\/core['"][\s\S]{0,200}\bButton\b/.test(content)
+      && !/from\s+['"]@doneisbetter\/gds-core['"][\s\S]{0,200}\bActionBar\b/.test(content)) {
+      findings.push({
+        rule: 'strict.action.legacy-wrapper',
+        severity: 'error',
+        file: filePath,
+        message: 'Strict mode forbids local button/action wrapper implementations. Use the canonical GDS ActionBar and semantic actions.',
+      });
+    }
+  }
+
+  return findings;
+}
+
 export function runComplianceCheck({ manifestPath }) {
   const absoluteManifestPath = resolve(manifestPath);
   const manifestRoot = dirname(absoluteManifestPath);
@@ -166,6 +335,7 @@ export function runComplianceCheck({ manifestPath }) {
     ...DEFAULT_FORBIDDEN_IMPORTS,
     ...(manifest.compliance?.bannedImports ?? []),
   ];
+  const strictMode = manifest.compliance?.strictMode === true;
 
   for (const exception of manifest.approvedExceptions ?? []) {
     if (exception.dependency) {
@@ -222,6 +392,8 @@ export function runComplianceCheck({ manifestPath }) {
     findings.push(...scanSourceFile(filePath, allowedImports, forbiddenImports));
   }
 
+  findings.push(...validateApprovedExceptions(manifest));
+
   if (protectedSurfacePaths.length) {
     const normalizedProtectedSurfacePaths = protectedSurfacePaths.map((value) => normalizePath(resolve(manifestRoot, value)));
 
@@ -246,6 +418,10 @@ export function runComplianceCheck({ manifestPath }) {
     }
   }
 
+  if (strictMode) {
+    findings.push(...runStrictCompliance({ manifest, manifestRoot, sourceFiles }));
+  }
+
   return {
     manifest,
     findings,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doneisbetter/gds-compliance",
-  "version": "2.6.1",
+  "version": "2.6.4",
   "type": "module",
   "main": "./index.js",
   "bin": {