GitHub의 Languages에 Astro나 CSS가 표시되어 있더라도, 이용 중인 PR 영향 분석 도구에 따라서는 .ts와 .js만 보고 있을 수 있습니다. 프론트엔드 리포지토리에서는 이러한 차이가 발생하기 쉽습니다.

특히 여러 개의 AI coding agent가 동일한 리포지토리에서 PR을 병렬로 생성하면, 한쪽은 Astro 컴포넌트를 수정하고 다른 한쪽은 CSS Modules나 Sass 공통 파일을 수정할 수 있습니다. 파일명이 다르기 때문에 단순한 동일 파일 비교만으로는 관계를 놓치게 됩니다.

이 기사에서는 GitHub Languages를 읽는 법과, Astro/CSS를 포함하는 PR에서 merge 전에 확인하고 싶은 의존 관계를 정리합니다.

GitHub Languages는 「구성비」이며, 해석 대응표가 아니다

GitHub 리포지토리 화면에 있는 Languages 바는 해당 리포지토리를 구성하는 언어의 개요입니다.

GitHub 공식 문서에 따르면, 언어 판정에는 Linguist가 사용되며, 결과는 구문 강조(Syntax Highlighting)나 리포지토리 통계에 이용됩니다. 기본 브랜치(Default branch)로 push한 후에 통계가 업데이트됩니다.

따라서, Languages에 Astro나 CSS가 표시되는 것과, 이용 중인 PR 분석·리뷰·의존 관계 도구가 그것들을 다룰 수 있는 것은 별개의 문제입니다.

확인할 때는 다음 두 가지를 구분해야 합니다.

• 리포지토리에 무엇이 포함되어 있는가: GitHub Languages의 구성비를 확인
• 도구가 무엇을 관계로 취급하는가: 대응 확장자뿐만 아니라, import나 참조를 어떻게 다루는지 확인

「TypeScript 대응」이라고 적혀 있더라도, .astro의 frontmatter, 템플릿, <style>, 외부 CSS까지 동일하게 다뤄진다는 보장은 없습니다.

.astro는 TypeScript와 HTML의 경계를 넘나든다

Astro 공식 문서에서는 Astro 컴포넌트가 주로 Component Script와 Component Template 두 가지로 구성된다고 설명합니다. ---로 둘러싸인 Component Script에서는 다른 Astro 컴포넌트, React 등의 프레임워크 컴포넌트, 데이터를 import할 수 있습니다. Component Template에서는 HTML과 JavaScript 식을 조합합니다.

예를 들어, 다음 1개의 파일에는 여러 관계가 있습니다.

---
import ProductCard from '../components/ProductCard.astro';
import { loadProducts } from '../data/products';
...

이 파일을 단순한 HTML로 취급하면, frontmatter의 import나 함수 호출을 놓치게 됩니다. 반대로 TypeScript로만 취급하면, 템플릿 측의 컴포넌트 이용이나 스타일과의 경계를 놓치게 됩니다.

PR의 영향 범위를 보는 것이 목적이라면, 적어도 다음을 구분하고 이용 중인 도구가 어디까지 다루는지 확인할 필요가 있습니다.

• frontmatter에서 import되는 Astro・TypeScript・JavaScript 파일
• 템플릿에서 이용되는 컴포넌트
• frontmatter에서 읽어오는 외부 스타일시트
• .astro 내의 <style>과 Sass 등의 preprocessor 지정

확장자를 대응 목록에 추가하는 것만으로는 부족하며, 1개의 파일 안에 서로 다른 언어 영역이 있다는 전제가 필요합니다.

@import도 PR끼리 연결한다

CSS Modules와 CSS는 겉보기에만 독립된 파일인 것이 아닙니다. JavaScript나 TypeScript에서 import되며, 또 다른 CSS나 Sass를 참조하기도 합니다.

CSS Modules

Vite 공식 문서에 따르면, .module.css로 끝나는 파일은 CSS Modules로 취급되며, import하면 대응하는 module object가 반환됩니다. preprocessor와 조합한 style.module.scss도 이용할 수 있습니다.

