chore: import upstream snapshot with attribution

nx-dev/models-document/src/index.ts

@@ -0,0 +1,4 @@
+export * from './lib/documents.models';
+export * from './lib/documents.transformers';
+export * from './lib/related-documents.utils';
+export { pkgToGeneratedApiDocs } from './lib/mappings';

nx-dev/models-document/src/lib/documents.models.ts

@@ -0,0 +1,42 @@
+/**
+ * @deprecated
+ */
+export interface DocumentData {
+  filePath: string;
+  data: { [key: string]: any };
+  content: string;
+  relatedContent: string;
+  tags: string[];
+}
+
+export interface DocumentMetadata {
+  id: string;
+  name: string;
+  description: string;
+  mediaImage?: string;
+  file: string;
+  path: string;
+  isExternal: boolean;
+  itemList: DocumentMetadata[];
+  tags: string[];
+}
+
+export interface ProcessedDocument {
+  content: string;
+  description: string;
+  mediaImage?: string;
+  filePath: string;
+  id: string;
+  name: string;
+  relatedDocuments: Record<string, RelatedDocument[]>;
+  parentDocuments?: RelatedDocument[];
+  tags: string[];
+}
+
+export interface RelatedDocument {
+  description: string;
+  file: string;
+  id: string;
+  name: string;
+  path: string;
+}

nx-dev/models-document/src/lib/documents.transformers.ts

@@ -0,0 +1,42 @@
+import { DocumentMetadata } from './documents.models';
+
+export function createDocumentMetadata(
+  defaults: Partial<DocumentMetadata> = {}
+): DocumentMetadata {
+  if (!defaults.id) throw new Error('A document entry requires an "id".');
+
+  return Object.assign(
+    {},
+    {
+      id: 'fake-id',
+      name: '',
+      description: '',
+      file: '',
+      itemList: [],
+      isExternal: false,
+      path: '',
+      tags: [],
+    },
+    defaults
+  );
+}
+
+export function convertToDocumentMetadata(
+  target: Partial<DocumentMetadata>
+): DocumentMetadata {
+  if (!target.id) throw new Error('A document entry requires an "id".');
+
+  return {
+    id: target.id,
+    name: target.name ?? '',
+    description: target.description ?? '',
+    mediaImage: target.mediaImage ?? '',
+    file: target.file ?? '',
+    itemList: target.itemList
+      ? target.itemList.map((item) => convertToDocumentMetadata(item))
+      : [],
+    isExternal: target.isExternal ?? false,
+    path: target.path ?? '',
+    tags: target.tags ?? [],
+  };
+}

nx-dev/models-document/src/lib/mappings.ts

