@rtorcato/repo-tooling 2.59.0

package/tooling/docusaurus/theme.css

@@ -0,0 +1,378 @@
+/**
+ * Shared @rtorcato Docusaurus component theme (shipped by @rtorcato/repo-tooling —
+ * copy via `repo-tooling copy docusaurus-theme`).
+ *
+ * The accent-agnostic component-override sheet every sibling docs site shares:
+ * navbar, doc cards, sidebar, TOC, pagination, footer, code blocks, markdown
+ * tables, buttons, and the hardened navy dark surfaces. Every rule references
+ * the `--jt-*` / `--ifm-*` tokens from `_jt-tokens.css` (see
+ * `copy docusaurus-theme-tokens`) — it defines NO accent colours.
+ *
+ * Usage in your `src/css/custom.css`:
+ *
+ *   @import "./_jt-tokens.css";   // shared design tokens
+ *   @import "./theme.css";        // this file — shared component styling
+ *   :root            { --ifm-color-primary: #YOURHEX; --jt-accent: #YOURHEX; ... }
+ *   [data-theme=dark]{ --ifm-color-primary: #YOURHEX; --jt-accent: #YOURHEX; ... }
+ *   ::selection      { background: rgba(R, G, B, 0.24); }  // accent — keep local
+ *
+ * The single-flat mobile drawer (the `.navbar-sidebar__items` transform lock +
+ * the repo-namespaced `.xx-mobile-menu` rules) is NOT here — it ships with the
+ * Navbar/MobileSidebar swizzle files, since its class prefix is per-repo.
+ */
+
+/* ---------- Navbar ---------- */
+.navbar {
+	border-bottom: 1px solid var(--jt-border);
+	box-shadow: none;
+}
+.navbar__link--active {
+	color: var(--jt-heading);
+}
+
+/* Configuration Reference / index cards (generated-index). Match the clean
+   "install box" look — near-page-bg fill + thin border instead of infima's dull
+   surface fill — with an accent-border hover. Full description (no one-line
+   `text--truncate` clamp) and equal card heights per row. */
+.theme-doc-card-container {
+	height: 100%;
+	background: var(--jt-code-bg);
+	border: 1px solid var(--jt-border);
+	border-radius: 14px;
+	box-shadow: none;
+	transition:
+		border-color 0.15s ease,
+		background 0.15s ease,
+		transform 0.15s ease;
+}
+.theme-doc-card-container:hover {
+	background: var(--jt-surface2);
+	border-color: var(--jt-accent-border);
+	transform: translateY(-2px);
+}
+.theme-doc-card-description.text--truncate {
+	white-space: normal;
+	overflow: visible;
+	text-overflow: unset;
+}
+
+/* ---------- Backgrounds ---------- */
+html,
+body,
+#__docusaurus,
+.main-wrapper {
+	background: var(--ifm-background-color);
+}
+/* Sidebar container: match page background, clean 1px right border, and
+   ensure a long sidebar list scrolls without clipping the page footer. The
+   sticky positioning + bounded height come from Infima defaults; the explicit
+   overflow rule here defends against any inner container with overflow: hidden. */
+.theme-doc-sidebar-container {
+	background: var(--ifm-background-color) !important;
+	border-right: 1px solid var(--jt-border) !important;
+}
+.theme-doc-sidebar-container > div,
+.theme-doc-sidebar-container nav,
+.theme-doc-sidebar-menu,
+.menu,
+.menu__list {
+	background: var(--ifm-background-color);
+}
+/* The sticky inner wrapper that holds the scrollable menu list. */
+.theme-doc-sidebar-container > div:first-child {
+	height: 100%;
+	overflow-y: auto;
+	overscroll-behavior: contain;
+}
+
+/* ---------- Sidebar ---------- */
+.menu {
+	font-size: 14px;
+	background: transparent;
+	padding: 16px 12px;
+}
+.menu__list .menu__list {
+	padding-left: 8px;
+}
+.menu__link {
+	border-radius: 8px;
+	color: var(--jt-muted);
+	line-height: 1.4;
+}
+.menu__link:hover {
+	background: var(--jt-surface2);
+	color: var(--jt-heading);
+}
+.menu__link--active:not(.menu__link--sublist) {
+	color: var(--jt-accent);
+	background: var(--jt-accent-soft);
+	font-weight: 600;
+}
+.menu__list-item-collapsible .menu__link {
+	font-weight: 600;
+	color: var(--jt-heading);
+	background: transparent;
+}
+.menu__list-item-collapsible .menu__link--active {
+	color: var(--jt-accent);
+	background: transparent;
+}
+.menu__list-item-collapsible:hover {
+	background: var(--jt-surface2);
+	border-radius: 8px;
+}
+.menu__caret:hover {
+	background: transparent;
+}
+
+/* ---------- Table of contents ---------- */
+.table-of-contents__link--active {
+	color: var(--jt-accent);
+	font-weight: 600;
+}
+.table-of-contents .table-of-contents__link:hover {
+	color: var(--jt-heading);
+}
+
+/* ---------- Pagination ---------- */
+.pagination-nav__link {
+	border: 1px solid var(--jt-border);
+	border-radius: 8px;
+	background: var(--jt-surface);
+}
+.pagination-nav__link:hover {
+	border-color: var(--jt-accent-border);
+	background: var(--jt-surface2);
+}
+
+/* ---------- Footer ---------- */
+.footer,
+.footer--dark {
+	--ifm-footer-background-color: var(--jt-bg2);
+	--ifm-footer-color: var(--jt-text);
+	--ifm-footer-link-color: var(--jt-text);
+	--ifm-footer-title-color: var(--jt-faint);
+	border-top: 1px solid var(--jt-border);
+}
+.footer__title {
+	font-size: 12px;
+	font-weight: 700;
+	letter-spacing: 0.08em;
+	text-transform: uppercase;
+	color: var(--jt-faint);
+}
+.footer__link-item {
+	color: var(--jt-text);
+}
+.footer__link-item:hover {
+	color: var(--jt-accent);
+	text-decoration: none;
+}
+.footer__copyright {
+	color: var(--jt-faint);
+	font-size: 13px;
+	text-align: left;
+}
+.footer__col {
+	font-size: 14px;
+}
+/* Hide the external-link "↗" SVG Docusaurus auto-appends to footer href links —
+   the design uses clean text labels only. The class is CSS-module hashed
+   (iconExternalLink_<hash>), so we target by attribute prefix. */
+.footer__link-item svg,
+.footer__link-item [class*="iconExternalLink"] {
+	display: none;
+}
+
+/* ---------- Code ----------
+   Prism is vsDark in both light & dark mode (to match the navy aesthetic),
+   so fenced code blocks must stay dark in BOTH themes — otherwise the pale
+   vsDark tokens wash out on a light background. Inline code (the `code` pills)
+   keeps the themed --ifm-code-background and stays readable. */
+code {
+	background: var(--jt-code-bg);
+	border: 1px solid var(--jt-border);
+	border-radius: 4px;
+	padding: 1px 6px;
+	font-size: var(--ifm-code-font-size);
+	font-family: var(--ifm-font-family-monospace);
+}
+.theme-code-block,
+div[class*="codeBlockContainer"],
+pre[class*="language-"] {
+	border: 1px solid var(--jt-border);
+	border-radius: 12px;
+	background: #0c111b !important;
+}
+.theme-code-block code,
+pre[class*="language-"] code {
+	background: transparent !important;
+	border: none !important;
+	color: #dfe5ee;
+}
+div[class*="codeBlockTitle"] {
+	background: #0a0e16 !important;
+	color: #94a1b4 !important;
+	border-bottom: 1px solid var(--jt-border);
+}
+[data-theme="light"] .theme-code-block,
+[data-theme="light"] div[class*="codeBlockContainer"],
+[data-theme="light"] pre[class*="language-"] {
+	border-color: rgba(12, 18, 28, 0.16);
+	box-shadow: 0 8px 24px -18px rgba(12, 18, 28, 0.5);
+}
+
+/* ---------- Markdown tables ----------
+   Rounded container, horizontal row dividers only (no heavy cell gridlines). */
+.markdown table,
+.theme-doc-markdown table,
+article table {
+	display: table;
+	width: 100%;
+	border-collapse: separate;
+	border-spacing: 0;
+	margin: 22px 0;
+	border: 1px solid var(--jt-border);
+	border-radius: 12px;
+	overflow: hidden;
+	font-size: 14px;
+}
+.markdown table thead,
+article table thead {
+	background: var(--jt-bg2);
+}
+.markdown table thead tr,
+article table thead tr {
+	border: none;
+	background: transparent;
+}
+.markdown table th,
+article table th {
+	text-align: left;
+	font-weight: 700;
+	font-size: 12px;
+	letter-spacing: 0.06em;
+	text-transform: uppercase;
+	color: var(--jt-faint);
+	border: none;
+	border-bottom: 1px solid var(--jt-border);
+	padding: 14px 18px;
+}
+.markdown table tbody tr,
+article table tbody tr {
+	background: transparent !important;
+	border: none;
+}
+.markdown table td,
+article table td {
+	border: none;
+	border-bottom: 1px solid var(--jt-border);
+	padding: 13px 18px;
+	vertical-align: middle;
+	color: var(--jt-text);
+}
+.markdown table tbody tr:last-child td,
+article table tbody tr:last-child td {
+	border-bottom: none;
+}
+.markdown table td:first-child,
+article table td:first-child {
+	font-weight: 600;
+	color: var(--jt-heading);
+	white-space: nowrap;
+}
+.markdown table td code,
+.markdown table th code,
+article table td code {
+	background: transparent !important;
+	border: none !important;
+	padding: 0 !important;
+	font-size: 13px;
+}
+.markdown table td:nth-child(2) code,
+article table td:nth-child(2) code {
+	color: var(--jt-accent);
+}
+.markdown table td:nth-child(3),
+article table td:nth-child(3) {
+	color: var(--jt-muted);
+	line-height: 1.9;
+}
+.markdown table td:nth-child(3) code,
+article table td:nth-child(3) code {
+	color: var(--jt-muted);
+}
+
+/* ---------- Buttons ---------- */
+.button--primary {
+	background: var(--jt-accent-fill);
+	border-color: var(--jt-accent-fill);
+	color: var(--jt-on-accent);
+	font-weight: 700;
+}
+.button--primary:hover {
+	background: var(--ifm-color-primary-light);
+	border-color: var(--ifm-color-primary-light);
+	color: var(--jt-on-accent);
+}
+.button--secondary {
+	background: transparent;
+	border-color: var(--jt-border2);
+	color: var(--jt-heading);
+}
+
+/* ============================================================
+   HARDENED DARK SURFACES
+   Infima's dark defaults are grey (#1b1b1d) and the footer is
+   slate. These explicit overrides force the navy palette even
+   if a default loads after this file.
+   ============================================================ */
+[data-theme="dark"] {
+	--ifm-background-color: #0a0e16;
+	--ifm-background-surface-color: #111824;
+	--ifm-navbar-background-color: #0a0e16;
+	--ifm-footer-background-color: #0b101a;
+}
+[data-theme="dark"],
+[data-theme="dark"] body,
+[data-theme="dark"] #__docusaurus,
+[data-theme="dark"] .main-wrapper,
+[data-theme="dark"] .navbar,
+[data-theme="dark"] main {
+	background-color: #0a0e16;
+}
+/* Footer follows the theme: soft grey panel in light mode, page-matching navy
+   in dark mode. Selectors are theme-scoped so the config's `style: 'dark'`
+   (which adds .footer--dark in BOTH modes) can't drag the light-mode footer
+   into a dark slate. */
+html[data-theme="light"] .footer,
+html[data-theme="light"] .footer--dark {
+	background-color: var(--jt-bg2) !important;
+	border-top: 1px solid var(--jt-border);
+}
+html[data-theme="light"] .footer__link-item {
+	color: var(--jt-text) !important;
+}
+html[data-theme="light"] .footer__title {
+	color: var(--jt-faint) !important;
+}
+html[data-theme="light"] .footer__copyright {
+	color: var(--jt-faint) !important;
+}
+html[data-theme="dark"] .footer,
+html[data-theme="dark"] .footer--dark {
+	background-color: #0a0e16 !important;
+	border-top: 1px solid var(--jt-border);
+}
+html[data-theme="dark"] .footer__link-item {
+	color: var(--jt-text) !important;
+}
+html[data-theme="dark"] .footer__title {
+	color: var(--jt-faint) !important;
+}
+html[data-theme="dark"] .footer__copyright {
+	color: var(--jt-faint) !important;
+}
+.footer__link-item:hover {
+	color: var(--jt-accent) !important;
+}

