refactor: widespread reworking (#11)

Co-authored-by: T6 <t6@t6.fyi>

.vscode/extensions.json

@@ -4,8 +4,6 @@
     "denoland.vscode-deno",
     "dprint.dprint",
     "esbenp.prettier-vscode",
-    "ms-azuretools.vscode-docker",
-    "streetsidesoftware.code-spell-checker",
-    "vadimcn.vscode-lldb"
+    "streetsidesoftware.code-spell-checker"
   ]
 }

README.md

@@ -1,17 +1,3 @@
-# `trun`
+# `egts`
 
-CLI test utility for Deno and the Browser
-
-## Flags
-
-```sh
---browser           # whether to run tests in the browser
---browser-exec-path # path to the browser binary
---concurrency       # number of tests to be run in parallel
---headless          # whether to run the browser in headless mode
---ignore            # name of ignore file; should contain list of glob patterns to not match
---include           # glob pattern of files to match
---import-map        # name of deno import map file
---output            # name of file to output test results to
---reload            # passed through to deno
-```
+Example-related utilities used in [Capi](https://github.com/paritytech/capi).

deno.jsonc

@@ -7,6 +7,7 @@
     "noUncheckedIndexedAccess": true,
     "useUnknownInCatchVariables": true
   },
+  "importMap": "import_map.json",
   "include": ["."],
   "lock": false,
   "lint": {
@@ -28,6 +29,7 @@
     }
   },
   "tasks": {
-    "udd": "deno run -A _tasks/udd.ts"
+    "udd": "deno run -A _tasks/udd.ts",
+    "moderate": "deno run -A https://deno.land/x/moderate@0.0.5/mod.ts && dprint fmt"
   }
 }

deps/case.ts

@@ -0,0 +1 @@
+export * from "https://deno.land/x/case@2.1.1/mod.ts"

deps/esbuild.ts

@@ -1 +1 @@
-export * from "https://deno.land/x/esbuild@v0.17.12/mod.js"
+export * from "https://deno.land/x/esbuild@v0.17.15/mod.js"

deps/scale.ts

@@ -0,0 +1 @@
+export * from "https://deno.land/x/scale@v0.11.2/mod.ts"

deps/std/assert.ts

@@ -1 +1 @@
-export * from "https://deno.land/std@0.180.0/testing/asserts.ts"
+export * from "https://deno.land/std@0.182.0/testing/asserts.ts"

deps/std/async.ts

@@ -1 +1 @@
-export * from "https://deno.land/std@0.180.0/async/mod.ts"
+export * from "https://deno.land/std@0.182.0/async/deferred.ts"

deps/std/datetime.ts

@@ -0,0 +1 @@
+export * from "https://deno.land/std@0.182.0/datetime/mod.ts"

deps/std/encoding/hex.ts

@@ -0,0 +1 @@
+export * from "https://deno.land/std@0.182.0/encoding/hex.ts"

deps/std/flags.ts

@@ -1 +1 @@
-export * from "https://deno.land/std@0.180.0/flags/mod.ts"
+export * from "https://deno.land/std@0.182.0/flags/mod.ts"

deps/std/fmt/colors.ts

@@ -0,0 +1 @@
+export * from "https://deno.land/std@0.182.0/fmt/colors.ts"

deps/std/fs.ts

@@ -1 +1 @@
-export * from "https://deno.land/std@0.180.0/fs/mod.ts"
+export * from "https://deno.land/std@0.182.0/fs/mod.ts"

deps/std/io.ts

@@ -1 +1 @@
-export * from "https://deno.land/std@0.180.0/io/mod.ts"
+export * from "https://deno.land/std@0.182.0/io/mod.ts"

deps/std/path.ts

@@ -1 +1 @@
-export * from "https://deno.land/std@0.180.0/path/mod.ts"
+export * from "https://deno.land/std@0.182.0/path/mod.ts"

deps/std/streams.ts

@@ -1 +1 @@
-export * from "https://deno.land/std@0.180.0/streams/mod.ts"
+export * from "https://deno.land/std@0.182.0/streams/mod.ts"

dprint.json

@@ -11,10 +11,9 @@
     "lineWidth": 80,
     "textWrap": "always"
   },
