for-humanity 0.1.2 → 0.2.1

package/src/content/to-doc-groups/_to-doc-group-branches.ts

@@ -0,0 +1,58 @@
+import {locale_doc_group, locale_doc_name} from "@/constant/locale";
+import type {Doc} from "@/type/doc";
+import type {DocGroup} from "@/type/doc-group";
+
+/**
+ * 같은 부모의 문서를 다음 경로 단계로 묶는 재귀 입력
+ */
+interface DocGroupBranchesOptions {
+    /**
+     * 부모 경로에 속한 문서
+     */
+    docs: readonly Doc[];
+    /**
+     * 부모까지의 경로 · 최상위는 빈 배열
+     */
+    path: DocGroup["path"];
+    /**
+     * 전체 경로의 JSON 키와 navigation 위치
+     */
+    positions: ReadonlyMap<string, number>;
+    /**
+     * 미지정 경로를 지정한 묶음 뒤에 놓는 위치
+     */
+    unlistedPosition: number;
+}
+
+/**
+ * 각 단계의 직접 문서와 하위 묶음을 분리 · 고정된 깊이 제한 없이 구성
+ */
+export const toDocGroupBranches = (options: DocGroupBranchesOptions): DocGroup[] => {
+    return [
+        ...Map.groupBy(
+            options.docs.filter((doc) => doc.data.group.length > options.path.length),
+            (doc) => doc.data.group[options.path.length],
+        ),
+    ]
+        .map(([name, docs]) => {
+            const path = [...options.path, name];
+
+            return {
+                name,
+                path,
+                docs,
+                position: options.positions.get(JSON.stringify(path)) ?? options.unlistedPosition,
+            };
+        })
+        .toSorted((a, b) => a.position - b.position || a.name.localeCompare(b.name, locale_doc_group))
+        .map((group) => {
+            return {
+                name: group.name,
+                path: group.path,
+                docs: group.docs
+                    .filter((doc) => doc.data.group.length === group.path.length)
+                    .toSorted((a, b) => a.data.order - b.data.order || a.data.name.localeCompare(b.data.name, locale_doc_name) || a.id.localeCompare(b.id, locale_doc_name)),
+                groups: toDocGroupBranches({docs: group.docs, path: group.path, positions: options.positions, unlistedPosition: options.unlistedPosition}),
+            };
+        });
+};

package/src/content/to-doc-groups/to-doc-groups.ts

@@ -0,0 +1,14 @@
+import {toDocGroupBranches} from "@/content/to-doc-groups/_to-doc-group-branches";
+import type {Doc} from "@/type/doc";
+import type {SiteConfig} from "@/type/site-config";
+
+/**
+ * 메타데이터 경로로 읽는 순서를 가진 문서 계층 구성
+ * navigation의 첫 지정을 조상에도 적용 · 미지정 형제 묶음은 이름순
+ */
+export const toDocGroups = (options: {docs: readonly Doc[]; navigation: SiteConfig["navigation"]}) => {
+    // 같은 조상을 지정한 경로는 최초 navigation 위치를 우선
+    const positions = new Map(options.navigation.flatMap((path, index) => path.map((_name, depth) => [JSON.stringify(path.slice(0, depth + 1)), index] as const)).toReversed());
+
+    return toDocGroupBranches({docs: options.docs, path: [], positions, unlistedPosition: options.navigation.length});
+};

package/src/type/doc-data.ts

@@ -1,5 +1,6 @@
 import {z} from "zod";
 import {doc_order_default, doc_type} from "@/constant/doc";
+import {groupPathSchema} from "@/type/group-path";
 
 /**
  * 문서 frontmatter 스키마 · 검증 실패 시 빌드 중단
@@ -18,9 +19,9 @@ export const docDataSchema = z.object({
      */
     type: z.enum(doc_type).default(doc_type.document),
     /**
-     * 사이드바의 문서 묶음
+     * 사이드바의 문서 묶음 경로 · 문자열도 배열로 정규화
      */
-    group: z.string().trim().min(1),
+    group: groupPathSchema,
     /**
      * 묶음 안의 읽는 순서 · 미지정 문서는 뒤에서 이름순
      */

package/src/type/doc-group.ts

@@ -0,0 +1,23 @@
+import type {Doc} from "@/type/doc";
+
+/**
+ * 사이드바의 문서 묶음 · 같은 이름도 전체 경로로 구분
+ */
+export interface DocGroup {
+    /**
+     * 현재 단계의 표시 이름
+     */
+    name: string;
+    /**
+     * 최상위부터 현재 단계까지의 경로
+     */
+    path: Doc["data"]["group"];
+    /**
+     * 현재 묶음에 직접 속한 문서 · order·제목·id 순
+     */
+    docs: Doc[];
+    /**
+     * 현재 묶음의 하위 묶음 · navigation·이름 순
+     */
+    groups: DocGroup[];
+}

