graphddb 0.3.1 → 0.4.1

package/dist/{chunk-VST3WOK3.js → chunk-G5RWWBAL.js}

@@ -6,7 +6,6 @@ import {
   MetadataRegistry,
   NO_MIDDLEWARE,
   TableMapping,
-  ViewRegistry,
   attachHiddenKey,
   attachModelClass,
   buildConditionExpression,
@@ -43,7 +42,7 @@ import {
   serializeFieldValue,
   serializeRawCondition,
   skTemplate
-} from "./chunk-YIXXTGZ6.js";
+} from "./chunk-CPTV3H2U.js";
 
 // src/spec/types.ts
 var SPEC_VERSION = "1.0";
@@ -112,7 +111,12 @@ function buildFields(metadata) {
   const fields = {};
   for (const field of metadata.fields) {
     const format = field.options?.format;
-    fields[field.propertyName] = format ? { type: DYNAMO_TYPE_TO_FIELD_TYPE[field.dynamoType], format } : { type: DYNAMO_TYPE_TO_FIELD_TYPE[field.dynamoType] };
+    const description = field.options?.description;
+    fields[field.propertyName] = {
+      type: DYNAMO_TYPE_TO_FIELD_TYPE[field.dynamoType],
+      ...format ? { format } : {},
+      ...description !== void 0 ? { description } : {}
+    };
   }
   return sortedRecord(fields);
 }
@@ -124,7 +128,8 @@ function buildEntity(metadata) {
     fields: buildFields(metadata),
     key: buildKey(metadata.primaryKey),
     gsis: buildGsis(metadata),
-    relations: buildRelations(metadata)
+    relations: buildRelations(metadata),
+    ...metadata.description !== void 0 ? { description: metadata.description } : {}
   };
 }
 function buildManifest(registry = MetadataRegistry) {
@@ -3573,7 +3578,8 @@ function buildQueryContract(methods) {
       op,
       resolution,
       inputArity,
-      __methodName: name
+      __methodName: name,
+      ...op.description !== void 0 ? { description: op.description } : {}
     };
   }
   const contract = { __isContract: true, kind: "query", methods: resolved };
