@unrdf/kgc-runtime 26.4.2

package/src/projections-docs.mjs

@@ -0,0 +1,300 @@
+/**
+ * @fileoverview Π_docs - Documentation Generation Projections
+ * Transforms KGC structures into Markdown documentation with code examples
+ */
+
+import { z } from 'zod';
+
+/**
+ * Documentation projection schema
+ */
+export const DocsProjectionSchema = z.object({
+  type: z.literal('docs'),
+  format: z.enum(['markdown', 'html', 'json']),
+  content: z.string(),
+  frontMatter: z.record(z.any()).optional(),
+  sections: z.array(z.object({
+    title: z.string(),
+    level: z.number(),
+    content: z.string(),
+  })).optional(),
+  crossRefs: z.array(z.object({
+    source: z.string(),
+    target: z.string(),
+    type: z.string(),
+  })).optional(),
+});
+
+/**
+ * @typedef {z.infer<typeof DocsProjectionSchema>} DocsProjection
+ */
+
+/**
+ * Escape markdown special characters
+ * @param {string} text - Text to escape
+ * @returns {string} Escaped text
+ */
+function escapeMarkdown(text) {
+  return text.replace(/([*_`#\[\]()>])/g, '\\$1');
+}
+
+/**
+ * Generate markdown heading
+ * @param {string} text - Heading text
+ * @param {number} level - Heading level (1-6)
+ * @returns {string} Markdown heading
+ */
+function heading(text, level = 1) {
+  return `${'#'.repeat(Math.min(level, 6))} ${text}`;
+}
+
+/**
+ * Generate markdown code block
+ * @param {string} code - Code content
+ * @param {string} [language='javascript'] - Language for syntax highlighting
+ * @returns {string} Markdown code block
+ */
+function codeBlock(code, language = 'javascript') {
+  return `\`\`\`${language}\n${code}\n\`\`\``;
+}
+
+/**
+ * Project receipt to documentation
+ * @param {import('./receipt.mjs').Receipt} receipt - Receipt to document
+ * @returns {DocsProjection} Documentation projection
+ */
+export function projectReceiptToDocs(receipt) {
+  const sections = [
+    {
+      title: 'Overview',
+      level: 2,
+      content: `Receipt ID: \`${receipt.id}\`\n\nOperation: **${receipt.operation}**\n\nTimestamp: ${receipt.timestamp}`,
+    },
+    {
+      title: 'Inputs',
+      level: 2,
+      content: codeBlock(JSON.stringify(receipt.inputs, null, 2), 'json'),
+    },
+    {
+      title: 'Outputs',
+      level: 2,
+      content: codeBlock(JSON.stringify(receipt.outputs, null, 2), 'json'),
+    },
+    {
+      title: 'Verification',
+      level: 2,
+      content: `Content Hash: \`${receipt.hash}\`` +
+        (receipt.parentHash ? `\n\nParent Hash: \`${receipt.parentHash}\`` : ''),
+    },
+  ];
+
+  const content = [
+    heading('Receipt Documentation', 1),
+    '',
+    ...sections.map(s => [heading(s.title, s.level), '', s.content, ''].join('\n')),
+  ].join('\n');
+
+  return DocsProjectionSchema.parse({
+    type: 'docs',
+    format: 'markdown',
+    content,
+    frontMatter: {
+      id: receipt.id,
+      operation: receipt.operation,
+      timestamp: receipt.timestamp,
+    },
+    sections,
+  });
+}
+
+/**
+ * Project schema to documentation with examples
+ * @param {string} schemaName - Schema name
+ * @param {import('zod').ZodType} schema - Zod schema
+ * @param {Record<string, any>} [example] - Example object
+ * @returns {DocsProjection} Documentation projection
+ */
+export function projectSchemaToDocs(schemaName, schema, example) {
+  const sections = [
+    {
+      title: 'Schema Definition',
+      level: 2,
+      content: `\`${schemaName}\` - Type-safe schema for validation and type inference.`,
+    },
+  ];
+
+  if (example) {
+    sections.push({
+      title: 'Example',
+      level: 2,
+      content: codeBlock(JSON.stringify(example, null, 2), 'json'),
+    });
+
+    sections.push({
+      title: 'Usage',
+      level: 2,
+      content: codeBlock(
+        `import { ${schemaName} } from '@unrdf/kgc-runtime/schemas';\n\n` +
+        `const validated = ${schemaName}.parse(data);`,
+        'javascript'
+      ),
+    });
+  }
+
+  const content = [
+    heading(`${schemaName} Documentation`, 1),
+    '',
+    ...sections.map(s => [heading(s.title, s.level), '', s.content, ''].join('\n')),
+  ].join('\n');
+
+  return DocsProjectionSchema.parse({
+    type: 'docs',
+    format: 'markdown',
+    content,
+    frontMatter: {
+      schema: schemaName,
+      type: 'schema-documentation',
+    },
+    sections,
+  });
+}
+
+/**
+ * Generate API documentation from function
+ * @param {Function} fn - Function to document
+ * @param {object} metadata - Function metadata
+ * @param {string} metadata.name - Function name
+ * @param {string} metadata.description - Function description
+ * @param {Array<{name: string, type: string, description: string}>} metadata.params - Parameters
+ * @param {object} metadata.returns - Return value info
+ * @param {string} [metadata.example] - Usage example
+ * @returns {DocsProjection} Documentation projection
+ */
+export function projectFunctionToDocs(fn, metadata) {
+  const sections = [
+    {
+      title: 'Description',
+      level: 2,
+      content: metadata.description,
+    },
+    {
+      title: 'Parameters',
+      level: 2,
+      content: metadata.params.map(p =>
+        `- **${p.name}** (\`${p.type}\`): ${p.description}`
+      ).join('\n'),
+    },
+    {
+      title: 'Returns',
+      level: 2,
+      content: `\`${metadata.returns.type}\` - ${metadata.returns.description}`,
+    },
+  ];
+
+  if (metadata.example) {
+    sections.push({
+      title: 'Example',
+      level: 2,
+      content: codeBlock(metadata.example, 'javascript'),
+    });
+  }
+
+  const content = [
+    heading(`${metadata.name}()`, 1),
+    '',
+    ...sections.map(s => [heading(s.title, s.level), '', s.content, ''].join('\n')),
+  ].join('\n');
+
+  return DocsProjectionSchema.parse({
+    type: 'docs',
+    format: 'markdown',
+    content,
+    frontMatter: {
+      function: metadata.name,
+      type: 'api-documentation',
+    },
+    sections,
+  });
+}
+
+/**
+ * Generate cross-reference links in markdown
+ * @param {string} text - Text with potential references
+ * @param {Map<string, string>} refMap - Map of reference IDs to URLs
+ * @returns {string} Text with markdown links
+ */
+export function generateCrossRefs(text, refMap) {
+  let result = text;
+
+  for (const [ref, url] of refMap.entries()) {
+    const pattern = new RegExp(`\\b${ref}\\b`, 'g');
+    result = result.replace(pattern, `[${ref}](${url})`);
+  }
+
+  return result;
+}
+
+/**
+ * Generate table of contents from sections
+ * @param {Array<{title: string, level: number}>} sections - Document sections
+ * @returns {string} Markdown table of contents
+ */
+export function generateTableOfContents(sections) {
+  const toc = sections.map(section => {
+    const indent = '  '.repeat(section.level - 1);
+    const anchor = section.title.toLowerCase().replace(/\s+/g, '-').replace(/[^\w-]/g, '');
+    return `${indent}- [${section.title}](#${anchor})`;
+  });
+
+  return '## Table of Contents\n\n' + toc.join('\n');
+}
+
+/**
+ * Project workflow to documentation
+ * @param {object} workflow - Workflow definition
+ * @param {string} workflow.id - Workflow ID
+ * @param {string} workflow.name - Workflow name
+ * @param {string} workflow.description - Workflow description
+ * @param {Array<{id: string, type: string, description: string}>} workflow.steps - Workflow steps
+ * @returns {DocsProjection} Documentation projection
+ */
+export function projectWorkflowToDocs(workflow) {
+  const sections = [
+    {
+      title: 'Overview',
+      level: 2,
+      content: workflow.description,
+    },
+    {
+      title: 'Workflow Steps',
+      level: 2,
+      content: workflow.steps.map((step, i) =>
+        `${i + 1}. **${step.type}** (\`${step.id}\`)\n   ${step.description}`
+      ).join('\n\n'),
+    },
+  ];
+
+  const content = [
+    heading(workflow.name, 1),
+    '',
+    ...sections.map(s => [heading(s.title, s.level), '', s.content, ''].join('\n')),
+  ].join('\n');
+
+  const crossRefs = workflow.steps.map((step, i) => ({
+    source: workflow.id,
+    target: step.id,
+    type: 'step',
+  }));
+
+  return DocsProjectionSchema.parse({
+    type: 'docs',
+    format: 'markdown',
+    content,
+    frontMatter: {
+      workflowId: workflow.id,
+      name: workflow.name,
+    },
+    sections,
+    crossRefs,
+  });
+}

package/src/projections-ide.mjs

@@ -0,0 +1,278 @@
+/**
+ * @fileoverview Π_ide - IDE Metadata Projections
+ * Transforms KGC structures into LSP-compatible metadata for IDE integration
+ */
+
+import { z } from 'zod';
+
+/**
+ * IDE projection schema (LSP-compatible)
+ */
+export const IDEProjectionSchema = z.object({
+  type: z.literal('ide'),
+  format: z.enum(['lsp', 'hover', 'completion', 'definition']),
+  content: z.record(z.any()),
+  uri: z.string().optional(),
+  range: z.object({
+    start: z.object({ line: z.number(), character: z.number() }),
+    end: z.object({ line: z.number(), character: z.number() }),
+  }).optional(),
+});
+
+/**
+ * @typedef {z.infer<typeof IDEProjectionSchema>} IDEProjection
+ */
+
+/**
+ * LSP Position
+ * @typedef {{line: number, character: number}} Position
+ */
+
+/**
+ * LSP Range
+ * @typedef {{start: Position, end: Position}} Range
+ */
+
+/**
+ * Project function to LSP hover information
+ * @param {object} fnInfo - Function information
+ * @param {string} fnInfo.name - Function name
+ * @param {string} fnInfo.signature - Function signature
+ * @param {string} fnInfo.documentation - Documentation text
+ * @param {Array<{name: string, type: string, description: string}>} fnInfo.parameters - Parameters
+ * @param {object} fnInfo.returns - Return type info
+ * @returns {IDEProjection} IDE projection
+ */
+export function projectFunctionToHover(fnInfo) {
+  const paramDocs = fnInfo.parameters.map(p =>
+    `@param {${p.type}} ${p.name} - ${p.description}`
+  ).join('\n');
+
+  const returnDoc = `@returns {${fnInfo.returns.type}} ${fnInfo.returns.description}`;
+
+  const markdown = [
+    `\`\`\`javascript`,
+    fnInfo.signature,
+    `\`\`\``,
+    '',
+    fnInfo.documentation,
+    '',
+    paramDocs,
+    returnDoc,
+  ].join('\n');
+
+  return IDEProjectionSchema.parse({
+    type: 'ide',
+    format: 'hover',
+    content: {
+      kind: 'markdown',
+      value: markdown,
+    },
+  });
+}
+
+/**
+ * Project schema to LSP completion items
+ * @param {string} schemaName - Schema name
+ * @param {object} fields - Schema fields
+ * @returns {IDEProjection} IDE projection with completions
+ */
+export function projectSchemaToCompletions(schemaName, fields) {
+  const completionItems = Object.entries(fields).map(([key, info]) => ({
+    label: key,
+    kind: 10, // LSP CompletionItemKind.Property
+    detail: info.type,
+    documentation: {
+      kind: 'markdown',
+      value: info.description || `${key} field of ${schemaName}`,
+    },
+    insertText: key,
+    insertTextFormat: 1, // PlainText
+  }));
+
+  return IDEProjectionSchema.parse({
+    type: 'ide',
+    format: 'completion',
+    content: {
+      isIncomplete: false,
+      items: completionItems,
+    },
+  });
+}
+
+/**
+ * Project function to LSP definition location
+ * @param {object} location - Source location
+ * @param {string} location.uri - File URI
+ * @param {Range} location.range - Location range
+ * @returns {IDEProjection} IDE projection
+ */
+export function projectToDefinition(location) {
+  return IDEProjectionSchema.parse({
+    type: 'ide',
+    format: 'definition',
+    content: {
+      uri: location.uri,
+      range: location.range,
+    },
+    uri: location.uri,
+    range: location.range,
+  });
+}
+
+/**
+ * Project receipt to LSP diagnostic
+ * @param {object} issue - Issue information
+ * @param {string} issue.message - Error message
+ * @param {string} issue.severity - Severity level (error, warning, info)
+ * @param {Range} issue.range - Error range
+ * @param {string} [issue.code] - Error code
+ * @returns {object} LSP Diagnostic
+ */
+export function projectToDiagnostic(issue) {
+  const severityMap = {
+    error: 1,
+    warning: 2,
+    info: 3,
+    hint: 4,
+  };
+
+  return {
+    range: issue.range,
+    severity: severityMap[issue.severity] || 1,
+    code: issue.code,
+    message: issue.message,
+    source: 'kgc-runtime',
+  };
+}
+
+/**
+ * Generate LSP symbol information for workspace indexing
+ * @param {object} symbolInfo - Symbol information
+ * @param {string} symbolInfo.name - Symbol name
+ * @param {string} symbolInfo.kind - Symbol kind (function, class, variable, etc.)
+ * @param {string} symbolInfo.containerName - Container name
+ * @param {object} symbolInfo.location - Symbol location
+ * @returns {object} LSP DocumentSymbol
+ */
+export function projectToSymbol(symbolInfo) {
+  const kindMap = {
+    function: 12,
+    class: 5,
+    interface: 11,
+    variable: 13,
+    constant: 14,
+    property: 7,
+    method: 6,
+  };
+
+  return {
+    name: symbolInfo.name,
+    kind: kindMap[symbolInfo.kind] || 13,
+    location: symbolInfo.location,
+    containerName: symbolInfo.containerName,
+  };
+}
+
+/**
+ * Generate code action (quick fix) for common issues
+ * @param {object} actionInfo - Action information
+ * @param {string} actionInfo.title - Action title
+ * @param {string} actionInfo.kind - Action kind (quickfix, refactor, etc.)
+ * @param {object} actionInfo.edit - Workspace edit
+ * @returns {object} LSP CodeAction
+ */
+export function projectToCodeAction(actionInfo) {
+  return {
+    title: actionInfo.title,
+    kind: actionInfo.kind || 'quickfix',
+    edit: actionInfo.edit,
+    isPreferred: actionInfo.isPreferred || false,
+  };
+}
+
+/**
+ * Project work item to LSP code lens
+ * @param {object} workItem - Work item
+ * @param {Range} range - Code range
+ * @returns {object} LSP CodeLens
+ */
+export function projectToCodeLens(workItem, range) {
+  return {
+    range,
+    command: {
+      title: `▶ ${workItem.goal}`,
+      command: 'kgc.executeWorkItem',
+      arguments: [workItem.id],
+    },
+  };
+}
+
+/**
+ * Generate signature help for function calls
+ * @param {object} fnInfo - Function information
+ * @param {number} activeParameter - Active parameter index
+ * @returns {IDEProjection} IDE projection with signature help
+ */
+export function projectToSignatureHelp(fnInfo, activeParameter = 0) {
+  const parameters = fnInfo.parameters.map(p => ({
+    label: `${p.name}: ${p.type}`,
+    documentation: {
+      kind: 'markdown',
+      value: p.description,
+    },
+  }));
+
+  const signature = {
+    label: `${fnInfo.name}(${fnInfo.parameters.map(p => `${p.name}: ${p.type}`).join(', ')}) => ${fnInfo.returns.type}`,
+    documentation: {
+      kind: 'markdown',
+      value: fnInfo.documentation,
+    },
+    parameters,
+  };
+
+  return IDEProjectionSchema.parse({
+    type: 'ide',
+    format: 'lsp',
+    content: {
+      signatures: [signature],
+      activeSignature: 0,
+      activeParameter,
+    },
+  });
+}
+
+/**
+ * Generate semantic tokens for syntax highlighting
+ * @param {Array<{line: number, char: number, length: number, tokenType: string, modifiers?: string[]}>} tokens - Token information
+ * @returns {object} LSP SemanticTokens
+ */
+export function projectToSemanticTokens(tokens) {
+  const tokenTypes = ['namespace', 'class', 'function', 'variable', 'property', 'parameter'];
+  const tokenModifiers = ['declaration', 'readonly', 'static', 'async'];
+
+  // Encode tokens as per LSP specification (delta encoding)
+  const data = [];
+  let prevLine = 0;
+  let prevChar = 0;
+
+  for (const token of tokens) {
+    const deltaLine = token.line - prevLine;
+    const deltaChar = deltaLine === 0 ? token.char - prevChar : token.char;
+    const typeIndex = tokenTypes.indexOf(token.tokenType);
+    const modifierBits = (token.modifiers || []).reduce(
+      (acc, mod) => acc | (1 << tokenModifiers.indexOf(mod)),
+      0
+    );
+
+    data.push(deltaLine, deltaChar, token.length, typeIndex, modifierBits);
+
+    prevLine = token.line;
+    prevChar = token.char;
+  }
+
+  return {
+    data,
+  };
+}