Skip to content

The open alternative to Salesforce, designed for AI.

11.6 KB
Raw Blame
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);
  }
}