Pular para o conteúdo
@aws/nx-plugin
Blog

Licença

Gerencie automaticamente arquivos LICENSE e cabeçalhos de código fonte em seu workspace.

Este gerador registra um sync generator para executar como parte dos seus targets lint, garantindo que seus arquivos fonte estejam em conformidade com o conteúdo e formato desejado da licença, além de assegurar que os arquivos LICENSE do seu projeto estejam corretos e que as informações de licenciamento estejam incluídas em arquivos relevantes do projeto (package.json, pyproject.toml).

Utilização

Executar o Gerador

  1. Instale o Nx Console VSCode Plugin se ainda não o fez
  2. Abra o console Nx no VSCode
  3. Clique em Generate (UI) na seção "Common Nx Commands"
  4. Procure por @aws/nx-plugin - license
  5. Preencha os parâmetros obrigatórios
    • Clique em Generate

    Opções

    Parâmetro Tipo Padrão Descrição
    license string Apache-2.0 SPDX License Identifier for your chosen license
    copyrightHolder string Amazon.com, Inc. or its affiliates The copyright holder, included in the LICENSE file and source file headers by default.

    Saída do Gerador

    O gerador criará ou atualizará os seguintes arquivos:

    • nx.json O target lint é configurado para executar o sync generator de licença
    • aws-nx-plugin.config.mts Configuração para o sync generator de licença

    Uma configuração padrão para conteúdo e formato de cabeçalhos de licença é adicionada ao aws-nx-plugin.config.mts para escrever cabeçalhos apropriados para vários tipos de arquivo. Você pode personalizar isso posteriormente; consulte a seção de configuração abaixo.

    Fluxo de Trabalho

    Sempre que você construir seus projetos (e um target lint for executado), o sync generator de licença garantirá que o licenciamento em seu projeto corresponda à sua configuração (veja comportamento de sincronização de licença abaixo). Se detectar que algo está desatualizado, você receberá uma mensagem como:

    Terminal window
      NX   O workspace está desatualizado
    

    [@aws/nx-plugin:license#sync]: Arquivos LICENSE do projeto estão desatualizados:
    - LICENSE
    - packages/<meu-projeto>LICENSE
    

    Arquivos package.json do projeto estão desatualizados:
    - package.json
    

    Arquivos pyproject.toml do projeto estão desatualizados:
    - pyproject.toml
    - packages/<meu-projeto-python>/pyproject.toml
    

    Cabeçalhos de licença estão desatualizados nos seguintes arquivos fonte:
    - packages/<meu-projeto>/src/index.ts
    - packages/<meu-projeto-python>/main.py
    

    Isso resultará em um erro no CI.
    

    ? Deseja sincronizar as alterações identificadas para atualizar seu workspace?
    Sim, sincronizar as alterações e executar as tasks
    Não, executar as tasks sem sincronizar as alterações

    Selecione Sim para sincronizar as alterações.

    Comportamento de Sincronização de Licença

    O sync generator de licença executa três tarefas principais:

    1. Sincronizar Cabeçalhos de Licença em Arquivos Fonte

    Quando executado, o sync generator garantirá que todos os arquivos fonte do workspace (baseado em sua configuração) contenham o cabeçalho de licença apropriado. O cabeçalho é escrito como o primeiro bloco de comentário ou série consecutiva de comentários de linha no arquivo (além do shebang/hashbang, se presente).

    Você pode atualizar a configuração a qualquer momento para alterar quais arquivos devem ser incluídos/excluídos, bem como o conteúdo ou formato dos cabeçalhos para diferentes tipos de arquivo. Para detalhes, consulte a seção de configuração.

    2. Sincronizar Arquivos LICENSE

    Quando executado, o sync generator garantirá que o arquivo raiz LICENSE corresponda à licença configurada, além de verificar que todos os subprojetos no workspace contenham o arquivo LICENSE correto.

    Você pode excluir projetos na configuração se necessário. Para detalhes, consulte a seção de configuração.

    3. Sincronizar Informações de Licença em Arquivos de Projeto

    Quando executado, o sync generator garantirá que os campos license em arquivos package.json e pyproject.toml estejam definidos conforme sua licença configurada.

    Você pode excluir projetos na configuração se necessário. Para detalhes, consulte a seção de configuração.

    Configuração

    A configuração é definida no arquivo aws-nx-plugin.config.mts na raiz do workspace.

    SPDX e Detentor dos Direitos Autorais

    Sua licença pode ser atualizada a qualquer momento via propriedade spdx:

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

    Quando o sync generator é executado, todos os arquivos LICENSE, package.json e pyproject.toml serão atualizados para refletir a licença configurada.

    Você pode configurar adicionalmente o detentor dos direitos autorais e o ano, que são incluídos em alguns arquivos LICENSE:

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

    Cabeçalhos de Licença

    Conteúdo

    O conteúdo do cabeçalho pode ser configurado de duas formas:

    1. Usando conteúdo inline:
    aws-nx-plugin.config.mts
    export default {
      license: {
        header: {
          content: {
            lines: [
              'Copyright: My Company, Incorporated.',
              'Licensed under the MIT License',
              'All rights reserved',
            ];
          }
          // ... configuração de formato
        }
      }
    } satisfies AwsNxPluginConfig;
    1. Carregando de um arquivo:
    aws-nx-plugin.config.mts
    export default {
      license: {
        header: {
          content: {
            filePath: 'license-header.txt'; // relativo à raiz do workspace
          }
          // ... configuração de formato
        }
      }
    } satisfies AwsNxPluginConfig;

    Formato

    Você pode especificar como os cabeçalhos são formatados para diferentes tipos de arquivo usando padrões glob. A configuração suporta comentários de linha, bloco ou combinação de ambos:

    aws-nx-plugin.config.mts
    export default {
      license: {
        header: {
          content: {
            lines: ['Copyright notice here'],
          },
          format: {
            // Comentários de linha
            '**/*.ts': {
              lineStart: '// ',
            },
            // Comentários de bloco
            '**/*.css': {
              blockStart: '/*',
              blockEnd: '*/',
            },
            // Comentários de bloco com prefixos
            '**/*.java': {
              blockStart: '/*',
              lineStart: ' * ',
              blockEnd: ' */',
            },
            // Comentários de linha com cabeçalho/rodapé
            '**/*.py': {
              blockStart: '# ------------',
              lineStart: '# ',
              blockEnd: '# ------------',
            },
          },
        },
      },
    } satisfies AwsNxPluginConfig;

    A configuração de formato suporta:

    • blockStart: Texto antes do conteúdo da licença (ex: iniciar bloco de comentário)
    • lineStart: Texto pré-pendido em cada linha
    • lineEnd: Texto pós-pendido em cada linha
    • blockEnd: Texto após o conteúdo da licença (ex: finalizar bloco de comentário)

    Sintaxe de Comentário Personalizada

    Para tipos de arquivo não suportados nativamente, você pode especificar sintaxe personalizada para identificar cabeçalhos existentes:

    aws-nx-plugin.config.mts
    export default {
      license: {
        header: {
          content: {
            lines: ['My license header'],
          },
          format: {
            '**/*.xyz': {
              lineStart: '## ',
            },
          },
          commentSyntax: {
            xyz: {
              line: '##', // Define sintaxe de comentário de linha
            },
            abc: {
              block: {
                // Define sintaxe de comentário de bloco
                start: '<!--',
                end: '-->',
              },
            },
          },
        },
      },
    } satisfies AwsNxPluginConfig;

    Excluir Arquivos

    Por padrão, em repositórios git, todos os arquivos .gitignore são respeitados. Em repositórios não-git, todos os arquivos são considerados a menos que explicitamente excluídos na configuração.

    Você pode excluir arquivos adicionais usando padrões glob:

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

    Excluir Arquivos de Projeto da Sincronização

    Todos os arquivos LICENSE, package.json e pyproject.toml são sincronizados por padrão.

    Você pode excluir projetos ou arquivos específicos usando padrões glob:

    aws-nx-plugin.config.mts
    export default {
      license: {
        files: {
          exclude: [
            // não sincroniza LICENSE, package.json ou pyproject.toml
            'packages/excluded-project',
            // não sincroniza LICENSE, mas sincroniza package.json/pyproject.toml
            'apps/internal/LICENSE',
          ];
        }
      }
    } satisfies AwsNxPluginConfig;

    Desativar Sincronização de Licença

    Para desativar o sync generator de licença:

    1. Remova a seção license do aws-nx-plugin.config.mts (ou remova o arquivo)
    2. Remova o gerador @aws/nx-plugin:license#sync de targetDefaults.lint.syncGenerators

    Para reativar, execute novamente o gerador license.