License

Gestisci le licenze in tutto il tuo workspace: sincronizza i file LICENSE e le intestazioni del codice sorgente per il tuo codice (license.source), e verifica che ogni dipendenza sia conforme a una lista di licenze consentite (license.dependencies).

Utilizzo

Eseguire il Generatore

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

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

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. Installa il Nx Console VSCode Plugin se non l'hai già fatto
2. Apri la console Nx in VSCode
3. Clicca su Generate (UI) nella sezione "Common Nx Commands"
4. Cerca @aws/nx-plugin - license
5. Compila i parametri richiesti
6. Clicca su Generate

Opzioni

Parametro	Tipo	Predefinito	Descrizione
license	Apache-2.0 | MIT | ASL	Apache-2.0	Identificatore di licenza SPDX per la licenza scelta
copyrightHolder	string	Amazon.com, Inc. or its affiliates	Il titolare del copyright, incluso nel file LICENSE e nelle intestazioni dei file sorgente per impostazione predefinita.
dependencyCheck	boolean	true	Configura un target license-check che fallisce quando le dipendenze dichiarano licenze al di fuori della lista consentita configurata.
preferInstallDependencies	boolean	true	Se preferire l'installazione delle dipendenze dopo l'esecuzione del generatore. Impostare su false per rimandare l'installazione quando si eseguono più generatori in batch (l'installazione viene comunque eseguita se necessaria affinché i generatori successivi possano calcolare il grafo dei progetti Nx); installare una volta alla fine.

Output del Generatore

Il generatore creerà o aggiornerà i seguenti file:

• nx.json Il target lint è configurato per eseguire il generatore di sincronizzazione delle licenze e dipende dal target license-check
• aws-nx-plugin.config.mts Configurazione per la sincronizzazione delle licenze del sorgente (license.source) e il controllo delle dipendenze (license.dependencies)

Intestazioni e File di Licenza

Il generatore registra un sync generator da eseguire come parte dei tuoi target lint che garantisce che i tuoi file sorgente contengano le intestazioni di licenza corrette, i tuoi progetti contengano file LICENSE e i metadati di licenza siano impostati in package.json e pyproject.toml.

Flusso di Lavoro

Ogni volta che compili i tuoi progetti (e viene eseguito un target lint), il generatore di sincronizzazione delle licenze si assicurerà che le licenze nel tuo progetto corrispondano alla tua configurazione. Se rileva che qualcosa non è sincronizzato, riceverai un messaggio come:

  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

Seleziona Yes per sincronizzare le modifiche.

Rivedi le Modifiche

Assicurati di controllare le modifiche apportate dal generatore di sincronizzazione delle licenze nel controllo di versione per garantire che eventuali task di build di integrazione continua non falliscano a causa di licenze non sincronizzate.

Comportamento di Sincronizzazione

Il generatore di sincronizzazione delle licenze esegue tre compiti principali:

1. Sincronizzare le Intestazioni di Licenza dei File Sorgente

Quando viene eseguito il generatore di sincronizzazione, garantirà che tutti i file di codice sorgente nel tuo workspace (in base alla tua configurazione) contengano l’intestazione di licenza appropriata. L’intestazione viene scritta come primo commento a blocco o serie consecutiva di commenti di riga nel file (oltre allo shebang/hashbang se presente in un file).

2. Sincronizzare i File LICENSE

Quando viene eseguito il generatore di sincronizzazione, garantirà che il file LICENSE radice corrisponda alla licenza configurata, oltre a garantire che tutti i sottoprogetti nel tuo workspace contengano anche il file LICENSE corretto.

3. Sincronizzare le informazioni di licenza nei file di progetto

Quando viene eseguito il generatore di sincronizzazione, garantirà che i campi license nei file package.json e pyproject.toml siano impostati sulla licenza configurata.

Configurazione di Intestazioni e File

La configurazione è definita nel file aws-nx-plugin.config.mts nella radice del tuo workspace.

SPDX e Titolare del Copyright

