for-humanity 0.2.1 → 0.4.0

package/src/content/read-docs.ts

@@ -1,9 +1,16 @@
 import {readdir, readFile} from "node:fs/promises";
-import {join, sep} from "node:path";
+import {join, posix, sep} from "node:path";
 import {VFile} from "vfile";
 import {parse as parseYaml} from "yaml";
 import {asset_dir, asset_favicon_path} from "@/constant/asset";
-import {copy_error_doc_id, copy_error_doc_id_clash, copy_error_frontmatter} from "@/constant/copy";
+import {
+    copy_error_doc_id,
+    copy_error_doc_id_clash,
+    copy_error_doc_parent_cycle,
+    copy_error_doc_parent_group,
+    copy_error_doc_parent_missing,
+    copy_error_frontmatter,
+} from "@/constant/copy";
 import type {Processor} from "@/content/create-processor";
 import type {Doc} from "@/type/doc";
 import {docDataSchema} from "@/type/doc-data";
@@ -49,8 +56,14 @@ export const readDocs = async (options: {root: string; processor: Processor}): P
                 throw new Error(`${copy_error_frontmatter}: ${path}: ${parsed.error.issues.map((issue) => `${issue.path.join(".")} ${issue.message}`).join(", ")}`);
             }
 
+            // 상대 부모 id는 파일 위치 기준으로 한 번 해소 · 문서 루트를 바꿔도 같은 관계 유지
+            const data = {
+                ...parsed.data,
+                parent: parsed.data.parent !== undefined && /^\.\.?\//.test(parsed.data.parent) ? posix.join(posix.dirname(id), parsed.data.parent) : parsed.data.parent,
+            };
+
             // 플러그인의 제목·절 정보 공유
-            const fh: DocFileData = {frontmatter: parsed.data, headings: [], sections: []};
+            const fh: DocFileData = {frontmatter: data, headings: [], sections: []};
             file.data.fh = fh;
 
             // YAML 노드만 제외 · 본문 위치와 오류의 원본 줄·열·offset 유지
@@ -59,7 +72,8 @@ export const readDocs = async (options: {root: string; processor: Processor}): P
 
             return {
                 id,
-                data: parsed.data,
+                data,
+                ancestors: [],
                 html: options.processor.stringify(rendered, file),
                 outline: {headings: fh.headings, sections: fh.sections},
             };
@@ -71,5 +85,25 @@ export const readDocs = async (options: {root: string; processor: Processor}): P
         throw new Error(`${copy_error_doc_id_clash}: ${duplicateIds.map((entry) => entry[0]).join(", ")}`);
     }
 
-    return docs;
+    // 모든 파일을 수집한 뒤 부모 참조 검증 · 파일 읽기 순서와 무관한 문서 경로
+    const docsById = new Map(docs.map((doc) => [doc.id, doc]));
+    return docs.map((doc) => {
+        const ancestors = new Set([doc.id]);
+        for (let parentId = doc.data.parent; parentId !== undefined; ) {
+            const parent = docsById.get(parentId);
+            if (parent === undefined) {
+                throw new Error(`${copy_error_doc_parent_missing}: ${doc.id} → ${parentId}`);
+            }
+            if (ancestors.has(parent.id)) {
+                throw new Error(`${copy_error_doc_parent_cycle}: ${[...ancestors, parent.id].join(" → ")}`);
+            }
+            if (JSON.stringify(parent.data.group) !== JSON.stringify(doc.data.group)) {
+                throw new Error(`${copy_error_doc_parent_group}: ${doc.id} → ${parent.id}`);
+            }
+            ancestors.add(parent.id);
+            parentId = parent.data.parent;
+        }
+
+        return {...doc, ancestors: [...ancestors].slice(1).toReversed()};
+    });
 };

package/src/content/rehype-assets.ts

