@wictorwilen/cocogen 1.0.17 → 1.0.19

package/CHANGELOG.md

@@ -7,14 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [1.0.17] - 2026-01-20
+## [1.0.19] - 2026-01-21
+
+### Fixed
+- Clarified error messaging for unsupported scalar types (with float64 hint).
+
+### Changed
+- Moved item payload ID encoding helpers into shared core helpers for TS and .NET.
+
+## [1.0.18] - 2026-01-21
 
 ### Breaking Changes
+- Removed legacy CSV-row helpers (`fromCsvRow`, `CsvParser`, `csv.ts`) in favor of row-based helpers.
 - Renamed CLI commands: `init-tsp` → `init`, `init` → `generate`.
 
 ### Added
+- Added agent-facing schema guidance document (docs/schema-assistant.md).
 - Managed identity authentication as the preferred credential for generated TS and .NET projects (client secret fallback).
 - .NET user-secrets support for configuration.
+- TypeSpec metadata support for `@doc`, `@example`, `@minLength`, `@maxLength`, `@minValue`, `@maxValue`, `@pattern`, `@format`, and `#deprecated`.
 
 ## [1.0.16] - 2026-01-20
 
@@ -37,5 +48,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Collection values no longer split on commas; use semicolons instead.
 
 [Unreleased]: https://github.com/wictorwilen/cocogen/compare/v1.0.16...HEAD
+[1.0.19]: https://github.com/wictorwilen/cocogen/compare/main...v1.0.19
+[1.0.18]: https://github.com/wictorwilen/cocogen/compare/main...v1.0.18
 [1.0.17]: https://github.com/wictorwilen/cocogen/compare/main...v1.0.17
 [1.0.16]: https://github.com/wictorwilen/cocogen/compare/main...v1.0.16

package/README.md

@@ -32,6 +32,9 @@
 End-user guide:
 - [docs/end-user.md](https://github.com/wictorwilen/cocogen/blob/main/docs/end-user.md)
 
+Agent schema guidance:
+- [docs/schema-assistant.md](https://github.com/wictorwilen/cocogen/blob/main/docs/schema-assistant.md)
+
 ## TypeSpec format
 `cocogen` expects a single “item model” decorated with `@coco.item()` and a single ID property decorated with `@coco.id`.
 

package/dist/init/init.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/init/init.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,WAAW,EAAgB,MAAM,UAAU,CAAC;AAK1D,MAAM,MAAM,WAAW,GAAG;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B,CAAC;AAkhCF,wBAAsB,eAAe,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,WAAW,CAAA;CAAE,CAAC,CAyB1G;AAED,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,WAAW,CAAA;CAAE,CAAC,CA2B9C;AAED,wBAAsB,aAAa,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,WAAW,CAAA;CAAE,CAAC,CAOxG;AAED,wBAAsB,aAAa,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,WAAW,CAAA;CAAE,CAAC,CAsHtG;AAED,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,WAAW,CAAA;CAAE,CAAC,CAoH9C"}
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/init/init.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,WAAW,EAAgB,MAAM,UAAU,CAAC;AAK1D,MAAM,MAAM,WAAW,GAAG;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B,CAAC;AAk1CF,wBAAsB,eAAe,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,WAAW,CAAA;CAAE,CAAC,CAyB1G;AAED,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,WAAW,CAAA;CAAE,CAAC,CA2B9C;AAED,wBAAsB,aAAa,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,WAAW,CAAA;CAAE,CAAC,CAOxG;AAED,wBAAsB,aAAa,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,WAAW,CAAA;CAAE,CAAC,CAsHtG;AAED,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,WAAW,CAAA;CAAE,CAAC,CAoH9C"}

package/dist/init/init.js

@@ -1,5 +1,5 @@
 import { readFileSync } from "node:fs";
-import { access, copyFile, mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { access, copyFile, mkdir, readdir, readFile, unlink, writeFile } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -7,6 +7,16 @@ import { loadIrFromTypeSpec } from "../tsp/loader.js";
 import { validateIr } from "../validate/validator.js";
 import { renderTemplate } from "./template.js";
 const COCOGEN_CONFIG_FILE = "cocogen.json";
+async function removeIfExists(filePath) {
+    try {
+        await unlink(filePath);
+    }
+    catch (error) {
+        const err = error;
+        if (err.code !== "ENOENT")
+            throw error;
+    }
+}
 function toTsType(type) {
     switch (type) {
         case "string":
@@ -202,11 +212,15 @@ async function loadProjectConfig(outDir) {
     };
 }
 async function writeGeneratedTs(outDir, ir, schemaFolderName) {
+    await mkdir(path.join(outDir, "src", "datasource"), { recursive: true });
     await mkdir(path.join(outDir, "src", schemaFolderName), { recursive: true });
     await mkdir(path.join(outDir, "src", "core"), { recursive: true });
+    await removeIfExists(path.join(outDir, "src", schemaFolderName, "fromCsvRow.ts"));
+    await removeIfExists(path.join(outDir, "src", "datasource", "csv.ts"));
     const modelProperties = ir.properties.map((p) => ({
         name: p.name,
         tsType: toTsType(p.type),
+        docComment: p.doc ? formatDocComment(p.doc, "  ") : undefined,
     }));
     const transformProperties = ir.properties.map((p) => {
         const parser = (() => {
@@ -230,16 +244,28 @@ async function writeGeneratedTs(outDir, ir, schemaFolderName) {
                     return "parseString";
             }
         })();
+        const nameLiteral = JSON.stringify(p.name);
+        const stringConstraints = buildTsStringConstraintsLiteral(p);
         const personEntity = p.personEntity
             ? (p.type === "stringCollection"
                 ? buildTsPersonEntityCollectionExpression(p.personEntity.fields.map((field) => ({
                     path: field.path,
                     source: field.source,
-                })))
+                })), (headersLiteral) => {
+                    const base = `parseStringCollection(readSourceValue(row, ${headersLiteral}))`;
+                    return stringConstraints
+                        ? `validateStringCollection(${nameLiteral}, ${base}, ${stringConstraints})`
+                        : base;
+                })
                 : buildTsPersonEntityExpression(p.personEntity.fields.map((field) => ({
                     path: field.path,
                     source: field.source,
-                }))))
+                })), (headersLiteral) => {
+                    const base = `parseString(readSourceValue(row, ${headersLiteral}))`;
+                    return stringConstraints
+                        ? `validateString(${nameLiteral}, ${base}, ${stringConstraints})`
+                        : base;
+                }))
             : null;
         const isPeopleLabel = p.labels.some((label) => label.startsWith("person"));
         const needsManualEntity = isPeopleLabel && !p.personEntity;
