Salta ai contenuti
@aws/nx-plugin
Blog

Licenza

Gestisci automaticamente i file LICENSE e le intestazioni del codice sorgente nel tuo workspace.

Questo generatore registra un sync generator da eseguire come parte dei tuoi target lint per garantire che i file sorgente rispettino il contenuto e il formato desiderati per le licenze, assicurando inoltre che i file LICENSE dei progetti siano corretti e che le informazioni sulle licenze siano incluse nei file di progetto rilevanti (package.json, pyproject.toml).

Utilizzo

Esegui il generatore

  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
    • Clicca su Generate

    Opzioni

    Parametro Tipo Predefinito Descrizione
    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.

    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
    • aws-nx-plugin.config.mts Configurazione per il generatore di sincronizzazione delle licenze

    Una configurazione predefinita per il contenuto e il formato delle intestazioni delle licenze viene aggiunta a aws-nx-plugin.config.mts per scrivere intestazioni appropriate per diversi tipi di file. Potresti voler personalizzare ulteriormente questa configurazione; consulta la sezione di configurazione qui sotto.

    Flusso di lavoro

    Ogni volta che costruisci i tuoi progetti (e viene eseguito un target lint), il generatore di sincronizzazione delle licenze verificherà che le licenze nei tuoi progetti corrispondano alla configurazione (vedi comportamento della sincronizzazione delle licenze qui sotto). Se rileva delle discrepanze, riceverai un messaggio come:

    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

    Seleziona Yes per sincronizzare le modifiche.

    Comportamento della sincronizzazione delle licenze

    Il generatore di sincronizzazione delle licenze esegue tre attività principali:

    1. Sincronizza le intestazioni delle licenze nei file sorgente

    Quando il generatore di sincronizzazione viene eseguito, assicura che tutti i file sorgente nel workspace (in base alla configurazione) contengano l’intestazione della 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).

    Puoi aggiornare la configurazione in qualsiasi momento per modificare quali file includere/escludere, oltre al contenuto o formato delle intestazioni per diversi tipi di file. Per maggiori dettagli, consulta la sezione di configurazione qui sotto.

    2. Sincronizza i file LICENSE

    Quando il generatore di sincronizzazione viene eseguito, verifica che il file LICENSE principale corrisponda alla licenza configurata e che tutti i sottoprogetti nel workspace contengano il file LICENSE corretto.

    Puoi escludere progetti specifici nella configurazione se necessario. Per maggiori dettagli, consulta la sezione di configurazione qui sotto.

    3. Sincronizza le informazioni sulle licenze nei file di progetto

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

    Puoi escludere progetti specifici nella configurazione se necessario. Per maggiori dettagli, consulta la sezione di configurazione qui sotto.

    Configurazione

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

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

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

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

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

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

    Intestazioni delle licenze

    Contenuto

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

    1. Utilizzando contenuto inline:
    aws-nx-plugin.config.mts
    export default {
      license: {
        header: {
          content: {
            lines: [
              'Copyright: My Company, Incorporated.',
              'Licensed under the MIT License',
              'All rights reserved',
            ];
          }
          // ... format configuration
        }
      }
    } satisfies AwsNxPluginConfig;
    1. Caricando da un file:
    aws-nx-plugin.config.mts
    export default {
      license: {
        header: {
          content: {
            filePath: 'license-header.txt'; // relativo alla radice del workspace
          }
          // ... format configuration
        }
      }
    } satisfies AwsNxPluginConfig;

    Formato

    Puoi specificare come formattare le intestazioni delle licenze per diversi tipi di file utilizzando pattern glob. La configurazione del formato supporta commenti a linea, a blocco o una combinazione di entrambi:

    aws-nx-plugin.config.mts
    export default {
      license: {
        header: {
          content: {
            lines: ['Copyright notice here'],
          },
          format: {
            // Commenti a linea
            '**/*.ts': {
              lineStart: '// ',
            },
            // Commenti a blocco
            '**/*.css': {
              blockStart: '/*',
              blockEnd: '*/',
            },
            // Commenti a blocco con prefisso per linea
            '**/*.java': {
              blockStart: '/*',
              lineStart: ' * ',
              blockEnd: ' */',
            },
            // Commenti a linea con intestazione/piè di pagina
            '**/*.py': {
              blockStart: '# ------------',
              lineStart: '# ',
              blockEnd: '# ------------',
            },
          },
        },
      },
    } satisfies AwsNxPluginConfig;

    La configurazione del formato supporta:

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

    Sintassi personalizzata per i commenti

    Per tipi di file non supportati nativamente, puoi specificare una sintassi personalizzata per identificare le intestazioni delle licenze esistenti.

    aws-nx-plugin.config.mts
    export default {
      license: {
        header: {
          content: {
            lines: ['My license header'],
          },
          format: {
            '**/*.xyz': {
              lineStart: '## ',
            },
          },
          commentSyntax: {
            xyz: {
              line: '##', // Definisci la sintassi per i commenti a linea
            },
            abc: {
              block: {
                // Definisci la sintassi per i commenti a blocco
                start: '<!--',
                end: '-->',
              },
            },
          },
        },
      },
    } satisfies AwsNxPluginConfig;

    Escludere file

    Per impostazione predefinita, in un repository git, tutti i file .gitignore vengono rispettati per sincronizzare solo i file gestiti dal controllo delle versioni. In repository non git, tutti i file vengono considerati a meno che non siano esplicitamente esclusi nella configurazione.

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

    Escludere file di progetto dalla sincronizzazione

    Tutti i file LICENSE, package.json e 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: {
        files: {
          exclude: [
            // non sincronizzare file LICENSE, package.json o pyproject.toml
            'packages/excluded-project',
            // non sincronizzare il file LICENSE, ma sincronizza package.json e/o pyproject.toml
            'apps/internal/LICENSE',
          ];
        }
      }
    } satisfies AwsNxPluginConfig;

    Disabilitare la sincronizzazione delle licenze

    Per disabilitare il generatore di sincronizzazione delle licenze:

    1. Rimuovi la sezione license dalla configurazione in aws-nx-plugin.config.mts (o elimina il file)
    2. Rimuovi il generatore @aws/nx-plugin:license#sync da targetDefaults.lint.syncGenerators

    Per riattivare la sincronizzazione, esegui nuovamente il generatore license.