fix: 관계의 묶음 이름과 작성자가 쓴 문장을 갈라 놓는다

관계 한 줄에 세 가지가 뭉쳐 있었다. 대상이 어떤 종류인지, 작성자가 왜 걸었는지,
대상이 무엇인지 — 셋 다 `reason` 한 칸을 지나느라 경로마다 다른 것이 같은 자리에
나왔다. 렌더 모델 경로에서는 작성자의 문장이 묶음 이름 자리에 눌려 한 줄짜리 라벨인
척했고, 공개 조회 경로에서는 묶음 이름이 그 자리를 차지하고 작성자의 문장은 아예
버려졌다. 「다음에 무엇을 읽을지」의 답이 그 문장인데 공개 화면에 한 번도 나오지 않았다.

이제 셋이 각자의 칸을 갖는다. `label` 은 대상의 종류, `note` 는 작성자가 쓴 문장,
`summary` 는 대상의 요약이다. 설명 자리에는 문장이 있으면 문장을, 없으면 요약을
보인다 — 요약은 대상을 설명하고 문장은 왜 지금 이것을 읽어야 하는지를 설명한다.

공개 주소로 종류를 되짚던 삼항 사슬도 표로 바꾼다. `/concepts/` 가 어디에도 없어서
개념으로 가는 관계가 전부 `PROJECT` 로 떨어지고 있었다 — 손으로 나열한 목록에 새
종류를 빠뜨리는 일이 이 저장소에서만 다섯 번째다.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ
This commit is contained in:
DongHyeonka
2026-09-01 16:48:11 +09:00
co-authored by Claude Opus 5
parent af5a6bbf23
commit 618a228eff
22 changed files with 698 additions and 76 deletions
@@ -127,18 +127,35 @@ function slugOf(title: string, index: number): string {
return normalized.length > 0 ? normalized : `section-${index + 1}`;
}
type Related = Readonly<{ type?: string; title?: string; summary?: string; path?: string }>;
type Related = Readonly<{
type?: string;
title?: string;
summary?: string;
path?: string;
/** 작성자가 남긴, 왜 이 기록이 걸려 있는지. 그룹 이름(`reason`)과는 다른 칸이다. */
reason?: string;
priority?: number;
}>;
/**
* The contract groups relations by why they relate (origin question, derived
* references, related cases); the renderer takes one list where the reason is a
* label. Flattening keeps the group name as that label.
*/
type PublicRelationEntry = {
reason: string;
title: string;
path: string;
summary: string;
note: string;
priority: number;
};
export function flattenRelations(
groups: Readonly<Record<string, Related | readonly Related[] | undefined>>,
labels: Readonly<Record<string, string>>,
): ReadonlyArray<{ reason: string; title: string; path: string; summary: string }> {
const flat: { reason: string; title: string; path: string; summary: string }[] = [];
): ReadonlyArray<PublicRelationEntry> {
const flat: PublicRelationEntry[] = [];
for (const [group, value] of Object.entries(groups)) {
if (!value) continue;
const reason = labels[group] ?? group;
@@ -152,7 +169,13 @@ export function flattenRelations(
reason,
title: entry.title,
path: entry.path,
summary: cardSummary((entry as { summary?: string }).summary),
summary: cardSummary(entry.summary),
/*
작성자가 관계마다 남긴 문장. 「다음에 무엇을 읽을지」의 답이 이것이고, 그룹 이름은
그저 분류다. 오래 Studio 에만 있었다.
*/
note: (entry.reason ?? "").trim(),
priority: entry.priority ?? 0,
});
}
}
@@ -171,7 +194,7 @@ export function baseOf(
primaryTopic?: Summary;
primaryProject?: Summary;
publishedAt?: string | null;
relations?: ReadonlyArray<{ reason: string; title: string; path: string; summary: string }>;
relations?: ReadonlyArray<PublicRelationEntry>;
}>,
) {
return {
@@ -11,8 +11,20 @@ export type PublicRelation = {
summary: string;
title: string;
path: string;
/**
* 작성자가 관계마다 남긴 이유. 아래 정적 자료에는 아무도 쓴 적이 없으므로 여기서는 빈 값이고,
* 내보낼 때 {@link publicRecords} 가 한 번에 채운다. 목록마다 `note: ""` 를 손으로 적게 하면
* 언젠가 하나를 빠뜨린다 — 이 저장소에서 이미 다섯 번 그랬다.
*/
note: string;
/** 낮을수록 먼저. */
priority: number;
};
/** 정적 자료가 실제로 적는 모양. 작성자가 남긴 이유가 없으므로 두 칸이 선택이다. */
type StaticRelation = Omit<PublicRelation, "note" | "priority"> &
Partial<Pick<PublicRelation, "note" | "priority">>;
export type RecordSection = {
id: string;
title: string;
@@ -185,7 +197,27 @@ export type HomeFocusItem = {
targetPath: string;
};
export const publicRecords: ReadonlyArray<PublicRecord> = [
/** 아래 목록이 적는 모양. 관계의 두 칸만 느슨하다. 유니온마다 나눠 적용한다. */
type Draft<T> = T extends unknown
? Omit<T, "relations"> & { relations: ReadonlyArray<StaticRelation> }
: never;
/**
* 관계의 빈 칸을 채운다. 정적 자료가 적는 모양과 포트가 요구하는 모양이 갈리는 지점이 여기
* 하나뿐이도록 한다.
*/
function withRelationDefaults(record: Draft<PublicRecord>): PublicRecord {
return {
...record,
relations: record.relations.map((relation) => ({
...relation,
note: relation.note ?? "",
priority: relation.priority ?? 0,
})),
} as PublicRecord;
}
const staticPublicRecords: ReadonlyArray<Draft<PublicRecord>> = [
{
kind: "CONCEPT",
slug: "kubernetes-scheduling",
@@ -607,6 +639,9 @@ export const publicRecords: ReadonlyArray<PublicRecord> = [
},
];
export const publicRecords: ReadonlyArray<PublicRecord> =
staticPublicRecords.map(withRelationDefaults);
export const projects: ReadonlyArray<Project> = [
{
slug: "backend-skeleton",