Aller au contenu
@aws/nx-plugin
Blog

License

Gérez les licences dans votre espace de travail : synchronisez les fichiers LICENSE et les en-têtes de code source pour votre propre code (license.source), et vérifiez que chaque dépendance est conforme à une liste de licences autorisées (license.dependencies).

Utilisation

Section intitulée « Utilisation »

Exécuter le générateur

Section intitulée « Exécuter le générateur »
Terminal window
pnpm nx g @aws/nx-plugin:license
Vous pouvez également effectuer une simulation pour voir quels fichiers seraient modifiés
Terminal window
pnpm nx g @aws/nx-plugin:license --dry-run

Options

Section intitulée « Options »
ParamètreTypePar défautDescription
license Apache-2.0 | MIT | ASLApache-2.0Identifiant de licence SPDX pour la licence choisie
copyrightHolder stringAmazon.com, Inc. or its affiliatesLe détenteur des droits d'auteur, inclus dans le fichier LICENSE et les en-têtes des fichiers source par défaut.
dependencyCheck booleantrueConfigure une cible license-check qui échoue lorsque les dépendances déclarent des licences en dehors de la liste autorisée configurée.
preferInstallDependencies booleantrueIndique s'il faut privilégier l'installation des dépendances après l'exécution du générateur. Définir sur false pour différer l'installation lors de l'exécution de plusieurs générateurs en lot (une installation s'exécute quand même si nécessaire pour que les générateurs suivants puissent calculer le graphe de projet Nx) ; installer une seule fois à la fin.

Sortie du générateur

Section intitulée « Sortie du générateur »

Le générateur créera ou mettra à jour les fichiers suivants :

  • nx.json La cible lint est configurée pour exécuter le générateur de synchronisation de licence et dépend de la cible license-check
  • aws-nx-plugin.config.mts Configuration pour la synchronisation des sources de licence (license.source) et la vérification des dépendances (license.dependencies)

En-têtes et fichiers de licence

Section intitulée « En-têtes et fichiers de licence »

Le générateur enregistre un générateur de synchronisation à exécuter dans le cadre de vos cibles lint, qui garantit que vos fichiers sources contiennent les en-têtes de licence corrects, que vos projets contiennent des fichiers LICENSE, et que les métadonnées de licence sont définies dans package.json et pyproject.toml.

Flux de travail

Section intitulée « Flux de travail »

Chaque fois que vous construisez vos projets (et qu’une cible lint s’exécute), le générateur de synchronisation de licence s’assurera que les licences de votre projet correspondent à votre configuration. S’il détecte que quelque chose n’est pas synchronisé, vous recevrez un message tel que :

Fenêtre de terminal
  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

Sélectionnez Yes pour synchroniser les modifications.

Comportement de synchronisation

Section intitulée « Comportement de synchronisation »

Le générateur de synchronisation de licence effectue trois tâches principales :

1. Synchroniser les en-têtes de licence des fichiers sources

Section intitulée « 1. Synchroniser les en-têtes de licence des fichiers sources »

Lorsque le générateur de synchronisation est exécuté, il s’assurera que tous les fichiers de code source de votre espace de travail (en fonction de votre configuration) contiennent l’en-tête de licence approprié. L’en-tête est écrit comme le premier commentaire de bloc ou la première série consécutive de commentaires de ligne dans le fichier (en plus du shebang/hashbang s’il est présent dans un fichier).

2. Synchroniser les fichiers LICENSE

Section intitulée « 2. Synchroniser les fichiers LICENSE »

Lorsque le générateur de synchronisation est exécuté, il s’assurera que le fichier LICENSE racine correspond à votre licence configurée, et que tous les sous-projets de votre espace de travail contiennent également le fichier LICENSE correct.

3. Synchroniser les informations de licence dans les fichiers de projet

Section intitulée « 3. Synchroniser les informations de licence dans les fichiers de projet »

Lorsque le générateur de synchronisation est exécuté, il s’assurera que les champs license dans les fichiers package.json et pyproject.toml sont définis sur votre licence configurée.

Configuration des en-têtes et fichiers

Section intitulée « Configuration des en-têtes et fichiers »

La configuration est définie dans le fichier aws-nx-plugin.config.mts à la racine de votre espace de travail.

SPDX et titulaire du droit d’auteur

Section intitulée « SPDX et titulaire du droit d’auteur »

Votre licence choisie peut être mise à jour à tout moment via la propriété de configuration spdx :

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

