test: prose knowledge extractor coverage

17 tests covering conflicts_with, depends_on, constrains,
supersedes extraction with singular/plural inflection,
deduplication, security requirements, timing patterns,
empty input, spec-doc filtering, and block text fallback.

Co-Authored-By: Claude <noreply@anthropic.com>

Author: salmad3

packages/agent-metadata/src/extractors/prose-knowledge.test.ts

@@ -0,0 +1,185 @@
+import { describe, it, expect } from 'vitest';
+import { buildSpecVocabulary, extractProseKnowledge } from './prose-knowledge.js';
+import type { DocumentMetadata } from '../types.js';
+
+function makeSpecDoc(tag: string, endpoints: string[]): DocumentMetadata {
+  return {
+    filePath: `openapi:${tag}`,
+    title: `API — ${tag}`,
+    blocks: endpoints.map((ep) => ({
+      id: ep.replace(/\s+/g, '-').toLowerCase(),
+      type: 'reference',
+      headingText: ep,
+      textContent: ep,
+      annotations: {},
+      codeBlocks: [],
+      sourcePath: `openapi:${tag}`,
+    })),
+    crossRefs: [],
+    links: [],
+    wordCount: 0,
+    headings: [],
+  };
+}
+
+function makeProseDoc(filePath: string, title: string): DocumentMetadata {
+  return {
+    filePath,
+    title,
+    blocks: [],
+    crossRefs: [],
+    links: [],
+    wordCount: 0,
+    headings: [],
+  };
+}
+
+const specDocs = [
+  makeSpecDoc('customers', ['POST /v2/customers', 'GET /v2/customers/{id}']),
+  makeSpecDoc('payments', ['POST /v2/payments', 'POST /v2/payments/{id}/confirm', 'POST /v2/payments/{id}/refund']),
+  makeSpecDoc('subscriptions', ['POST /v2/subscriptions', 'POST /v2/subscriptions/{id}/cancel', 'POST /v2/subscriptions/{id}/pause']),
+  makeSpecDoc('webhooks', ['POST /v2/webhooks']),
+];
+
+const vocabulary = buildSpecVocabulary(specDocs);
+
+describe('buildSpecVocabulary', () => {
+  it('extracts tags from spec documents', () => {
+    expect(vocabulary.tags).toEqual(
+      expect.arrayContaining(['customers', 'payments', 'subscriptions', 'webhooks']),
+    );
+  });
+
+  it('extracts endpoints from spec documents', () => {
+    expect(vocabulary.endpoints).toContain('POST /v2/payments');
+    expect(vocabulary.endpoints).toContain('POST /v2/subscriptions');
+  });
+
+  it('maps endpoints to their tags', () => {
+    expect(vocabulary.endpointToTag.get('post /v2/payments')).toBe('payments');
+    expect(vocabulary.endpointToTag.get('post /v2/webhooks')).toBe('webhooks');
+  });
+
+  it('skips schemas and security documents', () => {
+    const docsWithSchemas = [
+      ...specDocs,
+      makeSpecDoc('schemas', ['Customer', 'Payment']),
+      makeSpecDoc('security', ['bearer']),
+    ];
+    const vocab = buildSpecVocabulary(docsWithSchemas);
+    expect(vocab.tags).not.toContain('schemas');
+    expect(vocab.tags).not.toContain('security');
+  });
+});
+
+describe('extractProseKnowledge', () => {
+  const proseDocs = [makeProseDoc('docs/guide.md', 'Payment Guide')];
+
+  it('extracts conflicts_with from mutual exclusion language', () => {
+    const text = 'You should not call POST /v2/payments directly when using subscriptions.';
+    const rels = extractProseKnowledge(proseDocs, vocabulary, new Map([['docs/guide.md', text]]));
+    const conflict = rels.find((r) => r.type === 'conflicts_with');
+    expect(conflict).toBeDefined();
+    expect(conflict!.sourceDocPath).toBe('openapi:payments');
+    expect(conflict!.targetDocPath).toBe('openapi:subscriptions');
+  });
+
+  it('extracts depends_on from workflow ordering language', () => {
+    const text = 'Before processing a payment, you must create a customer first.';
+    const rels = extractProseKnowledge(proseDocs, vocabulary, new Map([['docs/guide.md', text]]));
+    const dep = rels.find((r) => r.type === 'depends_on');
+    expect(dep).toBeDefined();
+  });
+
+  it('extracts constrains from time constraint language', () => {
+    const text = 'You must confirm the payment within 30 minutes or it expires.';
+    const rels = extractProseKnowledge(proseDocs, vocabulary, new Map([['docs/guide.md', text]]));
+    const constraint = rels.find((r) => r.type === 'constrains' && r.evidence.includes('time'));
+    expect(constraint).toBeDefined();
+    expect(constraint!.targetDocPath).toBe('openapi:payments');
+  });
+
+  it('extracts constrains from failure handling language', () => {
+    const text = 'Failed payments cannot be retried. Create a new payment intent.';
+    const rels = extractProseKnowledge(proseDocs, vocabulary, new Map([['docs/guide.md', text]]));
+    const failure = rels.find((r) => r.type === 'constrains' && r.evidence.includes('failure'));
+    expect(failure).toBeDefined();
+    expect(failure!.targetDocPath).toBe('openapi:payments');
+  });
+
+  it('extracts constrains from retry policy language', () => {
+    const text = 'Subscriptions trigger automatic retry after 1 day, then 3 days, then 7 days.';
+    const rels = extractProseKnowledge(proseDocs, vocabulary, new Map([['docs/guide.md', text]]));
+    const retry = rels.find((r) => r.type === 'constrains' && r.evidence.includes('retry'));
+    expect(retry).toBeDefined();
+    expect(retry!.targetDocPath).toBe('openapi:subscriptions');
+  });
+
+  it('extracts supersedes from deprecation language', () => {
+    const text = 'The cancel endpoint for subscriptions is deprecated. Use pause instead.';
+    const rels = extractProseKnowledge(proseDocs, vocabulary, new Map([['docs/guide.md', text]]));
+    const dep = rels.find((r) => r.type === 'supersedes');
+    expect(dep).toBeDefined();
+    expect(dep!.targetDocPath).toBe('openapi:subscriptions');
+  });
+
+  it('extracts depends_on from security requirement language', () => {
+    const text = 'Always verify the webhook signature before processing the event.';
+    const rels = extractProseKnowledge(proseDocs, vocabulary, new Map([['docs/guide.md', text]]));
+    const sec = rels.find((r) => r.type === 'depends_on' && r.evidence.includes('security'));
+    expect(sec).toBeDefined();
+    expect(sec!.sourceDocPath).toBe('openapi:webhooks');
+  });
+
+  it('handles singular/plural inflection (payment → payments tag)', () => {
+    const text = 'A payment must be confirmed within 30 minutes.';
+    const rels = extractProseKnowledge(proseDocs, vocabulary, new Map([['docs/guide.md', text]]));
+    const match = rels.find((r) => r.targetDocPath === 'openapi:payments');
+    expect(match).toBeDefined();
+  });
+
+  it('returns empty array when no spec entities are mentioned', () => {
+    const text = 'This is a general guide about software engineering best practices.';
+    const rels = extractProseKnowledge(proseDocs, vocabulary, new Map([['docs/guide.md', text]]));
+    expect(rels).toHaveLength(0);
+  });
+
+  it('skips openapi-prefixed documents (spec docs are not prose)', () => {
+    const specAsProse = [makeProseDoc('openapi:payments', 'Payments')];
+    const text = 'Payments cannot be retried.';
+    const rels = extractProseKnowledge(specAsProse, vocabulary, new Map([['openapi:payments', text]]));
+    expect(rels).toHaveLength(0);
+  });
+
+  it('deduplicates rules with same type, source, and target', () => {
+    const text = 'Do not use payments when using subscriptions. Never call payments directly with subscriptions.';
+    const rels = extractProseKnowledge(proseDocs, vocabulary, new Map([['docs/guide.md', text]]));
+    const conflicts = rels.filter((r) => r.type === 'conflicts_with');
+    expect(conflicts).toHaveLength(1);
+  });
+
+  it('extracts timing information from "X business days" patterns', () => {
+    const text = 'Refunds take 5-10 business days to appear on the customer statement.';
+    const rels = extractProseKnowledge(proseDocs, vocabulary, new Map([['docs/guide.md', text]]));
+    const timing = rels.find((r) => r.evidence.includes('timing'));
+    expect(timing).toBeDefined();
+  });
+
+  it('falls back to block text when raw texts are not provided', () => {
+    const docsWithBlocks: DocumentMetadata[] = [{
+      ...proseDocs[0]!,
+      blocks: [{
+        id: 'b1',
+        type: 'section',
+        headingText: 'Payments',
+        textContent: 'Do not use payments when using subscriptions directly.',
+        annotations: {},
+        codeBlocks: [],
+        sourcePath: 'docs/guide.md',
+      }],
+    }];
+    const rels = extractProseKnowledge(docsWithBlocks, vocabulary);
+    const conflict = rels.find((r) => r.type === 'conflicts_with');
+    expect(conflict).toBeDefined();
+  });
+});