@smitejs/snippets 2.0.0-SNAPSHOT

package/dist/snippets.js

@@ -0,0 +1,209 @@
+import { readFile, readdir } from "node:fs/promises";
+import path from "node:path";
+/** A folder of files matching a predicate, sorted by path. */
+export const collectFiles = async (directory, predicate) => {
+    const entries = await readdir(directory, { withFileTypes: true }).catch((error) => {
+        if (error instanceof Error &&
+            "code" in error &&
+            error.code === "ENOENT") {
+            return [];
+        }
+        throw error;
+    });
+    const files = [];
+    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, filePath) => {
+    const snippets = [];
+    const lines = source.split("\n");
+    let current;
+    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, snippet) => {
+    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 = [];
+    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) => {
+    const testFiles = await collectFiles(input.srcDir, (filePath) => filePath.endsWith(".test.ts"));
+    const snippets = [];
+    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, packageName) => {
+    const index = new Map();
+    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) => value.trim().toLowerCase();
+/** Converts a snippet title into a URL-safe slug. */
+export const slugify = (value) => value
+    .replace(/^@/u, "")
+    .replaceAll("/", "-")
+    .replace(/[^a-zA-Z0-9-]+/gu, "-")
+    .toLowerCase();
+const findMatchingCloseParen = (code, openIndex) => {
+    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) => {
+    const results = [];
+    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) => {
+    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/docs/index.md

@@ -0,0 +1,22 @@
+# @smitejs/snippets
+
+Generate docs, JSDoc examples, and code from **tried-and-tested** code — the
+`#section … #endsection` blocks living inside your test files.
+
+Use `smite-snippets` (or the `@smitejs/snippets` exports) to:
+
+- **inject** — expand `@example <Title>` JSDoc lines in declarations/sources
+  with the tested snippet, rendered as a fenced ```ts block.
+- **document** — expand `@example <Title>` lines in concept markdown through
+  `expandMarkdown`, replacing them with placeholders you render to HTML.
+- **generate** — expand `// @snippet <Title>` marker lines in template/code
+  files with the tested snippet via `expandTemplate`.
+
+`create-smite-app` uses this machinery to ship `http`/`serverless` templates
+whose app code is byte-for-byte the tested snippets.
+
+```bash
+smite-snippets index packages/http/src --package @smitejs/http
+smite-snippets inject packages/http/src dist --package @smitejs/http
+smite-snippets template paths/to/template out --index index.json
+```

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@smitejs/snippets",
+  "version": "2.0.0-SNAPSHOT",
+  "description": "Generate docs, JSDoc examples, and code from tried-and-tested #section snippets.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/githiago-f/smite.git"
+  },
+  "homepage": "https://github.com/githiago-f/smite#readme",
+  "bugs": {
+    "url": "https://github.com/githiago-f/smite/issues"
+  },
+  "type": "module",
+  "bin": {
+    "smite-snippets": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "!dist/**/*.test.*", "!dist/.tsbuildinfo"],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "commander": "^15.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0"
+  },
+  "sideEffects": false
+}

