feat: unify entity description parsing logic

and update the VSCode extension to use the body parsing logic in hover previews. Still a few polishing items to do here: - expand internal references to linked names - fix katex styling oddities but this is a reasonable enough start to at least publish as a prerelease version.
pi-base · Jun 15, 2024 · 3ffa14a · 3ffa14a
1 parent 4e23d2d
commit 3ffa14a
Show file tree

Hide file tree

Showing 28 changed files with 1,169 additions and 339 deletions.
diff --git a/.prettierignore b/.prettierignore
@@ -1,4 +1,6 @@
 coverage
 dist
+out
 pnpm-lock.yaml
 .svelte-kit
+.vscode-test
diff --git a/packages/core/package.json b/packages/core/package.json
@@ -34,7 +34,7 @@
   },
   "dependencies": {
     "debug": "^4.3.4",
-    "micromark-util-types": "1.0.2",
+    "js-yaml": "^4.1.0",
     "rehype-katex": "^6.0.3",
     "rehype-stringify": "^9.0.4",
     "remark": "^14.0.3",
@@ -49,10 +49,12 @@
   "devDependencies": {
     "@types/debug": "^4.1.12",
     "@types/hast": "^2.3.9",
+    "@types/js-yaml": "^4.0.9",
     "@types/mdast": "^3.0.15",
     "@types/unist": "^2.0.10",
     "hast-util-to-html": "^8.0.4",
     "mdast-util-from-markdown": "1.3.0",
+    "micromark-util-types": "1.0.2",
     "peggy": "^3.0.2",
     "ts-pegjs": "^4.2.1"
   }

diff --git a/packages/core/src/Document.ts b/packages/core/src/Document.ts
@@ -0,0 +1,19 @@
+import * as z from 'zod'
+import * as yaml from 'js-yaml'
+
+// TODO: unify with logic in packages/compiler
+export function parseDocument<T>(schema: z.ZodSchema<T>, contents: string) {
+  const match = contents.match(
+    /^(---)?\s*(?<frontmatter>[\s\S]*?)\s*---(?<body>[\s\S]*)/,
+  )
+  if (!match?.groups) {
+    return
+  }
+
+  const { frontmatter, body } = match.groups
+  const meta = yaml.load(frontmatter)
+  const data = { description: body.trim() }
+  const raw = typeof meta === 'object' ? { ...meta, ...data } : data
+
+  return schema.safeParse(raw)
+}
diff --git a/packages/core/src/Parser.ts b/packages/core/src/Parser.ts
@@ -13,7 +13,7 @@ import { truncate as truncator } from './Parser/truncate.js'
 import { unnest } from './Parser/unnest.js'
 
 export type Options = {
-  link: Linkers
+  link: Partial<Linkers>
   truncate?: boolean
 }
 

diff --git a/packages/core/src/Parser/references.ts b/packages/core/src/Parser/references.ts
@@ -10,12 +10,30 @@ import { ExternalLinkNode, InternalLinkNode, Linkers } from './types'
  *
  * See https://github.com/syntax-tree/mdast-util-to-hast#fields-on-nodes
  */
-export function references({ internal, external }: Linkers) {
+export function references({ internal, external }: Partial<Linkers>) {
   return (): Transformer<Root, Root> => {
     return function transformer(tree: Root) {
       visit(tree, 'internalLink', (node: InternalLinkNode) => {
         const { kind, id } = node
 
+        if (!internal) {
+          Object.assign(node, {
+            data: {
+              hName: 'span',
+              hProperties: {
+                className: 'internal-link',
+              },
+              hChildren: [
+                {
+                  type: 'text',
+                  value: `${kind}${id}`,
+                },
+              ],
+            },
+          })
+          return
+        }
+
         const { href, title } = internal([kind, id])
 
         Object.assign(node, {
@@ -36,26 +54,27 @@ export function references({ internal, external }: Linkers) {
         })
       })
 
-      visit(tree, 'externalLink', (node: ExternalLinkNode) => {
-        const { href, title } = external([node.kind, node.id])
+      external &&
+        visit(tree, 'externalLink', (node: ExternalLinkNode) => {
+          const { href, title } = external([node.kind, node.id])
 
-        Object.assign(node, {
-          data: {
-            hName: 'a',
-            hProperties: {
-              href,
-              title,
-              className: 'external-link',
-            },
-            hChildren: [
-              {
-                type: 'text',
-                value: title,
+          Object.assign(node, {
+            data: {
+              hName: 'a',
+              hProperties: {
+                href,
+                title,
+                className: 'external-link',
               },
-            ],
-          },
+              hChildren: [
+                {
+                  type: 'text',
+                  value: title,
+                },
+              ],
+            },
+          })
         })
-      })
     }
   }
 }
diff --git a/packages/core/src/Theorem.ts b/packages/core/src/Theorem.ts
@@ -21,4 +21,4 @@ export type SerializedTheorem = {
   then: Formula<number>
   description: string
   refs: Ref[]
-}
+}
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
@@ -18,6 +18,7 @@ export { type Space, SpacePage } from './Space.js'
 export { type Theorem, SerializedTheorem } from './Theorem.js'
 export { type Trait } from './Trait.js'
 export { type Version } from './Bundle.js'
+export { parseDocument } from './Document.js'
 
 export * as bundle from './Bundle.js'
 export * as formula from './Formula.js'

diff --git a/packages/vscode/.vscode/extensions.json b/packages/vscode/.vscode/extensions.json
@@ -1,5 +1,9 @@
 {
   // See http://go.microsoft.com/fwlink/?LinkId=827846
   // for the documentation about the extensions.json format
-  "recommendations": ["dbaeumer.vscode-eslint", "connor4312.esbuild-problem-matchers", "ms-vscode.extension-test-runner"]
+  "recommendations": [
+    "dbaeumer.vscode-eslint", 
+    "amodio.tsl-problem-matcher",
+    "ms-vscode.extension-test-runner"
+  ]
 }
diff --git a/packages/vscode/.vscode/tasks.json b/packages/vscode/.vscode/tasks.json
@@ -3,65 +3,27 @@
 {
 	"version": "2.0.0",
 	"tasks": [
-		{
-            "label": "watch",
-            "dependsOn": [
-                "npm: watch:tsc",
-                "npm: watch:esbuild"
-            ],
-            "presentation": {
-                "reveal": "never"
-            },
-            "group": {
-                "kind": "build",
-                "isDefault": true
-            },
-            "runOptions": {
-                "runOn": "folderOpen"
-            }
-        },
-        {
-            "type": "npm",
-            "script": "watch:esbuild",
-            "group": "build",
-            "problemMatcher": "$esbuild-watch",
-            "isBackground": true,
-            "label": "npm: watch:esbuild",
-            "presentation": {
-                "group": "watch",
-                "reveal": "never"
-            }
-        },
-		{
-            "type": "npm",
-            "script": "watch:tsc",
-            "group": "build",
-            "problemMatcher": "$tsc-watch",
-            "isBackground": true,
-            "label": "npm: watch:tsc",
-            "presentation": {
-                "group": "watch",
-                "reveal": "never"
-            }
-        },
 		{
 			"type": "npm",
-			"script": "watch-tests",
-			"problemMatcher": "$tsc-watch",
-			"isBackground": true,
-			"presentation": {
-				"reveal": "never",
-				"group": "watchers"
+			"script": "compile",
+			"group": {
+				"kind": "build",
+				"isDefault": true
 			},
-			"group": "build"
+			"problemMatcher": [
+				"$ts-webpack",
+				"$tslint-webpack"
+			]
 		},
 		{
-			"label": "tasks: watch-tests",
-			"dependsOn": [
-				"npm: watch",
-				"npm: watch-tests"
-			],
-			"problemMatcher": []
+			"type": "npm",
+			"script": "watch",
+			"group": "build",
+			"isBackground": true,
+			"problemMatcher": [
+				"$ts-webpack-watch",
+				"$tslint-webpack-watch"
+			]
 		}
 	]
-}
+}
diff --git a/packages/vscode/.vscodeignore b/packages/vscode/.vscodeignore
@@ -5,7 +5,7 @@ node_modules/**
 src/**
 .gitignore
 .yarnrc
-esbuild.js
+webpack.config.js
 vsc-extension-quickstart.md
 **/.eslintrc.json
 **/*.map

diff --git a/packages/vscode/README.md b/packages/vscode/README.md
@@ -4,18 +4,30 @@ Utilities for viewing and editing the π-base data repository in VSCode.
 
 ## Publishing
 
-Run `pnpm run publish` to publish. (`prepublish` handles bundling with `pnpm`, which is otherwise unsupported by `vsce`.)
+We follow the [recommended](https://code.visualstudio.com/api/working-with-extensions/publishing-extension#prerelease-extensions) scheme of even minor versions for stable releases and odd minor versions for pre-releases, though this is not (yet) supported by tooling.
+
+```bash
+# == Publish a prerelease ==
+# Bump version and ensure it's at 0.1.x
+pnpm run publish:preview
+
+# == Publish a stable release ==
+# Bump version and ensure it's at 0.2.x
+pnpm run publish
+```
 
 ## TODOs
 
-This is an early release. Before a 1.0-level release, we will need to
+This is an early release. Before a 1.x release, we will need to
 
+- Support a reference provider (dual to definition provider)
+  - This may be a good time to look at the parser async problem; do we already need to scan and load the whole local repo?
 - Smooth out the build process (and in particular, make sure that changes can be published by the org)
-- Add tests
+  - Add tests
 - Unify logic between core, compile, and here
 - Add editing features as discussed in [this issue](https://github.com/pi-base/web/issues/5)
 - Update the README and CHANGELOG for the extension
-- Address inlined TODOs, like error handling
+- Address inlined TODOs
 
 <!--TODO
 ## Features

diff --git a/packages/vscode/esbuild.js b/packages/vscode/esbuild.js
diff --git a/packages/vscode/package.json b/packages/vscode/package.json
@@ -10,7 +10,7 @@
   "homepage": "https://topology.pi-base.org/",
   "license": "ISC",
   "author": "James Dabbs <james.dabbs@gmail.com> (https://jdabbs.com)",
-  "version": "0.0.16",
+  "version": "0.1.18",
   "repository": {
     "type": "git",
     "url": "https://github.com/pi-base/web.git"
@@ -31,12 +31,13 @@
   },
   "scripts": {
     "vscode:prepublish": "pnpm run package",
+    "publish:preview": "vsce publish --no-dependencies --pre-release",
     "publish": "vsce publish --no-dependencies",
-    "compile": "pnpm run check-types && pnpm run lint && node esbuild.js",
+    "compile": "webpack",
     "watch": "npm-run-all -p watch:*",
-    "watch:esbuild": "node esbuild.js --watch",
+    "watch:webpack": "webpack --watch",
     "watch:tsc": "tsc --noEmit --watch --project tsconfig.json",
-    "package": "pnpm run check-types && pnpm run lint && node esbuild.js --production",
+    "package": "pnpm run check-types && pnpm run lint && webpack --mode production --devtool hidden-source-map",
     "compile-tests": "tsc -p . --outDir out",
     "watch-tests": "tsc -p . -w --outDir out",
     "pretest": "pnpm run compile-tests && pnpm run compile && pnpm run lint",
@@ -46,22 +47,23 @@
   },
   "devDependencies": {
     "@types/debug": "^4.1.12",
-    "@types/js-yaml": "^4.0.9",
     "@types/mocha": "^10.0.6",
     "@types/vscode": "^1.89.0",
+    "@types/webpack-env": "^1.18.5",
     "@typescript-eslint/eslint-plugin": "^7.7.1",
     "@typescript-eslint/parser": "^7.7.1",
     "@vscode/test-cli": "^0.0.9",
     "@vscode/test-electron": "^2.3.9",
-    "esbuild": "^0.20.2",
     "eslint": "^8.57.0",
-    "npm-run-all": "^4.1.5"
+    "npm-run-all": "^4.1.5",
+    "ts-loader": "^9.5.1",
+    "webpack": "^5.92.0",
+    "webpack-cli": "^5.1.4"
   },
   "dependencies": {
     "@pi-base/core": "workspace:*",
     "@vscode/vsce": "^2.27.0",
     "debug": "^4.3.4",
-    "js-yaml": "^4.1.0",
     "zod": "^3.23.8"
   }
 }