En-tête de paternité — Ligne de licence SPDX par fichier

Référence normative canonique pour les contributeurs en aval. Ce document reprend les sections Paternité et En-tête de fichier de la spécification du projet (Spécification §0.5 + §4.6) ; c'est la référence autonome livrée avec le dépôt publié. La justification architecturale est consignée dans l'ADR-0002.

1. La ligne d'en-tête canoniqueCopy Anchor Link

Tout fichier applicable de l'écosystème DOIT commencer par une unique ligne canonique d'identifiant de licence SPDX, dans la syntaxe de commentaire de sa famille de type de fichier ; seul un shebang ou, dans les fichiers Markdown, un frontmatter YAML peut la précéder (§5). La ligne est le marqueur de licence lisible par machine du fichier ; sa présence est non négociable pour les fichiers non exemptés, et son contenu est régi par une source de vérité unique, jamais improvisé fichier par fichier. L'instrument de copyright complet vit une seule fois dans le fichier LICENSE à la racine du dépôt — il n'est pas dupliqué dans chaque fichier source.

1.1 Contenu d'information (invariant)Copy Anchor Link

Le contenu canonique est exactement une ligne :

1. SPDX-License-Identifier: MIT — le marqueur de licence lisible par machine selon la spécification REUSE maintenue par la FSFE ; analysé sans ambiguïté par la chaîne d'outils SPDX (reuse lint, scancode), l'outillage du noyau Linux et les scanners de licence en aval. Il ne porte ni bordure visuelle ni lignes de copyright, site web, e-mail ou GitHub par fichier — la provenance par fichier est la seule ligne SPDX, par conception (voir §4).

