콘텐츠로 이동
@aws/nx-plugin
Blog

라이선스

작업 공간 전체의 라이선스를 관리합니다: 자체 코드에 대한 LICENSE 파일 및 소스 코드 헤더를 동기화하고(license.source), 모든 의존성이 라이선스 허용 목록을 준수하는지 확인합니다(license.dependencies).

사용 방법

섹션 제목: “사용 방법”

생성기 실행

섹션 제목: “생성기 실행”
  1. 설치 Nx Console VSCode Plugin 아직 설치하지 않았다면
  2. VSCode에서 Nx 콘솔 열기
  3. 클릭 Generate (UI) "Common Nx Commands" 섹션에서
  4. 검색 @aws/nx-plugin - license
  5. 필수 매개변수 입력
    • 클릭 Generate

    옵션

    섹션 제목: “옵션”
    매개변수타입기본값설명
    license Apache-2.0 | MIT | ASLApache-2.0선택한 라이선스의 SPDX 라이선스 식별자
    copyrightHolder stringAmazon.com, Inc. or its affiliates저작권 보유자, 기본적으로 LICENSE 파일 및 소스 파일 헤더에 포함됩니다.
    dependencyCheck booleantrue구성된 허용 목록 외의 라이선스를 선언하는 의존성이 있을 때 실패하는 license-check 대상을 구성합니다.
    preferInstallDependencies booleantrue생성기 실행 후 의존성 설치를 선호할지 여부입니다. 여러 생성기를 일괄 처리할 때 설치를 연기하려면 false로 설정하세요 (후속 생성기가 Nx 프로젝트 그래프를 계산할 수 있도록 필요한 경우 설치는 여전히 실행됩니다); 마지막에 한 번만 설치합니다.

    생성기 출력

    섹션 제목: “생성기 출력”

    생성기는 다음 파일들을 생성하거나 업데이트합니다:

    • nx.json lint 대상이 라이선스 동기화 생성기를 실행하고 license-check 대상에 의존하도록 구성됨
    • aws-nx-plugin.config.mts 라이선스 소스 동기화(license.source) 및 의존성 검사(license.dependencies) 구성

    라이선스 헤더 및 파일

    섹션 제목: “라이선스 헤더 및 파일”

    생성기는 sync generator를 등록하여 lint 대상의 일부로 실행되며, 소스 파일에 올바른 라이선스 헤더가 포함되고, 프로젝트에 LICENSE 파일이 포함되며, package.json 및 pyproject.toml에 라이선스 메타데이터가 설정되도록 합니다.

    워크플로우

    섹션 제목: “워크플로우”

    프로젝트를 빌드할 때마다(lint 대상 실행 시) 라이선스 동기화 생성기는 프로젝트의 라이선스가 구성과 일치하는지 확인합니다. 동기화되지 않은 항목이 발견되면 다음과 같은 메시지가 표시됩니다:

    Terminal window
      NX   The workspace is out of sync
    

    [@aws/nx-plugin:license#sync]: Project LICENSE files are out of sync:
    - LICENSE
    - packages/<my-project>LICENSE
    

    Project package.json files are out of sync:
    - package.json
    

    Project pyproject.toml files are out of sync:
    - pyproject.toml
    - packages/<my-python-project>/pyproject.toml
    

    License headers are out of sync in the following source files:
    - packages/<my-project>/src/index.ts
    - packages/<my-python-project>/main.py
    

    This will result in an error in CI.
    

    ? Would you like to sync the identified changes to get your workspace up to date?
    Yes, sync the changes and run the tasks
    No, run the tasks without syncing the changes

    변경 사항을 동기화하려면 Yes를 선택하세요.

    동기화 동작

    섹션 제목: “동기화 동작”

    라이선스 동기화 생성기는 세 가지 주요 작업을 수행합니다:

    1. 소스 파일 라이선스 헤더 동기화

    섹션 제목: “1. 소스 파일 라이선스 헤더 동기화”

    동기화 생성기 실행 시 구성에 따라 작업 공간의 모든 소스 코드 파일에 적절한 라이선스 헤더가 포함되도록 합니다. 헤더는 파일의 첫 번째 블록 주석 또는 연속된 라인 주석으로 작성됩니다(파일에 shebang/hashbang이 있는 경우 제외).

    2. LICENSE 파일 동기화

    섹션 제목: “2. LICENSE 파일 동기화”

    동기화 생성기 실행 시 루트 LICENSE 파일이 구성된 라이선스와 일치하는지 확인하고, 작업 공간의 모든 하위 프로젝트에도 올바른 LICENSE 파일이 포함되도록 합니다.

    3. 프로젝트 파일 내 라이선스 정보 동기화

    섹션 제목: “3. 프로젝트 파일 내 라이선스 정보 동기화”

    동기화 생성기 실행 시 package.json 및 pyproject.toml 파일의 license 필드가 구성된 라이선스로 설정되도록 합니다.

    헤더 및 파일 구성

    섹션 제목: “헤더 및 파일 구성”

    구성은 작업 공간 루트의 aws-nx-plugin.config.mts 파일에서 정의됩니다.

    SPDX 및 저작권 소유자

    섹션 제목: “SPDX 및 저작권 소유자”

    라이선스는 spdx 구성 속성을 통해 언제든지 업데이트할 수 있습니다:

    aws-nx-plugin.config.mts
    export default {
      license: {
        source: {
          spdx: 'MIT',
        },
      },
    } satisfies AwsNxPluginConfig;

    동기화 생성기 실행 시 모든 LICENSE 파일, package.json 및 pyproject.toml 파일이 구성된 라이선스에 맞게 업데이트됩니다.

    일부 LICENSE 파일에 포함될 저작권 소유자 및 연도도 구성할 수 있습니다:

    aws-nx-plugin.config.mts
    export default {
      license: {
        source: {
          spdx: 'MIT',
          copyrightHolder: 'Amazon.com, Inc. or its affiliates',
          copyrightYear: 2025,
        },
      },
    } satisfies AwsNxPluginConfig;

    라이선스 헤더 내용

    섹션 제목: “라이선스 헤더 내용”

    라이선스 헤더 내용은 두 가지 방식으로 구성 가능:

    1. 인라인 내용 사용:
    aws-nx-plugin.config.mts
    export default {
      license: {
        source: {
          header: {
            content: {
              lines: [
                'Copyright: My Company, Incorporated.',
                'Licensed under the MIT License',
                'All rights reserved',
              ];
            }
            // ... 형식 구성
          }
        }
      }
    } satisfies AwsNxPluginConfig;
    1. 파일에서 로드:
    aws-nx-plugin.config.mts
    export default {
      license: {
        source: {
          header: {
            content: {
              filePath: 'license-header.txt'; // 작업 공간 루트 기준 상대 경로
            }
            // ... 형식 구성
          }
        }
      }
    } satisfies AwsNxPluginConfig;

    헤더 형식

    섹션 제목: “헤더 형식”

    글로브 패턴을 사용하여 다양한 파일 유형별 라이선스 헤더 형식을 지정할 수 있습니다. 형식 구성은 라인 주석, 블록 주석 또는 둘 다의 조합을 지원합니다:

    aws-nx-plugin.config.mts
    export default {
      license: {
        source: {
          header: {
            content: {
              lines: ['Copyright notice here'],
            },
            format: {
              // 라인 주석
              '**/*.ts': {
                lineStart: '// ',
              },
              // 블록 주석
              '**/*.css': {
                blockStart: '/*',
                blockEnd: '*/',
              },
              // 라인 접두사가 있는 블록 주석
              '**/*.java': {
                blockStart: '/*',
                lineStart: ' * ',
                blockEnd: ' */',
              },
              // 헤더/푸터가 있는 라인 주석
              '**/*.py': {
                blockStart: '# ------------',
                lineStart: '# ',
                blockEnd: '# ------------',
              },
            },
          },
        },
      },
    } satisfies AwsNxPluginConfig;

    형식 구성 지원 항목:

    • blockStart: 라이선스 내용 전에 작성될 텍스트 (예: 블록 주석 시작)
    • lineStart: 라이선스 내용 각 줄 앞에 추가될 텍스트
    • lineEnd: 라이선스 내용 각 줄 뒤에 추가될 텍스트
    • blockEnd: 라이선스 내용 후에 작성될 텍스트 (예: 블록 주석 종료)

    사용자 정의 주석 구문

    섹션 제목: “사용자 정의 주석 구문”

    기본 지원되지 않는 파일 유형의 경우, 사용자 정의 주석 구문을 지정하여 동기화 생성기가 기존 라이선스 헤더를 식별하도록 할 수 있습니다.

    aws-nx-plugin.config.mts
    export default {
      license: {
        source: {
          header: {
            content: {
              lines: ['My license header'],
            },
            format: {
              '**/*.xyz': {
                lineStart: '## ',
              },
            },
            commentSyntax: {
              xyz: {
                line: '##', // 라인 주석 구문 정의
              },
              abc: {
                block: {
                  // 블록 주석 구문 정의
                  start: '<!--',
                  end: '-->',
                },
              },
            },
          },
        },
      },
    } satisfies AwsNxPluginConfig;

    헤더 동기화에서 파일 제외

    섹션 제목: “헤더 동기화에서 파일 제외”

    기본적으로 git 저장소에서는 버전 관리 대상 파일만 동기화되도록 모든 .gitignore 파일이 적용됩니다. 비 git 저장소에서는 구성에서 명시적으로 제외하지 않는 한 모든 파일이 처리됩니다.

    글로브 패턴을 사용하여 라이선스 헤더 동기화에서 추가 파일을 제외할 수 있습니다:

    aws-nx-plugin.config.mts
    export default {
      license: {
        source: {
          header: {
            content: {
              lines: ['My license header'],
            },
            format: {
              '**/*.ts': {
                lineStart: '// ',
              },
            },
            exclude: ['**/generated/**', '**/dist/**', 'some-specific-file.ts'],
          },
        },
      },
    } satisfies AwsNxPluginConfig;

    파일 동기화에서 프로젝트 제외

    섹션 제목: “파일 동기화에서 프로젝트 제외”

    기본적으로 모든 LICENSE 파일, package.json 파일 및 pyproject.toml 파일이 구성된 라이선스와 동기화됩니다.

    글로브 패턴을 사용하여 특정 프로젝트나 파일을 동기화에서 제외할 수 있습니다:

    aws-nx-plugin.config.mts
    export default {
      license: {
        source: {
          files: {
            exclude: [
              // LICENSE 파일, package.json, pyproject.toml 동기화 제외
              'packages/excluded-project',
              // LICENSE 파일 동기화 제외 (package.json/pyproject.toml은 동기화 유지)
              'apps/internal/LICENSE',
            ];
          }
        }
      }
    } satisfies AwsNxPluginConfig;

    라이선스 동기화 비활성화

    섹션 제목: “라이선스 동기화 비활성화”

    라이선스 소스 동기화는 구성에 license.source 키가 있을 때 활성화됩니다. 비활성화하려면:

    1. aws-nx-plugin.config.mts 구성에서 license.source 섹션을 제거하세요 (의존성 라이선스 검사를 계속 원하는 경우 license.dependencies는 유지할 수 있습니다)
    2. 동기화 생성기를 완전히 제거하려면 targetDefaults.lint.syncGenerators에서 @aws/nx-plugin:license#sync 생성기를 제거하세요

    라이선스 동기화를 다시 활성화하려면 license 생성기를 다시 실행하세요.

    의존성 라이선스 검사

    섹션 제목: “의존성 라이선스 검사”

    license 생성기는 프로젝트의 의존성(또는 전이 의존성)이 허용 목록에 없는 라이선스를 선언할 때 실패하는 license-check 대상도 구성합니다.

    실행 방법

    섹션 제목: “실행 방법”

    생성기는 루트 project.json에 license-check 대상을 작성합니다:

    project.json
    {
      "targets": {
        "license-check": {
          "executor": "@aws/nx-plugin:license-check",
          "cache": true,
          "inputs": [
            "{workspaceRoot}/pnpm-lock.yaml",
            "{workspaceRoot}/aws-nx-plugin.config.mts"
          ],
          "options": {}
        }
      }
    }

    inputs는 작업 공간에 맞게 계산됩니다: 실제로 존재하는 lockfile만 포함되며, aws-nx-plugin.config.mts와 함께 Python 의존성 검사가 활성화된 경우(즉, Python 수집기가 구성된 경우) {workspaceRoot}/**/uv.lock 글로브가 추가됩니다.

    검사를 직접 실행할 수 있습니다:

    Terminal window
    pnpm nx license-check

    결과는 lockfile 및 aws-nx-plugin.config.mts에 대해 캐시됩니다 — 변경 사항이 없으면 재실행이 즉시 완료됩니다.

    수집기(Collector)가 스캔 대상을 결정합니다. npmCollector는 license-checker-rseidelsohn을 사용하고, pythonCollector는 pip-licenses를 사용합니다. 설치된 의존성이 없으면 검사할 항목이 없어 검사가 통과됩니다.

    lint/build의 일부로 실행

    섹션 제목: “lint/build의 일부로 실행”

    의존성 라이선스 검사는 작업 공간의 모든 프로젝트를 lint 또는 build할 때마다 자동으로 실행됩니다. license 생성기는 각 프로젝트의 lint 대상이 루트 license-check 대상에 의존하도록 연결하며, 프로젝트 생성기(ts#* 및 py#*)도 실행 시 동일하게 작동합니다 — 따라서 생성기가 실행되는 순서와 관계없이 검사가 연결됩니다.

    즉, 검사를 명시적으로 실행할 필요는 없지만, 여전히 license-check 대상으로 실행할 수 있습니다:

    Terminal window
    pnpm nx license-check

    연결은 각 프로젝트의 lint 대상에 대한 교차 프로젝트 dependsOn으로, 루트 license-check 대상을 가리킵니다. lint 또는 build 중에 검사를 건너뛰려면 LICENSE_DEPENDENCY_CHECK=skip 환경 변수를 설정하세요:

    Terminal window
    pnpm LICENSE_DEPENDENCY_CHECK=skip lint

    구성

    섹션 제목: “구성”

    기본적으로 검사는 DEFAULT_LICENSE_ALLOWLIST로 내보내지는 일반적인 허용 라이선스(MIT, Apache-2.0, BSD, ISC 등)의 내장 세트를 사용합니다. 구성에서 이를 확장하거나 재정의할 수 있습니다:

    aws-nx-plugin.config.mts
    import { AwsNxPluginConfig } from '@aws/nx-plugin';
    import { DEFAULT_LICENSE_ALLOWLIST } from '@aws/nx-plugin/sdk/license';
    

    export default {
      license: {
        // ...
        dependencies: {
          allow: [...DEFAULT_LICENSE_ALLOWLIST, { spdxId: 'LGPL-2.1-or-later', fullName: 'GNU Lesser General Public License v2.1 or later', aliases: [] }],
          exceptions: [
            { package: 'some-package', reason: 'Audited manually — ships MIT text without SPDX field' },
          ],
        },
      },
    } satisfies AwsNxPluginConfig;
    View the full list of licenses in DEFAULT_LICENSE_ALLOWLIST

    허용 목록 사용자 정의

    섹션 제목: “허용 목록 사용자 정의”

    허용 목록을 제한하려면 DEFAULT_LICENSE_ALLOWLIST를 자체 배열로 교체하세요. 확장하려면 기본값을 전개하고 항목을 추가하세요. 항목은 SPDX ID, 전체 라이선스 이름 또는 나열된 별칭(대소문자 구분 없음)으로 일치됩니다.

    패키지별 예외

    섹션 제목: “패키지별 예외”

    검사에 실패하는 패키지에 대해 exceptions를 사용하세요 — 라이선스가 허용 목록에 없거나 감지 가능한 라이선스 메타데이터 없이 제공되는 경우입니다. reason 필드는 검토자가 예외가 부여된 이유를 확인할 수 있도록 필수입니다.

    exceptions: [
      {
        package: 'union',
        version: '0.5.0',
        reason: 'Package ships verbatim MIT text without declaring license',
      },
    ];

    문제가 있는 메타데이터를 가진 의존성을 도입하는 생성기(예: MCP 서버 생성기)는 실행 시 필요한 예외를 구성에 자동으로 추가합니다.

    수집기

    섹션 제목: “수집기”

    수집기는 의존성을 발견하고 라이선스 메타데이터를 추출합니다. 내장 수집기는 npmCollector()(node_modules 스캔) 및 pythonCollector()(Python 가상 환경 스캔)입니다. 라이선스 생성기는 기본적으로 npmCollector()를 구성하고 Python 프로젝트가 있을 때 pythonCollector()를 추가합니다.

    사용자 정의 수집기를 구현하려면 LicenseCollector 인터페이스를 준수하세요:

    import type { LicenseCollector } from '@aws/nx-plugin/sdk/license';
    

    const myCollector = (): LicenseCollector => ({
      name: 'my-ecosystem',
      traceCommand: 'my-tool why <package>',
      async collect({ workspaceRoot }) {
        return [
          { name: 'some-dep', version: '1.0.0', rawLicense: 'MIT', ecosystem: 'my-ecosystem' },
        ];
      },
    });

    onDependency 훅

    섹션 제목: “onDependency 훅”

    license.dependencies는 선택적 onDependency 콜백을 허용하며, 검사 통과 여부와 관계없이 발견된 모든 의존성에 대해 한 번씩 호출됩니다. { package, spdx }를 받으며, 여기서 package는 패키지 이름이고 spdx는 해석된 SPDX 라이선스 표현식입니다. 예외의 spdx는 원시 선언된 라이선스보다 우선하며, 라이선스가 선언되지 않은 경우 spdx는 빈 문자열일 수 있습니다.

    이는 프로젝트 전체의 모든 라이선스를 출력하는 편리한 방법입니다. license-check 대상을 실행하여 출력을 확인하세요:

    aws-nx-plugin.config.mts
    import { AwsNxPluginConfig } from '@aws/nx-plugin';
    import { DEFAULT_LICENSE_ALLOWLIST } from '@aws/nx-plugin/sdk/license';
    

    export default {
      license: {
        dependencies: {
          allow: DEFAULT_LICENSE_ALLOWLIST,
          onDependency: ({ package: pkg, spdx }) => {
            console.log(`${pkg} - ${spdx}`);
          },
        },
      },
    } satisfies AwsNxPluginConfig;

    의존성 검사 비활성화

    섹션 제목: “의존성 검사 비활성화”

    의존성 라이선스 검사는 구성에 license.dependencies 키가 있을 때 활성화됩니다.

    단일 실행에 대해 검사를 비활성화하려면 LICENSE_DEPENDENCY_CHECK=skip 환경 변수를 설정하세요:

    Terminal window
    pnpm LICENSE_DEPENDENCY_CHECK=skip lint

    영구적으로 비활성화하려면 aws-nx-plugin.config.mts 구성에서 license.dependencies 키를 제거하세요. --dependencyCheck=false로 license 생성기를 다시 실행하여 이 없이 스캐폴드할 수도 있습니다.