License

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

사용법

생성기 실행

CLI

pnpm

pnpm nx g @aws/nx-plugin:license

yarn

yarn nx g @aws/nx-plugin:license

npm

npx nx g @aws/nx-plugin:license

bun

bunx nx g @aws/nx-plugin:license

어떤 파일이 변경될지 확인하기 위해 드라이 런을 수행할 수도 있습니다

pnpm

pnpm nx g @aws/nx-plugin:license --dry-run

yarn

yarn nx g @aws/nx-plugin:license --dry-run

npm

npx nx g @aws/nx-plugin:license --dry-run

bun

bunx nx g @aws/nx-plugin:license --dry-run

VSCode

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

옵션

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

생성기 출력

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

• nx.json lint 타겟이 라이선스 동기화 생성기를 실행하도록 구성되며 license-check 타겟에 의존합니다
• aws-nx-plugin.config.mts 라이선스 소스 동기화(license.source) 및 의존성 확인(license.dependencies)을 위한 구성

라이선스 헤더 및 파일

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

워크플로

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

  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. 소스 파일 라이선스 헤더 동기화

동기화 생성기가 실행되면 워크스페이스의 모든 소스 코드 파일(구성 기반)에 적절한 라이선스 헤더가 포함되어 있는지 확인합니다. 헤더는 파일의 첫 번째 블록 주석 또는 연속된 라인 주석 시리즈로 작성됩니다(파일에 shebang/hashbang이 있는 경우 그 다음에 작성됨).

2. LICENSE 파일 동기화

동기화 생성기가 실행되면 루트 LICENSE 파일이 구성된 라이선스와 일치하는지 확인하고, 워크스페이스의 모든 하위 프로젝트에도 올바른 LICENSE 파일이 포함되어 있는지 확인합니다.

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

동기화 생성기가 실행되면 package.json 및 pyproject.toml 파일의 license 필드가 구성된 라이선스로 설정되어 있는지 확인합니다.

헤더 및 파일 구성

구성은 워크스페이스 루트의 aws-nx-plugin.config.mts 파일에 정의됩니다.

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',
          ];
        }
        // ... format configuration
      }
    }
  }
} satisfies AwsNxPluginConfig;

2. 파일에서 로드:

aws-nx-plugin.config.mts

export default {
  license: {
    source: {
      header: {
        content: {
          filePath: 'license-header.txt'; // relative to workspace root
        }
        // ... format configuration
      }
    }
  }
} satisfies AwsNxPluginConfig;

헤더 형식

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

aws-nx-plugin.config.mts

export default {
  license: {
    source: {
      header: {
        content: {
          lines: ['Copyright notice here'],
        },
        format: {
          // Line comments
          '**/*.ts': {
            lineStart: '// ',
          },
          // Block comments
          '**/*.css': {
            blockStart: '/*',
            blockEnd: '*/',
          },
          // Block comments with line prefixes
          '**/*.java': {
            blockStart: '/*',
            lineStart: ' * ',
            blockEnd: ' */',
          },
          // Line comments with header/footer
          '**/*.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: '##', // Define line comment syntax
          },
          abc: {
            block: {
              // Define block comment syntax
              start: '<!--',
              end: '-->',
            },
          },
        },
      },
    },
  },
} satisfies AwsNxPluginConfig;

헤더 동기화에서 파일 제외

기본적으로 git 저장소에서는 모든 .gitignore 파일이 적용되어 버전 관리되는 파일만 동기화됩니다. git이 아닌 저장소에서는 구성에서 명시적으로 제외하지 않는 한 모든 파일이 고려됩니다.

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

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 파일이 구성된 라이선스와 동기화됩니다.

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

aws-nx-plugin.config.mts

export default {
  license: {
    source: {
      files: {
        exclude: [
          // do not sync LICENSE file, package.json or pyproject.toml
          'packages/excluded-project',
          // do not sync LICENSE file, but sync package.json and/or 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 glob이 추가됩니다.

확인을 직접 실행할 수 있습니다:

pnpm

pnpm nx license-check

yarn

yarn nx license-check

npm

npx nx license-check

bun

bunx nx license-check

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

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

lint/build의 일부로 실행

의존성 라이선스 확인은 워크스페이스의 프로젝트를 lint 또는 build할 때마다 자동으로 실행됩니다. license 생성기는 각 프로젝트의 lint 타겟이 루트 license-check 타겟에 의존하도록 연결하며, 프로젝트 생성기(ts#* 및 py#*)도 실행될 때 동일하게 수행합니다 — 따라서 생성기가 실행되는 순서에 관계없이 확인이 연결됩니다.

즉, 확인을 명시적으로 실행할 필요는 없지만 license-check 타겟으로 여전히 실행할 수 있습니다:

pnpm

pnpm nx license-check

yarn

yarn nx license-check

npm

npx nx license-check

bun

bunx nx license-check

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

pnpm

pnpm LICENSE_DEPENDENCY_CHECK=skip lint

yarn

yarn LICENSE_DEPENDENCY_CHECK=skip lint

npm

npm run LICENSE_DEPENDENCY_CHECK=skip lint

bun

bun 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;

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 훅

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 환경 변수를 설정하세요:

pnpm

pnpm LICENSE_DEPENDENCY_CHECK=skip lint

yarn

yarn LICENSE_DEPENDENCY_CHECK=skip lint

npm

npm run LICENSE_DEPENDENCY_CHECK=skip lint

bun

bun LICENSE_DEPENDENCY_CHECK=skip lint

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