package/src/type/group-path.ts

@@ -0,0 +1,7 @@
+import {z} from "zod";
+
+/**
+ * 탐색 묶음 경로 · 기존 단일 이름과 중첩 배열을 한 번만 정규화
+ * 쉼표·슬래시는 이름 그대로 유지하며 빈 경로·단계는 거부
+ */
+export const groupPathSchema = z.union([z.string().trim().min(1), z.array(z.string().trim().min(1)).min(1)]).transform((path) => (typeof path === "string" ? [path] : path));

package/src/type/site-assets.ts

@@ -2,6 +2,14 @@
  * 모든 페이지가 공유하는 HTML 머리 자원
  */
 export interface SiteAssets {
+    /**
+     * 내용 지문으로 구분한 스타일시트 URL
+     */
+    stylePath: string;
+    /**
+     * 내용 지문으로 구분한 브라우저 스크립트 URL
+     */
+    clientPath: string;
     /**
      * 내장 @font-face · head의 style 내용
      */

package/src/type/site-config.ts

@@ -2,6 +2,7 @@ import {z} from "zod";
 import {copy_error_navigation_clash, copy_site_title_default} from "@/constant/copy";
 import {site_navigation_default} from "@/constant/site";
 import {status_default_phrases, status_kind} from "@/constant/status";
+import {groupPathSchema} from "@/type/group-path";
 
 /**
  * for-humanity.config.mjs 설정 스키마
@@ -17,12 +18,12 @@ export const siteConfigSchema = z.object({
      */
     description: z.string().optional(),
     /**
-     * 탐색 묶음의 읽는 순서 · 미지정 묶음은 뒤에서 이름순
+     * 탐색 묶음 경로의 읽는 순서 · 미지정 형제 묶음은 뒤에서 이름순
      */
     navigation: z
-        .array(z.string().trim().min(1))
-        .refine((groups) => new Set(groups).size === groups.length, copy_error_navigation_clash)
-        .default([...site_navigation_default]),
+        .array(groupPathSchema)
+        .refine((groups) => new Set(groups.map((path) => JSON.stringify(path))).size === groups.length, copy_error_navigation_clash)
+        .default(site_navigation_default.map((name) => [name])),
     /**
      * 본문에서 상태 표지로 표시할 문구
      */

package/src/util/file/to-asset-path.ts

@@ -0,0 +1,26 @@
+import {createHash} from "node:crypto";
+import {readFileSync} from "node:fs";
+import {posix} from "node:path";
+
+/**
+ * 파일 내용으로 자원 URL을 구분하는 입력
+ */
+export interface AssetPathOptions {
+    /**
+     * 사이트 루트 기준 기본 자원 경로
+     */
+    path: string;
+    /**
+     * 배포할 실제 파일 경로
+     */
+    file: string;
+}
+
+/**
+ * 파일명에 내용 지문 추가 · 같은 내용은 같은 URL, 변경한 내용은 새 캐시 키 사용
+ */
+export const toAssetPath = (options: AssetPathOptions) => {
+    const extension = posix.extname(options.path);
+
+    return `${posix.dirname(options.path)}/${posix.basename(options.path, extension)}.${createHash("sha256").update(readFileSync(options.file)).digest("hex")}${extension}`;
+};

package/src/content/to-doc-groups.ts

@@ -1,18 +0,0 @@
-import {locale_doc_group, locale_doc_name} from "@/constant/locale";
-import type {Doc} from "@/type/doc";
-import type {SiteConfig} from "@/type/site-config";
-
-/**
- * 사이드바의 읽는 순서 · 설정 밖 묶음은 뒤에서 이름순
- * 같은 문서 이름·순서도 파일 id로 구분해 탐색 순서를 고정
- */
-export const toDocGroups = (options: {docs: readonly Doc[]; navigation: SiteConfig["navigation"]}) => {
-    const positions = new Map(options.navigation.map((name, index) => [name, index]));
-
-    return [...Map.groupBy(options.docs, (doc) => doc.data.group)]
-        .toSorted((a, b) => (positions.get(a[0]) ?? options.navigation.length) - (positions.get(b[0]) ?? options.navigation.length) || a[0].localeCompare(b[0], locale_doc_group))
-        .map(([name, docs]) => ({
-            name,
-            docs: docs.toSorted((a, b) => a.data.order - b.data.order || a.data.name.localeCompare(b.data.name, locale_doc_name) || a.id.localeCompare(b.id, locale_doc_name)),
-        }));
-};