@smitejs/snippets 2.0.0-SNAPSHOT

package/src/index.test.ts

@@ -0,0 +1,232 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildSnippetIndex,
+  collectTestSnippets,
+  expandExamples,
+  expandMarkdown,
+  expandTemplate,
+  extractSnippetExpected,
+  extractSnippets,
+  transformExpectedToResult,
+} from "./index.js";
+
+describe("extractSnippets", () => {
+  it("collects a section block with a slug and dedented code", () => {
+    const source = [
+      "it('works', () => {",
+      "  // #section - Extract a block",
+      "  const value = 1 + 1;",
+      "  // #endsection",
+      "});",
+    ].join("\n");
+
+    const snippets = extractSnippets(source, "fixture.test.ts");
+    expect(snippets).toHaveLength(1);
+    expect(snippets[0]?.title).toBe("Extract a block");
+    expect(snippets[0]?.slug).toBe("extract-a-block");
+    expect(snippets[0]?.code).toBe("const value = 1 + 1;");
+  });
+
+  it("throws on a nested section", () => {
+    const source = [
+      "// #section - A",
+      "// #section - B",
+      "// #endsection",
+    ].join("\n");
+
+    expect(() => extractSnippets(source, "a.test.ts")).toThrow(/Nested/u);
+  });
+
+  it("throws on an unclosed section", () => {
+    const source = "// #section - A\nconst x = 1;";
+    expect(() => extractSnippets(source, "a.test.ts")).toThrow(/Unclosed/u);
+  });
+});
+
+describe("extractSnippetExpected", () => {
+  it("reads the assertions that follow the section as expected values", () => {
+    const source = [
+      "  // #section - Compute a value",
+      "  const value = 2 + 2;",
+      "  // #endsection",
+      "  expect(value).toBe(4);",
+      "  expect(value).toMatchObject([4]);",
+    ].join("\n");
+
+    const snippets = extractSnippets(source, "a.test.ts");
+    expect(extractSnippetExpected(source, snippets[0] as never)).toContain(
+      "expect(value).toMatchObject([4]);",
+    );
+  });
+
+  it("reduces expect chains to the expected results", () => {
+    expect(
+      transformExpectedToResult("expect(x).toBe(1); expect(y).toBe(2)"),
+    ).toBe("1\n2");
+  });
+});
+
+describe("collectTestSnippets", () => {
+  it("builds a title index keyed on the lower-cased title", async () => {
+    const { snippetIndex, snippets } = await collectTestSnippets({
+      packageName: "@smitejs/snippets",
+      rootDir: process.cwd(),
+      srcDir: new URL("..", import.meta.url).pathname,
+    });
+    expect(snippets.length).toBeGreaterThan(0);
+    expect(snippetIndex.has("expand @example declarations")).toBe(true);
+  });
+
+  it("rejects duplicate titles", () => {
+    const snippets = [
+      {
+        title: "Same",
+        code: "a",
+        slug: "same",
+        filePath: "a",
+        startLine: 1,
+        expected: null,
+      },
+      {
+        title: "same",
+        code: "b",
+        slug: "same",
+        filePath: "b",
+        startLine: 1,
+        expected: null,
+      },
+    ];
+
+    expect(() => buildSnippetIndex(snippets, "pkg")).toThrow(/Duplicate/u);
+  });
+});
+
+describe("expandExamples", () => {
+  it("renders a referenced snippet into a fenced block", () => {
+    const snippets = [
+      {
+        title: "Serve an app",
+        code: "const server = serve(app);",
+        slug: "serve-an-app",
+        filePath: "a",
+        startLine: 1,
+        expected: null,
+      },
+    ];
+    const index = buildSnippetIndex(snippets, "pkg");
+    const expanded = expandExamples(
+      " * @example Serve an app\n",
+      index,
+      "pkg",
+      "index.d.ts",
+    );
+
+    expect(expanded).toContain("```ts");
+    expect(expanded).toContain("const server = serve(app);");
+  });
+
+  it("throws when a referenced title is missing", () => {
+    expect(() =>
+      expandExamples(" * @example Nope\n", new Map(), "pkg", "x.d.ts"),
+    ).toThrow(/Missing tested snippet: Nope/u);
+  });
+});
+
+describe("expandTemplate", () => {
+  it("replaces a // @snippet marker with the tested code", () => {
+    const snippets = [
+      {
+        title: "Bootstrap the app",
+        code: 'export const app = http.app("store");',
+        slug: "bootstrap",
+        filePath: "a",
+        startLine: 1,
+        expected: null,
+      },
+    ];
+    const index = buildSnippetIndex(snippets, "pkg");
+    const source =
+      'import { http } from "@smitejs/http";\n// @snippet Bootstrap the app\n';
+    const expanded = expandTemplate(source, index, "pkg", "app.ts");
+    expect(expanded).toBe(
+      'import { http } from "@smitejs/http";\nexport const app = http.app("store");\n',
+    );
+  });
+
+  it("throws when a marker has no tested snippet", () => {
+    expect(() =>
+      expandTemplate("// @snippet Nobody\n", new Map(), "pkg", "a.ts"),
+    ).toThrow(/Missing tested snippet: Nobody/u);
+  });
+});
+
+describe("expandMarkdown", () => {
+  it("replaces @example lines with placeholders and returns injectables", () => {
+    const snippet = {
+      title: "Bootstrap the app",
+      code: 'const app = http.app("store");',
+      slug: "bootstrap",
+      filePath: "x",
+      startLine: 1,
+      expected: null,
+    };
+    const index = buildSnippetIndex([snippet], "pkg");
+    const { body, examples } = expandMarkdown(
+      "# Serving\n\n@example Bootstrap the app\n\nDone",
+      index,
+      "pkg",
+      "concept.md",
+    );
+
+    expect(body).not.toContain("@example");
+    expect(examples).toHaveLength(1);
+    expect(examples[0]?.snippet.code).toBe('const app = http.app("store");');
+  });
+});
+
+describe("documentation examples", () => {
+  it("expands @example declarations", () => {
+    // #section - Expand @example declarations
+    const source = " * @example Expand @example declarations";
+    const snippet = buildSnippetIndex(
+      [
+        {
+          title: "Expand @example declarations",
+          code: "x()",
+          slug: "x",
+          filePath: "self.test.ts",
+          startLine: 1,
+          expected: null,
+        },
+      ],
+      "self",
+    );
+    const expanded = expandExamples(source, snippet, "self", "self.d.ts");
+    // #endsection
+
+    expect(expanded).toContain("```ts");
+  });
+
+  it("expands @snippet into a source file", () => {
+    // #section - Expand @snippet into a source file
+    const snippet = buildSnippetIndex([
+      {
+        title: "Expand @snippet into a source file",
+        code: "line = 1",
+        slug: "x",
+        filePath: "self.test.ts",
+        startLine: 1,
+        expected: null,
+      },
+    ]);
+    const expanded = expandTemplate(
+      "// @snippet Expand @snippet into a source file\n",
+      snippet,
+      "self",
+      "x.ts",
+    );
+    // #endsection
+
+    expect(expanded).toContain("line = 1");
+  });
+});

