Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion apps/docsite/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,8 @@ from the monorepo and writes typed TypeScript registries to `src/generated/`.

| Registry | Source | What it contains |
| ----------------------------- | -------------------------------------------------- | ------------------------------------------------------------- |
| `packageRegistry.ts` | `packages/*/package.json` | Name, version, description, README for each published package |
| `packageRegistry.ts` | `packages/*/package.json` | Name, version, description for each published package |
| `packageText.json` | Each package's `README.md` and `CHANGELOG.md` | README and changelog text of each package, for server modules |
| `componentRegistry.ts` | Core + CLI-configured integration `.doc.mjs` files | Props, usage docs, hooks, groups, per package |
| `componentPreviewRegistry.ts` | Components from those same packages | Runtime exports for the shared Properties preview |
| `blockRegistry.ts` | CLI + integration template blocks | Showcase and example blocks with metadata |
Expand Down
2 changes: 1 addition & 1 deletion apps/docsite/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
"generate": "node scripts/check-workspace-build.mjs && pnpm build:theme && node scripts/generate-data.mjs && node scripts/generate-scope.mjs && node scripts/generate-playground-types.mjs && node scripts/copy-vendor.mjs && node scripts/generate-landing-template-previews.mjs",
"dev": "pnpm generate && node ../../scripts/generate-i18n-runtime.mjs --watch -- pnpm --parallel --filter @astryxdesign/core --filter @astryxdesign/docsite dev:i18n",
"dev:i18n": "next dev --webpack",
"build": "pnpm generate && node scripts/build-mcp-runtime.mjs && next build --webpack && node scripts/check-template-gallery-bundle.mjs && node scripts/check-function-size.mjs",
"build": "pnpm generate && node scripts/build-mcp-runtime.mjs && next build --webpack && node scripts/check-template-gallery-bundle.mjs && node scripts/check-package-text-bundle.mjs && node scripts/check-function-size.mjs",
"start": "next start",
"typecheck": "tsc --noEmit",
"test": "vitest run",
Expand Down
135 changes: 135 additions & 0 deletions apps/docsite/scripts/check-package-text-bundle.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,135 @@
#!/usr/bin/env node
// Copyright (c) Meta Platforms, Inc. and affiliates.

/**
* @file Fails the build when a browser script holds a package's README or
* changelog text.
*
* The text is megabytes. Server routes render it, and no page's scripts need
* it. A client module that imports it adds it to each page that loads the
* module's chunk, and nothing reports that. After `next build`, a script
* under `.next/static/chunks` that holds most of the sampled lines of a text
* fails this check.
*/

import {existsSync, readdirSync, readFileSync} from 'node:fs';
import {dirname, join} from 'node:path';
import {fileURLToPath} from 'node:url';

const appRoot = join(dirname(fileURLToPath(import.meta.url)), '..');

