@sorane/core 0.2.0

package/src/markdown-image-refs.ts

@@ -0,0 +1,135 @@
+import { existsSync } from "node:fs";
+import { dirname, join, normalize, relative, resolve } from "node:path";
+import { isImageMetadataPath } from "./iptc-xmp-pass.ts";
+
+const MARKDOWN_IMAGE_RE = /!\[([^\]]*)]\(([^)]+)\)/g;
+
+export type InlineImageKind = "static" | "content";
+
+export interface MarkdownImageRef {
+  readonly markdownPath: string;
+  readonly sourceMdRel: string;
+  readonly srcAbs: string;
+  readonly kind: InlineImageKind;
+  /** サイトルートからの公開パス（例: `static/hero.jpg`, `article/fig.png`） */
+  readonly publicPath: string;
+  readonly outRel: string;
+  readonly alt: string;
+}
+
+function isExternalImageRef(target: string): boolean {
+  return /^[a-z][a-z0-9+.-]*:/i.test(target) || target.startsWith("//");
+}
+
+function imageTargetPath(raw: string): string {
+  const trimmed = raw.trim();
+  const unquoted = trimmed.replace(/^<|>$/g, "");
+  const pathOnly = unquoted.split(/\s+/)[0] ?? "";
+  return pathOnly.replace(/\\/g, "/");
+}
+
+function publicPathForHtml(outHtmlRel: string, markdownPath: string): string {
+  const htmlDir = dirname(outHtmlRel.replace(/\\/g, "/"));
+  const joined = htmlDir.length > 0 ? join(htmlDir, markdownPath) : markdownPath;
+  return normalize(joined).replace(/\\/g, "/");
+}
+
+/** Markdown 本文からローカル画像参照を抽出する。 */
+export function extractMarkdownImagePaths(markdown: string): Array<{ alt: string; path: string }> {
+  const out: Array<{ alt: string; path: string }> = [];
+  for (const match of markdown.matchAll(MARKDOWN_IMAGE_RE)) {
+    const path = imageTargetPath(match[2] ?? "");
+    if (path.length === 0 || isExternalImageRef(path)) continue;
+    out.push({ alt: (match[1] ?? "").trim(), path });
+  }
+  return out;
+}
+
+/** 単一の Markdown 画像参照を解決する（存在しない・非ラスタは null）。 */
+export function resolveMarkdownImageRef(opts: {
+  readonly markdownPath: string;
+  readonly sourceMdRel: string;
+  readonly outHtmlRel: string;
+  readonly contentDir: string;
+  readonly cwd: string;
+  readonly staticDirName: string;
+  readonly alt?: string;
+}): MarkdownImageRef | null {
+  const markdownPath = opts.markdownPath.replace(/\\/g, "/");
+  if (!isImageMetadataPath(markdownPath)) return null;
+
+  const sourceDir = dirname(opts.sourceMdRel.replace(/\\/g, "/"));
+  const contentResolved = normalize(
+    resolve(opts.contentDir, sourceDir === "." ? "" : sourceDir, markdownPath),
+  );
+  const staticRoot = resolve(opts.cwd, opts.staticDirName);
+
+  if (contentResolved.startsWith(staticRoot) && existsSync(contentResolved)) {
+    const staticRel = relative(staticRoot, contentResolved).replace(/\\/g, "/");
+    const publicPath = `${opts.staticDirName}/${staticRel}`;
+    return {
+      markdownPath,
+      sourceMdRel: opts.sourceMdRel,
+      srcAbs: contentResolved,
+      kind: "static",
+      publicPath,
+      outRel: join(opts.staticDirName, staticRel).replace(/\\/g, "/"),
+      alt: opts.alt ?? "",
+    };
+  }
+
+  if (
+    contentResolved.startsWith(opts.contentDir) &&
+    existsSync(contentResolved) &&
+    isImageMetadataPath(contentResolved)
+  ) {
+    const publicPath = publicPathForHtml(opts.outHtmlRel, markdownPath);
+    return {
+      markdownPath,
+      sourceMdRel: opts.sourceMdRel,
+      srcAbs: contentResolved,
+      kind: "content",
+      publicPath,
+      outRel: publicPath,
+      alt: opts.alt ?? "",
+    };
+  }
+
+  return null;
+}
+
+export function collectMarkdownImageRefs(opts: {
+  readonly body: string;
+  readonly sourceMdRel: string;
+  readonly outHtmlRel: string;
+  readonly contentDir: string;
+  readonly cwd: string;
+  readonly staticDirName: string;
+}): MarkdownImageRef[] {
+  const out: MarkdownImageRef[] = [];
+  for (const { alt, path } of extractMarkdownImagePaths(opts.body)) {
+    const resolved = resolveMarkdownImageRef({
+      markdownPath: path,
+      sourceMdRel: opts.sourceMdRel,
+      outHtmlRel: opts.outHtmlRel,
+      contentDir: opts.contentDir,
+      cwd: opts.cwd,
+      staticDirName: opts.staticDirName,
+      alt,
+    });
+    if (resolved) out.push(resolved);
+  }
+  return out;
+}
+
+/** `srcAbs` で重複排除したインライン画像一覧。 */
+export function dedupeMarkdownImageRefs(refs: readonly MarkdownImageRef[]): MarkdownImageRef[] {
+  const seen = new Set<string>();
+  const out: MarkdownImageRef[] = [];
+  for (const ref of refs) {
+    if (seen.has(ref.srcAbs)) continue;
+    seen.add(ref.srcAbs);
+    out.push(ref);
+  }
+  return out;
+}