@@ -0,0 +1,70 @@
+import {existsSync, realpathSync, statSync} from "node:fs";
+import {dirname, extname, isAbsolute, relative, resolve, sep} from "node:path";
+import type {Root} from "hast";
+import {visit} from "unist-util-visit";
+import type {VFile} from "vfile";
+import {asset_media_dir, asset_media_extensions} from "@/constant/asset";
+import {copy_error_asset} from "@/constant/copy";
+import {toAssetPath} from "@/util/file/to-asset-path";
+
+/**
+ * 명시적으로 참조한 로컬 이미지·첨부의 수집 계약
+ */
+export interface AssetOptions {
+    /**
+     * 자원을 읽을 수 있는 문서 루트
+     */
+    root: string;
+    /**
+     * dev 응답과 정적 복사에서 공유할 URL → 파일 목록
+     */
+    files: Map<string, string>;
+}
+
+/**
+ * 파일 위치 기준 이미지·첨부 → 내용 지문 URL · 원시 HTML도 같은 규칙
+ * 없는 파일, 폴더 밖 경로와 symlink, 지원하지 않는 이미지 형식은 빌드 실패
+ * 절대 URL·외부 URL은 작성자가 제공하며 수집하지 않음
+ */
+export const rehypeAssets = (options: AssetOptions) => (tree: Root, file: VFile) => {
+    visit(tree, "element", (node) => {
+        const property = node.tagName === "img" ? "src" : "href";
+        const url = node.properties[property];
+
+        if ((node.tagName !== "img" && node.tagName !== "a") || typeof url !== "string" || /^(?:[a-z][a-z\d+.-]*:|\/|#)/i.test(url)) {
+            return;
+        }
+
+        const match = /^([^?#]+)([?#].*)?$/.exec(url);
+        if (match === null) {
+            return;
+        }
+
+        const path = decodeURIComponent(match[1]);
+        const extension = extname(path).toLowerCase();
+        if (!asset_media_extensions.has(extension)) {
+            if (node.tagName === "img") {
+                file.fail(`${copy_error_asset}: 지원하지 않는 이미지 형식 · ${url}`, node);
+            }
+            return;
+        }
+
+        const target = resolve(dirname(file.path), path);
+        const location = relative(options.root, target);
+        if (location === ".." || location.startsWith(`..${sep}`) || isAbsolute(location)) {
+            file.fail(`${copy_error_asset}: 문서 폴더 밖 · ${url}`, node);
+        }
+        if (!existsSync(target)) {
+            file.fail(`${copy_error_asset}: 파일이 없다 · ${url}`, node);
+        }
+        const actual = realpathSync(target);
+        const actualLocation = relative(realpathSync(options.root), actual);
+        if (actualLocation === ".." || actualLocation.startsWith(`..${sep}`) || isAbsolute(actualLocation) || !statSync(actual).isFile()) {
+            file.fail(`${copy_error_asset}: 문서 폴더 밖이거나 일반 파일이 아니다 · ${url}`, node);
+        }
+
+        const assetUrl = toAssetPath({path: `${asset_media_dir}/asset${extension}`, file: actual});
+        options.files.set(assetUrl, actual);
+        node.properties[property] = match[2] === undefined ? assetUrl : `${assetUrl}${match[2]}`;
+    });
+};

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

@@ -0,0 +1,15 @@
+import {locale_doc_name} from "@/constant/locale";
+import type {Doc} from "@/type/doc";
+import type {DocBranch} from "@/type/doc-branch";
+
+/**
+ * 검증된 부모 관계로 문서 가지를 재귀 구성 · 형제 순서와 URL 유지
+ */
+export const toDocBranches = (options: {docs: readonly Doc[]; children: ReadonlyMap<Doc["data"]["parent"], Doc[]>}): DocBranch[] => {
+    return options.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))
+        .map((doc) => {
+            const children = options.children.get(doc.id);
+            return {...doc, children: children === undefined ? undefined : toDocBranches({docs: children, children: options.children})};
+        });
+};

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

@@ -1,4 +1,5 @@
-import {locale_doc_group, locale_doc_name} from "@/constant/locale";
+import {locale_doc_group} from "@/constant/locale";
+import {toDocBranches} from "@/content/to-doc-groups/_to-doc-branches";
 import type {Doc} from "@/type/doc";
 import type {DocGroup} from "@/type/doc-group";
 
@@ -10,6 +11,10 @@ interface DocGroupBranchesOptions {
      * 부모 경로에 속한 문서
      */
     docs: readonly Doc[];
+    /**
+     * 검증된 부모 id별 문서 · 자손을 각 단계에서 다시 수집하지 않음
+     */
+    children: ReadonlyMap<Doc["data"]["parent"], Doc[]>;
     /**
      * 부모까지의 경로 · 최상위는 빈 배열
      */
@@ -49,10 +54,17 @@ export const toDocGroupBranches = (options: DocGroupBranchesOptions): DocGroup[]
             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}),
