Bỏ qua để đến nội dung
@aws/nx-plugin
Blog

Giấy phép

Quản lý cấp phép trong toàn bộ workspace của bạn: đồng bộ các tệp LICENSE và header mã nguồn cho code của riêng bạn (license.source), đồng thời kiểm tra rằng mọi dependency tuân thủ danh sách giấy phép được phép (license.dependencies).

Cách sử dụng

Phần tiêu đề “Cách sử dụng”

Chạy Generator

Phần tiêu đề “Chạy Generator”
  1. Cài đặt Nx Console VSCode Plugin nếu bạn chưa cài đặt
  2. Mở Nx Console trong VSCode
  3. Nhấp Generate (UI) trong phần "Common Nx Commands"
  4. Tìm kiếm @aws/nx-plugin - license
  5. Điền các tham số bắt buộc
    • Nhấp Generate

    Tùy chọn

    Phần tiêu đề “Tùy chọn”
    Tham sốKiểuMặc địnhMô tả
    license Apache-2.0 | MIT | ASLApache-2.0Mã định danh giấy phép SPDX cho giấy phép bạn đã chọn
    copyrightHolder stringAmazon.com, Inc. or its affiliatesNgười giữ bản quyền, được bao gồm trong tệp LICENSE và phần đầu của các tệp mã nguồn theo mặc định.
    dependencyCheck booleantrueCấu hình một target license-check sẽ thất bại khi các dependency khai báo giấy phép nằm ngoài danh sách cho phép đã cấu hình.
    preferInstallDependencies booleantrueCó nên cài đặt các dependencies sau khi generator chạy hay không. Đặt thành false để hoãn việc cài đặt khi chạy nhiều generator cùng lúc (việc cài đặt vẫn sẽ chạy nếu cần thiết để các generator tiếp theo có thể tính toán Nx project graph); cài đặt một lần vào cuối.

    Đầu ra của Generator

    Phần tiêu đề “Đầu ra của Generator”

    Generator sẽ tạo hoặc cập nhật các tệp sau:

    • nx.json Target lint được cấu hình để chạy license sync generator và phụ thuộc vào target license-check
    • aws-nx-plugin.config.mts Cấu hình cho đồng bộ nguồn giấy phép (license.source) và kiểm tra dependency (license.dependencies)

    License Header & Tệp

    Phần tiêu đề “License Header & Tệp”

    Generator này đăng ký một sync generator để thực thi như một phần của các target lint của bạn, đảm bảo rằng các tệp nguồn của bạn chứa các license header chính xác, các dự án của bạn chứa các tệp LICENSE, và metadata cấp phép được thiết lập trong package.json và pyproject.toml.

    Quy trình làm việc

    Phần tiêu đề “Quy trình làm việc”

    Mỗi khi bạn build các dự án của mình (và target lint chạy), license sync generator sẽ đảm bảo rằng việc cấp phép trong dự án của bạn khớp với cấu hình của bạn. Nếu nó phát hiện bất kỳ điều gì không đồng bộ, bạn sẽ nhận được thông báo như sau:

    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

    Chọn Yes để đồng bộ các thay đổi.

    Hành vi đồng bộ

    Phần tiêu đề “Hành vi đồng bộ”

    License sync generator thực hiện ba nhiệm vụ chính:

    1. Đồng bộ License Header của tệp nguồn

    Phần tiêu đề “1. Đồng bộ License Header của tệp nguồn”

    Khi sync generator chạy, nó sẽ đảm bảo rằng tất cả các tệp mã nguồn trong workspace của bạn (dựa trên cấu hình của bạn) chứa license header phù hợp. Header được viết dưới dạng block comment đầu tiên hoặc chuỗi line comment liên tiếp trong tệp (ngoài shebang/hashbang nếu có trong tệp).

    2. Đồng bộ các tệp LICENSE

    Phần tiêu đề “2. Đồng bộ các tệp LICENSE”

    Khi sync generator chạy, nó sẽ đảm bảo rằng tệp LICENSE gốc tương ứng với giấy phép đã cấu hình của bạn, cũng như đảm bảo rằng tất cả các dự án con trong workspace của bạn cũng chứa tệp LICENSE chính xác.

    3. Đồng bộ thông tin cấp phép trong các tệp dự án

    Phần tiêu đề “3. Đồng bộ thông tin cấp phép trong các tệp dự án”

    Khi sync generator chạy, nó sẽ đảm bảo các trường license trong các tệp package.json và pyproject.toml được đặt theo giấy phép đã cấu hình của bạn.

    Cấu hình Header & Tệp

    Phần tiêu đề “Cấu hình Header & Tệp”

    Cấu hình được định nghĩa trong tệp aws-nx-plugin.config.mts ở thư mục gốc của workspace của bạn.

    Phần tiêu đề “SPDX và Copyright Holder”

    Giấy phép bạn chọn có thể được cập nhật bất cứ lúc nào thông qua thuộc tính cấu hình spdx:

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

    Khi sync generator chạy, tất cả các tệp LICENSE, package.json và pyproject.toml sẽ được cập nhật để phản ánh giấy phép đã cấu hình.

    Bạn có thể cấu hình thêm chủ sở hữu bản quyền và năm bản quyền, được bao gồm trong một số tệp LICENSE:

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

    Nội dung License Header

    Phần tiêu đề “Nội dung License Header”

    Nội dung license header có thể được cấu hình theo hai cách:

    1. Sử dụng nội dung inline:
    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;
    1. Tải từ một tệp:
    aws-nx-plugin.config.mts
    export default {
      license: {
        source: {
          header: {
            content: {
              filePath: 'license-header.txt'; // relative to workspace root
            }
            // ... format configuration
          }
        }
      }
    } satisfies AwsNxPluginConfig;

    Định dạng Header

    Phần tiêu đề “Định dạng Header”

    Bạn có thể chỉ định cách license header nên được định dạng cho các loại tệp khác nhau bằng cách sử dụng các mẫu glob. Cấu hình định dạng hỗ trợ line comment, block comment, hoặc kết hợp cả hai:

    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;

    Cấu hình định dạng hỗ trợ:

    • blockStart: Văn bản được viết trước nội dung giấy phép (ví dụ: để bắt đầu block comment)
    • lineStart: Văn bản được thêm vào đầu mỗi dòng của nội dung giấy phép
    • lineEnd: Văn bản được thêm vào cuối mỗi dòng của nội dung giấy phép
    • blockEnd: Văn bản được viết sau nội dung giấy phép (ví dụ: để kết thúc block comment)

    Cú pháp Comment tùy chỉnh

    Phần tiêu đề “Cú pháp Comment tùy chỉnh”

    Đối với các loại tệp không được hỗ trợ sẵn, bạn có thể chỉ định cú pháp comment tùy chỉnh để cho sync generator biết cách xác định các license header hiện có trong các loại tệp này.

    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;

    Loại trừ tệp khỏi đồng bộ Header

    Phần tiêu đề “Loại trừ tệp khỏi đồng bộ Header”

    Theo mặc định, trong một repository git, tất cả các tệp .gitignore được tôn trọng để đảm bảo rằng chỉ các tệp được quản lý bởi hệ thống quản lý phiên bản mới được đồng bộ. Trong các repository không phải git, tất cả các tệp đều được xem xét trừ khi được loại trừ rõ ràng trong cấu hình.

    Bạn có thể loại trừ các tệp bổ sung khỏi việc đồng bộ license header bằng cách sử dụng các mẫu 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;

    Loại trừ các dự án khỏi đồng bộ tệp

    Phần tiêu đề “Loại trừ các dự án khỏi đồng bộ tệp”

    Tất cả các tệp LICENSE, tệp package.json và tệp pyproject.toml được đồng bộ với giấy phép đã cấu hình theo mặc định.

    Bạn có thể loại trừ các dự án hoặc tệp cụ thể khỏi việc đồng bộ bằng cách sử dụng các mẫu 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;

    Vô hiệu hóa đồng bộ giấy phép

    Phần tiêu đề “Vô hiệu hóa đồng bộ giấy phép”

    Đồng bộ nguồn giấy phép được kích hoạt bởi sự hiện diện của khóa license.source trong cấu hình của bạn. Để vô hiệu hóa nó:

    1. Xóa phần license.source khỏi cấu hình của bạn trong aws-nx-plugin.config.mts (bạn có thể giữ license.dependencies nếu bạn vẫn muốn kiểm tra giấy phép dependency)
    2. Nếu bạn cũng muốn xóa hoàn toàn sync generator, hãy xóa generator @aws/nx-plugin:license#sync khỏi targetDefaults.lint.syncGenerators

    Để kích hoạt lại đồng bộ giấy phép, chỉ cần chạy lại generator license.

    Kiểm tra giấy phép Dependency

    Phần tiêu đề “Kiểm tra giấy phép Dependency”

    Generator license cũng cấu hình một target license-check sẽ thất bại khi một trong các dependency của dự án của bạn (hoặc bất kỳ transitive dependency nào) khai báo một giấy phép không có trong danh sách được phép của bạn.

    Cách nó chạy

    Phần tiêu đề “Cách nó chạy”

    Generator ghi một target license-check vào project.json gốc của bạn:

    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": {}
        }
      }
    }

    Các inputs được tính toán cho workspace của bạn: chỉ các lockfile thực sự có mặt mới được bao gồm, cùng với aws-nx-plugin.config.mts, cộng thêm một glob {workspaceRoot}/**/uv.lock khi kiểm tra dependency Python được bật (tức là một Python collector được cấu hình).

    Bạn có thể chạy kiểm tra trực tiếp:

    Terminal window
    pnpm nx license-check

    Kết quả được cache dựa trên các lockfile và aws-nx-plugin.config.mts của bạn — việc chạy lại sẽ tức thì khi không có gì thay đổi.

    Các collector xác định những gì được quét. npmCollector sử dụng license-checker-rseidelsohn, và pythonCollector sử dụng pip-licenses. Nếu không tìm thấy dependency đã cài đặt nào, kiểm tra sẽ pass mà không có gì để kiểm tra.

    Chạy như một phần của lint/build

    Phần tiêu đề “Chạy như một phần của lint/build”

    Kiểm tra giấy phép dependency chạy tự động mỗi khi bạn lint hoặc build bất kỳ dự án nào trong workspace của bạn. Generator license kết nối target lint của mỗi dự án để phụ thuộc vào target license-check gốc, và các project generator (ts#* và py#*) cũng làm điều tương tự khi chúng chạy — vì vậy kiểm tra được kết nối bất kể thứ tự các generator được chạy.

    Điều này có nghĩa là bạn không cần chạy kiểm tra một cách rõ ràng, mặc dù bạn vẫn có thể làm như vậy với target license-check:

    Terminal window
    pnpm nx license-check

    Kết nối là một dependsOn cross-project trên target lint của mỗi dự án trỏ đến target license-check gốc. Để bỏ qua kiểm tra trong quá trình lint hoặc build, hãy đặt biến môi trường LICENSE_DEPENDENCY_CHECK=skip:

    Terminal window
    pnpm LICENSE_DEPENDENCY_CHECK=skip lint

    Cấu hình

    Phần tiêu đề “Cấu hình”

    Theo mặc định, kiểm tra sử dụng một tập hợp các giấy phép cho phép phổ biến được tích hợp sẵn (MIT, Apache-2.0, BSD, ISC, v.v.) được xuất dưới dạng DEFAULT_LICENSE_ALLOWLIST. Bạn có thể mở rộng hoặc ghi đè điều này trong cấu hình của mình:

    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

    Tùy chỉnh danh sách được phép

    Phần tiêu đề “Tùy chỉnh danh sách được phép”

    Để hạn chế danh sách được phép, thay thế DEFAULT_LICENSE_ALLOWLIST bằng mảng của riêng bạn. Để mở rộng nó, spread mặc định và thêm các mục. Các mục được khớp theo SPDX id, tên giấy phép đầy đủ, hoặc bất kỳ alias nào được liệt kê (không phân biệt chữ hoa chữ thường).

    Ngoại lệ cho từng package

    Phần tiêu đề “Ngoại lệ cho từng package”

    Sử dụng exceptions cho các package thất bại trong kiểm tra — hoặc vì giấy phép của chúng không có trong danh sách được phép, hoặc vì chúng được ship mà không có metadata giấy phép có thể phát hiện được. Trường reason là bắt buộc để người đánh giá có thể thấy lý do tại sao ngoại lệ được cấp.

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

    Các generator giới thiệu các dependency với metadata có vấn đề (ví dụ: MCP server generator) sẽ tự động thêm các ngoại lệ cần thiết vào cấu hình của bạn khi chúng chạy.

    Collectors

    Phần tiêu đề “Collectors”

    Các collector khám phá các dependency và trích xuất metadata giấy phép. Các collector tích hợp sẵn là npmCollector() (quét node_modules) và pythonCollector() (quét các môi trường ảo Python). License generator cấu hình npmCollector() theo mặc định và thêm pythonCollector() khi có các dự án Python.

    Để triển khai một collector tùy chỉnh, tuân thủ interface 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' },
        ];
      },
    });

    Hook onDependency

    Phần tiêu đề “Hook onDependency”

    license.dependencies chấp nhận một callback onDependency tùy chọn được gọi một lần cho mỗi dependency được phát hiện, bất kể nó pass hay fail kiểm tra. Nó nhận { package, spdx }, trong đó package là tên package và spdx là biểu thức giấy phép SPDX đã được phân giải. spdx của một ngoại lệ được ưu tiên hơn giấy phép được khai báo thô, và spdx có thể là một chuỗi rỗng nếu không có giấy phép nào được khai báo.

    Đây là một cách tiện lợi để in ra tất cả các giấy phép trong dự án của bạn. Chạy target license-check để xem đầu ra:

    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;

    Vô hiệu hóa kiểm tra Dependency

    Phần tiêu đề “Vô hiệu hóa kiểm tra Dependency”

    Kiểm tra giấy phép dependency được kích hoạt bởi sự hiện diện của khóa license.dependencies trong cấu hình của bạn.

    Để vô hiệu hóa kiểm tra cho một lần chạy duy nhất, đặt biến môi trường LICENSE_DEPENDENCY_CHECK=skip:

    Terminal window
    pnpm LICENSE_DEPENDENCY_CHECK=skip lint

    Để vô hiệu hóa vĩnh viễn, xóa khóa license.dependencies khỏi cấu hình của bạn trong aws-nx-plugin.config.mts. Bạn cũng có thể chạy lại generator license với --dependencyCheck=false để scaffold mà không có nó.