package/src/index.ts

@@ -0,0 +1,19 @@
+export {
+  buildSnippetIndex,
+  collectFiles,
+  collectTestSnippets,
+  extractSnippetExpected,
+  extractSnippets,
+  normalizeExampleName,
+  slugify,
+  transformExpectedToResult,
+} from "./snippets.js";
+export type { Snippet } from "./snippets.js";
+export {
+  expandExamples,
+  expandMarkdown,
+  expandTemplate,
+  renderExample,
+} from "./expand.js";
+export type { MarkdownInjectable } from "./expand.js";
+export { injectIntoFiles } from "./inject.js";

package/src/inject.ts

@@ -0,0 +1,46 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { expandExamples } from "./expand.js";
+import { collectFiles } from "./snippets.js";
+import type { Snippet } from "./snippets.js";
+
+/**
+ * Walks `targetDir` for `.d.ts`/`.js`/`.ts` files and expands `@example`
+ * declarations in place against the snippet index. Returns the written paths.
+ *
+ * @group Inline
+ */
+export const injectIntoFiles = async (input: {
+  readonly targetDir: string;
+  readonly snippetIndex: ReadonlyMap<string, Snippet>;
+  readonly packageName: string;
+}): Promise<readonly string[]> => {
+  const files = await collectFiles(
+    input.targetDir,
+    (filePath) =>
+      filePath.endsWith(".d.ts") ||
+      filePath.endsWith(".js") ||
+      filePath.endsWith(".ts"),
+  );
+  const written: string[] = [];
+
+  for (const filePath of files) {
+    const source = await readFile(filePath, "utf8");
+    const expanded = expandExamples(
+      source,
+      input.snippetIndex,
+      input.packageName,
+      filePath,
+    );
+
+    if (expanded !== source) {
+      await writeFile(filePath, expanded);
+      written.push(filePath);
+    }
+  }
+
+  return written;
+};
+
+/** Default target directory when none is supplied to the inject command. */
+export const DEFAULT_INJECT_TARGET = join("dist");

package/src/snippets.ts

