ts-repo-utils 1.0.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,3 @@
+# ts-repo-utils
+
+Utilities for TypeScript Repositories.

package/package.json

@@ -0,0 +1,97 @@
+{
+  "name": "ts-repo-utils",
+  "version": "1.0.0",
+  "private": false,
+  "keywords": [
+    "typescript"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/noshiro-pf/ts-repo-utils.git"
+  },
+  "license": "Apache-2.0",
+  "author": "noshiro-pf <noshiro.pf@gmail.com>",
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      }
+    }
+  },
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "src",
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "npm run z:node-eval -- \"import { build } from './scripts/functions/build.mjs'; build();\"",
+    "check-all": "npm run z:node-esm -- ./scripts/cmd/check-all.mjs",
+    "check:ext": "npm run z:node-esm -- ./scripts/cmd/check-ext.mjs",
+    "cspell": "cspell \"**\" --gitignore --gitignore-root ./ --no-progress",
+    "doc": "npm run z:node-eval -- \"import { genDocs } from './scripts/functions/gen-docs.mjs'; genDocs();\"",
+    "fmt": "prettier --write .",
+    "gi": "npm run z:node-esm -- ./scripts/cmd/gi.mjs",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "md": "markdownlint-cli2",
+    "test": "npm run z:vitest -- run",
+    "test:cov": "npm run z:vitest -- run --coverage",
+    "test:cov:ui": "vite preview --outDir ./coverage",
+    "test:ui": "npm run z:vitest -- --ui",
+    "testw": "npm run z:vitest -- watch",
+    "tsc": "tsc --noEmit",
+    "tscw": "tsc --noEmit --watch",
+    "type-check": "tsc --noEmit",
+    "update-packages": "npx npm-check-updates -u --install always --reject @types/node",
+    "z:node-esm": "node --import tsx/esm",
+    "z:node-eval": "npm run z:node-esm -- --input-type=module --eval",
+    "z:vitest": "vitest --config ./configs/vitest.config.ts"
+  },
+  "dependencies": {
+    "@types/micromatch": "^4.0.9",
+    "fast-glob": "^3.3.3",
+    "micromatch": "^4.0.8",
+    "prettier": "^3.5.3"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.29.0",
+    "@rollup/plugin-replace": "^6.0.2",
+    "@rollup/plugin-strip": "^3.0.4",
+    "@rollup/plugin-typescript": "^12.1.2",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/commit-analyzer": "^13.0.1",
+    "@semantic-release/exec": "^7.1.0",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^11.0.3",
+    "@semantic-release/npm": "^12.0.1",
+    "@semantic-release/release-notes-generator": "^14.0.3",
+    "@types/node": "^20.19.0",
+    "@vitest/coverage-v8": "^3.2.3",
+    "@vitest/ui": "^3.2.3",
+    "conventional-changelog-conventionalcommits": "^9.0.0",
+    "cspell": "^9.1.1",
+    "dedent": "^1.6.0",
+    "eslint": "^9.29.0",
+    "markdownlint-cli2": "^0.18.1",
+    "prettier-plugin-organize-imports": "^4.1.0",
+    "prettier-plugin-packagejson": "^2.5.15",
+    "rollup": "^4.43.0",
+    "semantic-release": "^24.2.5",
+    "ts-type-forge": "^2.0.3",
+    "tsx": "^4.20.3",
+    "typedoc": "^0.28.5",
+    "typedoc-plugin-markdown": "^4.6.4",
+    "typescript": "^5.8.3",
+    "typescript-eslint": "^8.34.0",
+    "vitest": "^3.2.3"
+  },
+  "engines": {
+    "node": ">=20.11.0"
+  }
+}

package/src/functions/assert-ext.mts

