@svashevchenko/ez-know 0.1.0 → 0.2.0

package/dist/rest/server.js

@@ -529,13 +529,131 @@ var KNOWLEDGE_EXTRACTION_TYPE_LOOKUP = new Map(
     ...definition.aliases.map((alias) => [alias, definition])
   ])
 );
+function listKnowledgeExtractionTypes() {
+  return KNOWLEDGE_EXTRACTION_TYPES.slice();
+}
+function getKnowledgeExtractionTypeDefinition(type) {
+  const normalized = type.trim().toLowerCase().replace(/-/g, "_");
+  const exactMatch = KNOWLEDGE_EXTRACTION_TYPE_LOOKUP.get(normalized);
+  if (exactMatch) {
+    return exactMatch;
+  }
+  return KNOWLEDGE_EXTRACTION_TYPE_LOOKUP.get(type.trim().toLowerCase());
+}
+function requireKnowledgeExtractionTypeDefinition(type) {
+  const definition = getKnowledgeExtractionTypeDefinition(type);
+  if (!definition) {
+    throw new Error(
+      `Unsupported extraction type "${type}". Supported types: ${KNOWLEDGE_EXTRACTION_TYPES.map(
+        (entry) => entry.collection
+      ).join(", ")}`
+    );
+  }
+  return definition;
+}
+function buildKnowledgeExtractionSchemaUri(type) {
+  return `ez-know://extraction/schema/${requireKnowledgeExtractionTypeDefinition(type).collection}`;
+}
+function buildKnowledgeExtractionGuideUri(type) {
+  return `ez-know://extraction/guide/${requireKnowledgeExtractionTypeDefinition(type).collection}`;
+}
 
 // packages/core/src/knowledge/extraction-resources.ts
+import { readFile } from "node:fs/promises";
 import { z as z2 } from "zod/v4";
+var KNOWLEDGE_EXTRACTION_TYPES_RESOURCE_URI = "ez-know://extraction/types";
+var KNOWLEDGE_EXTRACTION_SCHEMA_RESOURCE_URI = "ez-know://extraction/schema/{type}";
+var KNOWLEDGE_EXTRACTION_GUIDE_RESOURCE_URI = "ez-know://extraction/guide/{type}";
+function createKnowledgeExtractionTypeResource(definition) {
+  return {
+    collection: definition.collection,
+    title: definition.title,
+    aliases: definition.aliases.slice(),
+    storageFile: definition.storageFile,
+    idConvention: { ...definition.idConvention },
+    schemaUri: buildKnowledgeExtractionSchemaUri(definition.collection),
+    guideUri: buildKnowledgeExtractionGuideUri(definition.collection)
+  };
+}
+function buildKnowledgeExtractionTypeIndexDocument() {
+  const supportedTypes = listKnowledgeExtractionTypes().map(
+    createKnowledgeExtractionTypeResource
+  );
+  return {
+    resource: {
+      uri: KNOWLEDGE_EXTRACTION_TYPES_RESOURCE_URI,
+      title: "Knowledge Extraction Types",
+      description: "Canonical registry of knowledge types supported by the extraction workflow."
+    },
+    source: {
+      kind: "registry",
+      count: supportedTypes.length
+    },
+    supportedTypes
+  };
+}
+function buildKnowledgeExtractionSchemaDocument(type) {
+  const definition = requireKnowledgeExtractionTypeDefinition(type);
+  const resource = createKnowledgeExtractionTypeResource(definition);
+  return {
+    resource: {
+      uri: resource.schemaUri,
+      title: `${definition.title} Extraction Schema`,
+      description: "Runtime JSON Schema view of the canonical knowledge object model."
+    },
+    source: {
+      kind: "runtime-zod",
+      collection: definition.collection,
+      schemaName: definition.schemaName,
+      storageFile: definition.storageFile,
+      guideUri: resource.guideUri
+    },
+    type: resource,
+    schema: z2.toJSONSchema(definition.schema)
+  };
+}
+async function readKnowledgeExtractionGuideMarkdown(type) {
+  const definition = requireKnowledgeExtractionTypeDefinition(type);
+  const guideFileName = definition.guideFilePath.split("/").pop();
+  if (!guideFileName) {
+    throw new Error(
+      `Invalid guide file path for extraction type "${definition.collection}".`
+    );
+  }
+  const guideUrl = new URL(`./guides/${guideFileName}`, import.meta.url);
+  const markdown = await readFile(guideUrl, "utf8");
+  return {
+    definition,
+    markdown
+  };
+}
+async function buildKnowledgeExtractionGuideDocument(type) {
+  const definition = requireKnowledgeExtractionTypeDefinition(type);
+  const resource = createKnowledgeExtractionTypeResource(definition);
+  const { markdown } = await readKnowledgeExtractionGuideMarkdown(type);
+  return {
+    resource: {
+      uri: resource.guideUri,
+      title: `${definition.title} Extraction Guide`,
+      description: "Checked-in Markdown guidance for extracting this knowledge type."
+    },
+    source: {
+      kind: "checked-in-markdown",
+      filePath: definition.guideFilePath
+    },
+    type: resource,
+    markdown
+  };
+}
+function listKnowledgeExtractionResourceTypes() {
+  return listKnowledgeExtractionTypes().map(
+    createKnowledgeExtractionTypeResource
+  );
+}
 
 // packages/core/src/knowledge/loader.ts
 import { existsSync } from "node:fs";
