The open alternative to Salesforce, designed for AI.
TypeScript crmcrm-systemcustomergood-first-issuegraphqlhacktoberfestjavascriptmarketingmonoreponestjsopen-sourcepostgresqlreactreactjssalestypescriptweb
import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
import { dirname, relative, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
import {
type ComponentDoc,
type ParserOptions,
type PropItem,
} from 'react-docgen-typescript';
import ts from 'typescript';
import { DESIGN_TOKENS } from '../design-tokens/designTokens';
import { collectLeaves } from '../design-tokens/pipeline/collectLeaves';
import { DOCUMENTED_COMPONENTS } from '../docs/components';
import { DocumentationParser } from '../docs/DocumentationParser';
import { formatDocumentationTokenValue } from '../docs/formatDocumentationTokenValue';
import { getIconDocumentationGroups } from '../docs/getIconDocumentationGroups';
import { getIconProps } from '../docs/getIconProps';
import { getPublicComponentExports } from '../docs/getPublicComponentExports';
import { isIconComponent } from '../docs/isIconComponent';
import { normalizeDocumentationDefaultValue } from '../docs/normalizeDocumentationDefaultValue';
import { normalizeDocumentationPropType } from '../docs/normalizeDocumentationPropType';
import {
type ComponentDocumentation,
type TokenDocumentation,
} from '../docs/types';
import { isDefined } from '../src/utilities/utils/isDefined';
const HIDDEN_PROP_TAGS = ['ignore', 'internal'];
const COMPONENT_PART_NAME_PATTERN = /^[A-Z]/;
const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
const sourceRoot = resolve(packageRoot, 'src');
const configurationPath = resolve(packageRoot, 'tsconfig.json');
const configuration = ts.readConfigFile(configurationPath, ts.sys.readFile);
if (configuration.error) {
throw new Error(
ts.flattenDiagnosticMessageText(configuration.error.messageText, '\n'),
);
}
const { options, errors } = ts.parseJsonConfigFileContent(
configuration.config,
ts.sys,
packageRoot,
);
if (errors.length > 0) {
throw new Error(
errors
.map((error) => ts.flattenDiagnosticMessageText(error.messageText, '\n'))
.join('\n'),
);
}
const sourcePaths = DOCUMENTED_COMPONENTS.map((component) =>
resolve(sourceRoot, component.source),
);
const packageManifest: { exports: Record<string, unknown> } = JSON.parse(
readFileSync(resolve(packageRoot, 'package.json'), 'utf8'),
);
const entryPoints = Object.keys(packageManifest.exports)
.filter((subpath) => !subpath.endsWith('.css'))
.map((subpath) => ({
name: subpath === '.' ? 'twenty-ui' : `twenty-ui/${subpath.slice(2)}`,
path: resolve(sourceRoot, subpath, 'index.ts'),
}));
const program = ts.createProgram(
[...sourcePaths, ...entryPoints.map((entry) => entry.path)],
{
...options,
preserveSymlinks: true,
},
);
const checker = program.getTypeChecker();
const publicComponents = getPublicComponentExports({
checker,
entryPoints: entryPoints.map((entry) => {
const source = program.getSourceFile(entry.path);
if (!isDefined(source)) {
throw new Error(`Could not read ${entry.name}`);
}
return { name: entry.name, source };
}),
});
const documentedNames = new Set<string>(
DOCUMENTED_COMPONENTS.map((component) => component.name),
);
const documentedDecorators = new Set([
'CatalogDecorator',
'ComponentDecorator',
]);
const catalogIcons = publicComponents.filter(
(component) =>
component.entryPoints.includes('twenty-ui/icon') &&
!documentedNames.has(component.name) &&
isIconComponent(getIconProps({ checker, ...component })),
);
const iconNames = new Set(catalogIcons.map((icon) => icon.name));
for (const component of publicComponents) {
if (
!documentedNames.has(component.name) &&
!iconNames.has(component.name) &&
!documentedDecorators.has(component.name)
) {
throw new Error(
`Missing documentation for ${component.name} from ${component.entryPoints.join(', ')}. Add a public component reference.`,
);
}
}
const iconGroups = getIconDocumentationGroups({ checker, icons: catalogIcons });
const isReactNativeAttribute = (prop: PropItem): boolean =>
prop.declarations !== undefined &&
prop.declarations.length > 0 &&
prop.declarations.every((declaration) =>
declaration.fileName.includes('@types/react/'),
);
const isHiddenProp = (prop: PropItem): boolean =>
HIDDEN_PROP_TAGS.some((tag) => tag in (prop.tags ?? {}));
const isDeclaredInTwentyUi = (propsType: ts.Type, propName: string): boolean =>
(propsType.isUnion() ? propsType.types : [propsType])
.flatMap(
(memberType) => memberType.getProperty(propName)?.getDeclarations() ?? [],
)
.some((declaration) =>
declaration.getSourceFile().fileName.startsWith(sourceRoot),
);
const parserOptions: ParserOptions = {
shouldExtractLiteralValuesFromEnum: true,
shouldIncludePropTagMap: true,
};
const extractProps = ({
symbol,
name,
propDescriptions = {},
propDefaults = {},
propOverrides = {},
}: {
symbol: ts.Symbol;
name: string;
propDescriptions?: Partial<Record<string, string>>;
propDefaults?: Partial<Record<string, string>>;
propOverrides?: Partial<Record<string, { type: string; required?: boolean }>>;
}): ComponentDocumentation['props'] => {
const declaration = symbol.valueDeclaration;
if (!declaration) {
throw new Error(`Could not find the declaration for ${name}`);
}
const componentParser = new DocumentationParser(program, {
...parserOptions,
skipChildrenPropWithoutDoc: !('children' in propDescriptions),
propFilter: (prop) =>
(!isReactNativeAttribute(prop) || prop.name in propDescriptions) &&
!isHiddenProp(prop),
});
const parsed: ComponentDoc | null = componentParser.getComponentInfo(
symbol,
declaration.getSourceFile(),
() => name,
);
const propsSymbol = componentParser.extractPropsFromTypeIfStatelessComponent(
checker.getTypeOfSymbolAtLocation(symbol, declaration),
);
if (
!isDefined(parsed) ||
!isDefined(propsSymbol) ||
Object.keys(parsed.props).length === 0
) {
throw new Error(`Could not extract props for ${name}`);
}
const propsType = checker.getTypeOfSymbol(propsSymbol);
return Object.values(parsed.props)
.sort((left, right) => left.name.localeCompare(right.name, 'en'))
.map((prop) => {
const description = (
propDescriptions[prop.name] ?? prop.description
).trim();
if (
description.length === 0 &&
isDeclaredInTwentyUi(propsType, prop.name)
) {
throw new Error(
`Missing description for ${name}.${prop.name}. Document the prop in its props type or documentation metadata.`,
);
}
const propOverride = propOverrides[prop.name];
return {
name: prop.name,
type:
propOverride?.type ??
normalizeDocumentationPropType({
type: prop.type,
required: prop.required,
}),
required: propOverride?.required ?? prop.required,
defaultValue:
propDefaults[prop.name] ??
normalizeDocumentationDefaultValue(prop.defaultValue),
description,
};
});
};
const components: ComponentDocumentation[] = DOCUMENTED_COMPONENTS.map(
(component) => {
const source = program.getSourceFile(resolve(sourceRoot, component.source));
const moduleSymbol = source && checker.getSymbolAtLocation(source);
let symbol =
moduleSymbol &&
checker
.getExportsOfModule(moduleSymbol)
.find((candidate) => candidate.name === component.name);
if (isDefined(symbol) && (symbol.flags & ts.SymbolFlags.Alias) !== 0) {
symbol = checker.getAliasedSymbol(symbol);
}
if (!symbol?.valueDeclaration) {
throw new Error(`Could not find the export for ${component.name}`);
}
const type = checker.getTypeOfSymbolAtLocation(
symbol,
symbol.valueDeclaration,
);
const metadata = {
name: component.name,
entryPoint: component.entryPoint,
slug: component.slug,
};
const props =
type.getCallSignatures().length > 0
? extractProps({
symbol,
name: component.name,
propDescriptions:
'propDescriptions' in component
? component.propDescriptions
: undefined,
propDefaults:
'propDefaults' in component ? component.propDefaults : undefined,
})
: [];
const partNames: readonly string[] | undefined =
'parts' in component ? component.parts : undefined;
const partPropDescriptions: Partial<
Record<string, Partial<Record<string, string>>>
> =
'partPropDescriptions' in component ? component.partPropDescriptions : {};
const partPropDefaults: Partial<
Record<string, Partial<Record<string, string>>>
> = 'partPropDefaults' in component ? component.partPropDefaults : {};
const partPropOverrides: Partial<
Record<
string,
Partial<Record<string, { type: string; required?: boolean }>>
>
> = 'partPropOverrides' in component ? component.partPropOverrides : {};
const componentParts = type
.getProperties()
.filter((part) => COMPONENT_PART_NAME_PATTERN.test(part.name))
.filter((part) => partNames?.includes(part.name) ?? props.length === 0);
const parts = componentParts.map((part) => {
const declaration = part.valueDeclaration;
const isNamespaceExport = (part.flags & ts.SymbolFlags.Alias) !== 0;
const isObjectPart =
isDefined(declaration) && ts.isPropertyAssignment(declaration);
if (!isObjectPart && !isNamespaceExport) {
throw new Error(`Could not resolve ${component.name}.${part.name}`);
}
let partSymbol = isObjectPart
? checker.getSymbolAtLocation(declaration.initializer)
: part;
if (!partSymbol) {
throw new Error(`Could not find ${component.name}.${part.name}`);
}
if ((partSymbol.flags & ts.SymbolFlags.Alias) !== 0) {
partSymbol = checker.getAliasedSymbol(partSymbol);
}
return {
name: part.name,
props: extractProps({
symbol: partSymbol,
name: `${component.name}.${part.name}`,
propDescriptions: partPropDescriptions[part.name],
propDefaults: partPropDefaults[part.name],
propOverrides: partPropOverrides[part.name],
}),
};
});
if (props.length === 0 && parts.length === 0) {
throw new Error(`Could not extract parts for ${component.name}`);
}
return {
...metadata,
props,
...(parts.length > 0 ? { parts } : {}),
};
},
);
const tokens: TokenDocumentation[] = collectLeaves(DESIGN_TOKENS)
.map((leaf) => ({
path: leaf.path.join('.'),
cssVariable: leaf.varName,
light: formatDocumentationTokenValue(leaf.light),
dark: formatDocumentationTokenValue(leaf.dark),
isNumber: leaf.unit === 'number',
}))
.sort((left, right) =>
left.path.localeCompare(right.path, 'en', { numeric: true }),
);
const outputs = [
{ name: 'components.docs.json', data: components },
{ name: 'tokens.docs.json', data: tokens },
{ name: 'icons.docs.json', data: iconGroups },
];
const isCheckMode = process.argv.includes('--check');
for (const output of outputs) {
const outputPath = resolve(packageRoot, 'generated', output.name);
const content = `${JSON.stringify(output.data, null, 2)}\n`;
if (isCheckMode) {
if (
!existsSync(outputPath) ||
readFileSync(outputPath, 'utf8') !== content
) {
process.stderr.write(
`Stale documentation data: ${relative(packageRoot, outputPath)}. Run npx nx generate:ui twenty-docs.\n`,
);
process.exitCode = 1;
}
} else {
mkdirSync(dirname(outputPath), { recursive: true });
writeFileSync(outputPath, content);
}
}