feat: add alias support

docs/1.guide/2.config.md

@@ -51,3 +51,10 @@ The markdown file name or path (relative to `dir`).
 - Default: `{}`
 
 A map of generator names to custom generators.
+
+### `alias`
+
+- Type: `Object`
+- Default: `{}`
+
+Custom alias used in `jsdocs` and `file` generators.

package.json

@@ -64,5 +64,5 @@
     "unbuild": "^2.0.0",
     "vitest": "^1.3.1"
   },
-  "packageManager": "[email protected].3"
-}
+  "packageManager": "[email protected].4"
+}

src/_utils.ts

@@ -3,14 +3,23 @@ import { readPackageJSON } from "pkg-types";
 import { defu } from "defu";
 import { fileURLToPath } from "mlly";
 import { resolve, join } from "pathe";
+import { resolveAlias } from "pathe/utils";
 
 export function resolvePath(
   path: string,
-  { url, dir }: { url?: string; dir: string },
+  {
+    url,
+    dir,
+    alias,
+  }: { url?: string; dir: string; alias?: Record<string, string> },
 ) {
   if (path.startsWith("/")) {
     return join(dir, path);
   }
+
+  if (alias) {
+    return resolveAlias(path, alias);
+  }
   return url ? fileURLToPath(new URL(path, url)) : resolve(dir, path);
 }
 

src/config.ts

@@ -1,4 +1,5 @@
 import { resolve } from "pathe";
+import { normalizeAliases } from "pathe/utils";
 import type { Generator } from "./generator";
 import type { AutomdResult } from "./automd";
 
@@ -43,6 +44,11 @@ export interface Config {
 
   /** Custom generators */
   generators?: Record<string, Generator>;
+
+  /**
+   * Custom alias, works when handle `automd:(jsdocs|file)` src
+   */
+  alias?: Record<string, string>;
 }
 
 const RESOLVED_CONFIG_SYMBOL = Symbol("automdConfig");
@@ -74,6 +80,10 @@ export function resolveConfig(
     Array.isArray(_config.input) ? _config.input : [_config.input]
   ).filter(Boolean);
 
+  if (_config.alias) {
+    _config.alias = normalizeAliases(_config.alias);
+  }
+
   return _config;
 }
 

src/generators/file.ts

@@ -7,7 +7,11 @@ import { resolvePath } from "../_utils";
 export const file = defineGenerator({
   name: "file",
   async generate({ args, config, url }) {
-    const fullPath = resolvePath(args.src, { url, dir: config.dir });
+    const fullPath = resolvePath(args.src, {
+      url,
+      dir: config.dir,
+      alias: config.alias,
+    });
     let contents = await readFile(fullPath, "utf8");
 
     if (args.code) {

src/generators/jsdocs.ts

@@ -12,7 +12,11 @@ export const jsdocs = defineGenerator({
   name: "jsdocs",
   async generate({ config, args, url }) {
     const { loadSchema } = await import("untyped/loader");
-    const fullPath = resolvePath(args.src, { url, dir: config.dir });
+    const fullPath = resolvePath(args.src, {
+      url,
+      dir: config.dir,
+      alias: config.alias,
+    });
 
     const schema = await loadSchema(fullPath);
 

test/parse.test.ts

@@ -1,5 +1,7 @@
+import { resolve } from "node:path";
 import { describe, it, expect } from "vitest";
 import { parseRawArgs, findBlocks } from "../src/_parse";
+import { transform } from "../src/transform";
 
 describe("parseRawArgs", () => {
   const tests = [
@@ -51,3 +53,68 @@ describe("findBlocks", () => {
     expect(blocks[2]).toMatchObject(mkBlock("jsdocs", "", "(c)"));
   });
 });
+
+describe("transform with alias", () => {
+  it("should parse alias correctly in jsdoc", async () => {
+    const input = `<!-- automd:jsdocs src="~/fixture/src/example" -->\n\n<!-- /automd -->`;
+
+    const result = await transform(input, {
+      alias: {
+        "~": resolve("./test"),
+      },
+    });
+
+    expect(result.contents).toMatchInlineSnapshot(`
+      "<!-- automd:jsdocs src="~/fixture/src/example" -->
+
+      ### \`add(a, b)\`
+
+      Adds two numbers together.
+
+      **Example:**
+
+      \`\`\`js
+      add(1, 2); // 3
+      \`\`\`
+
+      ### \`object\`
+
+      #### \`key\`
+
+      An object key
+
+      ##### \`subkey\`
+
+      - **Type**: \`string\`
+      - **Default**: \`"value"\`
+
+      A subkey
+
+      <!-- /automd -->"
+    `);
+  });
+
+  it("should parse alias correctly in file", async () => {
+    const input = `<!-- automd:file src="~/fixture/TEST.md" -->\n\n<!-- /automd -->`;
+
+    const result = await transform(input, {
+      alias: {
+        "~": resolve("./test"),
+      },
+    });
+
+    expect(result.contents).toMatchInlineSnapshot(`
+      "<!-- automd:file src="~/fixture/TEST.md" -->
+
+      ## The Lazy Coder's Guide to Programming
+
+      Programming can be hard. But fear not! With the power of copy-paste, you can conquer any coding challenge without breaking a sweat. Just remember: if it works once, it'll work a thousand times. Who needs original code anyway?
+
+      When your code doesn't work, don't blame yourself. It's clearly the compiler's fault for not understanding your genius. Remember, the more error messages you get, the closer you are to becoming a programming master.
+
+      Why waste time solving problems when someone else has already done it for you? Stack Overflow is your best friend, your mentor, and your savior. Just make sure to upvote the answers that save your bacon.
+
+      <!-- /automd -->"
+    `);
+  });
+});