-import { readFile } from "node:fs/promises";
+import { readFile as readFile2 } from "node:fs/promises";
 import { basename, join } from "node:path";
 import { z as z3 } from "zod/v4";
 
@@ -594,7 +712,7 @@ function readDiagnostic(kind, path, message, id) {
 async function readCanonicalFile(filePath, schema) {
   let raw;
   try {
-    raw = await readFile(filePath, "utf8");
+    raw = await readFile2(filePath, "utf8");
   } catch (error) {
     throw new KnowledgeStoreLoadError(
       `Failed to read canonical knowledge file: ${filePath}`,
@@ -918,7 +1036,7 @@ async function loadKnowledgeStoreFromEnv(envValue, cwd = process.cwd()) {
 
 // packages/core/src/knowledge/patch/storage.ts
 import { existsSync as existsSync2 } from "node:fs";
-import { mkdir, readFile as readFile2, readdir, writeFile } from "node:fs/promises";
+import { mkdir, readFile as readFile3, readdir, writeFile } from "node:fs/promises";
 import { isAbsolute, join as join3, normalize, resolve as resolve4, sep } from "node:path";
 import "zod/v4";
 
@@ -1118,7 +1236,7 @@ function buildDiagnostic(diagnostic) {
 
 // packages/core/src/knowledge/patch/storage.ts
 async function readJsonFile(filePath, schema) {
-  const raw = await readFile2(filePath, "utf8");
+  const raw = await readFile3(filePath, "utf8");
   const parsed = JSON.parse(raw);
   return schema.parse(parsed);
 }
@@ -2067,6 +2185,404 @@ var knowledgeGraphSchema = new GraphQLSchema({
   query: queryType
 });
 
+// packages/core/src/knowledge/schema-discovery.ts
+import {
+  isAbstractType,
+  isCompositeType,
+  isListType,
+  isNonNullType,
+  isObjectType,
+  isScalarType,
+  isUnionType
+} from "graphql";
+var KNOWLEDGE_SCHEMA_RESOURCE_URI = "ez-know://schema";
+var KNOWLEDGE_SCHEMA_LOOKUP_URI = "ez-know://lookup/{target}";
+function unwrapType(type) {
+  if (isNonNullType(type) || isListType(type)) {
+    return unwrapType(type.ofType);
+  }
+  if (isObjectType(type) || isScalarType(type) || isUnionType(type) || isAbstractType(type)) {
+    return { name: type.name, composite: type };
+  }
+  return { name: "Unknown", composite: type };
+}
+function describeType(type) {
+  if (isNonNullType(type)) {
+    return `${describeType(type.ofType)}!`;
+  }
+  if (isListType(type)) {
+    return `[${describeType(type.ofType)}]`;
+  }
+  if (isObjectType(type) || isScalarType(type) || isUnionType(type)) {
+    return type.name;
+  }
+  if (isAbstractType(type)) {
+    return type.name;
+  }
+  return "Unknown";
+}
+function formatDefaultValue(value) {
+  if (value === void 0 || value === null) {
+    return null;
+  }
+  return JSON.stringify(value) ?? String(value);
+}
+function summarizeField(field) {
+  const traversedType = unwrapType(field.type).composite;
+  const traversesTo = isCompositeType(traversedType) && !isScalarType(traversedType) ? traversedType.name : null;
+  return {
+    name: field.name,
+    type: describeType(field.type),
+    description: field.description ?? null,
+    arguments: field.args?.map((argument) => ({
+      name: argument.name,
+      type: describeType(argument.type),
+      description: argument.description ?? null,
+      defaultValue: formatDefaultValue(argument.defaultValue)
+    })) ?? [],
+    traversesTo
+  };
+}
+function summarizeObjectType(type) {
+  const fields = Object.values(type.getFields()).map(summarizeField);
+  return {
+    name: type.name,
+    description: type.description ?? null,
+    fields,
+    traversalFields: fields.filter((field) => field.traversesTo !== null).map((field) => field.name)
+  };
+}
+function getObjectTypes(schema) {
+  return Object.values(schema.getTypeMap()).filter((type) => isObjectType(type)).filter((type) => !type.name.startsWith("__")).filter((type) => type.name !== schema.getQueryType()?.name);
+}
+function buildKnowledgeSchemaDiscoveryDocument(schema) {
+  const queryType2 = schema.getQueryType();
+  if (!queryType2) {
+    throw new Error("Knowledge GraphQL schema has no root query type.");
+  }
+  return {
+    resource: {
+      uri: KNOWLEDGE_SCHEMA_RESOURCE_URI,
+      title: "Knowledge GraphQL Schema",
+      description: "Canonical discovery view of the runtime knowledge GraphQL schema."
+    },
+    source: {
+      kind: "runtime-schema",
+      queryType: queryType2.name
+    },
+    rootQuery: summarizeObjectType(queryType2),
+    objectTypes: getObjectTypes(schema).map(summarizeObjectType)
+  };
+}
+function getLookupMetadata(schema, target) {
+  const queryType2 = schema.getQueryType();
+  if (!queryType2) {
+    throw new Error("Knowledge GraphQL schema has no root query type.");
+  }
+  if (target === queryType2.name) {
+    return {
+      resource: {
+        uri: `ez-know://lookup/${target}`,
+        title: `Knowledge schema lookup: ${target}`,
+        description: "Focused lookup of the root query fields and their arguments."
+      },
+      source: {
+        kind: "runtime-schema",
+        queryType: queryType2.name
+      },
+      lookup: {
+        target: queryType2.name,
+        kind: "root-query"
+      },
+      rootQuery: summarizeObjectType(queryType2)
+    };
+  }
+  const rootField = queryType2.getFields()[target];
+  if (rootField) {
+    return {
+      resource: {
+        uri: `ez-know://lookup/${target}`,
+        title: `Knowledge schema lookup: ${target}`,
+        description: "Focused lookup of a single root query field and its arguments."
+      },
+      source: {
+        kind: "runtime-schema",
+        queryType: queryType2.name
+      },
+      lookup: {
+        target,
+        kind: "root-field"
+      },
+      field: summarizeField(rootField),
+      parentType: queryType2.name
+    };
+  }
+  const objectType = schema.getType(target);
+  if (objectType && isObjectType(objectType)) {
+    const typeSummary = summarizeObjectType(objectType);
+    const rootFields = Object.values(queryType2.getFields()).filter((field) => unwrapType(field.type).name === target).map((field) => field.name);
+    return {
+      resource: {
+        uri: `ez-know://lookup/${target}`,
+        title: `Knowledge schema lookup: ${target}`,
+        description: "Focused lookup of a single GraphQL type and its nested traversal fields."
+      },
+      source: {
+        kind: "runtime-schema",
+        queryType: queryType2.name
+      },
+      lookup: {
+        target,
+        kind: "object-type"
+      },
+      type: typeSummary,
+      rootFields
+    };
+  }
+  throw new Error(
+    `Unknown schema lookup target "${target}". Use a root field name, a type name, or "Query".`
+  );
+}
+function buildKnowledgeSchemaLookupDocument(schema, target) {
+  return getLookupMetadata(schema, target);
+}
+function listKnowledgeSchemaTargets(schema) {
+  const queryType2 = schema.getQueryType();
+  if (!queryType2) {
+    throw new Error("Knowledge GraphQL schema has no root query type.");
+  }
+  const objectTypeNames = getObjectTypes(schema).map((type) => type.name);
+  const rootFieldNames = Object.keys(queryType2.getFields());
+  const targetNames = ["Query", ...rootFieldNames, ...objectTypeNames];
+  return Array.from(new Set(targetNames)).sort(
+    (left, right) => left.localeCompare(right)
+  );
+}
+
+// packages/core/src/knowledge/resource-catalog.ts
+var KnowledgeResourceNotFoundError = class extends Error {
+  constructor(uri, message = `Unknown ez-know resource URI "${uri}".`) {
+    super(message);
+    this.uri = uri;
+    this.name = "KnowledgeResourceNotFoundError";
+  }
+  uri;
+  code = "RESOURCE_NOT_FOUND";
+};
+var KnowledgeResourceUriError = class extends Error {
+  constructor(uri, message) {
+    super(message);
+    this.uri = uri;
+    this.name = "KnowledgeResourceUriError";
+  }
+  uri;
+  code = "INVALID_RESOURCE_URI";
+};
+function createJsonResourceContent(uri, text) {
+  return {
+    uri,
+    mimeType: "application/json",
+    text
+  };
+}
+function createMarkdownResourceContent(uri, text) {
+  return {
+    uri,
+    mimeType: "text/markdown",
+    text
+  };
+}
+function createKnowledgeSchemaResourceDefinition() {
+  return {
+    uri: KNOWLEDGE_SCHEMA_RESOURCE_URI,
+    name: "knowledge-schema",
+    title: "Knowledge GraphQL Schema",
+    description: "Canonical runtime GraphQL schema discovery payload for the knowledge layer.",
+    mimeType: "application/json",
+    read: () => ({
+      resource: {
+        uri: KNOWLEDGE_SCHEMA_RESOURCE_URI,
+        title: "Knowledge GraphQL Schema",
+        description: "Canonical runtime GraphQL schema discovery payload for the knowledge layer.",
+        mimeType: "application/json"
+      },
+      content: createJsonResourceContent(
+        KNOWLEDGE_SCHEMA_RESOURCE_URI,
+        createKnowledgeSchemaDiscoveryText()
+      )
+    })
+  };
+}
+function createKnowledgeExtractionTypesResourceDefinition() {
+  return {
+    uri: KNOWLEDGE_EXTRACTION_TYPES_RESOURCE_URI,
+    name: "knowledge-extraction-types",
+    title: "Knowledge Extraction Types",
+    description: "Canonical registry of knowledge types supported by the extraction workflow.",
+    mimeType: "application/json",
+    read: () => ({
+      resource: {
+        uri: KNOWLEDGE_EXTRACTION_TYPES_RESOURCE_URI,
+        title: "Knowledge Extraction Types",
+        description: "Canonical registry of knowledge types supported by the extraction workflow.",
+        mimeType: "application/json"
+      },
+      content: createJsonResourceContent(
+        KNOWLEDGE_EXTRACTION_TYPES_RESOURCE_URI,
+        JSON.stringify(buildKnowledgeExtractionTypeIndexDocument(), null, 2)
+      )
+    })
+  };
+}
+function createKnowledgeSchemaLookupTemplateDefinition() {
+  return {
+    uriTemplate: KNOWLEDGE_SCHEMA_LOOKUP_URI,
+    name: "knowledge-schema-lookup",
+    title: "Knowledge Schema Lookup",
+    description: "Focused runtime GraphQL schema lookup for a type name, root field, or Query.",
+    mimeType: "application/json",
+    list: () => listKnowledgeSchemaTargets(knowledgeGraphSchema).map((target) => ({
+      uri: `ez-know://lookup/${target}`,
+      name: target,
+      title: `Knowledge schema lookup: ${target}`,
+      description: target === "Query" ? "Focused lookup of the root query fields." : `Focused lookup of ${target}.`,
+      mimeType: "application/json"
+    })),
+    read: (uri) => {
+      const target = readUriSegment(uri, "ez-know://lookup/");
+      try {
+        return {
+          resource: {
+            uri,
+            title: `Knowledge schema lookup: ${target}`,
+            description: target === "Query" ? "Focused lookup of the root query fields and their arguments." : `Focused lookup of ${target}.`,
+            mimeType: "application/json"
+          },
+          content: createJsonResourceContent(
+            uri,
+            createKnowledgeSchemaLookupText(target)
+          )
+        };
+      } catch (error) {
+        if (error instanceof Error) {
+          throw new KnowledgeResourceUriError(uri, error.message);
+        }
+        throw error;
+      }
+    }
+  };
+}
+function createKnowledgeExtractionSchemaTemplateDefinition() {
+  return {
+    uriTemplate: KNOWLEDGE_EXTRACTION_SCHEMA_RESOURCE_URI,
+    name: "knowledge-extraction-schema",
+    title: "Knowledge Extraction Schema",
+    description: "Runtime JSON-schema discovery for a supported knowledge type.",
+    mimeType: "application/json",
+    list: () => listKnowledgeExtractionResourceTypes().map((definition) => ({
+      uri: `ez-know://extraction/schema/${definition.collection}`,
+      name: definition.collection,
+      title: `${definition.title} Extraction Schema`,
+      description: `Runtime schema discovery for ${definition.title.toLowerCase()}.`,
+      mimeType: "application/json"
+    })),
+    read: (uri) => {
+      const type = readUriSegment(uri, "ez-know://extraction/schema/");
+      try {
+        const document = buildKnowledgeExtractionSchemaDocument(type);
+        return {
+          resource: {
+            uri: `ez-know://extraction/schema/${document.type.collection}`,
+            title: `${document.type.title} Extraction Schema`,
+            description: "Runtime JSON Schema view of the canonical knowledge object model.",
+            mimeType: "application/json"
+          },
+          content: createJsonResourceContent(
+            `ez-know://extraction/schema/${document.type.collection}`,
+            JSON.stringify(document, null, 2)
+          )
+        };
+      } catch (error) {
+        if (error instanceof Error) {
+          throw new KnowledgeResourceUriError(uri, error.message);
+        }
+        throw error;
+      }
+    }
+  };
+}
+function createKnowledgeExtractionGuideTemplateDefinition() {
+  return {
+    uriTemplate: KNOWLEDGE_EXTRACTION_GUIDE_RESOURCE_URI,
+    name: "knowledge-extraction-guide",
+    title: "Knowledge Extraction Guide",
+    description: "Checked-in Markdown guidance for a supported knowledge type.",
+    mimeType: "text/markdown",
+    list: () => listKnowledgeExtractionResourceTypes().map((definition) => ({
+      uri: `ez-know://extraction/guide/${definition.collection}`,
+      name: definition.collection,
+      title: `${definition.title} Extraction Guide`,
+      description: `Checked-in extraction guidance for ${definition.title.toLowerCase()}.`,
+      mimeType: "text/markdown"
+    })),
+    read: async (uri) => {
+      const type = readUriSegment(uri, "ez-know://extraction/guide/");
+      try {
+        const document = await buildKnowledgeExtractionGuideDocument(type);
+        return {
+          resource: {
+            uri: `ez-know://extraction/guide/${document.type.collection}`,
+            title: `${document.type.title} Extraction Guide`,
+            description: "Checked-in Markdown guidance for extracting this knowledge type.",
+            mimeType: "text/markdown"
+          },
+          content: createMarkdownResourceContent(
+            `ez-know://extraction/guide/${document.type.collection}`,
+            document.markdown
+          )
+        };
+      } catch (error) {
+        if (error instanceof Error) {
+          throw new KnowledgeResourceUriError(uri, error.message);
+        }
+        throw error;
+      }
+    }
+  };
+}
+function createKnowledgeSchemaDiscoveryText() {
+  return JSON.stringify(buildKnowledgeSchemaDiscoveryDocument(knowledgeGraphSchema), null, 2);
+}
+function createKnowledgeSchemaLookupText(target) {
+  return JSON.stringify(
+    buildKnowledgeSchemaLookupDocument(knowledgeGraphSchema, target),
+    null,
+    2
+  );
+}
+function readUriSegment(uri, prefix) {
+  if (!uri.startsWith(prefix)) {
+    throw new KnowledgeResourceNotFoundError(uri);
+  }
+  const segment = uri.slice(prefix.length);
+  if (segment.length === 0 || segment.includes("/")) {
+    throw new KnowledgeResourceUriError(
+      uri,
+      `Unsupported ez-know resource URI "${uri}".`
+    );
+  }
+  return segment;
+}
+var KNOWLEDGE_RESOURCE_DEFINITIONS = [
+  createKnowledgeSchemaResourceDefinition(),
+  createKnowledgeExtractionTypesResourceDefinition()
+];
+var KNOWLEDGE_RESOURCE_TEMPLATE_DEFINITIONS = [
+  createKnowledgeSchemaLookupTemplateDefinition(),
+  createKnowledgeExtractionSchemaTemplateDefinition(),
+  createKnowledgeExtractionGuideTemplateDefinition()
+];
+
 // packages/core/src/knowledge/patch/scope-audit.ts
 import { z as z6 } from "zod/v4";
 var compareScopeWithEvidenceInputSchema = z6.object({
@@ -2089,17 +2605,6 @@ var compareScopeWithEvidenceResultSchema = z6.object({
   message: z6.string()
 });
 
-// packages/core/src/knowledge/schema-discovery.ts
-import {
-  isAbstractType,
-  isCompositeType,
-  isListType,
-  isNonNullType,
-  isObjectType,
-  isScalarType,
-  isUnionType
-} from "graphql";
-
 // packages/rest/src/constants.ts
 var REST_SERVICE_NAME = "ez-know-rest";
 var REST_V1_PREFIX = "/api/v1";