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 · 03db567 · 03db567
1 parent 4e23d2d
commit 03db567
Show file tree

Hide file tree

Showing 27 changed files with 1,167 additions and 339 deletions.
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 <[email protected]> (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"
  }
 }