@hypequery/cli 1.25.2 → 1.26.0

package/dist/generators/client-contract/doc-comments.d.ts

@@ -0,0 +1,4 @@
+import type { ClientFieldAnnotation } from '@hypequery/protocol';
+/** One-line JSDoc from backend presentation text; validated text has no line breaks. */
+export declare function docComment(annotation: ClientFieldAnnotation | undefined, indent?: string): string;
+//# sourceMappingURL=doc-comments.d.ts.map

package/dist/generators/client-contract/doc-comments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doc-comments.d.ts","sourceRoot":"","sources":["../../../src/generators/client-contract/doc-comments.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAEjE,wFAAwF;AACxF,wBAAgB,UAAU,CAAC,UAAU,EAAE,qBAAqB,GAAG,SAAS,EAAE,MAAM,SAAK,GAAG,MAAM,CAK7F"}

package/dist/generators/client-contract/doc-comments.js

@@ -0,0 +1,8 @@
+/** One-line JSDoc from backend presentation text; validated text has no line breaks. */
+export function docComment(annotation, indent = '') {
+    const parts = [annotation?.label, annotation?.description].filter((part) => part !== undefined);
+    if (parts.length === 0)
+        return '';
+    // The comment terminator is the only sequence that can escape a block comment.
+    return `${indent}/** ${parts.join(' — ').replaceAll('*/', '*\\/')} */\n`;
+}