@@ -3587,8 +3593,8 @@ function buildCommandContract(methods) {
   const resolved = {};
   for (const [name, body] of Object.entries(methods)) {
     if (isPublicWriteDescriptor(body)) {
-      const { plan: plan2, select, condition, mode } = writeDescriptorToPlan(name, body);
-      resolved[name] = finalizeDescriptorCommand(name, plan2, select, condition, mode);
+      const { plan: plan2, select, condition, mode, description } = writeDescriptorToPlan(name, body);
+      resolved[name] = finalizeDescriptorCommand(name, plan2, select, condition, mode, description);
       continue;
     }
     if (isPublicComposeDescriptor(body)) {
@@ -3598,7 +3604,8 @@ function buildCommandContract(methods) {
         body.command,
         select,
         void 0,
-        body.mode ?? "transaction"
+        body.mode ?? "transaction",
+        body.description
       );
       continue;
     }
@@ -3663,7 +3670,7 @@ function buildPlannedCommandMethod(name, planned) {
     ...returnSelection !== void 0 ? { returnSelection } : {}
   };
 }
-function finalizeDescriptorCommand(name, plan2, select, condition, mode) {
+function finalizeDescriptorCommand(name, plan2, select, condition, mode, description) {
   const planned = {
     [PLANNED_COMMAND_BRAND]: true,
     plan: plan2,
@@ -3675,7 +3682,8 @@ function finalizeDescriptorCommand(name, plan2, select, condition, mode) {
   return {
     ...built,
     op,
-    mode
+    mode,
+    ...description !== void 0 ? { description } : {}
   };
 }
 function normalizeReturnSelection(select) {
@@ -3761,7 +3769,8 @@ function readDescriptorToOp(name, d) {
     keys,
     ...isQuery ? { keyFields: keyFieldNames2 } : {},
     ...select !== void 0 ? { select } : {},
-    ...compose.length > 0 ? { compose } : {}
+    ...compose.length > 0 ? { compose } : {},
+    ...d.description !== void 0 ? { description: d.description } : {}
   };
 }
 function writeDescriptorToPlan(name, d) {
@@ -3795,7 +3804,7 @@ function writeDescriptorToPlan(name, d) {
   });
   const select = d.result !== void 0 && d.result.select !== void 0 ? d.result.select : void 0;
   const condition = d.condition !== void 0 ? descriptorConditionRecord(d.condition, name) : void 0;
-  return { plan: plan2, select, condition, mode: d.mode ?? "transaction" };
+  return { plan: plan2, select, condition, mode: d.mode ?? "transaction", description: d.description };
 }
 
 // src/spec/mutation-command.ts
@@ -3952,9 +3961,8 @@ var MAINTAIN_ENTITY_PATH_RE = /^\$\.entity\.([A-Za-z_$][\w$]*)$/;
 var cachedMaintenanceGraph;
 function globalMaintenanceGraph() {
   const generation = MetadataRegistry.generation;
-  const viewGeneration = ViewRegistry.generation;
-  if (cachedMaintenanceGraph?.generation !== generation || cachedMaintenanceGraph?.viewGeneration !== viewGeneration) {
-    cachedMaintenanceGraph = { graph: buildMaintenanceGraph(), generation, viewGeneration };
+  if (cachedMaintenanceGraph?.generation !== generation) {
+    cachedMaintenanceGraph = { graph: buildMaintenanceGraph(), generation };
   }
   return cachedMaintenanceGraph.graph;
 }
@@ -5699,10 +5707,12 @@ function paramSpecs(params) {
   const out = {};
   for (const name of Object.keys(params).sort()) {
     const d = params[name];
-    out[name] = d.literals === void 0 ? { type: d.kind, required: d.required } : {
+    out[name] = {
       type: d.kind,
       required: d.required,
-      literals: d.literals
+      ...d.literals !== void 0 ? { literals: d.literals } : {},
+      // Pure-documentation description (issue #154); absent → byte-identical spec.
+      ...d.description !== void 0 ? { description: d.description } : {}
     };
   }
   return out;
@@ -5931,6 +5941,7 @@ function buildCommandSpec(def) {
   const params = paramSpecs(def.params);
   const entity = def.entity.name;
   const condition = extractCondition(def);
+  const description = def.description !== void 0 ? { description: def.description } : {};
   if (def.operation === "put") {
     const item = templateRecord3(def.key);
     return {
@@ -5939,7 +5950,8 @@ function buildCommandSpec(def) {
       entity,
       params,
       item,
-      ...condition ? { condition } : {}
+      ...condition ? { condition } : {},
+      ...description
     };
   }
   if (def.operation === "delete") {
@@ -5949,7 +5961,8 @@ function buildCommandSpec(def) {
       entity,
       params,
       keyCondition: writeKeyCondition(metadata, def.key, entity),
-      ...condition ? { condition } : {}
+      ...condition ? { condition } : {},
+      ...description
     };
   }
   return {
@@ -5959,7 +5972,8 @@ function buildCommandSpec(def) {
     params,
     keyCondition: writeKeyCondition(metadata, def.key, entity),
     changes: templateRecord3(def.changes),
-    ...condition ? { condition } : {}
+    ...condition ? { condition } : {},
+    ...description
   };
 }
 function writeKeyCondition(metadata, key, entity) {
@@ -6026,7 +6040,9 @@ function buildQuerySpec(def) {
     operations,
     // `defineQuery` → a single entity object; `defineList` → a connection.
     cardinality: def.operation === "query" ? "one" : "many",
-    ...executionPlan !== void 0 ? { executionPlan } : {}
+    ...executionPlan !== void 0 ? { executionPlan } : {},
+    // Pure-documentation description (issue #154); absent → byte-identical spec.
+    ...def.description !== void 0 ? { description: def.description } : {}
   };
 }
 function mergeSpecs(base, synthesized, kind) {
@@ -6790,7 +6806,9 @@ function serializeQueryContract(contractName, contract, querySpecs, contracts) {
       cardinality: method.resolution === "point" ? "one" : "many",
       operation: opName,
       ...compose.length > 0 ? { compose } : {},
-      ...compositionPlan !== void 0 ? { compositionPlan } : {}
+      ...compositionPlan !== void 0 ? { compositionPlan } : {},
+      // Pure-documentation description (issue #154); absent → byte-identical spec.
+      ...method.description !== void 0 ? { description: method.description } : {}
     };
   }
   return {
@@ -6878,7 +6896,9 @@ function serializeCommandContract(contractName, contract, commandSpecs, transact
       result: method.result,
       single,
       ...batch !== void 0 ? { batch } : {},
-      ...returnSelection !== void 0 && Object.keys(returnSelection).length > 0 ? { returnSelection: sortedReturnSelection(returnSelection) } : {}
+      ...returnSelection !== void 0 && Object.keys(returnSelection).length > 0 ? { returnSelection: sortedReturnSelection(returnSelection) } : {},
+      // Pure-documentation description (issue #154); absent → byte-identical spec.
+      ...method.description !== void 0 ? { description: method.description } : {}
     };
   }
   return {

package/dist/cli.js

@@ -2,10 +2,10 @@
 import {
   buildBridgeBundle,
   normalizeSelectSpec
-} from "./chunk-VST3WOK3.js";
+} from "./chunk-G5RWWBAL.js";
 import {
   MetadataRegistry
-} from "./chunk-YIXXTGZ6.js";
+} from "./chunk-CPTV3H2U.js";
 
 // src/cli.ts
 import { createRequire } from "module";
@@ -467,9 +467,16 @@ function pyTransactionParamType(txName, paramName, spec) {
   }
   return pyParamType(spec);
 }
+function pyDocLine(text) {
+  return text.replace(/\\/g, "\\\\").replace(/"""/g, '\\"\\"\\"').replace(/\r?\n/g, " ").trim();
+}
+function pyCommentLine(text) {
+  return text.replace(/\r?\n/g, " ").trim();
+}
 function collectResultTypes(manifest, entity, select, typeName, out, seen) {
   const meta = manifest.entities[entity];
   const fields = [];
+  const fieldDescriptions = {};
   for (const field of Object.keys(select).sort()) {
     const value = select[field];
     const relation = meta?.relations[field];
@@ -504,13 +511,23 @@ function collectResultTypes(manifest, entity, select, typeName, out, seen) {
       continue;
     }
     if (value === true) {
-      const fieldType = meta?.fields[field]?.type ?? "string";
+      const manifestField = meta?.fields[field];
+      const fieldType = manifestField?.type ?? "string";
       fields.push([field, pyScalarType(fieldType)]);
+      if (manifestField?.description !== void 0) {
+        fieldDescriptions[field] = manifestField.description;
+      }
     }
   }
   if (!seen.has(typeName)) {
     seen.add(typeName);
-    out.push({ name: typeName, fields });
+    out.push({
+      name: typeName,
+      fields,
+      ...Object.keys(fieldDescriptions).length > 0 ? { fieldDescriptions } : {},
+      // The entity's own description (issue #154) becomes the result class docstring.
+      ...meta?.description !== void 0 ? { docstring: meta.description } : {}
+    });
   }
 }
 function selectOf(def) {
@@ -519,29 +536,44 @@ function selectOf(def) {
 function queryResultTypeName(queryName) {
   return `${toPascalCase(queryName)}Result`;
 }
+function classDocstringLines(cls) {
+  return cls.docstring !== void 0 ? [`    """${pyDocLine(cls.docstring)}"""`] : [];
+}
+function withFieldComment(cls, name, line) {
+  const desc = cls.fieldDescriptions?.[name];
+  return desc !== void 0 ? `${line}  # ${pyCommentLine(desc)}` : line;
+}
 function renderTypedDict(cls) {
+  const doc = classDocstringLines(cls);
   if (cls.fields.length === 0) {
-    return `class ${cls.name}(TypedDict):
+    return doc.length > 0 ? `class ${cls.name}(TypedDict):
+${doc.join("\n")}` : `class ${cls.name}(TypedDict):
     pass`;
   }
-  const lines = cls.fields.map(([name, type]) => `    ${name}: ${type}`);
+  const lines = cls.fields.map(
+    ([name, type]) => withFieldComment(cls, name, `    ${name}: ${type}`)
+  );
   return `class ${cls.name}(TypedDict):
-${lines.join("\n")}`;
+${[...doc, ...lines].join("\n")}`;
 }
 function renderDataclass(cls) {
+  const doc = classDocstringLines(cls);
   if (cls.fields.length === 0) {
-    return `@dataclass
+    return doc.length > 0 ? `@dataclass
+class ${cls.name}:
+${doc.join("\n")}` : `@dataclass
 class ${cls.name}:
     pass`;
   }
   const lines = cls.fields.map(
-    ([name, type]) => type.endsWith("| None") ? `    ${name}: ${type} = None` : `    ${name}: ${type}`
+    ([name, type]) => type.endsWith("| None") ? withFieldComment(cls, name, `    ${name}: ${type} = None`) : withFieldComment(cls, name, `    ${name}: ${type}`)
   );
-  const required = lines.filter((l) => !l.endsWith("= None"));
-  const optional = lines.filter((l) => l.endsWith("= None"));
+  const isOptional = (l) => /:\s.*\| None\s*=\sNone(\s+#.*)?$/.test(l);
+  const required = lines.filter((l) => !isOptional(l));
+  const optional = lines.filter(isOptional);
   return `@dataclass
 class ${cls.name}:
-${[...required, ...optional].join("\n")}`;
+${[...doc, ...required, ...optional].join("\n")}`;
 }
 function collectTransactionElementTypes(transactions, out, seen) {
   for (const txName of Object.keys(transactions).sort()) {
@@ -625,7 +657,8 @@ function collectRepositories(queries, commands) {
       params: methodParams(def),
       returnType: `${queryResultTypeName(name)} | None`,
       kind: "query",
-      operationId: name
+      operationId: name,
+      ...def.description !== void 0 ? { description: def.description } : {}
     });
   }
   for (const name of Object.keys(commands).sort()) {
@@ -635,7 +668,8 @@ function collectRepositories(queries, commands) {
       params: methodParams(def),
       returnType: "None",
       kind: "command",
-      operationId: name
+      operationId: name,
+      ...def.description !== void 0 ? { description: def.description } : {}
     });
   }
   return [...byEntity.keys()].sort().map((className) => ({
@@ -646,11 +680,13 @@ function collectRepositories(queries, commands) {
 function renderMethod(m) {
   const sig = m.params.map((p) => `${p.argName}: ${p.pyType}`).join(", ");
   const head = `    def ${m.methodName}(self${sig ? ", " + sig : ""}) -> ${m.returnType}:`;
+  const doc = m.description !== void 0 ? [`        """${pyDocLine(m.description)}"""`] : [];
   const paramsDict = m.params.map((p) => `"${p.originalName}": ${p.argName}`).join(", ");
   const paramsArg = paramsDict ? `{${paramsDict}}` : "{}";
   if (m.kind === "query") {
     return [
       head,
+      ...doc,
       `        return self._runtime.execute_query(`,
       `            query_id="${m.operationId}",`,
       `            params=${paramsArg},`,
@@ -659,6 +695,7 @@ function renderMethod(m) {
   }
   return [
     head,
+    ...doc,
     `        self._runtime.execute_command(`,
     `            command_id="${m.operationId}",`,
     `            params=${paramsArg},`,