package/tooling/esbuild/index.d.mts

@@ -0,0 +1,6 @@
+import type { BuildOptions, BuildResult } from 'esbuild'
+
+export declare function buildCode(
+	entryPoints?: string[],
+	options?: Partial<BuildOptions>
+): Promise<BuildResult | undefined>

package/tooling/esbuild/index.mjs

@@ -0,0 +1,102 @@
+import * as fs from 'node:fs/promises'
+import * as path from 'node:path'
+import * as esbuild from 'esbuild'
+import { nodeExternalsPlugin } from 'esbuild-node-externals'
+
+// EXAMPLE ENTRY POINTS
+// const folders = await getEntrypointFolders('src')
+// 	const libEntryPointsArrays = await Promise.all(folders.map((folder) => getEntryPoints(folder)))
+// 	const libEntryPoints = libEntryPointsArrays.flat()
+// 	const allEntryPoints = [
+// 		'src/index.ts', // Main entry point
+// 		...libEntryPoints,
+// 		// ...exampleEntryPoints,
+// 	]
+
+export async function buildCode(entryPoints = []) {
+	const isProduction = process.env['NODE_ENV'] === 'production'
+	console.log(`Building...${isProduction ? '(production)' : '(development)'}`)
+	console.log('All entry points:', entryPoints)
+	if (entryPoints && entryPoints.length > 0) {
+		const buildPrefs = {
+			entryPoints: entryPoints, // Array of entry points to build
+			outdir: 'dist', // Output directory
+			platform: 'node', // Use 'browser' for browser builds
+			// outbase: 'src', // Base directory for output files
+			sourcemap: !isProduction, // Generate sourcemaps in development mode
+			minify: isProduction, // Minify in production mode
+			logLevel: 'info', // Set log level to 'info'
+			splitting: true, // Enable code splitting
+			format: 'esm', // Use 'cjs' as 'cjs' for CommonJS format
+			target: ['esnext'], // Specify ECMAScript target version
+			bundle: true, // Bundle all dependencies into the output
+			chunkNames: 'chunks/[name]-[hash]', // Define chunk naming pattern
+			// external: ['react', 'react-dom'], // Add other external dependencies here
+			// plugins: [
+			//   {
+			//     name: 'make-all-packages-external',
+			//     setup(build) {
+			//       let filter = /^[^.\/]|^\.[^.\/]|^\.\.[^\/]/; // Must not start with "/" or "./" or "../"
+			//       build.onResolve({ filter }, args => ({ path: args.path, external: true }));
+			//     },
+			//   },
+			// ],
+			plugins: [nodeExternalsPlugin()],
+		}
+		await esbuild.build(buildPrefs)
+	} else {
+		console.log('No entry points provided. Skipping build.')
+	}
+}
+/**
+ * Returns a list of entry point files in a directory.
+ *
+ * Scans the given directory and returns all files that:
+ *   - End with the specified file extension (default: ".ts")
+ *   - Are not test files (by default, excludes files containing ".test.")
+ *
+ * @param {string} dir - The directory to search (e.g., 'src')
+ * @param {string} [fileExtension='.ts'] - The file extension to match (e.g., '.ts', '.tsx')
+ * @param {boolean} [excludeTestFiles=true] - Whether to exclude test files (files containing '.test.')
+ * @returns {Promise<string[]>} - Array of entry point file paths (e.g., ['src/arrays/index.ts', ...])
+ */
+export async function getEntryPoints(dir, fileExtension = '.ts', excludeTestFiles = true) {
+	try {
+		const entries = await fs.readdir(dir, { withFileTypes: true })
+		return entries
+			.filter(
+				(entry) =>
+					entry.isFile() &&
+					entry.name.endsWith(fileExtension) &&
+					(!excludeTestFiles || !entry.name.includes('.test.'))
+			)
+			.map((entry) => path.join(dir, entry.name))
+	} catch (error) {
+		// @ts-expect-error
+		if (error.code === 'ENOENT') {
+			console.warn(`Directory ${dir} does not exist.`)
+			return []
+		}
+		throw error
+	}
+}
+/**
+ * Returns a list of all subdirectories in the given directory that contain an index.ts file.
+ * @param {string} dir - The directory to search (e.g., 'src')
+ * @returns {Promise<string[]>} - Array of entrypoint folder paths (e.g., ['src/arrays', 'src/strings'])
+ */
+export async function getEntrypointFolders(dir) {
+	const entries = await fs.readdir(dir, { withFileTypes: true })
+	const folders = entries.filter((e) => e.isDirectory())
+	const entryFolders = []
+	for (const folder of folders) {
+		const indexPath = path.join(dir, folder.name, 'index.ts')
+		try {
+			await fs.access(indexPath)
+			entryFolders.push(path.join(dir, folder.name))
+		} catch {
+			// index.ts does not exist, skip
+		}
+	}
+	return entryFolders
+}

