diff --git a/provider/docs/README.md b/provider/docs/README.md index 8cb582d4..0d68c94e 100644 --- a/provider/docs/README.md +++ b/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 diff --git a/provider/docs/package.json b/provider/docs/package.json index 385190ce..272136a8 100644 --- a/provider/docs/package.json +++ b/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" ], diff --git a/provider/docs/src/corpus/corpus.test.ts b/provider/docs/src/corpus/corpus.test.ts new file mode 100644 index 00000000..9354b27d --- /dev/null +++ b/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 + }) +}) diff --git a/provider/docs/src/corpus/corpus.ts b/provider/docs/src/corpus/corpus.ts new file mode 100644 index 00000000..025bfe75 --- /dev/null +++ b/provider/docs/src/corpus/corpus.ts @@ -0,0 +1,32 @@ +import { CorpusSearchResult } from './search' + +/** + * A documentation corpus. + */ +export interface Corpus { + search(query: string): Promise + 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 + }, + } +} diff --git a/provider/docs/src/corpus/search.test.ts b/provider/docs/src/corpus/search.test.ts new file mode 100644 index 00000000..6251f569 --- /dev/null +++ b/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([ + { docID: '2', score: 1, excerpt: 'b' }, + ]) + }) +}) diff --git a/provider/docs/src/corpus/search.ts b/provider/docs/src/corpus/search.ts new file mode 100644 index 00000000..3eb019d9 --- /dev/null +++ b/provider/docs/src/corpus/search.ts @@ -0,0 +1,5 @@ +export interface CorpusSearchResult { + docID: string + score: number + excerpt: string +} diff --git a/provider/docs/index.test.ts b/provider/docs/src/index.test.ts similarity index 90% rename from provider/docs/index.test.ts rename to provider/docs/src/index.test.ts index 227a4c6c..8c5abe1a 100644 --- a/provider/docs/index.test.ts +++ b/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({ + expect(await docs.capabilities({}, SETTINGS)).toStrictEqual({ selector: [{ path: '**/*.go' }], }) }) test('annotations', () => { expect( - prometheus.annotations( + docs.annotations( { file: 'file:///a/b.go', content: ` diff --git a/provider/docs/index.ts b/provider/docs/src/index.ts similarity index 84% rename from provider/docs/index.ts rename to provider/docs/src/index.ts index 2876d7d3..a2e22223 100644 --- a/provider/docs/index.ts +++ b/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 = { +const docs: OpenCodeGraphProvider = { capabilities(_params: CapabilitiesParams, settings: Settings): CapabilitiesResult { return { selector: settings.metricRegistrationPatterns?.map(({ path }) => ({ path })) || [] } }, @@ -111,7 +102,7 @@ const prometheus: OpenCodeGraphProvider = { }, } -export default prometheus +export default docs interface MatchResult { range: OpenCodeGraphRange diff --git a/provider/docs/tsconfig.json b/provider/docs/tsconfig.json index 33d05bb2..13999016 100644 --- a/provider/docs/tsconfig.json +++ b/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" }], }