@@ -0,0 +1,112 @@
+import '../node-global.mjs';
+import { assertPathExists } from './assert-path-exists.mjs';
+
+/**
+ * Configuration for directory extension checking.
+ */
+export type CheckExtConfig = DeepReadonly<{
+  /** Array of directory paths and their expected extensions */
+  directories: {
+    /** Directory path to check */
+    path: string;
+    /** Expected file extension (including the dot) */
+    extension: string;
+    /** Optional glob patterns to ignore (defaults to ['tsconfig.json', 'globals.d.*']) */
+    ignorePatterns?: string[];
+  }[];
+}>;
+
+/**
+ * Validates that all files in specified directories have the correct extensions.
+ * @param config - Configuration specifying directories and expected extensions.
+ * @throws Error with details of all incorrect files found.
+ */
+export const assertExt = async (config: CheckExtConfig): Promise<void> => {
+  const allIncorrectFiles: string[] = [];
+
+  // Check all directories in parallel
+  const results = await Promise.all(
+    config.directories.map(async ({ path: dir, extension, ignorePatterns }) => {
+      try {
+        return await getFilesWithIncorrectExtension(
+          dir,
+          extension,
+          ignorePatterns,
+        );
+      } catch (error) {
+        console.error(`Failed to check directory ${dir}: ${String(error)}`);
+        return [];
+      }
+    }),
+  );
+
+  // Collect all incorrect files
+  results.forEach((incorrectFiles) => {
+    allIncorrectFiles.push(...incorrectFiles);
+  });
+
+  if (allIncorrectFiles.length > 0) {
+    const generateErrorMessage = (): string => {
+      // Group directories by extension for a cleaner message
+      const extensionGroups = new Map<string, string[]>();
+
+      for (const { path: dirPath, extension } of config.directories) {
+        const relativePath = path.relative(process.cwd(), dirPath);
+        if (!extensionGroups.has(extension)) {
+          extensionGroups.set(extension, []);
+        }
+        extensionGroups.get(extension)?.push(relativePath);
+      }
+
+      // Generate message parts for each extension
+      const messageParts = Array.from(extensionGroups.entries()).map(
+        ([ext, dirs]) => {
+          const dirList = dirs.length === 1 ? dirs[0] : dirs.join(', ');
+          return `${dirList} should have ${ext} extension`;
+        },
+      );
+
+      return `All files in ${messageParts.join(' and ')}.`;
+    };
+
+    const errorMessage = [
+      'Files with incorrect extensions found:',
+      ...allIncorrectFiles.map((file) => `  - ${file}`),
+      '',
+      generateErrorMessage(),
+    ].join('\n');
+
+    throw new Error(errorMessage);
+  }
+
+  echo('✓ All files have correct extensions');
+};
+
+/**
+ * Checks if all files in a directory have the expected extension.
+ * @param dir - The directory to check.
+ * @param expectedExtension - The expected file extension.
+ * @param ignorePatterns - Optional glob patterns to ignore.
+ * @returns Array of files with incorrect extensions.
+ */
+const getFilesWithIncorrectExtension = async (
+  dir: string,
+  expectedExtension: string,
+  ignorePatterns?: readonly string[],
+): Promise<string[]> => {
+  await assertPathExists(dir, 'Directory');
+
+  const defaultIgnorePatterns = ['tsconfig.json', 'globals.d.*'];
+  const finalIgnorePatterns = ignorePatterns ?? defaultIgnorePatterns;
+
+  // Convert relative patterns to absolute paths for the glob ignore option
+  const absoluteIgnorePatterns = finalIgnorePatterns.map((pattern) =>
+    path.isAbsolute(pattern) ? pattern : `${dir}/${pattern}`,
+  );
+
+  const files = await glob(`${dir}/**/*`, {
+    ignore: absoluteIgnorePatterns,
+  });
+
+  return files.filter((file) => !file.endsWith(expectedExtension));
+};

package/src/functions/assert-path-exists.mts

