@json-to-office/jto 1.0.0 → 1.5.0

package/dist/cli.js

@@ -225,6 +225,30 @@ import {
   documentFontRegistry,
   themeFontRegistry
 } from "@json-to-office/shared";
+import {
+  QualityGateError
+} from "@json-to-office/quality";
+function toQualityWarnings(diagnostics) {
+  return diagnostics.map((finding) => ({
+    component: "quality",
+    message: `[${finding.code}] ${finding.message}`,
+    severity: finding.severity === "info" ? "info" : "warning",
+    context: {
+      ...finding.context ?? {},
+      code: finding.code,
+      path: finding.path,
+      originalSeverity: finding.severity,
+      ...finding.ruleId && { ruleId: finding.ruleId },
+      ...finding.category && { category: finding.category },
+      ...finding.certainty && { certainty: finding.certainty },
+      blocking: finding.blocking,
+      ...finding.suggestion && { suggestion: finding.suggestion },
+      ...finding.relatedPaths && { relatedPaths: finding.relatedPaths },
+      ...finding.evidence && { evidence: finding.evidence },
+      ...finding.fixes && { fixes: finding.fixes }
+    }
+  }));
+}
 function collectReferencedNames(config2, customThemes, adapterName) {
   const collect = adapterName === "docx" ? collectFontNamesFromDocx : collectFontNamesFromPptx;
   const names = /* @__PURE__ */ new Set();
@@ -444,6 +468,56 @@ var init_generator = __esm({
         const bypassCache = options?.bypassCache === true || extraEntries.length > 0 || declaresRegistry;
         const baseDir = typeof options?.baseDir === "string" ? options.baseDir : void 0;
         const renderer = typeof options?.renderer === "string" ? options.renderer : void 0;
+        const resolvedFonts = [];
+        const coreWarnings = [];
+        const needsFontOpts = extraEntries.length > 0 || declaresRegistry || fontMode !== void 0 || fontSubstitution !== void 0 || callerStrict !== void 0;
+        const fontOpts = needsFontOpts ? {
+          ...extraEntries.length > 0 && { extraEntries },
+          ...fontMode && { mode: fontMode },
+          ...fontSubstitution && { substitution: fontSubstitution },
+          ...callerStrict !== void 0 && { strict: callerStrict },
+          onResolved: (resolved) => {
+            resolvedFonts.push(...resolved);
+          }
+        } : void 0;
+        const registry = PluginRegistry.getInstance();
+        const quality = options?.quality;
+        const prepared = !registry.hasPlugins() && this.adapter.prepareDocument && this.adapter.validateDocument(config2).valid ? await this.adapter.prepareDocument(config2, {
+          customThemes,
+          fonts: fontOpts,
+          baseDir,
+          renderer,
+          warnings: coreWarnings
+        }) : void 0;
+        const qualityOptions = {
+          customThemes,
+          fonts: fontOpts,
+          baseDir,
+          renderer,
+          quality,
+          prepared
+        };
+        let qualityWarnings = [];
+        try {
+          if (this.adapter.analyzeQuality) {
+            const analysis = await this.adapter.analyzeQuality(
+              config2,
+              qualityOptions
+            );
+            if (analysis.blocked) throw new QualityGateError(analysis);
+            qualityWarnings = toQualityWarnings(analysis.diagnostics);
+          }
+        } catch (error) {
+          const errorCode = error?.code;
+          if (errorCode === "QUALITY_GATE_FAILED" || errorCode === "QUALITY_PROFILE_INCOMPATIBLE" || // An unusable policy is the caller's configuration, not a hiccup.
+          errorCode === "QUALITY_POLICY_INVALID" || quality?.policy?.onRuleError === "throw" || // A caller who asked for a gate must not receive an ungated document:
+          // if the analysis failed, the gate never ran. Only the advisory case
+          // (no gate requested) degrades to a warning.
+          quality?.policy?.gate && quality.policy.gate !== "none") {
+            throw error;
+          }
+          logger.warn("Quality analysis failed", { error });
+        }
         const cacheKeyData = {
           config: config2,
           customThemes: customThemes && Object.keys(customThemes).length > 0 ? customThemes : null,
@@ -466,30 +540,17 @@ var init_generator = __esm({
               filename: `${config2.metadata?.title || this.adapter.label}${this.adapter.extension}`,
               fileId: Date.now().toString(),
               buffer: cached.buffer,
-              // Warnings ride along with the bytes: a cache hit describes the same
-              // document, so it must report the same font problems.
+              // Render warnings ride with bytes. Quality is request policy, so it
+              // is recomputed and merged even when the rendered artifact is cached.
               cached: true,
-              warnings: cached.warnings
+              warnings: cached.warnings || qualityWarnings.length > 0 ? [...cached.warnings ?? [], ...qualityWarnings] : null
             };
           }
         }
         logger.info(`Generating ${this.adapter.label}`, {
           title: config2.metadata?.title
         });
-        const registry = PluginRegistry.getInstance();
         let buffer;
-        const resolvedFonts = [];
-        const needsFontOpts = extraEntries.length > 0 || declaresRegistry || fontMode !== void 0 || fontSubstitution !== void 0 || callerStrict !== void 0;
-        const fontOpts = needsFontOpts ? {
-          ...extraEntries.length > 0 && { extraEntries },
-          ...fontMode && { mode: fontMode },
-          ...fontSubstitution && { substitution: fontSubstitution },
-          ...callerStrict !== void 0 && { strict: callerStrict },
-          onResolved: (r) => {
-            resolvedFonts.push(...r);
-          }
-        } : void 0;
-        const coreWarnings = [];
         if (registry.hasPlugins()) {
           const plugins = registry.getPlugins();
           const generator = await this.adapter.createGenerator(plugins, {
@@ -497,7 +558,8 @@ var init_generator = __esm({
             fonts: fontOpts,
             baseDir,
             renderer,
-            warnings: coreWarnings
+            warnings: coreWarnings,
+            quality
           });
           buffer = await generator.generateBuffer(config2);
         } else {
@@ -506,7 +568,9 @@ var init_generator = __esm({
             fonts: fontOpts,
             baseDir,
             renderer,
-            warnings: coreWarnings
+            warnings: coreWarnings,
+            quality,
+            prepared
           });
         }
         const CANONICAL_WEIGHTS = /* @__PURE__ */ new Set([
@@ -532,10 +596,14 @@ var init_generator = __esm({
             context: { code: "FONT_NONCANONICAL_WEIGHT" }
           });
         }
-        const allWarnings = [...coreWarnings, ...extraWarnings];
+        const renderWarnings = [...coreWarnings, ...extraWarnings];
+        const allWarnings = [...renderWarnings, ...qualityWarnings];
         this.cacheService.set(
           cacheKey,
-          { buffer, warnings: allWarnings.length > 0 ? allWarnings : null },
+          {
+            buffer,
+            warnings: renderWarnings.length > 0 ? renderWarnings : null
+          },
           config2,
           { bypassCache: bypassCache || hasDynamicContent }
         );
@@ -548,9 +616,35 @@ var init_generator = __esm({
           resolvedFonts
         };
       }
-      async validate(jsonDefinition) {
+      async validate(jsonDefinition, options = {}) {
         const config2 = typeof jsonDefinition === "string" ? JSON.parse(jsonDefinition) : jsonDefinition;
-        return this.adapter.validateDocument(config2);
+        const result = this.adapter.validateDocument(config2);
+        if (!result.valid) return result;
+        if (this.adapter.analyzeQuality) {
+          try {
+            const prepared = this.adapter.prepareDocument ? await this.adapter.prepareDocument(config2, options) : void 0;
+            const qualityAnalysis = await this.adapter.analyzeQuality(
+              config2,
+              prepared ? { ...options, prepared } : options
+            );
+            return {
+              ...result,
+              valid: result.valid && !qualityAnalysis.blocked,
+              qualityAnalysis
+            };
+          } catch (error) {
+            const errorCode = error?.code;
+            const quality = options.quality;
+            if (errorCode === "QUALITY_GATE_FAILED" || errorCode === "QUALITY_PROFILE_INCOMPATIBLE" || errorCode === "QUALITY_POLICY_INVALID" || quality?.policy?.onRuleError === "throw" || // Same rule `generate` applies: an analysis that never ran leaves a
+            // requested gate unevaluated, and answering `valid: true` there would
+            // promise a generation this service would then refuse.
+            quality?.policy?.gate && quality.policy.gate !== "none") {
+              throw error;
+            }
+            logger.warn("Quality analysis failed", { error });
+          }
+        }
+        return result;
       }
       destroy() {
         if (this.cacheInvalidationHandler) {
@@ -992,7 +1086,15 @@ var init_health = __esm({
         const cacheService = getContainer().get("cacheService");
         cacheStats = cacheService.getStats();
       } catch {
-        cacheStats = { enabled: false, hits: 0, misses: 0, hitRate: 0, evictions: 0, size: 0, itemCount: 0 };
+        cacheStats = {
+          enabled: false,
+          hits: 0,
+          misses: 0,
+          hitRate: 0,
+          evictions: 0,
+          size: 0,
+          itemCount: 0
+        };
       }
       return c.json({
         status: "ok",
@@ -1022,7 +1124,7 @@ var init_health = __esm({
 
 // src/server/schemas/loose.ts
 import { Type } from "@sinclair/typebox";
-var FontOptionsSchema, LooseDocumentGenerationRequestSchema, LooseDocumentValidationRequestSchema, LooseDocumentDiffRequestSchema;
+var FontOptionsSchema, QualityOptionsSchema, LooseDocumentGenerationRequestSchema, LooseDocumentValidationRequestSchema, LooseDocumentDiffRequestSchema;
 var init_loose = __esm({
   "src/server/schemas/loose.ts"() {
     "use strict";
@@ -1043,6 +1145,18 @@ var init_loose = __esm({
       },
       { additionalProperties: false }
     );
+    QualityOptionsSchema = Type.Object(
+      {
+        profile: Type.Optional(
+          Type.Object(
+            { id: Type.String({ minLength: 1, maxLength: 128 }) },
+            { additionalProperties: true }
+          )
+        ),
+        policy: Type.Optional(Type.Object({}, { additionalProperties: true }))
+      },
+      { additionalProperties: false }
+    );
     LooseDocumentGenerationRequestSchema = Type.Object(
       {
         jsonDefinition: Type.Union([
@@ -1062,6 +1176,7 @@ var init_loose = __esm({
               // enum: the registry owns the list, answers an unknown id with the
               // ids that exist, and the route turns that into a 400.
               renderer: Type.Optional(Type.String({ maxLength: 64 })),
+              quality: Type.Optional(QualityOptionsSchema),
               // Name of the discovered document this definition came from; the
               // server maps it to that document's directory so relative asset
               // paths resolve against it (#142). Names, never paths — a client
@@ -1081,7 +1196,16 @@ var init_loose = __esm({
           // Allow JSON string
           Type.Object({}, { additionalProperties: true })
           // Allow any object
-        ])
+        ]),
+        options: Type.Optional(
+          Type.Object(
+            {
+              renderer: Type.Optional(Type.String({ maxLength: 64 })),
+              quality: Type.Optional(QualityOptionsSchema)
+            },
+            { additionalProperties: false }
+          )
+        )
       },
       { additionalProperties: true }
     );
@@ -1950,6 +2074,17 @@ import {
 import { dirname } from "path";
 function throwIfClientError(error) {
   const code = error?.code;
+  if (code === "QUALITY_GATE_FAILED") {
+    throw new HTTPException4(400, {
+      message: error.message,
+      cause: error
+    });
+  }
+  if (code === "QUALITY_PROFILE_INCOMPATIBLE" || // A gate or severity the policy parser cannot read came in on the
+  // request, so the request is what is at fault.
+  code === "QUALITY_POLICY_INVALID") {
+    throw new HTTPException4(400, { message: error.message });
+  }
   if (code === "UNSUPPORTED_RENDERER_FEATURE" || code === "UNCOMPILED_COMPONENT" || // An id nobody registered is the caller naming a backend that does not
   // exist. The message already lists the ones that do.
   code === "UNKNOWN_RENDERER") {
@@ -2044,6 +2179,7 @@ function createFormatRouter(adapter) {
         }
         const clientOptions = { ...options };
         delete clientOptions.baseDir;
+        delete clientOptions.prepared;
         const result = await generatorService.generate({
           jsonDefinition: effectiveDefinition,
           customThemes,
@@ -2091,13 +2227,10 @@ function createFormatRouter(adapter) {
     tbValidator(LooseDocumentValidationRequestSchema),
     async (c) => {
       const generatorService = getContainer().get("generatorService");
-      const { jsonDefinition } = getValidated(
-        c,
-        "json"
-      );
+      const { jsonDefinition, options } = getValidated(c, "json");
       const requestId = c.get("requestId");
       try {
-        const result = await generatorService.validate(jsonDefinition);
+        const result = await generatorService.validate(jsonDefinition, options);
         return c.json({
           success: result.valid,
           data: result,
@@ -2105,6 +2238,7 @@ function createFormatRouter(adapter) {
         });
       } catch (error) {
         logger.error("Validation failed", { error, requestId });
+        throwIfClientError(error);
         throw error;
       }
     }
@@ -2590,7 +2724,7 @@ async function generateDocumentSchema(format, pluginNames) {
     });
     const unified = shared.generateUnifiedDocumentSchema({ customComponents });
     return shared.convertToJsonSchema(unified, {
-      $schema: "https://json-schema.org/draft-07/schema#",
+      $schema: "http://json-schema.org/draft-07/schema#",
       $id: "https://json-to-office.dev/schema/document/v1.0.0",
       title: "JSON to DOCX Document Definition",
       description: "Schema for JSON to DOCX JSON document definitions"
@@ -2608,7 +2742,7 @@ async function generateDocumentSchema(format, pluginNames) {
     }));
     const unified = shared.generateUnifiedDocumentSchema({ customComponents });
     return shared.convertToJsonSchema(unified, {
-      $schema: "https://json-schema.org/draft-07/schema#",
+      $schema: "http://json-schema.org/draft-07/schema#",
       $id: "https://json-to-office.dev/schema/presentation/v1.0.0",
       title: "JSON to PPTX Presentation Definition",
       description: "Schema for JSON to PPTX JSON presentation definitions"
@@ -2631,7 +2765,7 @@ async function generateThemeSchema(format) {
   cleanupTypeBoxIds(schema);
   return {
     ...schema,
-    $schema: "https://json-schema.org/draft-07/schema#",
+    $schema: "http://json-schema.org/draft-07/schema#",
     $id: "https://json-to-office.dev/schemas/theme/v1.0.0",
     title: `JSON to ${label} Theme`,
     description: `Theme definition for JSON to ${label} ${format === "docx" ? "documents" : "presentations"}`
@@ -3499,6 +3633,19 @@ var init_error_handler = __esm({
     errorHandler = (err, c) => {
       const requestId = c.get("requestId") || "unknown";
       if (err instanceof HTTPException6) {
+        const cause = err.cause;
+        if (cause?.code === "QUALITY_GATE_FAILED") {
+          return c.json(
+            {
+              success: false,
+              error: err.message,
+              code: cause.code,
+              quality: cause.analysis,
+              requestId
+            },
+            400
+          );
+        }
         return c.json(
           {
             success: false,
@@ -4182,7 +4329,7 @@ function createDevCommand(adapter) {
 }
 
 // src/cli.ts
-var PACKAGE_VERSION = true ? "1.0.0" : "dev-mode";
+var PACKAGE_VERSION = true ? "1.5.0" : "dev-mode";
 var program = new Command2();
 program.name("jto").description("JSON to Office CLI - Generate .docx and .pptx from JSON").version(PACKAGE_VERSION);
 registerCoreCommands(program, {