Licenza

Gestisci le licenze nell’intero 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

Esegui il generatore

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

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

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 del codice sorgente delle licenze (license.source) e il controllo delle dipendenze (license.dependencies)

Intestazioni e file di licenza

Il generatore registra un generatore di sincronizzazione che viene eseguito come parte dei tuoi target lint per garantire che i file sorgente contengano le intestazioni di licenza corrette, che i progetti contengano i file LICENSE e che i metadati di licenza siano impostati in package.json e pyproject.toml.

Workflow

Ogni volta che costruisci i tuoi progetti (e viene eseguito un target lint), il generatore di sincronizzazione delle licenze si assicurerà che le licenze nei tuoi progetti 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]: I file LICENSE del progetto non sono sincronizzati:
- LICENSE
- packages/<my-project>LICENSE

I file package.json del progetto non sono sincronizzati:
- package.json

I file pyproject.toml del progetto non sono sincronizzati:
- pyproject.toml
- packages/<my-python-project>/pyproject.toml

Le intestazioni di licenza non sono sincronizzate nei seguenti file sorgente:
- packages/<my-project>/src/index.ts
- packages/<my-python-project>/main.py

Questo causerà un errore in CI.

? Desideri sincronizzare le modifiche identificate per aggiornare il workspace?
Sì, sincronizza le modifiche ed esegui i task
No, esegui i task senza sincronizzare le modifiche

Seleziona Sì per sincronizzare le modifiche.

Verificare le modifiche

Assicurati di verificare le modifiche apportate dal generatore di sincronizzazione delle licenze nel controllo delle versioni, per evitare che i task di integrazione continua falliscano a causa di licenze non sincronizzate.

Comportamento della sincronizzazione

Il generatore di sincronizzazione esegue tre attività principali:

1. Sincronizza le intestazioni di licenza nei file sorgente

Quando viene eseguito, il generatore si assicura che tutti i file sorgente nel workspace (in base alla configurazione) contengano l’intestazione di licenza appropriata. L’intestazione viene scritta come primo commento a blocco o serie consecutiva di commenti a linea nel file (escludendo eventuali shebang/hashbang presenti).

2. Sincronizza i file LICENSE

Il generatore verifica che il file LICENSE principale corrisponda alla licenza configurata, e che tutti i sottoprogetti nel workspace contengano il file LICENSE corretto.

3. Sincronizza le informazioni di licenza nei file di progetto

Il generatore assicura che i campi license nei file package.json e pyproject.toml siano impostati secondo la licenza configurata.

Configurazione di intestazioni e file

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

SPDX e titolare del copyright

La licenza selezionata può essere aggiornata in qualsiasi momento tramite la proprietà spdx:

aws-nx-plugin.config.mts

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

All’esecuzione del generatore, tutti i file LICENSE, package.json e pyproject.toml verranno aggiornati con la licenza configurata.

Puoi inoltre configurare titolare e anno del copyright, 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 può essere configurato in due modi:

1. 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',
          ];
        }
        // ... configurazione formato
      }
    }
  }
} satisfies AwsNxPluginConfig;

2. Caricamento da file:

aws-nx-plugin.config.mts

export default {
  license: {
    source: {
      header: {
        content: {
          filePath: 'license-header.txt'; // relativo alla root del workspace
        }
        // ... configurazione formato
      }
    }
  }
} satisfies AwsNxPluginConfig;

Formato dell’intestazione

Puoi specificare come formattare le intestazioni per diversi tipi di file usando pattern glob. Sono supportati commenti a linea, a blocco o combinazioni:

aws-nx-plugin.config.mts

export default {
  license: {
    source: {
      header: {
        content: {
          lines: ['Copyright notice here'],
        },
        format: {
          // Commenti a linea
          '**/*.ts': {
            lineStart: '// ',
          },
          // Commenti a blocco
          '**/*.css': {
            blockStart: '/*',
            blockEnd: '*/',
          },
          // Commenti a blocco con prefissi
          '**/*.java': {
            blockStart: '/*',
            lineStart: ' * ',
            blockEnd: ' */',
          },
          // Commenti a linea con header/footer
          '**/*.py': {
            blockStart: '# ------------',
            lineStart: '# ',
            blockEnd: '# ------------',
          },
        },
      },
    },
  },
} satisfies AwsNxPluginConfig;

Le opzioni di formato supportate:

• blockStart: Testo prima del contenuto della licenza (es. per iniziare un blocco)
• lineStart: Prefisso per ogni riga della licenza
• lineEnd: Suffisso per ogni riga della licenza
• blockEnd: Testo dopo il contenuto della licenza (es. per chiudere un blocco)

Sintassi personalizzata per commenti

Per tipi di file non supportati nativamente, puoi definire sintassi personalizzate per identificare le intestazioni esistenti:

aws-nx-plugin.config.mts

export default {
  license: {
    source: {
      header: {
        content: {
          lines: ['My license header'],
        },
        format: {
          '**/*.xyz': {
            lineStart: '## ',
          },
        },
        commentSyntax: {
          xyz: {
            line: '##', // Sintassi per commenti a linea
          },
          abc: {
            block: {
              // Sintassi per commenti a blocco
              start: '<!--',
              end: '-->',
            },
          },
        },
      },
    },
  },
} satisfies AwsNxPluginConfig;

Escludere file dalla sincronizzazione delle intestazioni

Per default, in repository git, tutti i file .gitignore vengono rispettati. In repository non git, tutti i file sono considerati a meno di esclusioni esplicite.

Puoi escludere ulteriori file usando 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, package.json e pyproject.toml vengono sincronizzati per default.

Puoi escludere progetti o file specifici usando pattern glob:

aws-nx-plugin.config.mts

export default {
  license: {
    source: {
      files: {
        exclude: [
          // non sincronizzare LICENSE, package.json o pyproject.toml
          'packages/excluded-project',
          // non sincronizzare LICENSE, ma sincronizza package.json/pyproject.toml
          'apps/internal/LICENSE',
        ];
      }
    }
  }
} satisfies AwsNxPluginConfig;

Disabilitare la sincronizzazione delle licenze

La sincronizzazione del codice sorgente delle licenze è 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 vuoi ancora il controllo delle licenze delle dipendenze)
2. Se vuoi anche rimuovere completamente il generatore di sincronizzazione, rimuovi il generatore @aws/nx-plugin:license#sync da targetDefaults.lint.syncGenerators

Per riattivare, esegui nuovamente il generatore license.

Controllo delle licenze delle dipendenze

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

Come funziona

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

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 il controllo delle dipendenze Python è abilitato (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 sono memorizzati in 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 usa license-checker-rseidelsohn, e il pythonCollector usa pip-licenses. Se non vengono trovate dipendenze installate, il controllo passa senza nulla da ispezionare.

Esecuzione 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 principale, 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.

Questo 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-progetto sul target lint di ogni progetto che punta al target license-check principale. 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 estenderlo o sovrascriverlo 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 restringere la lista, 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

Usa exceptions per i pacchetti che non superano 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é l’eccezione è stata concessa.

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 necessarie alla tua configurazione quando vengono eseguiti.

Collector

I collector scoprono le dipendenze ed estraggono i metadati di licenza. 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 essa.