@oddessentials/odd-docs 2.0.0

package/dist/index.js

@@ -0,0 +1,1173 @@
+// src/core/ir/builder.ts
+import { createHash } from "crypto";
+
+// src/core/parser/schemaParser.ts
+function parseSchema(schema) {
+  if (!schema) return [];
+  const jsonSchema = schema;
+  const parameters = [];
+  const required = new Set(jsonSchema.required ?? []);
+  if (jsonSchema.properties) {
+    for (const [name, propSchema] of Object.entries(jsonSchema.properties)) {
+      parameters.push(parseProperty(name, propSchema, required.has(name)));
+    }
+  }
+  return parameters;
+}
+function parseProperty(name, schema, isRequired) {
+  const param = {
+    name,
+    type: resolveType(schema),
+    required: isRequired
+  };
+  if (schema.description) {
+    param.description = schema.description;
+  }
+  if (schema.default !== void 0) {
+    param.default = schema.default;
+  }
+  if (schema.enum) {
+    param.enum = schema.enum;
+  }
+  const constraints = buildConstraints(schema);
+  if (constraints) {
+    param.constraints = constraints;
+  }
+  return param;
+}
+function resolveType(schema) {
+  if (schema.$ref) {
+    const refParts = schema.$ref.split("/");
+    return refParts[refParts.length - 1];
+  }
+  if (schema.enum) {
+    return "enum";
+  }
+  if (schema.type === "array" && schema.items) {
+    return `${resolveType(schema.items)}[]`;
+  }
+  return schema.type ?? "unknown";
+}
+function buildConstraints(schema) {
+  const parts = [];
+  if (schema.minimum !== void 0) {
+    parts.push(`min: ${schema.minimum}`);
+  }
+  if (schema.maximum !== void 0) {
+    parts.push(`max: ${schema.maximum}`);
+  }
+  if (schema.minLength !== void 0) {
+    parts.push(`minLength: ${schema.minLength}`);
+  }
+  if (schema.maxLength !== void 0) {
+    parts.push(`maxLength: ${schema.maxLength}`);
+  }
+  if (schema.pattern) {
+    parts.push(`pattern: ${schema.pattern}`);
+  }
+  return parts.length > 0 ? parts.join(", ") : void 0;
+}
+function enrichSchemaSection(section) {
+  return {
+    ...section,
+    parameters: parseSchema(section.schema)
+  };
+}
+
+// src/core/ir/builder.ts
+function buildDocIR(manifest) {
+  const enrichedInputs = enrichSchemaSection(manifest.inputs);
+  const ir = {
+    version: "1.0.0",
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    determinismKey: "",
+    // Computed below
+    entity: manifest.entity,
+    inputs: enrichedInputs,
+    constraints: manifest.constraints,
+    lifecycle: manifest.lifecycle,
+    provenance: {
+      entity: "manifest",
+      inputs: "manifest"
+    }
+  };
+  ir.determinismKey = computeDeterminismKey(ir);
+  return ir;
+}
+function computeDeterminismKey(ir) {
+  const canonical = JSON.stringify({
+    entity: ir.entity,
+    inputs: ir.inputs,
+    constraints: ir.constraints,
+    lifecycle: ir.lifecycle
+  });
+  const hash = createHash("sha256").update(canonical).digest("hex");
+  return `sha256:${hash}`;
+}
+
+// src/core/ir/merger.ts
+var PRECEDENCE = ["introspection", "manifest", "overlay", "narrative"];
+function getPrecedence(source) {
+  const index = PRECEDENCE.indexOf(source);
+  return index === -1 ? PRECEDENCE.length : index;
+}
+function mergeDocIR(sources) {
+  const sorted = [...sources].sort((a, b) => getPrecedence(a.source) - getPrecedence(b.source));
+  let merged = {
+    version: "1.0.0",
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    determinismKey: "",
+    entity: { type: "tool", id: "", version: "" },
+    inputs: { provenance: "manifest" },
+    provenance: {}
+  };
+  for (const { ir, source } of sorted) {
+    merged = mergePartial(merged, ir, source);
+  }
+  if (merged.inputs?.schema) {
+    merged.inputs = enrichSchemaSection(merged.inputs);
+  }
+  if (merged.outputs?.schema) {
+    merged.outputs = enrichSchemaSection(merged.outputs);
+  }
+  merged.determinismKey = computeDeterminismKey(merged);
+  return merged;
+}
+function mergePartial(base, partial, source) {
+  const result = { ...base };
+  if (partial.entity) {
+    const baseProvenance = base.provenance?.entity;
+    if (!baseProvenance || getPrecedence(source) <= getPrecedence(baseProvenance)) {
+      result.entity = {
+        ...result.entity,
+        ...partial.entity
+      };
+      result.provenance = { ...result.provenance, entity: source };
+    }
+  }
+  if (partial.inputs) {
+    const baseProvenance = base.inputs?.provenance;
+    if (!baseProvenance || getPrecedence(source) <= getPrecedence(baseProvenance)) {
+      result.inputs = {
+        ...result.inputs,
+        ...partial.inputs,
+        provenance: source
+      };
+      result.provenance = { ...result.provenance, inputs: source };
+    }
+  }
+  if (partial.outputs) {
+    const baseProvenance = base.outputs?.provenance;
+    if (!baseProvenance || getPrecedence(source) <= getPrecedence(baseProvenance)) {
+      result.outputs = {
+        ...result.outputs,
+        ...partial.outputs,
+        provenance: source
+      };
+      result.provenance = { ...result.provenance, outputs: source };
+    }
+  }
+  if (partial.overview) {
+    result.overview = result.overview ?? {};
+    if (partial.overview.intent && !result.overview.intent) {
+      result.overview.intent = partial.overview.intent;
+    }
+    if (partial.overview.useCases) {
+      const existing = new Set(result.overview.useCases ?? []);
+      for (const useCase of partial.overview.useCases) {
+        existing.add(useCase);
+      }
+      result.overview.useCases = [...existing];
+    }
+    if (partial.overview.sideEffects) {
+      result.overview.sideEffects = mergeSideEffects(
+        result.overview.sideEffects ?? [],
+        partial.overview.sideEffects,
+        source
+      );
+    }
+  }
+  if (partial.constraints) {
+    result.constraints = result.constraints ?? {};
+    if (partial.constraints.capabilities) {
+      result.constraints.capabilities = mergeCapabilities(
+        result.constraints.capabilities ?? [],
+        partial.constraints.capabilities,
+        source
+      );
+    }
+    if (partial.constraints.timeoutMs !== void 0) {
+      const baseProvenance = base.provenance?.constraints;
+      if (!baseProvenance || getPrecedence(source) <= getPrecedence(baseProvenance)) {
+        result.constraints.timeoutMs = partial.constraints.timeoutMs;
+      }
+    }
+    if (partial.constraints.resourceLimits) {
+      const baseProvenance = base.provenance?.constraints;
+      if (!baseProvenance || getPrecedence(source) <= getPrecedence(baseProvenance)) {
+        result.constraints.resourceLimits = {
+          ...result.constraints.resourceLimits,
+          ...partial.constraints.resourceLimits
+        };
+      }
+    }
+  }
+  if (partial.narrative) {
+    result.narrative = result.narrative ?? {};
+    if (partial.narrative.examples) {
+      result.narrative.examples = [
+        ...result.narrative.examples ?? [],
+        ...partial.narrative.examples
+      ];
+    }
+    if (partial.narrative.notes) {
+      result.narrative.notes = [...result.narrative.notes ?? [], ...partial.narrative.notes];
+    }
+  }
+  if (partial.errors) {
+    result.errors = mergeErrors(result.errors ?? [], partial.errors, source);
+  }
+  if (partial.lifecycle) {
+    const baseProvenance = base.provenance?.lifecycle;
+    if (!baseProvenance || getPrecedence(source) <= getPrecedence(baseProvenance)) {
+      result.lifecycle = {
+        ...result.lifecycle,
+        ...partial.lifecycle
+      };
+      result.provenance = { ...result.provenance, lifecycle: source };
+    }
+  }
+  return result;
+}
+function mergeSideEffects(base, incoming, source) {
+  const byType = /* @__PURE__ */ new Map();
+  for (const effect of base) {
+    byType.set(effect.type, effect);
+  }
+  for (const effect of incoming) {
+    const existing = byType.get(effect.type);
+    if (!existing || getPrecedence(source) <= getPrecedence(existing.provenance ?? "narrative")) {
+      byType.set(effect.type, { ...effect, provenance: source });
+    }
+  }
+  return [...byType.values()].sort((a, b) => a.type.localeCompare(b.type));
+}
+function mergeCapabilities(base, incoming, source) {
+  const byType = /* @__PURE__ */ new Map();
+  for (const cap of base) {
+    byType.set(cap.type, cap);
+  }
+  for (const cap of incoming) {
+    const existing = byType.get(cap.type);
+    if (!existing || getPrecedence(source) <= getPrecedence(existing.provenance ?? "narrative")) {
+      byType.set(cap.type, { ...cap, provenance: source });
+    }
+  }
+  return [...byType.values()].sort((a, b) => a.type.localeCompare(b.type));
+}
+function mergeErrors(base, incoming, source) {
+  if (!base) return incoming;
+  if (!incoming) return base;
+  const byCode = /* @__PURE__ */ new Map();
+  for (const err of base) {
+    byCode.set(err.code, err);
+  }
+  for (const err of incoming) {
+    const existing = byCode.get(err.code);
+    if (!existing || getPrecedence(source) <= getPrecedence(existing.provenance ?? "narrative")) {
+      byCode.set(err.code, { ...err, provenance: source });
+    }
+  }
+  return [...byCode.values()].sort((a, b) => a.code.localeCompare(b.code));
+}
+
+// src/core/capabilities.ts
+var KNOWN_CAPABILITIES = [
+  "network",
+  "filesystem",
+  "secrets",
+  "exec",
+  "subprocess",
+  "database",
+  "queue"
+];
+var SAFETY_AFFECTING_PATTERNS = ["network", "exec", "subprocess", "write", "delete"];
+function isKnownCapability(capability) {
+  return KNOWN_CAPABILITIES.includes(capability);
+}
+function isSafetyAffecting(capability) {
+  return SAFETY_AFFECTING_PATTERNS.some(
+    (pattern) => capability.toLowerCase().includes(pattern.toLowerCase())
+  );
+}
+
+// src/core/ir/validator.ts
+function validateDocIR(ir, options = {}) {
+  const issues = [];
+  if (!ir.entity.id) {
+    issues.push({
+      severity: "error",
+      code: "MISSING_TOOL_ID",
+      message: "Tool ID is required",
+      path: "entity.id"
+    });
+  }
+  if (!ir.entity.version) {
+    issues.push({
+      severity: "error",
+      code: "MISSING_VERSION",
+      message: "Version is required",
+      path: "entity.version"
+    });
+  }
+  if (!ir.inputs?.schema && !ir.inputs?.parameters?.length) {
+    issues.push({
+      severity: "error",
+      code: "MISSING_PARAMETERS_SCHEMA",
+      message: "Parameters schema is required",
+      path: "inputs"
+    });
+  }
+  if (ir.constraints?.capabilities) {
+    for (const cap of ir.constraints.capabilities) {
+      if (!isKnownCapability(cap.type)) {
+        const isSafety = isSafetyAffecting(cap.type);
+        issues.push({
+          severity: options.strict && isSafety ? "error" : "warning",
+          code: "UNKNOWN_CAPABILITY",
+          message: `Unknown capability: ${cap.type}${isSafety ? " (safety-affecting)" : ""}`,
+          path: `constraints.capabilities.${cap.type}`,
+          provenance: cap.provenance
+        });
+      }
+    }
+  }
+  issues.push(...checkStructuralContradictions(ir));
+  const hasErrors = issues.some((i) => i.severity === "error");
+  return {
+    valid: !hasErrors,
+    issues
+  };
+}
+function checkStructuralContradictions(ir) {
+  const issues = [];
+  if (ir.narrative?.notes && ir.inputs?.parameters) {
+    const schemaParams = new Set(ir.inputs.parameters.map((p) => p.name.toLowerCase()));
+    for (const note of ir.narrative.notes) {
+      const paramMentions = note.match(/(?:parameter|param)\s+[`"']?(\w+)[`"']?/gi) ?? [];
+      const theParamMentions = note.match(/the\s+[`"']?(\w+)[`"']?\s+parameter/gi) ?? [];
+      for (const match of [...paramMentions, ...theParamMentions]) {
+        const paramName = match.replace(/.*?[`"']?(\w+)[`"']?.*/i, "$1").toLowerCase();
+        if (paramName && !schemaParams.has(paramName) && paramName !== "parameter") {
+          issues.push({
+            severity: "error",
+            code: "NARRATIVE_REFERENCES_UNDEFINED_PARAM",
+            message: `Narrative references parameter "${paramName}" not in schema`,
+            path: "narrative.notes",
+            provenance: "narrative"
+          });
+        }
+      }
+    }
+  }
+  if (ir.narrative?.examples && ir.inputs?.parameters) {
+    const schemaParams = new Set(ir.inputs.parameters.map((p) => p.name));
+    for (const example of ir.narrative.examples) {
+      if (example.input && typeof example.input === "object") {
+        for (const key of Object.keys(example.input)) {
+          if (!schemaParams.has(key)) {
+            issues.push({
+              severity: "warning",
+              code: "EXAMPLE_USES_UNDEFINED_PARAM",
+              message: `Example uses parameter "${key}" not in schema`,
+              path: `narrative.examples.${example.title ?? "unnamed"}`,
+              provenance: "narrative"
+            });
+          }
+        }
+      }
+    }
+  }
+  if (ir.overview?.sideEffects && ir.constraints?.capabilities) {
+    const capTypes = new Set(ir.constraints.capabilities.map((c) => c.type));
+    for (const effect of ir.overview.sideEffects) {
+      const expectedCap = mapSideEffectToCapability(effect.type);
+      if (expectedCap && !capTypes.has(expectedCap)) {
+        issues.push({
+          severity: "error",
+          code: "SIDE_EFFECT_CAPABILITY_MISMATCH",
+          message: `Side effect "${effect.type}" requires capability "${expectedCap}" which is not declared`,
+          path: `overview.sideEffects.${effect.type}`,
+          provenance: effect.provenance
+        });
+      }
+    }
+  }
+  return issues;
+}
+function mapSideEffectToCapability(effectType) {
+  const mapping = {
+    filesystem: "filesystem",
+    network: "network",
+    secrets: "secrets",
+    exec: "exec",
+    subprocess: "subprocess",
+    database: "database",
+    queue: "queue"
+  };
+  return mapping[effectType] ?? null;
+}
+function formatValidationResult(result, repoPath) {
+  const lines = [];
+  lines.push(`Validating: ${repoPath}`);
+  lines.push("");
+  if (result.valid) {
+    lines.push("\u2713 Validation passed");
+  } else {
+    lines.push("\u2717 Validation failed");
+  }
+  lines.push("");
+  const errors = result.issues.filter((i) => i.severity === "error");
+  const warnings = result.issues.filter((i) => i.severity === "warning");
+  if (errors.length > 0) {
+    lines.push(`Errors (${errors.length}):`);
+    for (const issue of errors) {
+      lines.push(`  \u2717 [${issue.code}] ${issue.message}`);
+      if (issue.path) {
+        lines.push(`    at ${issue.path}`);
+      }
+    }
+    lines.push("");
+  }
+  if (warnings.length > 0) {
+    lines.push(`Warnings (${warnings.length}):`);
+    for (const issue of warnings) {
+      lines.push(`  \u26A0 [${issue.code}] ${issue.message}`);
+      if (issue.path) {
+        lines.push(`    at ${issue.path}`);
+      }
+    }
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+
+// src/core/parser/manifestParser.ts
+import { readFile } from "fs/promises";
+import { join } from "path";
+async function parseManifest(repoPath) {
+  const manifestPath = join(repoPath, "manifest.json");
+  let content;
+  try {
+    content = await readFile(manifestPath, "utf-8");
+  } catch {
+    throw new Error(`Manifest not found: ${manifestPath}`);
+  }
+  let manifest;
+  try {
+    manifest = JSON.parse(content);
+  } catch {
+    throw new Error(`Invalid JSON in manifest: ${manifestPath}`);
+  }
+  if (!manifest.tool_id) {
+    throw new Error("Manifest missing required field: tool_id");
+  }
+  if (!manifest.version) {
+    throw new Error("Manifest missing required field: version");
+  }
+  const capabilities = [];
+  if (manifest.capabilities) {
+    for (const [type, values] of Object.entries(manifest.capabilities)) {
+      if (Array.isArray(values) && values.length > 0) {
+        capabilities.push({ type, values, provenance: "manifest" });
+      }
+    }
+  }
+  const result = {
+    entity: {
+      type: "tool",
+      id: manifest.tool_id,
+      version: manifest.version,
+      description: manifest.description
+    },
+    inputs: {
+      schema: manifest.parameters,
+      provenance: "manifest"
+    }
+  };
+  if (capabilities.length > 0 || manifest.timeout_ms || manifest.resource_limits) {
+    result.constraints = {
+      capabilities: capabilities.length > 0 ? capabilities : void 0,
+      timeoutMs: manifest.timeout_ms,
+      resourceLimits: manifest.resource_limits ? {
+        memoryMb: manifest.resource_limits.memory_mb,
+        cpuCores: manifest.resource_limits.cpu_cores
+      } : void 0
+    };
+  }
+  if (manifest.deprecation) {
+    result.lifecycle = {
+      version: manifest.version,
+      deprecation: {
+        deprecatedAt: manifest.deprecation.deprecated_at,
+        sunsetDate: manifest.deprecation.sunset_date,
+        migrationUrl: manifest.deprecation.migration_url
+      }
+    };
+  }
+  return result;
+}
+
+// src/core/parser/mcpIntrospection.ts
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+async function introspectMcpServer(options) {
+  if (!options.serverCommand) {
+    throw new Error("Server command is required for introspection");
+  }
+  const transport = new StdioClientTransport({
+    command: options.serverCommand,
+    args: options.serverArgs ?? []
+  });
+  const client = new Client(
+    {
+      name: "odd-docs",
+      version: "0.1.0"
+    },
+    {
+      capabilities: {}
+    }
+  );
+  const result = {};
+  try {
+    await client.connect(transport);
+    try {
+      const toolsResponse = await client.listTools();
+      result.tools = toolsResponse.tools.map((t) => ({
+        name: t.name,
+        description: t.description,
+        inputSchema: t.inputSchema
+      }));
+    } catch {
+    }
+    try {
+      const resourcesResponse = await client.listResources();
+      result.resources = resourcesResponse.resources.map((r) => ({
+        uri: r.uri,
+        name: r.name,
+        description: r.description,
+        mimeType: r.mimeType
+      }));
+    } catch {
+    }
+    try {
+      const promptsResponse = await client.listPrompts();
+      result.prompts = promptsResponse.prompts.map((p) => ({
+        name: p.name,
+        description: p.description,
+        arguments: p.arguments
+      }));
+    } catch {
+    }
+  } finally {
+    await client.close();
+  }
+  return result;
+}
+function introspectionToPartialIR(introspection, toolName) {
+  const provenance = "introspection";
+  const tool = toolName ? introspection.tools?.find((t) => t.name === toolName) : introspection.tools?.[0];
+  if (!tool) {
+    return { provenance: { source: provenance } };
+  }
+  const inputs = {
+    schema: tool.inputSchema,
+    provenance
+  };
+  const capabilities = [];
+  if (introspection.resources?.length) {
+    capabilities.push({
+      type: "resources",
+      values: introspection.resources.map((r) => r.uri),
+      provenance
+    });
+  }
+  return {
+    entity: {
+      type: "tool",
+      id: tool.name,
+      version: "0.0.0",
+      // Runtime doesn't provide version
+      description: tool.description
+    },
+    inputs,
+    constraints: capabilities.length > 0 ? { capabilities } : void 0,
+    provenance: {
+      entity: provenance,
+      inputs: provenance
+    }
+  };
+}
+function parseIntrospectTarget(target) {
+  if (target.startsWith("stdio://")) {
+    const parts2 = target.slice(8).split(" ");
+    return {
+      serverCommand: parts2[0],
+      serverArgs: parts2.slice(1)
+    };
+  }
+  if (target.startsWith("npx ")) {
+    const parts2 = target.split(" ");
+    return {
+      serverCommand: "npx",
+      serverArgs: parts2.slice(1)
+    };
+  }
+  if (target.startsWith("node ")) {
+    const parts2 = target.split(" ");
+    return {
+      serverCommand: "node",
+      serverArgs: parts2.slice(1)
+    };
+  }
+  const parts = target.split(" ");
+  return {
+    serverCommand: parts[0],
+    serverArgs: parts.slice(1)
+  };
+}
+
+// src/core/renderer/markdownRenderer.ts
+function renderMarkdown(ir) {
+  const lines = [];
+  lines.push(`# ${ir.entity.id}`);
+  lines.push("");
+  lines.push(`**Version:** ${ir.entity.version}  `);
+  lines.push(`**Type:** ${ir.entity.type}  `);
+  if (ir.entity.description) {
+    lines.push("");
+    lines.push(ir.entity.description);
+  }
+  lines.push("");
+  if (ir.overview) {
+    lines.push("## Overview");
+    lines.push("");
+    if (ir.overview.intent) {
+      lines.push(`**Intent:** ${ir.overview.intent}`);
+      lines.push("");
+    }
+    if (ir.overview.useCases?.length) {
+      lines.push("### Use Cases");
+      lines.push("");
+      for (const useCase of ir.overview.useCases) {
+        lines.push(`- ${useCase}`);
+      }
+      lines.push("");
+    }
+    if (ir.overview.sideEffects?.length) {
+      lines.push("### Side Effects");
+      lines.push("");
+      for (const effect of ir.overview.sideEffects) {
+        lines.push(
+          `- **${effect.type}**: ${effect.description} ${provenanceBadge(effect.provenance)}`
+        );
+      }
+      lines.push("");
+    }
+  }
+  if (ir.inputs?.parameters?.length) {
+    lines.push("## Inputs");
+    lines.push("");
+    lines.push(provenanceBadge(ir.inputs.provenance));
+    lines.push("");
+    lines.push(renderParameterTable(ir.inputs.parameters));
+    lines.push("");
+  }
+  if (ir.outputs?.parameters?.length) {
+    lines.push("## Outputs");
+    lines.push("");
+    lines.push(provenanceBadge(ir.outputs.provenance));
+    lines.push("");
+    lines.push(renderParameterTable(ir.outputs.parameters));
+    lines.push("");
+  }
+  if (ir.constraints) {
+    lines.push("## Constraints");
+    lines.push("");
+    if (ir.constraints.capabilities?.length) {
+      lines.push("### Capabilities");
+      lines.push("");
+      for (const cap of ir.constraints.capabilities) {
+        const values = cap.values?.join(", ") ?? "enabled";
+        lines.push(`- **${cap.type}**: ${values} ${provenanceBadge(cap.provenance)}`);
+      }
+      lines.push("");
+    }
+    if (ir.constraints.timeoutMs) {
+      lines.push(`**Timeout:** ${ir.constraints.timeoutMs}ms`);
+      lines.push("");
+    }
+    if (ir.constraints.resourceLimits) {
+      lines.push("### Resource Limits");
+      lines.push("");
+      if (ir.constraints.resourceLimits.memoryMb) {
+        lines.push(`- Memory: ${ir.constraints.resourceLimits.memoryMb} MB`);
+      }
+      if (ir.constraints.resourceLimits.cpuCores) {
+        lines.push(`- CPU: ${ir.constraints.resourceLimits.cpuCores} cores`);
+      }
+      lines.push("");
+    }
+  }
+  if (ir.errors?.length) {
+    lines.push("## Errors");
+    lines.push("");
+    lines.push("| Code | Description | Recovery |");
+    lines.push("|------|-------------|----------|");
+    for (const err of ir.errors) {
+      lines.push(`| \`${err.code}\` | ${err.description ?? ""} | ${err.recovery ?? ""} |`);
+    }
+    lines.push("");
+  }
+  if (ir.lifecycle?.deprecation) {
+    lines.push("## Lifecycle");
+    lines.push("");
+    lines.push("> [!WARNING]");
+    lines.push(`> This tool is deprecated as of ${ir.lifecycle.deprecation.deprecatedAt}.`);
+    lines.push(`> Sunset date: ${ir.lifecycle.deprecation.sunsetDate}`);
+    if (ir.lifecycle.deprecation.migrationUrl) {
+      lines.push(`> Migration guide: ${ir.lifecycle.deprecation.migrationUrl}`);
+    }
+    lines.push("");
+  }
+  if (ir.narrative?.examples?.length) {
+    lines.push("## Examples");
+    lines.push("");
+    for (const example of ir.narrative.examples) {
+      if (example.title) {
+        lines.push(`### ${example.title}`);
+        lines.push("");
+      }
+      if (example.description) {
+        lines.push(example.description);
+        lines.push("");
+      }
+      if (example.input) {
+        lines.push("**Input:**");
+        lines.push("```json");
+        lines.push(JSON.stringify(example.input, null, 2));
+        lines.push("```");
+        lines.push("");
+      }
+      if (example.output) {
+        lines.push("**Output:**");
+        lines.push("```json");
+        lines.push(JSON.stringify(example.output, null, 2));
+        lines.push("```");
+        lines.push("");
+      }
+    }
+  }
+  if (ir.narrative?.notes?.length) {
+    lines.push("## Notes");
+    lines.push("");
+    lines.push("*[author notes]*");
+    lines.push("");
+    for (const note of ir.narrative.notes) {
+      lines.push(note);
+      lines.push("");
+    }
+  }
+  lines.push("---");
+  lines.push("");
+  lines.push(`*Generated at ${ir.generatedAt}*  `);
+  lines.push(`*Determinism key: \`${ir.determinismKey}\`*`);
+  return lines.join("\n");
+}
+function renderParameterTable(params) {
+  const lines = [];
+  lines.push("| Name | Type | Required | Default | Description |");
+  lines.push("|------|------|----------|---------|-------------|");
+  for (const param of params) {
+    const required = param.required ? "\u2713" : "";
+    const defaultVal = param.default !== void 0 ? `\`${JSON.stringify(param.default)}\`` : "";
+    const desc = param.description ?? "";
+    lines.push(`| \`${param.name}\` | \`${param.type}\` | ${required} | ${defaultVal} | ${desc} |`);
+  }
+  return lines.join("\n");
+}
+function provenanceBadge(source) {
+  if (!source) return "";
+  const badges = {
+    introspection: "`[from introspection]`",
+    manifest: "`[from schema]`",
+    overlay: "`[from overlay]`",
+    narrative: "`[author notes]`"
+  };
+  return badges[source] ?? "";
+}
+
+// src/core/renderer/htmlRenderer.ts
+import { marked } from "marked";
+function renderHTML(ir) {
+  const markdown = renderMarkdown(ir);
+  const htmlContent = marked.parse(markdown);
+  return `<!DOCTYPE html>
+<html lang="en" data-theme="light">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <meta name="description" content="${escapeHtml(ir.entity.description ?? `Documentation for ${ir.entity.id}`)}">
+  <title>${escapeHtml(ir.entity.id)} - odd-docs</title>
+  <style>
+${getThemeStyles()}
+  </style>
+</head>
+<body>
+  <div class="container">
+    <header>
+      <nav class="breadcrumb">
+        <a href="index.html">Home</a> / <span>${escapeHtml(ir.entity.id)}</span>
+      </nav>
+    </header>
+    <main class="content">
+${htmlContent}
+    </main>
+    <footer>
+      <p class="meta">
+        Generated by <a href="https://github.com/oddessentials/odd-docs">odd-docs</a> at ${ir.generatedAt}
+      </p>
+      <p class="determinism">
+        <code>${ir.determinismKey}</code>
+      </p>
+    </footer>
+  </div>
+  <script>
+${getThemeScript()}
+  </script>
+</body>
+</html>`;
+}
+function renderIndexHTML(docs) {
+  const items = docs.map(
+    (ir) => `
+      <li>
+        <a href="${ir.entity.id}.html">
+          <strong>${escapeHtml(ir.entity.id)}</strong>
+          <span class="version">v${ir.entity.version}</span>
+        </a>
+        <p>${escapeHtml(ir.entity.description ?? "")}</p>
+      </li>`
+  ).join("\n");
+  return `<!DOCTYPE html>
+<html lang="en" data-theme="light">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Documentation - odd-docs</title>
+  <style>
+${getThemeStyles()}
+  </style>
+</head>
+<body>
+  <div class="container">
+    <header>
+      <h1>Documentation</h1>
+    </header>
+    <main class="content">
+      <ul class="doc-list">
+${items}
+      </ul>
+    </main>
+    <footer>
+      <p class="meta">Generated by <a href="https://github.com/oddessentials/odd-docs">odd-docs</a></p>
+    </footer>
+  </div>
+  <script>
+${getThemeScript()}
+  </script>
+</body>
+</html>`;
+}
+function escapeHtml(str) {
+  return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#039;");
+}
+function getThemeStyles() {
+  return `
+    /* CSS Variables for theming */
+    :root {
+      /* Colors - neutral palette */
+      --color-bg: #ffffff;
+      --color-bg-secondary: #f8f9fa;
+      --color-text: #1a1a2e;
+      --color-text-muted: #6c757d;
+      --color-border: #dee2e6;
+      --color-link: #0066cc;
+      --color-link-hover: #004499;
+      --color-accent: #0066cc;
+      --color-success: #28a745;
+      --color-warning: #ffc107;
+      --color-error: #dc3545;
+      
+      /* Typography */
+      --font-sans: system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif;
+      --font-mono: 'SF Mono', Monaco, 'Cascadia Code', monospace;
+      --font-size-base: 16px;
+      --line-height: 1.6;
+      
+      /* Spacing */
+      --space-xs: 0.25rem;
+      --space-sm: 0.5rem;
+      --space-md: 1rem;
+      --space-lg: 1.5rem;
+      --space-xl: 2rem;
+      
+      /* Layout */
+      --max-width: 800px;
+      --border-radius: 4px;
+    }
+    
+    [data-theme="dark"] {
+      --color-bg: #1a1a2e;
+      --color-bg-secondary: #16213e;
+      --color-text: #e8e8e8;
+      --color-text-muted: #a0a0a0;
+      --color-border: #3a3a5e;
+      --color-link: #66b3ff;
+      --color-link-hover: #99ccff;
+    }
+    
+    /* Reset */
+    *, *::before, *::after {
+      box-sizing: border-box;
+    }
+    
+    body {
+      margin: 0;
+      padding: 0;
+      font-family: var(--font-sans);
+      font-size: var(--font-size-base);
+      line-height: var(--line-height);
+      color: var(--color-text);
+      background: var(--color-bg);
+    }
+    
+    /* Container */
+    .container {
+      max-width: var(--max-width);
+      margin: 0 auto;
+      padding: var(--space-lg);
+    }
+    
+    /* Typography */
+    h1, h2, h3, h4, h5, h6 {
+      margin-top: var(--space-xl);
+      margin-bottom: var(--space-md);
+      line-height: 1.3;
+    }
+    
+    h1 { font-size: 2rem; }
+    h2 { font-size: 1.5rem; border-bottom: 1px solid var(--color-border); padding-bottom: var(--space-sm); }
+    h3 { font-size: 1.25rem; }
+    
+    p { margin: var(--space-md) 0; }
+    
+    a {
+      color: var(--color-link);
+      text-decoration: none;
+    }
+    
+    a:hover {
+      color: var(--color-link-hover);
+      text-decoration: underline;
+    }
+    
+    /* Code */
+    code {
+      font-family: var(--font-mono);
+      font-size: 0.9em;
+      background: var(--color-bg-secondary);
+      padding: var(--space-xs) var(--space-sm);
+      border-radius: var(--border-radius);
+    }
+    
+    pre {
+      background: var(--color-bg-secondary);
+      padding: var(--space-md);
+      border-radius: var(--border-radius);
+      overflow-x: auto;
+    }
+    
+    pre code {
+      background: none;
+      padding: 0;
+    }
+    
+    /* Tables */
+    table {
+      width: 100%;
+      border-collapse: collapse;
+      margin: var(--space-md) 0;
+    }
+    
+    th, td {
+      padding: var(--space-sm) var(--space-md);
+      border: 1px solid var(--color-border);
+      text-align: left;
+    }
+    
+    th {
+      background: var(--color-bg-secondary);
+      font-weight: 600;
+    }
+    
+    /* Provenance badges */
+    code[class*="from"] {
+      font-size: 0.75em;
+      color: var(--color-text-muted);
+      background: transparent;
+    }
+    
+    /* Blockquotes (for warnings/notes) */
+    blockquote {
+      margin: var(--space-md) 0;
+      padding: var(--space-md);
+      border-left: 4px solid var(--color-warning);
+      background: var(--color-bg-secondary);
+    }
+    
+    blockquote p:first-child { margin-top: 0; }
+    blockquote p:last-child { margin-bottom: 0; }
+    
+    /* Lists */
+    ul, ol {
+      padding-left: var(--space-lg);
+    }
+    
+    li { margin: var(--space-sm) 0; }
+    
+    /* Doc list (index page) */
+    .doc-list {
+      list-style: none;
+      padding: 0;
+    }
+    
+    .doc-list li {
+      padding: var(--space-md);
+      border: 1px solid var(--color-border);
+      border-radius: var(--border-radius);
+      margin-bottom: var(--space-md);
+    }
+    
+    .doc-list a {
+      display: flex;
+      align-items: center;
+      gap: var(--space-sm);
+    }
+    
+    .doc-list .version {
+      color: var(--color-text-muted);
+      font-size: 0.875em;
+    }
+    
+    .doc-list p {
+      margin: var(--space-sm) 0 0;
+      color: var(--color-text-muted);
+    }
+    
+    /* Header */
+    header {
+      margin-bottom: var(--space-lg);
+    }
+    
+    .breadcrumb {
+      font-size: 0.875em;
+      color: var(--color-text-muted);
+    }
+    
+    .breadcrumb a {
+      color: inherit;
+    }
+    
+    /* Footer */
+    footer {
+      margin-top: var(--space-xl);
+      padding-top: var(--space-lg);
+      border-top: 1px solid var(--color-border);
+      font-size: 0.875em;
+      color: var(--color-text-muted);
+    }
+    
+    .determinism code {
+      font-size: 0.75em;
+    }
+    
+    /* Theme toggle */
+    .theme-toggle {
+      position: fixed;
+      top: var(--space-md);
+      right: var(--space-md);
+      padding: var(--space-sm) var(--space-md);
+      border: 1px solid var(--color-border);
+      border-radius: var(--border-radius);
+      background: var(--color-bg);
+      cursor: pointer;
+      font-size: 0.875em;
+    }
+    
+    /* Responsive */
+    @media (max-width: 600px) {
+      .container { padding: var(--space-md); }
+      h1 { font-size: 1.5rem; }
+      h2 { font-size: 1.25rem; }
+      table { font-size: 0.875em; }
+    }
+  `;
+}
+function getThemeScript() {
+  return `
+    // Theme toggle
+    const toggle = document.createElement('button');
+    toggle.className = 'theme-toggle';
+    toggle.textContent = '\u{1F319}';
+    toggle.onclick = () => {
+      const html = document.documentElement;
+      const isDark = html.dataset.theme === 'dark';
+      html.dataset.theme = isDark ? 'light' : 'dark';
+      toggle.textContent = isDark ? '\u{1F319}' : '\u2600\uFE0F';
+      localStorage.setItem('theme', html.dataset.theme);
+    };
+    document.body.appendChild(toggle);
+    
+    // Restore saved theme
+    const saved = localStorage.getItem('theme');
+    if (saved) {
+      document.documentElement.dataset.theme = saved;
+      toggle.textContent = saved === 'dark' ? '\u2600\uFE0F' : '\u{1F319}';
+    } else if (window.matchMedia('(prefers-color-scheme: dark)').matches) {
+      document.documentElement.dataset.theme = 'dark';
+      toggle.textContent = '\u2600\uFE0F';
+    }
+  `;
+}
+export {
+  KNOWN_CAPABILITIES,
+  SAFETY_AFFECTING_PATTERNS,
+  buildDocIR,
+  computeDeterminismKey,
+  enrichSchemaSection,
+  formatValidationResult,
+  introspectMcpServer,
+  introspectionToPartialIR,
+  isKnownCapability,
+  isSafetyAffecting,
+  mergeDocIR,
+  parseIntrospectTarget,
+  parseManifest,
+  parseSchema,
+  renderHTML,
+  renderIndexHTML,
+  renderMarkdown,
+  validateDocIR
+};
+//# sourceMappingURL=index.js.map