@elevasis/core 0.15.0 → 0.16.0

package/src/knowledge/__tests__/queries.test.ts

@@ -0,0 +1,504 @@
+import { describe, expect, it } from 'vitest'
+import { byFeature, byKind, byOwner, governs, governedBy, parsePath } from '../queries'
+import { formatText, formatJson, formatIdsOnly } from '../format'
+import type { OrganizationGraph } from '../../organization-model/graph/types'
+import type { OrgKnowledgeNode } from '../../organization-model/domains/knowledge'
+
+// ---------------------------------------------------------------------------
+// Synthetic fixtures
+// ---------------------------------------------------------------------------
+
+/**
+ * Three knowledge nodes covering all three kinds.
+ * - playbook-a governs feature:sales.crm and feature:sales.lead-gen
+ * - strategy-b governs feature:sales.lead-gen
+ * - reference-c has no links (no governs edges)
+ * - playbook-d is owned by "role.ops-lead"
+ */
+const NODES: OrgKnowledgeNode[] = [
+  {
+    id: 'knowledge.playbook-a',
+    kind: 'playbook',
+    title: 'Playbook A',
+    summary: 'Playbook A summary.',
+    body: '## Playbook A\n\nContent.',
+    links: [{ nodeId: 'feature:sales.crm' }, { nodeId: 'feature:sales.lead-gen' }],
+    ownerIds: [],
+    updatedAt: '2026-01-01'
+  },
+  {
+    id: 'knowledge.strategy-b',
+    kind: 'strategy',
+    title: 'Strategy B',
+    summary: 'Strategy B summary.',
+    body: '## Strategy B\n\nContent.',
+    links: [{ nodeId: 'feature:sales.lead-gen' }],
+    ownerIds: ['role.ops-lead'],
+    updatedAt: '2026-01-02'
+  },
+  {
+    id: 'knowledge.reference-c',
+    kind: 'reference',
+    title: 'Reference C',
+    summary: 'Reference C summary.',
+    body: '## Reference C\n\nContent.',
+    links: [],
+    ownerIds: [],
+    updatedAt: '2026-01-03'
+  },
+  {
+    id: 'knowledge.playbook-d',
+    kind: 'playbook',
+    title: 'Playbook D',
+    summary: 'Playbook D summary.',
+    body: '## Playbook D\n\nContent.',
+    links: [],
+    ownerIds: ['role.ops-lead', 'role.ceo'],
+    updatedAt: '2026-01-04'
+  }
+]
+
+/**
+ * Minimal synthetic OrganizationGraph derived from the above nodes.
+ * Graph node IDs follow the convention: `knowledge:<om-node-id>`
+ */
+const GRAPH: OrganizationGraph = {
+  version: 1,
+  organizationModelVersion: 1,
+  nodes: [
+    { id: 'organization-model', kind: 'organization', label: 'Organization Model' },
+    { id: 'feature:sales.crm', kind: 'feature', label: 'CRM', sourceId: 'sales.crm', featureId: 'sales.crm' },
+    {
+      id: 'feature:sales.lead-gen',
+      kind: 'feature',
+      label: 'Lead Gen',
+      sourceId: 'sales.lead-gen',
+      featureId: 'sales.lead-gen'
+    },
+    {
+      id: 'knowledge:knowledge.playbook-a',
+      kind: 'knowledge',
+      label: 'Playbook A',
+      sourceId: 'knowledge.playbook-a'
+    },
+    {
+      id: 'knowledge:knowledge.strategy-b',
+      kind: 'knowledge',
+      label: 'Strategy B',
+      sourceId: 'knowledge.strategy-b'
+    },
+    {
+      id: 'knowledge:knowledge.reference-c',
+      kind: 'knowledge',
+      label: 'Reference C',
+      sourceId: 'knowledge.reference-c'
+    },
+    {
+      id: 'knowledge:knowledge.playbook-d',
+      kind: 'knowledge',
+      label: 'Playbook D',
+      sourceId: 'knowledge.playbook-d'
+    }
+  ],
+  edges: [
+    // contains edges (organization -> knowledge nodes)
+    {
+      id: 'edge:contains:organization-model:knowledge:knowledge.playbook-a',
+      kind: 'contains',
+      sourceId: 'organization-model',
+      targetId: 'knowledge:knowledge.playbook-a'
+    },
+    {
+      id: 'edge:contains:organization-model:knowledge:knowledge.strategy-b',
+      kind: 'contains',
+      sourceId: 'organization-model',
+      targetId: 'knowledge:knowledge.strategy-b'
+    },
+    {
+      id: 'edge:contains:organization-model:knowledge:knowledge.reference-c',
+      kind: 'contains',
+      sourceId: 'organization-model',
+      targetId: 'knowledge:knowledge.reference-c'
+    },
+    {
+      id: 'edge:contains:organization-model:knowledge:knowledge.playbook-d',
+      kind: 'contains',
+      sourceId: 'organization-model',
+      targetId: 'knowledge:knowledge.playbook-d'
+    },
+    // governs edges
+    {
+      id: 'edge:governs:knowledge:knowledge.playbook-a:feature:sales.crm',
+      kind: 'governs',
+      sourceId: 'knowledge:knowledge.playbook-a',
+      targetId: 'feature:sales.crm'
+    },
+    {
+      id: 'edge:governs:knowledge:knowledge.playbook-a:feature:sales.lead-gen',
+      kind: 'governs',
+      sourceId: 'knowledge:knowledge.playbook-a',
+      targetId: 'feature:sales.lead-gen'
+    },
+    {
+      id: 'edge:governs:knowledge:knowledge.strategy-b:feature:sales.lead-gen',
+      kind: 'governs',
+      sourceId: 'knowledge:knowledge.strategy-b',
+      targetId: 'feature:sales.lead-gen'
+    }
+  ]
+}
+
+// ---------------------------------------------------------------------------
+// byFeature
+// ---------------------------------------------------------------------------
+
+describe('byFeature', () => {
+  it('returns nodes that have governs edges to the given feature', () => {
+    const result = byFeature(GRAPH, 'sales.crm', NODES)
+    expect(result).toHaveLength(1)
+    expect(result[0].id).toBe('knowledge.playbook-a')
+  })
+
+  it('returns multiple nodes when multiple knowledge nodes govern the same feature', () => {
+    const result = byFeature(GRAPH, 'sales.lead-gen', NODES)
+    const ids = result.map((n) => n.id).sort()
+    expect(ids).toEqual(['knowledge.playbook-a', 'knowledge.strategy-b'].sort())
+  })
+
+  it('returns empty array when no node governs the feature', () => {
+    const result = byFeature(GRAPH, 'feature.does-not-exist', NODES)
+    expect(result).toHaveLength(0)
+  })
+
+  it('returns full OrgKnowledgeNode objects (not just graph stubs)', () => {
+    const result = byFeature(GRAPH, 'sales.crm', NODES)
+    expect(result[0].body).toBeDefined()
+    expect(result[0].links).toBeDefined()
+    expect(result[0].ownerIds).toBeDefined()
+  })
+})
+
+// ---------------------------------------------------------------------------
+// byKind
+// ---------------------------------------------------------------------------
+
+describe('byKind', () => {
+  it('returns all playbook nodes', () => {
+    const result = byKind(GRAPH, 'playbook', NODES)
+    expect(result).toHaveLength(2)
+    expect(result.every((n) => n.kind === 'playbook')).toBe(true)
+  })
+
+  it('returns strategy nodes', () => {
+    const result = byKind(GRAPH, 'strategy', NODES)
+    expect(result).toHaveLength(1)
+    expect(result[0].id).toBe('knowledge.strategy-b')
+  })
+
+  it('returns reference nodes', () => {
+    const result = byKind(GRAPH, 'reference', NODES)
+    expect(result).toHaveLength(1)
+    expect(result[0].id).toBe('knowledge.reference-c')
+  })
+
+  it('returns empty array when no nodes match the kind', () => {
+    const result = byKind(GRAPH, 'playbook', [])
+    expect(result).toHaveLength(0)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// byOwner
+// ---------------------------------------------------------------------------
+
+describe('byOwner', () => {
+  it('returns nodes where ownerIds includes the given owner', () => {
+    const result = byOwner(GRAPH, 'role.ops-lead', NODES)
+    const ids = result.map((n) => n.id).sort()
+    expect(ids).toEqual(['knowledge.playbook-d', 'knowledge.strategy-b'].sort())
+  })
+
+  it('returns nodes for a second owner', () => {
+    const result = byOwner(GRAPH, 'role.ceo', NODES)
+    expect(result).toHaveLength(1)
+    expect(result[0].id).toBe('knowledge.playbook-d')
+  })
+
+  it('returns empty array when ownerId is not present in any node', () => {
+    const result = byOwner(GRAPH, 'role.unknown', NODES)
+    expect(result).toHaveLength(0)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// governs
+// ---------------------------------------------------------------------------
+
+describe('governs', () => {
+  it('returns target graph node IDs for outgoing governs edges (OM node id input)', () => {
+    const result = governs(GRAPH, 'knowledge.playbook-a')
+    expect(result.sort()).toEqual(['feature:sales.crm', 'feature:sales.lead-gen'].sort())
+  })
+
+  it('accepts graph node ID format input', () => {
+    const result = governs(GRAPH, 'knowledge:knowledge.playbook-a')
+    expect(result.sort()).toEqual(['feature:sales.crm', 'feature:sales.lead-gen'].sort())
+  })
+
+  it('returns single target for a node with one link', () => {
+    const result = governs(GRAPH, 'knowledge.strategy-b')
+    expect(result).toEqual(['feature:sales.lead-gen'])
+  })
+
+  it('returns empty array for a node with no governs edges', () => {
+    const result = governs(GRAPH, 'knowledge.reference-c')
+    expect(result).toHaveLength(0)
+  })
+
+  it('returns empty array for an unknown nodeId', () => {
+    const result = governs(GRAPH, 'knowledge.does-not-exist')
+    expect(result).toHaveLength(0)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// governedBy
+// ---------------------------------------------------------------------------
+
+describe('governedBy', () => {
+  it('returns knowledge graph node IDs for incoming governs edges (prefixed feature id)', () => {
+    const result = governedBy(GRAPH, 'feature:sales.lead-gen')
+    const sorted = result.sort()
+    expect(sorted).toEqual(['knowledge:knowledge.playbook-a', 'knowledge:knowledge.strategy-b'].sort())
+  })
+
+  it('accepts bare feature id (auto-prefixes with feature:)', () => {
+    const result = governedBy(GRAPH, 'sales.crm')
+    expect(result).toEqual(['knowledge:knowledge.playbook-a'])
+  })
+
+  it('returns empty array when no knowledge node governs the target', () => {
+    const result = governedBy(GRAPH, 'feature:dashboard')
+    expect(result).toHaveLength(0)
+  })
+
+  it('returns empty array for unknown target node id', () => {
+    const result = governedBy(GRAPH, 'feature:does-not-exist')
+    expect(result).toHaveLength(0)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// parsePath — happy paths (all five mount axes)
+// ---------------------------------------------------------------------------
+
+describe('parsePath — happy paths', () => {
+  it('/by-kind/playbook → mount:by-kind args:[playbook]', () => {
+    expect(parsePath('/by-kind/playbook')).toEqual({ mount: 'by-kind', args: ['playbook'] })
+  })
+
+  it('/by-kind/strategy → mount:by-kind args:[strategy]', () => {
+    expect(parsePath('/by-kind/strategy')).toEqual({ mount: 'by-kind', args: ['strategy'] })
+  })
+
+  it('/by-feature/sales.crm → mount:by-feature args:[sales.crm]', () => {
+    expect(parsePath('/by-feature/sales.crm')).toEqual({ mount: 'by-feature', args: ['sales.crm'] })
+  })
+
+  it('/by-feature/sales/crm (slash-delimited) → mount:by-feature args:[sales/crm]', () => {
+    // featureId with slashes is joined and passed as-is for the caller to interpret
+    expect(parsePath('/by-feature/sales/crm')).toEqual({ mount: 'by-feature', args: ['sales/crm'] })
+  })
+
+  it('/by-owner/role.ops-lead → mount:by-owner args:[role.ops-lead]', () => {
+    expect(parsePath('/by-owner/role.ops-lead')).toEqual({ mount: 'by-owner', args: ['role.ops-lead'] })
+  })
+
+  it('/graph/knowledge.outreach-playbook/governs → mount:graph args:[knowledge.outreach-playbook,governs]', () => {
+    expect(parsePath('/graph/knowledge.outreach-playbook/governs')).toEqual({
+      mount: 'graph',
+      args: ['knowledge.outreach-playbook', 'governs']
+    })
+  })
+
+  it('/graph/knowledge.outreach-playbook/governed-by → mount:graph args:[knowledge.outreach-playbook,governed-by]', () => {
+    expect(parsePath('/graph/knowledge.outreach-playbook/governed-by')).toEqual({
+      mount: 'graph',
+      args: ['knowledge.outreach-playbook', 'governed-by']
+    })
+  })
+
+  it('/<nodeId> single segment → mount:node args:[nodeId]', () => {
+    expect(parsePath('/knowledge.outreach-playbook')).toEqual({
+      mount: 'node',
+      args: ['knowledge.outreach-playbook']
+    })
+  })
+
+  it('trailing slash is stripped before parsing', () => {
+    expect(parsePath('/by-kind/playbook/')).toEqual({ mount: 'by-kind', args: ['playbook'] })
+  })
+})
+
+// ---------------------------------------------------------------------------
+// parsePath — invalid inputs (5+)
+// ---------------------------------------------------------------------------
+
+describe('parsePath — invalid inputs', () => {
+  it('throws on empty string', () => {
+    expect(() => parsePath('')).toThrow('parsePath: path must be a non-empty string')
+  })
+
+  it('throws when path does not start with /', () => {
+    expect(() => parsePath('by-kind/playbook')).toThrow('parsePath: path must start with "/"')
+  })
+
+  it('throws on bare root path "/"', () => {
+    expect(() => parsePath('/')).toThrow('parsePath: path resolves to root with no mount')
+  })
+
+  it('throws on /by-feature with no featureId argument', () => {
+    expect(() => parsePath('/by-feature')).toThrow('/by-feature requires a featureId argument')
+  })
+
+  it('throws on /by-kind with no kind argument', () => {
+    expect(() => parsePath('/by-kind')).toThrow('/by-kind requires a kind argument')
+  })
+
+  it('throws on /by-owner with no ownerId argument', () => {
+    expect(() => parsePath('/by-owner')).toThrow('/by-owner requires an ownerId argument')
+  })
+
+  it('throws on /graph with only nodeId (missing verb)', () => {
+    expect(() => parsePath('/graph/knowledge.outreach-playbook')).toThrow('/graph requires <nodeId>/<verb>')
+  })
+
+  it('throws on /graph/<nodeId>/<unknown-verb>', () => {
+    expect(() => parsePath('/graph/knowledge.outreach-playbook/list')).toThrow(
+      'verb must be "governs" or "governed-by"'
+    )
+  })
+
+  it('throws on multi-segment path with unrecognized first segment', () => {
+    expect(() => parsePath('/unknown-mount/some-arg')).toThrow('unrecognized path pattern')
+  })
+})
+
+// ---------------------------------------------------------------------------
+// formatText
+// ---------------------------------------------------------------------------
+
+describe('formatText', () => {
+  it('returns "(no results)" for empty array', () => {
+    expect(formatText([])).toBe('(no results)')
+  })
+
+  it('includes header row with KIND and ID columns', () => {
+    const output = formatText([NODES[0]])
+    expect(output).toContain('KIND')
+    expect(output).toContain('ID')
+    expect(output).toContain('TITLE')
+  })
+
+  it('includes node id and title in output', () => {
+    const output = formatText([NODES[0]])
+    expect(output).toContain('knowledge.playbook-a')
+    expect(output).toContain('Playbook A')
+  })
+
+  it('truncates long summaries', () => {
+    const longSummary = 'x'.repeat(200)
+    const node: OrgKnowledgeNode = { ...NODES[0], summary: longSummary }
+    const output = formatText([node])
+    expect(output).toContain('...')
+  })
+})
+
+// ---------------------------------------------------------------------------
+// formatJson — envelope shape
+// ---------------------------------------------------------------------------
+
+describe('formatJson', () => {
+  it('returns a JSON string with top-level keys: path, mount, args, results', () => {
+    const raw = formatJson({
+      path: '/by-kind/playbook',
+      parsed: { mount: 'by-kind', args: ['playbook'] },
+      results: [NODES[0]]
+    })
+    const parsed = JSON.parse(raw) as Record<string, unknown>
+    expect(Object.keys(parsed).sort()).toEqual(['args', 'mount', 'path', 'results'].sort())
+  })
+
+  it('preserves path in envelope', () => {
+    const raw = formatJson({
+      path: '/by-kind/playbook',
+      parsed: { mount: 'by-kind', args: ['playbook'] },
+      results: []
+    })
+    expect(JSON.parse(raw)).toMatchObject({ path: '/by-kind/playbook' })
+  })
+
+  it('preserves mount in envelope', () => {
+    const raw = formatJson({
+      path: '/by-kind/strategy',
+      parsed: { mount: 'by-kind', args: ['strategy'] },
+      results: []
+    })
+    expect(JSON.parse(raw)).toMatchObject({ mount: 'by-kind' })
+  })
+
+  it('preserves args array in envelope', () => {
+    const raw = formatJson({
+      path: '/by-feature/sales.crm',
+      parsed: { mount: 'by-feature', args: ['sales.crm'] },
+      results: []
+    })
+    expect(JSON.parse(raw)).toMatchObject({ args: ['sales.crm'] })
+  })
+
+  it('includes results in envelope for string[] (governs/governedBy)', () => {
+    const raw = formatJson({
+      path: '/graph/knowledge.playbook-a/governs',
+      parsed: { mount: 'graph', args: ['knowledge.playbook-a', 'governs'] },
+      results: ['feature:sales.crm', 'feature:sales.lead-gen']
+    })
+    const parsed = JSON.parse(raw) as { results: string[] }
+    expect(parsed.results).toEqual(['feature:sales.crm', 'feature:sales.lead-gen'])
+  })
+
+  it('envelope is NOT flat { results } — must have path/mount/args siblings', () => {
+    const raw = formatJson({
+      path: '/by-kind/playbook',
+      parsed: { mount: 'by-kind', args: ['playbook'] },
+      results: [NODES[0]]
+    })
+    const parsed = JSON.parse(raw) as Record<string, unknown>
+    // Must NOT be flat (only results key)
+    expect(parsed).toHaveProperty('path')
+    expect(parsed).toHaveProperty('mount')
+    expect(parsed).toHaveProperty('args')
+    expect(parsed).toHaveProperty('results')
+  })
+})
+
+// ---------------------------------------------------------------------------
+// formatIdsOnly
+// ---------------------------------------------------------------------------
+
+describe('formatIdsOnly', () => {
+  it('returns empty string for empty array', () => {
+    expect(formatIdsOnly([])).toBe('')
+  })
+
+  it('returns newline-separated ids for OrgKnowledgeNode array', () => {
+    const output = formatIdsOnly([NODES[0], NODES[1]])
+    const lines = output.split('\n')
+    expect(lines).toContain('knowledge.playbook-a')
+    expect(lines).toContain('knowledge.strategy-b')
+  })
+
+  it('returns newline-separated strings for string[] (governs results)', () => {
+    const output = formatIdsOnly(['feature:sales.crm', 'feature:sales.lead-gen'])
+    expect(output).toBe('feature:sales.crm\nfeature:sales.lead-gen')
+  })
+})

package/src/knowledge/format.ts

@@ -0,0 +1,99 @@
+import type { OrgKnowledgeNode } from '../organization-model/domains/knowledge'
+import type { KnowledgeMount, ParsedKnowledgePath } from './queries'
+
+// ---------------------------------------------------------------------------
+// formatText
+// ---------------------------------------------------------------------------
+
+/**
+ * Renders a list of `OrgKnowledgeNode` results as a human-friendly text table.
+ *
+ * Output format (one row per node):
+ *   `<kind>  <id>  <title>  —  <summary (truncated to 80 chars)>`
+ *
+ * Returns `"(no results)"` when the array is empty.
+ */
+export function formatText(results: OrgKnowledgeNode[]): string {
+  if (results.length === 0) {
+    return '(no results)'
+  }
+
+  const kindWidth = Math.max(...results.map((n) => n.kind.length), 8)
+  const idWidth = Math.max(...results.map((n) => n.id.length), 4)
+
+  const header = `${'KIND'.padEnd(kindWidth)}  ${'ID'.padEnd(idWidth)}  TITLE`
+  const divider = '-'.repeat(header.length + 20)
+
+  const rows = results.map((n) => {
+    const summary = n.summary.length > 80 ? n.summary.slice(0, 77) + '...' : n.summary
+    return `${n.kind.padEnd(kindWidth)}  ${n.id.padEnd(idWidth)}  ${n.title}  —  ${summary}`
+  })
+
+  return [header, divider, ...rows].join('\n')
+}
+
+// ---------------------------------------------------------------------------
+// formatJson
+// ---------------------------------------------------------------------------
+
+/**
+ * Wrapped JSON envelope for machine-readable output.
+ *
+ * Shape: `{ path, mount, args, results }`
+ *
+ * - `path`    — the original path string passed to `parsePath`
+ * - `mount`   — the resolved mount axis
+ * - `args`    — the parsed arguments array
+ * - `results` — the query results (array of `OrgKnowledgeNode` or string IDs)
+ */
+export interface KnowledgeJsonEnvelope {
+  path: string
+  mount: KnowledgeMount
+  args: string[]
+  results: OrgKnowledgeNode[] | string[]
+}
+
+/**
+ * Formats query results as a wrapped JSON envelope string.
+ *
+ * The envelope shape is `{ path, mount, args, results }`.  This is intentionally
+ * NOT flat `{ results }` — consumers (agent skills, jq pipelines) need the
+ * mount + args to know how to interpret the results array.
+ *
+ * @param input.path    - The original path string (e.g. `"/by-feature/sales.crm"`).
+ * @param input.mount   - The resolved mount axis.
+ * @param input.args    - The parsed argument array.
+ * @param input.results - The query results.
+ */
+export function formatJson(input: {
+  path: string
+  parsed: ParsedKnowledgePath
+  results: OrgKnowledgeNode[] | string[]
+}): string {
+  const envelope: KnowledgeJsonEnvelope = {
+    path: input.path,
+    mount: input.parsed.mount,
+    args: input.parsed.args,
+    results: input.results
+  }
+  return JSON.stringify(envelope, null, 2)
+}
+
+// ---------------------------------------------------------------------------
+// formatIdsOnly
+// ---------------------------------------------------------------------------
+
+/**
+ * Renders results as newline-separated IDs for piping.
+ *
+ * - For `OrgKnowledgeNode[]` results: emits `node.id` per line.
+ * - For `string[]` results (governs / governedBy): emits each string per line.
+ *
+ * Returns an empty string when the array is empty (suitable for `wc -l` piping).
+ */
+export function formatIdsOnly(results: OrgKnowledgeNode[] | string[]): string {
+  if (results.length === 0) return ''
+
+  const ids = results.map((r) => (typeof r === 'string' ? r : r.id))
+  return ids.join('\n')
+}

package/src/knowledge/index.ts

@@ -0,0 +1,5 @@
+export { byFeature, byKind, byOwner, governs, governedBy, parsePath } from './queries'
+export type { KnowledgeMount, ParsedKnowledgePath } from './queries'
+
+export { formatText, formatJson, formatIdsOnly } from './format'
+export type { KnowledgeJsonEnvelope } from './format'