@@ -0,0 +1,30 @@
+import * as fs from 'node:fs/promises';
+
+/**
+ * Checks if a file or directory exists.
+ * @param filePath - The path to check.
+ * @returns True if the path exists.
+ */
+export const pathExists = async (filePath: string): Promise<boolean> => {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * Validates that a path exists and throws if it doesn't.
+ * @param filePath - The path to validate.
+ * @param description - Description for error message.
+ * @throws Error if path doesn't exist.
+ */
+export const assertPathExists = async (
+  filePath: string,
+  description = 'Path',
+): Promise<void> => {
+  if (!(await pathExists(filePath))) {
+    throw new Error(`${description} does not exist: ${filePath}`);
+  }
+};

package/src/functions/assert-repo-is-dirty.mts

@@ -0,0 +1,66 @@
+import '../node-global.mjs';
+
+/**
+ * Checks if the repository has uncommitted changes.
+ * @returns True if the repo is dirty, false otherwise.
+ * @throws Error if git command fails.
+ */
+export const repoIsDirty = async (): Promise<boolean> => {
+  const status = await getGitStatus();
+  return status.isDirty;
+};
+
+/**
+ * Checks if the repository is dirty and exits with code 1 if it is.
+ * @throws Error if git command fails.
+ */
+export const assertRepoIsDirty = async (): Promise<void> => {
+  try {
+    const status = await getGitStatus();
+
+    if (!status.isDirty) {
+      echo('Repo is clean\n');
+      return;
+    }
+
+    echo('Repo is dirty\n');
+    echo('Changed files:\n');
+    echo(status.stdout);
+
+    // Show files not tracked by git and unstaged changes
+    const addResult = await $('git add -N .');
+    if (addResult.type === 'error') {
+      echo('Warning: Failed to add untracked files for diff\n');
+    }
+
+    const diffResult = await $('git diff');
+    if (diffResult.type === 'error') {
+      echo('Warning: Failed to show diff\n');
+    }
+
+    process.exit(1);
+  } catch (error) {
+    echo(`Error checking repository status: ${String(error)}\n`);
+    process.exit(1);
+  }
+};
+
+/**
+ * Gets the git status of the repository.
+ * @returns An object containing status information.
+ */
+const getGitStatus = async (): Promise<{
+  isDirty: boolean;
+  stdout: string;
+}> => {
+  const res = await $('git status --porcelain');
+
+  if (res.type === 'error') {
+    throw new Error(`Failed to get git status: ${res.exception.message}`);
+  }
+
+  return {
+    isDirty: res.stdout.trim() !== '',
+    stdout: res.stdout,
+  };
+};

package/src/functions/exec-async.mts

@@ -0,0 +1,44 @@
+import { exec, type ExecException } from 'node:child_process';
+
+export type ExecResult = Readonly<
+  | { type: 'ok'; stdout: string; stderr: string }
+  | { type: 'error'; exception: ExecException }
+>;
+
+/**
+ * Executes a shell command asynchronously.
+ * @param cmd - The command to execute.
+ * @param options - Optional configuration for command execution.
+ * @returns A promise that resolves with the command result.
+ */
+export const $ = (
+  cmd: string,
+  options: Readonly<{ silent?: boolean; timeout?: number }> = {},
+): Promise<ExecResult> => {
+  const { silent = false, timeout = 30000 } = options;
+
+  if (!silent) {
+    console.log(`$ ${cmd}`);
+  }
+
+  return new Promise((resolve) => {
+    const execOptions = { timeout };
+
+    exec(cmd, execOptions, (error, stdout, stderr) => {
+      if (!silent) {
+        if (stdout !== '') {
+          console.log(stdout);
+        }
+        if (stderr !== '') {
+          console.error(stderr);
+        }
+      }
+
+      if (error !== null) {
+        resolve({ type: 'error', exception: error });
+      } else {
+        resolve({ type: 'ok', stdout, stderr });
+      }
+    });
+  });
+};

package/src/functions/format.mts

@@ -0,0 +1,241 @@
+import glob from 'fast-glob';
+import { exec } from 'node:child_process';
+import { readFile, writeFile } from 'node:fs/promises';
+import { promisify } from 'node:util';
+import * as prettier from 'prettier';
+
+const execAsync = promisify(exec);
+
+/**
+ * Format files matching the given glob pattern using Prettier
+ * @param pathGlob - Glob pattern to match files
+ * @returns 'ok' if successful, 'err' if any errors occurred
+ */
+export const formatFiles = async (pathGlob: string): Promise<'ok' | 'err'> => {
+  try {
+    // Find all files matching the glob
+    const files = await glob(pathGlob, {
+      absolute: true,
+      ignore: ['**/node_modules/**', '**/.git/**'],
+      dot: true,
+    });
+
+    if (files.length === 0) {
+      console.log('No files found matching pattern:', pathGlob);
+      return 'ok';
+    }
+
+    console.log(`Formatting ${files.length} files...`);
+
+    // Format each file
+    const results = await Promise.allSettled(
+      files.map(async (filePath) => {
+        try {
+          // Read file content
+          const content = await readFile(filePath, 'utf8');
+
+          // Resolve prettier config for this file
+          const options = await prettier.resolveConfig(filePath);
+
+          // Check if file is ignored by prettier
+          const fileInfo = await prettier.getFileInfo(filePath, {
+            ignorePath: '.prettierignore',
+          });
+
+          if (fileInfo.ignored) {
+            console.log(`Skipping ignored file: ${filePath}`);
+            return;
+          }
+
+          // Format the content
+          const formatted = await prettier.format(content, {
+            ...options,
+            filepath: filePath,
+          });
+
+          // Only write if content changed
+          if (formatted !== content) {
+            await writeFile(filePath, formatted, 'utf8');
+            console.log(`Formatted: ${filePath}`);
+          }
+        } catch (error) {
+          console.error(`Error formatting ${filePath}:`, error);
+          throw error;
+        }
+      }),
+    );
+
+    // Check if any formatting failed
+    const hasErrors = results.some((result) => result.status === 'rejected');
+    return hasErrors ? 'err' : 'ok';
+  } catch (error) {
+    console.error('Error in formatFiles:', error);
+    return 'err';
+  }
+};
+
+/**
+ * Format only files that have been changed (git status)
+ * @returns 'ok' if successful, 'err' if any errors occurred
+ */
+export const formatChanged = async (): Promise<'ok' | 'err'> => {
+  try {
+    // Get changed files from git status
+    const { stdout, stderr } = await execAsync('git status --porcelain');
+
+    if (stderr !== '') {
+      console.error('Git error:', stderr);
+      return 'err';
+    }
+
+    // Parse git status output
+    const files = stdout
+      .split('\n')
+      .filter((line) => line.trim() !== '')
+      .map((line) => {
+        // Status format: "XY filename" where X and Y are status codes
+        const match = /^..\s+(.+)$/u.exec(line);
+        return match?.[1];
+      })
+      .filter(
+        (file): file is string =>
+          // Filter out deleted files (status starts with 'D')
+          file !== undefined && !stdout.includes(`D  ${file}`),
+      );
+
+    if (files.length === 0) {
+      console.log('No changed files to format');
+      return 'ok';
+    }
+
+    console.log('Formatting changed files:', files);
+
+    // Format each changed file
+    const results = await Promise.allSettled(
+      files.map(async (filePath) => {
+        try {
+          // Check if file exists and is not deleted
+          const content = await readFile(filePath, 'utf8').catch(() => null);
+          if (content === null) {
+            console.log(`Skipping non-existent file: ${filePath}`);
+            return;
+          }
+
+          // Resolve prettier config for this file
+          const options = await prettier.resolveConfig(filePath);
+
+          // Check if file is ignored by prettier
+          const fileInfo = await prettier.getFileInfo(filePath, {
+            ignorePath: '.prettierignore',
+          });
+
+          if (fileInfo.ignored) {
+            console.log(`Skipping ignored file: ${filePath}`);
+            return;
+          }
+
+          // Format the content
+          const formatted = await prettier.format(content, {
+            ...options,
+            filepath: filePath,
+          });
+
+          // Only write if content changed
+          if (formatted !== content) {
+            await writeFile(filePath, formatted, 'utf8');
+            console.log(`Formatted: ${filePath}`);
+          }
+        } catch (error) {
+          console.error(`Error formatting ${filePath}:`, error);
+          throw error;
+        }
+      }),
+    );
+
+    // Check if any formatting failed
+    const hasErrors = results.some((result) => result.status === 'rejected');
+    return hasErrors ? 'err' : 'ok';
+  } catch (error) {
+    console.error('Error in formatChanged:', error);
+    return 'err';
+  }
+};
+
+/**
+ * Format only files that differ from the specified base branch or commit
+ * @param base - Base branch name or commit hash to compare against (defaults to 'main')
+ * @returns 'ok' if successful, 'err' if any errors occurred
+ */
+export const formatDiffFrom = async (
+  base: string = 'main',
+): Promise<'ok' | 'err'> => {
+  try {
+    // Get files that differ from base branch/commit (excluding deleted files)
+    const { stdout, stderr } = await execAsync(
+      `git diff --name-only ${base} --diff-filter=d`,
+    );
+
+    if (stderr !== '') {
+      console.error('Git error:', stderr);
+      return 'err';
+    }
+
+    // Parse git diff output
+    const files = stdout
+      .split('\n')
+      .map((line) => line.trim())
+      .filter((line) => line !== '');
+
+    if (files.length === 0) {
+      console.log(`No files differ from ${base}`);
+      return 'ok';
+    }
+
+    console.log(`Formatting files that differ from ${base}:`, files);
+
+    // Format each file
+    const results = await Promise.allSettled(
+      files.map(async (filePath) => {
+        try {
+          // Read file content
+          const content = await readFile(filePath, 'utf8');
+
+          // Resolve prettier config for this file
+          const options = await prettier.resolveConfig(filePath);
+
+          // Check if file is ignored by prettier
+          const fileInfo = await prettier.getFileInfo(filePath, {
+            ignorePath: '.prettierignore',
+          });
+
+          if (fileInfo.ignored) {
+            console.log(`Skipping ignored file: ${filePath}`);
+            return;
+          }
+
+          // Format the content
+          const formatted = await prettier.format(content, {
+            ...options,
+            filepath: filePath,
+          });
+
+          // Only write if content changed
+          if (formatted !== content) {
+            await writeFile(filePath, formatted, 'utf8');
+            console.log(`Formatted: ${filePath}`);
+          }
+        } catch (error) {
+          console.error(`Error formatting ${filePath}:`, error);
+          throw error;
+        }
+      }),
+    );
+
+    // Check if any formatting failed
+    const hasErrors = results.some((result) => result.status === 'rejected');
+    return hasErrors ? 'err' : 'ok';
+  } catch (error) {
+    console.error('Error in formatDiffFrom:', error);
+    return 'err';
+  }
+};

package/src/functions/format.test.mts

@@ -0,0 +1,138 @@
+import dedent from 'dedent';
+import { mkdir, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { formatDiffFrom, formatFiles } from './format.mjs';
+
+describe('formatFiles', () => {
+  const testDir = join(process.cwd(), 'test-format-files');
+
+  // Helper to create a test file with unformatted content
+  const createTestFile = async (
+    filename: string,
+    content: string,
+  ): Promise<string> => {
+    const filePath = join(testDir, filename);
+    await writeFile(filePath, content, 'utf8');
+    return filePath;
+  };
+
+  // Helper to read file content
+  const readTestFile = async (filePath: string): Promise<string> => {
+    const { readFile } = await import('node:fs/promises');
+    return readFile(filePath, 'utf8');
+  };
+
+  test('should format files matching glob pattern', async () => {
+    // Setup test directory
+    await mkdir(testDir, { recursive: true });
+
+    try {
+      // Create test files with unformatted code
+      const file1 = await createTestFile(
+        'test1.ts',
+        dedent`
+          const   foo    =    "bar"
+          const baz = {a:1,b:2}
+        `,
+      );
+
+      const file2 = await createTestFile(
+        'test2.ts',
+        dedent`
+          function test  (  x:number,y:string  )   {
+          return x+1
+          }
+        `,
+      );
+
+      // Create a non-matching file
+      await createTestFile('test.md', '# Test\n\nSome    spaces');
+
+      // Format TypeScript files
+      const result = await formatFiles(`${testDir}/*.ts`);
+      expect(result).toBe('ok');
+
+      // Check that files were formatted
+      const content1 = await readTestFile(file1);
+      expect(content1).toBe(
+        `${dedent`
+          const foo = 'bar';
+          const baz = { a: 1, b: 2 };
+        `}\n`,
+      );
+
+      const content2 = await readTestFile(file2);
+      expect(content2).toBe(
+        `${dedent`
+          function test(x: number, y: string) {
+            return x + 1;
+          }
+        `}\n`,
+      );
+
+      // Check that non-matching file was not touched
+      const mdContent = await readTestFile(join(testDir, 'test.md'));
+      expect(mdContent).toBe('# Test\n\nSome    spaces');
+    } finally {
+      // Cleanup
+      await rm(testDir, { recursive: true, force: true });
+    }
+  });
+
+  test('should return ok when no files match pattern', async () => {
+    const result = await formatFiles('/non-existent-path/*.ts');
+    expect(result).toBe('ok');
+  });
+
+  test('should handle nested directories with glob pattern', async () => {
+    // Setup test directory with nested structure
+    await mkdir(join(testDir, 'src', 'utils'), { recursive: true });
+
+    try {
+      // Create nested test file
+      const nestedFile = await createTestFile(
+        join('src', 'utils', 'helper.ts'),
+        dedent`
+          export const helper=(x:number)=>{return x*2}
+        `,
+      );
+
+      // Format with recursive glob
+      const result = await formatFiles(`${testDir}/**/*.ts`);
+      expect(result).toBe('ok');
+
+      // Check that nested file was formatted
+      const content = await readTestFile(nestedFile);
+      expect(content).toBe(
+        `${dedent`
+          export const helper = (x: number) => {
+            return x * 2;
+          };
+        `}\n`,
+      );
+    } finally {
+      // Cleanup
+      await rm(testDir, { recursive: true, force: true });
+    }
+  });
+});
+
+describe('formatDiffFrom', () => {
+  test('should use default base branch "main"', () => {
+    // This test would require a git repository setup, so we'll just verify the function exists
+    // and can be called with no arguments
+    expect(typeof formatDiffFrom).toBe('function');
+    expect(formatDiffFrom.length).toBe(0); // Function has default parameter
+  });
+
+  test('should accept custom base branch or commit', () => {
+    // Verify the function can be called with a custom base
+    const customBases = ['develop', 'feature/test', 'abc123'];
+
+    for (const base of customBases) {
+      // This would normally test against a real git repo, but we're just verifying
+      // the function signature accepts the parameter
+      expect(() => formatDiffFrom(base)).not.toThrow();
+    }
+  });
+});

package/src/functions/gen-index.mts

@@ -0,0 +1,228 @@
+import micromatch from 'micromatch';
+import '../node-global.mjs';
+import { assertExt } from './assert-ext.mjs';
+import { assertPathExists } from './assert-path-exists.mjs';
+
+/**
+ * Configuration for index file generation.
+ */
+export type GenIndexConfig = DeepReadonly<{
+  /** Target directories to generate index files for (string or array of strings) */
+  targetDirectory: string | string[];
+
+  /** File extension of source files to export (default: '.mts') */
+  sourceExtension?: `.${string}`;
+
+  /** File extension to use in export statements (default: '.mjs') */
+  exportExtension?: `.${string}`;
+
+  /** Glob patterns of files to exclude from exports (default: excludes .d.* and .test.* files) */
+  excludePatterns?: string[];
+}>;
+
+/**
+ * Generates index.mts files recursively in `config.targetDirectory`.
+ * @param config - Configuration for index file generation
+ * @throws Error if any step fails.
+ */
+export const genIndex = async (config: GenIndexConfig): Promise<void> => {
+  echo('Starting index file generation...\n');
+
+  // Merge config with defaults
+  const filledConfig: DeepRequired<GenIndexConfig> = fillConfig(config);
+
+  // Normalize target directories to array
+  const targetDirs =
+    typeof config.targetDirectory === 'string'
+      ? [config.targetDirectory]
+      : config.targetDirectory;
+
+  try {
+    // Step 1: Validate file extensions
+    echo('1. Validating file extensions...');
+    await assertExt({
+      directories: [
+        {
+          path: path.resolve(projectRootPath, './src'),
+          extension: '.mts',
+          ignorePatterns: ['tsconfig.json', 'globals.d.mts'],
+        },
+        {
+          path: path.resolve(projectRootPath, './scripts'),
+          extension: '.mts',
+          ignorePatterns: ['tsconfig.json'],
+        },
+      ],
+    });
+    echo('✓ File extensions validated\n');
+
+    // Step 2: Verify target directories exist
+    for (const dir of targetDirs) {
+      const resolvedDir = path.resolve(dir);
+      // eslint-disable-next-line no-await-in-loop
+      await assertPathExists(resolvedDir, `Target directory: ${dir}`);
+    }
+
+    // Step 3: Generate index files
+    echo('2. Generating index files...');
+    for (const dir of targetDirs) {
+      const resolvedDir = path.resolve(dir);
+      // eslint-disable-next-line no-await-in-loop
+      await generateIndexFileForDir(resolvedDir, filledConfig);
+    }
+    echo('✓ Index files generated\n');
+
+    // Step 4: Format generated files
+    echo('3. Formatting generated files...');
+    const fmtResult = await $('npm run fmt');
+    if (fmtResult.type === 'error') {
+      throw new Error(`Formatting failed: ${fmtResult.exception.message}`);
+    }
+    echo('✓ Formatting completed\n');
+
+    echo('✅ Index file generation completed successfully!\n');
+  } catch (error) {
+    echo(`❌ Index generation failed: ${String(error)}\n`);
+    throw error;
+  }
+};
+
+const fillConfig = (config: GenIndexConfig): DeepRequired<GenIndexConfig> => {
+  const sourceExtension = config.sourceExtension ?? '.mts';
+  const exportExtension = config.exportExtension ?? '.mjs'; // For ESM imports, .mts resolves to .mjs
+
+  return {
+    targetDirectory: config.targetDirectory,
+    sourceExtension,
+    exportExtension,
+    excludePatterns: config.excludePatterns ?? [
+      `*.d${sourceExtension}`,
+      `*.test${sourceExtension}`,
+    ],
+  };
+};
+
+/**
+ * Generates an index.mts file for the given directory.
+ * Recursively calls itself for subdirectories.
+ * @param dirPath - The absolute path to the directory to process.
+ * @param config - The merged configuration object.
+ * @param baseDir - The base directory path for calculating relative paths (optional, defaults to dirPath).
+ * @throws Error if directory processing fails.
+ */
+const generateIndexFileForDir = async (
+  dirPath: string,
+  config: DeepReadonly<{
+    sourceExtension: `.${string}`;
+    exportExtension: `.${string}`;
+    excludePatterns: string[];
+  }>,
+  baseDir?: string,
+): Promise<void> => {
+  try {
+    const actualBaseDir = baseDir ?? dirPath;
+    const entries = await fs.readdir(dirPath, { withFileTypes: true });
+
+    const subDirectories: string[] = [];
+    const filesToExport: string[] = [];
+
+    for (const entry of entries) {
+      const entryName = entry.name;
+      const entryPath = path.join(dirPath, entryName);
+      const relativePath = path.relative(actualBaseDir, entryPath);
+
+      if (entry.isDirectory()) {
+        subDirectories.push(entryName);
+        // Recursively call for subdirectories first
+        // eslint-disable-next-line no-await-in-loop
+        await generateIndexFileForDir(entryPath, config, actualBaseDir);
+      } else if (entry.isFile() && shouldExportFile(relativePath, config)) {
+        filesToExport.push(entryName);
+      }
+    }
+
+    const indexContent = generateIndexContent(
+      subDirectories,
+      filesToExport,
+      config,
+    );
+
+    const indexPath = path.join(dirPath, `index${config.sourceExtension}`);
+
+    await fs.writeFile(indexPath, indexContent);
+    echo(`Generated: ${path.relative(process.cwd(), indexPath)}`);
+  } catch (error) {
+    throw new Error(
+      `Failed to generate index for directory ${dirPath}: ${String(error)}`,
+    );
+  }
+};
+
+/**
+ * Determines if a file should be exported in the index file.
+ * @param filePath - The relative path to the file from the target directory.
+ * @param config - The merged configuration object.
+ * @returns True if the file should be exported.
+ */
+const shouldExportFile = (
+  filePath: string,
+  config: DeepReadonly<{
+    sourceExtension: `.${string}`;
+    excludePatterns: string[];
+  }>,
+): boolean => {
+  const fileName = path.basename(filePath);
+
+  // Must have the correct source extension
+  if (!fileName.endsWith(config.sourceExtension)) {
+    return false;
+  }
+
+  // Don't export the index file itself
+  if (fileName === `index${config.sourceExtension}`) {
+    return false;
+  }
+
+  // Check against exclusion patterns
+  for (const pattern of config.excludePatterns) {
+    if (
+      micromatch.isMatch(filePath, pattern) ||
+      micromatch.isMatch(fileName, pattern)
+    ) {
+      return false;
+    }
+  }
+
+  return true;
+};
+
+/**
+ * Generates the content for an index file.
+ * @param subDirectories - Array of subdirectory names.
+ * @param filesToExport - Array of file names to export.
+ * @param config - The merged configuration object.
+ * @returns The index file content.
+ */
+const generateIndexContent = (
+  subDirectories: readonly string[],
+  filesToExport: readonly string[],
+  config: DeepReadonly<{
+    sourceExtension: string;
+    exportExtension: `.${string}`;
+  }>,
+): string => {
+  const exportStatements = [
+    ...subDirectories.map(
+      (subDir) => `export * from "./${subDir}/index${config.exportExtension}";`,
+    ),
+    ...filesToExport.map((file) => {
+      const fileNameWithoutExt = path.basename(file, config.sourceExtension);
+
+      return `export * from "./${fileNameWithoutExt}${config.exportExtension}";`;
+    }),
+  ];
+
+  return exportStatements.length === 0
+    ? 'export {};'
+    : exportStatements.join('\n');
+};

package/src/functions/index.mts

@@ -0,0 +1,6 @@
+export * from './assert-ext.mjs';
+export * from './assert-path-exists.mjs';
+export * from './assert-repo-is-dirty.mjs';
+export * from './exec-async.mjs';
+export * from './format.mjs';
+export * from './gen-index.mjs';

package/src/globals.d.mts

@@ -0,0 +1 @@
+/// <reference types="ts-type-forge" />

package/src/index.mts

@@ -0,0 +1 @@
+export * from './functions/index.mjs';

package/src/node-global.mts

@@ -0,0 +1,27 @@
+import { default as glob_ } from 'fast-glob';
+import * as fs_ from 'node:fs/promises';
+import * as path_ from 'node:path';
+import { $ as $_ } from './functions/exec-async.mjs';
+import { projectRootPath as projectRootPath_ } from './project-root-path.mjs';
+
+const globalsDef = {
+  $: $_,
+  echo: console.log,
+  projectRootPath: projectRootPath_,
+
+  path: path_,
+  fs: fs_,
+  glob: glob_,
+} as const;
+
+Object.assign(globalThis, globalsDef);
+
+declare global {
+  const $: typeof $_;
+  const echo: typeof console.log;
+  const projectRootPath: typeof projectRootPath_;
+
+  const path: typeof path_;
+  const fs: typeof fs_;
+  const glob: typeof glob_;
+}

package/src/project-root-path.mts

@@ -0,0 +1,3 @@
+import * as path from 'node:path';
+
+export const projectRootPath = path.resolve(import.meta.dirname, '..');