@@ -0,0 +1,326 @@
+import { readFile, readdir } from "node:fs/promises";
+import path from "node:path";
+
+/**
+ * A tested documentation snippet extracted from a `#section ... #endsection`
+ * block. The snippet code is exercised by the test file it lives in, so it is
+ * safe to publish into docs, JSDoc declarations, or generated code.
+ *
+ * @group Snippets
+ */
+export interface Snippet {
+  /** The tested code between `#section` and `#endsection`, dedented. */
+  readonly code: string;
+  /** Absolute or root-relative path of the test file hosting the block. */
+  readonly filePath: string;
+  /** 1-based line of the `#section` marker. */
+  readonly startLine: number;
+  /** The human-readable title from the `#section` marker. */
+  readonly title: string;
+  /** URL-safe slug derived from {@link Snippet.title}. */
+  readonly slug: string;
+  /** The expected-value lines extracted from the assertions that follow. */
+  readonly expected: string | null;
+}
+
+/** A folder of files matching a predicate, sorted by path. */
+export const collectFiles = async (
+  directory: string,
+  predicate: (filePath: string) => boolean,
+): Promise<readonly string[]> => {
+  const entries = await readdir(directory, { withFileTypes: true }).catch(
+    (error: unknown) => {
+      if (
+        error instanceof Error &&
+        "code" in error &&
+        error.code === "ENOENT"
+      ) {
+        return [];
+      }
+
+      throw error;
+    },
+  );
+  const files: string[] = [];
+
+  for (const entry of entries) {
+    const entryPath = path.join(directory, entry.name);
+
+    if (entry.isDirectory()) {
+      files.push(...(await collectFiles(entryPath, predicate)));
+      continue;
+    }
+
+    if (entry.isFile() && predicate(entryPath)) {
+      files.push(entryPath);
+    }
+  }
+
+  return files.sort();
+};
+
+const sectionPattern = /^\s*\/\/\s*#section\s*-\s*(.+)\s*$/u;
+const endsectionPattern = /^\s*\/\/\s*#endsection\s*$/u;
+
+/**
+ * Extracts every `#section ... #endsection` snippet from a test source. Nested
+ * or unclosed sections throw.
+ *
+ * @group Snippets
+ */
+export const extractSnippets = (
+  source: string,
+  filePath: string,
+): readonly Snippet[] => {
+  const snippets: Snippet[] = [];
+  const lines = source.split("\n");
+  let current:
+    | {
+        code: string[];
+        filePath: string;
+        startLine: number;
+        title: string;
+      }
+    | undefined;
+
+  lines.forEach((line, index) => {
+    const section = line.match(sectionPattern);
+
+    if (section) {
+      if (current) {
+        throw new Error(
+          `Nested documentation snippet in ${filePath}:${index + 1}`,
+        );
+      }
+
+      current = {
+        code: [],
+        filePath,
+        startLine: index + 1,
+        title: section[1]?.trim() ?? "",
+      };
+      return;
+    }
+
+    if (endsectionPattern.test(line)) {
+      if (current) {
+        snippets.push({
+          ...current,
+          code: dedent(current.code.join("\n")).trim(),
+          expected: null,
+          slug: slugify(current.title),
+        });
+      }
+
+      current = undefined;
+      return;
+    }
+
+    if (current) {
+      current.code.push(line);
+    }
+  });
+
+  if (current) {
+    throw new Error(
+      `Unclosed documentation snippet in ${filePath}:${current.startLine}`,
+    );
+  }
+
+  return snippets;
+};
+
+/**
+ * Extracts the expected-result lines that immediately follow a snippet's
+ * `#endsection` marker (the assertions testing it), as plain code. Returns
+ * `null` when there is nothing to show.
+ *
+ * @group Snippets
+ */
+export const extractSnippetExpected = (
+  testSource: string,
+  snippet: Snippet,
+): string | null => {
+  const lines = testSource.split("\n");
+  const sectionLine = lines.findIndex(
+    (line, idx) => idx >= snippet.startLine - 1 && endsectionPattern.test(line),
+  );
+
+  if (sectionLine === -1) {
+    return null;
+  }
+
+  const expectedLines: string[] = [];
+  const sectionIndent = lines[sectionLine]?.match(/^\s*/u)?.[0] ?? "";
+  let i = sectionLine + 1;
+
+  for (; i < lines.length; i++) {
+    const line = lines[i] ?? "";
+
+    if (line.trim().length === 0) {
+      continue;
+    }
+
+    const lineIndent = line.match(/^\s*/u)?.[0] ?? "";
+
+    if (lineIndent.length < sectionIndent.length) {
+      break;
+    }
+
+    expectedLines.push(line);
+  }
+
+  if (expectedLines.length === 0) {
+    return null;
+  }
+
+  const code = dedent(expectedLines.join("\n")).trim();
+  return code.length > 0 ? code : null;
+};
+
+/**
+ * Collects every tested snippet from the `*.test.ts` files under `srcDir`,
+ * returning both the flat list and a title index. Duplicate titles throw.
+ *
+ * @group Snippets
+ */
+export const collectTestSnippets = async (input: {
+  readonly packageName: string;
+  readonly rootDir: string;
+  readonly srcDir: string;
+}): Promise<{
+  snippetIndex: ReadonlyMap<string, Snippet>;
+  snippets: readonly Snippet[];
+}> => {
+  const testFiles = await collectFiles(input.srcDir, (filePath) =>
+    filePath.endsWith(".test.ts"),
+  );
+  const snippets: Snippet[] = [];
+
+  for (const filePath of testFiles) {
+    const source = await readFile(filePath, "utf8");
+    const relativePath = path.relative(input.rootDir, filePath);
+    const extracted = extractSnippets(source, relativePath);
+
+    for (const snippet of extracted) {
+      const raw = extractSnippetExpected(source, snippet);
+      snippets.push({
+        ...snippet,
+        expected: raw ? transformExpectedToResult(raw) : null,
+      });
+    }
+  }
+
+  return {
+    snippetIndex: buildSnippetIndex(snippets, input.packageName),
+    snippets,
+  };
+};
+
+/**
+ * Builds the title → snippet index, throwing on duplicate or empty titles.
+ *
+ * @group Snippets
+ */
+export const buildSnippetIndex = (
+  snippets: readonly Snippet[],
+  packageName: string,
+): ReadonlyMap<string, Snippet> => {
+  const index = new Map<string, Snippet>();
+
+  for (const snippet of snippets) {
+    const key = normalizeExampleName(snippet.title);
+
+    if (index.has(key)) {
+      throw new Error(
+        `Duplicate tested snippet "${snippet.title}" in ${packageName}.`,
+      );
+    }
+
+    index.set(key, snippet);
+  }
+
+  return index;
+};
+
+/** Normalizes a snippet title into its lookup key. */
+export const normalizeExampleName = (value: string): string =>
+  value.trim().toLowerCase();
+
+/** Converts a snippet title into a URL-safe slug. */
+export const slugify = (value: string): string =>
+  value
+    .replace(/^@/u, "")
+    .replaceAll("/", "-")
+    .replace(/[^a-zA-Z0-9-]+/gu, "-")
+    .toLowerCase();
+
+const findMatchingCloseParen = (code: string, openIndex: number): number => {
+  let depth = 1;
+
+  for (let i = openIndex + 1; i < code.length; i++) {
+    if (code[i] === "(") {
+      depth++;
+    } else if (code[i] === ")") {
+      depth--;
+
+      if (depth === 0) {
+        return i;
+      }
+    }
+  }
+
+  return -1;
+};
+
+/**
+ * Reduces a block of `expect(...).toBe(...)` assertions into just the expected
+ * values. Falls back to the raw code when no `expect` calls are present.
+ */
+export const transformExpectedToResult = (code: string): string => {
+  const results: string[] = [];
+  let idx = 0;
+
+  while (idx < code.length) {
+    const expectIdx = code.indexOf("expect(", idx);
+
+    if (expectIdx === -1) {
+      break;
+    }
+
+    const expectOpen = expectIdx + "expect(".length;
+    const expectClose = findMatchingCloseParen(code, expectOpen);
+
+    if (expectClose === -1) {
+      break;
+    }
+
+    const matcherOpen = code.indexOf("(", expectClose + 1);
+
+    if (matcherOpen === -1) {
+      break;
+    }
+
+    const matcherClose = findMatchingCloseParen(code, matcherOpen);
+
+    if (matcherClose === -1) {
+      break;
+    }
+
+    const value = code.slice(matcherOpen + 1, matcherClose).trim();
+    results.push(value);
+    idx = matcherClose + 1;
+  }
+
+  return results.length > 0 ? results.join("\n") : code;
+};
+
+const dedent = (value: string): string => {
+  const lines = value.replace(/\s+$/u, "").split("\n");
+  const indentation = lines
+    .filter((line) => line.trim().length > 0)
+    .map((line) => line.match(/^\s*/u)?.[0].length ?? 0);
+  const size = indentation.length === 0 ? 0 : Math.min(...indentation);
+
+  return lines.map((line) => line.slice(size)).join("\n");
+};

package/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist",
+    "tsBuildInfoFile": "dist/.tsbuildinfo"
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["src/**/*.test.ts"]
+}