Merge branch 'main' into zodiac

.github/pull_request_template.md

@@ -0,0 +1,3 @@
+<!-- Please first read https://github.com/faker-js/faker/blob/verify-semantic-pull-requests/CONTRIBUTING.md -->
+
+<!-- Help us by writing a correct PR title following this guide: https://github.com/faker-js/faker/blob/verify-semantic-pull-requests/CONTRIBUTING.md#committing -->

.github/workflows/semantic-pull-request.yml

@@ -20,17 +20,11 @@ jobs:
           types: |
             feat
             fix
-            docs
-            dx
+            chore
             refactor
-            perf
+            docs
             test
-            locale
-            workflow
-            build
             ci
-            chore
-            types
-            wip
-            release
-            deps
+            build
+            infra
+            revert

CONTRIBUTING.md

@@ -225,3 +225,107 @@ pnpm run docs:serve # Serve docs from /dist
 ## Deploying documentation
 
 See the [netlify.toml](netlify.toml) for configuration.
+
+## Committing
+
+Pull Request titles need to follow our semantic convention.
+
+PR titles are written in following convention: `type(scope): subject`
+
+**type** is required and indicates the intent of the PR
+
+> The types `feat` and `fix` will be shown in the changelog as `### Features` or `### Bug Fixes`  
+> All other types wont show up except for breaking changes marked with the `!` in front of `:`
+
+Allowed types are:
+
+| type     | description                                                               |
+| -------- | ------------------------------------------------------------------------- |
+| feat     | A new feature is introduced                                               |
+| fix      | A bug was fixed                                                           |
+| chore    | No user affected code changes were made                                   |
+| refactor | A refactoring that affected also user (e.g. log a deprecation warning)    |
+| docs     | Docs were changed                                                         |
+| test     | Test were changed                                                         |
+| ci       | CI were changed                                                           |
+| build    | Build scripts were changed                                                |
+| infra    | Infrastructure related things were made (e.g. issue-template was updated) |
+| revert   | A revert was triggered via git                                            |
+
+**scope** is optional and indicates the scope of the PR
+
+> The scope will be shown in the changelog in front of the _subject_ in bold text  
+> Also as the commits are sorted alphabetically, the scope will group the commits indirectly into categories
+
+Allowed scopes are:
+
+| scope           | description                                                                  |
+| --------------- | ---------------------------------------------------------------------------- |
+| \<module-name\> | The specific module name that was affected by the PR                         |
+| locale          | When only locale(s) are added/updated/removed                                |
+| module          | When some modules where updates or something related to modules were changed |
+| revert          | When a revert was made via git                                               |
+| deps            | Will mostly be used by Renovate                                              |
+| release         | Will be set by release process                                               |
+
+> The scope is not checkable via `Semantic Pull Request` action as this would limit the scopes to only existing modules,  
+> but if we add a new module like `color`, then the PR author couldn't use the new module name as scope.  
+> As such, we (the Faker team) must be mindful of valid scopes and we reserve the right to edit titles as we see fit.
+
+**subject** is required and describes what the PR does
+
+> Please note that the PR title should not include a suffix of e.g. `(#123)` as this will be done automatically by GitHub while merging
+
+Some examples of valid pull request titles:
+
+```shell
+feat: add casing option
+feat(locale): extend Hebrew (he)
+fix: lower target to support Webpack 4
+chore: add naming convention rule
+refactor(address): deprecate streetPrefix and streetSuffix
+docs: remove unused playground
+test: validate @see contents
+ci: allow breaking change commits
+build: add node v18 support
+infra: rework bug-report template
+revert: add more arabic names dataset (#362)
+
+# Breaking changes
+refactor!: remove faker default export
+build!: remove node v12 support
+
+# A release PR will look like this
+chore(release): 7.4.0
+
+# Renovate automatically generates these
+chore(deps): update devdependencies
+chore(deps): update typescript-eslint to ~5.33.0
+```
+
+Previous pull request titles that could have been written in a better way:
+
+```diff
+- feat: `datatype.hexadecimal` signature change
++ feat(datatype): hexadecimal signature change
+  datatype is one of our modules and can be used as scope
+
+- feat(image): add image via.placeholder provider
++ feat(image): add via.placeholder provider
+  image was redundant in the subject
+
+- feat(system.networkInterface): add networkInterface faker
++ feat(system): add networkInterface method
+  networkInterface was redundant in the scope and made the whole commit message long
+  also method in the subject explains a bit better what it is
+
+- chore(bug-report-template): new design
++ infra: rework bug-report template
+  the type infra tells that no actual code-changes were made
+  the subject contains what the PR does
+
+- chore: rename Gender to Sex
++ refactor(name): rename Gender to Sex
+  this was not a chore as it touched runtime code that affected the end-user
+  scope name can be used here to tell that the change affects only the name module
+```

