Convert package-scripts to TypeScript

.changeset/ts-package-scripts.md

@@ -0,0 +1,5 @@
+---
+'markdown-magic-package-scripts': minor
+---
+
+TypeScript: ship type declarations

packages/package-scripts/README.md

@@ -10,14 +10,14 @@ yarn add -D markdown-magic markdown-magic-package-scripts
 
 ## Adding the plugin
 
-See `example.js` for usage.
+See `example.ts` for usage.
 
-<!-- AUTO-GENERATED-CONTENT:START (CODE:src=./example.js) -->
+<!-- AUTO-GENERATED-CONTENT:START (CODE:src=./example.ts) -->
 
-```js
+```ts
 import path from 'path';
 import { markdownMagic } from 'markdown-magic';
-import SCRIPTS from './index.js';
+import SCRIPTS from './index.ts';
 
 const config = {
   matchWord: 'AUTO-GENERATED-CONTENT',
@@ -36,11 +36,14 @@ await markdownMagic(markdownPath, config);
 
 <!-- AUTO-GENERATED-CONTENT:START (SCRIPTS) -->
 
-| Script   | Description                      |
-| -------- | -------------------------------- |
-| `docs`   | generate docs                    |
-| `empty`  | `echo "this is just an example"` |
-| `format` | format code                      |
-| `test`   | `vitest run`                     |
+| Script     | Description                         |
+| ---------- | ----------------------------------- |
+| `prebuild` | `rm -rf dist`                       |
+| `build`    | `tsc --project tsconfig.build.json` |
+| `docs`     | generate docs                       |
+| `empty`    | `echo "this is just an example"`    |
+| `format`   | format code                         |
+| `prepack`  | `pnpm build`                        |
+| `test`     | `vitest run`                        |
 
 <!-- AUTO-GENERATED-CONTENT:END -->

packages/package-scripts/__snapshots__/index.spec.js.snap → packages/package-scripts/__snapshots__/index.spec.ts.snap

@@ -3,8 +3,11 @@
 exports[`markdown-magic-package-scripts > renders a table of scripts from the nearest package.json 1`] = `
 "| Script | Description |
 |--------|-------------|
-| \`docs\` | \`node example.js && prettier --write README.md\` |
+| \`prebuild\` | \`rm -rf dist\` |
+| \`build\` | \`tsc --project tsconfig.build.json\` |
+| \`docs\` | \`node example.ts && prettier --write README.md\` |
 | \`empty\` | \`echo "this is just an example"\` |
 | \`format\` | \`prettier --write .\` |
+| \`prepack\` | \`pnpm build\` |
 | \`test\` | \`vitest run\` |"
 `;

packages/package-scripts/example.js → packages/package-scripts/example.ts

@@ -1,6 +1,6 @@
 import path from 'path';
 import { markdownMagic } from 'markdown-magic';
-import SCRIPTS from './index.js';
+import SCRIPTS from './index.ts';
 
 const config = {
   matchWord: 'AUTO-GENERATED-CONTENT',

packages/package-scripts/index.spec.js → packages/package-scripts/index.spec.ts

@@ -1,6 +1,6 @@
 import path from 'path';
 import { describe, expect, it } from 'vitest';
-import format from './index.js';
+import format from './index.ts';
 
 const srcPath = path.join(import.meta.dirname, 'README.md');
 

packages/package-scripts/index.js → packages/package-scripts/index.ts

@@ -2,8 +2,11 @@ import { readFileSync } from 'fs';
 import path from 'path';
 import { findUpSync } from 'find-up';
 import sortScripts from 'sort-scripts';
+import type { TransformArgs } from './types.ts';
 
-function findPkg(dir) {
+export type { TransformArgs, TransformOptions } from './types.ts';
+
+function findPkg(dir: string): string {
   const pkgPath = findUpSync('package.json', { cwd: dir });
 
   if (!pkgPath) {
@@ -13,8 +16,12 @@ function findPkg(dir) {
   return pkgPath;
 }
 
-export default function SCRIPTS({ content, options = {}, srcPath }) {
-  let pkgPath;
+export default function SCRIPTS({
+  content,
+  options = {},
+  srcPath,
+}: TransformArgs): string {
+  let pkgPath: string;
 
   if (options && options.pkg) {
     pkgPath = path.resolve(path.dirname(srcPath), options.pkg);
@@ -32,18 +39,23 @@ export default function SCRIPTS({ content, options = {}, srcPath }) {
     .map((s) => s.trim());
   const headerIndex = rows.findIndex((row) => row.startsWith('|-'));
 
-  const details = (headerIndex !== -1 ? rows.slice(headerIndex + 1) : rows)
+  const details: Record<string, string | undefined> = (
+    headerIndex !== -1 ? rows.slice(headerIndex + 1) : rows
+  )
     .map((row) =>
       row
         .split('|')
         .map((s) => s.trim())
         .filter((s) => !!s),
     )
     .filter(([script]) => !!script)
-    .reduce((obj, [script, description]) => {
-      obj[script.replace(/`/g, '')] = description;
-      return obj;
-    }, {});
+    .reduce(
+      (obj: Record<string, string | undefined>, [script, description]) => {
+        obj[script.replace(/`/g, '')] = description;
+        return obj;
+      },
+      {},
+    );
 
   return ['| Script | Description |', '|--------|-------------|']
     .concat(

packages/package-scripts/package.json

@@ -3,17 +3,21 @@
   "version": "2.0.0",
   "description": "Print list of scripts in package.json with descriptions",
   "type": "module",
-  "main": "index.js",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "exports": {
-    ".": "./index.js",
+    ".": "./dist/index.js",
     "./package.json": "./package.json"
   },
   "engines": {
     "node": ">=22.18.0"
   },
   "scripts": {
+    "prebuild": "rm -rf dist",
+    "build": "tsc --project tsconfig.build.json",
+    "prepack": "pnpm build",
     "test": "vitest run",
-    "docs": "node example.js && prettier --write README.md",
+    "docs": "node example.ts && prettier --write README.md",
     "empty": "echo \"this is just an example\"",
     "format": "prettier --write ."
   },
@@ -40,15 +44,17 @@
     "markdown-magic": "^4"
   },
   "devDependencies": {
+    "@types/node": "^24.13.2",
     "markdown-magic": "catalog:",
     "prettier": "catalog:",
+    "typescript": "^6.0.3",
     "vitest": "catalog:"
   },
   "homepage": "https://github.com/camacho/markdown-magic-plugins#readme",
   "bugs": {
     "url": "https://github.com/camacho/markdown-magic-plugins/issues"
   },
   "files": [
-    "index.js"
+    "dist"
   ]
 }

packages/package-scripts/sort-scripts-shim.d.ts

@@ -0,0 +1,10 @@
+// Ambient shim for `sort-scripts`. Upstream ships no type declarations and
+// no `@types/sort-scripts` package exists — smallest correct local
+// declaration for the single default export actually used here (verified
+// against node_modules/sort-scripts@1.0.1/index.js: takes a scripts map,
+// returns `[name, script]` pairs sorted with pre/post ordering).
+declare module 'sort-scripts' {
+  export default function sortScripts(
+    scripts: Record<string, string>,
+  ): Array<[string, string]>;
+}

packages/package-scripts/tsconfig.build.json

@@ -0,0 +1,18 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "noEmit": false,
+    "outDir": "dist",
+    "rootDir": ".",
+    "types": ["node"]
+  },
+  "exclude": [
+    "node_modules",
+    "dist",
+    "*.spec.ts",
+    "example.ts",
+    "__fixtures__",
+    "__snapshots__"
+  ],
+  "include": ["*.ts"]
+}

packages/package-scripts/types.ts

@@ -0,0 +1,14 @@
+// Transform interface shared by markdown-magic plugins. Adapted from
+// format-package's scripts/markdown-transformers.ts TransformArgs/TransformOptions
+// (content: unknown -> content: string, the plugins' actual contract), plus
+// this package's own `pkg` option.
+export interface TransformOptions {
+  pkg?: string;
+  [key: string]: unknown;
+}
+
+export interface TransformArgs {
+  content: string;
+  options: TransformOptions;
+  srcPath: string;
+}