빌드 시 같은 슬러그를 만드는 파일 충돌을 찾아내는 방법

빌드 시 충돌 감지 대상

Quartz는 Markdown 파일을 정적 HTML로 변환하는 과정에서 파일 경로를 URL 슬러그로 매핑합니다. 이 과정에서 서로 다른 소스 파일이 동일한 슬러그 값을 가지면 빌드 충돌이 발생합니다. quartz/util/slugCollisions.ts 파일은 이러한 충돌을 감지하고 보고하는 핵심 모듈입니다. 이 도구는 빌드 결과물에서 중복된 URL이 생성되지 않도록 사전에 경고합니다.

충돌 감지 로직은 detectSlugCollisions 함수에서 처리됩니다. 이 함수는 처리된 콘텐츠 배열을 순회하며 각 파일의 슬러그를 Map 구조에 저장합니다. 동일한 슬러그가 이미 존재할 경우 해당 슬러그에 연결된 파일 목록에 현재 파일을 추가합니다. 이 과정은 파일이 파싱된 순서인 Glob 순서에 따라 결정됩니다.

export function detectSlugCollisions(content: ProcessedContent[]): SlugCollision[] {
  const bySlug = new Map<FullSlug, Array<{ relativePath: string; filePath: string }>>()
  // ...
}

충돌 파일의 승패 결정 규칙

동일한 슬러그를 가진 파일이 여러 개 있을 때, 최종 빌드 결과에서 살아남는 파일은 하나뿐입니다. slugCollisions.ts의 주석과 구현을 보면 이 규칙을 명확히 알 수 있습니다.

• 승자(Winner): 충돌 목록에서 마지막에 등장하는 파일이 승자가 됩니다.
• 패자(Shadowed): 승자를 제외한 나머지 파일은 빌드 결과에서 가려집니다.
• 순서: 파일 목록은 파싱된 배열의 순서이며, 현재 구현에서는 결정적인 Glob 순서입니다.

이 규칙은 에미터의 last-write-wins 동작을 따릅니다. 따라서 수정 시각이 아니라 빌드 시스템이 파일을 처리한 순서가 최종 결과물을 결정합니다. 현재 Glob 순서가 파일명과 연관돼 보여도, 탐지 함수가 직접 사용하는 값은 전달받은 배열의 순서입니다.

/**
 * ... The `winner` is the file whose HTML output and trie
 * data represent this slug in the final build ...
 * `winner` is always the last entry.
 */
export interface SlugCollision {
  slug: FullSlug
  files: Array<{ relativePath: string; filePath: string }>
  winner: { relativePath: string; filePath: string }
}

충돌 경고 메시지 분석

빌드 과정에서 충돌이 감지되면 formatCollisionWarning 함수가 경고 메시지를 생성합니다. 이 메시지는 개발자가 충돌을 빠르게 식별하고 해결할 수 있도록 구조화된 정보를 제공합니다.

• 헤더: 감지된 충돌 그룹의 총개수를 명시합니다.
• 설명: 마지막에 처리된 파일이 사용되고, 나머지는 콘텐츠가 표시되지 않는다고 알립니다.
• 상세 목록: 충돌하는 슬러그별로 관련 파일과 승패 표시를 나열합니다.
• 해결 제안: 파일명을 바꾸거나 불필요한 파일을 삭제하고, Obsidian 폴더 노트 규칙도 확인하라고 안내합니다.

export function formatCollisionWarning(collisions: SlugCollision[]): string {
  // ...
  lines.push(`Warning: ${collisions.length} slug collisions detected.`)
  lines.push(`Multiple source files produced the same URL slug. The last-processed file wins...`)
  // ...
}

저장소 fixture가 검증하는 경우

quartz/util/slugCollisions.test.ts 파일은 충돌 감지 로직의 정확성을 검증하는 테스트 케이스를 포함합니다. 이 테스트를 통해 실제 빌드 환경에서 발생할 수 있는 시나리오를 확인할 수 있습니다.

• 충돌 없음: 서로 다른 슬러그와 빈 입력은 빈 배열을 반환합니다.
• 마지막 항목 승자: 두 파일과 세 파일 fixture 모두 마지막 항목을 winner로 지정합니다.
• 복수 충돌: a/index와 b/index가 동시에 겹치면 충돌 그룹 수가 2가 됩니다.
• 경고 표시: 패자에는 (shadowed), 승자에는 (used for this URL)이 붙습니다.
• 슬러그 없는 파일: slug가 없는 항목은 충돌 감지 대상에서 제외됩니다.