-  "includes": ["**.{dockerfile,json,md,toml,ts,tsx}"],
+  "includes": ["**.{json,md,toml,ts,tsx}"],
   "excludes": [""],
   "plugins": [
-    "https://plugins.dprint.dev/dockerfile-0.3.0.wasm",
     "https://plugins.dprint.dev/json-0.17.0.wasm",
     "https://plugins.dprint.dev/markdown-0.15.2.wasm",
     "https://plugins.dprint.dev/toml-0.5.4.wasm",

examples/basic.eg.md

@@ -0,0 +1,46 @@
+<!-- This file is @generated by egts -->
+
+# Example
+
+Welcome to egts. This very script is an egts.
+The jsdoc section above serves as frontmatter.
+The code serves as to-be markdown code fences.
+And the comments serve as ordinary lines of markdown body.
+
+Bring imports into scope.
+
+```ts
+import { date, description, stability, tags, title, toMarkdown } from "egts"
+```
+
+Compile an egts of this very script!
+
+```ts
+const result = toMarkdown("basic.eg.ts", await Deno.readTextFile(new URL(import.meta.url)), {
+  title,
+  tags: tags(["example", "docs", "deno", "typescript"]),
+  date: date("yyyy-MM-dd"),
+  description,
+  stability,
+})
+```
+
+Log out the typed frontmatter.
+
+```ts
+console.log(result.frontmatter)
+```
+
+Write the result to the fs.
+
+```ts
+await Deno.writeTextFile(
+  new URL(import.meta.resolve("./basic.eg.md")),
+  `<!-- This file is @generated by egts -->
+
+# ${result.frontmatter.title}
+
+${result.content}
+`,
+)
+```

examples/basic.eg.ts

@@ -0,0 +1,39 @@
+/**
+ * @title Example
+ * @tags example,docs,deno,typescript
+ * @date 2023-10-10
+ * @description This description can be very long and even span
+ * multiple lines. It will be parsed as expected.
+ * @stability experiment
+ */
+
+/// Welcome to egts. This very script is an egts.
+/// The jsdoc section above serves as frontmatter.
+/// The code serves as to-be markdown code fences.
+/// And the comments serve as ordinary lines of markdown body.
+
+/// Bring imports into scope.
+import { date, description, stability, tags, title, toMarkdown } from "egts"
+
+/// Compile an egts of this very script!
+const result = toMarkdown("basic.eg.ts", await Deno.readTextFile(new URL(import.meta.url)), {
+  title,
+  tags: tags(["example", "docs", "deno", "typescript"]),
+  date: date("yyyy-MM-dd"),
+  description,
+  stability,
+})
+
+/// Log out the typed frontmatter.
+console.log(result.frontmatter)
+
+/// Write the result to the fs.
+await Deno.writeTextFile(
+  new URL(import.meta.resolve("./basic.eg.md")),
+  `<!-- This file is @generated by egts -->
+
+# ${result.frontmatter.title}
+
+${result.content}
+`,
+)

frontmatter.ts

@@ -0,0 +1,43 @@
+const rFrontmatterFile = /^\s*\/\*\*(?<comment>.+?)\*\/\s*(?<body>.*)$/s
+const rLeadingAsterisk = /^\s*(?:\* ?)?/gm
+const rTagStart = /^(?=@\w+)/m
+const rTag = /^@(?<key>\w+)(\s+(?<value>.*))?$/s
+
+export function parseFrontmatter<F extends Record<string, unknown>>(
+  pathname: string,
+  src: string,
+  parsers: FrontmatterParsers<F>,
+): ParseFrontmatterResult<F> {
+  const fileMatch = rFrontmatterFile.exec(src)
+  if (!fileMatch) throw new Error(`Could not extract module comment from "${pathname}".`)
+  const { comment = "", body = "" } = fileMatch.groups ?? {}
+  const commentContent = comment.replace(rLeadingAsterisk, "").trim()
+  const tagsText = commentContent.split(rTagStart)
+  const frontmatterRaw = Object.fromEntries(
+    tagsText.map((pairText) => {
+      const tagMatch = rTag.exec(pairText)
+      if (!tagMatch) throw new Error(`Error when attempting to match tag in "${pathname}"`)
+      const { key = "", value = "" } = tagMatch.groups ?? {}
+      return [key, value.trim()]
+    }),
+  )
+  const frontmatter = {} as F
+  for (const [key, parse] of Object.entries(parsers)) {
+    try {
+      frontmatter[key as keyof F] = parse(frontmatterRaw[key])
+    } catch (e) {
+      throw new Error(`Failed to parse "${key}" from "${pathname}"\n${Deno.inspect(e)}`)
+    }
+  }
+  return { frontmatter, body }
+}
+
+export type FrontmatterParsers<F extends Record<string, unknown>> = {
+  [K in keyof F]: FrontmatterParser<F[K]>
+}
+export type FrontmatterParser<T> = (raw: string | undefined) => T
+
+export interface ParseFrontmatterResult<F extends Record<string, unknown>> {
+  frontmatter: F
+  body: string
+}

frontmatter_parsers.ts

@@ -0,0 +1,35 @@
+import { titleCase } from "./deps/case.ts"
+import * as $ from "./deps/scale.ts"
+import * as datetime from "./deps/std/datetime.ts"
+import { FrontmatterParser } from "./frontmatter.ts"
+
+export const title: FrontmatterParser<string> = (raw) => {
+  $.assert($.str, raw)
+  return titleCase(raw)
+}
+
+export const description: FrontmatterParser<string> = (raw) => {
+  $.assert($.str, raw)
+  return raw
+}
+
+const $stability = $.literalUnion(["experiment", "unstable", "nearing", "stable"])
+export const stability: FrontmatterParser<$.Native<typeof $stability>> = (raw) => {
+  $.assert($stability, raw)
+  return raw
+}
+
+export function tags<T extends string>(allowed: T[]): FrontmatterParser<T[]> {
+  return (raw) => {
+    const tags = raw?.split(",")
+    $.assert($.array($.literalUnion(allowed)), tags)
+    return tags
+  }
+}
+
+export function date(format: string): FrontmatterParser<Date> {
+  return (raw) => {
+    $.assert($.str, raw)
+    return datetime.parse(raw, format)
+  }
+}

import_map.json

@@ -0,0 +1,7 @@
+{
+  "scopes": {
+    "examples/": {
+      "egts": "./mod.ts"
+    }
+  }
+}