@sorane/okf 0.2.0

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@sorane/okf",
+  "version": "0.2.0",
+  "description": "Open Knowledge Format parsing, validation, and serialization for sorane",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/masanork/sorane.git",
+    "directory": "packages/okf"
+  },
+  "homepage": "https://sorane.dev",
+  "bugs": "https://github.com/masanork/sorane/issues",
+  "files": [
+    "src"
+  ],
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "engines": {
+    "node": ">=23.6"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
+    "js-yaml": "^4.1.0"
+  }
+}

package/src/bundle.ts

@@ -0,0 +1,70 @@
+import { createGzip } from "node:zlib";
+import type { OkfConcept } from "./normalize.ts";
+import { conceptToOkfMarkdown } from "./serialize.ts";
+
+export interface BundleEntry {
+  readonly path: string;
+  readonly content: string;
+}
+
+export interface BundleConcept {
+  readonly concept: OkfConcept;
+  readonly slug: string;
+}
+
+/** 公開 concept を OKF bundle エントリに変換する（{type}/{slug}.md）。 */
+export function buildBundleEntries(concepts: readonly BundleConcept[]): BundleEntry[] {
+  return concepts
+    .slice()
+    .sort((a, b) => {
+      const pa = `${a.concept.type}/${a.slug}`;
+      const pb = `${b.concept.type}/${b.slug}`;
+      return pa < pb ? -1 : pa > pb ? 1 : 0;
+    })
+    .map((c) => ({
+      path: `${c.concept.type}/${c.slug}.md`,
+      content: conceptToOkfMarkdown(c.concept),
+    }));
+}
+
+/** 最小 tar（USTAR）を組み立てる。 */
+function tarEntries(entries: readonly BundleEntry[]): Buffer {
+  const blocks: Buffer[] = [];
+  for (const entry of entries) {
+    const content = Buffer.from(entry.content, "utf8");
+    const name = entry.path;
+    const header = Buffer.alloc(512, 0);
+    header.write(name.slice(0, 100), 0, "ascii");
+    header.write("0000644\0", 100, "ascii");
+    header.write("0000000\0", 108, "ascii");
+    header.write("0000000\0", 116, "ascii");
+    header.write(content.length.toString(8).padStart(11, "0") + "\0", 124, "ascii");
+    header.write(Math.floor(Date.now() / 1000).toString(8).padStart(11, "0") + "\0", 136, "ascii");
+    header.write("        ", 148, "ascii");
+    header.write("ustar\0", 257, "ascii");
+    header.write("00", 263, "ascii");
+    let checksum = 0;
+    for (let i = 0; i < 512; i++) checksum += header[i]!;
+    header.write(checksum.toString(8).padStart(6, "0") + "\0 ", 148, "ascii");
+    blocks.push(header, content);
+    const pad = (512 - (content.length % 512)) % 512;
+    if (pad > 0) blocks.push(Buffer.alloc(pad, 0));
+  }
+  blocks.push(Buffer.alloc(512, 0));
+  blocks.push(Buffer.alloc(512, 0));
+  return Buffer.concat(blocks);
+}
+
+/** OKF bundle を gzip 圧縮した bytes として返す。 */
+export function buildOkfBundle(concepts: readonly BundleConcept[]): Promise<Buffer> {
+  const entries = buildBundleEntries(concepts);
+  const tar = tarEntries(entries);
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    const gzip = createGzip();
+    gzip.on("data", (c) => chunks.push(c));
+    gzip.on("end", () => resolve(Buffer.concat(chunks)));
+    gzip.on("error", reject);
+    gzip.end(tar);
+  });
+}

package/src/digital-source-type.ts

