wip

provider/docs/README.md

@@ -1,6 +1,6 @@
 # Docs context provider for OpenCodeGraph
 
-This is a context provider for [OpenCodeGraph](https://opencodegraph.org) that indexes a documentation corpus and annotates your code with links to relevant documentation pages.
+This is a context provider for [OpenCodeGraph](https://opencodegraph.org) that adds contextual documentation to your code from an existing documentation corpus.
 
 ## Screenshot
 

provider/docs/package.json

@@ -1,19 +1,18 @@
 {
-  "name": "@opencodegraph/provider-prometheus",
-  "version": "0.0.2",
-  "description": "Hover over a Prometheus metric to see what it's doing in prod (OpenCodeGraph provider)",
+  "name": "@opencodegraph/provider-docs",
+  "version": "0.0.1",
+  "description": "Add contextual documentation to your code from an existing documentation corpus (OpenCodeGraph provider)",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/sourcegraph/opencodegraph",
-    "directory": "provider/prometheus"
+    "directory": "provider/docs"
   },
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
     "dist",
-    "index.ts",
     "!**/*.test.*",
     "README.md"
   ],

provider/docs/src/corpus/corpus.test.ts

@@ -0,0 +1,12 @@
+import { describe, expect, test } from 'vitest'
+import { createCorpus, Document } from './corpus'
+
+function doc(docID: string | number, text: string): Document {
+    return { docID: typeof docID === 'string' ? docID : docID.toString(), text }
+}
+
+describe('Corpus', () => {
+    test('#length', () => {
+        expect(createCorpus([doc(1, 'a'), doc(2, 'b')]).length).toEqual
+    })
+})

provider/docs/src/corpus/corpus.ts

@@ -0,0 +1,32 @@
+import { CorpusSearchResult } from './search'
+
+/**
+ * A documentation corpus.
+ */
+export interface Corpus {
+    search(query: string): Promise<CorpusSearchResult[]>
+    length: number
+}
+
+export interface Document {
+    docID: string
+    text: string
+}
+
+export function createCorpus(docs: Document[]): Corpus {
+    return {
+        search: query => {
+            const terms = query.split(/\s+/)
+            const results: CorpusSearchResult[] = []
+            for (const doc of docs) {
+                if (terms.some(term => doc.text.includes(term))) {
+                    results.push({ docID: doc.docID, score: 1, excerpt: doc.text })
+                }
+            }
+            return Promise.resolve(results)
+        },
+        get length(): number {
+            return docs.length
+        },
+    }
+}

provider/docs/src/corpus/search.test.ts

@@ -0,0 +1,15 @@
+import { describe, expect, test } from 'vitest'
+import { createCorpus, Document } from './corpus'
+import { CorpusSearchResult } from './search'
+
+function doc(docID: string | number, text: string): Document {
+    return { docID: typeof docID === 'string' ? docID : docID.toString(), text }
+}
+
+describe('Corpus#search', () => {
+    test('finds matches', async () => {
+        expect(await createCorpus([doc(1, 'a'), doc(2, 'b')]).search('b')).toEqual<CorpusSearchResult[]>([
+            { docID: '2', score: 1, excerpt: 'b' },
+        ])
+    })
+})

provider/docs/src/corpus/search.ts

@@ -0,0 +1,5 @@
+export interface CorpusSearchResult {
+    docID: string
+    score: number
+    excerpt: string
+}

provider/docs/index.test.ts → provider/docs/src/index.test.ts

@@ -1,6 +1,6 @@
 import { type AnnotationsResult, type CapabilitiesResult } from '@opencodegraph/provider'
 import { describe, expect, test } from 'vitest'
-import prometheus, { type Settings } from './index'
+import docs, { type Settings } from './index'
 
 describe('prometheus', () => {
     const SETTINGS: Settings = {
@@ -14,14 +14,14 @@ describe('prometheus', () => {
     }
 
     test('capabilities', async () => {
-        expect(await prometheus.capabilities({}, SETTINGS)).toStrictEqual<CapabilitiesResult>({
+        expect(await docs.capabilities({}, SETTINGS)).toStrictEqual<CapabilitiesResult>({
             selector: [{ path: '**/*.go' }],
         })
     })
 
     test('annotations', () => {
         expect(
-            prometheus.annotations(
+            docs.annotations(
                 {
                     file: 'file:///a/b.go',
                     content: `

provider/docs/index.ts → provider/docs/src/index.ts

@@ -44,19 +44,10 @@ interface MetricRegistrationPattern {
 }
 
 /**
- * An [OpenCodeGraph](https://opencodegraph.org) provider that lets you hover over a Prometheus
- * metric in your code to see what it's doing in prod and to click through to the live metrics on
- * [Prometheus](https://prometheus.io), [Grafana](https://grafana.com/), or another metrics viewer.
- *
- * These links will be visible in every dev's editor, in code search, on the code host, and in code
- * review (assuming all of those tools have OpenCodeGraph support).
- *
- * - TODO(sqs): Make this find dashboards containing the metric (like
- *   https://github.com/panodata/grafana-wtf).
- * - TODO(sqs): Hit the Prometheus/Grafana APIs to fetch data (eg `curl -XPOST
- *   'https://prometheus.demo.do.prometheus.io/api/v1/query?query=go_gc_duration_seconds&timeout=200ms'`).
+ * An [OpenCodeGraph](https://opencodegraph.org) provider that adds contextual documentation to your
+ * code from an existing documentation corpus.
  */
-const prometheus: OpenCodeGraphProvider<Settings> = {
+const docs: OpenCodeGraphProvider<Settings> = {
     capabilities(_params: CapabilitiesParams, settings: Settings): CapabilitiesResult {
         return { selector: settings.metricRegistrationPatterns?.map(({ path }) => ({ path })) || [] }
     },
@@ -111,7 +102,7 @@ const prometheus: OpenCodeGraphProvider<Settings> = {
     },
 }
 
-export default prometheus
+export default docs
 
 interface MatchResult {
     range: OpenCodeGraphRange

provider/docs/tsconfig.json

@@ -2,11 +2,11 @@
   "extends": "../../.config/tsconfig.base.json",
   "compilerOptions": {
     "module": "ESNext",
-    "rootDir": ".",
+    "rootDir": "src",
     "outDir": "dist",
     "lib": ["ESNext"],
   },
-  "include": ["*.ts"],
+  "include": ["src"],
   "exclude": ["dist", "vitest.config.ts"],
   "references": [{ "path": "../../lib/provider" }],
 }