La licenza scelta può essere aggiornata in qualsiasi momento tramite la proprietà di configurazione spdx:

aws-nx-plugin.config.mts

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

Quando viene eseguito il generatore di sincronizzazione, tutti i file LICENSE, package.json e pyproject.toml verranno aggiornati per riflettere la licenza configurata.

Puoi inoltre configurare il titolare del copyright e l’anno del copyright, che sono inclusi in alcuni file LICENSE:

aws-nx-plugin.config.mts

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

Contenuto dell’Intestazione di Licenza

Il contenuto dell’intestazione di licenza può essere configurato in due modi:

1. Utilizzando contenuto 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. Caricando da un file:

aws-nx-plugin.config.mts

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

Formato dell’Intestazione

Puoi specificare come le intestazioni di licenza dovrebbero essere formattate per diversi tipi di file utilizzando pattern glob. La configurazione del formato supporta commenti di riga, commenti a blocco o una combinazione di entrambi:

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;

La configurazione del formato supporta:

• blockStart: Testo scritto prima del contenuto della licenza (ad es. per iniziare un commento a blocco)
• lineStart: Testo anteposto a ogni riga del contenuto della licenza
• lineEnd: Testo aggiunto a ogni riga del contenuto della licenza
• blockEnd: Testo scritto dopo il contenuto della licenza (ad es. per terminare un commento a blocco)

Sintassi dei Commenti Personalizzata

Per i tipi di file che non sono supportati nativamente, puoi specificare una sintassi dei commenti personalizzata per indicare al generatore di sincronizzazione come identificare le intestazioni di licenza esistenti in questi tipi di file.

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;

Escludere File dalla Sincronizzazione delle Intestazioni

Per impostazione predefinita, in un repository git, tutti i file .gitignore vengono rispettati per garantire che vengano sincronizzati solo i file gestiti dal controllo di versione. Nei repository non-git, tutti i file vengono considerati a meno che non siano esplicitamente esclusi nella configurazione.

Puoi escludere file aggiuntivi dalla sincronizzazione delle intestazioni di licenza utilizzando pattern 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;

Escludere Progetti dalla Sincronizzazione dei File

Tutti i file LICENSE, i file package.json e i file pyproject.toml vengono sincronizzati con la licenza configurata per impostazione predefinita.

Puoi escludere progetti o file specifici dalla sincronizzazione utilizzando pattern 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;

Disabilitare la Sincronizzazione delle Licenze

La sincronizzazione delle licenze del sorgente è abilitata dalla presenza della chiave license.source nella tua configurazione. Per disabilitarla:

1. Rimuovi la sezione license.source dalla tua configurazione in aws-nx-plugin.config.mts (puoi mantenere license.dependencies se desideri ancora il controllo delle licenze delle dipendenze)
2. Se desideri anche rimuovere completamente il generatore di sincronizzazione, rimuovi il generatore @aws/nx-plugin:license#sync da targetDefaults.lint.syncGenerators

Per riabilitare la sincronizzazione delle licenze, esegui semplicemente di nuovo il generatore license.

Controlli delle Licenze delle Dipendenze

Il generatore license configura anche un target license-check che fallisce quando una delle dipendenze del tuo progetto (o qualsiasi dipendenza transitiva) dichiara una licenza che non è nella tua lista consentita.

Come viene eseguito

Il generatore scrive un target license-check nel tuo project.json radice:

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

Gli inputs sono calcolati per il tuo workspace: vengono inclusi solo i lockfile effettivamente presenti, insieme a aws-nx-plugin.config.mts, più un glob {workspaceRoot}/**/uv.lock quando è abilitato il controllo delle dipendenze Python (cioè quando è configurato un collector Python).

Puoi eseguire il controllo direttamente:

pnpm

pnpm nx license-check

yarn

yarn nx license-check

npm

npx nx license-check

bun

bunx nx license-check

I risultati vengono memorizzati nella cache rispetto ai tuoi lockfile e aws-nx-plugin.config.mts — le riesecuzioni sono istantanee quando nulla è cambiato.