import styles from './ProductCard.module.scss';
export function ProductCard() {
return <article className={styles.card}>...</article>;
...

이 경우, .tsx와 .module.scss는 별개의 파일이지만 직접적인 관계를 맺고 있습니다. 만약 PR A가 컴포넌트를 변경하고, PR B가 동일한 모듈의 클래스(class) 구성을 변경한다면, 머지(merge) 전에 함께 확인해야 할 대상입니다.

@import와 Sass

Vite의 CSS 기능은 CSS의 @import를 처리하며, Sass나 Less에서도 에일리어스(alias) 해결이나 URL 조정을 수행합니다. 또한 .scss, .sass, .less 등의 프리프로세서(preprocessor)를 지원합니다.

@use './tokens' as tokens;
@import './responsive.css';
.card {
...

공통 토큰(token)이나 import 대상을 변경하는 PR은 해당 파일을 직접 수정하지 않은 여러 화면에 영향을 미칩니다. src/styles/를 "코드가 아님"으로 일괄 제외해 버리면, 이러한 관계가 확인 대상에서 사라지게 됩니다.

Astro의 Styles and CSS 가이드에서도 .astro의 프론트매터(frontmatter)에서 로컬 스타일시트(stylesheet)를 ESM import할 수 있으며, .scss 등의 프리프로세서(preprocessor) 파일에도 동일한 형식을 사용할 수 있다고 설명되어 있습니다.

Astro/CSS를 포함하는 PR에서 확인하는 체크리스트

AI가 만든 PR이든 사람이 만든 PR이든, 머지(merge) 전 확인 항목은 동일합니다. Astro/CSS가 있는 리포지토리(repository)에서는 다음 사항을 확인합니다.

1. .astro의 프론트매터(frontmatter)만 보고 끝내지 않았는가

컴포넌트 스크립트(Component Script)의 import 외에도, 템플릿(Template)에서 사용하는 컴포넌트, 외부 스타일시트(stylesheet), <style>의 변경 사항을 확인합니다.

2. CSS import를 의존 관계에서 제외하지 않았는가

import './global.css', CSS 모듈(CSS Modules), Astro 프론트매터(frontmatter)의 스타일시트(stylesheet) import를 대상에 포함합니다.

3. CSS 이후의 참조를 추적하고 있는가

@import, Sass의 @use나 @forward, 공통 토큰(token), 믹스인(mixin) 등 스타일시트(stylesheet) 간의 관계를 확인합니다.

4. 참조원별 확장자 해결(extension resolution)을 확인하고 있는가

확장자 해결 규칙은 참조원마다 다릅니다. JavaScript/TypeScript의 import, Astro 컴포넌트(component) import, Sass의 @use・@forward, 디렉토리의 index를 구분하여 확인합니다.

5. 동시에 오픈(open)되어 있는 PR과 비교했는가

하나의 PR을 단독으로 읽는 것만으로는 다른 PR이 공통 컴포넌트(component)나 스타일시트(stylesheet)를 변경하고 있다는 사실을 알 수 없습니다. 머지(merge) 직전뿐만 아니라, PR을 연 시점과 업데이트한 시점에 가로 방향의 관계를 다시 검토해야 합니다.

6. "관계를 찾을 수 없음"을 "안전함"으로 바꿔 말하고 있지 않은가

지원하지 않는 구문, 가져올 수 없었던 파일, 동적 참조는 남아있을 수 있습니다. 해석할 수 없었던 상태와, 확인했으나 관계가 희박한 상태를 구분하여 다루어야 합니다.

AI 병렬 개발에서는 언어 대응을 리포지토리(repository) 단위로 정리해야 한다

AI 코딩 에이전트(AI coding agent)를 늘리기 전에, 리포지토리(repository)의 언어(Languages)와 실제 파일 구성으로부터 확인 대상을 미리 정리해 두면 운영하기 수월해집니다.

언어 · 형식 | 확인하는 주요 관계
TypeScript/JS | import, export, 함수 · 컴포넌트 이용
Astro | frontmatter, template, component, stylesheet
...

GitHub Languages의 비율이 작은 언어도 제외 사유가 되지 않습니다. 불과 몇 %밖에 되지 않는 공통 스타일시트(stylesheet)나 레이아웃(layout)이 수많은 페이지에서 참조될 수 있기 때문입니다. 구성 비율이 아니라, PR끼리 연결되는 관계가 있는지에 따라 우선순위를 결정합니다.

Veripsa Core에서 Astro/CSS를 포함하는 PR을 확인하는 방법

Veripsa Core는 동일한 리포지토리(repository)에서 오픈(open)되어 있는 PR에 대해, Astro · CSS · Sass · CSS 모듈(CSS Modules)을 포함하는 변경 사항도 확인 대상에 포함합니다. 결과는 GitHub checks로 보고하며, 필요에 따라 PR 코멘트(comment)로도 출력합니다. 동적 참조나 지원하지 않는 구문까지 모두 망라하는 것은 아니며, 결과가 곧 안전성의 증명은 아닙니다.

처음에는 선택한 1개의 리포지토리(repository)에 설치하여, 브랜치 보호(branch protection) 설정을 변경하지 않고도 출력을 확인할 수 있습니다.

GitHub Languages는 리포지토리를 파악하는 입구입니다. PR(Pull Request)의 영향 범위를 확인할 때는, 해당 바(bar)의 내역을 실제 import, component, stylesheet 간의 관계로 연결하여 살펴볼 필요가 있습니다.

Discussion