docs/.vitepress/components/api-docs/method.vue

@@ -12,8 +12,6 @@ function seeAlsoToUrl(see: string): string {
 
 <template>
   <div>
-    <h2 :id="props.method.name">{{ props.method.title }}</h2>
-
     <div v-if="props.method.deprecated" class="warning custom-block">
       <p class="custom-block-title">Deprecated</p>
       <p>This method is deprecated and will be removed in a future version.</p>

docs/api/.gitignore

@@ -1,3 +1,3 @@
 *.md
 !localization.md
-*.ts
+*.json

package.json

@@ -128,7 +128,7 @@
     "standard-version": "~9.5.0",
     "tsx": "~3.8.2",
     "typedoc": "~0.23.10",
-    "typedoc-plugin-missing-exports": "~0.23.0",
+    "typedoc-plugin-missing-exports": "~1.0.0",
     "typescript": "~4.7.4",
     "validator": "~13.7.0",
     "vite": "~3.0.7",

scripts/apidoc/apiDocsWriter.ts

@@ -26,40 +26,41 @@ editLink: false
  * @param moduleName The name of the module to write the docs for.
  * @param lowerModuleName The lowercase name of the module.
  * @param comment The module comments.
+ * @param methods The methods of the module.
  */
 export function writeApiDocsModulePage(
   moduleName: string,
   lowerModuleName: string,
-  comment: string
+  comment: string,
+  methods: Method[]
 ): void {
   // Write api docs page
   let content = `
   <script setup>
-  import ApiDocsMethod from '../.vitepress/components/api-docs/method.vue'
-  import { ${lowerModuleName} } from './${lowerModuleName}'
-  import { ref } from 'vue';
-
-  const methods = ref(${lowerModuleName});
+  import ApiDocsMethod from '../.vitepress/components/api-docs/method.vue';
+  import ${lowerModuleName} from './${lowerModuleName}.json';
   </script>
 
-  # ${moduleName}
-
   <!-- This file is automatically generated. -->
   <!-- Run '${scriptCommand}' to update -->
 
+  # ${moduleName}
+
   ::: v-pre
 
   ${comment}
 
   :::
 
-  <ul>
-    <li v-for="method of methods" :key="method.name">
-      <a :href="'#' + method.name">{{ method.title }}</a>
-    </li>
-  </ul>
+  ${methods
+    .map(
+      (method) => `
+  ## ${method.name}
 
-  <ApiDocsMethod v-for="method of methods" :key="method.name" :method="method" v-once />
+  <ApiDocsMethod :method="${lowerModuleName}.${method.name}" v-once />
+  `
+    )
+    .join('')}
   `.replace(/\n +/g, '\n');
 
   content = vitePressInFileOptions + formatMarkdown(content);
@@ -71,18 +72,26 @@ export function writeApiDocsModulePage(
  * Writes the api page for the given method to the correct location.
  *
  * @param methodName The name of the method to write the docs for.
+ * @param capitalizedMethodName The capitalized name of the method.
  */
-export function writeApiDocsDirectPage(methodName: string): void {
+export function writeApiDocsDirectPage(
+  methodName: string,
+  capitalizedMethodName: string
+): void {
   let content = `
   <script setup>
-  import ApiDocsMethod from '../.vitepress/components/api-docs/method.vue'
-  import { ${methodName} } from './${methodName}'
-  import { ref } from 'vue';
-
-  const methods = ref(${methodName});
+  import ApiDocsMethod from '../.vitepress/components/api-docs/method.vue';
+  import ${methodName} from './${methodName}.json';
   </script>
 
-  <ApiDocsMethod v-for="method of methods" :key="method.name" :method="method" v-once />
+  <!-- This file is automatically generated. -->
+  <!-- Run '${scriptCommand}' to update -->
+
+  # ${capitalizedMethodName}
+
+  ## ${methodName}
+
+  <ApiDocsMethod :method="${methodName}.${methodName}" v-once />
   `.replace(/\n +/g, '\n');
 
   content = vitePressInFileOptions + formatMarkdown(content);
@@ -100,18 +109,17 @@ export function writeApiDocsData(
   lowerModuleName: string,
   methods: Method[]
 ): void {
-  let contentTs = `
-import type { Method } from '../.vitepress/components/api-docs/method';
-
-export const ${lowerModuleName}: Method[] = ${JSON.stringify(
-    methods,
-    null,
-    2
-  )}`;
-
-  contentTs = formatTypescript(contentTs);
-
-  writeFileSync(resolve(pathOutputDir, `${lowerModuleName}.ts`), contentTs);
+  const content = JSON.stringify(
+    methods.reduce<Record<string, Method>>(
+      (map, method) => ({
+        ...map,
+        [method.name]: method,
+      }),
+      {}
+    )
+  );
+
+  writeFileSync(resolve(pathOutputDir, `${lowerModuleName}.json`), content);
 }
 
 /**

scripts/apidoc/directMethods.ts

@@ -1,26 +1,40 @@
-import * as TypeDoc from 'typedoc';
+import type {
+  DeclarationReflection,
+  ProjectReflection,
+  ReflectionType,
+} from 'typedoc';
+import { ReflectionKind } from 'typedoc';
 import { writeApiDocsData, writeApiDocsDirectPage } from './apiDocsWriter';
 import { analyzeSignature } from './signature';
 import type { Page, PageIndex } from './utils';
 
+/**
+ * Selects the direct methods from the project that needs to be documented.
+ *
+ * @param project The project used to extract the direct methods.
+ * @returns The direct methods to document.
+ */
+export function selectDirectMethods(
+  project: ProjectReflection
+): DeclarationReflection[] {
+  return project
+    .getChildrenByKind(ReflectionKind.Class)
+    .filter((ref) => ref.name === 'Faker')[0]
+    .getChildrenByKind(ReflectionKind.Property)
+    .filter((ref) => ['fake', 'unique'].includes(ref.name));
+}
+
 /**
  * Analyzes and writes the documentation for direct methods such as `faker.fake()`.
  *
  * @param project The project used to extract the direct methods.
  * @returns The generated pages.
  */
-export function processDirectMethods(
-  project: TypeDoc.ProjectReflection
-): PageIndex {
+export function processDirectMethods(project: ProjectReflection): PageIndex {
   const pages: PageIndex = [];
 
-  const directs = project
-    .getChildrenByKind(TypeDoc.ReflectionKind.Class)
-    .filter((ref) => ref.name === 'Faker')[0]
-    .getChildrenByKind(TypeDoc.ReflectionKind.Property)
-    .filter((ref) => ['fake', 'unique'].includes(ref.name));
-
-  for (const direct of directs) {
+  // Generate direct method files
+  for (const direct of selectDirectMethods(project)) {
     pages.push(processDirectMethod(direct));
   }
 
@@ -33,25 +47,22 @@ export function processDirectMethods(
  * @param direct The direct method to process.
  * @returns The generated pages.
  */
-export function processDirectMethod(
-  direct: TypeDoc.DeclarationReflection
-): Page {
+export function processDirectMethod(direct: DeclarationReflection): Page {
   const methodName = direct.name;
-  const upperMethodName =
+  const capitalizedMethodName =
     methodName.substring(0, 1).toUpperCase() + methodName.substring(1);
-  console.log(`Processing Direct: ${upperMethodName}`);
+  console.log(`Processing Direct: ${capitalizedMethodName}`);
 
-  const signatures = (direct.type as TypeDoc.ReflectionType).declaration
-    .signatures;
+  const signatures = (direct.type as ReflectionType).declaration.signatures;
   const signature = signatures[signatures.length - 1];
 
-  writeApiDocsDirectPage(methodName);
+  writeApiDocsDirectPage(methodName, capitalizedMethodName);
   writeApiDocsData(methodName, [
     analyzeSignature(signature, undefined, methodName),
   ]);
 
   return {
-    text: upperMethodName,
+    text: capitalizedMethodName,
     link: `/api/${methodName}.html`,
   };
 }