+                docs: toDocBranches({
+                    docs: group.docs.filter((doc) => doc.data.group.length === group.path.length && doc.data.parent === undefined),
+                    children: options.children,
+                }),
+                groups: toDocGroupBranches({
+                    docs: group.docs,
+                    children: options.children,
+                    path: group.path,
+                    positions: options.positions,
+                    unlistedPosition: options.unlistedPosition,
+                }),
             };
         });
 };

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

@@ -10,5 +10,6 @@ export const toDocGroups = (options: {docs: readonly Doc[]; navigation: SiteConf
     // 같은 조상을 지정한 경로는 최초 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});
+    const children = Map.groupBy(options.docs, (doc) => doc.data.parent);
+    return toDocGroupBranches({docs: options.docs, children, path: [], positions, unlistedPosition: options.navigation.length});
 };

package/src/dev.ts

@@ -41,7 +41,7 @@ export const createDevApp = (options: DevOptions) => {
             return c.notFound();
         }
 
-        c.header("content-type", asset_content_types[extname(file)] ?? asset_content_type_default);
+        c.header("content-type", asset_content_types[extname(file).toLowerCase()] ?? asset_content_type_default);
 
         if (extname(file) === ".woff2") {
             c.header("Cache-Control", font_cache_control);

package/src/style/token.css

@@ -55,7 +55,8 @@
     --app-font-mono: "JetBrains Mono Variable", var(--app-font-sans);
     --app-font-brand: "Architects Daughter", var(--app-font-sans);
 
-    /* 글자 크기 · 12px 기본과 역할별 제목 크기 */
+    /* 글자 크기 · 11px 비상호작용 묶음 · 12px 기본과 역할별 제목 크기 */
+    --app-font-size-group: 11px;
     --app-font-size-label: 12px;
     --app-font-size-detail: 12px;
     --app-font-size-dense: 12px;
@@ -65,9 +66,9 @@
     --app-font-size-section: 14px;
     --app-font-size-title: 16px;
 
-    /* 굵기 · 기본 400 · 현재 위치 500 · 제목·강조 600 */
+    /* 굵기 · 기본 400 · 현재 위치·제목·강조 600 */
     --app-font-weight-mark: 400;
-    --app-font-weight-active: 500;
+    --app-font-weight-active: 600;
     --app-font-weight-strong: 600;
     --app-font-weight-title: 600;
 

package/src/type/doc-branch.ts

@@ -0,0 +1,11 @@
+import type {Doc} from "@/type/doc";
+
+/**
+ * 문서 탐색의 클릭 가능한 가지 · 원래 URL과 본문을 유지
+ */
+export interface DocBranch extends Doc {
+    /**
+     * 같은 부모 아래의 문서 · order·제목·id 순, 말단 문서는 생략
+     */
+    children?: DocBranch[];
+}

package/src/type/doc-data.ts

@@ -15,13 +15,17 @@ export const docDataSchema = z.object({
      */
     label: z.string(),
     /**
-     * 문서 종류 · blueprint 전용 표현 미구현
+     * 기존 type 값 호환 · 생략 권장, 렌더링 차이 없음
      */
     type: z.enum(doc_type).default(doc_type.document),
     /**
      * 사이드바의 문서 묶음 경로 · 문자열도 배열로 정규화
      */
     group: groupPathSchema,
+    /**
+     * 같은 묶음 안의 부모 문서 id · 확장자 제외, ./·../ 상대 경로도 허용
+     */
+    parent: z.string().trim().min(1).optional(),
     /**
      * 묶음 안의 읽는 순서 · 미지정 문서는 뒤에서 이름순
      */

package/src/type/doc-group.ts

@@ -1,4 +1,5 @@
 import type {Doc} from "@/type/doc";
+import type {DocBranch} from "@/type/doc-branch";
 
 /**
  * 사이드바의 문서 묶음 · 같은 이름도 전체 경로로 구분
@@ -13,9 +14,9 @@ export interface DocGroup {
      */
     path: Doc["data"]["group"];
     /**
-     * 현재 묶음에 직접 속한 문서 · order·제목·id 순
+     * 현재 묶음의 부모 없는 문서 · 하위 문서는 각 문서 가지에 포함
      */
-    docs: Doc[];
+    docs: DocBranch[];
     /**
      * 현재 묶음의 하위 묶음 · navigation·이름 순
      */

package/src/type/doc.ts

@@ -13,4 +13,8 @@ export interface Doc extends DocContent {
      * 검증된 머리말
      */
     data: DocData;
+    /**
+     * 검증된 부모 문서 경로 · 최상위부터 직접 부모까지, 자신은 제외
+     */
+    ancestors: string[];
 }