I collector determinano cosa viene scansionato. L’npmCollector utilizza license-checker-rseidelsohn, e il pythonCollector utilizza pip-licenses. Se non vengono trovate dipendenze installate, il controllo passa senza nulla da ispezionare.

Eseguire come parte di lint/build

Il controllo delle licenze delle dipendenze viene eseguito automaticamente ogni volta che esegui lint o build su qualsiasi progetto nel tuo workspace. Il generatore license collega il target lint di ogni progetto per dipendere dal target license-check radice, e i generatori di progetto (ts#* e py#*) fanno lo stesso quando vengono eseguiti — quindi il controllo è collegato indipendentemente dall’ordine in cui vengono eseguiti i generatori.

Ciò significa che non è necessario eseguire il controllo esplicitamente, anche se puoi ancora farlo con il target license-check:

pnpm

pnpm nx license-check

yarn

yarn nx license-check

npm

npx nx license-check

bun

bunx nx license-check

Il collegamento è un dependsOn cross-project sul target lint di ogni progetto che punta al target license-check radice. Per saltare il controllo durante un lint o build, imposta la variabile d’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

Configurazione

Per impostazione predefinita, il controllo utilizza un set integrato di licenze permissive comuni (MIT, Apache-2.0, BSD, ISC, ecc.) esportato come DEFAULT_LICENSE_ALLOWLIST. Puoi estendere o sovrascrivere questo nella tua configurazione:

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;

Visualizza l'elenco completo delle licenze in DEFAULT_LICENSE_ALLOWLIST

Personalizzare la lista consentita

Per limitare la lista consentita, sostituisci DEFAULT_LICENSE_ALLOWLIST con il tuo array. Per estenderla, espandi il default e aggiungi voci. Le voci vengono confrontate per id SPDX, nome completo della licenza o uno qualsiasi degli alias elencati (senza distinzione tra maiuscole e minuscole).

Eccezioni per singoli pacchetti

Utilizza exceptions per i pacchetti che falliscono il controllo — sia perché la loro licenza non è nella lista consentita, sia perché vengono forniti senza metadati di licenza rilevabili. Il campo reason è obbligatorio in modo che i revisori possano vedere perché è stata concessa l’eccezione.

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

I generatori che introducono dipendenze con metadati problematici (ad es. il generatore di server MCP) aggiungono automaticamente le eccezioni richieste alla tua configurazione quando vengono eseguiti.

Collector

I collector scoprono le dipendenze ed estraggono i metadati delle licenze. I collector integrati sono npmCollector() (scansiona node_modules) e pythonCollector() (scansiona gli ambienti virtuali Python). Il generatore di licenze configura npmCollector() per impostazione predefinita e aggiunge pythonCollector() quando sono presenti progetti Python.

Per implementare un collector personalizzato, conformati all’interfaccia 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' },
    ];
  },
});

L’hook onDependency

license.dependencies accetta un callback opzionale onDependency che viene invocato una volta per ogni dipendenza scoperta, indipendentemente dal fatto che superi o meno il controllo. Riceve { package, spdx }, dove package è il nome del pacchetto e spdx è l’espressione di licenza SPDX risolta. L’spdx di un’eccezione ha la precedenza sulla licenza dichiarata grezza, e spdx può essere una stringa vuota se non è stata dichiarata alcuna licenza.

Questo è un modo pratico per stampare tutte le licenze nel tuo progetto. Esegui il target license-check per vedere l’output:

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;

Disabilitare i Controlli delle Dipendenze

Il controllo delle licenze delle dipendenze è abilitato dalla presenza della chiave license.dependencies nella tua configurazione.

Per disabilitare i controlli per una singola esecuzione, imposta la variabile d’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

Per disabilitare permanentemente, rimuovi la chiave license.dependencies dalla tua configurazione in aws-nx-plugin.config.mts. Puoi anche rieseguire il generatore license con --dependencyCheck=false per generare lo scaffold senza di esso.