chore(repo): Add logic to prevent duplication of legacy hooks Typedoc

.changeset/short-apes-joke.md

@@ -0,0 +1,2 @@
+---
+---

.typedoc/extract-returns-and-params.mjs

@@ -6,13 +6,33 @@ import { fileURLToPath } from 'node:url';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
+const LEGACY_HOOK_NAMES = new Set(['use-sign-in-1', 'use-sign-up-1']);
+
+/**
+ * Returns legacy hook output info or null if not a legacy hook.
+ * @param {string} filePath
+ * @returns {{ outputDir: string; baseName: string } | null}
+ */
+function getLegacyHookTarget(filePath) {
+  const fileName = path.basename(filePath, '.mdx');
+  if (!LEGACY_HOOK_NAMES.has(fileName)) {
+    return null;
+  }
+  const dirName = path.dirname(filePath);
+  return {
+    outputDir: path.join(dirName, 'legacy'),
+    baseName: fileName.replace(/-1$/, ''),
+  };
+}
+
 /**
  * Extracts the "## Returns" section from a markdown file and writes it to a separate file.
  * @param {string} filePath - The path to the markdown file
  * @returns {boolean} True if a file was created
  */
 function extractReturnsSection(filePath) {
   const content = fs.readFileSync(filePath, 'utf-8');
+  const legacyTarget = getLegacyHookTarget(filePath);
 
   // Find the "## Returns" section
   const returnsStart = content.indexOf('## Returns');
@@ -34,8 +54,15 @@ function extractReturnsSection(filePath) {
 
   // Generate the new filename: use-auth.mdx -> use-auth-return.mdx
   const fileName = path.basename(filePath, '.mdx');
-  const dirName = path.dirname(filePath);
-  const newFilePath = path.join(dirName, `${fileName}-return.mdx`);
+  let outputBaseName = `${fileName}-return`;
+  let outputDir = path.dirname(filePath);
+  // Legacy hooks: move into legacy/ and drop the -1
+  if (legacyTarget) {
+    outputBaseName = `${legacyTarget.baseName}-return`;
+    outputDir = legacyTarget.outputDir;
+    fs.mkdirSync(outputDir, { recursive: true });
+  }
+  const newFilePath = path.join(outputDir, `${outputBaseName}.mdx`);
 
   // Write the extracted Returns section to the new file
   fs.writeFileSync(newFilePath, returnsContent, 'utf-8');
@@ -67,10 +94,19 @@ function extractParametersSection(filePath) {
   const content = fs.readFileSync(filePath, 'utf-8');
   const fileName = path.basename(filePath, '.mdx');
   const dirName = path.dirname(filePath);
+  const legacyTarget = getLegacyHookTarget(filePath);
+  let outputDir = dirName;
+  let outputBaseName = fileName;
+
+  if (legacyTarget) {
+    outputDir = legacyTarget.outputDir;
+    outputBaseName = legacyTarget.baseName;
+    fs.mkdirSync(outputDir, { recursive: true });
+  }
 
   // Always use -params suffix
   const suffix = '-params';
-  const targetFileName = `${fileName}${suffix}.mdx`;
+  const targetFileName = `${outputBaseName}${suffix}.mdx`;
   const propsFileName = `${fileName}-props.mdx`;
 
   // Delete any existing -props file (TypeDoc-generated)
@@ -100,13 +136,37 @@ function extractParametersSection(filePath) {
   const processedParams = replaceGenericTypesInParamsTable(paramsContent);
 
   // Write to new file
-  const newFilePath = path.join(dirName, targetFileName);
+  const newFilePath = path.join(outputDir, targetFileName);
   fs.writeFileSync(newFilePath, processedParams, 'utf-8');
 
   console.log(`[extract-returns] Created ${path.relative(process.cwd(), newFilePath)}`);
   return true;
 }
 
+/**
+ * Moves legacy hook docs into a legacy/ folder and removes the -1 suffix
+ * @param {string} filePath
+ */
+function moveLegacyHookDoc(filePath) {
+  const legacyTarget = getLegacyHookTarget(filePath);
+  if (!legacyTarget) {
+    return;
+  }
+
+  const legacyDir = legacyTarget.outputDir;
+  fs.mkdirSync(legacyDir, { recursive: true });
+  const legacyPath = path.join(legacyDir, `${legacyTarget.baseName}.mdx`);
+
+  if (fs.existsSync(legacyPath)) {
+    fs.unlinkSync(legacyPath);
+  }
+
+  fs.renameSync(filePath, legacyPath);
+  console.log(
+    `[extract-returns] Moved ${path.relative(process.cwd(), filePath)} -> ${path.relative(process.cwd(), legacyPath)}`,
+  );
+}
+
 /**
  * Recursively reads all .mdx files in a directory, excluding generated files
  * @param {string} dir - The directory to read
@@ -169,6 +229,9 @@ function main() {
       if (extractParametersSection(filePath)) {
         paramsCount++;
       }
+
+      // Move legacy hook docs after extraction
+      moveLegacyHookDoc(filePath);
     }
 
     console.log(`[extract-returns] Extracted ${returnsCount} Returns sections`);