package/src/migrate.ts

@@ -0,0 +1,60 @@
+import {
+  conceptToOkfMarkdown,
+  extract,
+  normalizeConcept,
+  parseYaml,
+} from "@sorane/okf";
+
+function slugFromPath(filePath: string): string {
+  const base = filePath.replace(/\\/g, "/").split("/").pop() ?? filePath;
+  return base.replace(/\.md$/i, "");
+}
+
+const SUPPORTED_BUMP_PROFILES = new Set(["0.1", "0.2"]);
+
+export interface MigrateToOkfOptions {
+  readonly bumpProfile?: string;
+}
+
+/** 旧 frontmatter を OKF native markdown に変換する。 */
+export function migrateToOkf(
+  source: string,
+  filePath: string,
+  opts?: MigrateToOkfOptions,
+): string {
+  const { frontmatter, body } = extract(source);
+  const raw =
+    frontmatter !== null
+      ? ((parseYaml(frontmatter) as Record<string, unknown>) ?? {})
+      : {};
+  const concept = normalizeConcept(raw, body, slugFromPath(filePath));
+
+  const bumpedProfile =
+    opts?.bumpProfile !== undefined
+      ? `sorane-okf/${opts.bumpProfile}`
+      : undefined;
+  const defaultProfile = bumpedProfile ?? concept.profile ?? "sorane-okf/0.1";
+
+  const migrated: typeof concept = {
+    ...concept,
+    type: concept.type || "article",
+    profile: defaultProfile,
+    frontmatter: Object.fromEntries(
+      Object.entries(concept.frontmatter).filter(
+        ([k]) => !["layout", "kind", "date", "publishedAt"].includes(k),
+      ),
+    ),
+  };
+
+  return conceptToOkfMarkdown(migrated);
+}
+
+export function parseBumpProfileArg(argv: readonly string[]): string | undefined {
+  const i = argv.indexOf("--bump-profile");
+  if (i < 0 || i + 1 >= argv.length) return undefined;
+  const version = argv[i + 1]!.trim();
+  if (!SUPPORTED_BUMP_PROFILES.has(version)) {
+    throw new Error(`unsupported --bump-profile version: ${version} (supported: 0.1, 0.2)`);
+  }
+  return version;
+}

