License

Gerencie licenciamento em todo o seu workspace: sincronize arquivos LICENSE e cabeçalhos de código-fonte para o seu próprio código (license.source), e verifique se cada dependência está em conformidade com uma lista de licenças permitidas (license.dependencies).

Uso

Executar o Gerador

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

Você também pode realizar uma execução simulada para ver quais arquivos seriam alterados

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. 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
6. Clique em Generate

Opções

Parâmetro	Tipo	Padrão	Descrição
license	Apache-2.0 | MIT | ASL	Apache-2.0	Identificador SPDX da licença escolhida
copyrightHolder	string	Amazon.com, Inc. or its affiliates	O detentor dos direitos autorais, incluído no arquivo LICENSE e nos cabeçalhos dos arquivos de código-fonte por padrão.
dependencyCheck	boolean	true	Configurar um target de verificação de licença que falha quando as dependências declaram licenças fora da lista de permissões configurada.
preferInstallDependencies	boolean	true	Se deve preferir instalar dependências após a execução do gerador. Defina como false para adiar a instalação ao executar múltiplos geradores em lote (uma instalação ainda é executada se necessário para que geradores subsequentes possam calcular o grafo de projetos Nx); instale uma vez no final.

Saída do Gerador

O gerador criará ou atualizará os seguintes arquivos:

• nx.json O target lint é configurado para executar o gerador de sincronização de licença e depende do target license-check
• aws-nx-plugin.config.mts Configuração para sincronização de fonte de licença (license.source) e verificação de dependências (license.dependencies)

Cabeçalhos e Arquivos de Licença

O gerador registra um sync generator para executar como parte dos seus targets lint, o que garante que seus arquivos de origem contenham os cabeçalhos de licença corretos, seus projetos contenham arquivos LICENSE, e os metadados de licenciamento sejam definidos em package.json e pyproject.toml.

Fluxo de Trabalho

Sempre que você compilar seus projetos (e um target lint for executado), o gerador de sincronização de licença garantirá que o licenciamento em seu projeto corresponda à sua configuração. Se detectar que algo está fora de sincronia, você receberá uma mensagem como:

  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

Selecione Yes para sincronizar as alterações.

Revisar Alterações

Certifique-se de verificar as alterações que o gerador de sincronização de licença faz no controle de versão para garantir que quaisquer tarefas de build de integração contínua não falhem devido a licenças fora de sincronia.

Comportamento de Sincronização

O gerador de sincronização de licença executa três tarefas principais:

1. Sincronizar Cabeçalhos de Licença de Arquivos de Origem

Quando o gerador de sincronização é executado, ele garantirá que todos os arquivos de código-fonte em seu workspace (com base em sua configuração) contenham o cabeçalho de licença apropriado. O cabeçalho é escrito como o primeiro comentário de bloco ou série consecutiva de comentários de linha no arquivo (além do shebang/hashbang, se presente em um arquivo).

2. Sincronizar Arquivos LICENSE

Quando o gerador de sincronização é executado, ele garantirá que o arquivo LICENSE raiz corresponda à sua licença configurada, bem como garantirá que todos os subprojetos em seu workspace também contenham o arquivo LICENSE correto.

3. Sincronizar informações de licenciamento em arquivos de projeto

Quando o gerador de sincronização é executado, ele garantirá que os campos license em arquivos package.json e pyproject.toml sejam definidos para sua licença configurada.

Configuração de Cabeçalho e Arquivo

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

SPDX e Detentor de Direitos Autorais

Sua licença escolhida pode ser atualizada a qualquer momento através da propriedade de configuração spdx:

aws-nx-plugin.config.mts

export default {
  license: {
    source: {
      spdx: 'MIT',
    },
  },
} satisfies AwsNxPluginConfig;

Quando o gerador de sincronização é 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 de direitos autorais e o ano de direitos autorais, que são incluídos em alguns arquivos LICENSE:

aws-nx-plugin.config.mts

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

Conteúdo do Cabeçalho de Licença

O conteúdo do cabeçalho de licença pode ser configurado de duas maneiras:

1. Usando conteúdo 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;

2. Carregando de um arquivo:

aws-nx-plugin.config.mts

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

Formato do Cabeçalho

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

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;

A configuração de formato suporta:

• blockStart: Texto escrito antes do conteúdo da licença (por exemplo, para iniciar um comentário de bloco)
• lineStart: Texto anexado ao início de cada linha do conteúdo da licença
• lineEnd: Texto anexado ao final de cada linha do conteúdo da licença
• blockEnd: Texto escrito após o conteúdo da licença (por exemplo, para encerrar um comentário de bloco)

Sintaxe de Comentário Personalizada

Para tipos de arquivo que não são nativamente suportados, você pode especificar sintaxe de comentário personalizada para informar ao gerador de sincronização como identificar cabeçalhos de licença existentes nesses tipos de arquivo.

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;

Excluindo Arquivos da Sincronização de Cabeçalho

Por padrão, em um repositório git, todos os arquivos .gitignore são respeitados para garantir que apenas arquivos gerenciados pelo controle de versão sejam sincronizados. 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 da sincronização de cabeçalho de licença usando padrões 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;

Excluindo Projetos da Sincronização de Arquivo

