mirror of
https://github.com/tester-army/e2e.git
synced 2026-11-22 03:18:03 +08:00
Reverts #1693. e2e.com builds the docs from main again, so every push to main touching docs/ redeploys it.
249 lines
12 KiB
TypeScript
249 lines
12 KiB
TypeScript
/**
|
|
* The examples registry, `examples/examples.json`: every example on
|
|
* https://e2e.com/examples, official, partner, and community. The site
|
|
* (e2e-inc/e2e-site) downloads the file at build time and renders a page
|
|
* per entry from it and the README at its `repository` (or its `readme`);
|
|
* `site.yml` redeploys
|
|
* the site when the file changes on `main`.
|
|
*
|
|
* `examples.schema.json` pins the shape; `registryProblems` checks what a
|
|
* schema cannot: unique slugs and tags, tags an example names but the
|
|
* registry does not define, icons that are not in `examples/icons/`, official
|
|
* examples living under the e2e-inc organization on GitHub or the e2e_inc
|
|
* group on GitLab (and, in this
|
|
* repository, matching the folders under `examples/` and the ones
|
|
* `e2e init --example` can copy), partner and community examples living
|
|
* outside it, partner examples in their author's own repository, community
|
|
* examples pinned to a commit, and a `readme` only where the folder has no
|
|
* README.md, in the example's own repository.
|
|
*/
|
|
|
|
import { execFileSync } from 'node:child_process';
|
|
import { existsSync, readdirSync, readFileSync } from 'node:fs';
|
|
import { join } from 'node:path';
|
|
import { Ajv2020 } from 'ajv/dist/2020.js';
|
|
import { REPO_ROOT } from './public-packages.ts';
|
|
|
|
const EXAMPLES_DIR = join(REPO_ROOT, 'examples');
|
|
export const REGISTRY_PATH = join(EXAMPLES_DIR, 'examples.json');
|
|
const SCHEMA_PATH = join(EXAMPLES_DIR, 'examples.schema.json');
|
|
const ICONS_DIR = join(EXAMPLES_DIR, 'icons');
|
|
/**
|
|
* The `e2e init --example` presets, read as text: the module uses syntax
|
|
* Node's type stripping cannot run (parameter properties).
|
|
*/
|
|
const INIT_EXAMPLES_PATH = join(REPO_ROOT, 'packages/e2e/src/cli/init/examples.ts');
|
|
|
|
/** An official example in this repository: its folder under `examples/` on `main`. */
|
|
const FOLDER_URL = /^https:\/\/github\.com\/(?:e2e-inc|tester-army)\/e2e\/tree\/main\/examples\/([a-z0-9-]+)$/;
|
|
/** Any URL into this repository. */
|
|
const THIS_REPO_URL = /^https:\/\/github\.com\/(?:e2e-inc|tester-army)\/e2e(?:\/|$)/i;
|
|
/**
|
|
* Any URL into the e2e-inc organization on GitHub or the e2e_inc group on
|
|
* GitLab: official examples live there, and only they do.
|
|
*/
|
|
const ORG_URL = /^https:\/\/(?:github\.com\/(?:e2e-inc|tester-army)|gitlab\.com\/e2e_inc)\//i;
|
|
const ORG_NAMES = 'https://github.com/e2e-inc/ or https://gitlab.com/e2e_inc/';
|
|
/** The owner of a github.com URL, lowercased. A partner's repository must be on GitHub, under its `author.github`. */
|
|
function ownerOf(repository: string): string | undefined {
|
|
return repository.match(/^https:\/\/github\.com\/([^/]+)\//)?.[1]?.toLowerCase();
|
|
}
|
|
|
|
/**
|
|
* A github.com or gitlab.com URL split into its project and what follows it.
|
|
* A GitHub project is `<owner>/<repo>`; a GitLab one runs up to the `-`
|
|
* segment (`/-/tree/`, `/-/blob/`), since GitLab groups nest.
|
|
*/
|
|
function splitUrl(url: string): { host: 'github.com' | 'gitlab.com'; project: string; rest: string[] } | undefined {
|
|
const match = url.match(/^https:\/\/(github\.com|gitlab\.com)\/(.+)$/);
|
|
if (!match) return undefined;
|
|
const host = match[1] as 'github.com' | 'gitlab.com';
|
|
const segments = match[2]!.split('/').filter(Boolean);
|
|
const end = host === 'github.com' ? 2 : segments.includes('-') ? segments.indexOf('-') : segments.length;
|
|
const rest = segments.slice(host === 'github.com' ? end : end + 1);
|
|
return { host, project: segments.slice(0, end).join('/'), rest };
|
|
}
|
|
/** `<host>/<project>` of a github.com or gitlab.com URL, lowercased. */
|
|
function repoOf(url: string): string | undefined {
|
|
const parts = splitUrl(url);
|
|
return parts && `${parts.host}/${parts.project}`.toLowerCase();
|
|
}
|
|
/** The ref of a `/tree/<ref>` or `/blob/<ref>` URL (`/-/tree/<ref>` on GitLab). */
|
|
function refOf(url: string): string | undefined {
|
|
const [kind, ref] = splitUrl(url)?.rest ?? [];
|
|
return kind === 'tree' || kind === 'blob' ? ref : undefined;
|
|
}
|
|
/** A folder URL whose ref is a full commit SHA. */
|
|
function isPinned(url: string): boolean {
|
|
return splitUrl(url)?.rest[0] === 'tree' && /^[0-9a-f]{40}$/.test(refOf(url) ?? '');
|
|
}
|
|
|
|
/** Folders under `examples/` that are not examples: the site's logos. */
|
|
const UNLISTED_FOLDERS = new Set(['icons']);
|
|
|
|
export type TagKind = 'framework' | 'useCase' | 'platform';
|
|
const TAG_KINDS: readonly TagKind[] = ['framework', 'useCase', 'platform'];
|
|
|
|
interface Tag {
|
|
id: string;
|
|
label: string;
|
|
}
|
|
|
|
interface RegistryExample {
|
|
slug: string;
|
|
icon?: string;
|
|
source: 'official' | 'partner' | 'community';
|
|
repository: string;
|
|
readme?: string | false;
|
|
author: { github: string; website?: string };
|
|
tags: Partial<Record<TagKind, string[]>>;
|
|
}
|
|
|
|
export interface Registry {
|
|
tags: Record<TagKind, Tag[]>;
|
|
examples: RegistryExample[];
|
|
}
|
|
|
|
export interface RegistryEnvironment {
|
|
/** The folders under `examples/` that git tracks. */
|
|
folders: string[];
|
|
/** The file names in `examples/icons/`. */
|
|
icons: string[];
|
|
/** The folders `e2e init --example` can copy. */
|
|
initExamples: string[];
|
|
}
|
|
|
|
export function readEnvironment(): RegistryEnvironment {
|
|
return {
|
|
// Tracked folders only: a renamed example leaves an untracked folder (its
|
|
// ignored node_modules) behind on disk, which must not count as an example.
|
|
folders: [
|
|
...new Set(
|
|
execFileSync('git', ['ls-files', '-z', '--', 'examples/'], { cwd: REPO_ROOT, encoding: 'utf8' })
|
|
.split('\0')
|
|
.map((file) => file.split('/'))
|
|
.filter((parts) => parts.length > 2)
|
|
.map((parts) => parts[1]!),
|
|
),
|
|
],
|
|
icons: existsSync(ICONS_DIR) ? readdirSync(ICONS_DIR) : [],
|
|
initExamples: [...readFileSync(INIT_EXAMPLES_PATH, 'utf8').matchAll(/\{ id: '([a-z0-9-]+)'/g)].map((match) => match[1]!),
|
|
};
|
|
}
|
|
|
|
function duplicates(values: string[]): string[] {
|
|
return [...new Set(values.filter((value, index) => values.indexOf(value) !== index))];
|
|
}
|
|
|
|
/** The schema violations, as `<path>: <message>` lines. */
|
|
export function schemaProblems(json: unknown): string[] {
|
|
const ajv = new Ajv2020({ allErrors: true });
|
|
const validate = ajv.compile(JSON.parse(readFileSync(SCHEMA_PATH, 'utf8')) as Record<string, unknown>);
|
|
if (validate(json)) return [];
|
|
return (validate.errors ?? []).map((error) => {
|
|
const extra = error.keyword === 'additionalProperties' ? ` (${String(error.params.additionalProperty)})` : '';
|
|
return `${error.instancePath || '/'}: ${error.message ?? 'is invalid'}${extra}`;
|
|
});
|
|
}
|
|
|
|
/** Everything wrong with a registry that already matches the schema; empty when it is fine. */
|
|
export function registryProblems(registry: Registry, env: RegistryEnvironment): string[] {
|
|
const problems: string[] = [];
|
|
|
|
for (const kind of TAG_KINDS) {
|
|
for (const id of duplicates(registry.tags[kind].map((tag) => tag.id))) {
|
|
problems.push(`tags.${kind}: "${id}" is defined twice`);
|
|
}
|
|
}
|
|
|
|
for (const slug of duplicates(registry.examples.map((example) => example.slug))) {
|
|
problems.push(`examples: slug "${slug}" is used twice`);
|
|
}
|
|
|
|
for (const example of registry.examples) {
|
|
const name = `examples "${example.slug}"`;
|
|
if (example.icon && !env.icons.includes(example.icon)) {
|
|
problems.push(`${name}: icon ${example.icon} is not in examples/icons/`);
|
|
}
|
|
for (const kind of TAG_KINDS) {
|
|
const known = new Set(registry.tags[kind].map((tag) => tag.id));
|
|
for (const id of example.tags[kind] ?? []) {
|
|
if (!known.has(id)) problems.push(`${name}: tag "${id}" is not defined in tags.${kind}`);
|
|
}
|
|
}
|
|
|
|
const folder = example.repository.match(FOLDER_URL)?.[1];
|
|
if (example.source === 'official') {
|
|
if (!ORG_URL.test(example.repository)) {
|
|
problems.push(`${name}: an official example lives under ${ORG_NAMES}`);
|
|
} else if (THIS_REPO_URL.test(example.repository)) {
|
|
// In this repository, an official example is one of the folders under examples/.
|
|
if (!folder) {
|
|
problems.push(`${name}: an official example in e2e-inc/e2e must point at its folder, https://github.com/e2e-inc/e2e/tree/main/examples/<folder>`);
|
|
} else if (!env.folders.includes(folder)) {
|
|
problems.push(`${name}: examples/${folder} does not exist`);
|
|
} else if (folder !== example.slug) {
|
|
problems.push(`${name}: an official example's slug must be its folder name, ${folder}`);
|
|
} else if (!env.initExamples.includes(folder)) {
|
|
problems.push(`${name}: e2e init --example cannot copy ${folder}; add it to packages/e2e/src/cli/init/examples.ts`);
|
|
}
|
|
}
|
|
} else if (ORG_URL.test(example.repository)) {
|
|
problems.push(`${name}: a ${example.source} example lives in its own repository, outside the e2e-inc organization and the e2e_inc group`);
|
|
} else if (example.source === 'partner' && ownerOf(example.repository) !== example.author.github.toLowerCase()) {
|
|
// The site's partner seal credits author.name, so the partner must own the repository.
|
|
problems.push(`${name}: a partner example lives in its author's repository, https://github.com/${example.author.github}/`);
|
|
} else if (example.source === 'community' && !isPinned(example.repository)) {
|
|
// The page renders the README live: a branch could change under a reviewed entry.
|
|
problems.push(
|
|
`${name}: a community example pins its repository to a commit, https://github.com/<owner>/<repo>/tree/<commit sha>/<path> or https://gitlab.com/<group>/<project>/-/tree/<commit sha>/<path>`,
|
|
);
|
|
}
|
|
if (typeof example.readme === 'string') {
|
|
if (repoOf(example.readme) !== repoOf(example.repository)) {
|
|
problems.push(`${name}: readme must be a file in the example's repository, https://${repoOf(example.repository)}/`);
|
|
} else if (readmeUrl({ repository: example.repository, readme: example.readme }) === readmeUrl({ repository: example.repository })) {
|
|
problems.push(`${name}: readme names the folder's own README.md; leave it out`);
|
|
} else if (example.source === 'community' && refOf(example.readme) !== refOf(example.repository)) {
|
|
problems.push(`${name}: a community example's readme is pinned to the same commit as its repository`);
|
|
}
|
|
}
|
|
if (example.source === 'partner' && !example.author?.website) {
|
|
problems.push(`${name}: a partner example names its author's landing page in author.website`);
|
|
} else if (example.source !== 'partner' && example.author?.website) {
|
|
// A website link is part of a partnership, not something any entry can add.
|
|
problems.push(`${name}: only a partner example has author.website`);
|
|
}
|
|
}
|
|
|
|
const listed = new Set(registry.examples.filter((example) => example.source === 'official').map((example) => example.slug));
|
|
for (const folder of env.folders) {
|
|
if (!UNLISTED_FOLDERS.has(folder) && !listed.has(folder)) {
|
|
problems.push(`examples/${folder} has no official entry in examples/examples.json`);
|
|
}
|
|
}
|
|
|
|
return problems;
|
|
}
|
|
|
|
/** Whether an example is a folder in this repository, which the checks read from disk instead of fetching. */
|
|
export function isLocalFolder(repository: string): boolean {
|
|
return FOLDER_URL.test(repository);
|
|
}
|
|
|
|
/**
|
|
* The raw URL of the README the site renders as an example's page: its
|
|
* `readme` file when it names one, else README.md in its `repository`.
|
|
* `undefined` for an example with `readme: false`.
|
|
*/
|
|
export function readmeUrl(example: Pick<RegistryExample, 'repository' | 'readme'>): string | undefined {
|
|
if (example.readme === false) return undefined;
|
|
const parts = splitUrl(example.readme || example.repository);
|
|
if (!parts) return undefined;
|
|
const [, ref = 'HEAD', ...rest] = parts.rest;
|
|
const path = example.readme ? rest.join('/') : [...rest, 'README.md'].join('/');
|
|
return parts.host === 'github.com'
|
|
? `https://raw.githubusercontent.com/${parts.project}/${ref}/${path}`
|
|
: `https://gitlab.com/${parts.project}/-/raw/${ref}/${path}`;
|
|
}
|