@rtorcato/js-tooling 2.16.0 → 2.17.1

package/dist/cli/commands/doctor.js

@@ -596,6 +596,72 @@ async function checkCodeQL(dir) {
         hint: 'Run `npx @rtorcato/js-tooling fix codeql` to scaffold CodeQL security scanning',
     };
 }
+const TYPEDOC_CONFIGS = [
+    'typedoc.json',
+    'typedoc.config.js',
+    'typedoc.config.mjs',
+    'typedoc.config.cjs',
+    'typedoc.config.ts',
+];
+async function checkTypedoc(dir, pkg) {
+    if (pkg?.private === true) {
+        return {
+            check: 'TypeDoc',
+            status: 'ok',
+            detail: 'not applicable (package is private)',
+        };
+    }
+    let configFile = null;
+    let configContent = null;
+    for (const candidate of TYPEDOC_CONFIGS) {
+        const fp = path.join(dir, candidate);
+        if (await fs.pathExists(fp)) {
+            configFile = candidate;
+            try {
+                configContent = await fs.readFile(fp, 'utf-8');
+            }
+            catch {
+                configContent = '';
+            }
+            break;
+        }
+    }
+    const deps = {
+        ...(pkg?.dependencies ?? {}),
+        ...(pkg?.devDependencies ?? {}),
+    };
+    const hasDep = !!deps['typedoc'];
+    const usesPreset = configContent ? /@rtorcato\/js-tooling\/typedoc/.test(configContent) : false;
+    if (configFile && usesPreset) {
+        return {
+            check: 'TypeDoc',
+            status: 'ok',
+            detail: `${configFile} extends the preset`,
+        };
+    }
+    if (configFile && !usesPreset) {
+        return {
+            check: 'TypeDoc',
+            status: 'drift',
+            detail: `${configFile} found but does not extend @rtorcato/js-tooling/typedoc`,
+            hint: 'Add `"extends": ["@rtorcato/js-tooling/typedoc"]` to typedoc.json',
+        };
+    }
+    if (hasDep && !configFile) {
+        return {
+            check: 'TypeDoc',
+            status: 'drift',
+            detail: 'typedoc installed but no typedoc.json found',
+            hint: 'Run `npx @rtorcato/js-tooling fix typedoc` to scaffold typedoc.json',
+        };
+    }
+    return {
+        check: 'TypeDoc',
+        status: 'optional-missing',
+        detail: 'TypeDoc not configured',
+        hint: 'Run `npx @rtorcato/js-tooling fix typedoc` to scaffold API docs generation',
+    };
+}
 function isPublishableLibrary(pkg) {
     if (!pkg || pkg.private === true)
         return false;
@@ -748,6 +814,7 @@ export async function runDoctor(dir) {
     results.push(await checkCodeQL(targetDir));
     results.push(await checkGitLabCI(targetDir));
     results.push(await checkCodeowners(targetDir));
+    results.push(await checkTypedoc(targetDir, pkg));
     results.push(await checkAreTheTypesWrong(targetDir, pkg));
     results.push(await checkTreeshakeSetup(targetDir, pkg));
     // Lockfile-driven demotion: if the lock records an intentional opt-out for a

package/dist/cli/commands/fix-targets.js

@@ -25,6 +25,7 @@ export const FIX_TARGETS = {
     lockfile: 'lockfile',
     '.js-tooling.json': 'lockfile',
     'are-the-types-wrong': 'attw',
+    TypeDoc: 'typedoc',
 };
 export function getFixTargetForCheck(checkName) {
     return FIX_TARGETS[checkName] ?? null;

package/dist/cli/commands/fix.js

@@ -13,6 +13,7 @@ import { composeVerifyScriptFromPkg } from '../generators/package-json.js';
 import { generateCodeQLWorkflow, generateDependabotConfig, generateRenovateConfig, } from '../generators/security.js';
 import { generateVitestConfig } from '../generators/testing.js';
 import { generateTreeshakeCheck, inferSubpathsFromExports } from '../generators/treeshake.js';
+import { generateTypedocConfig, generateTypedocWorkflow } from '../generators/typedoc.js';
 import { copyPreset } from '../utils/copy-preset.js';
 import { LOCKFILE_NAME, readLockfile, updateLockfileConfig, writeLockfile, } from '../utils/lockfile.js';
 import { runDoctor } from './doctor.js';
@@ -359,6 +360,30 @@ const FIXERS = [
             return { filesWritten: written };
         },
     },
+    {
+        target: 'typedoc',
+        description: 'Scaffold typedoc.json extending the preset + .github/workflows/docs.yml (GitHub Pages)',
+        appliesTo: ['TypeDoc'],
+        outputs: ['typedoc.json', '.github/workflows/docs.yml'],
+        riskLevel: 'safe-add',
+        canFixDrift: true,
+        async run({ targetDir, pkg }) {
+            await generateTypedocConfig(pkg, targetDir);
+            const workflow = await generateTypedocWorkflow(targetDir);
+            const pkgPath = path.join(targetDir, 'package.json');
+            const filesWritten = ['typedoc.json', workflow];
+            if (await fs.pathExists(pkgPath)) {
+                const pkgData = (await fs.readJson(pkgPath));
+                const scripts = pkgData.scripts ?? {};
+                if (!scripts.docs) {
+                    pkgData.scripts = { ...scripts, docs: 'typedoc' };
+                    await fs.writeJson(pkgPath, pkgData, { spaces: 2 });
+                    filesWritten.push('package.json');
+                }
+            }
+            return { filesWritten };
+        },
+    },
     {
         target: 'package-json',
         description: 'Add @rtorcato/js-tooling to devDependencies',

package/dist/cli/generators/typedoc.js

@@ -0,0 +1,40 @@
+import path from 'node:path';
+import fs from 'fs-extra';
+const DOCS_WORKFLOW = `name: 📚 Docs
+on:
+  push:
+    branches: [main]
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm docs
+      - uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: \${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs
+`;
+export async function generateTypedocConfig(pkg, targetDir) {
+    const name = pkg?.name ?? 'My Library';
+    const config = {
+        extends: ['@rtorcato/js-tooling/typedoc'],
+        entryPoints: ['./src/index.ts'],
+        name,
+    };
+    await fs.writeJson(path.join(targetDir, 'typedoc.json'), config, { spaces: 2 });
+}
+export async function generateTypedocWorkflow(targetDir) {
+    const workflowsDir = path.join(targetDir, '.github', 'workflows');
+    await fs.ensureDir(workflowsDir);
+    await fs.writeFile(path.join(workflowsDir, 'docs.yml'), DOCS_WORKFLOW);
+    return '.github/workflows/docs.yml';
+}

package/dist/cli/index.js

@@ -148,6 +148,12 @@ const TOOL_CATALOG = [
         exports: ['@rtorcato/js-tooling/tsup'],
         fixTarget: null,
     },
+    {
+        name: 'TypeDoc',
+        description: 'API documentation generation for TypeScript library projects',
+        exports: ['@rtorcato/js-tooling/typedoc'],
+        fixTarget: 'typedoc',
+    },
     {
         name: 'esbuild',
         description: 'Fast JavaScript bundler configuration',

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@rtorcato/js-tooling",
-	"version": "2.16.0",
+	"version": "2.17.1",
 	"description": "JavaScript and TypeScript tooling for Node.js, React, Next.js, and Vitest.",
 	"type": "module",
 	"keywords": [
@@ -70,6 +70,7 @@
 		"tooling/tests/ssr-safety.d.mts",
 		"tooling/tsup/index.ts",
 		"tooling/biome/biome.json",
+		"tooling/typedoc/typedoc.json",
 		"tooling/semantic-release/*.mjs",
 		"tooling/semantic-release/*.d.mts",
 		"README.md"
@@ -142,6 +143,7 @@
 		},
 		"./tsup": "./tooling/tsup/index.ts",
 		"./biome": "./tooling/biome/biome.json",
+		"./typedoc": "./tooling/typedoc/typedoc.json",
 		"./semantic-release": {
 			"types": "./tooling/semantic-release/index.d.mts",
 			"import": "./tooling/semantic-release/index.mjs"

package/tooling/typedoc/typedoc.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "https://typedoc.org/schema.json",
+  "excludePrivate": true,
+  "excludeExternals": true,
+  "includeVersion": true,
+  "out": "docs"
+}