package/dist/generators/client-contract/input-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"input-types.d.ts","sourceRoot":"","sources":["../../../src/generators/client-contract/input-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAgB,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAEhF,eAAO,MAAM,OAAO,GAAI,OAAO,MAAM,KAAG,MAA+B,CAAC;AACxE,eAAO,MAAM,KAAK,GAAI,QAAQ,SAAS,MAAM,EAAE,KAAG,MAAsD,CAAC;AACzG,eAAO,MAAM,KAAK,GAAI,QAAQ,SAAS,MAAM,EAAE,KAAG,MAAgD,CAAC;AAWnG,0GAA0G;AAC1G,wBAAgB,eAAe,CAAC,QAAQ,EAAE,sBAAsB,GAAG,MAAM,CAqBxE"}
+{"version":3,"file":"input-types.d.ts","sourceRoot":"","sources":["../../../src/generators/client-contract/input-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAgB,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAEhF,eAAO,MAAM,OAAO,GAAI,OAAO,MAAM,KAAG,MAA+B,CAAC;AACxE,eAAO,MAAM,KAAK,GAAI,QAAQ,SAAS,MAAM,EAAE,KAAG,MAAsD,CAAC;AACzG,eAAO,MAAM,KAAK,GAAI,QAAQ,SAAS,MAAM,EAAE,KAAG,MAAgD,CAAC;AAenG,0GAA0G;AAC1G,wBAAgB,eAAe,CAAC,QAAQ,EAAE,sBAAsB,GAAG,MAAM,CAqBxE"}

package/dist/generators/client-contract/input-types.js

@@ -4,6 +4,10 @@ export const names = (values) => union([...values].sort().map(literal));
 function predicate(field, definition, having = false) {
     const scalar = definition.type === 'number' ? 'number' : definition.type === 'boolean' ? 'boolean' : 'string';
     return [...definition.operators].sort().map(operator => {
+        // A null check names no value (RFC 0023).
+        if (operator === 'isNull' || operator === 'isNotNull') {
+            return `{ readonly ${having ? 'measure' : 'field'}: ${literal(field)}; readonly operator: ${literal(operator)} }`;
+        }
         const value = operator === 'between' ? `readonly [${scalar}, ${scalar}]`
             : operator === 'in' || operator === 'notIn' ? `readonly [${scalar}, ...${scalar}[]]` : scalar;
         return `{ readonly ${having ? 'measure' : 'field'}: ${literal(field)}; readonly operator: ${literal(operator)}; readonly value: ${value} }`;

package/dist/generators/client-contract/render.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../../../src/generators/client-contract/render.ts"],"names":[],"mappings":"AA0BA,kGAAkG;AAClG,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAqB5D"}
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../../../src/generators/client-contract/render.ts"],"names":[],"mappings":"AAmCA,kGAAkG;AAClG,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAqB5D"}

package/dist/generators/client-contract/render.js

@@ -1,13 +1,16 @@
 import { validateProtocolClientContract } from '@hypequery/protocol';
+import { docComment } from './doc-comments.js';
 import { clientInputType, literal } from './input-types.js';
 function dimensionType(definition) {
     const wire = definition.wireType === 'number-or-string' ? 'number | string' : definition.wireType;
     return wire + (definition.nullable === false ? '' : ' | null');
 }
 function endpointType(endpoint) {
+    const fields = endpoint.annotations?.fields ?? {};
     const dimensions = Object.keys(endpoint.dimensions).sort().filter(key => endpoint.dimensions[key].groupable)
-        .map(key => `readonly ${literal(key)}?: ${dimensionType(endpoint.dimensions[key])};`);
-    const measures = Object.keys(endpoint.measures).sort().map(key => `readonly ${literal(key)}?: string | null;`);
+        .map(key => `${docComment(fields[key])}readonly ${literal(key)}?: ${dimensionType(endpoint.dimensions[key])};`);
+    const measures = Object.keys(endpoint.measures).sort()
+        .map(key => `${docComment(fields[key])}readonly ${literal(key)}?: string | null;`);
     // The physical time column may be nullable; the descriptor makes no non-null guarantee.
     const row = `{ ${[...dimensions, ...measures, ...(endpoint.time ? ['readonly period?: string | null;'] : [])].join('\n')} }`;
     const semantic = {
@@ -21,6 +24,11 @@ function endpointType(endpoint) {
     readonly __hypequeryClientSemantic?: ${JSON.stringify(semantic)};
   }`;
 }
+/** A metric documents itself through its sole measure; a dataset through its group text. */
+function endpointDoc(endpoint) {
+    const metric = endpoint.kind === 'metric' ? endpoint.annotations?.fields?.[Object.keys(endpoint.measures)[0]] : undefined;
+    return metric ?? endpoint.annotations;
+}
 /** Data-only generator: no API module evaluation, credentials, drivers or server dependencies. */
 export function renderClientContract(source) {
     const contract = validateProtocolClientContract(source);
@@ -36,7 +44,7 @@ export interface ClientResponseMeta {
   cache?: { hit: boolean };
 }
 export type ClientApi = {
-${entries.map(({ endpoint, key }) => `  ${literal(key)}: ${endpointType(endpoint)};`).join('\n')}
+${entries.map(({ endpoint, key }) => `${docComment(endpointDoc(endpoint), '  ')}  ${literal(key)}: ${endpointType(endpoint)};`).join('\n')}
 };
 export const clientManifest = {
 ${entries.map(({ endpoint, key }) => `  [${literal(key)}]: { method: 'POST', path: ${literal(endpoint.path)}, schemaHash: ${literal(endpoint.schemaHash)} },`).join('\n')}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypequery/cli",
-  "version": "1.25.2",
+  "version": "1.26.0",
   "description": "CLI for scaffolding type-safe ClickHouse analytics, semantic datasets, React manifests, and deployments",
   "keywords": [
     "clickhouse",
@@ -30,8 +30,8 @@
     "open": "^11.0.4",
     "ora": "^8.0.1",
     "prompts": "^2.4.2",
-    "@hypequery/deployment": "0.10.2",
-    "@hypequery/protocol": "0.23.0"
+    "@hypequery/deployment": "0.11.0",
+    "@hypequery/protocol": "0.24.0"
   },
   "optionalDependencies": {
     "@napi-rs/keyring": "2.1.2"
@@ -54,8 +54,8 @@
     "@vitest/coverage-v8": "^5.0.5",
     "typescript": "^6.0.3",
     "vitest": "^5.0.5",
-    "@hypequery/mcp": "0.10.2",
-    "@hypequery/serve": "0.23.1"
+    "@hypequery/mcp": "0.11.0",
+    "@hypequery/serve": "0.24.0"
   },
   "repository": {
     "type": "git",