@@ -0,0 +1,186 @@
+/*
+ * We present a different grouping or naming for the API docs compared to their package names.
+ * - pagePath - the path to the package's API docs page
+ * - includeDocuments - whether to include documents, which should eventually be moved to guides
+ *
+ * This mapping is used in:
+ * - scripts/documentation/generators/generate-manifests.ts (generate menus)
+ * - nx-dev/data-access-documents/src/lib/documents.api.ts (generate page urls)
+ * - nx-dev/nx-dev/pages/[...segments].tsx (generate page content)
+ */
+export const pkgToGeneratedApiDocs: Record<
+  string,
+  { pagePath: string; introPath: string; includeDocuments?: boolean }
+> = {
+  // ts/js
+  js: {
+    pagePath: '/technologies/typescript/api',
+    introPath: '/technologies/typescript/introduction',
+  },
+  // angular
+  angular: {
+    pagePath: '/technologies/angular/api',
+    introPath: '/technologies/angular/introduction',
+  },
+  // react
+  react: {
+    pagePath: '/technologies/react/api',
+    introPath: '/technologies/react/introduction',
+  },
+  'react-native': {
+    pagePath: '/technologies/react/react-native/api',
+    introPath: '/technologies/react/react-native/introduction',
+  },
+  expo: {
+    pagePath: '/technologies/react/expo/api',
+    introPath: '/technologies/react/expo/introduction',
+  },
+  next: {
+    pagePath: '/technologies/react/next/api',
+    introPath: '/technologies/react/next/introduction',
+  },
+  remix: {
+    pagePath: '/technologies/react/remix/api',
+    introPath: '/technologies/react/remix/introduction',
+  },
+  // vue
+  vue: {
+    pagePath: '/technologies/vue/api',
+    introPath: '/technologies/vue/introduction',
+  },
+  nuxt: {
+    pagePath: '/technologies/vue/nuxt/api',
+    introPath: '/technologies/vue/nuxt/introduction',
+  },
+  // node
+  node: {
+    pagePath: '/technologies/node/api',
+    introPath: '/technologies/node/introduction',
+  },
+  express: {
+    pagePath: '/technologies/node/express/api',
+    introPath: '/technologies/node/express/introduction',
+  },
+  nest: {
+    pagePath: '/technologies/node/nest/api',
+    introPath: '/technologies/node/nest/introduction',
+  },
+  // java
+  gradle: {
+    pagePath: '/technologies/java/api',
+    introPath: '/technologies/java/introduction',
+  },
+  // build tools
+  webpack: {
+    pagePath: '/technologies/build-tools/webpack/api',
+    introPath: '/technologies/build-tools/webpack/introduction',
+  },
+  vite: {
+    pagePath: '/technologies/build-tools/vite/api',
+    introPath: '/technologies/build-tools/vite/introduction',
+  },
+  rollup: {
+    pagePath: '/technologies/build-tools/rollup/api',
+    introPath: '/technologies/build-tools/rollup/introduction',
+  },
+  esbuild: {
+    pagePath: '/technologies/build-tools/esbuild/api',
+    introPath: '/technologies/build-tools/esbuild/introduction',
+  },
+  rspack: {
+    pagePath: '/technologies/build-tools/rspack/api',
+    introPath: '/technologies/build-tools/rspack/introduction',
+  },
+  rsbuild: {
+    pagePath: '/technologies/build-tools/rsbuild/api',
+    introPath: '/technologies/build-tools/rsbuild/introduction',
+  },
+  // test tools
+  jest: {
+    pagePath: '/technologies/test-tools/jest/api',
+    introPath: '/technologies/test-tools/jest/introduction',
+  },
+  storybook: {
+    pagePath: '/technologies/test-tools/storybook/api',
+    introPath: '/technologies/test-tools/storybook/introduction',
+  },
+  playwright: {
+    pagePath: '/technologies/test-tools/playwright/api',
+    introPath: '/technologies/test-tools/playwright/introduction',
+  },
+  cypress: {
+    pagePath: '/technologies/test-tools/cypress/api',
+    introPath: '/technologies/test-tools/cypress/introduction',
+  },
+  detox: {
+    pagePath: '/technologies/test-tools/detox/api',
+    introPath: '/technologies/test-tools/detox/introduction',
+  },
+  // misc
+  'module-federation': {
+    pagePath: '/technologies/module-federation/api',
+    introPath: '/technologies/module-federation/introduction',
+  },
+  eslint: {
+    pagePath: '/technologies/eslint/api',
+    introPath: '/technologies/eslint/introduction',
+  },
+  'eslint-plugin': {
+    pagePath: '/technologies/eslint/eslint-plugin/api',
+    introPath: '/technologies/eslint/eslint-plugin/api',
+  },
+  // core and misc
+  // For now, things that are not in technologies are put here in references/core-api
+  nx: {
+    pagePath: '/reference/core-api/nx',
+    introPath: '/reference/core-api/nx',
+    // TODO(docs): move these to guides and remove this
+    includeDocuments: true,
+  },
+  workspace: {
+    pagePath: '/reference/core-api/workspace',
+    introPath: '/reference/core-api/workspace',
+    // TODO(docs): move these to guides and remove this
+    includeDocuments: true,
+  },
+  owners: {
+    pagePath: '/reference/core-api/owners',
+    introPath: '/reference/core-api/owners',
+  },
+  conformance: {
+    pagePath: '/reference/core-api/conformance',
+    introPath: '/reference/core-api/conformance',
+    // TODO(docs): move these to guides and remove this
+    includeDocuments: true,
+  },
+  'azure-cache': {
+    pagePath: '/reference/core-api/azure-cache',
+    introPath: '/reference/core-api/azure-cache',
+  },
+  'gcs-cache': {
+    pagePath: '/reference/core-api/gcs-cache',
+    introPath: '/reference/core-api/gcs-cache',
+  },
+  's3-cache': {
+    pagePath: '/reference/core-api/s3-cache',
+    introPath: '/reference/core-api/s3-cache',
+  },
+  'shared-fs-cache': {
+    pagePath: '/reference/core-api/shared-fs-cache',
+    introPath: '/reference/core-api/shared-fs-cache',
+  },
+  devkit: {
+    pagePath: '/reference/core-api/devkit',
+    introPath: '/reference/core-api/devkit/documents/nx_devkit',
+    // TODO(docs): move these to guides and remove this
+    includeDocuments: true,
+  },
+  plugin: {
+    pagePath: '/reference/core-api/plugin',
+    introPath: '/reference/core-api/plugin',
+  },
+  web: {
+    pagePath: '/reference/core-api/web',
+    introPath: '/reference/core-api/web',
+  },
+};

nx-dev/models-document/src/lib/related-documents.utils.ts

@@ -0,0 +1,56 @@
+import { RelatedDocument } from './documents.models';
+
+export interface RelatedDocumentsCategory {
+  id: string;
+  /**
+   * Matcher that will be evaluated against a path.
+   */
+  matchers: string[];
+  name: string;
+  relatedDocuments: RelatedDocument[];
+}
+
+export function categorizeRelatedDocuments(
+  items: RelatedDocument[]
+): RelatedDocumentsCategory[] {
+  const categories: RelatedDocumentsCategory[] = [
+    {
+      id: 'concepts',
+      name: 'Concepts',
+      matchers: [
+        '/concepts/',
+        '/concepts/module-federation/',
+        '/concepts/decisions/',
+      ],
+      relatedDocuments: [],
+    },
+    {
+      id: 'recipes',
+      name: 'Guides',
+      matchers: ['/recipes/', '/guides/'],
+      relatedDocuments: [],
+    },
+    {
+      id: 'reference',
+      name: 'Reference',
+      // TODO(caleb): including /technologies/ in the route will duplicate the display of `recipes/guides` so leaving off for now
+      matchers: ['/workspace/', '/nx-api/', '/core-api/'],
+      relatedDocuments: [],
+    },
+    {
+      id: 'see-also',
+      name: 'See also',
+      matchers: ['/see-also/'],
+      relatedDocuments: [],
+    },
+  ];
+
+  items?.forEach((i) =>
+    categories.forEach((c) => {
+      if (c.matchers.some((m) => i.path.includes(m)))
+        c.relatedDocuments.push(i);
+    })
+  );
+
+  return categories.filter((c) => !!c.relatedDocuments.length);
+}