wip

README.md

@@ -39,4 +39,5 @@ _Status: alpha_
 
 ## TODOs
 
-- rename opencodegraphdata -> something shorter
+- item.ui and item.ai
+- add support for resolving annotations (because )

client/web-playground/package.json

@@ -24,6 +24,7 @@
     "@codemirror/lint": "^6.4.2",
     "@opencodegraph/client": "workspace:*",
     "@opencodegraph/codemirror-extension": "workspace:*",
+    "@opencodegraph/provider-docs": "workspace:*",
     "@opencodegraph/provider-links": "workspace:*",
     "@opencodegraph/provider-storybook": "workspace:*",
     "@opencodegraph/ui-react": "workspace:*",

client/web-playground/src/demo/settings.ts

@@ -1,8 +1,23 @@
 import { type ProviderSettings } from '@opencodegraph/client'
 
+const USE_STORED_CORPUS = true
+
 async function getProviders(): Promise<Record<string, ProviderSettings | boolean>> {
     const providerSettings: Record<string, ProviderSettings | boolean> = {
-        '../../../../provider/hello-world/index.ts': true,
+        '../../../../provider/hello-world/index.ts': false,
+        '../../../../provider/docs/src/provider/provider.ts': {
+            corpus: USE_STORED_CORPUS
+                ? {
+                      url: new URL(
+                          'tmp-ocg-provider-docs/sourcegraph-docs-old-web-corpus.json',
+                          import.meta.url
+                      ).toString(),
+                  }
+                : {
+                      entryPage: 'http://localhost:5800/docs/start',
+                      prefix: 'http://localhost:5800/docs',
+                  },
+        } satisfies import('@opencodegraph/provider-docs').Settings,
         '../../../../provider/links/index.ts': {
             links: [
                 {
@@ -38,7 +53,9 @@ async function getProviders(): Promise<Record<string, ProviderSettings | boolean
         } satisfies import('@opencodegraph/provider-storybook').Settings,
     }
 
-    const providerModules = import.meta.glob('../../../../provider/*/index.ts', { as: 'url' })
+    const providerModules = import.meta.glob('../../../../provider/{*/index.ts,docs/src/provider/provider.ts}', {
+        as: 'url',
+    })
     for (const [path, url] of Object.entries(providerModules)) {
         const providerUri = new URL(await url(), import.meta.url).toString()
         const settings = providerSettings[path] ?? true

client/web-playground/vite.config.ts

@@ -1,12 +1,15 @@
 import { resolve } from 'path'
 import react from '@vitejs/plugin-react'
-import { defineConfig } from 'vite'
+import { defineConfig, searchForWorkspaceRoot } from 'vite'
+
+// TODO(sqs): un-hardcode
+const docsProviderDataDir = resolve('/Users/sqs/tmp/ocg-provider-docs')
 
 export default defineConfig(({ mode }) => ({
     plugins: [react()],
     resolve: {
-        alias:
-            mode === 'development'
+        alias: [
+            ...(mode === 'development'
                 ? [
                       // In dev mode, build from TypeScript sources so we don't need to run `tsc -b`
                       // in the background.
@@ -17,8 +20,14 @@ export default defineConfig(({ mode }) => ({
                           replacement: '$1/src/index',
                       },
                   ]
-                : [],
+                : []),
+            {
+                find: 'tmp-ocg-provider-docs',
+                replacement: docsProviderDataDir,
+            },
+        ],
     },
+    define: {},
     css: {
         devSourcemap: true,
         modules: {
@@ -27,6 +36,9 @@ export default defineConfig(({ mode }) => ({
     },
     server: {
         port: 5900,
+        fs: {
+            allow: [searchForWorkspaceRoot(process.cwd()), docsProviderDataDir],
+        },
     },
     build: {
         emptyOutDir: false,

lib/client/src/api.ts

@@ -56,6 +56,7 @@ export function observeAnnotations<R extends Range>(
                               emitPartial ? startWith(null) : tap(),
                               catchError(error => {
                                   logger?.(`failed to get annotations: ${error}`)
+                                  console.error(error)
                                   return of(null)
                               })
                           )

lib/protocol/package.json

@@ -17,7 +17,7 @@
   ],
   "sideEffects": false,
   "scripts": {
-    "generate": "node --no-warnings=ExperimentalWarning --loader ts-node/esm/transpile-only ../schema/dev/generateJsonSchemaTypes.ts src/opencodegraph-protocol.schema.json \"import { Item, Annotation } from '@opencodegraph/schema'\" > src/opencodegraph-protocol.schema.ts && pnpm -w run format \"$PNPM_SCRIPT_SRC_DIR/src/opencodegraph-protocol.schema.ts\"",
+    "generate": "node --no-warnings=ExperimentalWarning --loader ts-node/esm/transpile-only ../schema/dev/generateJsonSchemaTypes.ts src/opencodegraph-protocol.schema.json \"import { Annotation } from '@opencodegraph/schema'\" > src/opencodegraph-protocol.schema.ts && pnpm -w run format \"$PNPM_SCRIPT_SRC_DIR/src/opencodegraph-protocol.schema.ts\"",
     "build": "pnpm run --silent generate && tsc --build",
     "test": "vitest",
     "prepublishOnly": "tsc --build --clean && pnpm run build"

lib/schema/src/opencodegraph.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "opencodegraph.schema.json#",
-  "title": "Data",
+  "title": "Schema",
   "description": "Metadata about code",
   "allowComments": true,
   "type": "object",
@@ -14,35 +14,59 @@
   },
   "definitions": {
     "Annotation": {
-      "description": "An annotation describes information relevant to a specific range in a file.",
+      "description": "An annotation describes information relevant to a file (or a range within a file).",
       "type": "object",
       "additionalProperties": false,
-      "required": ["item", "range"],
+      "required": [],
       "properties": {
-        "item": { "$ref": "#/definitions/Item" },
-        "range": { "$ref": "#/definitions/Range" }
+        "title": {
+          "description": "A descriptive title of the annotation.",
+          "type": "string"
+        },
+        "url": {
+          "description": "An external URL with more information about the annotation.",
+          "type": "string",
+          "format": "uri"
+        },
+        "ui": {
+          "description": "The human user interface of the annotation, with information for human consumption.",
+          "$ref": "#/definitions/AnnotationUI"
+        },
+        "ai": {
+          "description": "Information from the annotation intended for consumption by AI, not humans.222",
+          "$ref": "#/definitions/AssistantInfo"
+        },
+        "range": {
+          "description": "The range in the file that this annotation applies to. If not set, the annotation applies to the entire file.",
+          "$ref": "#/definitions/Range"
+        }
       }
     },
-    "Item": {
+    "AnnotationUI": {
+      "description": "The human user interface of an annotation, with information for human consumption.",
       "type": "object",
       "additionalProperties": false,
-      "required": ["title"],
       "properties": {
-        "title": { "type": "string" },
-        "detail": { "type": "string" },
-        "url": { "description": "An external URL with more information.", "type": "string", "format": "uri" },
-        "image": { "$ref": "#/definitions/ItemImage" }
+        "detail": {
+          "description": "Text containing additional details for the human, shown when they interact with the annotation.",
+          "type": "string"
+        },
+        "format": {
+          "description": "The format of the title and description (Markdown or plain text).",
+          "type": "string",
+          "enum": ["markdown", "plaintext"]
+        }
       }
     },
-    "ItemImage": {
+    "AssistantInfo": {
+      "description": "Information from an annotation intended for consumption by AI, not humans.",
       "type": "object",
       "additionalProperties": false,
-      "required": ["url"],
       "properties": {
-        "url": { "type": "string", "format": "uri" },
-        "width": { "type": "number" },
-        "height": { "type": "number" },
-        "alt": { "type": "string" }
+        "content": {
+          "description": "Text content for AI to consume.",
+          "type": "string"
+        }
       }
     },
     "Range": {

lib/schema/src/opencodegraph.schema.ts

@@ -1,31 +1,50 @@
 /**
  * Metadata about code
  */
-export interface Data {
+export interface Schema {
     annotations?: Annotation[]
 }
 /**
- * An annotation describes information relevant to a specific range in a file.
+ * An annotation describes information relevant to a file (or a range within a file).
  */
 export interface Annotation {
-    item: Item
-    range: Range
+    /**
+     * A descriptive title of the annotation.
+     */
+    title?: string
+    /**
+     * An external URL with more information about the annotation.
+     */
+    url?: string
+    ui?: AnnotationUI
+    ai?: AssistantInfo
+    range?: Range
 }
-export interface Item {
-    title: string
+/**
+ * The human user interface of the annotation, with information for human consumption.
+ */
+export interface AnnotationUI {
+    /**
+     * Text containing additional details for the human, shown when they interact with the annotation.
+     */
     detail?: string
     /**
-     * An external URL with more information.
+     * The format of the title and description (Markdown or plain text).
      */
-    url?: string
-    image?: ItemImage
+    format?: 'markdown' | 'plaintext'
 }
-export interface ItemImage {
-    url: string
-    width?: number
-    height?: number
-    alt?: string
+/**
+ * Information from the annotation intended for consumption by AI, not humans.222
+ */
+export interface AssistantInfo {
+    /**
+     * Text content for AI to consume.
+     */
+    content?: string
 }
+/**
+ * The range in the file that this annotation applies to. If not set, the annotation applies to the entire file.
+ */
 export interface Range {
     start: Position
     end: Position

package.json

@@ -57,7 +57,7 @@
     "ts-node": "^10.9.2",
     "typescript": "^5.3.3",
     "vite": "^5",
-    "vitest": "^0"
+    "vitest": "^1.1.0"
   },
   "eslintConfig": {
     "extends": "./.config/eslintrc.js"