package/tooling/eslint/base.d.mts

@@ -0,0 +1,6 @@
+import type { Linter } from 'eslint'
+
+declare const config: Linter.Config[]
+export default config
+
+export declare const restrictEnvAccess: Linter.Config[]

package/tooling/eslint/base.mjs

@@ -0,0 +1,122 @@
+/// <reference types="./types.d.ts" />
+
+import eslint from '@eslint/js'
+import tsPlugin from '@typescript-eslint/eslint-plugin'
+import importPlugin from 'eslint-plugin-import'
+import jestPlugin from 'eslint-plugin-jest'
+import tseslint from 'typescript-eslint'
+
+// import path from 'path';
+// import url from 'url';
+
+// const __filename = url.fileURLToPath(import.meta.url);
+// const __dirname = path.dirname(__filename);
+
+/**
+ * All packages that leverage t3-env should use this rule
+ */
+export const restrictEnvAccess = tseslint.config({
+	files: ['**/*.js', '**/*.ts', '**/*.tsx'],
+	rules: {
+		'no-restricted-properties': [
+			'error',
+			{
+				object: 'process',
+				property: 'env',
+				message: "Use `import { env } from '~/env'` instead to ensure validated types.",
+			},
+		],
+		'no-restricted-imports': [
+			'error',
+			{
+				name: 'process',
+				importNames: ['env'],
+				message: "Use `import { env } from '~/env'` instead to ensure validated types.",
+			},
+		],
+	},
+})
+
+export default tseslint.config(
+	{
+		// Globally ignored files
+		ignores: [
+			//
+			'**/*.config.js',
+			'.turbo',
+			'dist',
+			'build',
+			'.react-email',
+			'not-used',
+			'out', //for next js static builds
+			'.next',
+			'pnpm-lock.yaml',
+			'node_modules',
+			'.react-email',
+		],
+	},
+	{
+		files: ['**/*.js', '**/*.ts', '**/*.tsx'],
+		plugins: {
+			import: importPlugin,
+			'@typescript-eslint': tsPlugin,
+			jest: jestPlugin,
+		},
+		extends: [
+			//
+			eslint.configs.recommended,
+			...tseslint.configs.recommended,
+			...tseslint.configs.recommendedTypeChecked,
+			...tseslint.configs.stylisticTypeChecked,
+			// ...jestPlugin.configs['flat/recommended'],
+			// turbo,
+			// vitest,
+			// airbnb,
+			// "eslint:recommended",
+			// 'airbnb-typescript',
+			// 'plugin:jest/recommended',
+			//"plugin:prettier/recommended", // Enables eslint-plugin-prettier and eslint-config-prettier. This will display prettier errors as ESLint errors. Make sure this is always the last configuration in the extends array.
+			// eslintConfigPrettier,
+		],
+		rules: {
+			'no-console': 'warn',
+			'@typescript-eslint/no-unsafe-assignment': 'error',
+			'@typescript-eslint/no-explicit-any': 'off',
+			'@typescript-eslint/consistent-type-definitions': 'off',
+			'tailwindcss/no-custom-classname': 'off',
+			'@typescript-eslint/no-unsafe-return': 'off',
+			'@typescript-eslint/no-unsafe-call': 'off',
+			'@typescript-eslint/no-unsafe-member-access': 'off',
+			//   "jest/no-disabled-tests": "warn",
+			// "jest/no-focused-tests": "error",
+			// "jest/no-identical-title": "error",
+			// "jest/prefer-to-have-length": "warn",
+			// "jest/valid-expect": "error"
+			//
+			'@typescript-eslint/no-unused-vars': [
+				'error',
+				{ argsIgnorePattern: '^_', varsIgnorePattern: '^_' },
+			],
+			'@typescript-eslint/consistent-type-imports': [
+				'warn',
+				{ prefer: 'type-imports', fixStyle: 'separate-type-imports' },
+			],
+			'@typescript-eslint/no-misused-promises': [2, { checksVoidReturn: { attributes: false } }],
+			'@typescript-eslint/no-unnecessary-condition': [
+				'error',
+				{
+					allowConstantLoopConditions: true,
+				},
+			],
+			'@typescript-eslint/no-non-null-assertion': 'error',
+			'import/consistent-type-specifier-style': ['error', 'prefer-top-level'],
+		},
+	},
+	{
+		linterOptions: { reportUnusedDisableDirectives: true },
+		// languageOptions: { parserOptions: { project: ['./tsconfig.json', './**/*/tsconfig.json'] } },
+		languageOptions: {
+			parserOptions: { project: true }, //, tsconfigRootDir: __dirname
+		},
+	}
+)

