chore: import upstream snapshot with attribution

nx-dev/models-document/.babelrc

@@ -0,0 +1,10 @@
+{
+  "presets": [
+    [
+      "@nx/js/babel",
+      {
+        "useBuiltIns": "usage"
+      }
+    ]
+  ]
+}

nx-dev/models-document/README.md

@@ -0,0 +1,7 @@
+# nx-dev-models-document
+
+This library was generated with [Nx](https://nx.dev).
+
+## Running unit tests
+
+Run `nx test nx-dev-models-document` to execute the unit tests via [Jest](https://jestjs.io).

nx-dev/models-document/eslint.config.mjs

@@ -0,0 +1,3 @@
+import { baseConfig } from '../../eslint.config.mjs';
+
+export default [...baseConfig];

nx-dev/models-document/jest.config.cts

@@ -0,0 +1,16 @@
+/* eslint-disable */
+module.exports = {
+  displayName: 'nx-dev-models-document',
+  globals: {},
+  transform: {
+    '^.+\\.[tj]sx?$': [
+      'ts-jest',
+      {
+        tsconfig: '<rootDir>/tsconfig.spec.json',
+      },
+    ],
+  },
+  moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx'],
+  coverageDirectory: '../../coverage/nx-dev/models-document',
+  preset: '../../jest.preset.js',
+};

nx-dev/models-document/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "@nx/nx-dev-models-document",
+  "version": "0.0.1",
+  "type": "commonjs",
+  "private": true,
+  "main": "./src/index.ts",
+  "types": "./src/index.ts"
+}

nx-dev/models-document/project.json

@@ -0,0 +1,8 @@
+{
+  "name": "nx-dev-models-document",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "nx-dev/models-document/src",
+  "projectType": "library",
+  "targets": {},
+  "tags": ["scope:nx-dev", "type:util"]
+}

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);
+}

nx-dev/models-document/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "files": [],
+  "include": [],
+  "references": [
+    {
+      "path": "./tsconfig.lib.json"
+    }
+  ]
+}

nx-dev/models-document/tsconfig.lib.json

@@ -0,0 +1,11 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "declaration": true,
+    "types": ["node"],
+    "composite": true
+  },
+  "exclude": ["**/*.spec.ts", "**/*.test.ts", "jest.config.ts"],
+  "include": ["**/*.ts"]
+}

nx-dev/models-document/tsconfig.spec.json

@@ -0,0 +1,19 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist/spec",
+    "types": ["jest", "node"]
+  },
+  "include": [
+    "**/*.test.ts",
+    "**/*.spec.ts",
+    "**/*.test.tsx",
+    "**/*.spec.tsx",
+    "**/*.test.js",
+    "**/*.spec.js",
+    "**/*.test.jsx",
+    "**/*.spec.jsx",
+    "**/*.d.ts",
+    "jest.config.ts"
+  ]
+}