package/src/cli.ts

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import process from "node:process";
+import { Command } from "commander";
+import { expandTemplate } from "./expand.js";
+import { injectIntoFiles } from "./inject.js";
+import {
+  buildSnippetIndex,
+  collectFiles,
+  collectTestSnippets,
+} from "./snippets.js";
+import type { Snippet } from "./snippets.js";
+
+const program = new Command();
+const colorEnabled =
+  process.stdout.isTTY === true && process.env.NO_COLOR === undefined;
+const paint =
+  (code: number) =>
+  (text: string): string =>
+    colorEnabled ? `\u001b[${code}m${text}\u001b[0m` : text;
+const green = paint(32);
+const cyan = paint(36);
+const red = paint(31);
+
+const collectFor = async (src: string, packageName: string) => {
+  const { snippetIndex } = await collectTestSnippets({
+    packageName,
+    rootDir: process.cwd(),
+    srcDir: resolve(process.cwd(), src),
+  });
+  return snippetIndex;
+};
+
+const loadIndex = async (
+  file: string,
+): Promise<ReadonlyMap<string, Snippet>> => {
+  const raw = JSON.parse(await readFile(resolve(process.cwd(), file), "utf8"));
+  return buildSnippetIndex(raw as Snippet[], "index");
+};
+
+program
+  .name("smite-snippets")
+  .description(
+    "Generate docs, JSDoc examples, and code from tested #section snippets.",
+  )
+  .version("0.1.0");
+
+program
+  .command("index")
+  .description(
+    "Collect tested snippets from a package's src test files as JSON",
+  )
+  .argument("<src>", "package source directory holding *.test.ts files")
+  .requiredOption("--package <name>", "package name used in error messages")
+  .action(async (src: string, options: { package: string }) => {
+    const { snippets } = await collectTestSnippets({
+      packageName: options.package,
+      rootDir: process.cwd(),
+      srcDir: resolve(process.cwd(), src),
+    });
+    process.stdout.write(`${JSON.stringify(snippets, null, 2)}\n`);
+  });
+
+program
+  .command("inject")
+  .description(
+    "Expand @example JSDoc references in declaration/source files in place",
+  )
+  .argument("<src>", "package source directory holding *.test.ts files")
+  .argument("<target>", "directory to expand @example into, defaults to ./dist")
+  .requiredOption("--package <name>", "package name used in error messages")
+  .action(async (src: string, target: string, options: { package: string }) => {
+    const snippetIndex = await collectFor(src, options.package);
+    const written = await injectIntoFiles({
+      targetDir: resolve(process.cwd(), target),
+      snippetIndex,
+      packageName: options.package,
+    });
+    for (const filePath of written) {
+      console.log(`${green("Injected")} ${cyan(filePath)}`);
+    }
+  });
+
+program
+  .command("template")
+  .description(
+    "Expand // @snippet markers in a template tree into an output directory",
+  )
+  .argument("<src>", "template directory (files may carry // @snippet markers)")
+  .argument("<out>", "output directory for the expanded tree")
+  .requiredOption(
+    "--index <file>",
+    "JSON snippet index produced by `smite-snippets index`",
+  )
+  .action(async (src: string, out: string, options: { index: string }) => {
+    const snippetIndex = await loadIndex(options.index);
+    const sourceDir = resolve(process.cwd(), src);
+    const outDir = resolve(process.cwd(), out);
+    const files = await collectFiles(sourceDir, () => true);
+
+    for (const filePath of files) {
+      const source = await readFile(filePath, "utf8");
+      const relativePath = filePath.slice(sourceDir.length + 1);
+      const expanded = expandTemplate(
+        source,
+        snippetIndex,
+        "template",
+        relativePath,
+      );
+      const targetPath = join(outDir, relativePath);
+      await mkdir(dirname(targetPath), { recursive: true });
+      await writeFile(targetPath, expanded);
+    }
+  });
+
+try {
+  await program.parseAsync(process.argv);
+} catch (error) {
+  console.error(red(error instanceof Error ? error.message : String(error)));
+  process.exitCode = 1;
+}

package/src/docs.test.ts

@@ -0,0 +1,68 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import {
+  collectFiles,
+  collectTestSnippets,
+  expandExamples,
+  normalizeExampleName,
+} from "./index.js";
+
+const packageName = "@smitejs/snippets";
+const rootDir = process.cwd();
+const srcDir = join(rootDir, "packages/snippets/src");
+
+const exampleReferences = async () => {
+  const { snippetIndex } = await collectTestSnippets({
+    packageName,
+    rootDir,
+    srcDir,
+  });
+  const files = await collectFiles(srcDir, (filePath) =>
+    filePath.endsWith(".ts"),
+  );
+  const references: Array<{ filePath: string; title: string }> = [];
+
+  for (const filePath of files) {
+    const source = await readFile(filePath, "utf8");
+
+    for (const match of source.matchAll(
+      /^(\s*\*[^\S\r\n]*)@example[^\S\r\n]+([^\r\n]+?)\s*$/gmu,
+    )) {
+      references.push({ filePath, title: match[2]?.trim() ?? "" });
+    }
+  }
+
+  return { snippetIndex, references };
+};
+
+describe("documentation integrity", () => {
+  it("every @example resolves to a tested #section snippet", async () => {
+    const { snippetIndex, references } = await exampleReferences();
+    const missing = references
+      .filter(({ title }) => !snippetIndex.has(normalizeExampleName(title)))
+      .map(
+        ({ filePath, title }) =>
+          `- Missing tested snippet "${title}" in ${filePath}`,
+      );
+    expect(missing).toEqual([]);
+  });
+
+  it("renders each referenced snippet into a code block", async () => {
+    const { snippetIndex } = await collectTestSnippets({
+      packageName,
+      rootDir,
+      srcDir,
+    });
+
+    for (const title of snippetIndex.keys()) {
+      const rendered = expandExamples(
+        ` * @example ${title}\n`,
+        snippetIndex,
+        packageName,
+        "synthetic.d.ts",
+      );
+      expect(rendered).toContain("```ts");
+    }
+  });
+});

package/src/expand.ts

