@doneisbetter/gds-compliance 2.6.3 → 2.6.5

package/index.js

@@ -10,6 +10,43 @@ const DEFAULT_STALE_DOCUMENTATION_REFERENCES = [
   '/Users/Shared/Projects/GENERAL_DESIGN_SYSTEM',
   'GENERAL_DESIGN_SYSTEM',
 ];
+const STRICT_COMPLIANCE_FIELDS = [
+  'approvedShellPrimitives',
+  'approvedDetailPrimitives',
+  'approvedListingPrimitives',
+  'approvedActionPrimitives',
+  'approvedTemporaryExceptions',
+  'approvedThemeLanes',
+  'themeOwnershipPaths',
+];
+const DEFAULT_APPROVED_THEME_LANES = [
+  'gdsTheme',
+  'gdsDarkPublicTheme',
+  'gdsFlatSurfaceTheme',
+  'gdsEditorialPublicTheme',
+  'createPublicBrandTheme',
+];
+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',
+];
+const PRODUCT_AUTHORED_REQUIRED_FIELDS = [
+  'a11yRequirements',
+  'testingRequirements',
+  'observabilityRequirements',
+];
 
 export function validateManifest(manifest) {
   const findings = [];
@@ -63,6 +100,99 @@ 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.`,
+      });
+    }
+
+    if (exception.category === 'product-authored-experience') {
+      const missingProductAuthoredFields = PRODUCT_AUTHORED_REQUIRED_FIELDS.filter((field) => {
+        const value = exception[field];
+        return !Array.isArray(value) || value.length === 0;
+      });
+
+      if (missingProductAuthoredFields.length > 0) {
+        findings.push({
+          rule: 'exception-product-authored-metadata',
+          severity: 'error',
+          file: exception.surface,
+          message: `Creator-authored experience exception "${exception.surface}" must define ${missingProductAuthoredFields.join(', ')} so accessibility, testing, and observability obligations remain explicit.`,
+        });
+      }
+    }
+  }
+
   return findings;
 }
 
@@ -88,6 +218,23 @@ function normalizePath(value) {
   return value.replace(/\\/g, '/');
 }
 
+function escapeRegex(value) {
+  return value.replace(/[|\\{}()[\]^$+?.]/g, '\\$&');
+}
+
+function globToRegExp(pattern) {
+  const normalized = normalizePath(pattern).replace(/^\.\//, '');
+  const escaped = escapeRegex(normalized)
+    .replace(/\\\*\\\*/g, '.*')
+    .replace(/\\\*/g, '[^/]*');
+  return new RegExp(`^${escaped}$`);
+}
+
+function matchesScope(relativePath, scopes) {
+  const normalizedRelativePath = normalizePath(relativePath).replace(/^\.\//, '');
+  return scopes.some((scope) => globToRegExp(scope).test(normalizedRelativePath));
+}
+
 function isForbiddenImport(source, allowedImports, forbiddenImports) {
   if (allowedImports.has(source)) {
     return false;
@@ -150,6 +297,175 @@ 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;
+}
+
+function validateApprovedExceptionsAgainstRepo({ manifestRoot, manifest, sourceFiles }) {
+  const findings = [];
+  const normalizedRoot = normalizePath(manifestRoot).replace(/\/$/, '');
+  const normalizedSourceFiles = sourceFiles.map((absolutePath) => ({
+    absolutePath,
+    relativePath: normalizePath(absolutePath).replace(`${normalizedRoot}/`, ''),
+  }));
+
+  for (const exception of manifest.approvedExceptions ?? []) {
+    const scopes = exception.scope ?? [];
+    if (!scopes.length) {
+      continue;
+    }
+
+    const matchingFiles = normalizedSourceFiles.filter((file) => matchesScope(file.relativePath, scopes));
+    if (!matchingFiles.length) {
+      findings.push({
+        rule: 'exception-scope-no-matches',
+        severity: 'error',
+        file: exception.surface,
+        message: `Approved exception "${exception.surface}" does not match any files in the repository. Remove the stale exception or narrow it to the real implementation path.`,
+      });
+    }
+  }
+
+  for (const adapter of manifest.localAdapters ?? []) {
+    if (adapter.status !== 'exception') {
+      continue;
+    }
+
+    const normalizedAdapterPath = normalizePath(adapter.path).replace(/^\.\//, '');
+    const coveredByApprovedException = (manifest.approvedExceptions ?? []).some((exception) =>
+      matchesScope(normalizedAdapterPath, exception.scope ?? []));
+
+    if (!coveredByApprovedException) {
+      findings.push({
+        rule: 'exception-adapter-outside-scope',
+        severity: 'error',
+        file: adapter.path,
+        message: `Local adapter exception "${adapter.contract}" is not covered by any approved exception scope. Tie exception adapters to a reviewed narrow exception instead of leaving local authority unbounded.`,
+      });
+    }
+  }
+
+  return findings;
+}
+
+function isCoveredByApprovedException(relativePath, approvedExceptions = []) {
+  return approvedExceptions.some((exception) => matchesScope(relativePath, exception.scope ?? []));
+}
+
+function findThemeOwnershipFiles({ manifestRoot, sourceFiles, themeOwnershipPaths = [] }) {
+  if (!themeOwnershipPaths.length) {
+    return [];
+  }
+
+  const normalizedRoot = normalizePath(manifestRoot).replace(/\/$/, '');
+  return sourceFiles.filter((absolutePath) => {
+    const relativePath = normalizePath(absolutePath).replace(`${normalizedRoot}/`, '');
+    return themeOwnershipPaths.some((scope) => matchesScope(relativePath, [scope]));
+  });
+}
+
+function scanThemeGovernance({ manifestRoot, manifest, sourceFiles }) {
+  const findings = [];
+  const approvedThemeLanes = new Set(manifest.compliance?.approvedThemeLanes ?? DEFAULT_APPROVED_THEME_LANES);
+  const themeOwnershipPaths = manifest.compliance?.themeOwnershipPaths ?? [];
+  const themeFiles = findThemeOwnershipFiles({ manifestRoot, sourceFiles, themeOwnershipPaths });
+  const normalizedRoot = normalizePath(manifestRoot).replace(/\/$/, '');
+
+  for (const filePath of themeFiles) {
+    const content = readFileSync(filePath, 'utf8');
+    const relativePath = normalizePath(filePath).replace(`${normalizedRoot}/`, '');
+
+    if (isCoveredByApprovedException(relativePath, manifest.approvedExceptions ?? [])) {
+      continue;
+    }
+
+    if (/import\s*\{[^}]*\bextendGdsTheme\b[^}]*\}\s*from\s*['"]@doneisbetter\/gds(?:-theme)?(?:\/(?:client|server))?['"]/.test(content)) {
+      findings.push({
+        rule: 'theme.noncanonical-extend-helper',
+        severity: 'error',
+        file: relativePath,
+        message: `Theme ownership file "${relativePath}" imports extendGdsTheme(...). Consumer repos must use approved theme lanes (${[...approvedThemeLanes].join(', ')}) instead of a custom branding-layer helper.`,
+      });
+    }
+
+    if (/\b(createTheme|mergeMantineTheme|mergeThemeOverrides)\s*\(/.test(content)) {
+      findings.push({
+        rule: 'theme.parallel-branding-layer',
+        severity: 'error',
+        file: relativePath,
+        message: `Theme ownership file "${relativePath}" creates a local Mantine theme layer outside the approved GDS theme lanes. Use a shipped preset or createPublicBrandTheme(...) instead of a parallel branding authority.`,
+      });
+    }
+  }
+
+  return findings;
+}
+
 export function runComplianceCheck({ manifestPath }) {
   const absoluteManifestPath = resolve(manifestPath);
   const manifestRoot = dirname(absoluteManifestPath);
@@ -166,6 +482,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 +539,10 @@ export function runComplianceCheck({ manifestPath }) {
     findings.push(...scanSourceFile(filePath, allowedImports, forbiddenImports));
   }
 
+  findings.push(...validateApprovedExceptions(manifest));
+  findings.push(...validateApprovedExceptionsAgainstRepo({ manifestRoot, manifest, sourceFiles }));
+  findings.push(...scanThemeGovernance({ manifestRoot, manifest, sourceFiles }));
+
   if (protectedSurfacePaths.length) {
     const normalizedProtectedSurfacePaths = protectedSurfacePaths.map((value) => normalizePath(resolve(manifestRoot, value)));
 
@@ -246,6 +567,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.3",
+  "version": "2.6.5",
   "type": "module",
   "main": "./index.js",
   "bin": {