@supalive/codegen 1.1.0 → 1.2.0

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { n as generateToDisk, r as readEntryConfig } from "./src-BD-RIuCu.js";
+import { n as generateToDisk, r as readEntryConfig } from "./src-DIj2CWMc.js";
 import path from "node:path";
 //#region src/cli.ts
 function parseArgs(argv) {

package/dist/index.d.ts

@@ -62,10 +62,14 @@ interface FieldIR {
   optional: boolean;
   /** May be explicitly null (Zod `.nullable()` / TS `| null`). */
   nullable: boolean;
+  /** Doc comment copied from the TS source (JSDoc or Zod `.describe()`). */
+  doc?: string;
 }
 interface ModelIR {
   name: string;
   fields: FieldIR[];
+  /** Doc comment copied from the TS type declaration, when it has one. */
+  doc?: string;
 }
 interface EnumValueIR {
   dartName: string;
@@ -86,6 +90,8 @@ interface ProcedureIR {
   result: DartType;
   /** Whether the result may be null (TS `T | null`). */
   resultNullable: boolean;
+  /** Doc comment copied from the procedure's TS declaration (JSDoc). */
+  doc?: string;
 }
 interface ClientIR {
   clientClassName: string;

package/dist/index.js

@@ -1,2 +1,2 @@
-import { a as emit, i as resolveConfig, n as generateToDisk, o as extractClient, r as readEntryConfig, t as generate } from "./src-BD-RIuCu.js";
+import { a as emit, i as resolveConfig, n as generateToDisk, o as extractClient, r as readEntryConfig, t as generate } from "./src-DIj2CWMc.js";
 export { emit, extractClient, generate, generateToDisk, readEntryConfig, resolveConfig };

package/dist/{src-BD-RIuCu.js → src-DIj2CWMc.js}

@@ -2,6 +2,49 @@ import fs from "node:fs";
 import path from "node:path";
 import { Node, Project, ts } from "ts-morph";
 //#region src/zod-schema.ts
+/**
+* Map each procedure to the doc comment on its declaration, so the generated
+* client carries the same descriptions the backend documents. Reads the JSDoc
+* on the procedures-map entry, or (for a shorthand like `{ staffLogin }`)
+* follows the identifier to its `export const staffLogin = query({...})` and
+* reads that statement's JSDoc. Best-effort: any failure yields no doc.
+*/
+function scanProcedureDocs(routerDecl) {
+	const result = /* @__PURE__ */ new Map();
+	try {
+		const proceduresObj = getProceduresObjectLiteral(routerDecl);
+		if (!proceduresObj) return result;
+		for (const prop of proceduresObj.getProperties()) {
+			const key = getPropertyKey(prop);
+			if (!key) continue;
+			const doc = procedureDocText(prop);
+			if (doc) result.set(key, doc);
+		}
+	} catch {}
+	return result;
+}
+/** JSDoc on a procedures-map entry, or on the const it references. */
+function procedureDocText(prop) {
+	const own = jsDocText(prop);
+	if (own) return own;
+	let idNode;
+	if (Node.isShorthandPropertyAssignment(prop)) idNode = prop.getNameNode();
+	else if (Node.isPropertyAssignment(prop)) idNode = prop.getInitializer();
+	if (idNode && Node.isIdentifier(idNode)) {
+		for (const def of idNode.getDefinitionNodes()) if (Node.isVariableDeclaration(def)) {
+			const stmt = def.getVariableStatement();
+			const doc = stmt ? jsDocText(stmt) : void 0;
+			if (doc) return doc;
+		}
+	}
+}
+/** The trimmed description of a node's last JSDoc block, if any. */
+function jsDocText(node) {
+	const docs = Node.isJSDocable(node) ? node.getJsDocs() : [];
+	if (docs.length === 0) return void 0;
+	const desc = docs[docs.length - 1].getDescription().trim();
+	return desc.length > 0 ? desc : void 0;
+}
 function scanZodArgMeta(routerDecl) {
 	const result = /* @__PURE__ */ new Map();
 	try {
@@ -76,7 +119,9 @@ function scanObjectSchema(schema) {
 		if (methods.has("bigint")) meta.numeric = "bigint";
 		else if (methods.has("int")) meta.numeric = "int";
 		if (methods.has("default") || methods.has("catch") || methods.has("prefault")) meta.optional = true;
-		if (meta.numeric || meta.optional) map.set(key, meta);
+		const description = topLevelZodDescription(init);
+		if (description) meta.description = description;
+		if (meta.numeric || meta.optional || meta.description) map.set(key, meta);
 	}
 	return map;
 }
@@ -97,6 +142,34 @@ function topLevelZodMethods(node) {
 	}
 	return methods;
 }
+/**
+* The description string from a field's top-level `.describe("...")` or
+* `.meta({ description: "..." })`, walking the method chain (outermost first,
+* so the outermost description wins).
+*/
+function topLevelZodDescription(node) {
+	let cur = node;
+	while (cur && Node.isCallExpression(cur)) {
+		const expr = cur.getExpression();
+		if (!Node.isPropertyAccessExpression(expr)) break;
+		const method = expr.getName();
+		if (method === "describe") {
+			const arg = cur.getArguments()[0];
+			if (arg && Node.isStringLiteral(arg)) return arg.getLiteralValue();
+		}
+		if (method === "meta") {
+			const arg = cur.getArguments()[0];
+			if (arg && Node.isObjectLiteralExpression(arg)) {
+				const d = arg.getProperty("description");
+				if (d && Node.isPropertyAssignment(d)) {
+					const init = d.getInitializer();
+					if (init && Node.isStringLiteral(init)) return init.getLiteralValue();
+				}
+			}
+		}
+		cur = expr.getExpression();
+	}
+}
 function findZodObjectLiteral(node) {
 	let cur = node;
 	while (cur && Node.isCallExpression(cur)) {
@@ -115,20 +188,26 @@ function findZodObjectLiteral(node) {
 //#region src/extract.ts
 /** Load the router from the entry file and extract a ClientIR. */
 function extractClient(config) {
-	const exported = new Project({
+	const project = new Project({
 		tsConfigFilePath: config.tsconfig,
 		skipAddingFilesFromTsConfig: config.tsconfig ? false : true,
 		compilerOptions: config.tsconfig ? void 0 : {
 			strict: true,
 			target: ts.ScriptTarget.ES2022
 		}
-	}).addSourceFileAtPath(path.resolve(config.entry)).getExportedDeclarations().get(config.router);
+	});
+	const entry = project.addSourceFileAtPath(path.resolve(config.entry));
+	const opts = project.getCompilerOptions();
+	if (!(opts.strictNullChecks ?? opts.strict ?? false)) console.warn("[supalive-codegen] strictNullChecks is disabled" + (config.tsconfig ? ` in ${config.tsconfig}` : "") + ". Nullable/optional fields (`T | null`, `field?`) will be generated as non-nullable, because TypeScript erases those unions when strictNullChecks is off. Set `strict: true` (or `strictNullChecks: true`) in your tsconfig for correct output.");
+	const exported = entry.getExportedDeclarations().get(config.router);
 	if (!exported || exported.length === 0) throw new Error(`Could not find an export named "${config.router}" in ${config.entry}. Set { router: "<name>" } in your config or pass --router.`);
 	const routerDecl = exported[0];
 	const proceduresSym = routerDecl.getType().getProperty("procedures");
 	if (!proceduresSym) throw new Error(`Export "${config.router}" does not look like a Supalive router (no "procedures" property).`);
 	const proceduresType = proceduresSym.getTypeAtLocation(routerDecl);
-	const extractor = new Extractor(routerDecl, config, scanZodArgMeta(routerDecl));
+	const argMeta = scanZodArgMeta(routerDecl);
+	const procDocs = scanProcedureDocs(routerDecl);
+	const extractor = new Extractor(routerDecl, config, argMeta, project.getTypeChecker());
 	const procedures = [];
 	for (const procSym of proceduresType.getProperties()) {
 		const name = procSym.getName();
@@ -136,6 +215,8 @@ function extractClient(config) {
 		const ir = extractor.procedure(name, procType);
 		if (!ir) continue;
 		if (ir.internal && !config.includeInternal) continue;
+		const doc = procDocs.get(name);
+		if (doc) ir.doc = doc;
 		procedures.push(ir);
 	}
 	procedures.sort((a, b) => a.name.localeCompare(b.name));
@@ -150,16 +231,28 @@ var Extractor = class {
 	locationNode;
 	config;
 	argMeta;
+	tc;
 	modelRegistry = /* @__PURE__ */ new Map();
 	enumRegistry = /* @__PURE__ */ new Map();
 	/** Value-set signature → already-registered enum name, for structural dedup. */
 	enumBySignature = /* @__PURE__ */ new Map();
 	nameCounts = /* @__PURE__ */ new Map();
 	visiting = /* @__PURE__ */ new Set();
-	constructor(locationNode, config, argMeta) {
+	constructor(locationNode, config, argMeta, tc) {
 		this.locationNode = locationNode;
 		this.config = config;
 		this.argMeta = argMeta;
+		this.tc = tc;
+	}
+	/** Doc comment attached to a symbol's declaration (resolves TS aliases). */
+	symbolDoc(sym) {
+		try {
+			const parts = sym.compilerSymbol.getDocumentationComment(this.tc.compilerObject);
+			const text = ts.displayPartsToString(parts).trim();
+			return text.length > 0 ? text : void 0;
+		} catch {
+			return;
+		}
 	}
 	models() {
 		return [...this.modelRegistry.values()];
@@ -186,6 +279,7 @@ var Extractor = class {
 				if (!meta) continue;
 				if (meta.numeric && (f.type.kind === "double" || f.type.kind === "int")) f.type = { kind: meta.numeric };
 				if (meta.optional) f.optional = true;
+				if (meta.description && !f.doc) f.doc = meta.description;
 			}
 		}
 		const ret = unwrapPromise(sig.getReturnType());
@@ -285,13 +379,17 @@ var Extractor = class {
 				jsonKey,
 				type: dartType,
 				optional,
-				nullable
+				nullable,
+				doc: this.symbolDoc(prop)
 			});
 		}
 		this.visiting.delete(name);
+		const modelSym = type.getAliasSymbol() ?? type.getSymbol();
+		const doc = modelSym ? this.symbolDoc(modelSym) : void 0;
 		this.modelRegistry.set(name, {
 			name,
-			fields
+			fields,
+			doc
 		});
 		return {
 			kind: "model",
@@ -457,10 +555,53 @@ function singular(hint) {
 	if (hint.endsWith("s") && !hint.endsWith("ss")) return hint.slice(0, -1);
 	return hint + "Item";
 }
+/**
+* Dart reserved words — none may be used as a bare identifier (e.g. an enum
+* constant), so a wire value like `void` must be escaped.
+*/
+const DART_RESERVED = /* @__PURE__ */ new Set([
+	"assert",
+	"break",
+	"case",
+	"catch",
+	"class",
+	"const",
+	"continue",
+	"default",
+	"do",
+	"else",
+	"enum",
+	"extends",
+	"false",
+	"final",
+	"finally",
+	"for",
+	"if",
+	"in",
+	"is",
+	"new",
+	"null",
+	"rethrow",
+	"return",
+	"super",
+	"switch",
+	"this",
+	"throw",
+	"true",
+	"try",
+	"var",
+	"void",
+	"while",
+	"with"
+]);
+/** Suffix a trailing `_` when [name] is a Dart reserved word. */
+function escapeDartId(name) {
+	return DART_RESERVED.has(name) ? `${name}_` : name;
+}
 function enumValueName(wire) {
 	const c = camel(wire);
 	if (!c || /^[0-9]/.test(c)) return "v" + pascal(wire);
-	return c;
+	return escapeDartId(c);
 }
 //#endregion
 //#region src/emit.ts
@@ -474,6 +615,11 @@ function emit(ir) {
 		contents: emitClient(ir)
 	}];
 }
+/** Render source doc text as Dart `///` lines at [indent], or "" when absent. */
+function docComment(text, indent) {
+	if (!text) return "";
+	return text.replace(/\r\n?/g, "\n").split("\n").map((line) => `${indent}///${line.length ? ` ${line}` : ""}`).join("\n") + "\n";
+}
 /** Dart type name for a non-null [DartType]. */
 function typeName(t) {
 	switch (t.kind) {
@@ -601,7 +747,7 @@ function emitModel(m) {
 		if (f.optional && f.nullable) return `    this.${f.name} = const Optional.absent()`;
 		return !(f.optional || f.nullable) ? `    required this.${f.name}` : `    this.${f.name}`;
 	}).join(",\n");
-	const fields = m.fields.map((f) => `  final ${fieldType(f)} ${f.name};`).join("\n");
+	const fields = m.fields.map((f) => `${docComment(f.doc, "  ")}  final ${fieldType(f)} ${f.name};`).join("\n");
 	const fromJson = m.fields.map((f) => emitFromJsonField(f)).join("\n");
 	const toJson = m.fields.map((f) => emitToJsonField(f)).join("\n");
 	const copyParams = m.fields.map((f) => `    Object? ${f.name} = _undefined`).join(",\n");
@@ -621,7 +767,7 @@ function emitModel(m) {
 	}).join(" &&\n          ");
 	const hashParts = m.fields.map((f) => isDeep(f) ? `deepHashCode(${f.name})` : f.name).join(", ");
 	const hashBody = m.fields.length === 0 ? "runtimeType.hashCode" : m.fields.length <= 19 ? `Object.hash(runtimeType, ${hashParts})` : `Object.hashAll([runtimeType, ${hashParts}])`;
-	return `class ${m.name} implements SupaliveModel {
+	return `${docComment(m.doc, "")}class ${m.name} implements SupaliveModel {
   const ${m.name}(${m.fields.length ? "{\n" + ctorParams + ",\n  }" : ""});
 
 ${fields}
@@ -725,7 +871,7 @@ function emitEndpoint(p) {
 	const endpointClass = p.kind === "query" ? "QueryEndpoint" : p.kind === "mutation" ? "MutationEndpoint" : "ActionEndpoint";
 	const args = argsTypeName(p);
 	const result = resultTypeName(p);
-	return `  late final ${p.name} = ${endpointClass}<${args}, ${result}>(
+	return `${docComment(p.doc, "  ")}  late final ${p.name} = ${endpointClass}<${args}, ${result}>(
     _client,
     '${p.name}',
     ${encodeArgs(p)},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supalive/codegen",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Generate type-safe client code (Dart, and more) from a Supalive TypeScript router.",
   "author": "Rebaz Raouf",
   "license": "MIT",
@@ -41,7 +41,8 @@
   "scripts": {
     "build": "tsdown",
     "dev": "node --import tsx ./src/cli.ts",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "test": "vitest --run"
   },
   "dependencies": {
     "ts-morph": "^24.0.0"