1.2 La forme de référence (famille de commentaire #)Copy Anchor Link

Le texte canonique — écrit ici sous sa forme de syntaxe de commentaire # — est la source de vérité dans src/apothem/schemas/authorship-header.txt :

# SPDX-License-Identifier: MIT

Ce texte est la seule source faisant autorité. Le validateur file-header (§8) vérifie les fichiers par rapport à cette fixture exacte à l'octet près. Toute divergence entre la ligne d'en-tête d'un fichier et cette fixture (sous substitution de syntaxe selon le §2) est signalée comme constat. Le validateur est bloquant : sous --strict, tel qu'exécuté par la CI et le hook de pre-commit, un constat fait échouer l'exécution (§8).

2. Variantes par type de fichier (exactes à l'octet près)Copy Anchor Link

Le contenu d'information de la ligne est invariant ; seule sa syntaxe de commentaire varie selon le type de fichier. Le tableau complet des variantes par type de fichier :

Variante Markdown (rendu canonique) :

<!-- SPDX-License-Identifier: MIT -->

L'enveloppe de commentaire HTML (ou MDX {/* */}) se rend de manière invisible, de sorte que la surface rendue reste propre tandis que le marqueur de licence dans le code source demeure lisible par machine pour tous les types de fichier.

3. Liste d'exceptions (catégoriquement exemptées)Copy Anchor Link

Les classes suivantes sont exemptées de la ligne d'en-tête SPDX. Le validateur file-header laisse ces fichiers passer sans les vérifier. Les classes ci-dessous correspondent à la liste de motifs glob de header-exceptions.txt :

• Fichiers juridiques et de version — LICENSE, LICENSE.md, LICENSE.txt, NOTICE et VERSION. LICENSE porte la ligne de copyright faisant autorité, dont le validateur license-author-consistency confirme la présence.
• La fixture canonique — schemas/authorship-header.txt. Injecter l'en-tête dans la fixture produirait un en-tête de l'en-tête.
• Ressources *.svg — les commentaires XML sont fragiles pour les marqueurs de commentaire de ligne ; la provenance des SVG est donc portée par le README des ressources et par les sorties raster générées.
• Fichiers JSON (.json) — JSON n'a pas de syntaxe de commentaire. Lorsqu'une attribution est requise pour une configuration JSON, placez un <file>.NOTICE.md voisin.
• Lockfiles — chaque fichier *.lock, package-lock.json, yarn.lock, pnpm-lock.yaml et go.sum. Ces fichiers sont gérés par machine.
• Fichiers générés et minifiés — tout fichier situé sous un répertoire generated/, et les bundles minifiés (*.min.js, *.min.css).
• Contenu tiers vendorisé — fichiers sous _vendor/, vendor/, third_party/ et node_modules/. Ils portent la licence ou la notice propre à l'amont. Injecter notre marqueur par-dessus l'attribution amont constitue une violation de licence.
• État d'audit, de planification et d'environnement — tout ce qui se trouve sous .audit/ et .apothem/, qui contient les plans, la mémoire, les données d'apprentissage et les contextes. Également projects/ et memory/ à la racine de l'arbre de travail, qui appartiennent à l'environnement. Ces arborescences sont ignorées par git ou détenues par l'opérateur, et hors du périmètre de l'arbre publié. La provenance des fichiers de plan est suivie par leur frontmatter (voir plans-discipline.md §3).
• Jeux de données de test — fichiers .yaml, .yml, .txt et .json sous tests/fixtures/. Les fichiers source de test de cette arborescence portent toujours l'en-tête.
• Entrées de test de fumée de l'injecteur — les fichiers situés sous tests/conformity-scenarios/fixtures/F-13-injector-smoke/. Ils restent sans en-tête, car le test de l'injecteur vérifie que celui-ci y ajoute l'en-tête.
• Fichiers de packaging et marqueurs vides — .SRCINFO, que l'analyseur de packaging lit strictement, et les marqueurs de zéro octet .keep, .gitkeep et py.typed.
• Fichiers binaires — les suffixes d'image, de police, d'archive, de média et d'objet compilé listés dans la fixture. Un suffixe que la table de variantes du validateur ne couvre pas est exempté par défaut.

La liste d'exceptions est elle-même encodée sous forme de liste regex/glob dans src/apothem/schemas/header-exceptions.txt et constitue l'entrée de la vérification d'applicabilité du validateur. Les amendements exigent une enquête structurée et un nouvel ADR.

4. Interaction avec la licenceCopy Anchor Link

La ligne SPDX déclare la licence du projet de manière lisible par machine ; le fichier LICENSE la déclare de manière faisant autorité :

• SPDX-License-Identifier: MIT — le marqueur de licence lisible par machine selon la spécification REUSE et le standard SPDX. Les scanners de licence automatisés analysent directement cette ligne ; la syntaxe d'expression SPDX est compatible avec reuse lint, scancode-toolkit, FOSSology et l'outillage de licence du noyau Linux.

• LICENSE à la racine du dépôt — l'instrument juridique faisant autorité, qui porte les termes complets du MIT et le titulaire du copyright. C'est le seul emplacement de la déclaration de copyright ; les en-têtes par fichier s'y réfèrent implicitement via l'identifiant SPDX partagé plutôt que de réénoncer le copyright dans chaque fichier.

Forme à une seule ligne. La provenance par fichier est la seule ligne SPDX ; l'instrument de copyright vit une seule fois dans le LICENSE racine. Les boîtes de bannière multilignes encadrées (copyright, site web, e-mail, lignes de contact enveloppées dans un cadre tracé) sont rejetées par le validateur : elles dupliquent les métadonnées de contact et de copyright dans chaque fichier sans rien ajouter que le marqueur de licence lisible par machine ne fournisse déjà à l'outillage REUSE/SPDX/SBOM. La fixture exacte à l'octet près, située dans src/apothem/schemas/authorship-header.txt, porte la forme à une seule ligne ; le validateur s'exécute contre cette fixture.

Références croisées. Fichier LICENSE (MIT) — l'instrument juridique prévaut en cas de conflit. ADR-0006 documente la justification de la ratification du resserrement de la bannière.

5. Position d'insertionCopy Anchor Link

• La ligne SPDX est le premier contenu du fichier, avec deux exceptions. Une ligne shebang (#!/usr/bin/env bash, #!/usr/bin/env python3, etc.) reste toujours en ligne 1, et la ligne SPDX commence en ligne 2. Dans les fichiers Markdown / MDX avec frontmatter YAML, le frontmatter vient en premier (puce suivante).
• Pour les fichiers Markdown / MDX avec frontmatter YAML, le frontmatter reste à l'octet 0 afin que l'outillage puisse l'analyser, et le commentaire SPDX suit le --- de fermeture, puis vient le corps, qui s'ouvre par le H1 dans les fichiers qui en comportent un. scripts/inject-header.py place le commentaire de cette façon.
• Une unique ligne vide sépare la ligne SPDX du contenu suivant (le H1, le corps, etc.).

6. Politique de visibilité de l'en-têteCopy Anchor Link

Pour les fichiers Markdown et MDX, la ligne SPDX est toujours écrite à l'intérieur de son enveloppe de commentaire (<!-- ... --> ou {/* */}). Elle n'est visible que dans le code source et n'apparaît pas dans la page rendue. L'injecteur ne dispose d'aucun rendu visible ni d'aucune dérogation par fichier. Aucun outil du dépôt ne lit la fixture src/apothem/schemas/header-visibility.yaml.

7. L'injecteur — scripts/inject-header.{sh,py}Copy Anchor Link

Une CLI déterministe qui :

• Prend un ou plusieurs chemins de fichier (ou des globs).
• Détermine l'applicabilité au moyen de la liste d'exceptions (§3).
• Détecte l'état de l'en-tête existant (canonique / malformé / absent) et retire tout bloc de bannière non canonique trouvé, de sorte que les ré-exécutions soient idempotentes.
• Rend la variante SPDX correcte selon le type de fichier (§2).
• Insère à la position correcte (§5), en respectant les shebangs et le frontmatter.
• Ajoute la ligne vide manquante à une ligne SPDX située au point d'insertion et qui n'en a pas, au lieu d'insérer une seconde copie au-dessus.
• Fonctionne selon trois modes : fix-in-place (écrit), emit-patch (affiche un diff unifié), check (sortie avec un code non nul en cas de divergence ; aucune tâche de CI ne l'exécute sur l'arbre suivi).
• Idempotent : l'exécuter deux fois est sans effet.

L'injecteur est invoqué par la cible make headers-fix, qui exécute scripts/inject-header.py --mode fix-in-place.

8. Le validateur — file-headerCopy Anchor Link

Se trouve dans src/apothem/conformity/file_header_grep.py. Pour chaque fichier de l'arbre de travail, le validateur détermine son applicabilité (selon le §3) et, si elle s'applique, vérifie que la ligne SPDX canonique est présente au point d'insertion. Pour la plupart des familles, ce point est la tête du fichier, après un éventuel shebang. Pour les fichiers Markdown et MDX, un bloc frontmatter YAML est d'abord ignoré : la ligne canonique peut donc suivre la clôture, comme l'exige le §5. Les fichiers MDX se résolvent sur la forme {/* */} (§2) et sont vérifiés selon celle-ci. Le validateur et l'injecteur placent le bloc canonique au même index.

S'appuie sur la fixture exacte à l'octet près située dans src/apothem/schemas/authorship-header.txt. L'exécution sur le corpus rapporte, pour ce matcher, un nombre de constats et un échantillon de fichiers signalés. Elle n'affiche ni diff par fichier ni pourcentage de couverture. Le matcher est bloquant : sous --strict, utilisé par la CI et le hook de pre-commit, un constat fait échouer l'exécution. Sans --strict, le portail signale le constat et se termine avec le code 0.

9. Mécanismes d'auto-applicationCopy Anchor Link

La discipline doit survivre à chaque session future et à chaque contributeur futur. Surfaces d'application obligatoires :

1. src/apothem/schemas/authorship-header.txt — la fixture canonique exacte à l'octet près ; une source de vérité unique.
2. scripts/inject-header.{sh,py} — l'injecteur mécanique (§7).
3. Validateur file-header (§8) — signale les divergences sous forme de constat bloquant, qui fait échouer une exécution --strict.
4. Hook de pre-commit — le hook conformity-corpus-perwrite exécute chaque matcher par écriture, y compris le validateur file-header (§8), sur l'arbre suivi, avec --strict. Le matcher file-header est bloquant : un constat bloque donc le commit. Le hook se contente de vérifier. Il n'a pas de mode de correction et n'exécute jamais l'injecteur (§7), qui s'exécute via make headers-fix.
5. Bloc de comportement obligatoire de CLAUDE.md — demande à l'assistant d'injecter la ligne SPDX canonique chaque fois qu'il crée un fichier applicable.
6. Le fichier d'instructions de GitHub Copilot situé dans .github/copilot-instructions.md — demande à Copilot de faire de même lors de la génération de fichiers.
7. Hooks PreToolUse situés dans src/apothem/hooks/messages/pretooluse-{write,edit}-header-guard.md — interceptent les appels d'outils Write/Edit sur les chemins applicables, afin que la ligne SPDX soit injectée à la création du fichier plutôt que relevée plus tard comme constat du validateur. Le vérificateur de la garde, src/apothem/hooks/lib/header_check.py, n'utilise que la bibliothèque standard et lit la fixture et la liste d'exemptions dans le répertoire schemas/ situé à côté de hooks/, de sorte qu'il fonctionne aussi sous le plugin Claude Code, où le paquet apothem n'est pas importable. Il applique les tables de variantes et les règles de site d'insertion de l'injecteur aux fichiers situés dans le projet, et uniquement dans un projet git qui porte la fixture d'en-tête (src/apothem/schemas/authorship-header.txt), car la ligne SPDX est la convention de ce dépôt et non une valeur par défaut pour chaque projet qu'ouvre le plugin.
8. Case à cocher du modèle de PR — affirmation, à l'attention du contributeur, que chaque nouveau fichier porte la ligne SPDX canonique.
9. Ce document (site/content/docs/reference/authorship-header.mdx) — l'explicatif canonique et normatif.

Voir aussiCopy Anchor Link

• ADR-0002 — justification architecturale, alternatives envisagées.
• ADR-0006 — ratification du resserrement de la bannière.
• src/apothem/schemas/authorship-header.txt — la fixture canonique exacte à l'octet près.
• src/apothem/schemas/header-exceptions.txt — la liste d'exceptions (forme regex/glob).
• scripts/inject-header.py et scripts/inject-header.sh — l'injecteur.
• src/apothem/conformity/file_header_grep.py — le validateur.
• Spécification du projet §0.5 + §4.6 — le texte canonique reflété ici.