test("detects a two-file collision with winner = last file", () => {
  const content = makeContent([
    { slug: "foo/index", relativePath: "foo/foo.md" },
    { slug: "foo/index", relativePath: "foo/index.md" },
  ])
  const collisions = detectSlugCollisions(content)
  assert.strictEqual(collisions.length, 1)
  assert.strictEqual(collisions[0]!.winner.relativePath, "foo/index.md")
})

경고를 읽고 충돌을 해소하는 절차

빌드 경고가 발생했을 때 충돌을 해결하기 위해 다음과 같은 점검 순서를 따릅니다.

1. 경고 개수 확인: 빌드 로그에서 Warning: X slug collisions detected.를 찾습니다. 여기서 X는 파일 수가 아니라 충돌한 슬러그 그룹 수입니다.
2. 충돌 슬러그 식별: 이어지는 slug \…“ 줄에서 겹친 URL을 확인합니다.
3. 파일 목록 대조: (shadowed)가 붙은 파일과 (used for this URL)이 붙은 파일을 모두 확인합니다.
4. 승자 확인: (used for this URL) 파일이 현재 처리 순서에서 마지막 항목이며 최종 URL에 사용됩니다.
5. 원인 제거: 의도한 한 파일만 그 슬러그를 만들도록 파일명이나 폴더 구조를 바꾸고 다시 빌드합니다.

특히 Obsidian을 사용하는 경우 folder/index.md와 folder/folder.md가 같은 슬러그를 만들 수 있습니다. 경고의 승자를 그대로 받아들이기보다 둘 중 어느 파일이 해당 URL을 소유해야 하는지 정한 뒤 나머지 경로를 바꾸는 편이 안전합니다.

npm test로 직접 재현하는 순서

임시 Markdown 파일을 추가할 필요는 없습니다. 저장소 루트에서 기존 fixture를 그대로 실행합니다.

npm test

scripts/run-tests.mjs는 quartz/**/*.test.ts와 scripts/**/*.test.ts를 모아 Node 테스트 러너에 전달합니다. 전체 실행 결과에서 quartz/util/slugCollisions.test.ts의 테스트가 통과했는지 확인한 다음, 해당 파일의 fixture와 assertion을 함께 읽습니다. 판정 기준은 다음과 같습니다.

• 서로 다른 슬러그를 넣은 fixture의 결과가 []여야 합니다.
• 같은 슬러그를 가진 배열에서는 마지막 항목이 winner여야 합니다.
• 단일 경고에는 (shadowed)와 (used for this URL)이 각각 나타나야 합니다.
• 두 그룹 fixture의 헤더에는 2 slug collisions detected가 나타나야 합니다.

이 검사는 테스트 러너의 테스트 발견·실행·종료 코드에 의존합니다. 명령행 옵션과 출력 형식은 Node.js Test Runner 공식 문서에서 확인할 수 있습니다. fixture가 통과하면 탐지 함수와 경고 문자열의 계약을 재현한 것이고, 현재 콘텐츠 전체에 충돌이 없다는 뜻까지 보장하는 것은 아닙니다.

이 방법이 통하지 않는 조건과 한계

이 충돌 감지 로직은 빌드 단계에서 동작하므로, 이미 빌드된 결과물에서 충돌을 해결하는 데는 직접적인 도움이 되지 않습니다. 또한, 이 로직은 파일의 내용이나 메타데이터를 비교하지 않고 오직 슬러그 값만을 기준으로 충돌을 감지합니다. 따라서 슬러그는 다르지만 내용이 중복되는 파일은 감지하지 못합니다.

또한, 이 설명은 quartz/util/slugCollisions.ts와 quartz/util/slugCollisions.test.ts의 현재 계약에 한정됩니다. 다른 정적 사이트 생성기나 커스텀 플러그인에는 그대로 적용되지 않습니다. 파싱 배열의 순서가 설정이나 구현 변경으로 달라지면 승자도 달라질 수 있으므로, 장기적인 해결책은 처리 순서에 기대는 것이 아니라 슬러그를 하나로 만드는 것입니다.