Lorsque le générateur de synchronisation s’exécute, tous les fichiers LICENSE, package.json et pyproject.toml seront mis à jour pour refléter la licence configurée.

Vous pouvez également configurer le titulaire du droit d’auteur et l’année du droit d’auteur, qui sont inclus dans certains fichiers LICENSE :

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

Contenu de l’en-tête de licence

Section intitulée « Contenu de l’en-tête de licence »

Le contenu de l’en-tête de licence peut être configuré de deux manières :

  1. En utilisant du contenu en ligne :
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;
  1. En chargeant depuis un fichier :
aws-nx-plugin.config.mts
export default {
  license: {
    source: {
      header: {
        content: {
          filePath: 'license-header.txt'; // relative to workspace root
        }
        // ... format configuration
      }
    }
  }
} satisfies AwsNxPluginConfig;

Format de l’en-tête

Section intitulée « Format de l’en-tête »

Vous pouvez spécifier comment les en-têtes de licence doivent être formatés pour différents types de fichiers en utilisant des motifs glob. La configuration du format prend en charge les commentaires de ligne, les commentaires de bloc ou une combinaison des deux :

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 configuration du format prend en charge :

  • blockStart : Texte écrit avant le contenu de la licence (par exemple pour commencer un commentaire de bloc)
  • lineStart : Texte ajouté au début de chaque ligne du contenu de la licence
  • lineEnd : Texte ajouté à la fin de chaque ligne du contenu de la licence
  • blockEnd : Texte écrit après le contenu de la licence (par exemple pour terminer un commentaire de bloc)

Syntaxe de commentaire personnalisée

Section intitulée « Syntaxe de commentaire personnalisée »

Pour les types de fichiers qui ne sont pas pris en charge nativement, vous pouvez spécifier une syntaxe de commentaire personnalisée pour indiquer au générateur de synchronisation comment identifier les en-têtes de licence existants dans ces types de fichiers.

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;

Exclure des fichiers de la synchronisation des en-têtes

Section intitulée « Exclure des fichiers de la synchronisation des en-têtes »

Par défaut, dans un dépôt git, tous les fichiers .gitignore sont respectés pour garantir que seuls les fichiers gérés par le contrôle de version sont synchronisés. Dans les dépôts non-git, tous les fichiers sont considérés sauf s’ils sont explicitement exclus dans la configuration.

Vous pouvez exclure des fichiers supplémentaires de la synchronisation des en-têtes de licence en utilisant des motifs 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;

Exclure des projets de la synchronisation des fichiers

Section intitulée « Exclure des projets de la synchronisation des fichiers »

Tous les fichiers LICENSE, package.json et pyproject.toml sont synchronisés avec la licence configurée par défaut.

Vous pouvez exclure des projets ou des fichiers spécifiques de la synchronisation en utilisant des motifs 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;

Désactiver la synchronisation de licence

Section intitulée « Désactiver la synchronisation de licence »

La synchronisation des sources de licence est activée par la présence de la clé license.source dans votre configuration. Pour la désactiver :

  1. Supprimez la section license.source de votre configuration dans aws-nx-plugin.config.mts (vous pouvez conserver license.dependencies si vous souhaitez toujours vérifier les licences des dépendances)
  2. Si vous souhaitez également supprimer complètement le générateur de synchronisation, supprimez le générateur @aws/nx-plugin:license#sync de targetDefaults.lint.syncGenerators

Pour réactiver la synchronisation de licence, exécutez simplement le générateur license à nouveau.

Vérifications des licences des dépendances

Section intitulée « Vérifications des licences des dépendances »

Le générateur license configure également une cible license-check qui échoue lorsque l’une des dépendances de votre projet (ou toute dépendance transitive) déclare une licence qui ne figure pas dans votre liste autorisée.

Comment cela fonctionne

Section intitulée « Comment cela fonctionne »

Le générateur écrit une cible license-check dans votre project.json racine :

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

Les inputs sont calculés pour votre espace de travail : seuls les fichiers de verrouillage réellement présents sont inclus, ainsi que aws-nx-plugin.config.mts, plus un glob {workspaceRoot}/**/uv.lock lorsque la vérification des dépendances Python est activée (c’est-à-dire qu’un collecteur Python est configuré).

Vous pouvez exécuter la vérification directement :

Terminal window
pnpm nx license-check

Les résultats sont mis en cache par rapport à vos fichiers de verrouillage et aws-nx-plugin.config.mts — les réexécutions sont instantanées lorsque rien n’a changé.

