[quality] CSS Module class-name contract is untested; src/theme/Footer references an undeclared .iconLink and ships an orphan .orgText #319

import assert from 'node:assert/strict';
import { readFileSync, readdirSync, existsSync } from 'node:fs';
import { dirname, join, relative, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
import test from 'node:test';

// CSS Modules export only the class names declared in the stylesheet, so a
// reference to an undeclared class evaluates to `undefined` and renders as a
// missing `class` attribute. Nothing in the build fails, nothing in the test
// suite reads these names, and the element simply loses its styling.
const root = fileURLToPath(new URL('..', import.meta.url));
const srcDir = join(root, 'src');

function walk(dir) {
  const out = [];
  for (const entry of readdirSync(dir, { withFileTypes: true })) {
    const full = join(dir, entry.name);
    if (entry.isDirectory()) out.push(...walk(full));
    else if (/\.(js|jsx|ts|tsx)$/.test(entry.name)) out.push(full);
  }
  return out;
}

// Strips comments so commented-out code never counts as a reference and a
// commented-out rule never counts as a declaration.
function stripComments(source) {
  return source.replace(/\/\*[\s\S]*?\*\//g, '');
}

// Collects `import styles from './styles.module.css'` bindings, keyed by the
// local identifier, so a file that renames the default import is still read.
function cssImports(source, fromFile) {
  const imports = new Map();
  const pattern =
    /import\s+([A-Za-z_$][\w$]*)\s+from\s+['"]([^'"]+\.module\.css)['"]/g;
  for (const [, binding, specifier] of source.matchAll(pattern)) {
    imports.set(binding, resolve(dirname(fromFile), specifier));
  }
  return imports;
}

// Import specifiers contain the substring `styles.module`, which would
// otherwise be read as a reference to a class named `module`.
function withoutImports(source) {
  return source.replace(/^\s*import\s[\s\S]*?from\s+['"][^'"]+['"];?/gm, '');
}

function referencedClasses(source, binding) {
  const names = new Set();
  source = withoutImports(source);
  const dotted = new RegExp(`\\b${binding}\\.([A-Za-z_$][\\w$-]*)`, 'g');
  for (const [, name] of source.matchAll(dotted)) names.add(name);
  const bracketed = new RegExp(
    `\\b${binding}\\[\\s*['"\`]([\\w-]+)['"\`]\\s*\\]`,
    'g',
  );
  for (const [, name] of source.matchAll(bracketed)) names.add(name);
  return names;
}

// True when a file indexes the stylesheet with a computed key, in which case
// the referenced set cannot be known statically and the forward assertion
// would be unsound for that file.
function hasDynamicAccess(source, binding) {
  return new RegExp(`\\b${binding}\\[(?!\\s*['"\`][\\w-]+['"\`]\\s*\\])`).test(
    source,
  );
}

function declaredClasses(css) {
  return new Set(
    [...stripComments(css).matchAll(/\.(-?[A-Za-z_][\w-]*)/g)].map(
      (match) => match[1],
    ),
  );
}

// The first class in a selector is the rule's entry point. `.socialIcons svg`
// and `.button:hover` are reachable through `socialIcons` and `button`, so
// only the leading class decides whether a rule is reachable from JS at all.
function entryPointClasses(css) {
  const names = new Set();
  const body = stripComments(css);
  // Selector lists precede a `{` and follow `}`, `{` or the start of file.
  for (const [, , selectorList] of body.matchAll(/(^|[{}])([^{}]*)\{/g)) {
    for (const selector of selectorList.split(',')) {
      const trimmed = selector.trim();
      if (!trimmed || trimmed.startsWith('@')) continue;
      const leading = trimmed.match(/^\.(-?[A-Za-z_][\w-]*)/);
      if (leading) names.add(leading[1]);
    }
  }
  return names;
}

const modules = [];
for (const file of walk(srcDir)) {
  const source = stripComments(readFileSync(file, 'utf8'));
  for (const [binding, cssPath] of cssImports(source, file)) {
    modules.push({ file, binding, cssPath, source });
  }
}

test('at least one CSS Module import is discovered', () => {
  assert.ok(
    modules.length > 0,
    'found no `*.module.css` imports under src/; the extraction is vacuous',
  );
});

test('every imported *.module.css file exists on disk', () => {
  for (const { file, cssPath } of modules) {
    assert.ok(
      existsSync(cssPath),
      `${relative(root, file)} imports ${relative(root, cssPath)}, which does not exist`,
    );
  }
});

test('every referenced CSS Module class is declared in its stylesheet', () => {
  let checked = 0;
  for (const { file, binding, cssPath, source } of modules) {
    if (hasDynamicAccess(source, binding)) continue;
    const declared = declaredClasses(readFileSync(cssPath, 'utf8'));
    for (const name of referencedClasses(source, binding)) {
      checked += 1;
      assert.ok(
        declared.has(name),
        `${relative(root, file)} uses \`${binding}.${name}\`, but ` +
          `${relative(root, cssPath)} declares no \`.${name}\` rule; ` +
          'the class attribute renders as undefined',
      );
    }
  }
  assert.ok(checked > 0, 'no class references were checked');
});

test('every CSS Module rule is reachable from the code that imports it', () => {
  const byStylesheet = new Map();
  for (const { binding, cssPath, source } of modules) {
    if (!byStylesheet.has(cssPath)) byStylesheet.set(cssPath, new Set());
    const used = byStylesheet.get(cssPath);
    for (const name of referencedClasses(source, binding)) used.add(name);
  }
  for (const [cssPath, used] of byStylesheet) {
    const entryPoints = entryPointClasses(readFileSync(cssPath, 'utf8'));
    assert.ok(
      entryPoints.size > 0,
      `${relative(root, cssPath)} yielded no selectors; the extraction is vacuous`,
    );
    const orphans = [...entryPoints].filter((name) => !used.has(name)).sort();
    assert.deepEqual(
      orphans,
      [],
      `${relative(root, cssPath)} declares rules no importer references: ` +
        orphans.map((name) => `.${name}`).join(', '),
    );
  }
});