const SAMPLES_PER_TEXT = 10;
// A shorter line is often a heading or a phrase that other pages also use.
const MIN_LINE_LENGTH = 40;
// A minifier keeps these characters of a string as they are. It can escape a
// quote, a backslash or a dollar sign, and a character outside ASCII.
const PRINTABLE_ASCII = /^[\x20-\x7e]+$/u;
const ESCAPABLE_CHARACTER = /["'`\\$]/u;

/**
* Lines of a text that a script holds unchanged when it holds the text,
* spread over the whole text.
* @param {string} text
* @returns {string[]}
*/
export function sampleLines(text) {
const lines = [
...new Set(
text
.split('\n')
.map(line => line.trim())
.filter(
line =>
line.length >= MIN_LINE_LENGTH &&
PRINTABLE_ASCII.test(line) &&
!ESCAPABLE_CHARACTER.test(line),
),
),
];
if (lines.length <= SAMPLES_PER_TEXT) return lines;
const step = lines.length / SAMPLES_PER_TEXT;
return Array.from(
{length: SAMPLES_PER_TEXT},
(_, index) => lines[Math.floor(index * step)],
);
}

/**
* The README and the changelog of each package, with the sampled lines.
* @param {{name: string, readme: string | null, changelog: string | null}[]} packageText
* @returns {{label: string, samples: string[]}[]}
*/
export function sampledTexts(packageText) {
return packageText.flatMap(({name, readme, changelog}) =>
[
{label: `${name} README`, text: readme},
{label: `${name} changelog`, text: changelog},
].flatMap(({label, text}) => {
const samples = text == null ? [] : sampleLines(text);
// One line cannot tell a text from a page that quotes it.
return samples.length > 1 ? [{label, samples}] : [];
}),
);
}

/**
* Each text that a script holds, as one line of a report.
* @param {{label: string, samples: string[]}[]} texts
* @param {{path: string, source: string}[]} scripts
* @returns {string[]}
*/
export function textsInScripts(texts, scripts) {
return scripts.flatMap(({path, source}) =>
texts.flatMap(({label, samples}) => {
const held = samples.filter(sample => source.includes(sample)).length;
// A page can share a sentence with a README. More than half of the
// sampled lines in one script is the text itself.
return held > samples.length / 2
? [`${label} (${held} of ${samples.length} sampled lines) in ${path}`]
: [];
}),
);
}

/**
* Checks the scripts of one build. Throws when a script holds a text, and
* when there is no script or no text to check.
* @param {{chunksRoot: string, textPath: string}} build
* @returns {string} the result, for the build log
*/
export function checkPackageTextBundle({chunksRoot, textPath}) {
if (!existsSync(chunksRoot)) {
throw new Error(`${chunksRoot} is missing: run next build first.`);
}
const scripts = readdirSync(chunksRoot, {recursive: true, encoding: 'utf8'})
.filter(file => file.endsWith('.js'))
.map(path => ({
path,
source: readFileSync(join(chunksRoot, path), 'utf8'),
}));
if (scripts.length === 0) {
throw new Error(`No browser script found under ${chunksRoot}`);
}
const texts = sampledTexts(JSON.parse(readFileSync(textPath, 'utf8')));
if (texts.length === 0) {
throw new Error(`No README or changelog text to check in ${textPath}`);
}
const found = textsInScripts(texts, scripts);
if (found.length > 0) {
throw new Error(
`A browser script holds package README or changelog text. Only server modules may import src/lib/packageText.ts:\n${found
.map(line => `- ${line}`)
.join('\n')}`,
);
}
return `Package text bundle check passed: ${scripts.length} browser scripts hold none of ${texts.length} README and changelog texts`;
}

if (fileURLToPath(import.meta.url) === process.argv[1]) {
console.log(
checkPackageTextBundle({
chunksRoot: join(appRoot, '.next', 'static', 'chunks'),
textPath: join(appRoot, 'src', 'generated', 'packageText.json'),
}),
);
}
20 changes: 17 additions & 3 deletions apps/docsite/scripts/generate-data.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@
*
* Generates:
* - packageRegistry.ts — metadata for every distributable package
* - packageText.json — each package's README and changelog text
* - componentRegistry.ts — component listings per package (from .doc.mjs)
* - blockRegistry.ts — showcases + example blocks from CLI templates
* - templateRegistry.ts — page templates including playground source
Expand Down Expand Up @@ -496,7 +497,12 @@ function generatePackageRegistry() {
.sort((a, b) => a.name.localeCompare(b.name));

const publicPackages = packages.map(
({packageExports: _packageExports, ...pkg}) => pkg,
({
packageExports: _packageExports,
readme: _readme,
changelog: _changelog,
...pkg
}) => pkg,
);
const content = `// Auto-generated by scripts/generate-data.mjs — do not edit

Expand All @@ -510,13 +516,21 @@ export interface PackageMeta {
peerDependencies: Record<string, string>;
hasReadme: boolean;
hasChangelog: boolean;
readme: string | null;
changelog: string | null;
}

export const packages: PackageMeta[] = ${JSON.stringify(publicPackages, null, 2)};
`;
writeRegistry('packageRegistry.ts', content);
// Client modules import the registry for a package's name or version. The
// text is megabytes, so it has a file that only server modules read.
const packageText = packages.map(({name, readme, changelog}) => ({
name,
readme,
changelog,
}));
const packageTextPath = path.join(OUT_DIR, 'packageText.json');
fs.writeFileSync(packageTextPath, `${JSON.stringify(packageText)}\n`);
console.log(` wrote ${path.relative(REPO_ROOT, packageTextPath)}`);
return packages;
}

Expand Down
32 changes: 0 additions & 32 deletions apps/docsite/src/__tests__/data-extraction.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -222,38 +222,6 @@ describe('packageRegistry', () => {
const names = packages.map(p => p.name);
expect(new Set(names).size).toBe(names.length);
});

it('packages with READMEs have readme content', () => {
for (const pkg of packages) {
if (pkg.hasReadme) {
expect(pkg.readme).toBeTruthy();
expect(typeof pkg.readme).toBe('string');
expect(pkg.readme!.length).toBeGreaterThan(50);
} else {
expect(pkg.readme).toBeNull();
}
}
});

it('packages with CHANGELOGs have changelog content', () => {
for (const pkg of packages) {
if (pkg.hasChangelog) {
expect(pkg.changelog).toBeTruthy();
expect(typeof pkg.changelog).toBe('string');
expect(pkg.changelog!.length).toBeGreaterThan(
pkg.name === '@astryxdesign/richtext' ? 0 : 50,
);
} else {
expect(pkg.changelog).toBeNull();
}
}
});

it('CLI package has a substantial README', () => {
const cli = packages.find(p => p.name === '@astryxdesign/cli');
expect(cli?.readme).toBeTruthy();
expect(cli!.readme!.length).toBeGreaterThan(1000);
});
});

// ── Component Registry ─────────────────────────────────────────────────
Expand Down
Loading