Les collecteurs déterminent ce qui est analysé. Le npmCollector utilise license-checker-rseidelsohn, et le pythonCollector utilise pip-licenses. Si aucune dépendance installée n’est trouvée, la vérification réussit sans rien à inspecter.

Exécution dans le cadre de lint/build

Section intitulée « Exécution dans le cadre de lint/build »

La vérification des licences des dépendances s’exécute automatiquement chaque fois que vous exécutez lint ou build sur n’importe quel projet de votre espace de travail. Le générateur license connecte la cible lint de chaque projet pour qu’elle dépende de la cible license-check racine, et les générateurs de projet (ts#* et py#*) font de même lorsqu’ils s’exécutent — ainsi la vérification est connectée quel que soit l’ordre dans lequel les générateurs sont exécutés.

Cela signifie que vous n’avez pas besoin d’exécuter la vérification explicitement, bien que vous puissiez toujours le faire avec la cible license-check :

Terminal window
pnpm nx license-check

Le câblage est un dependsOn inter-projets sur la cible lint de chaque projet qui pointe vers la cible license-check racine. Pour ignorer la vérification lors d’un lint ou d’une construction, définissez la variable d’environnement LICENSE_DEPENDENCY_CHECK=skip :

Terminal window
pnpm LICENSE_DEPENDENCY_CHECK=skip lint

Configuration

Section intitulée « Configuration »

Par défaut, la vérification utilise un ensemble intégré de licences permissives courantes (MIT, Apache-2.0, BSD, ISC, etc.) exporté sous le nom DEFAULT_LICENSE_ALLOWLIST. Vous pouvez étendre ou remplacer cela dans votre configuration :

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;
Voir la liste complète des licences dans DEFAULT_LICENSE_ALLOWLIST

Personnaliser la liste autorisée

Section intitulée « Personnaliser la liste autorisée »

Pour restreindre la liste autorisée, remplacez DEFAULT_LICENSE_ALLOWLIST par votre propre tableau. Pour l’étendre, décomposez la valeur par défaut et ajoutez des entrées. Les entrées sont comparées par identifiant SPDX, nom complet de licence ou l’un des alias listés (insensible à la casse).

Exceptions par paquet

Section intitulée « Exceptions par paquet »

Utilisez exceptions pour les paquets qui échouent à la vérification — soit parce que leur licence ne figure pas dans la liste autorisée, soit parce qu’ils sont livrés sans métadonnées de licence détectables. Le champ reason est requis pour que les réviseurs puissent voir pourquoi l’exception a été accordée.

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

Les générateurs qui introduisent des dépendances avec des métadonnées problématiques (par exemple le générateur de serveur MCP) ajoutent automatiquement les exceptions requises à votre configuration lorsqu’ils s’exécutent.

Collecteurs

Section intitulée « Collecteurs »

Les collecteurs découvrent les dépendances et extraient les métadonnées de licence. Les collecteurs intégrés sont npmCollector() (analyse node_modules) et pythonCollector() (analyse les environnements virtuels Python). Le générateur de licence configure npmCollector() par défaut et ajoute pythonCollector() lorsque des projets Python sont présents.

Pour implémenter un collecteur personnalisé, conformez-vous à l’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' },
    ];
  },
});

Le hook onDependency

Section intitulée « Le hook onDependency »

license.dependencies accepte un callback optionnel onDependency qui est invoqué une fois pour chaque dépendance découverte, qu’elle réussisse ou échoue la vérification. Il reçoit { package, spdx }, où package est le nom du paquet et spdx est l’expression de licence SPDX résolue. Le spdx d’une exception a la priorité sur la licence brute déclarée, et spdx peut être une chaîne vide si aucune licence n’a été déclarée.

C’est un moyen pratique d’imprimer toutes les licences de votre projet. Exécutez la cible license-check pour voir la sortie :

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;

Désactiver les vérifications des dépendances

Section intitulée « Désactiver les vérifications des dépendances »

La vérification des licences des dépendances est activée par la présence de la clé license.dependencies dans votre configuration.

Pour désactiver les vérifications pour une seule exécution, définissez la variable d’environnement LICENSE_DEPENDENCY_CHECK=skip :

Terminal window
pnpm LICENSE_DEPENDENCY_CHECK=skip lint

Pour désactiver de manière permanente, supprimez la clé license.dependencies de votre configuration dans aws-nx-plugin.config.mts. Vous pouvez également réexécuter le générateur license avec --dependencyCheck=false pour générer sans elle.