An open source design system that's fully customizable and agent ready
TypeScript
chore(native): check the package boundary across all of packages/native, with the build-time exceptions listed (#8034)
Cindy Zhang45b0afd49055
diff --git a/packages/native/README.md b/packages/native/README.mdindex 9db2ad5816..170a55bd11 100644--- a/packages/native/README.md+++ b/packages/native/README.md@@ -145,8 +145,23 @@ files are ignored on `main`.Boundaries, checked by `pnpm check:package-boundaries`:- `@astryxdesign/core` never imports this package.-- This package's source never imports core. It reads core's documentation- files as data at build time.+- No file in this package, in any folder, imports core, apart from the+ build-time reads AST-082 FR16 lists until core's portable entry ships: the+ theme generator in `scripts/` may import `@astryxdesign/core/theme` and+ `@astryxdesign/core/theme/tokens`; `scripts/swift-ios-strings.mjs` may+ read core's locale catalogs (`@astryxdesign/core/locales/*.json`); and+ `scripts/core-docs.mjs` reads core's component documentation and built-in+ icon names as data.+- The check reads source text in every folder except `node_modules`, `dist`,+ `.build`, and `.swiftpm`. It flags any other module specifier that names+ core (`import`, `require`, `require.resolve`, `import.meta.resolve`, or a+ relative path into `packages/core`). It also flags a path to core's package,+ written as adjacent string segments (`'@astryxdesign', 'core'`,+ `'node_modules', '@astryxdesign/core'`, `'packages', 'core'`) or inside one+ string (`node_modules/@astryxdesign/core`, `packages/core`). In+ `scripts/core-docs.mjs` it allows exactly one such path, the `CORE_ROOT`+ definition, and only the listed reads under `CORE_ROOT`. It does not follow+ paths computed in other ways.## Experiment matrixdiff --git a/scripts/check-package-boundaries.js b/scripts/check-package-boundaries.jsindex 3949a6db9c..75c7d3a7a5 100644--- a/scripts/check-package-boundaries.js+++ b/scripts/check-package-boundaries.js@@ -9,63 +9,144 @@* package so consumers do not get parallel implementations.** Also keeps core and the experimental native package apart (AST-082 FR14,- * FR16): core never imports @astryxdesign/native, and native's source never- * imports core. Native reads core's documentation as data at build time.+ * FR16): core never imports @astryxdesign/native, and no file anywhere in+ * packages/native/ imports core outside the portable entry. Until core ships+ * that entry, NATIVE_CORE_EXCEPTIONS names each build-time read of core that+ * is allowed (AST-082 FR16): two theme entries imported by build scripts,+ * core's locale catalogs imported by the Swift strings generator, and core's+ * component documentation and built-in icon names read as data by one loader.+ * Any other import of core fails, as does any other path to core's package+ * that CORE_PACKAGE_PATH recognizes. The check reads source text; it does not+ * follow paths computed in other ways.*/const fs = require('node:fs');const path = require('node:path');-const ROOT = path.resolve(__dirname, '..');-const CORE_SRC = path.join(ROOT, 'packages/core/src');-const NATIVE_SRC = path.join(ROOT, 'packages/native/src');-const IMPORT_SPECIFIER = /\b(?:from|import|require)\s*\(?\s*['"]([^'"]+)['"]/g;+// Static and dynamic imports, require, require.resolve, and+// import.meta.resolve.+const IMPORT_SPECIFIER =+ /\b(?:from|import|require|require\.resolve|import\.meta\.resolve)\s*\(?\s*['"]([^'"]+)['"]/g;+const CORE_SOURCE = /\.(ts|tsx)$/;+const NATIVE_SOURCE = /\.(ts|tsx|mts|cts|js|jsx|mjs|cjs)$/;+// Installed dependencies, build output, and Swift build state hold no native+// source of their own.+const NATIVE_SKIPPED_DIRECTORIES = new Set([+ 'node_modules',+ 'dist',+ '.build',+ '.swiftpm',+]);+// A path built to core's package, as adjacent string segments or inside one+// string: its installed copy ('@astryxdesign', 'core'; 'node_modules',+// '@astryxdesign/core'; or node_modules/@astryxdesign/core) or its workspace+// source ('packages', 'core'; or packages/core).+const CORE_PACKAGE_PATH =+ /['"](?:@astryxdesign|packages)['"]\s*,\s*['"]core['"]|['"]node_modules['"]\s*,\s*['"]@astryxdesign\/core\b|['"`][^'"`]*(?:node_modules\/@astryxdesign|\bpackages)\/core\b/g;-const violations = [];+/**+ * The interim exceptions to AST-082 FR16: build-time reads of core that+ * native makes before core's portable entry exists. Each one ends when the+ * portable entry ships. Adding one is a reviewed change to this list.+ */+const NATIVE_CORE_EXCEPTIONS = Object.freeze({+ // Imports of core by build scripts, each scoped to a folder or one file.+ imports: Object.freeze([+ // The Swift theme generator resolves a theme's tokens through core's theme+ // entries (native theme generator spec, G2).+ Object.freeze({+ name: 'theme entries',+ directory: 'packages/native/scripts',+ specifiers: Object.freeze([+ '@astryxdesign/core/theme',+ '@astryxdesign/core/theme/tokens',+ ]),+ }),+ // The Swift strings generator reads core's locale catalogs, through core's+ // public ./locales/*.json export.+ Object.freeze({+ name: "core's locale catalogs",+ file: 'packages/native/scripts/swift-ios-strings.mjs',+ specifiers: Object.freeze([+ /^@astryxdesign\/core\/locales\/[\w-]+\.json$/,+ ]),+ }),+ ]),+ // Core's files that native reads as data, each by name, through one loader+ // that roots every read at its CORE_ROOT.+ data: Object.freeze({+ reader: 'packages/native/scripts/core-docs.mjs',+ reads: Object.freeze([+ // A component's documentation, the source of the native contracts.+ Object.freeze({+ name: 'component documentation',+ path: /^'src', `\$\{\w+\}\.doc\.mjs`$/,+ }),+ // Core's built-in icon names, for the native icon coverage test (FR17).+ Object.freeze({+ name: 'built-in icon names',+ path: /^'src', 'Icon', 'globalIconRegistry\.tsx'$/,+ }),+ ]),+ }),+});+// A path the data reader builds from its CORE_ROOT; the group is everything+// after CORE_ROOT, with whitespace collapsed before matching.+const CORE_ROOT_READ =+ /\bpath\.(?:join|resolve)\(\s*CORE_ROOT\s*,\s*([^)]*?)\s*,?\s*\)/g;-function walk(dir, check = checkFile) {+function corePackagePaths(content) {+ return (content.match(CORE_PACKAGE_PATH) ?? []).length;+}++function walk(dir, extensions, skipped, visit) {for (const entry of fs.readdirSync(dir, {withFileTypes: true})) {const fullPath = path.join(dir, entry.name);if (entry.isDirectory()) {- walk(fullPath, check);- continue;- }-- if (!/\.(ts|tsx)$/.test(entry.name)) {+ if (!skipped.has(entry.name)) walk(fullPath, extensions, skipped, visit);continue;}-- check(fullPath);+ if (extensions.test(entry.name)) visit(fullPath);}}-function importsOf(filePath) {- const content = fs.readFileSync(filePath, 'utf8');+function importsOf(content) {return [...content.matchAll(IMPORT_SPECIFIER)].map(match => match[1]);}-function checkNativeBoundary(filePath, forbidden, message) {- const relPath = path.relative(ROOT, filePath);- for (const specifier of importsOf(filePath)) {- const resolved = specifier.startsWith('.')- ? path.relative(ROOT, path.resolve(path.dirname(filePath), specifier))- : specifier;- if (- forbidden.some(- prefix => resolved === prefix || resolved.startsWith(`${prefix}/`),- )- ) {- violations.push({- file: relPath,- message: `${message} (imports "${specifier}")`,- });- }- }+function matchesPackage(resolved, prefixes) {+ return prefixes.some(+ prefix => resolved === prefix || resolved.startsWith(`${prefix}/`),+ );}-function checkFile(filePath) {- const relPath = path.relative(ROOT, filePath);+function resolveSpecifier(root, filePath, specifier) {+ return specifier.startsWith('.')+ ? path+ .relative(root, path.resolve(path.dirname(filePath), specifier))+ .split(path.sep)+ .join('/')+ : specifier;+}++function isAllowedNativeImport(relPath, specifier) {+ return NATIVE_CORE_EXCEPTIONS.imports.some(+ exception =>+ (exception.file+ ? relPath === exception.file+ : relPath.startsWith(`${exception.directory}/`)) &&+ exception.specifiers.some(allowed =>+ typeof allowed === 'string'+ ? allowed === specifier+ : allowed.test(specifier),+ ),+ );+}++function checkCoreFile(root, filePath, violations) {+ const relPath = path.relative(root, filePath);const basename = path.basename(filePath);+ const content = fs.readFileSync(filePath, 'utf8');if (/^XDSCommon[A-Z]/.test(basename)) {violations.push({@@ -75,9 +156,7 @@ function checkFile(filePath) {});}- const content = fs.readFileSync(filePath, 'utf8');- const lines = content.split('\n');- lines.forEach((line, index) => {+ content.split('\n').forEach((line, index) => {if (/^\s*export\s+(?:declare\s+)?(?:class|const|function|interface|type)\s+XDSCommon[A-Z]/.test(line,@@ -90,36 +169,116 @@ function checkFile(filePath) {});}});++ for (const specifier of importsOf(content)) {+ const resolved = resolveSpecifier(root, filePath, specifier);+ if (matchesPackage(resolved, ['@astryxdesign/native', 'packages/native'])) {+ violations.push({+ file: relPath,+ message: `@astryxdesign/core must never import @astryxdesign/native. (imports "${specifier}")`,+ });+ }+ }}-walk(CORE_SRC);-walk(CORE_SRC, filePath =>- checkNativeBoundary(- filePath,- ['@astryxdesign/native', 'packages/native'],- '@astryxdesign/core must never import @astryxdesign/native.',- ),-);-if (fs.existsSync(NATIVE_SRC)) {- walk(NATIVE_SRC, filePath =>- checkNativeBoundary(- filePath,- ['@astryxdesign/core', 'packages/core'],- '@astryxdesign/native source must not import core; read core documentation at build time instead.',- ),- );+function checkNativeFile(root, filePath, violations) {+ const relPath = path.relative(root, filePath).split(path.sep).join('/');+ const content = fs.readFileSync(filePath, 'utf8');++ for (const specifier of importsOf(content)) {+ const resolved = resolveSpecifier(root, filePath, specifier);+ if (+ matchesPackage(resolved, ['@astryxdesign/core', 'packages/core']) &&+ !isAllowedNativeImport(relPath, specifier)+ ) {+ violations.push({+ file: relPath,+ message: `@astryxdesign/native must not import core outside the portable entry or a listed build-time exception. (imports "${specifier}")`,+ });+ }+ }++ // A declaration file runs nothing, so it reads nothing.+ if (/\.d\.[cm]?ts$/.test(relPath)) return;++ const {data} = NATIVE_CORE_EXCEPTIONS;+ if (relPath !== data.reader) {+ if (corePackagePaths(content) > 0 || /\bCORE_ROOT\b/.test(content)) {+ violations.push({+ file: relPath,+ message: `@astryxdesign/native reads core's package as data only through ${data.reader}.`,+ });+ }+ return;+ }++ // The reader roots core at one place, its CORE_ROOT definition, so a second+ // root cannot read around the listed reads.+ if (corePackagePaths(content) > 1) {+ violations.push({+ file: relPath,+ message:+ 'The data reader may build one path to core, its CORE_ROOT; every read must go through CORE_ROOT.',+ });+ }++ // Every use of CORE_ROOT beyond its definition must be one of the listed+ // reads.+ let reads = 0;+ for (const match of content.matchAll(CORE_ROOT_READ)) {+ const read = match[1].replace(/\s+/g, ' ');+ reads++;+ if (!data.reads.some(listed => listed.path.test(read))) {+ violations.push({+ file: relPath,+ message: `@astryxdesign/native reads an unlisted file of core (CORE_ROOT, ${read}); listed reads: ${data.reads.map(listed => listed.name).join(', ')}.`,+ });+ }+ }+ const uses = (content.match(/\bCORE_ROOT\b/g) ?? []).length;+ if (uses - 1 > reads) {+ violations.push({+ file: relPath,+ message:+ 'CORE_ROOT is used outside path.join(CORE_ROOT, ...); every read of core must be a listed read.',+ });+ }}-if (violations.length === 0) {- console.log('Package boundaries are clean.');- process.exit(0);+/** Every package-boundary violation under `root`, a repository checkout. */+function findViolations(root) {+ const violations = [];+ const coreSrc = path.join(root, 'packages/core/src');+ const nativeRoot = path.join(root, 'packages/native');++ if (fs.existsSync(coreSrc)) {+ walk(coreSrc, CORE_SOURCE, new Set(), filePath =>+ checkCoreFile(root, filePath, violations),+ );+ }+ if (fs.existsSync(nativeRoot)) {+ walk(nativeRoot, NATIVE_SOURCE, NATIVE_SKIPPED_DIRECTORIES, filePath =>+ checkNativeFile(root, filePath, violations),+ );+ }+ return violations;}-console.log(`Found ${violations.length} package boundary violation(s):\n`);-for (const violation of violations) {- console.log(` ${violation.file}: ${violation.message}`);+module.exports = {findViolations, NATIVE_CORE_EXCEPTIONS};++if (require.main === module) {+ const violations = findViolations(path.resolve(__dirname, '..'));+ if (violations.length === 0) {+ console.log('Package boundaries are clean.');+ process.exit(0);+ }++ console.log(`Found ${violations.length} package boundary violation(s):\n`);+ for (const violation of violations) {+ console.log(` ${violation.file}: ${violation.message}`);+ }+ console.log(+ '\nMove common shell integrations to their owning package or update the existing wrapper there.',+ );+ process.exit(1);}-console.log(- '\nMove common shell integrations to their owning package or update the existing wrapper there.',-);-process.exit(1);diff --git a/scripts/check-package-boundaries.test.mjs b/scripts/check-package-boundaries.test.mjsnew file mode 100644index 0000000000..7b6b133eee--- /dev/null+++ b/scripts/check-package-boundaries.test.mjs@@ -0,0 +1,246 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file Verifies the package boundary check.+ * @input Temporary repository trees with core and native source files.+ * @output Confirms core never imports native, and that no file anywhere under+ * packages/native/ imports or reads core outside the listed build-time+ * exceptions (AST-082 FR16).+ * @position Regression coverage for scripts/check-package-boundaries.js,+ * which `pnpm check:repo` runs.+ */++import {mkdirSync, mkdtempSync, rmSync, writeFileSync} from 'node:fs';+import {createRequire} from 'node:module';+import {tmpdir} from 'node:os';+import path from 'node:path';+import {afterEach, describe, expect, it} from 'vitest';++const require = createRequire(import.meta.url);+const {+ findViolations,+ NATIVE_CORE_EXCEPTIONS,+} = require('./check-package-boundaries.js');++const roots = [];++function tree(files) {+ const root = mkdtempSync(path.join(tmpdir(), 'astryx-boundaries-'));+ roots.push(root);+ for (const [file, content] of Object.entries(files)) {+ mkdirSync(path.dirname(path.join(root, file)), {recursive: true});+ writeFileSync(path.join(root, file), content);+ }+ return root;+}++const files = violations => violations.map(violation => violation.file);++afterEach(() => {+ for (const root of roots.splice(0)) {+ rmSync(root, {recursive: true, force: true});+ }+});++describe('package boundaries', () => {+ it('pass on this repository', () => {+ expect(findViolations(path.resolve(import.meta.dirname, '..'))).toEqual([]);+ });++ it('fail when core imports native', () => {+ const root = tree({+ 'packages/core/src/Button/Button.tsx':+ "import {Button} from '@astryxdesign/native';\n",+ });+ expect(files(findViolations(root))).toEqual([+ 'packages/core/src/Button/Button.tsx',+ ]);+ });++ it('fail on a core import in any native folder, including a new one', () => {+ const root = tree({+ 'packages/native/src/index.ts': "import '@astryxdesign/core';\n",+ 'packages/native/scripts/generate.mjs':+ "import {Button} from '@astryxdesign/core/Button';\n",+ 'packages/native/kotlin-android-1/scripts/theme.mjs':+ "const core = await import('@astryxdesign/core/theme');\n",+ 'packages/native/swift-ios-1/tools/relative.cjs':+ "require('../../../core/src/index.ts');\n",+ });+ expect(files(findViolations(root)).sort()).toEqual([+ 'packages/native/kotlin-android-1/scripts/theme.mjs',+ 'packages/native/scripts/generate.mjs',+ 'packages/native/src/index.ts',+ 'packages/native/swift-ios-1/tools/relative.cjs',+ ]);+ });++ it("allow the theme generator's two core theme entries only in scripts/", () => {+ const root = tree({+ 'packages/native/scripts/swift-ios-theme.mjs': [+ "const {defineTheme} = await import('@astryxdesign/core/theme');",+ "const {resolveThemeTokens} = await import('@astryxdesign/core/theme/tokens');",+ ].join('\n'),+ 'packages/native/src/theme/theme.ts':+ "import {defineTheme} from '@astryxdesign/core/theme';\n",+ });+ expect(files(findViolations(root))).toEqual([+ 'packages/native/src/theme/theme.ts',+ ]);+ expect(NATIVE_CORE_EXCEPTIONS.imports.map(listed => listed.name)).toEqual([+ 'theme entries',+ "core's locale catalogs",+ ]);+ });++ it("allow core's locale catalogs only in the Swift strings generator", () => {+ const read =+ "const dir = path.dirname(require.resolve('@astryxdesign/core/locales/en.json'));\n";+ const root = tree({+ 'packages/native/scripts/swift-ios-strings.mjs': read,+ 'packages/native/scripts/swift-ios-theme.mjs': read,+ 'packages/native/swift-ios-1/scripts/strings.mjs': read,+ });+ expect(files(findViolations(root)).sort()).toEqual([+ 'packages/native/scripts/swift-ios-theme.mjs',+ 'packages/native/swift-ios-1/scripts/strings.mjs',+ ]);+ const other = tree({+ 'packages/native/scripts/swift-ios-strings.mjs':+ "import messages from '@astryxdesign/core/locales/en.generated.js';\n",+ });+ expect(files(findViolations(other))).toEqual([+ 'packages/native/scripts/swift-ios-strings.mjs',+ ]);+ });++ it("allow reading core's package as data only through the listed loader", () => {+ const loader = [+ 'export const CORE_ROOT = path.join(',+ ' PACKAGE_ROOT,',+ " 'node_modules',",+ " '@astryxdesign',",+ " 'core',",+ ');',+ ].join('\n');+ const root = tree({+ 'packages/native/scripts/core-docs.mjs': loader,+ 'packages/native/scripts/core-docs.d.mts':+ 'export declare const CORE_ROOT: string;\n',+ 'packages/native/swift-ios-1/scripts/tokens.mjs': loader,+ 'packages/native/src/read.ts':+ "readFileSync('node_modules/@astryxdesign/core/src/Button/Button.doc.mjs');\n",+ 'packages/native/scripts/icons.mjs':+ "import {CORE_ROOT} from './core-docs.mjs';\n",+ });+ expect(files(findViolations(root)).sort()).toEqual([+ 'packages/native/scripts/icons.mjs',+ 'packages/native/src/read.ts',+ 'packages/native/swift-ios-1/scripts/tokens.mjs',+ ]);+ expect(NATIVE_CORE_EXCEPTIONS.data.reader).toBe(+ 'packages/native/scripts/core-docs.mjs',+ );+ });++ it('allow the loader only its listed reads: component docs and icon names', () => {+ const loader = reads =>+ [+ "export const CORE_ROOT = path.join(PACKAGE_ROOT, 'node_modules', '@astryxdesign', 'core');",+ ...reads,+ ].join('\n');+ const listed = [+ "const file = path.join(CORE_ROOT, 'src', `${relative}.doc.mjs`);",+ 'const source = fs.readFileSync(',+ " path.join(CORE_ROOT, 'src', 'Icon', 'globalIconRegistry.tsx'),",+ " 'utf8',",+ ');',+ ];+ expect(+ findViolations(+ tree({'packages/native/scripts/core-docs.mjs': loader(listed)}),+ ),+ ).toEqual([]);+ expect(NATIVE_CORE_EXCEPTIONS.data.reads.map(read => read.name)).toEqual([+ 'component documentation',+ 'built-in icon names',+ ]);++ for (const unlisted of [+ "path.join(CORE_ROOT, 'src', 'Button', 'Button.tsx');",+ "path.join(CORE_ROOT, 'dist', 'index.js');",+ 'fs.readdirSync(CORE_ROOT);',+ ]) {+ const violations = findViolations(+ tree({+ 'packages/native/scripts/core-docs.mjs': loader([+ ...listed,+ unlisted,+ ]),+ }),+ );+ expect(files(violations), unlisted).toEqual([+ 'packages/native/scripts/core-docs.mjs',+ ]);+ }+ });++ it('catch a second data reader that joins node_modules and @astryxdesign/core', () => {+ const root = tree({+ 'packages/native/scripts/icons.mjs':+ "const core = path.join(PACKAGE_ROOT, 'node_modules', '@astryxdesign/core');\n",+ });+ expect(files(findViolations(root))).toEqual([+ 'packages/native/scripts/icons.mjs',+ ]);+ });++ it('allow the data reader exactly one path to core, its CORE_ROOT', () => {+ const coreRoot =+ "export const CORE_ROOT = path.join(PACKAGE_ROOT, 'node_modules', '@astryxdesign', 'core');";+ for (const secondRoot of [+ "const other = path.join(PACKAGE_ROOT, 'node_modules', '@astryxdesign', 'core');",+ "fs.readFileSync('node_modules/@astryxdesign/core/dist/index.js');",+ "const other = path.join(PACKAGE_ROOT, 'node_modules', '@astryxdesign/core');",+ ]) {+ const root = tree({+ 'packages/native/scripts/core-docs.mjs': [coreRoot, secondRoot].join(+ '\n',+ ),+ });+ expect(files(findViolations(root)), secondRoot).toEqual([+ 'packages/native/scripts/core-docs.mjs',+ ]);+ }+ });++ it('catch resolve calls and paths to the core workspace', () => {+ const root = tree({+ 'packages/native/scripts/a.mjs':+ "const entry = require.resolve('@astryxdesign/core/Button');\n",+ 'packages/native/scripts/b.mjs':+ "const url = import.meta.resolve('@astryxdesign/core');\n",+ 'packages/native/scripts/c.mjs':+ "const src = path.join(REPO, 'packages', 'core', 'src');\n",+ 'packages/native/scripts/d.mjs':+ "const src = path.join(REPO, 'packages/core/src');\n",+ });+ expect(files(findViolations(root)).sort()).toEqual([+ 'packages/native/scripts/a.mjs',+ 'packages/native/scripts/b.mjs',+ 'packages/native/scripts/c.mjs',+ 'packages/native/scripts/d.mjs',+ ]);+ });++ it('skip installed dependencies, build output, and Swift build state', () => {+ const root = tree({+ 'packages/native/node_modules/@astryxdesign/core/index.js':+ "import './src/index.js';\nimport '@astryxdesign/core/theme';\n",+ 'packages/native/dist/index.js': "import '@astryxdesign/core';\n",+ 'packages/native/swift-ios-1/.build/plugin.mjs':+ "import '@astryxdesign/core';\n",+ });+ expect(findViolations(root)).toEqual([]);+ });+});