package/tooling/eslint/nextjs.d.mts

@@ -0,0 +1,4 @@
+import type { Linter } from 'eslint'
+
+declare const config: Linter.Config[]
+export default config

package/tooling/eslint/nextjs.mjs

@@ -0,0 +1,22 @@
+import nextPlugin from '@next/eslint-plugin-next'
+
+/** @type {Awaited<import('typescript-eslint').Config>} */
+export default [
+	{
+		files: ['**/*.ts', '**/*.tsx'],
+		plugins: {
+			'@next/next': nextPlugin,
+		},
+		rules: {
+			...nextPlugin.configs.recommended.rules,
+			...nextPlugin.configs['core-web-vitals'].rules,
+			// TypeError: context.getAncestors is not a function
+			'@next/next/no-duplicate-head': 'off',
+			'@next/next/no-page-custom-font': 'off',
+			//
+			'@next/next/no-img-element': 'off',
+			'@next/next/no-html-link-for-pages': 'off',
+			'react/jsx-key': 'off',
+		},
+	},
+]

package/tooling/eslint/types.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Since the ecosystem hasn't fully migrated to ESLint's new FlatConfig system yet,
+ * we "need" to type some of the plugins manually :(
+ */
+
+declare module '@eslint/js' {
+	// Why the hell doesn't eslint themselves export their types?
+	import type { Linter } from 'eslint'
+
+	export const configs: {
+		readonly recommended: { readonly rules: Readonly<Linter.RulesRecord> }
+		readonly all: { readonly rules: Readonly<Linter.RulesRecord> }
+	}
+}
+
+declare module 'eslint-plugin-import' {
+	import type { Linter, Rule } from 'eslint'
+
+	export const configs: {
+		recommended: { rules: Linter.RulesRecord }
+	}
+	export const rules: Record<string, Rule.RuleModule>
+}
+
+declare module 'eslint-plugin-react' {
+	import type { Linter, Rule } from 'eslint'
+
+	export const configs: {
+		recommended: { rules: Linter.RulesRecord }
+		all: { rules: Linter.RulesRecord }
+		'jsx-runtime': { rules: Linter.RulesRecord }
+	}
+	export const rules: Record<string, Rule.RuleModule>
+}
+
+declare module 'eslint-plugin-react-hooks' {
+	import type { Linter, Rule } from 'eslint'
+
+	export const configs: {
+		recommended: {
+			rules: {
+				'rules-of-hooks': Linter.RuleEntry
+				'exhaustive-deps': Linter.RuleEntry
+			}
+		}
+	}
+	export const rules: Record<string, Rule.RuleModule>
+}
+
+declare module '@next/eslint-plugin-next' {
+	import type { Linter, Rule } from 'eslint'
+
+	export const configs: {
+		recommended: { rules: Linter.RulesRecord }
+		'core-web-vitals': { rules: Linter.RulesRecord }
+	}
+	export const rules: Record<string, Rule.RuleModule>
+}