ppt-template-reuse 0.4.0-rc.2

package/src/core/template-inspector.mjs

@@ -0,0 +1,489 @@
+import path from "node:path";
+
+import { fingerprint, sha256File } from "./io.mjs";
+import {
+  attr,
+  elements,
+  emuToPoints,
+  loadPptx,
+  parseXml,
+  shapeRecords,
+  slideRecords,
+  xmlFrom,
+} from "./pptx-package.mjs";
+
+const VISUAL_CUE =
+  /(插入图片|相关图片|照片|图片|image|photo|picture|icon|图标|占位)/i;
+
+function normalized(value) {
+  return String(value || "").replace(/\s+/g, "").toLowerCase();
+}
+
+function textUnits(value) {
+  let count = 0;
+  for (const character of String(value || "")) {
+    if (/\s/.test(character)) count += 0.3;
+    else if (/[\u3400-\u9fff\u3000-\u303f\uff00-\uffef]/u.test(character)) {
+      count += 1;
+    } else count += 0.55;
+  }
+  return Number(count.toFixed(2));
+}
+
+function isGrayFill(value) {
+  const match = String(value || "").match(/^([0-9a-f]{6})$/i);
+  if (!match) return false;
+  const channels = [0, 2, 4].map((offset) =>
+    Number.parseInt(match[1].slice(offset, offset + 2), 16),
+  );
+  return (
+    Math.max(...channels) - Math.min(...channels) <= 12 &&
+    channels[0] >= 70 &&
+    channels[0] <= 225
+  );
+}
+
+function purposeForShape(shape, titleId) {
+  if (shape.id === titleId) return "title";
+  if (/title|标题/i.test(shape.placeholderType || shape.name)) return "title";
+  if (/subtitle|副标题/i.test(shape.placeholderType || shape.name)) {
+    return "subtitle";
+  }
+  if (/footer|页脚/i.test(shape.placeholderType || shape.name)) return "footer";
+  if (/date|日期/i.test(shape.placeholderType || shape.name)) return "date";
+  if (/sldnum|页码/i.test(shape.placeholderType || shape.name)) {
+    return "pageNumber";
+  }
+  if (shape.kind === "image") return "image";
+  if (shape.kind === "chart") return "chart";
+  if (shape.kind === "table") return "table";
+  return "body";
+}
+
+function titleShape(shapes) {
+  const explicit = shapes.find(
+    (shape) =>
+      shape.kind === "text" &&
+      /title|ctrTitle|标题/i.test(shape.placeholderType || shape.name),
+  );
+  if (explicit) return explicit;
+  return shapes
+    .filter((shape) => shape.kind === "text" && shape.text)
+    .sort(
+      (left, right) =>
+        right.fontSize - left.fontSize ||
+        left.bbox.y - right.bbox.y ||
+        left.bbox.x - right.bbox.x,
+    )[0];
+}
+
+function classifySlide(slideNumber, slideCount, shapes) {
+  const text = shapes.map((shape) => shape.text).join(" ");
+  const compact = normalized(text);
+  const textShapes = shapes.filter((shape) => shape.kind === "text" && shape.text);
+  const bodyShapes = textShapes.filter((shape) =>
+    /body|content|正文|内容/i.test(
+      `${shape.placeholderType || ""} ${shape.name || ""}`,
+    ),
+  );
+  const contentCue =
+    /(分析|依据|证据|事实|规则|理由|影响|结论|问题|方法|数据|说明|analysis|evidence|reason|finding)/i.test(
+      text,
+    );
+  const visuals = shapes.filter((shape) =>
+    ["image", "chart", "table"].includes(shape.kind),
+  );
+  if (slideNumber === 1) {
+    return {
+      layoutFamily: "cover",
+      communicationFunctions: ["opening", "identity"],
+      narrativeRoles: ["opening"],
+    };
+  }
+  if (/(谢谢|thank|q&a|questions|答疑)/i.test(text)) {
+    return {
+      layoutFamily: "closing",
+      communicationFunctions: ["closing"],
+      narrativeRoles: ["closing"],
+    };
+  }
+  if (/(目录|议程|agenda|contents|路线)/i.test(text)) {
+    return {
+      layoutFamily: "agenda",
+      communicationFunctions: ["roadmap", "agenda"],
+      narrativeRoles: ["agenda", "roadmap"],
+    };
+  }
+  if (/(时间轴|timeline|历程|里程碑)/i.test(text)) {
+    return {
+      layoutFamily: "timeline",
+      communicationFunctions: ["sequence", "chronology"],
+      narrativeRoles: ["sequence"],
+    };
+  }
+  if (
+    /(封面|答辩人|汇报人|制作人|指导教师)/i.test(text) &&
+    !/(part|chapter|section|目录|议程|contents)/i.test(text) &&
+    Math.max(...textShapes.map((shape) => shape.fontSize || 0), 0) >= 36
+  ) {
+    return {
+      layoutFamily: "cover",
+      communicationFunctions: ["opening", "identity"],
+      narrativeRoles: ["opening"],
+    };
+  }
+  if (shapes.some((shape) => shape.kind === "chart")) {
+    return {
+      layoutFamily: "chart",
+      communicationFunctions: ["data", "evidence"],
+      narrativeRoles: ["evidence", "analysis"],
+    };
+  }
+  if (shapes.some((shape) => shape.kind === "table")) {
+    return {
+      layoutFamily: "table",
+      communicationFunctions: ["comparison", "data"],
+      narrativeRoles: ["evidence", "analysis"],
+    };
+  }
+  if (/^(part|chapter|section|\d{1,2})/i.test(compact)) {
+    return {
+      layoutFamily: "divider",
+      communicationFunctions: ["section"],
+      narrativeRoles: ["section"],
+    };
+  }
+  if (
+    textShapes.length <= 3 &&
+    visuals.length === 0 &&
+    Math.max(...textShapes.map((shape) => shape.fontSize || 0), 0) >= 24 &&
+    !contentCue &&
+    (bodyShapes.length === 0 ||
+      bodyShapes.reduce((sum, shape) => sum + shape.text.length, 0) < 18)
+  ) {
+    return {
+      layoutFamily: "divider",
+      communicationFunctions: ["section"],
+      narrativeRoles: ["section"],
+    };
+  }
+  if (visuals.some((shape) => shape.kind === "image")) {
+    return {
+      layoutFamily: "image",
+      communicationFunctions: ["example", "evidence", "visual"],
+      narrativeRoles: ["evidence", "analysis"],
+    };
+  }
+  if (
+    textShapes.length >= 4 &&
+    new Set(textShapes.map((shape) => Math.round(shape.bbox.x / 80))).size >= 2
+  ) {
+    return {
+      layoutFamily: "comparison",
+      communicationFunctions: ["comparison", "analysis"],
+      narrativeRoles: ["analysis"],
+    };
+  }
+  return {
+    layoutFamily: "analysis",
+    communicationFunctions: ["claim", "analysis", "evidence"],
+    narrativeRoles: ["analysis"],
+  };
+}
+
+function inferUseCases(allText) {
+  const primary = [];
+  if (/(大学|university|学院|答辩|论文|研究|文献)/i.test(allText)) {
+    primary.push("academic-defense");
+  }
+  if (/(课程|作业|课堂|汇报|course|homework|assignment)/i.test(allText)) {
+    primary.push("course-presentation");
+  }
+  if (/(法院|民法|法律|合同|诉讼|法条)/i.test(allText)) {
+    primary.push("legal-analysis");
+  }
+  if (/(产品|市场|融资|商业|客户|增长)/i.test(allText)) {
+    primary.push("product-proposal", "business-pitch");
+  }
+  if (/(数据|同比|环比|指标|报告)/i.test(allText)) primary.push("data-report");
+  if (/(教学|培训|学习目标|练习)/i.test(allText)) {
+    primary.push("teaching-training");
+  }
+  if (/(年度|季度|业绩|部门|经营)/i.test(allText)) {
+    primary.push("corporate-report");
+  }
+  if (/(政策|治理|监管|改革|政府)/i.test(allText)) {
+    primary.push("policy-public-affairs");
+  }
+  if (/(作品集|摄影|品牌|视觉|portfolio)/i.test(allText)) {
+    primary.push("visual-portfolio");
+  }
+  return [...new Set(primary.length ? primary : ["general-report"])];
+}
+
+export async function inspectTemplate(templatePath) {
+  const resolved = path.resolve(templatePath);
+  const extension = path.extname(resolved).toLowerCase();
+  if (extension === ".pptm") {
+    const error = new Error("Macro-enabled PPTM templates are rejected by default");
+    error.code = "MACRO_TEMPLATE_REJECTED";
+    throw error;
+  }
+  if (![".pptx", ".potx"].includes(extension)) {
+    throw new Error("Template must be a native PPTX or POTX file");
+  }
+  const zip = await loadPptx(resolved);
+  const order = await slideRecords(zip);
+  const slideSize = elements(order.presentation, "sldSz")[0];
+  const canvas = {
+    width: emuToPoints(attr(slideSize, "cx")),
+    height: emuToPoints(attr(slideSize, "cy")),
+  };
+  const slides = [];
+  const textCorpus = [];
+  for (const record of order.slides) {
+    const xml = await xmlFrom(zip, record.partName);
+    const document = parseXml(xml);
+    const shapes = shapeRecords(document);
+    const title = titleShape(shapes);
+    const classification = classifySlide(
+      record.slideNumber,
+      order.slides.length,
+      shapes,
+    );
+    const slotSchema = [];
+    const assetRequirements = [];
+    let ambiguousGrayPlaceholder = false;
+    for (const shape of shapes) {
+      const purpose = purposeForShape(shape, title?.id);
+      const visualInstruction =
+        shape.kind === "text" &&
+        VISUAL_CUE.test(`${shape.name} ${shape.description} ${shape.text}`);
+      const largeGrayShape =
+        shape.kind === "text" &&
+        isGrayFill(shape.fillColor) &&
+        shape.bbox.width * shape.bbox.height >=
+          canvas.width * canvas.height * 0.08;
+      const isEditableText =
+        shape.kind === "text" &&
+        !visualInstruction &&
+        !largeGrayShape &&
+        !["pageNumber", "date"].includes(purpose) &&
+        Boolean(shape.text);
+      const visualPlaceholder =
+        (["image", "chart", "table"].includes(shape.kind) &&
+          VISUAL_CUE.test(`${shape.name} ${shape.description} ${shape.text}`)) ||
+        visualInstruction ||
+        largeGrayShape;
+      if (largeGrayShape && !visualInstruction) ambiguousGrayPlaceholder = true;
+      if (isEditableText || visualPlaceholder) {
+        const type = visualPlaceholder
+          ? ["chart", "table"].includes(shape.kind)
+            ? shape.kind
+            : "image"
+          : "text";
+        const semanticType =
+          visualInstruction && /icon|图标/i.test(`${shape.name} ${shape.text}`)
+            ? "icon"
+            : type;
+        slotSchema.push({
+          slotId: `slide-${record.slideNumber}-shape-${shape.id}`,
+          sourceShapeId: shape.id,
+          sourceElementName: shape.name,
+          type,
+          semanticType,
+          purpose: visualPlaceholder ? type : purpose,
+          required: purpose === "title" || purpose === "body" || visualPlaceholder,
+          maxTextUnits:
+            type === "text"
+              ? Math.max(
+                  textUnits(shape.text) * 1.35,
+                  (shape.bbox.width / Math.max(8, shape.fontSize || 14)) * 12,
+                )
+              : undefined,
+          sourceText: shape.text || undefined,
+          bbox: shape.bbox,
+        });
+      }
+      if (visualPlaceholder) {
+        assetRequirements.push({
+          type:
+            visualInstruction && /icon|图标/i.test(`${shape.name} ${shape.text}`)
+              ? "icon"
+              : ["chart", "table"].includes(shape.kind)
+                ? shape.kind
+                : "image",
+          slotId: `slide-${record.slideNumber}-shape-${shape.id}`,
+          required: true,
+        });
+      }
+      if (shape.text) textCorpus.push(shape.text);
+    }
+    const hasTitle = slotSchema.some((slot) => slot.purpose === "title");
+    const hasBody = slotSchema.some((slot) => slot.purpose === "body");
+    const safe =
+      hasTitle &&
+      !ambiguousGrayPlaceholder &&
+      (hasBody ||
+        ["cover", "closing", "divider", "agenda"].includes(
+          classification.layoutFamily,
+        ));
+    slides.push({
+      sourceSlide: record.slideNumber,
+      sourcePart: record.partName,
+      layoutFamily: classification.layoutFamily,
+      layoutVariant: `${classification.layoutFamily}-${slotSchema.length}`,
+      communicationFunctions: classification.communicationFunctions,
+      narrativeRoles: classification.narrativeRoles,
+      slotSchema,
+      assetRequirements,
+      contentRecipe: {
+        recommendedSourceUnits: {
+          min: ["cover", "closing", "divider"].includes(
+            classification.layoutFamily,
+          )
+            ? 0
+            : 1,
+          max: Math.max(
+            1,
+            slotSchema.filter((slot) => slot.type === "text").length - 1,
+          ),
+        },
+      },
+      safetyStatus: safe ? "automatic" : "review",
+      confidence: safe ? 0.86 : 0.58,
+      editability: "native-ooxml",
+      protectedElements: shapes
+        .filter(
+          (shape) =>
+            !slotSchema.some(
+              (slot) => String(slot.sourceShapeId) === String(shape.id),
+            ),
+        )
+        .map((shape) => ({ id: shape.id, name: shape.name, kind: shape.kind })),
+    });
+  }
+  const variantSelections = {};
+  for (const [role, family] of [
+    ["opening", "cover"],
+    ["closing", "closing"],
+  ]) {
+    const variants = slides.filter(
+      (slide) =>
+        slide.layoutFamily === family && slide.safetyStatus === "automatic",
+    );
+    if (variants.length > 1) {
+      variantSelections[role] = variants.map((slide) => slide.sourceSlide);
+      for (const slide of variants) {
+        slide.safetyStatus = "review";
+        slide.confidence = Math.min(Number(slide.confidence || 0.58), 0.68);
+      }
+    }
+  }
+  const automatic = slides.filter((slide) => slide.safetyStatus === "automatic");
+  const automaticFamilies = new Set(
+    automatic.map((slide) => slide.layoutFamily),
+  );
+  const capability = (families) => ({
+    safeCount: automatic.filter((slide) =>
+      families.includes(slide.layoutFamily),
+    ).length,
+  });
+  const familyCount = new Set(slides.map((slide) => slide.layoutFamily)).size;
+  const placeholderCount = slides.reduce(
+    (sum, slide) => sum + slide.assetRequirements.length,
+    0,
+  );
+  const templateKind =
+    placeholderCount > 0
+      ? "blank-template"
+      : slides.length >= 8 && familyCount >= 5
+        ? "layout-gallery"
+        : "filled-example";
+  const useCases = inferUseCases(textCorpus.join(" "));
+  const profile = {
+    schemaVersion: 3,
+    source: {
+      path: resolved,
+      sha256: await sha256File(resolved),
+      extension,
+    },
+    canvas,
+    templateKind,
+    templateKindConfidence: 0.82,
+    purposeProfile: {
+      primaryUseCases: useCases,
+      secondaryUseCases: ["general-report"],
+      incompatibleUseCases: [],
+      confidence: useCases[0] === "general-report" ? 0.66 : 0.82,
+    },
+    capabilities: {
+      cover: capability(["cover"]),
+      closing: capability(["closing"]),
+      analysis: capability(["analysis", "comparison", "table"]),
+      issue: capability(["analysis", "comparison"]),
+      counterargument: capability(["comparison", "analysis"]),
+      conclusion: capability(["closing", "analysis"]),
+      recommendation: capability(["closing", "analysis"]),
+      summary: capability(["analysis", "closing"]),
+      background: capability(["analysis", "image"]),
+      problem: capability(["analysis", "comparison"]),
+      solution: capability(["analysis", "comparison"]),
+      process: capability(["timeline"]),
+      comparison: capability(["comparison", "table"]),
+      chronology: capability(["timeline"]),
+      timeline: capability(["timeline"]),
+      data: capability(["chart", "table"]),
+      evidence: capability(["analysis", "image", "chart", "table"]),
+      imagery: capability(["image"]),
+      "image-evidence": capability(["image"]),
+      roadmap: capability(["agenda"]),
+      section: capability(["divider"]),
+    },
+    densityRange:
+      automatic.some(
+        (slide) =>
+          slide.slotSchema.filter((slot) => slot.type === "text").length >= 5,
+      )
+        ? "high"
+        : automatic.some(
+              (slide) =>
+                slide.slotSchema.filter((slot) => slot.type === "text").length >=
+                3,
+            )
+          ? "medium"
+          : "low",
+    visualBalance:
+      [...automaticFamilies].some((family) =>
+        ["image", "chart", "table"].includes(family),
+      )
+        ? "balanced"
+        : "text-led",
+    variantSelections,
+    slides,
+    reviewSummary: {
+      automaticSlides: automatic.map((slide) => slide.sourceSlide),
+      reviewSlides: slides
+        .filter((slide) => slide.safetyStatus === "review")
+        .map((slide) => slide.sourceSlide),
+      blockedSlides: [],
+    },
+  };
+  profile.profileFingerprint = fingerprint(profile);
+  profile.actionRequired =
+    profile.reviewSummary.reviewSlides.length ||
+    profile.purposeProfile.confidence < 0.75
+      ? {
+          type: "template-semantics",
+          slides: profile.reviewSummary.reviewSlides,
+          instructions: [
+            "Review every flagged slide at full size.",
+            "Confirm layoutFamily, communicationFunctions, narrativeRoles, slot purpose, asset requirements, protected elements, and safe editability.",
+            "When opening or closing variants are listed, approve exactly one variant for that role and block the alternatives so repeated runs do not choose by accident.",
+            "Do not authorize chart, diagram, icon, SmartArt, animation, or media edits unless the native object and slot are explicit.",
+          ],
+          variantSelections,
+        }
+      : null;
+  return profile;
+}