const fs = require("node:fs"); const path = require("node:path"); const { sortScripts } = require("./utils/sort-scripts"); /** * This enforcement is not here to prevent adoption of newer * package standards such as "exports". It is to ensure consistency in the * monorepo until the time comes for those changes. * ---- * * The script will enforce several things on a package json object: * * - main and module must be defined. * In the future this may change. Browser is more standard than module, and * exports may be used for ESM (.mjs) support. * * - If a react-native entry exists, browser and react native entries must be of the * same type (object replacement directives or string entry point). * If either is not defined, both must not be defined. * * - when react-native has file replacement directives, it must include both * CJS and ESM dist replacements. * * - exports must not be defined unless the package name is core. */ module.exports = function (pkgJsonFilePath, overwrite = false) { const errors = []; const pkgJson = require(pkgJsonFilePath); const pkgDirRoot = path.dirname(pkgJsonFilePath); const isSubmoduleCarrier = fs.existsSync(path.join(pkgDirRoot, "src", "submodules")) && "exports" in pkgJson; if (!isSubmoduleCarrier) { if ("exports" in pkgJson) { errors.push(`${pkgJson.name} must not have an 'exports' field.`); if (overwrite) { delete pkgJson.exports; } } } for (const requiredField of ["main", "module"]) { if (!(requiredField in pkgJson)) { errors.push(`${requiredField} field missing in ${pkgJson.name}`); if (overwrite) { switch (requiredField) { case "main": pkgJson[requiredField] = "./dist-cjs/index.js"; break; case "module": pkgJson[requiredField] = pkgJson.main.replace("dist-cjs", "dist-es"); break; } } } } if (typeof pkgJson.browser !== typeof pkgJson["react-native"]) { errors.push(`browser and react-native fields are different in ${pkgJson.name}`); } if (!pkgJson.files) { errors.push(`no files entry in ${pkgJson.name}`); } if (typeof pkgJson.browser === "object" && typeof pkgJson["react-native"] === "object") { // Skip canonicalization for packages with submodules — they manage their own fields. if (!isSubmoduleCarrier) { const browserCanonical = Object.entries(pkgJson.browser).reduce((acc, [k, v]) => { if (!k.includes("dist-cjs/") || typeof v === "boolean") { acc[k] = v; } return acc; }, {}); if (Object.keys(browserCanonical).length !== Object.keys(pkgJson.browser).length) { errors.push(`${pkgJson.name} browser field is incomplete.`); if (overwrite) { pkgJson.browser = browserCanonical; } } const reactNativeCanonical = [ ...new Set([ ...Object.entries(pkgJson["react-native"]).map(([k, v]) => [ k.replace("dist-cjs", "dist-es"), typeof v === "string" ? v.replace("dist-cjs", "dist-es") : v, ]), ...Object.entries(pkgJson["react-native"]).map(([k, v]) => [ k.replace("dist-es", "dist-cjs"), typeof v === "string" ? v.replace("dist-es", "dist-cjs") : v, ]), ]), ].reduce((acc, [k, v]) => { acc[k] = v; return acc; }, {}); if (Object.keys(reactNativeCanonical).length !== Object.keys(pkgJson["react-native"]).length) { errors.push(`${pkgJson.name} react-native field is incomplete.`); if (overwrite) { pkgJson["react-native"] = reactNativeCanonical; } } } else { // For submodule packages, validate that index.browser.ts/index.native.ts are declared. const submodulesDir = path.join(pkgDirRoot, "src", "submodules"); const browserField = pkgJson.browser || {}; const reactNativeField = pkgJson["react-native"] || {}; let didModify = false; for (const sub of fs.readdirSync(submodulesDir)) { const subPath = path.join(submodulesDir, sub); if (!fs.lstatSync(subPath).isDirectory()) { continue; } const esIndex = `./dist-es/submodules/${sub}/index.js`; const cjsIndex = `./dist-cjs/submodules/${sub}/index.js`; if (fs.existsSync(path.join(subPath, "index.browser.ts"))) { const esBrowserExpected = `./dist-es/submodules/${sub}/index.browser.js`; // browser field: re-path dist-es only. if (browserField[esIndex] !== esBrowserExpected) { errors.push(`${pkgJson.name} browser["${esIndex}"] should be "${esBrowserExpected}"`); if (overwrite) { browserField[esIndex] = esBrowserExpected; didModify = true; } } // Conditional exports must have "browser" condition pointing to dist-es. const exportEntry = pkgJson.exports?.[`./${sub}`]; if (exportEntry) { const esBrowser = esBrowserExpected; const cjsBrowser = esBrowser.replace("dist-es", "dist-cjs"); const expectedBrowser = { import: esBrowser, require: cjsBrowser }; if (JSON.stringify(exportEntry.browser) !== JSON.stringify(expectedBrowser)) { errors.push(`${pkgJson.name} exports["./${sub}"].browser should be ${JSON.stringify(expectedBrowser)}`); if (overwrite) { exportEntry.browser = expectedBrowser; } } // react-native condition: native variant if exists, otherwise browser fallback. const hasNative = fs.existsSync(path.join(subPath, "index.native.ts")); const esRn = hasNative ? `./dist-es/submodules/${sub}/index.native.js` : esBrowser; const cjsRn = esRn.replace("dist-es", "dist-cjs"); const expectedRn = { import: esRn, require: cjsRn }; if (JSON.stringify(exportEntry["react-native"]) !== JSON.stringify(expectedRn)) { errors.push( `${pkgJson.name} exports["./${sub}"]["react-native"] should be ${JSON.stringify(expectedRn)}` ); if (overwrite) { exportEntry["react-native"] = expectedRn; } } } } if (fs.existsSync(path.join(subPath, "index.native.ts"))) { const esNativeExpected = `./dist-es/submodules/${sub}/index.native.js`; const cjsNativeExpected = `./dist-cjs/submodules/${sub}/index.native.js`; // react-native field: re-path both dist-es and dist-cjs. if (reactNativeField[esIndex] !== esNativeExpected) { errors.push(`${pkgJson.name} react-native["${esIndex}"] should be "${esNativeExpected}"`); if (overwrite) { reactNativeField[esIndex] = esNativeExpected; didModify = true; } } if (reactNativeField[cjsIndex] !== cjsNativeExpected) { errors.push(`${pkgJson.name} react-native["${cjsIndex}"] should be "${cjsNativeExpected}"`); if (overwrite) { reactNativeField[cjsIndex] = cjsNativeExpected; didModify = true; } } } else if (fs.existsSync(path.join(subPath, "index.browser.ts"))) { // No native variant — react-native falls back to browser for both dist-es and dist-cjs. const esBrowserExpected = `./dist-es/submodules/${sub}/index.browser.js`; const cjsBrowserExpected = `./dist-cjs/submodules/${sub}/index.browser.js`; if (reactNativeField[esIndex] !== esBrowserExpected) { errors.push( `${pkgJson.name} react-native["${esIndex}"] should be "${esBrowserExpected}" (fallback to browser)` ); if (overwrite) { reactNativeField[esIndex] = esBrowserExpected; didModify = true; } } if (reactNativeField[cjsIndex] !== cjsBrowserExpected) { errors.push( `${pkgJson.name} react-native["${cjsIndex}"] should be "${cjsBrowserExpected}" (fallback to browser)` ); if (overwrite) { reactNativeField[cjsIndex] = cjsBrowserExpected; didModify = true; } } } } // Enforce condition key ordering in exports. const expectedOrder = ["types", "react-native", "browser", "module", "node", "import", "require", "default"]; for (const [exportPath, exportEntry] of Object.entries(pkgJson.exports)) { if (typeof exportEntry !== "object" || exportEntry === null) { continue; } const keys = Object.keys(exportEntry); const ordered = keys.slice().sort((a, b) => { const ai = expectedOrder.indexOf(a); const bi = expectedOrder.indexOf(b); return (ai === -1 ? 999 : ai) - (bi === -1 ? 999 : bi); }); if (JSON.stringify(keys) !== JSON.stringify(ordered)) { errors.push(`${pkgJson.name} exports["${exportPath}"] keys should be ordered: ${ordered.join(", ")}`); if (overwrite) { const reordered = {}; for (const k of ordered) { reordered[k] = exportEntry[k]; } pkgJson.exports[exportPath] = reordered; } } } if (didModify) { pkgJson.browser = browserField; pkgJson["react-native"] = reactNativeField; } } } // Validate variant replacement directives match source files. // Skip for packages with submodules — they use index-level variant files instead. const srcDir = path.join(pkgDirRoot, "src"); if (fs.existsSync(srcDir) && !isSubmoduleCarrier) { const browserField = pkgJson.browser || {}; const reactNativeField = pkgJson["react-native"] || {}; let didModify = false; // Check that every .browser.ts / .native.ts source file has directives. const walkSync = (dir) => { const results = []; for (const entry of fs.readdirSync(dir, { withFileTypes: true })) { const fullPath = path.join(dir, entry.name); if (entry.isDirectory()) { results.push(...walkSync(fullPath)); } else { results.push(fullPath); } } return results; }; for (const file of walkSync(srcDir)) { if (file.match(/\.(browser|native)\.ts$/) && !file.match(/\.spec\.|\.integ\./)) { const relativePath = file.replace(srcDir, "").replace(/\.ts$/, ""); const canonicalPath = relativePath.replace(/\.(browser|native)$/, ""); const variant = relativePath.match(/\.(browser|native)$/)[1]; const esCanonical = `./dist-es${canonicalPath}`; const esVariant = `./dist-es${relativePath}`; const cjsCanonical = `./dist-cjs${canonicalPath}`; const cjsVariant = `./dist-cjs${relativePath}`; // For react-native, .native takes precedence over .browser. const hasNativeVariant = variant === "browser" && fs.existsSync(file.replace(/\.browser\.ts$/, ".native.ts")); if (variant === "browser") { if (browserField[esCanonical] !== esVariant) { errors.push(`${pkgJson.name} browser["${esCanonical}"] should be "${esVariant}"`); if (overwrite) { browserField[esCanonical] = esVariant; didModify = true; } } if (!hasNativeVariant) { if (reactNativeField[esCanonical] !== esVariant) { errors.push(`${pkgJson.name} react-native["${esCanonical}"] should be "${esVariant}"`); if (overwrite) { reactNativeField[esCanonical] = esVariant; didModify = true; } } if (reactNativeField[cjsCanonical] !== cjsVariant) { errors.push(`${pkgJson.name} react-native["${cjsCanonical}"] should be "${cjsVariant}"`); if (overwrite) { reactNativeField[cjsCanonical] = cjsVariant; didModify = true; } } } } else if (variant === "native") { if (reactNativeField[esCanonical] !== esVariant) { errors.push(`${pkgJson.name} react-native["${esCanonical}"] should be "${esVariant}"`); if (overwrite) { reactNativeField[esCanonical] = esVariant; didModify = true; } } if (reactNativeField[cjsCanonical] !== cjsVariant) { errors.push(`${pkgJson.name} react-native["${cjsCanonical}"] should be "${cjsVariant}"`); if (overwrite) { reactNativeField[cjsCanonical] = cjsVariant; didModify = true; } } } } } if (didModify) { if (Object.keys(browserField).length) { pkgJson.browser = browserField; } if (Object.keys(reactNativeField).length) { pkgJson["react-native"] = reactNativeField; } } // Verify each existing directive points to an actual source file. for (const [field, directives] of [ ["browser", pkgJson.browser], ["react-native", pkgJson["react-native"]], ]) { if (typeof directives !== "object" || directives === null) { continue; } for (const [canonical, variant] of Object.entries(directives)) { if (typeof variant === "boolean") { continue; } if (!variant.startsWith("./")) { continue; } const variantSrcFile = path.join( pkgDirRoot, variant.replace(/^\.\/dist-(es|cjs)/, "src").replace(/(\.js)?$/, ".ts") ); if (!fs.existsSync(variantSrcFile)) { errors.push( `${pkgJson.name} ${field}["${canonical}"] -> "${variant}" has no corresponding source file (expected ${variantSrcFile})` ); } } } } // Enforce lint script and build integration for submodule carriers. if (isSubmoduleCarrier) { const relScripts = path.relative(pkgDirRoot, path.join(__dirname, "validation")); const expectedLint = `node ${relScripts}/submodules-linter.js`; if (!pkgJson.scripts?.lint || !pkgJson.scripts.lint.includes("submodules-linter")) { errors.push(`${pkgJson.name} must have a "lint" script that calls the submodules-linter`); if (overwrite) { pkgJson.scripts = pkgJson.scripts || {}; pkgJson.scripts.lint = expectedLint; } } if (!pkgJson.scripts?.prebuild || !pkgJson.scripts.prebuild.includes("yarn lint")) { errors.push(`${pkgJson.name} prebuild script must include "yarn lint"`); if (overwrite) { pkgJson.scripts = pkgJson.scripts || {}; pkgJson.scripts.prebuild = pkgJson.scripts.prebuild ? `${pkgJson.scripts.prebuild} && yarn lint` : "yarn lint"; } } } // Ban per-package "lint" and "format" scripts that invoke linters/formatters. // These tools run at the repo root level only (yarn lint / yarn format). const bannedLintPatterns = ["eslint", "oxlint", "tslint"]; const bannedFormatPatterns = ["prettier", "oxfmt"]; if (pkgJson.scripts?.lint && !isSubmoduleCarrier) { for (const pattern of bannedLintPatterns) { if (pkgJson.scripts.lint.includes(pattern)) { errors.push(`${pkgJson.name} scripts["lint"] must not call ${pattern}. Run "yarn lint" from the repo root.`); if (overwrite) { delete pkgJson.scripts.lint; } break; } } } if (pkgJson.scripts?.format) { for (const pattern of bannedFormatPatterns) { if (pkgJson.scripts.format.includes(pattern)) { errors.push( `${pkgJson.name} scripts["format"] must not call ${pattern}. Run "yarn format" from the repo root.` ); if (overwrite) { delete pkgJson.scripts.format; } break; } } } // Enforce clean script uses premove. const expectedClean = "premove dist-cjs dist-es dist-types"; if (pkgJson.scripts?.clean !== expectedClean) { errors.push(`${pkgJson.name} scripts["clean"] must be "${expectedClean}"`); if (overwrite) { pkgJson.scripts = pkgJson.scripts || {}; pkgJson.scripts.clean = expectedClean; } } // Enforce build:es cleans dist-es before compiling. if (pkgJson.scripts?.["build:es"] && pkgJson.scripts["build:es"] !== "exit 0") { if (!pkgJson.scripts["build:es"].startsWith("premove dist-es")) { errors.push(`${pkgJson.name} scripts["build:es"] must start with "premove dist-es"`); if (overwrite) { pkgJson.scripts["build:es"] = "premove dist-es && " + pkgJson.scripts["build:es"]; } } } // Enforce build:types cleans dist-types before compiling. if (pkgJson.scripts?.["build:types"] && pkgJson.scripts["build:types"] !== "exit 0") { if (!pkgJson.scripts["build:types"].startsWith("premove dist-types")) { errors.push(`${pkgJson.name} scripts["build:types"] must start with "premove dist-types"`); if (overwrite) { pkgJson.scripts["build:types"] = "premove dist-types && " + pkgJson.scripts["build:types"]; } } } // Ban publishConfig.directory. changesets (v3+) refuses to publish a package // that sets it when the package manager is Yarn, which fails the release. // Yarn resolves workspace: ranges on its own when publishing from the package // directory, so no staged publish directory is needed. if (pkgJson.publishConfig && "directory" in pkgJson.publishConfig) { errors.push(`${pkgJson.name} must not have publishConfig.directory. changesets cannot publish it with Yarn.`); if (overwrite) { delete pkgJson.publishConfig.directory; if (Object.keys(pkgJson.publishConfig).length === 0) { delete pkgJson.publishConfig; } } } // Ban the stage-release script that populated publishConfig.directory. // Release artifacts are built by "yarn build:release" at the repo root. if (pkgJson.scripts?.["stage-release"]) { errors.push(`${pkgJson.name} must not have a "stage-release" script. Use "yarn build:release" from the repo root.`); if (overwrite) { delete pkgJson.scripts["stage-release"]; } } // Enforce premove devDependency. if (pkgJson.devDependencies?.premove !== "4.0.0") { errors.push(`${pkgJson.name} devDependencies["premove"] must be "4.0.0"`); if (overwrite) { pkgJson.devDependencies = pkgJson.devDependencies || {}; pkgJson.devDependencies.premove = "4.0.0"; } } if (pkgJson.dependencies?.premove) { errors.push(`${pkgJson.name} premove must be in devDependencies, not dependencies`); if (overwrite) { delete pkgJson.dependencies.premove; } } // Enforce build scripts. const isNonStub = "build:es:cjs" in (pkgJson.scripts || {}); const expectedBuildTypes = "premove dist-types && yarn g:tsc -p tsconfig.types.json"; if (isNonStub) { const expectedBuildEsCjs = "node ../../scripts/compilation/es_cjs.js"; const expectedBuild = `concurrently 'yarn:build:types' 'yarn:build:es:cjs'`; if (pkgJson.scripts?.build !== expectedBuild) { errors.push(`${pkgJson.name} scripts["build"] must be "${expectedBuild}"`); if (overwrite) { pkgJson.scripts = pkgJson.scripts || {}; pkgJson.scripts.build = expectedBuild; } } if (pkgJson.scripts?.["build:es:cjs"] !== expectedBuildEsCjs) { errors.push(`${pkgJson.name} scripts["build:es:cjs"] must be "${expectedBuildEsCjs}"`); if (overwrite) { pkgJson.scripts = pkgJson.scripts || {}; pkgJson.scripts["build:es:cjs"] = expectedBuildEsCjs; } } if (pkgJson.scripts?.["build:types"] !== expectedBuildTypes) { errors.push(`${pkgJson.name} scripts["build:types"] must be "${expectedBuildTypes}"`); if (overwrite) { pkgJson.scripts = pkgJson.scripts || {}; pkgJson.scripts["build:types"] = expectedBuildTypes; } } } else { const expectedBuild = "yarn g:tsc -p tsconfig.cjs.json && yarn g:tsc -p tsconfig.es.json && yarn g:tsc -p tsconfig.types.json"; if (pkgJson.scripts?.build !== expectedBuild) { errors.push(`${pkgJson.name} scripts["build"] must be "${expectedBuild}"`); if (overwrite) { pkgJson.scripts = pkgJson.scripts || {}; pkgJson.scripts.build = expectedBuild; } } if (pkgJson.scripts?.["build:types"] !== expectedBuildTypes) { errors.push(`${pkgJson.name} scripts["build:types"] must be "${expectedBuildTypes}"`); if (overwrite) { pkgJson.scripts = pkgJson.scripts || {}; pkgJson.scripts["build:types"] = expectedBuildTypes; } } } // Ensure :watch variants exist for vitest-based test scripts. if (pkgJson.scripts) { const watchPairs = [ ["test", "test:watch"], ["test:integration", "test:integration:watch"], ["test:e2e", "test:e2e:watch"], ]; for (const [base, watch] of watchPairs) { const cmd = pkgJson.scripts[base]; if (cmd && cmd.includes("vitest") && cmd.includes("run")) { const isCompounded = cmd.includes("&&"); const expected = cmd.split("&&")[0].trim().replace("vitest run", "vitest watch"); if (!pkgJson.scripts[watch]) { if (isCompounded) { errors.push( `${pkgJson.name} scripts["${watch}"] is missing and base command is compounded — resolve manually` ); } else { errors.push(`${pkgJson.name} ${watch} script was missing. Added automatically. Commit changes.`); if (overwrite) { pkgJson.scripts[watch] = expected; } } } else if (pkgJson.scripts[watch].includes("vitest watch")) { const afterWatch = pkgJson.scripts[watch].split("vitest watch")[1]; if (afterWatch.includes("&&")) { errors.push( `${pkgJson.name} scripts["${watch}"] has unreachable commands after vitest watch — resolve manually` ); } } } } } // Alphabetize scripts when running locally (not in CodeBuild). // Exception: "foo:watch" always immediately follows "foo". if (!process.env.CODEBUILD_BUILD_ID && pkgJson.scripts) { const sorted = Object.keys(pkgJson.scripts).sort(sortScripts); if (JSON.stringify(Object.keys(pkgJson.scripts)) !== JSON.stringify(sorted)) { const reordered = {}; for (const k of sorted) { reordered[k] = pkgJson.scripts[k]; } pkgJson.scripts = reordered; if (overwrite) { fs.writeFileSync(pkgJsonFilePath, JSON.stringify(pkgJson, null, 2) + "\n"); } } } if (overwrite && errors.length) { fs.writeFileSync(pkgJsonFilePath, JSON.stringify(pkgJson, null, 2) + "\n"); } return errors; };