@@ -0,0 +1,165 @@
+import { normalizeExampleName } from "./snippets.js";
+import type { Snippet } from "./snippets.js";
+
+/**
+ * A placeholder/render pair produced by {@link expandMarkdownExamples}. The
+ * caller scans a rendered document for each placeholder and replaces it with
+ * the rendered snippet markup.
+ *
+ * @group Markdown
+ */
+export interface MarkdownInjectable {
+  readonly placeholder: string;
+  readonly snippet: Snippet;
+}
+
+const exampleTag = /^(\s*\*[^\S\r\n]*)@example[^\S\r\n]+([^\r\n]+?)\s*$/gmu;
+
+/**
+ * Expands every JSDoc `@example <Title>` line in a source string with the
+ * matching tested snippet, rendered as a fenced code block. Throws when a
+ * referenced snippet is missing. The code must not contain a closing JSDoc
+ * comment sequence (asterisk followed by a slash), which would close the
+ * comment early.
+ *
+ * @group Inline
+ * @example Expand @example declarations
+ */
+export const expandExamples = (
+  source: string,
+  snippetIndex: ReadonlyMap<string, Snippet>,
+  packageName: string,
+  filePath: string,
+): string => {
+  const unresolved: string[] = [];
+  const expanded = source.replace(
+    exampleTag,
+    (line, prefix: string, title: string) => {
+      const snippet = snippetIndex.get(normalizeExampleName(title));
+
+      if (!snippet) {
+        unresolved.push(title);
+        return line;
+      }
+
+      if (snippet.code.includes("*/")) {
+        throw new Error(
+          [
+            `Cannot expand @example "${title}" in ${filePath} (${packageName}).`,
+            'The snippet code contains "*/", which would close the JSDoc',
+            "comment early and corrupt the emitted declaration.",
+            'Rewrite the snippet to avoid "*/" (e.g. a cron schedule without',
+            'a "*/" step) before releasing.',
+          ].join("\n"),
+        );
+      }
+
+      return renderExample(prefix, snippet.code);
+    },
+  );
+
+  if (unresolved.length > 0) {
+    throw new Error(
+      [
+        `Cannot expand @example references in ${filePath} (${packageName}).`,
+        ...unresolved.map((title) => `- Missing tested snippet: ${title}`),
+      ].join("\n"),
+    );
+  }
+
+  return expanded;
+};
+
+/** Renders a snippet into a JSDoc fenced ```ts block with the given prefix. */
+export const renderExample = (prefix: string, code: string): string =>
+  [
+    `${prefix}@example`,
+    `${prefix}\`\`\`ts`,
+    ...code.split("\n").map((line) => `${prefix}${line}`),
+    `${prefix}\`\`\``,
+  ].join("\n");
+
+/**
+ * Expands `// @snippet <Title>` marker lines in a template/code file by
+ * replacing each with the tested snippet code. The route either keeps files
+ * untouched when they carry no markers. Throws on unresolved markers.
+ *
+ * @group Template
+ * @example Expand @snippet into a source file
+ */
+export const expandTemplate = (
+  source: string,
+  snippetIndex: ReadonlyMap<string, Snippet>,
+  packageName: string,
+  filePath: string,
+): string => {
+  const unresolved: string[] = [];
+
+  const expanded = source.replace(
+    /(\/\/\s*@snippet\s+[^\r\n]+)(?:\r?\n|$)/gu,
+    (marker, markerText: string) => {
+      const title = markerText.replace(/^\/\/\s*@snippet\s+/u, "").trim();
+      const snippet = snippetIndex.get(normalizeExampleName(title));
+
+      if (!snippet) {
+        unresolved.push(title);
+        return marker;
+      }
+
+      return `${snippet.code}\n`;
+    },
+  );
+
+  if (unresolved.length > 0) {
+    throw new Error(
+      [
+        `Cannot expand @snippet references in ${filePath} (${packageName}).`,
+        ...unresolved.map((title) => `- Missing tested snippet: ${title}`),
+      ].join("\n"),
+    );
+  }
+
+  return expanded;
+};
+
+/**
+ * Scans a concept-document markdown source for `@example <Title>` lines,
+ * replacing them with placeholder lines and returning the list of injectables.
+ * The caller renders the placeholders to HTML after markdown conversion so
+ * code fences survive the renderer.
+ *
+ * @group Markdown
+ */
+export const expandMarkdown = (
+  source: string,
+  snippetIndex: ReadonlyMap<string, Snippet>,
+  packageName: string,
+  filePath: string,
+): { body: string; examples: readonly MarkdownInjectable[] } => {
+  const injectables: MarkdownInjectable[] = [];
+  const scrubbed: string[] = [];
+
+  for (const line of source.split("\n")) {
+    const example = line.match(/^\s*@example\s+(.+?)\s*$/u);
+
+    if (example) {
+      const title = example[1]?.trim() ?? "";
+      const snippet = snippetIndex.get(normalizeExampleName(title));
+
+      if (!snippet) {
+        throw new Error(
+          `Missing tested snippet "${title}" referenced by ${filePath} (${packageName}).`,
+        );
+      }
+
+      const placeholder = `SMITE_EXAMPLE_${injectables.length}`;
+      injectables.push({ placeholder, snippet });
+      scrubbed.push("", placeholder, "");
+      continue;
+    }
+
+    scrubbed.push(line);
+  }
+
+  return { body: scrubbed.join("\n"), examples: injectables };
+};