embedex 0.1.0

package/README.md

@@ -0,0 +1,92 @@
+<h1 align="center">embedex</h1>
+<p align="center">
+  <img alt="embedex logo." src="./static/logo.png" width=320>
+</p>
+
+Command-line interface (CLI) to embed examples into TypeDoc comments.
+
+While you can write code directly in TypeDoc comments using the [`@example` tag](https://typedoc.org/tags/example/), they aren't type-checked, linted, or tested, making it difficult to keep them up to date.
+
+While [`typedoc-plugin-include-example`](https://github.com/ferdodo/typedoc-plugin-include-example) embeds code into the resulting TypeDoc, it's missing from your code so VS Code's on-hover doesn't show the examples.
+
+Ensure your example code runs and shows up in your IDE with `embedex`.
+
+## Table of contents <!-- omit from toc -->
+
+- [Install](#install)
+- [Usage](#usage)
+- [Reference](#reference)
+- [Local development commands](#local-development-commands)
+
+## Install
+
+```sh
+npm install -D embedex
+```
+
+## Usage
+
+1. Add an example to `./examples` (configurable). The first line is a comma-separated list of paths from the current working directory to embed targets. `./examples/greeter.ts`:
+
+   ```ts
+   // src/greeter.ts
+   import { greet } from "@my-scope/greeter";
+
+   greet("world");
+   ```
+
+1. In embed target files, add an example comment with the path of the example. `./src/greeter.ts`:
+
+   ````ts
+   /**
+    * Greets a person by name.
+    *
+    * @example
+    * ```ts
+    * // examples/greeter.ts
+    * ```
+    */
+   function greet(name: string) {
+     console.log(`Hello, ${name}!`);
+   }
+   ````
+
+1. Run `npx embedex`.
+1. The example is embedded! `./src/greeter.ts`:
+
+   ````ts
+   /**
+    * Greets a person by name.
+    *
+    * @example
+    * ```ts
+    * // examples/greeter.ts
+    * import { greet } from "@my-scope/greeter";
+    *
+    * greet("world");
+    * ```
+    */
+   function greet(name: string) {
+     console.log(`Hello, ${name}!`);
+   }
+   ````
+
+## Reference
+
+```
+Usage: embedex [options]
+
+Command-line interface (CLI) to embed example TypeScript code into TypeDoc comments.
+
+Options:
+  -V, --version                 output the version number
+  -e, --examplesGlob <pattern>  examples glob pattern (default: "examples/**/*.ts")
+  -c, --check                   check if examples are already embedded, useful for CI (default:
+                                false)
+  -v, --verbose                 show verbose output (default: false)
+  -h, --help                    display help for command
+```
+
+## Local development commands
+
+See [`package.json`](./package.json) `scripts` for a list of commands.

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "embedex",
+  "description": "Command-line interface (CLI) to embed example TypeScript code into TypeDoc comments.",
+  "version": "0.1.0",
+  "bin": {
+    "embedex": "./src/bin/cli.js"
+  },
+  "dependencies": {
+    "@commander-js/extra-typings": "12.1.0",
+    "glob": "11.0.0",
+    "tslib": "2.8.0",
+    "yoctocolors-cjs": "2.1.2"
+  },
+  "keywords": [],
+  "license": "MIT",
+  "main": "./src/index.js",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "commonjs",
+  "typings": "./src/index.d.ts",
+  "types": "./src/index.d.ts"
+}

package/src/bin/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/src/bin/cli.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const extra_typings_1 = require("@commander-js/extra-typings");
+const package_json_1 = require("../../package.json");
+const embed_1 = require("../lib/embed");
+const processResult_1 = require("./processResult");
+const program = new extra_typings_1.Command()
+    .name(package_json_1.name)
+    .description("Command-line interface (CLI) to embed example TypeScript code into TypeDoc comments.")
+    .version(String(package_json_1.version))
+    .addOption(new extra_typings_1.Option("-e, --examplesGlob <pattern>", "examples glob pattern").default("examples/**/*.ts"))
+    .addOption(new extra_typings_1.Option("-c, --check", "check if examples are already embedded, useful for CI").default(false))
+    .addOption(new extra_typings_1.Option("-v, --verbose", "show verbose output").default(false));
+program.parse();
+const options = program.opts();
+const { check, examplesGlob, verbose } = options;
+const cwd = process.cwd();
+if (verbose) {
+    console.log((0, processResult_1.dim)("examplesGlob:\n  ", examplesGlob));
+    console.log((0, processResult_1.dim)("cwd:\n  ", cwd));
+}
+(0, embed_1.embed)({
+    examplesGlob,
+    cwd,
+    write: !check,
+})
+    .then((result) => {
+    const output = (0, processResult_1.processResult)({ check, result, cwd, verbose });
+    if (output.some((o) => o.isError)) {
+        console.error(output.map((o) => o.message).join("\n"));
+        process.exit(1);
+    }
+    else {
+        console.log(output.map((o) => o.message).join("\n"));
+    }
+})
+    .catch((error) => {
+    console.error(error.message);
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/src/bin/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../../../../packages/embedex/src/bin/cli.ts"],"names":[],"mappings":";;;AACA,+DAA8D;AAE9D,qDAAmD;AACnD,wCAAqC;AACrC,mDAAqD;AAErD,MAAM,OAAO,GAAG,IAAI,uBAAO,EAAE;KAC1B,IAAI,CAAC,mBAAI,CAAC;KACV,WAAW,CACV,sFAAsF,CACvF;KACA,OAAO,CAAC,MAAM,CAAC,sBAAO,CAAC,CAAC;KACxB,SAAS,CACR,IAAI,sBAAM,CAAC,8BAA8B,EAAE,uBAAuB,CAAC,CAAC,OAAO,CAAC,kBAAkB,CAAC,CAChG;KACA,SAAS,CACR,IAAI,sBAAM,CAAC,aAAa,EAAE,uDAAuD,CAAC,CAAC,OAAO,CACxF,KAAK,CACN,CACF;KACA,SAAS,CAAC,IAAI,sBAAM,CAAC,eAAe,EAAE,qBAAqB,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;AAEhF,OAAO,CAAC,KAAK,EAAE,CAAC;AAEhB,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;AAC/B,MAAM,EAAE,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;AACjD,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;AAE1B,IAAI,OAAO,EAAE,CAAC;IACZ,OAAO,CAAC,GAAG,CAAC,IAAA,mBAAG,EAAC,mBAAmB,EAAE,YAAY,CAAC,CAAC,CAAC;IACpD,OAAO,CAAC,GAAG,CAAC,IAAA,mBAAG,EAAC,UAAU,EAAE,GAAG,CAAC,CAAC,CAAC;AACpC,CAAC;AAED,IAAA,aAAK,EAAC;IACJ,YAAY;IACZ,GAAG;IACH,KAAK,EAAE,CAAC,KAAK;CACd,CAAC;KACC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE;IACf,MAAM,MAAM,GAAG,IAAA,6BAAa,EAAC,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC,CAAC;IAC9D,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;QAClC,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;QACvD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IACvD,CAAC;AACH,CAAC,CAAC;KACD,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACf,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAC7B,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/src/bin/processResult.d.ts

@@ -0,0 +1,14 @@
+import { type Embed, type EmbedResult } from "../lib/types";
+interface Output {
+    code: Embed["code"];
+    isError: boolean;
+    message: string;
+}
+export declare function dim(...messages: string[]): string;
+export declare function processResult(params: {
+    check: boolean;
+    result: EmbedResult;
+    cwd: string;
+    verbose: boolean;
+}): Output[];
+export {};

package/src/bin/processResult.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dim = dim;
+exports.processResult = processResult;
+const tslib_1 = require("tslib");
+const node_path_1 = require("node:path");
+const yoctocolors_cjs_1 = tslib_1.__importDefault(require("yoctocolors-cjs"));
+function dim(...messages) {
+    return yoctocolors_cjs_1.default.dim(messages.join(" "));
+}
+function processResult(params) {
+    const { check, result, cwd, verbose } = params;
+    const { embeds, examples, targets } = result;
+    function relative(path) {
+        return (0, node_path_1.relative)(cwd, path);
+    }
+    if (verbose) {
+        console.log(dim("examples:\n  ", examples
+            .map(({ path, targets }) => `${relative(path)} -> ${targets.map(relative).join(", ")}`)
+            .join("\n  ")));
+        console.log(dim("targets:\n  ", targets
+            .map(({ path, examples }) => `${relative(path)} -> ${examples.map(relative).join(", ")}`)
+            .join("\n  ")));
+    }
+    const output = [];
+    for (const embed of embeds) {
+        const { code, paths } = embed;
+        const { target, examples } = paths;
+        const toOutput = createToOutput({
+            code,
+            paths: { target: relative(target), examples: examples.map((path) => relative(path)) },
+        });
+        // eslint-disable-next-line default-case
+        switch (code) {
+            case "NO_CHANGE": {
+                output.push(toOutput());
+                break;
+            }
+            case "NO_MATCH": {
+                output.push(toOutput(true));
+                break;
+            }
+            case "UPDATE": {
+                output.push(toOutput(check));
+                break;
+            }
+        }
+    }
+    return output.sort((a, b) => a.code.localeCompare(b.code));
+}
+function createToOutput(params) {
+    const { code, paths } = params;
+    const { target, examples } = paths;
+    return (isError = false) => ({
+        code,
+        isError,
+        message: `${yoctocolors_cjs_1.default.green(code)} ${yoctocolors_cjs_1.default.gray(target)} -> ${yoctocolors_cjs_1.default.gray(examples.join(", "))}`,
+    });
+}
+//# sourceMappingURL=processResult.js.map

package/src/bin/processResult.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"processResult.js","sourceRoot":"","sources":["../../../../../packages/embedex/src/bin/processResult.ts"],"names":[],"mappings":"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"}

package/src/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./lib/embed";
+export * from "./lib/types";

package/src/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./lib/embed"), exports);
+tslib_1.__exportStar(require("./lib/types"), exports);
+//# sourceMappingURL=index.js.map

package/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../packages/embedex/src/index.ts"],"names":[],"mappings":";;;AAAA,sDAA4B;AAC5B,sDAA4B"}

package/src/lib/embed.d.ts

@@ -0,0 +1,5 @@
+import { type EmbedParams, type EmbedResult } from "./types";
+/**
+ * Command-line interface (CLI) to embed examples into TypeDoc comments.
+ */
+export declare function embed(params: Readonly<EmbedParams>): Promise<EmbedResult>;

package/src/lib/embed.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.embed = embed;
+const promises_1 = require("node:fs/promises");
+const createExampleMap_1 = require("./internal/createExampleMap");
+const createTargetMap_1 = require("./internal/createTargetMap");
+const processTargets_1 = require("./internal/processTargets");
+/**
+ * Command-line interface (CLI) to embed examples into TypeDoc comments.
+ */
+async function embed(params) {
+    const { examplesGlob: globPattern, cwd, write } = params;
+    const exampleMap = await (0, createExampleMap_1.createExampleMap)({ globPattern, cwd });
+    const targetMap = await (0, createTargetMap_1.createTargetMap)({ exampleMap });
+    const embeds = (0, processTargets_1.processTargets)({ exampleMap, cwd, targetMap });
+    await Promise.all(embeds.map(async (embed) => {
+        if (write && embed.code === "UPDATE") {
+            await (0, promises_1.writeFile)(embed.paths.target, embed.updatedContent);
+        }
+    }));
+    return {
+        embeds,
+        examples: [...exampleMap.entries()].map(([key, value]) => ({
+            path: key,
+            targets: value.targets,
+        })),
+        targets: [...targetMap.entries()].map(([key, value]) => ({
+            path: key,
+            examples: [...value.examples],
+        })),
+    };
+}
+//# sourceMappingURL=embed.js.map

package/src/lib/embed.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"embed.js","sourceRoot":"","sources":["../../../../../packages/embedex/src/lib/embed.ts"],"names":[],"mappings":";;AAUA,sBA0BC;AApCD,+CAA6C;AAE7C,kEAA+D;AAC/D,gEAA6D;AAC7D,8DAA2D;AAG3D;;GAEG;AACI,KAAK,UAAU,KAAK,CAAC,MAA6B;IACvD,MAAM,EAAE,YAAY,EAAE,WAAW,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,MAAM,CAAC;IACzD,MAAM,UAAU,GAAG,MAAM,IAAA,mCAAgB,EAAC,EAAE,WAAW,EAAE,GAAG,EAAE,CAAC,CAAC;IAChE,MAAM,SAAS,GAAG,MAAM,IAAA,iCAAe,EAAC,EAAE,UAAU,EAAE,CAAC,CAAC;IAExD,MAAM,MAAM,GAAG,IAAA,+BAAc,EAAC,EAAE,UAAU,EAAE,GAAG,EAAE,SAAS,EAAE,CAAC,CAAC;IAE9D,MAAM,OAAO,CAAC,GAAG,CACf,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE;QACzB,IAAI,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YACrC,MAAM,IAAA,oBAAS,EAAC,KAAK,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,cAAc,CAAC,CAAC;QAC5D,CAAC;IACH,CAAC,CAAC,CACH,CAAC;IAEF,OAAO;QACL,MAAM;QACN,QAAQ,EAAE,CAAC,GAAG,UAAU,CAAC,OAAO,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC;YACzD,IAAI,EAAE,GAAG;YACT,OAAO,EAAE,KAAK,CAAC,OAAO;SACvB,CAAC,CAAC;QACH,OAAO,EAAE,CAAC,GAAG,SAAS,CAAC,OAAO,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC;YACvD,IAAI,EAAE,GAAG;YACT,QAAQ,EAAE,CAAC,GAAG,KAAK,CAAC,QAAQ,CAAC;SAC9B,CAAC,CAAC;KACJ,CAAC;AACJ,CAAC"}

package/src/lib/internal/createExampleMap.d.ts

@@ -0,0 +1,5 @@
+import { type ExampleMap } from "./types";
+export declare function createExampleMap(params: {
+    globPattern: string;
+    cwd: string;
+}): Promise<ExampleMap>;

package/src/lib/internal/createExampleMap.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createExampleMap = createExampleMap;
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const glob_1 = require("glob");
+const EXAMPLE_MARKER_PREFIX = "// ";
+async function createExampleMap(params) {
+    const { globPattern, cwd } = params;
+    const exampleMap = new Map();
+    const paths = await (0, glob_1.glob)(globPattern, { absolute: true, cwd, nodir: true });
+    for await (const path of paths) {
+        const content = await (0, promises_1.readFile)(path, "utf8");
+        const [first, ...rest] = content.split("\n");
+        if (first?.startsWith(EXAMPLE_MARKER_PREFIX)) {
+            exampleMap.set(path, {
+                content: rest.join("\n"),
+                targets: first
+                    .replace(EXAMPLE_MARKER_PREFIX, "")
+                    .split(",")
+                    .map((t) => (0, node_path_1.join)(cwd, t.trim())),
+            });
+        }
+    }
+    return exampleMap;
+}
+//# sourceMappingURL=createExampleMap.js.map

package/src/lib/internal/createExampleMap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createExampleMap.js","sourceRoot":"","sources":["../../../../../../packages/embedex/src/lib/internal/createExampleMap.ts"],"names":[],"mappings":";;AAUA,4CAuBC;AAjCD,+CAA4C;AAC5C,yCAAiC;AAEjC,+BAA4B;AAK5B,MAAM,qBAAqB,GAAG,KAAK,CAAC;AAE7B,KAAK,UAAU,gBAAgB,CAAC,MAGtC;IACC,MAAM,EAAE,WAAW,EAAE,GAAG,EAAE,GAAG,MAAM,CAAC;IACpC,MAAM,UAAU,GAAG,IAAI,GAAG,EAAwB,CAAC;IACnD,MAAM,KAAK,GAAG,MAAM,IAAA,WAAI,EAAC,WAAW,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAE5E,IAAI,KAAK,EAAE,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QAC/B,MAAM,OAAO,GAAG,MAAM,IAAA,mBAAQ,EAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAC7C,MAAM,CAAC,KAAK,EAAE,GAAG,IAAI,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC7C,IAAI,KAAK,EAAE,UAAU,CAAC,qBAAqB,CAAC,EAAE,CAAC;YAC7C,UAAU,CAAC,GAAG,CAAC,IAAI,EAAE;gBACnB,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;gBACxB,OAAO,EAAE,KAAK;qBACX,OAAO,CAAC,qBAAqB,EAAE,EAAE,CAAC;qBAClC,KAAK,CAAC,GAAG,CAAC;qBACV,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAA,gBAAI,EAAC,GAAG,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;aACnC,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,OAAO,UAAU,CAAC;AACpB,CAAC"}

package/src/lib/internal/createTargetMap.d.ts

@@ -0,0 +1,4 @@
+import { type ExampleMap, type TargetMap } from "./types";
+export declare function createTargetMap(params: Readonly<{
+    exampleMap: Readonly<ExampleMap>;
+}>): Promise<TargetMap>;

package/src/lib/internal/createTargetMap.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTargetMap = createTargetMap;
+const promises_1 = require("node:fs/promises");
+async function createTargetMap(params) {
+    const { exampleMap } = params;
+    const uniqueTargetPaths = new Set([...exampleMap.values()].flatMap(({ targets }) => targets));
+    const targetContents = new Map();
+    await Promise.all([...uniqueTargetPaths].map(async (path) => {
+        targetContents.set(path, await (0, promises_1.readFile)(path, "utf8"));
+    }));
+    return new Map([...uniqueTargetPaths].map((targetPath) => [
+        targetPath,
+        {
+            content: targetContents.get(targetPath),
+            examples: new Set([...exampleMap.entries()]
+                .filter(([_, { targets }]) => targets.includes(targetPath))
+                .map(([examplePath]) => examplePath)),
+        },
+    ]));
+}
+//# sourceMappingURL=createTargetMap.js.map

package/src/lib/internal/createTargetMap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createTargetMap.js","sourceRoot":"","sources":["../../../../../../packages/embedex/src/lib/internal/createTargetMap.ts"],"names":[],"mappings":";;AAKA,0CA0BC;AA/BD,+CAA4C;AAKrC,KAAK,UAAU,eAAe,CACnC,MAAsD;IAEtD,MAAM,EAAE,UAAU,EAAE,GAAG,MAAM,CAAC;IAE9B,MAAM,iBAAiB,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,UAAU,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;IAC9F,MAAM,cAAc,GAAG,IAAI,GAAG,EAAsB,CAAC;IACrD,MAAM,OAAO,CAAC,GAAG,CACf,CAAC,GAAG,iBAAiB,CAAC,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE;QACxC,cAAc,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,IAAA,mBAAQ,EAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;IACzD,CAAC,CAAC,CACH,CAAC;IAEF,OAAO,IAAI,GAAG,CACZ,CAAC,GAAG,iBAAiB,CAAC,CAAC,GAAG,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC;QACzC,UAAU;QACV;YACE,OAAO,EAAE,cAAc,CAAC,GAAG,CAAC,UAAU,CAAE;YACxC,QAAQ,EAAE,IAAI,GAAG,CACf,CAAC,GAAG,UAAU,CAAC,OAAO,EAAE,CAAC;iBACtB,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,OAAO,EAAE,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;iBAC1D,GAAG,CAAC,CAAC,CAAC,WAAW,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC,CACvC;SACF;KACF,CAAC,CACH,CAAC;AACJ,CAAC"}

package/src/lib/internal/processTargets.d.ts

@@ -0,0 +1,7 @@
+import type { Embed } from "../types";
+import { type ExampleMap, type TargetMap } from "./types";
+export declare function processTargets(params: Readonly<{
+    exampleMap: ExampleMap;
+    cwd: string;
+    targetMap: TargetMap;
+}>): Embed[];

package/src/lib/internal/processTargets.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.processTargets = processTargets;
+const node_path_1 = require("node:path");
+function processTargets(params) {
+    const { exampleMap, targetMap, cwd } = params;
+    function absolutePath(path) {
+        return (0, node_path_1.join)(cwd, path);
+    }
+    const result = [];
+    for (const [target, value] of targetMap.entries()) {
+        const { content, examples } = value;
+        const matches = matchAll({ content, exists: (example) => examples.has(absolutePath(example)) });
+        if (matches.length === 0) {
+            result.push({ code: "NO_MATCH", paths: { target, examples: [] } });
+        }
+        else {
+            let updatedContent = content;
+            for (const { fullMatch, language, indent, example } of matches) {
+                const exampleContent = exampleMap.get(absolutePath(example));
+                const replacement = `\`\`\`${language}\n${prefixLines({
+                    content: [`// ${example}`, ...exampleContent.content.split("\n"), `\`\`\``],
+                    indent,
+                })}`;
+                updatedContent = updatedContent.replaceAll(fullMatch, replacement);
+            }
+            const paths = { examples: matches.map((m) => absolutePath(m.example)), target };
+            result.push(content === updatedContent
+                ? { code: "NO_CHANGE", paths }
+                : { code: "UPDATE", paths, updatedContent });
+        }
+    }
+    return result;
+}
+function matchAll(params) {
+    const { content, exists } = params;
+    return [...content.matchAll(/```(typescript|ts)\n(\s+)\*\s+\/\/\s(.+)\n[\S\s]+?```/g)]
+        .map((match) => {
+        const [fullMatch, language, indent, example] = match;
+        return isDefined(fullMatch) &&
+            isDefined(language) &&
+            isDefined(indent) &&
+            isDefined(example) &&
+            exists(example)
+            ? { fullMatch, language, indent, example }
+            : undefined;
+    })
+        .filter(isDefined);
+}
+function prefixLines(params) {
+    const { content, indent } = params;
+    return content
+        .map((line) => {
+        const trimmed = line.trim();
+        return trimmed ? `${indent}* ${line}` : `${indent}*`;
+    })
+        .join("\n");
+}
+function isDefined(value) {
+    return value !== null && value !== undefined;
+}
+//# sourceMappingURL=processTargets.js.map

package/src/lib/internal/processTargets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"processTargets.js","sourceRoot":"","sources":["../../../../../../packages/embedex/src/lib/internal/processTargets.ts"],"names":[],"mappings":"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"}

package/src/lib/internal/types.d.ts

@@ -0,0 +1,12 @@
+import { type ExamplePath, type TargetPath } from "../types";
+export interface Example {
+    content: string;
+    targets: TargetPath[];
+}
+export type ExampleMap = Map<ExamplePath, Example>;
+interface Target {
+    content: string;
+    examples: Set<ExamplePath>;
+}
+export type TargetMap = Map<TargetPath, Target>;
+export {};

package/src/lib/internal/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/src/lib/internal/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../../../packages/embedex/src/lib/internal/types.ts"],"names":[],"mappings":""}

package/src/lib/types.d.ts

@@ -0,0 +1,37 @@
+export type ExamplePath = string;
+export type TargetPath = string;
+export interface EmbedParams {
+    examplesGlob: string;
+    cwd: string;
+    write: boolean;
+}
+export type Code = "NO_CHANGE" | "NO_MATCH" | "UPDATE";
+export interface Result {
+    code: Code;
+    paths: {
+        target: TargetPath;
+        examples: ExamplePath[];
+    };
+}
+export type NoMatch = Result & {
+    code: "NO_MATCH";
+};
+export type NoChange = Result & {
+    code: "NO_CHANGE";
+};
+export type Updated = Result & {
+    code: "UPDATE";
+    updatedContent: string;
+};
+export type Embed = NoMatch | Updated | NoChange;
+export interface EmbedResult {
+    embeds: Embed[];
+    examples: Array<{
+        path: ExamplePath;
+        targets: TargetPath[];
+    }>;
+    targets: Array<{
+        path: TargetPath;
+        examples: ExamplePath[];
+    }>;
+}

package/src/lib/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/src/lib/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../../packages/embedex/src/lib/types.ts"],"names":[],"mappings":""}