@sorane/core 0.2.0

package/src/diagrams/render-body-section.ts

@@ -0,0 +1,52 @@
+import type { TocEntry, RenderOptions } from "../render.ts";
+import { renderMarkdownDocument } from "../render.ts";
+import type { DiagramRenderMeta } from "./diagram-meta.ts";
+import { emptyDiagramMeta } from "./diagram-meta.ts";
+import { needsAsyncDiagramCompile } from "./needs-async-compile.ts";
+import {
+  renderMarkdownDocumentAsync,
+  type AsyncRenderOptions,
+} from "./render-async.ts";
+
+export interface BodySectionResult {
+  readonly html: string;
+  readonly diagrams: DiagramRenderMeta;
+  readonly outline: readonly TocEntry[];
+}
+
+export type BodySectionOptions = RenderOptions & AsyncRenderOptions;
+
+export function renderBodySection(
+  markdown: string,
+  opts?: BodySectionOptions,
+): BodySectionResult {
+  const rendered = renderMarkdownDocument(markdown, opts);
+  return {
+    html: rendered.html,
+    diagrams: rendered.diagrams ?? emptyDiagramMeta(),
+    outline: rendered.outline,
+  };
+}
+
+export async function renderBodySectionAsync(
+  markdown: string,
+  opts?: BodySectionOptions,
+): Promise<BodySectionResult> {
+  const rendered = await renderMarkdownDocumentAsync(markdown, opts);
+  return {
+    html: rendered.html,
+    diagrams: rendered.diagrams ?? emptyDiagramMeta(),
+    outline: rendered.outline,
+  };
+}
+
+/** ビルド時コンパイルが必要なら非同期、それ以外は同期。 */
+export async function renderBodySectionForConfig(
+  markdown: string,
+  opts?: BodySectionOptions,
+): Promise<BodySectionResult> {
+  if (needsAsyncDiagramCompile(opts?.diagrams)) {
+    return renderBodySectionAsync(markdown, opts);
+  }
+  return renderBodySection(markdown, opts);
+}

package/src/diagrams/validate-diagram-alt.ts