package/src/not-found.ts

@@ -0,0 +1,64 @@
+import type { OkfConcept } from "@sorane/okf";
+import { escapeHtml, stripDuplicateTitleHeading } from "./render.ts";
+import { siteLabels } from "./site-labels.ts";
+
+export const NOT_FOUND_SLUG = "404";
+
+export function isNotFoundSource(relPath: string): boolean {
+  const base = relPath.replace(/\\/g, "/").split("/").pop() ?? relPath;
+  return base.replace(/\.md$/i, "") === NOT_FOUND_SLUG;
+}
+
+export interface NotFoundLabels {
+  readonly heading: string;
+  readonly message: string;
+  readonly messageAlt?: string;
+  readonly backToHome: string;
+}
+
+export function notFoundLabels(lang: string): NotFoundLabels {
+  if (lang.startsWith("ja")) {
+    return {
+      heading: "404",
+      message: "指定されたページは存在しません。",
+      messageAlt: "Page not found.",
+      backToHome: "トップページへ",
+    };
+  }
+  return {
+    heading: "404",
+    message: "Page not found.",
+    backToHome: "Back to home",
+  };
+}
+
+export function renderDefaultNotFoundBody(lang: string, homeHref = "./index.html"): string {
+  const labels = notFoundLabels(lang);
+  const alt =
+    labels.messageAlt !== undefined
+      ? `<p lang="en">${escapeHtml(labels.messageAlt)}</p>\n`
+      : "";
+  return (
+    `<article class="article-page not-found-page">\n` +
+    `<header>\n<h1>${escapeHtml(labels.heading)}</h1>\n</header>\n` +
+    `<div class="article-body">\n` +
+    `<p>${escapeHtml(labels.message)}</p>\n` +
+    `${alt}` +
+    `<p><a href="${escapeHtml(homeHref)}">${escapeHtml(labels.backToHome)}</a></p>\n` +
+    `</div>\n</article>`
+  );
+}
+
+export function renderCustomNotFoundBody(concept: OkfConcept, bodyHtml: string): string {
+  const title = concept.title.trim().length > 0 ? concept.title : notFoundLabels("ja").heading;
+  return (
+    `<article class="article-page not-found-page">\n` +
+    `<header>\n<h1>${escapeHtml(title)}</h1>\n</header>\n` +
+    `<div class="article-body">\n${bodyHtml}\n</div>\n` +
+    `</article>`
+  );
+}
+
+export function notFoundBodySource(concept: OkfConcept): string {
+  return stripDuplicateTitleHeading(concept.body, concept.title);
+}

package/src/og-meta.ts

