` (1 occurrence); use Astryx `Button`; do not hand-write controls from raw elements or custom control CSS (API Use-the-System)',
+ ],
+]);
function main() {
if (!existsSync(pathsFile) || !existsSync(mdFile)) {
@@ -44,6 +56,7 @@ function main() {
}
const rendered = renderAstryxSurfaceInventory(root);
+ assertNoAstryxBlockers(rendered, legacyBlockerBaseline);
const committedMd = readFileSync(mdFile, 'utf8');
const committedPaths = readFileSync(pathsFile, 'utf8');
const mdDrift = committedMd !== rendered.markdown;
diff --git a/scripts/generate-astryx-surface-inventory.mjs b/scripts/generate-astryx-surface-inventory.mjs
index 076e7753bd..9b4c130595 100644
--- a/scripts/generate-astryx-surface-inventory.mjs
+++ b/scripts/generate-astryx-surface-inventory.mjs
@@ -385,6 +385,8 @@ const RAW_BUTTON_RE = /<\s*button\b/;
const RAW_INPUT_RE = /<\s*input\b/;
const RAW_SELECT_RE = /<\s*select\b/;
const RAW_TEXTAREA_RE = /<\s*textarea\b/;
+const RAW_ACTION_ELEMENT_RE =
+ /<\s*(span|div)\b(?=[^>]*(?:onClick\s*=|role\s*=\s*['"]button['"]))[^>]*>/g;
const HEX_RE = /#[0-9a-fA-F]{3,8}\b/;
const OFF_HEIGHT_RE = /(?:min-)?height:\s*(\d+)px/g;
const ALLOWED_H = new Set([28, 32, 36]);
@@ -528,11 +530,22 @@ export function analyzeTsx(rel, text, ctx) {
const rawInput = RAW_INPUT_RE.test(code);
const rawSelect = RAW_SELECT_RE.test(code);
const rawTextarea = RAW_TEXTAREA_RE.test(code);
+ const rawActionElements = [...code.matchAll(RAW_ACTION_ELEMENT_RE)].map((match) => match[1]);
+ const rawActionElementCounts = new Map();
+ for (const element of rawActionElements) {
+ rawActionElementCounts.set(element, (rawActionElementCounts.get(element) || 0) + 1);
+ }
const gaps = [];
+ const admissionGaps = [];
if (rawButton) gaps.push('raw `
\` (${count} ${count === 1 ? 'occurrence' : 'occurrences'}); use Astryx \`Button\`; do not hand-write controls from raw elements or custom control CSS (API Use-the-System)`,
+ );
+ }
for (const name of shadows) {
gaps.push(`public export \`${name}\` shadows Astryx component (not a re-export)`);
}
@@ -552,6 +565,7 @@ export function analyzeTsx(rel, text, ctx) {
: 'aligned — no raw controls; no Astryx JSX usage';
return {
astryx: named.size > 0 ? [...named].sort().join(', ') : 'none',
+ admissionGaps,
gaps: note,
severity,
};
@@ -696,10 +710,25 @@ export function renderAstryxSurfaceInventory(repoRoot = root) {
files,
excluded,
totals: bySev,
+ blockers: rows.flatMap((row) => [
+ ...(row.severity === 'blocker' ? [{ path: row.path, gaps: row.gaps }] : []),
+ ...(row.admissionGaps || []).map((gaps) => ({ path: row.path, gaps })),
+ ]),
version,
};
}
+export function assertNoAstryxBlockers(rendered, legacyBaseline = new Map()) {
+ const blockers = rendered.blockers.filter(
+ (blocker) => legacyBaseline.get(blocker.path) !== blocker.gaps,
+ );
+ if (blockers.length === 0) return;
+ const details = blockers.map((blocker) => `- ${blocker.path}: ${blocker.gaps}`).join('\n');
+ throw new Error(
+ `Astryx surface blocker: hand-written controls are not allowed when Astryx owns the component. Use Astryx \`Button\` or the matching Astryx primitive; do not hand-write controls from raw elements or custom control CSS.\n${details}`,
+ );
+}
+
function main() {
const rendered = renderAstryxSurfaceInventory(root);
const mdPath = join(root, 'docs/astryx-surface-file-inventory.md');
diff --git a/scripts/generate-astryx-surface-inventory.test.mjs b/scripts/generate-astryx-surface-inventory.test.mjs
index d92f104be3..db55428022 100644
--- a/scripts/generate-astryx-surface-inventory.test.mjs
+++ b/scripts/generate-astryx-surface-inventory.test.mjs
@@ -25,6 +25,7 @@ import { after, describe, test } from 'node:test';
import {
analyzeTsx,
+ assertNoAstryxBlockers,
assertAstryxComponentSet,
loadAstryxComponents,
loadMakaUiBarrel,
@@ -225,4 +226,61 @@ describe('analyzeTsx severity (#3868)', () => {
const result = analyzeTsx('packages/ui/src/bad.tsx', src, base);
assert.equal(result.severity, 'blocker');
});
+
+ test('blocks hand-written span and div actions with an actionable Astryx diagnostic', () => {
+ for (const src of [
+ 'export function Bad() { return {}}>x; }',
+ 'export function Bad() { return x
; }',
+ ]) {
+ const result = analyzeTsx('packages/ui/src/bad.tsx', src, base);
+ assert.equal(result.severity, 'aligned');
+ assert.match(result.admissionGaps.join('; '), /use Astryx `Button`/);
+ assert.match(result.admissionGaps.join('; '), /do not hand-write controls/);
+ }
+ });
+
+ test('allows non-interactive spans and divs used for layout or text', () => {
+ const src = 'export function Fine() { return x
; }\n';
+ const result = analyzeTsx('packages/ui/src/fine.tsx', src, base);
+ assert.equal(result.severity, 'aligned');
+ assert.deepEqual(result.admissionGaps, []);
+ });
+
+ test('fails the CI gate even after a blocker inventory is regenerated', () => {
+ assert.throws(
+ () =>
+ assertNoAstryxBlockers({
+ blockers: [
+ {
+ path: 'packages/ui/src/bad.tsx',
+ gaps: 'hand-written interactive ``; use Astryx `Button`; do not hand-write controls',
+ },
+ ],
+ }),
+ /Astryx surface blocker.*packages\/ui\/src\/bad\.tsx.*use Astryx `Button`.*do not hand-write controls/is,
+ );
+ });
+
+ test('permits only exact legacy blocker fingerprints, never new debt at the same path', () => {
+ const path = 'packages/ui/src/legacy.tsx';
+ const gaps =
+ 'hand-written interactive `` (1 occurrence); use Astryx `Button`; do not hand-write controls';
+ const baseline = new Map([[path, gaps]]);
+ assert.doesNotThrow(() => assertNoAstryxBlockers({ blockers: [{ path, gaps }] }, baseline));
+ assert.throws(
+ () =>
+ assertNoAstryxBlockers(
+ {
+ blockers: [
+ {
+ path,
+ gaps: 'hand-written interactive `
` (2 occurrences); use Astryx `Button`; do not hand-write controls',
+ },
+ ],
+ },
+ baseline,
+ ),
+ /Astryx surface blocker/,
+ );
+ });
});