@@ -0,0 +1,56 @@
+import type { DiagramsConfig } from "../config.ts";
+import { isGraphvizLang } from "./compile-graphviz.ts";
+import { extractAltText } from "./parse-diagram-fence.ts";
+
+const FENCE_OPEN_RE = /^(`{3,}|~{3,})(\S*)\s*(.*)$/;
+
+function isDiagramLangActive(lang: string, config: DiagramsConfig): boolean {
+  if (config.enabled === false) return false;
+  if (lang === "mermaid") return config.mermaid?.mode !== "off";
+  if (lang === "d2") return config.d2?.enabled === true;
+  if (isGraphvizLang(lang)) return config.graphviz?.enabled === true;
+  return false;
+}
+
+/** Markdown 本文の図表フェンスで alt 欠落を検出する（warning のみ、ビルドは継続）。 */
+export function validateDiagramAltWarnings(
+  body: string,
+  config: DiagramsConfig,
+): readonly string[] {
+  const warnings: string[] = [];
+  const lines = body.split(/\r?\n/);
+  let i = 0;
+  while (i < lines.length) {
+    const open = FENCE_OPEN_RE.exec(lines[i]!);
+    if (open === null) {
+      i++;
+      continue;
+    }
+    const marker = open[1]!;
+    const lang = open[2] ?? "";
+    const meta = open[3] ?? "";
+    const close = marker[0]!;
+    const minLen = marker.length;
+    const block: string[] = [];
+    i++;
+    while (i < lines.length) {
+      const line = lines[i]!;
+      if (
+        line.length >= minLen &&
+        line.startsWith(close.repeat(minLen)) &&
+        (line.length === minLen || /^\s*$/.test(line.slice(minLen)))
+      ) {
+        break;
+      }
+      block.push(line);
+      i++;
+    }
+    i++;
+    if (!isDiagramLangActive(lang, config)) continue;
+    if (extractAltText(meta, block.join("\n"))) continue;
+    warnings.push(
+      `diagram (${lang}) has no alt text; add alt="..." to the fence info string or a %% alt: comment`,
+    );
+  }
+  return warnings;
+}

package/src/docs.ts

@@ -0,0 +1,257 @@
+import type { OkfConcept } from "@sorane/okf";
+import { dirname, relative } from "node:path";
+import type { DiagramsConfig, DocsNavSpec } from "./config.ts";
+import type { DiagramRenderMeta } from "./diagrams/diagram-meta.ts";
+import {
+  escapeHtml,
+  stripDuplicateTitleHeading,
+  type RenderedMarkdown,
+  renderMarkdownDocument,
+} from "./render.ts";
+import { needsAsyncDiagramCompile } from "./diagrams/needs-async-compile.ts";
+import {
+  renderMarkdownDocumentAsync,
+  type AsyncRenderOptions,
+} from "./diagrams/render-async.ts";
+import { siteLabels } from "./site-labels.ts";
+
+export interface DocsArticleRenderOpts extends AsyncRenderOptions {
+  readonly badgeHtml?: string;
+  readonly diagrams?: DiagramsConfig;
+}
+
+export interface DocsArticleResult {
+  readonly bodyHtml: string;
+  readonly diagrams: DiagramRenderMeta;
+}
+
+export interface ArticleNav {
+  readonly prev?: { href: string; title: string };
+  readonly next?: { href: string; title: string };
+}
+
+const SERIF_FONT_STYLES = new Set(["GJM", "serif", "mincho"]);
+
+function articleFontClass(concept: OkfConcept): string {
+  const font = concept.frontmatter.font;
+  if (typeof font !== "string") return "";
+  return SERIF_FONT_STYLES.has(font) ? " font-serif" : "";
+}
+
+function relLinkFrom(fromRel: string, toRel: string): string {
+  const from = fromRel.replace(/\\/g, "/");
+  const to = toRel.replace(/\\/g, "/");
+  const rel = relative(dirname(from), to).split("\\").join("/");
+  return rel.length > 0 ? rel : "./";
+}
+
+export interface DocsNavItem {
+  readonly href: string;
+  readonly title: string;
+}
+
+export function docsNavFor(
+  href: string,
+  items: readonly DocsNavItem[],
+): ArticleNav | undefined {
+  const i = items.findIndex((item) => item.href === href);
+  if (i < 0) return undefined;
+  const prev =
+    i > 0 ? { href: items[i - 1]!.href, title: items[i - 1]!.title } : undefined;
+  const next =
+    i < items.length - 1
+      ? { href: items[i + 1]!.href, title: items[i + 1]!.title }
+      : undefined;
+  if (!prev && !next) return undefined;
+  return { prev, next };
+}
+
+export function docsSidebarHtml(
+  items: readonly DocsNavItem[],
+  currentHref: string,
+  fromRel: string,
+): string {
+  if (items.length === 0) return "";
+  const links = items
+    .map((item) => {
+      const href = relLinkFrom(fromRel, item.href);
+      const current = item.href === currentHref ? ' aria-current="page"' : "";
+      return (
+        `<li class="docs-nav-item">` +
+        `<a href="${escapeHtml(href)}" class="docs-nav-link"${current}>${escapeHtml(item.title)}</a>` +
+        `</li>`
+      );
+    })
+    .join("\n");
+  return (
+    `<nav class="docs-sidebar-nav" aria-label="ドキュメント">\n` +
+    `<ul class="docs-nav-list">\n${links}\n</ul>\n` +
+    `</nav>\n`
+  );
+}
+
+function pageTocHtml(outline: RenderedMarkdown["outline"], lang: string): string {
+  const entries = outline.filter((e) => e.depth >= 2 && e.depth <= 4);
+  if (entries.length < 2) return "";
+  const label = siteLabels(lang).toc;
+  const items = entries
+    .map((e) => {
+      const cls = e.depth > 2 ? ` class="page-toc-depth-${e.depth}"` : "";
+      return (
+        `<li${cls}><a href="#${escapeHtml(e.id)}">${escapeHtml(e.text)}</a></li>`
+      );
+    })
+    .join("\n");
+  return (
+    `<nav class="page-toc" aria-label="${escapeHtml(label)}">\n` +
+    `<p class="page-toc-title">${escapeHtml(label)}</p>\n` +
+    `<ul class="page-toc-list">\n${items}\n</ul>\n` +
+    `</nav>\n`
+  );
+}
+
+function docsPagerHtml(nav: ArticleNav | undefined, lang: string): string {
+  if (!nav?.prev && !nav?.next) return "";
+  const labels = siteLabels(lang);
+  const prev = nav.prev
+    ? `<a class="docs-pager-card docs-pager-prev" href="${escapeHtml(nav.prev.href)}">` +
+      `<span class="docs-pager-label">${escapeHtml(labels.prevPage)}</span>` +
+      `<span class="docs-pager-title">${escapeHtml(nav.prev.title)}</span>` +
+      `</a>`
+    : `<span class="docs-pager-spacer" aria-hidden="true"></span>`;
+  const next = nav.next
+    ? `<a class="docs-pager-card docs-pager-next" href="${escapeHtml(nav.next.href)}">` +
+      `<span class="docs-pager-label">${escapeHtml(labels.nextPage)}</span>` +
+      `<span class="docs-pager-title">${escapeHtml(nav.next.title)}</span>` +
+      `</a>`
+    : `<span class="docs-pager-spacer" aria-hidden="true"></span>`;
+  return (
+    `<nav class="docs-pager" aria-label="${escapeHtml(labels.pageNav)}">\n` +
+    `${prev}\n${next}\n` +
+    `</nav>\n`
+  );
+}
+
+export function renderDocsArticleBody(
+  concept: OkfConcept,
+  rendered: RenderedMarkdown,
+  nav: ArticleNav | undefined,
+  lang: string,
+  opts?: DocsArticleRenderOpts,
+): string {
+  const badge = opts?.badgeHtml ?? "";
+  const header = `<header>\n<h1>${escapeHtml(concept.title)}</h1>\n${badge}</header>\n`;
+  const toc = pageTocHtml(rendered.outline, lang);
+  return (
+    `<article class="article-page docs-page${articleFontClass(concept)}">\n` +
+    `${header}\n` +
+    `${toc}` +
+    `<div class="article-body docs-content">\n${rendered.html}</div>\n` +
+    `${docsPagerHtml(nav, lang)}\n` +
+    `</article>\n`
+  );
+}
+
+export function renderDocsIndexBody(opts: {
+  readonly siteTitle: string;
+  readonly description?: string;
+  readonly introHtml?: string;
+  readonly docsNav: readonly DocsNavItem[];
+  readonly profileUrl?: string;
+  readonly githubUrl?: string;
+  readonly lang?: string;
+}): string {
+  const labels = siteLabels(opts.lang ?? "ja");
+  const links = [
+    opts.profileUrl
+      ? `<a href="${escapeHtml(opts.profileUrl)}" class="blog-profile-link">${escapeHtml(labels.profile)}</a>`
+      : "",
+    opts.githubUrl
+      ? `<a href="${escapeHtml(opts.githubUrl)}" class="blog-profile-link">${escapeHtml(labels.github)}</a>`
+      : "",
+  ]
+    .filter(Boolean)
+    .join(" ");
+  const profile = links ? links : "";
+  const intro = opts.introHtml ? `<div class="docs-intro">${opts.introHtml}</div>` : "";
+  const items = opts.docsNav
+    .map(
+      (item) =>
+        `<li class="docs-index-item">` +
+        `<a href="${escapeHtml(item.href)}" class="docs-index-link">${escapeHtml(item.title)}</a>` +
+        `</li>`,
+    )
+    .join("\n");
+  const navSection =
+    items.length > 0
+      ? `<section class="docs-index-nav">\n` +
+        `<h2>${escapeHtml(labels.documentation)}</h2>\n` +
+        `<ul class="docs-index-list">\n${items}\n</ul>\n` +
+        `</section>\n`
+      : "";
+  return (
+    `<div class="docs-index">\n` +
+    `<header class="docs-index-header">\n` +
+    `<h1>${escapeHtml(opts.siteTitle)}</h1>\n` +
+    (opts.description ? `<p class="blog-lead">${escapeHtml(opts.description)}</p>\n` : "") +
+    (profile ? `<div class="blog-profile">${profile}</div>\n` : "") +
+    `${intro}` +
+    `</header>\n` +
+    `${navSection}` +
+    `</div>\n`
+  );
+}
+
+export function resolveDocsNav(
+  nav: readonly DocsNavSpec[] | undefined,
+  titleByHref: ReadonlyMap<string, string>,
+): DocsNavItem[] {
+  if (!nav || nav.length === 0) return [];
+  return nav.map((spec) => {
+    const href = typeof spec === "string" ? spec : spec.href;
+    const title =
+      (typeof spec === "object" && spec.title) ||
+      titleByHref.get(href) ||
+      href.replace(/\.html$/i, "");
+    return { href, title };
+  });
+}
+
+export function renderDocsArticleFromConceptWithMeta(
+  concept: OkfConcept,
+  nav: ArticleNav | undefined,
+  lang: string,
+  opts?: DocsArticleRenderOpts,
+): DocsArticleResult {
+  const body = stripDuplicateTitleHeading(concept.body, concept.title);
+  const rendered = renderMarkdownDocument(body, opts);
+  return {
+    bodyHtml: renderDocsArticleBody(concept, rendered, nav, lang, opts),
+    diagrams: rendered.diagrams ?? { mermaid: 0, d2: 0, graphviz: 0 },
+  };
+}
+
+export async function renderDocsArticleFromConceptWithMetaForConfig(
+  concept: OkfConcept,
+  nav: ArticleNav | undefined,
+  lang: string,
+  opts?: DocsArticleRenderOpts,
+): Promise<DocsArticleResult> {
+  const body = stripDuplicateTitleHeading(concept.body, concept.title);
+  const rendered = needsAsyncDiagramCompile(opts?.diagrams)
+    ? await renderMarkdownDocumentAsync(body, opts)
+    : renderMarkdownDocument(body, opts);
+  return {
+    bodyHtml: renderDocsArticleBody(concept, rendered, nav, lang, opts),
+    diagrams: rendered.diagrams ?? { mermaid: 0, d2: 0, graphviz: 0 },
+  };
+}
+
+export function renderDocsArticleFromConcept(
+  concept: OkfConcept,
+  nav: ArticleNav | undefined,
+  lang: string,
+  opts?: DocsArticleRenderOpts,
+): string {
+  return renderDocsArticleFromConceptWithMeta(concept, nav, lang, opts).bodyHtml;
+}

package/src/emit-page.ts

@@ -0,0 +1,87 @@
+import { writeFileSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import type { ParsedConcept } from "@sorane/okf";
+import { conceptToOkfMarkdown } from "@sorane/okf";
+import { buildPage } from "./ssg.ts";
+import type { SoraneConfig } from "./config.ts";
+import { resolveOgImageUrl } from "./og-meta.ts";
+import { extractDescription } from "./ssg.ts";
+
+function pageOgImage(
+  frontmatter: Record<string, unknown>,
+  siteOgImage: string | undefined,
+  baseUrl: string,
+): string | undefined {
+  const raw =
+    typeof frontmatter.og_image === "string"
+      ? frontmatter.og_image
+      : typeof frontmatter.ogImage === "string"
+        ? frontmatter.ogImage
+        : siteOgImage;
+  return resolveOgImageUrl(baseUrl, raw);
+}
+
+export interface EmitPageOptions {
+  readonly cwd: string;
+  readonly config: SoraneConfig;
+  readonly outDir: string;
+  readonly outRel: string;
+  readonly concept: ParsedConcept["concept"];
+  readonly bodyHtml: string;
+  readonly baseUrl: string;
+  readonly fontCss?: string;
+  readonly extraHead?: string[];
+  readonly isIndex?: boolean;
+  readonly showArchiveNav?: boolean;
+  readonly searchPath?: string;
+  readonly pageKind?: "website" | "article";
+  readonly docsLayout?: boolean;
+  readonly docsSidebarHtml?: string;
+  readonly headerSearchHtml?: string;
+}
+
+export function emitPage(opts: EmitPageOptions): { mdOutRel: string; canonicalUrl?: string } {
+  const outAbs = join(opts.outDir, opts.outRel);
+  mkdirSync(dirname(outAbs), { recursive: true });
+
+  const depth = opts.outRel.replace(/\\/g, "/").split("/").length - 1;
+  const rootPrefix = depth > 0 ? "../".repeat(depth) : "./";
+
+  const description =
+    opts.concept.description ??
+    extractDescription(opts.concept.body) ??
+    (opts.isIndex ? opts.config.site.description : undefined);
+  const canonicalUrl =
+    opts.baseUrl.length > 0 ? `${opts.baseUrl.replace(/\/$/, "")}/${opts.outRel}` : undefined;
+
+  const mdOutRel = opts.outRel.replace(/\.html$/, ".md");
+  writeFileSync(join(opts.outDir, mdOutRel), conceptToOkfMarkdown(opts.concept), "utf8");
+
+  const extraHead = [
+    ...(opts.extraHead ?? []),
+    ...(opts.fontCss ? [opts.fontCss] : []),
+  ];
+
+  const html = buildPage({
+    title: opts.concept.title,
+    siteTitle: opts.config.site.title,
+    bodyHtml: opts.bodyHtml,
+    rootPrefix,
+    description,
+    canonicalUrl,
+    lang: opts.config.site.lang,
+    feedPath: "feed.xml",
+    showArchiveNav: opts.showArchiveNav,
+    searchPath: opts.searchPath,
+    pageKind: opts.pageKind ?? (opts.isIndex ? "website" : "article"),
+    machineSources: [{ href: mdOutRel, type: "text/markdown" }],
+    extraHead: extraHead.length > 0 ? extraHead : undefined,
+    docsLayout: opts.docsLayout,
+    docsSidebarHtml: opts.docsSidebarHtml,
+    headerSearchHtml: opts.headerSearchHtml,
+    ogImageUrl: pageOgImage(opts.concept.frontmatter, opts.config.site.og_image, opts.baseUrl),
+  });
+  writeFileSync(outAbs, html, "utf8");
+
+  return { mdOutRel, canonicalUrl };
+}

package/src/index.ts

@@ -0,0 +1,49 @@
+export { runBuild, type BuildOptions, type BuildResult } from "./build.ts";
+export { mergeConfig, DEFAULT_CONFIG, resolvePermalink, type SoraneConfig } from "./config.ts";
+export { migrateToOkf, parseBumpProfileArg, type MigrateToOkfOptions } from "./migrate.ts";
+export { validateHeadingWarnings } from "./validate-heading-structure.ts";
+export { processStaticAssets, type StaticAssetPassResult } from "./static-assets.ts";
+export {
+  signRasterWithC2pa,
+  probeC2paManifest,
+  c2patoolAvailable,
+  resolveC2paCredentials,
+  isC2paRasterPath,
+} from "./c2pa-pass.ts";
+export {
+  loadAssetProvenance,
+  resolveC2paCreateIntent,
+  type AssetProvenanceEntry,
+} from "./asset-provenance.ts";
+export {
+  buildPage,
+  extractDescription,
+  renderArticleBody,
+  renderIndexBody,
+  rootPrefixFromRel,
+  relLinkFrom,
+  buildSearchMount,
+  buildSearchHead,
+  isSearchView,
+  sanitizeListDescription,
+  articleFontClass,
+  renderFeaturedExcerpt,
+  buildWebSiteJsonLd,
+} from "./ssg.ts";
+export { siteLabels, type SiteLabels } from "./site-labels.ts";
+export type { FeaturedMode } from "./config.ts";
+export {
+  renderMarkdown,
+  rewriteLinks,
+  escapeHtml,
+  stripDuplicateTitleHeading,
+} from "./render.ts";
+export { buildCatalogJsonLd, type CatalogEntry } from "./catalog.ts";
+export {
+  buildRobotsTxt,
+  buildSitemapXml,
+  buildLlmsTxt,
+  type SiteEntry,
+} from "./site-meta.ts";
+export { validateDiagramAltWarnings } from "./diagrams/validate-diagram-alt.ts";
+export { resolveOgImageUrl, ogLocaleFromLang } from "./og-meta.ts";

package/src/iptc-xmp-pass.ts

@@ -0,0 +1,94 @@
+import { spawnSync } from "node:child_process";
+import { resolveDigitalSourceType } from "@sorane/okf";
+import type { AssetProvenanceEntry } from "./asset-provenance.ts";
+
+const IMAGE_METADATA_RE = /\.(jpe?g|png|webp)$/i;
+
+export function isImageMetadataPath(filePath: string): boolean {
+  return IMAGE_METADATA_RE.test(filePath);
+}
+
+export function hasImageMetadataFields(entry: AssetProvenanceEntry | undefined): boolean {
+  if (!entry) return false;
+  return Boolean(
+    entry.digitalSourceType ||
+      entry.aiDisclosureNote ||
+      (entry.aiSystems && entry.aiSystems.length > 0),
+  );
+}
+
+/** ExifTool 引数を組み立てる（in-place 書き込み用）。 */
+export function buildIptcXmpExiftoolArgs(entry: AssetProvenanceEntry): string[] {
+  const args: string[] = ["-overwrite_original"];
+
+  if (entry.digitalSourceType) {
+    const resolved = resolveDigitalSourceType(entry.digitalSourceType);
+    if (resolved) {
+      args.push(`-XMP-iptcExt:DigitalSourceType=${resolved.uri}`);
+    }
+  }
+
+  if (entry.aiDisclosureNote) {
+    args.push(`-XMP-iptcExt:AIPromptInformation=${entry.aiDisclosureNote}`);
+  }
+
+  if (entry.aiSystems && entry.aiSystems.length > 0) {
+    const first = entry.aiSystems[0]!;
+    const label = first.provider ? `${first.name} (${first.provider})` : first.name;
+    args.push(`-XMP-iptcExt:AISystemUsed=${label}`);
+    if (first.version) {
+      args.push(`-XMP-iptcExt:AISystemVersionUsed=${first.version}`);
+    }
+  }
+
+  return args;
+}
+
+/** ExifTool で IPTC Extension XMP を画像に埋め込む。 */
+export function embedIptcXmp(
+  filePath: string,
+  entry: AssetProvenanceEntry,
+  opts: { readonly binary?: string } = {},
+): { readonly ok: boolean; readonly message?: string } {
+  const args = buildIptcXmpExiftoolArgs(entry);
+  if (args.length <= 1) {
+    return { ok: false, message: "no IPTC XMP fields to write" };
+  }
+
+  const binary = opts.binary ?? "exiftool";
+  const result = spawnSync(binary, [...args, filePath], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+
+  if (result.status !== 0) {
+    const msg = (result.stderr || result.stdout || "").trim();
+    return { ok: false, message: msg.length > 0 ? msg : `exiftool exited ${result.status}` };
+  }
+  return { ok: true };
+}
+
+export function exiftoolAvailable(binary = "exiftool"): boolean {
+  const result = spawnSync(binary, ["-ver"], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  return result.status === 0;
+}
+
+/** 出力画像に期待する XMP が付いているか簡易確認。 */
+export function probeIptcXmp(
+  filePath: string,
+  expectedUri: string | undefined,
+  binary = "exiftool",
+): boolean {
+  const result = spawnSync(
+    binary,
+    ["-s", "-s", "-s", "-G1", "-XMP-iptcExt:DigitalSourceType", filePath],
+    { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] },
+  );
+  if (result.status !== 0) return false;
+  const value = (result.stdout || "").trim();
+  if (!expectedUri) return value.length > 0;
+  return value === expectedUri || value.endsWith(expectedUri.split("/").pop() ?? "");
+}