@@ -0,0 +1,18 @@
+/** site.og_image / frontmatter og_image を絶対 URL に解決する。base_url 無しの相対パスは undefined。 */
+export function resolveOgImageUrl(baseUrl: string, image?: string): string | undefined {
+  if (image === undefined || image.trim().length === 0) return undefined;
+  const trimmed = image.trim();
+  if (/^https?:\/\//i.test(trimmed)) return trimmed;
+  const base = baseUrl.replace(/\/$/, "");
+  if (base.length === 0) return undefined;
+  if (trimmed.startsWith("/")) return `${base}${trimmed}`;
+  return `${base}/${trimmed}`;
+}
+
+/** BCP 47 lang を Open Graph locale にざっくり変換する。 */
+export function ogLocaleFromLang(lang: string): string {
+  const primary = lang.split("-")[0]?.toLowerCase() ?? "ja";
+  if (primary === "ja") return "ja_JP";
+  if (primary === "en") return "en_US";
+  return lang.replace("-", "_");
+}

package/src/render.ts

@@ -0,0 +1,233 @@
+import type { Schema } from "hast-util-sanitize";
+import type { Root as HastRoot } from "hast";
+import rehypeAutolinkHeadings from "rehype-autolink-headings";
+import rehypeRaw from "rehype-raw";
+import rehypeSanitize, { defaultSchema } from "rehype-sanitize";
+import { SlugLedger } from "@sorane/search";
+import type { DiagramsConfig } from "./config.ts";
+import { DEFAULT_DIAGRAMS_CONFIG } from "./config.ts";
+import {
+  countDiagramsForConfig,
+  type DiagramRenderMeta,
+} from "./diagrams/diagram-meta.ts";
+import { remarkDiagramFences } from "./diagrams/parse-diagram-fence.ts";
+import { rehypeDiagramPre } from "./diagrams/rehype-diagram-pre.ts";
+import rehypeStringify from "rehype-stringify";
+import type { Root as MdastRoot } from "mdast";
+import remarkGfm from "remark-gfm";
+import remarkParse from "remark-parse";
+import remarkRehype from "remark-rehype";
+import { unified } from "unified";
+import { visit } from "unist-util-visit";
+
+const schemaAttributes = defaultSchema.attributes ?? {};
+
+/** はてな移行記事の HTML を許可しつつ script 等は落とす。 */
+export const sanitizeSchema: Schema = {
+  ...defaultSchema,
+  clobberPrefix: "",
+  attributes: {
+    ...schemaAttributes,
+    a: [
+      ...(schemaAttributes.a ?? []).filter(
+        (entry) => (typeof entry === "string" ? entry : entry[0]) !== "className",
+      ),
+      "title",
+      ["className", "data-footnote-backref", "keyword", "okeyword", "heading-anchor"],
+    ],
+    h1: [...(schemaAttributes.h1 ?? []), "id"],
+    h2: [...(schemaAttributes.h2 ?? []), "id"],
+    h3: [...(schemaAttributes.h3 ?? []), "id"],
+    h4: [...(schemaAttributes.h4 ?? []), "id"],
+    h5: [...(schemaAttributes.h5 ?? []), "id"],
+    h6: [...(schemaAttributes.h6 ?? []), "id"],
+    blockquote: [
+      ...(schemaAttributes.blockquote ?? []),
+      ["className", "twitter-tweet"],
+      "dataLang",
+      "dataDnt",
+      "dataConversation",
+    ],
+    span: [
+      ...(schemaAttributes.span ?? []),
+      ["style", /^font-style:\s*italic;?$/i],
+    ],
+    figure: [
+      [
+        "className",
+        "figure-image",
+        "figure-image-fotolife",
+        "mceNonEditable",
+        "diagram",
+        "diagram--d2",
+        "diagram--mermaid",
+        "diagram--graphviz",
+      ],
+      "role",
+    ],
+    figcaption: [],
+    iframe: ["src", "width", "height", "frameBorder", "allowFullScreen"],
+    embed: ["src", "type", "width", "height"],
+    object: ["width", "height"],
+    param: ["name", "value"],
+    img: [...(schemaAttributes.img ?? []), "title", "loading", "decoding"],
+    pre: [...(schemaAttributes.pre ?? []), "dataSoraneAlt"],
+  },
+  tagNames: [
+    ...(defaultSchema.tagNames ?? []),
+    "center",
+    "embed",
+    "figcaption",
+    "figure",
+    "iframe",
+    "object",
+    "param",
+  ],
+};
+
+export interface TocEntry {
+  readonly depth: number;
+  readonly id: string;
+  readonly text: string;
+}
+
+export interface RenderOptions {
+  readonly diagrams?: DiagramsConfig;
+}
+
+export interface RenderedMarkdown {
+  readonly html: string;
+  readonly outline: readonly TocEntry[];
+  readonly diagrams?: DiagramRenderMeta;
+}
+
+export type { DiagramRenderMeta };
+
+function hastToPlainText(node: { type?: string; value?: string; children?: unknown[] }): string {
+  if (node.type === "text" && typeof node.value === "string") return node.value;
+  if (!node.children) return "";
+  return node.children
+    .map((child) => hastToPlainText(child as { type?: string; value?: string; children?: unknown[] }))
+    .join("");
+}
+
+function rehypeHeadingIds() {
+  const ledger = new SlugLedger();
+  return (tree: HastRoot) => {
+    visit(tree, "element", (node) => {
+      const m = /^h([1-6])$/.exec(node.tagName);
+      if (!m) return;
+      const text = hastToPlainText(node).trim();
+      if (!text) return;
+      node.properties ??= {};
+      node.properties.id = ledger.next(text);
+    });
+  };
+}
+
+function rehypeCollectOutline(outline: TocEntry[]) {
+  return () => (tree: HastRoot) => {
+    visit(tree, "element", (node) => {
+      const m = /^h([2-4])$/.exec(node.tagName);
+      if (!m) return;
+      const id = node.properties?.id;
+      if (typeof id !== "string" || id.length === 0) return;
+      const text = hastToPlainText(node)
+        .replace(/\s*#\s*$/, "")
+        .trim();
+      if (!text) return;
+      outline.push({ depth: Number(m[1]), id, text });
+    });
+  };
+}
+
+function markdownPipeline(
+  outline: TocEntry[],
+  diagrams: DiagramRenderMeta,
+  diagramConfig: DiagramsConfig,
+) {
+  return unified()
+    .use(remarkParse)
+    .use(remarkGfm)
+    .use(remarkDiagramFences(diagramConfig))
+    .use(() => (tree: MdastRoot) => {
+      Object.assign(diagrams, countDiagramsForConfig(tree, diagramConfig));
+    })
+    .use(remarkRehype, { allowDangerousHtml: true })
+    .use(rehypeRaw)
+    .use(rehypeDiagramPre)
+    .use(rehypeHeadingIds)
+    .use(rehypeAutolinkHeadings, {
+      behavior: "append",
+      properties: {
+        className: ["heading-anchor"],
+        ariaHidden: "true",
+        tabIndex: -1,
+      },
+      content: { type: "text", value: "#" },
+    })
+    .use(rehypeCollectOutline(outline))
+    .use(rehypeSanitize, sanitizeSchema)
+    .use(rehypeStringify);
+}
+
+/** 相対 .md リンクを .html に書き換える。 */
+export function rewriteLinks(markdown: string): string {
+  return markdown.replace(
+    /\]\(([^)]+)\)/g,
+    (full, target: string) => {
+      const trimmed = target.trim();
+      if (/^[a-z][a-z0-9+.-]*:/i.test(trimmed)) return full;
+      if (trimmed.startsWith("#")) return full;
+      const m = trimmed.match(/^([^#]*?)\.md(#.*)?$/i);
+      if (!m) return full;
+      return `](${m[1]}.html${m[2] ?? ""})`;
+    },
+  );
+}
+
+/** ヘッダ h1 と重複する先頭 `# title` 行を除く。 */
+export function stripDuplicateTitleHeading(markdown: string, title: string): string {
+  const lines = markdown.split(/\r?\n/);
+  let i = 0;
+  while (i < lines.length && lines[i].trim() === "") i++;
+  if (i >= lines.length) return markdown;
+  const m = lines[i].match(/^#\s+(.+)$/);
+  if (!m || m[1].trim() !== title.trim()) return markdown;
+  const rest = [...lines.slice(0, i), ...lines.slice(i + 1)];
+  if (rest[i]?.trim() === "") rest.splice(i, 1);
+  return rest.join("\n");
+}
+
+/** Markdown 本文をサニタイズ済み HTML と見出し outline に変換する。 */
+export function renderMarkdownDocument(
+  markdown: string,
+  opts?: RenderOptions,
+): RenderedMarkdown {
+  const diagramConfig = opts?.diagrams ?? DEFAULT_DIAGRAMS_CONFIG;
+  const outline: TocEntry[] = [];
+  const diagrams: DiagramRenderMeta = { mermaid: 0, d2: 0, graphviz: 0 };
+  const html = markdownPipeline(outline, diagrams, diagramConfig)
+    .processSync(rewriteLinks(markdown))
+    .toString()
+    .replace(/\r\n?/g, "\n")
+    .trimEnd();
+  return {
+    html: html.length > 0 ? `${html}\n` : "",
+    outline,
+    diagrams,
+  };
+}
+
+/** Markdown 本文をサニタイズ済み HTML に変換する。 */
+export function renderMarkdown(markdown: string, opts?: RenderOptions): string {
+  return renderMarkdownDocument(markdown, opts).html;
+}
+
+export function escapeHtml(text: string): string {
+  return text
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}

package/src/site-labels.ts

@@ -0,0 +1,97 @@
+export interface SiteLabels {
+  readonly archive: string;
+  readonly search: string;
+  readonly feed: string;
+  readonly profile: string;
+  readonly github: string;
+  readonly readMore: string;
+  readonly pastArticles: string;
+  readonly moreArticles: string;
+  readonly yearArchive: string;
+  readonly updated: string;
+  readonly toc: string;
+  readonly documentation: string;
+  readonly prevPage: string;
+  readonly nextPage: string;
+  readonly pageNav: string;
+  readonly skipToContent: string;
+  readonly docsMenu: string;
+  readonly aiDisclosureAria: string;
+  readonly aiPolicyLink: string;
+}
+
+const JA: SiteLabels = {
+  archive: "アーカイブ",
+  search: "検索",
+  feed: "フィード",
+  profile: "プロフィール",
+  github: "GitHub",
+  readMore: "続きを読む →",
+  pastArticles: "過去の記事",
+  moreArticles: "さらに読む →",
+  yearArchive: "年別に探す",
+  updated: "更",
+  toc: "目次",
+  documentation: "ドキュメント",
+  prevPage: "前へ",
+  nextPage: "次へ",
+  pageNav: "ページ",
+  skipToContent: "本文へスキップ",
+  docsMenu: "ドキュメントメニュー",
+  aiDisclosureAria: "AI コンテンツ開示",
+  aiPolicyLink: "AI 開示ポリシー",
+};
+
+const EN: SiteLabels = {
+  archive: "Archive",
+  search: "Search",
+  feed: "Feed",
+  profile: "Profile",
+  github: "GitHub",
+  readMore: "Read more →",
+  pastArticles: "Archive",
+  moreArticles: "More articles →",
+  yearArchive: "Browse by year",
+  updated: "upd",
+  toc: "On this page",
+  documentation: "Documentation",
+  prevPage: "Previous",
+  nextPage: "Next",
+  pageNav: "Page",
+  skipToContent: "Skip to content",
+  docsMenu: "Documentation menu",
+  aiDisclosureAria: "AI content disclosure",
+  aiPolicyLink: "AI disclosure policy",
+};
+
+export function siteLabels(lang: string): SiteLabels {
+  return lang.startsWith("ja") ? JA : EN;
+}
+
+/** サイトヘッダ・フッタ等の固定 UI 文言（フォントサブセット用） */
+export function siteChromeText(lang: string, siteTitle: string, includeSearch = false): string {
+  const labels = siteLabels(lang);
+  const parts = [
+    siteTitle,
+    labels.archive,
+    labels.feed,
+    labels.profile,
+    labels.github,
+    labels.readMore,
+    labels.pastArticles,
+    labels.moreArticles,
+    labels.yearArchive,
+    labels.updated,
+    labels.toc,
+    labels.documentation,
+    labels.prevPage,
+    labels.nextPage,
+    labels.skipToContent,
+    labels.docsMenu,
+    labels.aiDisclosureAria,
+    labels.aiPolicyLink,
+    "サイト",
+  ];
+  if (includeSearch) parts.push(labels.search);
+  return parts.join("");
+}