@rtorcato/js-tooling 2.15.0 → 2.17.0

package/dist/cli/commands/doctor.js

@@ -596,6 +596,114 @@ 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;
+    return !!(pkg.exports || pkg.main || pkg.module || pkg.files);
+}
+async function checkAreTheTypesWrong(_dir, pkg) {
+    if (!isPublishableLibrary(pkg)) {
+        return {
+            check: 'are-the-types-wrong',
+            status: 'ok',
+            detail: 'not applicable (private or no published exports)',
+        };
+    }
+    const deps = {
+        ...(pkg?.dependencies ?? {}),
+        ...(pkg?.devDependencies ?? {}),
+    };
+    const scripts = pkg?.scripts ?? {};
+    const hasDep = !!deps['are-the-types-wrong'];
+    const hasScript = Object.values(scripts).some((s) => /\battw\b|are-the-types-wrong/.test(s));
+    if (hasDep && hasScript) {
+        return {
+            check: 'are-the-types-wrong',
+            status: 'ok',
+            detail: 'are-the-types-wrong installed and wired into a script',
+        };
+    }
+    if (hasDep) {
+        return {
+            check: 'are-the-types-wrong',
+            status: 'drift',
+            detail: 'are-the-types-wrong installed but no script runs it',
+            hint: 'Add `"attw": "attw --pack"` to package.json scripts and call it from your verify/CI chain',
+        };
+    }
+    return {
+        check: 'are-the-types-wrong',
+        status: 'optional-missing',
+        detail: 'are-the-types-wrong not configured',
+        hint: 'Run `pnpm add -D are-the-types-wrong && attw --pack` to validate TypeScript exports before publishing',
+    };
+}
 async function checkTreeshakeSetup(dir, pkg) {
     const appCheckPath = path.join(dir, 'apps', 'treeshake-check', 'check.mjs');
     if (await fs.pathExists(appCheckPath)) {
@@ -706,6 +814,8 @@ 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
     // check that's currently optional-missing, demote it to ok with a clear detail.

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

@@ -24,6 +24,8 @@ export const FIX_TARGETS = {
     'GitLab CI': 'gitlab-ci',
     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.15.0",
+	"version": "2.17.0",
 	"description": "JavaScript and TypeScript tooling for Node.js, React, Next.js, and Vitest.",
 	"type": "module",
 	"keywords": [
@@ -52,6 +52,7 @@
 		"tooling/prettier/index.mjs",
 		"tooling/prettier/index.d.mts",
 		"tooling/typescript/*.json",
+		"tooling/typescript/v1/*.json",
 		"tooling/typescript/reset.d.ts",
 		"tooling/vite/vite.config.mjs",
 		"tooling/vite/vite.config.d.mts",
@@ -69,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"
@@ -113,6 +115,12 @@
 		"./typescript/react": "./tooling/typescript/tsconfig.react.json",
 		"./typescript/test": "./tooling/typescript/tsconfig.test.json",
 		"./typescript/reset": "./tooling/typescript/reset.d.ts",
+		"./typescript/base@1": "./tooling/typescript/v1/tsconfig.base.json",
+		"./typescript/next@1": "./tooling/typescript/v1/tsconfig.next.json",
+		"./typescript/express@1": "./tooling/typescript/v1/tsconfig.express.json",
+		"./typescript/node@1": "./tooling/typescript/v1/tsconfig.node.json",
+		"./typescript/react@1": "./tooling/typescript/v1/tsconfig.react.json",
+		"./typescript/test@1": "./tooling/typescript/v1/tsconfig.test.json",
 		"./vite": {
 			"types": "./tooling/vite/vite.config.d.mts",
 			"import": "./tooling/vite/vite.config.mjs"
@@ -135,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"
+}

package/tooling/typescript/v1/tsconfig.base.json

@@ -0,0 +1,77 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "compilerOptions": {
+    // 🔧 Output & Module Resolution
+    "moduleResolution": "bundler",
+    "module": "esnext",
+    "target": "esnext",
+    // "module": "esnext", //
+    // "moduleResolution": "node", // Prefer "bundler" if you're using Vite, esbuild, etc.
+    // "target": "esnext", //
+    "lib": ["ES2022"], // Specify library files to be included in the compilation
+    "rootDir": "src",
+    "outDir": "dist",
+
+
+    // 🔍 JavaScript Support
+    "allowJs": true, // Allow JavaScript files to be compiled
+    "checkJs": true, // Enable type checking on JavaScript files
+    "resolveJsonModule": true,  // Allow importing JSON files
+    "isolatedModules": true, // Ensure that each file can be safely transpiled independently
+    "esModuleInterop": true, // Enables emit interoperability between CommonJS and ES Modules
+    "allowSyntheticDefaultImports": true, // recommend enabling this for smoother interop
+
+    // ⚙️ Module Detection
+    "moduleDetection": "force", // Force module detection
+
+    // 📈 Performance
+    "skipLibCheck": true, // Skip type checking of declaration files
+    "incremental": true, // Enable incremental compilation
+    "disableSourceOfProjectReferenceRedirect": true, // Disable source of project reference redirect
+
+    // 🚨 Strict Type Checking
+    "strict": true, // Enable all strict type checking options
+    "noUncheckedIndexedAccess": true, // Disallow accessing an index signature with an arbitrary key
+    "noImplicitAny": true, // Disallow implicit any type
+    "noImplicitReturns": true, // Disallow functions that do not return a value
+    "noImplicitOverride": true, // Ensure override keyword is used
+    "noImplicitThis": true, // Disallow 'this' with an implicit any type
+    "noPropertyAccessFromIndexSignature": true, // Disallow property access from index signature
+
+    // 🧹 Lint-Like Settings
+    "noUnusedLocals": true, // Disallow unused locals
+    "noUnusedParameters": true, // Disallow unused parameters
+    "noFallthroughCasesInSwitch": true, // Disallow fallthrough cases in switch statements
+
+    // 📦 Types & Declarations
+    "types": ["node", "vitest"], // Specify type declaration files to be included in the compilation
+    "declaration": false, // Do not generate .d.ts files
+    "declarationMap": false, // Do not generate sourcemaps for d.ts files
+
+    // 🛑 Emit Settings
+    "noEmit": true, // Do not emit output files
+    "sourceMap": true, // Generate sourcemaps for .ts files
+
+    "paths": { // Path mapping for module resolution
+      "~/*": ["./src/*"],
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["src/**/*", "index.d.ts"], // Include files in the src directory and index.d.ts
+  "exclude": [
+    "node_modules",
+    "build",
+    "dist",
+    ".next",
+    ".expo",
+    "OLD",
+    "**/*.test.ts",
+    "**/*.test.tsx",
+    "**/*.spec.ts",
+    "**/*.spec.tsx",
+    ".turbo",
+    "out",
+    "not-used",
+    "vitest.config.ts"
+  ] // Exclude directories from compilation
+}

package/tooling/typescript/v1/tsconfig.express.json

@@ -0,0 +1,9 @@
+{
+  "extends": "./tsconfig.base.json",
+  "compilerOptions": {
+    "lib": ["ES2022"], // Only include ES libs, no DOM
+    "types": ["node", "express", "vitest"], // Add express types for API development
+  },
+  "include": ["src", "index.d.ts"],
+  "exclude": ["node_modules", "dist", "build", "test", "**/*.test.ts", "**/*.spec.ts"]
+}

package/tooling/typescript/v1/tsconfig.next.json

@@ -0,0 +1,19 @@
+{
+  "extends": "./tsconfig.base.json",
+  "compilerOptions": {
+    "jsx": "preserve", // Let Next.js handle JSX transformation
+    "lib": ["DOM", "DOM.Iterable", "ESNext"], // Include DOM types for browser APIs
+    "module": "esnext", // Next.js expects ESNext modules
+    "moduleResolution": "bundler", // Modern module resolution for Next.js
+    "allowJs": true, // Allow JavaScript files
+    "esModuleInterop": true, // Interop for CommonJS/ESM
+    "types": ["react", "tailwindcss", "vitest"],
+    "plugins": [ { "name": "next" } ], // Next.js plugin for TypeScript
+    "paths": {
+      "~/*": ["./src/*"],
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["next-env.d.ts", "src", "pages", "app", "components", "types", "index.d.ts"],
+  "exclude": ["node_modules", "dist", ".next", "build", "out"]
+}

package/tooling/typescript/v1/tsconfig.node.json

@@ -0,0 +1,9 @@
+{
+  "extends": "./tsconfig.base.json",
+  "compilerOptions": {
+    "lib": ["ES2022"],
+    "types": ["node", "vitest"]
+  },
+  "include": ["src", "index.d.ts"],
+  "exclude": ["node_modules", "dist", "build", "test", "**/*.test.ts", "**/*.spec.ts"]
+}

package/tooling/typescript/v1/tsconfig.react.json

@@ -0,0 +1,14 @@
+{
+  "extends": "./tsconfig.base.json",
+  "compilerOptions": {
+    "jsx": "react-jsx", // Use the new JSX transform for React 17+
+    "lib": ["DOM", "DOM.Iterable", "ESNext"],// Include DOM types for browser APIs
+    "types": ["react", "react-dom", "tailwindcss", "vitest"],
+    "paths": {
+      "~/*": ["./src/*"],
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["src", "index.d.ts", "types"],
+  "exclude": ["node_modules", "dist", "build", "out", "**/*.test.ts", "**/*.spec.ts"]
+}

package/tooling/typescript/v1/tsconfig.test.json

@@ -0,0 +1,8 @@
+{
+  "extends": "./tsconfig.base.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "types": ["node", "vitest"]
+  },
+  "include": ["src", "tests", "**/*.test.ts", "**/*.test.tsx", "**/*.spec.ts", "**/*.spec.tsx"]
+}