@@ -0,0 +1,200 @@
+export const IPTC_BASE = "http://cv.iptc.org/newscodes/digitalsourcetype" as const;
+
+export type EuAiLabel = "basic" | "fully-generated" | "partially-modified";
+
+export const RETIRED_ALIASES: Readonly<Record<string, string>> = {
+  digitalArt: "digitalCreation",
+};
+
+export const PHASE1_CODES = new Set([
+  "trainedAlgorithmicMedia",
+  "compositeWithTrainedAlgorithmicMedia",
+  "compositeSynthetic",
+  "algorithmicMedia",
+  "humanEdits",
+  "digitalCreation",
+]);
+
+const EU_INFER: Readonly<Record<string, EuAiLabel | undefined>> = {
+  trainedAlgorithmicMedia: "fully-generated",
+  compositeWithTrainedAlgorithmicMedia: "partially-modified",
+  compositeSynthetic: "partially-modified",
+  algorithmicMedia: undefined,
+  humanEdits: undefined,
+  digitalCreation: undefined,
+};
+
+export interface ResolvedDigitalSourceType {
+  readonly uri: string;
+  readonly code: string;
+  readonly warnings: readonly string[];
+}
+
+export function resolveDigitalSourceType(
+  raw: string,
+): ResolvedDigitalSourceType | null {
+  const trimmed = raw.trim();
+  if (trimmed.length === 0) return null;
+
+  let code: string;
+  const warnings: string[] = [];
+
+  if (trimmed.startsWith("http://") || trimmed.startsWith("https://")) {
+    const normalized = trimmed.replace(/\/$/, "");
+    const prefix = `${IPTC_BASE}/`;
+    const httpUri = normalized.replace(/^https:\/\//, "http://");
+    if (!httpUri.startsWith(prefix)) return null;
+    code = httpUri.slice(prefix.length);
+  } else {
+    code = trimmed;
+  }
+
+  if (code in RETIRED_ALIASES) {
+    const replacement = RETIRED_ALIASES[code]!;
+    warnings.push(`${code} is retired; use ${replacement}`);
+    code = replacement;
+  }
+
+  if (!PHASE1_CODES.has(code)) return null;
+
+  return {
+    uri: `${IPTC_BASE}/${code}`,
+    code,
+    warnings,
+  };
+}
+
+export function inferEuLabel(
+  code: string,
+  override?: EuAiLabel,
+): EuAiLabel | undefined {
+  if (override) return override;
+  return EU_INFER[code];
+}
+
+export function showsEuBadge(code: string, override?: EuAiLabel): boolean {
+  if (override) return true;
+  const inferred = EU_INFER[code];
+  return inferred !== undefined;
+}
+
+export type EuAiLabelInput = EuAiLabel;
+
+export function parseEuAiLabel(raw: unknown): EuAiLabel | undefined {
+  if (raw === "basic" || raw === "fully-generated" || raw === "partially-modified") {
+    return raw;
+  }
+  return undefined;
+}
+
+export interface AiSystemRef {
+  readonly name: string;
+  readonly version?: string;
+  readonly provider?: string;
+}
+
+export function parseAiSystems(raw: unknown): AiSystemRef[] | undefined {
+  if (!Array.isArray(raw) || raw.length === 0) return undefined;
+  const out: AiSystemRef[] = [];
+  for (const item of raw) {
+    if (item === null || typeof item !== "object" || Array.isArray(item)) return undefined;
+    const name = (item as Record<string, unknown>).name;
+    if (typeof name !== "string" || name.length === 0) return undefined;
+    const version = (item as Record<string, unknown>).version;
+    const provider = (item as Record<string, unknown>).provider;
+    out.push({
+      name,
+      version: typeof version === "string" ? version : undefined,
+      provider: typeof provider === "string" ? provider : undefined,
+    });
+  }
+  return out;
+}
+
+const DISCLOSURE_KEYS = new Set([
+  "digitalSourceType",
+  "euAiLabel",
+  "aiDisclosureNote",
+  "aiSystems",
+]);
+
+export function hasDisclosureKeys(frontmatter: Record<string, unknown>): boolean {
+  return Object.keys(frontmatter).some((k) => DISCLOSURE_KEYS.has(k));
+}
+
+export interface DisclosureValidationIssue {
+  readonly path: string;
+  readonly message: string;
+}
+
+export function validateDisclosureFields(
+  frontmatter: Record<string, unknown>,
+  strictCodes: boolean,
+): { readonly issues: DisclosureValidationIssue[]; readonly warnings: string[] } {
+  const issues: DisclosureValidationIssue[] = [];
+  const warnings: string[] = [];
+
+  if (!hasDisclosureKeys(frontmatter)) {
+    return { issues, warnings };
+  }
+
+  const digitalSourceType = frontmatter.digitalSourceType;
+  const euAiLabel = frontmatter.euAiLabel;
+  const aiDisclosureNote = frontmatter.aiDisclosureNote;
+  const aiSystems = frontmatter.aiSystems;
+
+  const hasDst =
+    typeof digitalSourceType === "string" && digitalSourceType.trim().length > 0;
+
+  if (
+    (euAiLabel !== undefined && euAiLabel !== null && euAiLabel !== "") ||
+    (Array.isArray(aiSystems) && aiSystems.length > 0) ||
+    (typeof aiDisclosureNote === "string" && aiDisclosureNote.trim().length > 0)
+  ) {
+    if (!hasDst) {
+      issues.push({
+        path: "digitalSourceType",
+        message: "digitalSourceType is required when other AI disclosure fields are set",
+      });
+    }
+  }
+
+  if (euAiLabel !== undefined && euAiLabel !== null && euAiLabel !== "") {
+    if (!parseEuAiLabel(euAiLabel)) {
+      issues.push({
+        path: "euAiLabel",
+        message: "euAiLabel must be basic, fully-generated, or partially-modified",
+      });
+    }
+  }
+
+  if (aiSystems !== undefined && parseAiSystems(aiSystems) === undefined) {
+    issues.push({
+      path: "aiSystems",
+      message: "aiSystems must be an array of { name, version?, provider? }",
+    });
+  }
+
+  if (typeof aiDisclosureNote === "string" && aiDisclosureNote.length > 500) {
+    issues.push({
+      path: "aiDisclosureNote",
+      message: "aiDisclosureNote must be at most 500 characters",
+    });
+  }
+
+  if (hasDst && typeof digitalSourceType === "string") {
+    const resolved = resolveDigitalSourceType(digitalSourceType);
+    if (!resolved) {
+      const msg = `unknown digitalSourceType: ${digitalSourceType}`;
+      if (strictCodes) {
+        issues.push({ path: "digitalSourceType", message: msg });
+      } else {
+        warnings.push(msg);
+      }
+    } else {
+      warnings.push(...resolved.warnings);
+    }
+  }
+
+  return { issues, warnings };
+}

package/src/extract.ts

@@ -0,0 +1,26 @@
+/**
+ * OKF concept markdown から frontmatter を抽出する。
+ * gray-matter は使わない（CORE_SCHEMA との整合のため parse は yaml.ts に委ねる）。
+ */
+
+export interface ExtractResult {
+  readonly frontmatter: string | null;
+  readonly body: string;
+}
+
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
+
+export function extract(source: string): ExtractResult {
+  const match = source.match(FRONTMATTER_RE);
+  if (!match) {
+    return { frontmatter: null, body: source };
+  }
+  return {
+    frontmatter: match[1] ?? "",
+    body: source.slice(match[0].length),
+  };
+}
+
+export function stripFrontmatter(source: string): string {
+  return extract(source).body;
+}

package/src/index.ts

@@ -0,0 +1,35 @@
+export { extract, stripFrontmatter } from "./extract.ts";
+export { parseYaml, dumpYaml } from "./yaml.ts";
+export { normalizeConcept, type OkfConcept } from "./normalize.ts";
+export {
+  toOkfFrontmatterLines,
+  conceptToOkfMarkdown,
+} from "./serialize.ts";
+export {
+  validateSource,
+  validateProfileFormat,
+  resolveProfileSchema,
+  type ValidationResult,
+  type ValidationIssue,
+} from "./validate.ts";
+export {
+  IPTC_BASE,
+  resolveDigitalSourceType,
+  inferEuLabel,
+  showsEuBadge,
+  parseEuAiLabel,
+  parseAiSystems,
+  validateDisclosureFields,
+  hasDisclosureKeys,
+  PHASE1_CODES,
+  type EuAiLabel,
+  type AiSystemRef,
+  type ResolvedDigitalSourceType,
+} from "./digital-source-type.ts";
+export { parseConcept, type ParsedConcept } from "./parse.ts";
+export {
+  buildBundleEntries,
+  buildOkfBundle,
+  type BundleConcept,
+  type BundleEntry,
+} from "./bundle.ts";

package/src/normalize.ts

@@ -0,0 +1,120 @@
+/**
+ * 入力 frontmatter を OKF native 表現に正規化する（純粋・決定論的）。
+ *
+ * 移行期の旧キー:
+ *   layout/kind → type
+ *   date/publishedAt → timestamp (ISO 8601)
+ */
+
+export interface OkfConcept {
+  readonly type: string;
+  readonly title: string;
+  readonly body: string;
+  readonly frontmatter: Record<string, unknown>;
+  readonly timestamp?: string;
+  readonly description?: string;
+  readonly tags?: readonly string[];
+  readonly resource?: string;
+  readonly profile?: string;
+  readonly warnings: readonly string[];
+}
+
+function resolveType(raw: Record<string, unknown>, warnings: string[]): string {
+  if (typeof raw.type === "string" && raw.type.length > 0) return raw.type;
+  if (typeof raw.kind === "string" && raw.kind.length > 0) {
+    warnings.push("deprecated: `kind` → use `type`");
+    return raw.kind;
+  }
+  if (raw.layout === "blog") {
+    warnings.push("deprecated: `layout: blog` → use `type: index`");
+    return "index";
+  }
+  if (raw.layout === "article") {
+    warnings.push("deprecated: `layout: article` → use `type: article`");
+    return "article";
+  }
+  return "";
+}
+
+function toIsoTimestamp(value: unknown): string | undefined {
+  if (typeof value !== "string" || value.length === 0) return undefined;
+  if (/^\d{4}-\d{2}-\d{2}$/.test(value)) {
+    return `${value}T00:00:00Z`;
+  }
+  const d = new Date(value);
+  if (Number.isNaN(d.getTime())) return value;
+  if (/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/.test(value)) return value;
+  return d.toISOString();
+}
+
+function resolveTimestamp(raw: Record<string, unknown>, warnings: string[]): string | undefined {
+  if (raw.timestamp !== undefined) {
+    const ts = toIsoTimestamp(raw.timestamp);
+    return ts;
+  }
+  if (raw.publishedAt !== undefined) {
+    warnings.push("deprecated: `publishedAt` → use `timestamp`");
+    return toIsoTimestamp(raw.publishedAt);
+  }
+  if (raw.date !== undefined) {
+    warnings.push("deprecated: `date` → use `timestamp`");
+    return toIsoTimestamp(raw.date);
+  }
+  return undefined;
+}
+
+function resolveTitle(raw: Record<string, unknown>, body: string, fallback: string): string {
+  if (typeof raw.title === "string" && raw.title.length > 0) return raw.title;
+  const m = body.match(/^#{1,6}\s+(.+?)\s*$/m);
+  if (m?.[1]) return m[1].trim();
+  return fallback;
+}
+
+/** frontmatter オブジェクト + 本文から OKF concept を組み立てる。 */
+export function normalizeConcept(
+  raw: Record<string, unknown>,
+  body: string,
+  fallbackTitle: string,
+): OkfConcept {
+  const warnings: string[] = [];
+  const type = resolveType(raw, warnings);
+  const title = resolveTitle(raw, body, fallbackTitle);
+  const timestamp = resolveTimestamp(raw, warnings);
+
+  const frontmatter: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(raw)) {
+    if (key === "type" || key === "kind" || key === "layout") continue;
+    if (key === "timestamp" || key === "publishedAt" || key === "date") continue;
+    if (key === "title") continue;
+    if (value !== undefined) frontmatter[key] = value;
+  }
+
+  const description =
+    typeof raw.description === "string" && raw.description.length > 0
+      ? raw.description
+      : undefined;
+  const tags = Array.isArray(raw.tags)
+    ? raw.tags.filter((t): t is string => typeof t === "string")
+    : undefined;
+  const resource =
+    typeof raw.resource === "string" && raw.resource.length > 0
+      ? raw.resource
+      : undefined;
+  const profile =
+    typeof raw.profile === "string" && raw.profile.length > 0
+      ? raw.profile
+      : undefined;
+
+  return {
+    type,
+    title,
+    body,
+    frontmatter,
+    timestamp,
+    description,
+    tags,
+    resource,
+    profile,
+    warnings,
+  };
+}

package/src/parse.ts

@@ -0,0 +1,28 @@
+import { extract } from "./extract.ts";
+import { normalizeConcept, type OkfConcept } from "./normalize.ts";
+import { parseYaml } from "./yaml.ts";
+import { validateSource, type ValidationResult } from "./validate.ts";
+
+export interface ParsedConcept {
+  readonly concept: OkfConcept;
+  readonly file: string;
+  readonly relPath: string;
+  readonly validation: ValidationResult;
+}
+
+function slugFromPath(relPath: string): string {
+  const base = relPath.replace(/\\/g, "/").split("/").pop() ?? relPath;
+  return base.replace(/\.md$/i, "");
+}
+
+/** markdown ソースを parse + normalize する（検証結果も返す）。 */
+export function parseConcept(file: string, relPath: string, source: string): ParsedConcept {
+  const validation = validateSource(relPath, source);
+  const { frontmatter, body } = extract(source);
+  const raw =
+    frontmatter !== null
+      ? ((parseYaml(frontmatter) as Record<string, unknown>) ?? {})
+      : {};
+  const concept = normalizeConcept(raw, body, slugFromPath(relPath));
+  return { concept, file, relPath, validation };
+}

package/src/serialize.ts

@@ -0,0 +1,115 @@
+import type { OkfConcept } from "./normalize.ts";
+
+const KEY_ORDER = [
+  "type",
+  "title",
+  "timestamp",
+  "description",
+  "resource",
+  "tags",
+  "profile",
+  "digitalSourceType",
+  "euAiLabel",
+  "aiDisclosureNote",
+  "aiSystems",
+] as const;
+
+function formatScalar(value: unknown): string {
+  if (typeof value === "boolean" || typeof value === "number") {
+    return String(value);
+  }
+  const s = String(value);
+  if (s.length === 0) return "''";
+  if (/^\s|\s$/.test(s)) return `'${s.replace(/'/g, "''")}'`;
+  if (/^[-?:,\[\]{}#&*!|>'"%@`]/.test(s)) return `'${s.replace(/'/g, "''")}'`;
+  if (/:(\s|$)/.test(s)) return `'${s.replace(/'/g, "''")}'`;
+  if (/\s#/.test(s)) return `'${s.replace(/'/g, "''")}'`;
+  if (/^(true|false|null|yes|no|on|off|~)$/i.test(s)) return `'${s.replace(/'/g, "''")}'`;
+  if (/^[+-]?(\d+\.?\d*|\.\d+)([eE][+-]?\d+)?$/.test(s)) return `'${s.replace(/'/g, "''")}'`;
+  return s;
+}
+
+function appendAiSystemsEntry(
+  lines: string[],
+  key: string,
+  systems: readonly { name: string; version?: string; provider?: string }[],
+): void {
+  lines.push(`${key}:`);
+  for (const s of systems) {
+    lines.push(`  - name: ${formatScalar(s.name)}`);
+    if (s.version) lines.push(`    version: ${formatScalar(s.version)}`);
+    if (s.provider) lines.push(`    provider: ${formatScalar(s.provider)}`);
+  }
+}
+
+function appendYamlEntry(lines: string[], key: string, value: unknown): void {
+  if (value === undefined) return;
+  if (Array.isArray(value)) {
+    if (value.length === 0) {
+      lines.push(`${key}: []`);
+      return;
+    }
+    lines.push(`${key}:`);
+    for (const item of value) {
+      lines.push(`  - ${formatScalar(item)}`);
+    }
+    return;
+  }
+  if (value !== null && typeof value === "object") {
+    lines.push(`${key}:`);
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+      if (v === undefined) continue;
+      lines.push(`  ${k}: ${formatScalar(v)}`);
+    }
+    return;
+  }
+  lines.push(`${key}: ${formatScalar(value)}`);
+}
+
+/** OKF native frontmatter 行を組み立てる（旧キーは出力しない）。 */
+export function toOkfFrontmatterLines(concept: OkfConcept): string[] {
+  const lines: string[] = [];
+  lines.push(`type: ${formatScalar(concept.type)}`);
+  lines.push(`title: ${formatScalar(concept.title)}`);
+  if (concept.timestamp) lines.push(`timestamp: ${formatScalar(concept.timestamp)}`);
+  if (concept.description) lines.push(`description: ${formatScalar(concept.description)}`);
+  if (concept.resource) lines.push(`resource: ${formatScalar(concept.resource)}`);
+  if (concept.tags && concept.tags.length > 0) appendYamlEntry(lines, "tags", [...concept.tags]);
+  if (concept.profile) lines.push(`profile: ${formatScalar(concept.profile)}`);
+
+  const fm = concept.frontmatter;
+  if (typeof fm.digitalSourceType === "string" && fm.digitalSourceType.length > 0) {
+    lines.push(`digitalSourceType: ${formatScalar(fm.digitalSourceType)}`);
+  }
+  if (typeof fm.euAiLabel === "string" && fm.euAiLabel.length > 0) {
+    lines.push(`euAiLabel: ${formatScalar(fm.euAiLabel)}`);
+  }
+  if (typeof fm.aiDisclosureNote === "string" && fm.aiDisclosureNote.length > 0) {
+    lines.push(`aiDisclosureNote: ${formatScalar(fm.aiDisclosureNote)}`);
+  }
+  if (Array.isArray(fm.aiSystems) && fm.aiSystems.length > 0) {
+    const parsed = fm.aiSystems.filter(
+      (s): s is { name: string; version?: string; provider?: string } =>
+        s !== null &&
+        typeof s === "object" &&
+        !Array.isArray(s) &&
+        typeof (s as { name?: unknown }).name === "string",
+    );
+    if (parsed.length > 0) appendAiSystemsEntry(lines, "aiSystems", parsed);
+  }
+
+  const ordered = new Set(KEY_ORDER);
+  const restKeys = Object.keys(concept.frontmatter)
+    .filter((k) => !ordered.has(k as (typeof KEY_ORDER)[number]))
+    .sort();
+  for (const key of restKeys) {
+    appendYamlEntry(lines, key, concept.frontmatter[key]);
+  }
+  return lines;
+}
+
+/** Document → OKF native markdown。 */
+export function conceptToOkfMarkdown(concept: OkfConcept): string {
+  const lines = toOkfFrontmatterLines(concept);
+  return `---\n${lines.join("\n")}\n---\n${concept.body}`;
+}

package/src/validate.ts

@@ -0,0 +1,189 @@
+import Ajv from "ajv";
+import addFormats from "ajv-formats";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { validateDisclosureFields } from "./digital-source-type.ts";
+import { extract } from "./extract.ts";
+import { normalizeConcept } from "./normalize.ts";
+import { parseYaml } from "./yaml.ts";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = join(__dirname, "../../..");
+const PROFILE_SCHEMA_DIR = join(REPO_ROOT, "profile");
+
+const SUPPORTED_PROFILE_RE = /^sorane-okf\/(0\.[12])$/;
+const DEFAULT_PROFILE = "sorane-okf/0.1";
+
+const SUPPORTED_TYPES = new Set(["article", "index"]);
+
+export interface ValidationIssue {
+  readonly where: "structure" | "frontmatter" | "type" | "profile";
+  readonly message: string;
+  readonly instancePath?: string;
+}
+
+export interface ValidationResult {
+  readonly file: string;
+  readonly ok: boolean;
+  readonly type?: string;
+  readonly issues: readonly ValidationIssue[];
+  readonly warnings: readonly string[];
+}
+
+const validatorCache = new Map<string, ReturnType<Ajv["compile"]>>();
+
+export function validateProfileFormat(
+  profile: string | undefined,
+): ValidationIssue | null {
+  if (profile === undefined) return null;
+  if (!SUPPORTED_PROFILE_RE.test(profile)) {
+    return {
+      where: "profile",
+      message: `Unsupported profile "${profile}"; supported: sorane-okf/0.1, sorane-okf/0.2`,
+    };
+  }
+  return null;
+}
+
+export function resolveProfileSchema(profile: string): string {
+  const m = profile.match(SUPPORTED_PROFILE_RE);
+  if (!m) {
+    throw new Error(`unsupported profile: ${profile}`);
+  }
+  return join(PROFILE_SCHEMA_DIR, `sorane-okf-${m[1]}.schema.json`);
+}
+
+function getValidatorForProfile(profile: string): ReturnType<Ajv["compile"]> {
+  const path = resolveProfileSchema(profile);
+  let v = validatorCache.get(path);
+  if (!v) {
+    const ajv = new Ajv({ allErrors: true, strict: false });
+    addFormats(ajv);
+    v = ajv.compile(JSON.parse(readFileSync(path, "utf8")));
+    validatorCache.set(path, v);
+  }
+  return v;
+}
+
+function slugFromPath(filePath: string): string {
+  const base = filePath.replace(/\\/g, "/").split("/").pop() ?? filePath;
+  return base.replace(/\.md$/i, "");
+}
+
+/** 1 つの markdown ソースを sorane-okf プロファイルで検証する。 */
+export function validateSource(file: string, source: string): ValidationResult {
+  const { frontmatter, body } = extract(source);
+  const issues: ValidationIssue[] = [];
+  const warnings: string[] = [];
+
+  if (frontmatter === null) {
+    return {
+      file,
+      ok: false,
+      issues: [
+        {
+          where: "structure",
+          message: "frontmatter ブロック（--- で囲む）がありません",
+        },
+      ],
+      warnings,
+    };
+  }
+
+  let raw: Record<string, unknown>;
+  try {
+    const parsed = parseYaml(frontmatter);
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return {
+        file,
+        ok: false,
+        issues: [{ where: "frontmatter", message: "frontmatter が YAML マッピングではありません" }],
+        warnings,
+      };
+    }
+    raw = parsed as Record<string, unknown>;
+  } catch (e) {
+    return {
+      file,
+      ok: false,
+      issues: [
+        {
+          where: "frontmatter",
+          message: `frontmatter の YAML 解析に失敗: ${e instanceof Error ? e.message : String(e)}`,
+        },
+      ],
+      warnings,
+    };
+  }
+
+  const profileIssue = validateProfileFormat(
+    typeof raw.profile === "string" ? raw.profile : undefined,
+  );
+  if (profileIssue) {
+    issues.push(profileIssue);
+  }
+
+  const concept = normalizeConcept(raw, body, slugFromPath(file));
+  warnings.push(...concept.warnings);
+
+  if (!concept.type) {
+    issues.push({
+      where: "type",
+      message: "OKF 必須フィールド `type` がありません",
+    });
+  } else if (!SUPPORTED_TYPES.has(concept.type)) {
+    issues.push({
+      where: "type",
+      message: `未サポートの type: ${concept.type}（v0.1 は article / index のみ）`,
+    });
+  }
+
+  const profile =
+    typeof concept.profile === "string" && SUPPORTED_PROFILE_RE.test(concept.profile)
+      ? concept.profile
+      : DEFAULT_PROFILE;
+
+  if (issues.every((i) => i.where !== "profile")) {
+    const validate = getValidatorForProfile(profile);
+    const fmForSchema: Record<string, unknown> = {
+      type: concept.type || "article",
+      title: concept.title,
+      ...concept.frontmatter,
+    };
+    if (concept.timestamp) fmForSchema.timestamp = concept.timestamp;
+    if (concept.description) fmForSchema.description = concept.description;
+    if (concept.tags) fmForSchema.tags = [...concept.tags];
+    if (concept.resource) fmForSchema.resource = concept.resource;
+    if (concept.profile) fmForSchema.profile = concept.profile;
+
+    if (!validate(fmForSchema)) {
+      for (const err of validate.errors ?? []) {
+        issues.push({
+          where: "frontmatter",
+          instancePath: err.instancePath || "/",
+          message: err.message ?? "invalid",
+        });
+      }
+    }
+  }
+
+  const strictDisclosure = profile === "sorane-okf/0.2";
+  const disclosure = validateDisclosureFields(concept.frontmatter, strictDisclosure);
+  warnings.push(...disclosure.warnings);
+  for (const d of disclosure.issues) {
+    issues.push({
+      where: "frontmatter",
+      instancePath: `/${d.path}`,
+      message: d.message,
+    });
+  }
+
+  return {
+    file,
+    ok: issues.length === 0,
+    type: concept.type || undefined,
+    issues,
+    warnings,
+  };
+}

package/src/yaml.ts

@@ -0,0 +1,16 @@
+import yaml from "js-yaml";
+
+/** CORE_SCHEMA で YAML を読む（日付の自動 Date 化を防ぐ）。 */
+export function parseYaml(source: string): unknown {
+  return yaml.load(source, { schema: yaml.CORE_SCHEMA });
+}
+
+export function dumpYaml(value: unknown): string {
+  return yaml.dump(value, {
+    schema: yaml.CORE_SCHEMA,
+    lineWidth: -1,
+    quotingType: '"',
+    forceQuotes: false,
+    noRefs: true,
+  });
+}