Todos os arquivos LICENSE, arquivos package.json e arquivos pyproject.toml são sincronizados com a licença configurada por padrão.

Você pode excluir projetos ou arquivos específicos da sincronização usando padrões 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;

Desabilitando a Sincronização de Licença

A sincronização de fonte de licença é habilitada pela presença da chave license.source em sua configuração. Para desabilitá-la:

1. Remova a seção license.source da sua configuração em aws-nx-plugin.config.mts (você pode manter license.dependencies se ainda quiser verificação de licença de dependência)
2. Se você também quiser remover completamente o gerador de sincronização, remova o gerador @aws/nx-plugin:license#sync de targetDefaults.lint.syncGenerators

Para reabilitar a sincronização de licença, simplesmente execute o gerador license novamente.

Verificações de Licença de Dependência

O gerador license também configura um target license-check que falha quando uma das dependências do seu projeto (ou qualquer dependência transitiva) declara uma licença que não está na sua lista de permitidas.

Como é executado

O gerador escreve um target license-check no seu project.json raiz:

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

Os inputs são computados para o seu workspace: apenas lockfiles que estão realmente presentes são incluídos, juntamente com aws-nx-plugin.config.mts, mais um glob {workspaceRoot}/**/uv.lock quando a verificação de dependência Python está habilitada (ou seja, um coletor Python está configurado).

Você pode executar a verificação diretamente:

pnpm

pnpm nx license-check

yarn

yarn nx license-check

npm

npx nx license-check

bun

bunx nx license-check

Os resultados são armazenados em cache em relação aos seus lockfiles e aws-nx-plugin.config.mts — re-execuções são instantâneas quando nada mudou.

Coletores determinam o que é escaneado. O npmCollector usa license-checker-rseidelsohn, e o pythonCollector usa pip-licenses. Se nenhuma dependência instalada for encontrada, a verificação passa sem nada para inspecionar.

Executando como parte de lint/build

A verificação de licença de dependência é executada automaticamente sempre que você executa lint ou build em qualquer projeto em seu workspace. O gerador license conecta o target lint de cada projeto para depender do target license-check raiz, e os geradores de projeto (ts#* e py#*) fazem o mesmo quando são executados — então a verificação é conectada independentemente da ordem em que os geradores são executados.

Isso significa que você não precisa executar a verificação explicitamente, embora ainda possa fazê-lo com o target license-check:

pnpm

pnpm nx license-check

yarn

yarn nx license-check

npm

npx nx license-check

bun

bunx nx license-check

A conexão é um dependsOn entre projetos no target lint de cada projeto que aponta para o target license-check raiz. Para pular a verificação durante um lint ou build, defina a variável de ambiente 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

Configuração

Por padrão, a verificação usa um conjunto integrado de licenças permissivas comuns (MIT, Apache-2.0, BSD, ISC, etc.) exportado como DEFAULT_LICENSE_ALLOWLIST. Você pode estender ou substituir isso em sua configuração:

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;

Ver a lista completa de licenças em DEFAULT_LICENSE_ALLOWLIST

Personalizando a lista de permitidas

Para restringir a lista de permitidas, substitua DEFAULT_LICENSE_ALLOWLIST pelo seu próprio array. Para estendê-la, espalhe o padrão e adicione entradas. As entradas são correspondidas por id SPDX, nome completo da licença ou qualquer um dos aliases listados (sem distinção entre maiúsculas e minúsculas).

Exceções por pacote

Use exceptions para pacotes que falham na verificação — seja porque sua licença não está na lista de permitidas, ou porque eles são enviados sem metadados de licença detectáveis. O campo reason é obrigatório para que os revisores possam ver por que a exceção foi concedida.

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

Geradores que introduzem dependências com metadados problemáticos (por exemplo, o gerador de servidor MCP) adicionam automaticamente as exceções necessárias à sua configuração quando são executados.

Coletores

Coletores descobrem dependências e extraem metadados de licença. Os coletores integrados são npmCollector() (escaneia node_modules) e pythonCollector() (escaneia ambientes virtuais Python). O gerador de licença configura npmCollector() por padrão e adiciona pythonCollector() quando projetos Python estão presentes.

Para implementar um coletor personalizado, conforme a 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' },
    ];
  },
});

O hook onDependency

license.dependencies aceita um callback opcional onDependency que é invocado uma vez para cada dependência descoberta, independentemente de passar ou falhar na verificação. Ele recebe { package, spdx }, onde package é o nome do pacote e spdx é a expressão de licença SPDX resolvida. O spdx de uma exceção tem precedência sobre a licença bruta declarada, e spdx pode ser uma string vazia se nenhuma licença foi declarada.

Esta é uma maneira útil de imprimir todas as licenças em seu projeto. Execute o target license-check para ver a saída:

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;

Desabilitando Verificações de Dependência

A verificação de licença de dependência é habilitada pela presença da chave license.dependencies em sua configuração.

Para desabilitar as verificações para uma única execução, defina a variável de ambiente 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

Para desabilitar permanentemente, remova a chave license.dependencies da sua configuração em aws-nx-plugin.config.mts. Você também pode executar novamente o gerador license com --dependencyCheck=false para criar o scaffold sem ele.