@@ -251,10 +277,23 @@ async function writeGeneratedTs(outDir, ir, schemaFolderName) {
                 : noSource
                     ? `undefined as unknown as ${toTsType(p.type)}`
                     : `${parser}(readSourceValue(row, ${JSON.stringify(p.source.csvHeaders)}))`;
+        const validationMetadata = {
+            name: p.name,
+            type: p.type,
+            ...(p.minLength !== undefined ? { minLength: p.minLength } : {}),
+            ...(p.maxLength !== undefined ? { maxLength: p.maxLength } : {}),
+            ...(p.pattern ? { pattern: p.pattern } : {}),
+            ...(p.format ? { format: p.format } : {}),
+            ...(p.minValue !== undefined ? { minValue: p.minValue } : {}),
+            ...(p.maxValue !== undefined ? { maxValue: p.maxValue } : {}),
+        };
+        const validatedExpression = needsManualEntity || noSource || personEntity
+            ? expression
+            : applyTsValidationExpression(validationMetadata, expression);
         return {
             name: p.name,
             parser,
-            expression,
+            expression: validatedExpression,
             isCollection: p.type === "stringCollection",
             transformName: toTsIdentifier(p.name),
             tsType: toTsType(p.type),
@@ -268,7 +307,9 @@ async function writeGeneratedTs(outDir, ir, schemaFolderName) {
     await writeFile(path.join(outDir, "src", schemaFolderName, "model.ts"), await renderTemplate("ts/src/generated/model.ts.ejs", {
         itemTypeName: ir.item.typeName,
         properties: modelProperties,
+        itemDocComment: ir.item.doc ? formatDocComment(ir.item.doc) : undefined,
     }), "utf8");
+    await writeFile(path.join(outDir, "src", "datasource", "row.ts"), await renderTemplate("ts/src/generated/row.ts.ejs", {}), "utf8");
     await writeFile(path.join(outDir, "src", schemaFolderName, "constants.ts"), await renderTemplate("ts/src/generated/constants.ts.ejs", {
         graphApiVersion: ir.connection.graphApiVersion,
         contentCategory: ir.connection.contentCategory ?? null,
@@ -285,7 +326,6 @@ async function writeGeneratedTs(outDir, ir, schemaFolderName) {
     await writeFile(path.join(outDir, "src", schemaFolderName, "schemaPayload.ts"), await renderTemplate("ts/src/generated/schemaPayload.ts.ejs", {
         schemaPayloadJson: JSON.stringify(schemaPayload(ir), null, 2),
     }), "utf8");
-    await writeFile(path.join(outDir, "src", "datasource", "csv.ts"), await renderTemplate("ts/src/generated/csv.ts.ejs", {}), "utf8");
     await writeFile(path.join(outDir, "src", schemaFolderName, "propertyTransformBase.ts"), await renderTemplate("ts/src/generated/propertyTransformBase.ts.ejs", {
         properties: transformProperties,
     }), "utf8");
@@ -296,7 +336,7 @@ async function writeGeneratedTs(outDir, ir, schemaFolderName) {
     catch {
         await writeFile(transformOverridesPath, await renderTemplate("ts/src/propertyTransform.ts.ejs", {}), "utf8");
     }
-    await writeFile(path.join(outDir, "src", schemaFolderName, "fromCsvRow.ts"), await renderTemplate("ts/src/generated/fromCsvRow.ts.ejs", {
+    await writeFile(path.join(outDir, "src", schemaFolderName, "fromRow.ts"), await renderTemplate("ts/src/generated/fromRow.ts.ejs", {
         properties: transformProperties,
         itemTypeName: ir.item.typeName,
         idRawExpression,
@@ -328,6 +368,8 @@ async function writeGeneratedTs(outDir, ir, schemaFolderName) {
         itemTypeName: ir.item.typeName,
         isPeopleConnector: ir.connection.contentCategory === "people",
     }), "utf8");
+    await writeFile(path.join(outDir, "src", "core", "validation.ts"), await renderTemplate("ts/src/core/validation.ts.ejs", {}), "utf8");
+    await writeFile(path.join(outDir, "src", "core", "itemId.ts"), await renderTemplate("ts/src/core/itemId.ts.ejs", {}), "utf8");
 }
 function toGraphPropertyTypeEnumName(type) {
     switch (type) {
@@ -372,25 +414,25 @@ function toOdataCollectionType(type) {
 function toCsParseFunction(type) {
     switch (type) {
         case "stringCollection":
-            return "CsvParser.ParseStringCollection";
+            return "RowParser.ParseStringCollection";
         case "int64Collection":
-            return "CsvParser.ParseInt64Collection";
+            return "RowParser.ParseInt64Collection";
         case "doubleCollection":
-            return "CsvParser.ParseDoubleCollection";
+            return "RowParser.ParseDoubleCollection";
         case "dateTimeCollection":
-            return "CsvParser.ParseDateTimeCollection";
+            return "RowParser.ParseDateTimeCollection";
         case "boolean":
-            return "CsvParser.ParseBoolean";
+            return "RowParser.ParseBoolean";
         case "int64":
-            return "CsvParser.ParseInt64";
+            return "RowParser.ParseInt64";
         case "double":
-            return "CsvParser.ParseDouble";
+            return "RowParser.ParseDouble";
         case "dateTime":
-            return "CsvParser.ParseDateTime";
+            return "RowParser.ParseDateTime";
         case "principal":
         case "string":
         default:
-            return "CsvParser.ParseString";
+            return "RowParser.ParseString";
     }
 }
 function toCsPropertyValueExpression(type, csPropertyName) {
@@ -403,6 +445,14 @@ function toCsPropertyValueExpression(type, csPropertyName) {
             return `item.${csPropertyName}`;
     }
 }
+function formatDocComment(doc, indent = "") {
+    const lines = doc.split(/\r?\n/).map((line) => `${indent} * ${line}`);
+    return `${indent}/**\n${lines.join("\n")}\n${indent} */`;
+}
+function formatCsDocSummary(doc) {
+    const lines = doc.split(/\r?\n/).map((line) => `/// ${line}`);
+    return ["/// <summary>", ...lines, "/// </summary>"];
+}
 function buildObjectTree(fields) {
     const root = {};
     for (const field of fields) {
@@ -429,7 +479,7 @@ function buildObjectTree(fields) {
     }
     return root;
 }
-function buildTsPersonEntityExpression(fields) {
+function buildTsPersonEntityExpression(fields, valueExpressionBuilder = (headersLiteral) => `parseString(readSourceValue(row, ${headersLiteral}))`) {
     const tree = buildObjectTree(fields);
     const indentUnit = "  ";
     const renderNode = (node, level) => {
@@ -439,7 +489,7 @@ function buildTsPersonEntityExpression(fields) {
             if (typeof value === "object" && value && "path" in value) {
                 const field = value;
                 const headers = JSON.stringify(field.source.csvHeaders);
-                return `${childIndent}${JSON.stringify(key)}: parseString(readSourceValue(row, ${headers}))`;
+                return `${childIndent}${JSON.stringify(key)}: ${valueExpressionBuilder(headers)}`;
             }
             return `${childIndent}${JSON.stringify(key)}: ${renderNode(value, level + 1)}`;
         });
@@ -450,7 +500,7 @@ ${indent}}`;
     const rendered = renderNode(tree, 2);
     return `JSON.stringify(\n${indentUnit.repeat(2)}${rendered}\n${indentUnit.repeat(2)})`;
 }
-function buildTsPersonEntityCollectionExpression(fields) {
+function buildTsPersonEntityCollectionExpression(fields, collectionExpressionBuilder = (headersLiteral) => `parseStringCollection(readSourceValue(row, ${headersLiteral}))`) {
     const indentUnit = "  ";
     const renderNode = (node, level, valueVar) => {
         const indent = indentUnit.repeat(level);
@@ -470,7 +520,7 @@ ${indent}}`;
         const field = fields[0];
         const headers = JSON.stringify(field.source.csvHeaders);
         const rendered = renderNode(tree, 2, "value");
-        return `parseStringCollection(readSourceValue(row, ${headers}))
+        return `${collectionExpressionBuilder(headers)}
   .map((value) => JSON.stringify(\n${indentUnit.repeat(2)}${rendered}\n${indentUnit.repeat(2)}))`;
     }
     const tree = buildObjectTree(fields);
@@ -479,7 +529,7 @@ ${indent}}`;
         const varName = `field${index}`;
         fieldVarByPath.set(field.path, varName);
         const headers = JSON.stringify(field.source.csvHeaders);
-        return `  const ${varName} = parseStringCollection(readSourceValue(row, ${headers}));`;
+        return `  const ${varName} = ${collectionExpressionBuilder(headers)};`;
     });
     const renderNodeMany = (node) => {
         const entries = Object.entries(node).map(([key, value]) => {
@@ -500,7 +550,7 @@ ${indentUnit}}`;
         : "const lengths = [0];";
     return `(() => {\n${fieldLines.join("\n")}\n${lengthVars}\n  const maxLen = Math.max(0, ...lengths);\n  const getValue = (values: string[], index: number): string => {\n    if (values.length === 0) return \"\";\n    if (values.length === 1) return values[0] ?? \"\";\n    return values[index] ?? \"\";\n  };\n  const results: string[] = [];\n  for (let index = 0; index < maxLen; index++) {\n    results.push(JSON.stringify(\n      ${renderNodeMany(tree)}\n    ));\n  }\n  return results;\n})()`;
 }
-function buildCsPersonEntityExpression(fields) {
+function buildCsPersonEntityExpression(fields, valueExpressionBuilder = (headersLiteral) => `RowParser.ParseString(row, ${headersLiteral})`) {
     const tree = buildObjectTree(fields);
     const indentUnit = "    ";
     const renderNode = (node, level) => {
@@ -510,7 +560,7 @@ function buildCsPersonEntityExpression(fields) {
             if (typeof value === "object" && value && "path" in value) {
                 const field = value;
                 const headers = `new[] { ${field.source.csvHeaders.map((h) => JSON.stringify(h)).join(", ")} }`;
-                return `${childIndent}[${JSON.stringify(key)}] = CsvParser.ParseString(row, ${headers})`;
+                return `${childIndent}[${JSON.stringify(key)}] = ${valueExpressionBuilder(headers)}`;
             }
             return `${childIndent}[${JSON.stringify(key)}] = ${renderNode(value, level + 1)}`;
         });
@@ -519,7 +569,7 @@ function buildCsPersonEntityExpression(fields) {
     const rendered = renderNode(tree, 2);
     return `JsonSerializer.Serialize(\n${indentUnit.repeat(2)}${rendered}\n${indentUnit.repeat(2)})`;
 }
-function buildCsPersonEntityCollectionExpression(fields) {
+function buildCsPersonEntityCollectionExpression(fields, collectionExpressionBuilder = (headersLiteral) => `RowParser.ParseStringCollection(row, ${headersLiteral})`) {
     const indentUnit = "    ";
     const renderNode = (node, level, valueVar) => {
         const indent = indentUnit.repeat(level);
@@ -537,7 +587,7 @@ function buildCsPersonEntityCollectionExpression(fields) {
         const field = fields[0];
         const headers = `new[] { ${field.source.csvHeaders.map((h) => JSON.stringify(h)).join(", ")} }`;
         const rendered = renderNode(tree, 3, "value");
-        return `CsvParser.ParseStringCollection(row, ${headers})
+        return `${collectionExpressionBuilder(headers)}
             .Select(value => JsonSerializer.Serialize(\n${indentUnit.repeat(3)}${rendered}\n${indentUnit.repeat(3)}))
             .ToList()`;
     }
@@ -547,7 +597,7 @@ function buildCsPersonEntityCollectionExpression(fields) {
         const varName = `field${index}`;
         fieldVarByPath.set(field.path, varName);
         const headers = `new[] { ${field.source.csvHeaders.map((h) => JSON.stringify(h)).join(", ")} }`;
-        return `        var ${varName} = CsvParser.ParseStringCollection(row, ${headers});`;
+        return `        var ${varName} = ${collectionExpressionBuilder(headers)};`;
     });
     const renderNodeMany = (node) => {
         const entries = Object.entries(node).map(([key, value]) => {
@@ -597,6 +647,125 @@ function sampleValueForType(type) {
             return "sample";
     }
 }
+function buildTsStringConstraintsLiteral(prop) {
+    const parts = [];
+    if (prop.minLength !== undefined)
+        parts.push(`minLength: ${prop.minLength}`);
+    if (prop.maxLength !== undefined)
+        parts.push(`maxLength: ${prop.maxLength}`);
+    if (prop.pattern?.regex)
+        parts.push(`pattern: ${JSON.stringify(prop.pattern.regex)}`);
+    if (prop.format)
+        parts.push(`format: ${JSON.stringify(prop.format)}`);
+    return parts.length > 0 ? `{ ${parts.join(", ")} }` : undefined;
+}
+function buildTsNumberConstraintsLiteral(prop) {
+    const parts = [];
+    if (prop.minValue !== undefined)
+        parts.push(`minValue: ${prop.minValue}`);
+    if (prop.maxValue !== undefined)
+        parts.push(`maxValue: ${prop.maxValue}`);
+    return parts.length > 0 ? `{ ${parts.join(", ")} }` : undefined;
+}
+function applyTsValidationExpression(prop, expression) {
+    const stringConstraints = buildTsStringConstraintsLiteral(prop);
+    const numberConstraints = buildTsNumberConstraintsLiteral(prop);
+    const nameLiteral = JSON.stringify(prop.name);
+    switch (prop.type) {
+        case "string":
+        case "principal":
+        case "dateTime":
+            return stringConstraints ? `validateString(${nameLiteral}, ${expression}, ${stringConstraints})` : expression;
+        case "stringCollection":
+        case "dateTimeCollection":
+            return stringConstraints
+                ? `validateStringCollection(${nameLiteral}, ${expression}, ${stringConstraints})`
+                : expression;
+        case "int64":
+        case "double":
+            return numberConstraints ? `validateNumber(${nameLiteral}, ${expression}, ${numberConstraints})` : expression;
+        case "int64Collection":
+        case "doubleCollection":
+            return numberConstraints
+                ? `validateNumberCollection(${nameLiteral}, ${expression}, ${numberConstraints})`
+                : expression;
+        default:
+            return expression;
+    }
+}
+function buildCsStringConstraintsLiteral(prop) {
+    const minLength = prop.minLength !== undefined ? prop.minLength.toString() : "null";
+    const maxLength = prop.maxLength !== undefined ? prop.maxLength.toString() : "null";
+    const pattern = prop.pattern?.regex ? JSON.stringify(prop.pattern.regex) : "null";
+    const format = prop.format ? JSON.stringify(prop.format) : "null";
+    const hasAny = prop.minLength !== undefined || prop.maxLength !== undefined || Boolean(prop.pattern?.regex) || Boolean(prop.format);
+    return { minLength, maxLength, pattern, format, hasAny };
+}
+function buildCsNumberConstraintsLiteral(prop) {
+    const minValue = prop.minValue !== undefined ? prop.minValue.toString() : "null";
+    const maxValue = prop.maxValue !== undefined ? prop.maxValue.toString() : "null";
+    const hasAny = prop.minValue !== undefined || prop.maxValue !== undefined;
+    return { minValue, maxValue, hasAny };
+}
+function applyCsValidationExpression(prop, expression, csvHeadersLiteral) {
+    const stringConstraints = buildCsStringConstraintsLiteral(prop);
+    const numberConstraints = buildCsNumberConstraintsLiteral(prop);
+    const nameLiteral = JSON.stringify(prop.name);
+    switch (prop.type) {
+        case "string":
+        case "principal":
+            return stringConstraints.hasAny
+                ? `Validation.ValidateString(${nameLiteral}, ${expression}, ${stringConstraints.minLength}, ${stringConstraints.maxLength}, ${stringConstraints.pattern}, ${stringConstraints.format})`
+                : expression;
+        case "dateTime":
+            if (!stringConstraints.hasAny)
+                return expression;
+            return `RowParser.ParseDateTime(Validation.ValidateString(${nameLiteral}, RowParser.ReadValue(row, ${csvHeadersLiteral}), ${stringConstraints.minLength}, ${stringConstraints.maxLength}, ${stringConstraints.pattern}, ${stringConstraints.format}))`;
+        case "stringCollection":
+            return stringConstraints.hasAny
+                ? `Validation.ValidateStringCollection(${nameLiteral}, ${expression}, ${stringConstraints.minLength}, ${stringConstraints.maxLength}, ${stringConstraints.pattern}, ${stringConstraints.format})`
+                : expression;
+        case "dateTimeCollection":
+            if (!stringConstraints.hasAny)
+                return expression;
+            return `Validation.ValidateStringCollection(${nameLiteral}, RowParser.ParseStringCollection(RowParser.ReadValue(row, ${csvHeadersLiteral})), ${stringConstraints.minLength}, ${stringConstraints.maxLength}, ${stringConstraints.pattern}, ${stringConstraints.format}).Select(value => RowParser.ParseDateTime(value)).ToList()`;
+        case "int64":
+            return numberConstraints.hasAny
+                ? `Validation.ValidateInt64(${nameLiteral}, ${expression}, ${numberConstraints.minValue}, ${numberConstraints.maxValue})`
+                : expression;
+        case "double":
+            return numberConstraints.hasAny
+                ? `Validation.ValidateDouble(${nameLiteral}, ${expression}, ${numberConstraints.minValue}, ${numberConstraints.maxValue})`
+                : expression;
+        case "int64Collection":
+            return numberConstraints.hasAny
+                ? `Validation.ValidateInt64Collection(${nameLiteral}, ${expression}, ${numberConstraints.minValue}, ${numberConstraints.maxValue})`
+                : expression;
+        case "doubleCollection":
+            return numberConstraints.hasAny
+                ? `Validation.ValidateDoubleCollection(${nameLiteral}, ${expression}, ${numberConstraints.minValue}, ${numberConstraints.maxValue})`
+                : expression;
+        default:
+            return expression;
+    }
+}
+function exampleValueForType(example, type) {
+    if (example === undefined || example === null)
+        return undefined;
+    if (type.endsWith("Collection")) {
+        if (Array.isArray(example)) {
+            return example.map((value) => (value === undefined || value === null ? "" : String(value))).join(";");
+        }
+        if (typeof example === "string")
+            return example;
+        return JSON.stringify(example);
+    }
+    if (typeof example === "string")
+        return example;
+    if (typeof example === "number" || typeof example === "boolean")
+        return String(example);
+    return JSON.stringify(example);
+}
 function sampleValueForHeader(header, type) {
     const lower = header.toLowerCase();
     if (lower.includes("job title"))
@@ -650,6 +819,14 @@ function buildSampleCsv(ir) {
     const valueByHeader = new Map();
     for (const prop of ir.properties) {
         if (prop.personEntity) {
+            const exampleValue = exampleValueForType(prop.example, prop.type);
+            if (exampleValue && prop.personEntity.fields.length === 1) {
+                const headers = prop.personEntity.fields[0]?.source.csvHeaders ?? [];
+                for (const header of headers) {
+                    if (!valueByHeader.has(header))
+                        valueByHeader.set(header, exampleValue);
+                }
+            }
             for (const field of prop.personEntity.fields) {
                 for (const header of field.source.csvHeaders) {
                     if (!valueByHeader.has(header))
@@ -658,9 +835,11 @@ function buildSampleCsv(ir) {
             }
             continue;
         }
+        const exampleValue = exampleValueForType(prop.example, prop.type);
         for (const header of prop.source.csvHeaders) {
-            if (!valueByHeader.has(header))
-                valueByHeader.set(header, sampleValueForHeader(header, prop.type));
+            if (!valueByHeader.has(header)) {
+                valueByHeader.set(header, exampleValue ?? sampleValueForHeader(header, prop.type));
+            }
         }
     }
     const headerLine = headers.map(csvEscape).join(",");
@@ -669,13 +848,18 @@ function buildSampleCsv(ir) {
 }
 async function writeGeneratedDotnet(outDir, ir, namespaceName, schemaFolderName, schemaNamespace) {
     await mkdir(path.join(outDir, schemaFolderName), { recursive: true });
+    await mkdir(path.join(outDir, "Datasource"), { recursive: true });
     await mkdir(path.join(outDir, "Core"), { recursive: true });
+    await removeIfExists(path.join(outDir, schemaFolderName, "FromCsvRow.cs"));
+    await removeIfExists(path.join(outDir, "Datasource", "CsvParser.cs"));
     const usedPropertyNames = new Set();
     const itemTypeName = toCsIdentifier(ir.item.typeName);
     const properties = ir.properties.map((p) => {
         const parseFn = toCsParseFunction(p.type);
         const csvHeadersLiteral = `new[] { ${p.source.csvHeaders.map((h) => JSON.stringify(h)).join(", ")} }`;
         const isCollection = p.type === "stringCollection";
+        const nameLiteral = JSON.stringify(p.name);
+        const csStringConstraints = buildCsStringConstraintsLiteral(p);
         const personEntity = p.personEntity
             ? {
                 entity: p.personEntity.entity,
@@ -692,11 +876,34 @@ async function writeGeneratedDotnet(outDir, ir, namespaceName, schemaFolderName,
             ? `throw new NotImplementedException("Missing @coco.source(..., to) mappings for people entity '${p.name}'. Implement in PropertyTransform.cs.")`
             : personEntity
                 ? isCollection
-                    ? buildCsPersonEntityCollectionExpression(personEntity.fields)
-                    : buildCsPersonEntityExpression(personEntity.fields)
+                    ? buildCsPersonEntityCollectionExpression(personEntity.fields, (headersLiteral) => {
+                        const base = `RowParser.ParseStringCollection(row, ${headersLiteral})`;
+                        return csStringConstraints.hasAny
+                            ? `Validation.ValidateStringCollection(${nameLiteral}, ${base}, ${csStringConstraints.minLength}, ${csStringConstraints.maxLength}, ${csStringConstraints.pattern}, ${csStringConstraints.format})`
+                            : base;
+                    })
+                    : buildCsPersonEntityExpression(personEntity.fields, (headersLiteral) => {
+                        const base = `RowParser.ParseString(row, ${headersLiteral})`;
+                        return csStringConstraints.hasAny
+                            ? `Validation.ValidateString(${nameLiteral}, ${base}, ${csStringConstraints.minLength}, ${csStringConstraints.maxLength}, ${csStringConstraints.pattern}, ${csStringConstraints.format})`
+                            : base;
+                    })
                 : noSource
                     ? "default!"
                     : `${parseFn}(row, ${csvHeadersLiteral})`;
+        const validationMetadata = {
+            name: p.name,
+            type: p.type,
+            ...(p.minLength !== undefined ? { minLength: p.minLength } : {}),
+            ...(p.maxLength !== undefined ? { maxLength: p.maxLength } : {}),
+            ...(p.pattern ? { pattern: p.pattern } : {}),
+            ...(p.format ? { format: p.format } : {}),
+            ...(p.minValue !== undefined ? { minValue: p.minValue } : {}),
+            ...(p.maxValue !== undefined ? { maxValue: p.maxValue } : {}),
+        };
+        const validatedExpression = needsManualEntity || noSource || personEntity
+            ? transformExpression
+            : applyCsValidationExpression(validationMetadata, transformExpression, csvHeadersLiteral);
         return {
             name: p.name,
             csName: toCsPropertyName(p.name, itemTypeName, usedPropertyNames),
@@ -706,16 +913,35 @@ async function writeGeneratedDotnet(outDir, ir, namespaceName, schemaFolderName,
             isCollection,
             personEntity,
             parseFn,
-            transformExpression,
+            transformExpression: validatedExpression,
             transformThrows: needsManualEntity,
             graphTypeEnumName: toGraphPropertyTypeEnumName(p.type),
             description: p.description,
+            doc: p.doc,
             labels: p.labels,
             aliases: p.aliases,
             search: p.search,
             type: p.type,
+            format: p.format,
+            pattern: p.pattern,
+            minLength: p.minLength,
+            maxLength: p.maxLength,
+            minValue: p.minValue,
+            maxValue: p.maxValue,
         };
     });
+    const recordDocLines = [];
+    if (ir.item.doc) {
+        recordDocLines.push(...formatCsDocSummary(ir.item.doc));
+    }
+    for (const prop of properties) {
+        if (!prop.doc)
+            continue;
+        const docLines = prop.doc.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+        if (docLines.length === 0)
+            continue;
+        recordDocLines.push(`/// <param name=\"${prop.csName}\">${docLines.join(" ")}</param>`);
+    }
     const schemaPropertyLines = properties
         .filter((p) => p.name !== ir.item.contentPropertyName)
         .map((p) => {
@@ -765,7 +991,7 @@ async function writeGeneratedDotnet(outDir, ir, namespaceName, schemaFolderName,
     const idRawHeadersDotnet = itemIdProperty?.personEntity?.fields[0]?.source.csvHeaders ?? itemIdProperty?.csvHeaders ?? [];
     const idRawHeadersLiteral = `new[] { ${idRawHeadersDotnet.map((h) => JSON.stringify(h)).join(", ")} }`;
     const idRawExpressionDotnet = idRawHeadersDotnet.length
-        ? `CsvParser.ParseString(row, ${idRawHeadersLiteral})`
+        ? `RowParser.ParseString(row, ${idRawHeadersLiteral})`
         : "string.Empty";
     const constructorArgs = [
         ...properties.map((p) => `(${p.csType})transforms.TransformProperty(${JSON.stringify(p.name)}, row)`),
@@ -790,7 +1016,7 @@ async function writeGeneratedDotnet(outDir, ir, namespaceName, schemaFolderName,
     })
         .join("\n");
     const itemIdExpression = itemIdProperty
-        ? `!string.IsNullOrEmpty(item.CocoId) ? item.CocoId : (item.${itemIdProperty.csName} ?? string.Empty)`
+        ? `!string.IsNullOrEmpty(item.InternalId) ? item.InternalId : (item.${itemIdProperty.csName} ?? string.Empty)`
         : "\"\"";
     const contentValueExpression = ir.item.contentPropertyName
         ? `Convert.ToString(item.${toCsIdentifier(ir.item.contentPropertyName)}) ?? string.Empty`
@@ -806,6 +1032,7 @@ async function writeGeneratedDotnet(outDir, ir, namespaceName, schemaFolderName,
         schemaNamespace,
         itemTypeName: ir.item.typeName,
         properties: properties.map((p) => ({ csName: p.csName, csType: p.csType })),
+        recordDocLines,
     }), "utf8");
     await writeFile(path.join(outDir, schemaFolderName, "Constants.cs"), await renderTemplate("dotnet/Generated/Constants.cs.ejs", {
         schemaNamespace,
@@ -826,7 +1053,7 @@ async function writeGeneratedDotnet(outDir, ir, namespaceName, schemaFolderName,
         schemaPropertyLines,
         graphApiVersion: ir.connection.graphApiVersion,
     }), "utf8");
-    await writeFile(path.join(outDir, "Datasource", "CsvParser.cs"), await renderTemplate("dotnet/Generated/CsvParser.cs.ejs", {
+    await writeFile(path.join(outDir, "Datasource", "RowParser.cs"), await renderTemplate("dotnet/Generated/RowParser.cs.ejs", {
         namespaceName,
     }), "utf8");
     await writeFile(path.join(outDir, schemaFolderName, "PropertyTransformBase.cs"), await renderTemplate("dotnet/Generated/PropertyTransformBase.cs.ejs", {
@@ -834,6 +1061,11 @@ async function writeGeneratedDotnet(outDir, ir, namespaceName, schemaFolderName,
         schemaNamespace,
         properties,
         usesPersonEntity: properties.some((p) => p.personEntity),
+        usesLinq: properties.some((p) => p.type === "dateTimeCollection" &&
+            (p.minLength !== undefined ||
+                p.maxLength !== undefined ||
+                Boolean(p.pattern?.regex) ||
+                Boolean(p.format))),
     }), "utf8");
     const transformOverridesPath = path.join(outDir, schemaFolderName, "PropertyTransform.cs");
     try {
@@ -844,13 +1076,14 @@ async function writeGeneratedDotnet(outDir, ir, namespaceName, schemaFolderName,
             schemaNamespace,
         }), "utf8");
     }
-    await writeFile(path.join(outDir, schemaFolderName, "FromCsvRow.cs"), await renderTemplate("dotnet/Generated/FromCsvRow.cs.ejs", {
+    await writeFile(path.join(outDir, schemaFolderName, "FromRow.cs"), await renderTemplate("dotnet/Generated/FromRow.cs.ejs", {
         namespaceName,
         schemaNamespace,
         itemTypeName: ir.item.typeName,
         constructorArgLines,
     }), "utf8");
     await writeFile(path.join(outDir, schemaFolderName, "ItemPayload.cs"), await renderTemplate("dotnet/Generated/ItemPayload.cs.ejs", {
+        namespaceName,
         schemaNamespace,
         itemTypeName: ir.item.typeName,
         itemIdExpression,
@@ -866,6 +1099,12 @@ async function writeGeneratedDotnet(outDir, ir, namespaceName, schemaFolderName,
         isPeopleConnector: ir.connection.contentCategory === "people",
         graphApiVersion: ir.connection.graphApiVersion,
     }), "utf8");
+    await writeFile(path.join(outDir, "Core", "Validation.cs"), await renderTemplate("dotnet/Core/Validation.cs.ejs", {
+        namespaceName,
+    }), "utf8");
+    await writeFile(path.join(outDir, "Core", "ItemId.cs"), await renderTemplate("dotnet/Core/ItemId.cs.ejs", {
+        namespaceName,
+    }), "utf8");
 }
 function formatValidationErrors(ir) {
     const issues = validateIr(ir);