Skip to content
Apothem
Справочник

Заголовок авторства — построчная SPDX-строка лицензии

Определение и принудительное применение пофайловых маркеров SPDX-идентификатора лицензии с помощью канонических однострочных заголовков в подходящем синтаксисе комментариев для каждого типа файла.

Каноническая нормативная ссылка для нижестоящих участников. Этот документ зеркалирует разделы Authorship & File-Header спецификации проекта (Spec §0.5 + §4.6); это автономная ссылка, поставляемая с опубликованным репозиторием. Архитектурное обоснование зафиксировано в ADR-0002.

1. Каноническая строка заголовка

Каждый применимый файл в экосистеме ДОЛЖЕН начинаться с одной канонической строки SPDX-идентификатора лицензии в синтаксисе комментариев своего семейства типов файлов. Эта строка — машиночитаемый маркер лицензии файла; её наличие непреложно для неосвобождённых файлов, а её содержимое управляется единым источником истины, а не импровизируется для каждого файла. Полный авторский документ о правах живёт один раз в корневом файле LICENSE репозитория — он не дублируется в каждый исходный файл.

1.1 Информационное содержимое (инвариант)

Каноническое содержимое — это ровно одна строка:

  1. SPDX-License-Identifier: MIT — машиночитаемый маркер лицензии согласно спецификации REUSE, поддерживаемой FSFE; парсится без неоднозначности SPDX-инструментарием (reuse lint, scancode), инструментами ядра Linux и нижестоящими сканерами лицензий. Он не несёт визуальной рамки и не содержит пофайловых строк копирайта, веб-сайта, e-mail или GitHub — пофайловое происхождение по замыслу выражается единственной строкой SPDX (см. §4).

1.2 Эталонная форма (семейство #-комментариев)

Канонический текст — записанный здесь в форме #-синтаксиса комментариев — имеет своим источником истины src/apothem/schemas/authorship-header.txt:

# SPDX-License-Identifier: MIT

Этот текст — единственный авторитетный источник. Валидатор file-header (§7) работает против этой байт-точной фикстуры. Любое расхождение между строкой заголовка файла и этой фикстурой (с учётом подстановки синтаксиса по §2) — это сбой CI.

2. Варианты по типам файлов (байт-точные)

Информационное содержимое строки инвариантно; меняется только её синтаксис комментариев по типу файла. Полная таблица вариантов по типам файлов:

Семейство типов файловСинтаксис комментариевРендеринг варианта
Семейство # — .sh, .bash, .zsh, .py, .rb, .pl, .ps1, .yml, .yaml, .toml, .cff, .gitignore, .gitattributes, .editorconfig, .shellcheckrc, .env.example, Makefile, Dockerfile, Procfile, CODEOWNERS, PKGBUILD, безрасширительные shell-точки входа вроде scripts/apothemстроковый комментарий ## SPDX-License-Identifier: MIT
Семейство // — .js, .jsx, .mjs, .cjs, .ts, .tsx, .go, .rs, .java, .kt, .swift, .c, .cc, .cpp, .h, .hpp, .cs, .scala, .dart, .jsoncстроковый комментарий //// SPDX-License-Identifier: MIT
Семейство блочных комментариев — .html, .htm, .md, .markdown, .xml, .vue (область шаблона), .php (область шаблона)<!-- ... --><!-- SPDX-License-Identifier: MIT -->
MDX (.mdx){/* ... */} (комментарий JSX-выражения){/* SPDX-License-Identifier: MIT */}
Семейство C-блоков — .css, .scss, .less, .sql (/* */)/* ... *//* SPDX-License-Identifier: MIT */
Семейство ; — .ini, .cfg, некоторые .lisp/.scmстроковый комментарий ;; SPDX-License-Identifier: MIT
Семейство -- — .sql, .lua, .hs, .elm, .adaстроковый комментарий ---- SPDX-License-Identifier: MIT
Lock-файлы / сгенерированные / JSONнет / неприменимоОсвобождён. См. §3 Список исключений.

Вариант Markdown (канонический рендеринг):

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

Обёртка HTML-комментария (или MDX {/* */}) рендерится невидимо, поэтому отображаемая поверхность остаётся чистой, а внутрисходный маркер лицензии остаётся машиночитаемым для всех типов файлов.

3. Список исключений (категорически освобождены)

Следующие классы освобождены от строки SPDX-заголовка. Проверка применимости валидатора file-header возвращает для них not-applicable:

  • LICENSE — сам по себе юридический инструмент; несёт авторитетную строку копирайта, наличие которой подтверждает валидатор license-author-consistency.
  • *.svg-ассеты — XML-комментарии ненадёжны для строковых маркеров комментариев, поэтому происхождение SVG несут README ассета и сгенерированные растровые выходы.
  • CHANGELOG.md — документ примечаний к выпуску с фиксированным форматом; строка SPDX появляется как одиночный HTML-комментарий над заголовком changelog, а не вплетается в формат.
  • JSON-файлы (.json) — у JSON нет синтаксиса комментариев. Где для JSON-конфига требуется атрибуция, размещайте соседний <file>.NOTICE.md.
  • Lock-файлы — package-lock.json, yarn.lock, pnpm-lock.yaml, Cargo.lock, Pipfile.lock, poetry.lock, go.sum и т. д. (управляемые машиной).
  • Сгенерированные файлы — всё с маркером # Generated by ... или // Generated by ..., либо всё, соответствующее .gitattributes linguist-generated=true.
  • Вендорённое стороннее содержимое — файлы под vendor/, third_party/, node_modules/. Они несут собственную лицензию/уведомление вышестоящего источника; внедрение нашего маркера поверх вышестоящей атрибуции — это нарушение лицензии.
  • Файлы .audit/ — gitignore-эфемера; вне области опубликованного дерева.
  • Файлы планов (<project-root>/.apothem/plans/** и устаревший <project-root>/.plans/**) — gitignore-эфемера; происхождение — это фронтматтер плана (см. plans-discipline.md §3).
  • Пустые маркеры — .keep, .gitkeep и т. д. (семантически нулевого размера).
  • Бинарные файлы любого рода.

Сам список исключений закодирован как список regex/glob в src/apothem/schemas/header-exceptions.txt и служит входом для проверки применимости валидатора. Поправки требуют структурированного запроса и нового ADR.

4. Взаимодействие лицензий

Строка SPDX объявляет лицензию проекта машиночитаемо; файл LICENSE объявляет её авторитетно:

  • SPDX-License-Identifier: MIT — машиночитаемый маркер лицензии согласно спецификации REUSE и стандарту SPDX. Автоматические сканеры лицензий парсят эту строку напрямую; синтаксис SPDX-выражений кросс-совместим с reuse lint, scancode-toolkit, FOSSology и инструментарием лицензий ядра Linux.
  • Корневой LICENSE репозитория — авторитетный юридический инструмент, несущий полные условия MIT и правообладателя. Это единственный дом для заявления о копирайте; пофайловые заголовки ссылаются на него неявно через общий SPDX-идентификатор, а не переизлагают копирайт в каждом файле.

Однострочная форма. Пофайловое происхождение — это единственная строка SPDX; авторский документ о правах живёт один раз в корневом LICENSE. Рамочные многострочные баннер-боксы (копирайт, веб-сайт, e-mail, контактные строки, обёрнутые в линованную рамку) отвергаются валидатором: они дублируют контактные метаданные и метаданные копирайта в каждом файле, не добавляя ничего, чего машиночитаемый маркер лицензии уже не предоставляет инструментарию REUSE/SPDX/SBOM. Байт-точная фикстура в src/apothem/schemas/authorship-header.txt несёт однострочную форму; валидатор работает против этой фикстуры.

Перекрёстные ссылки. Файл LICENSE (MIT) — юридический инструмент имеет приоритет в случае конфликта. ADR-0006 документирует обоснование ратификации сужения баннера.

5. Позиция вставки

  • Строка SPDX — это первое содержимое файла, с одним-единственным исключением: строка shebang (#!/usr/bin/env bash, #!/usr/bin/env python3 и т. д.), которая всегда остаётся строкой 1; строка SPDX начинается со строки 2.
  • Для файлов Markdown / MDX с YAML-фронтматтером комментарий SPDX располагается в самом верху, затем следует YAML-фронтматтер, затем H1 и тело. Отображаемый вывод начинается с невидимого комментария, затем фронтматтер парсится инструментарием, затем течёт видимое содержимое.
  • Одна пустая строка отделяет строку SPDX от следующего содержимого (--- фронтматтера, преемника shebang, H1 и т. д.).

6. Политика видимости заголовка

Конкретно для файлов Markdown строка SPDX по умолчанию невидима — обёрнута в <!-- ... --> (или {/* */} для MDX), видима только в исходнике. Это правильная политика для README, CONTRIBUTING, CLAUDE.md, поддерживаемых файлов инструкций для harness, SKILL.md навыка, тел команд, стилей вывода и страниц документации. Видимый рендеринг (строка SPDX как обычный текст или огороженный блок в верхней части вывода) разрешён для автономных справочных документов, которым выгодно сразу читаемое происхождение; политика задаётся по классу файла в src/apothem/schemas/header-visibility.yaml (по умолчанию invisible), с разрешённым маркером переопределения на уровне файла <!-- header-visibility: visible --> сразу после строки.

7. Инжектор — scripts/inject-header.{sh,py}

Детерминированный CLI, который:

  • Принимает один или несколько путей к файлам (или glob'ов).
  • Определяет применимость через список исключений (§3).
  • Обнаруживает существующее состояние заголовка (канонический / неправильный / отсутствующий), снимая любой неканонический баннер-блок, который находит, чтобы повторные запуски были идемпотентны.
  • Рендерит корректный вариант SPDX по типу файла (§2).
  • Вставляет в корректную позицию (§5), уважая shebang и фронтматтер.
  • Работает в трёх режимах: fix-in-place (записывает), emit-patch (печатает унифицированный diff), check (exit-non-zero при любом расхождении — используется CI).
  • Идемпотентен: двойной запуск — это no-op.

Инжектор вызывается Make-таргетами, которые формируют новые файлы с предвставленной строкой SPDX (make headers-fix и каркасы make new-*), и pre-commit-хуком в режиме --fix.

8. Валидатор — file-header (CI)

Живёт в src/apothem/conformity/file_header_grep.py. Для каждого файла в рабочем дереве валидатор просматривает его применимость (по §3) и, если применимо, утверждает, что каноническая строка SPDX присутствует в голове файла — впереди всего прочего содержимого, и единственное разрешённое предшествующее содержимое — это shebang (§5).

Подкреплён байт-точной фикстурой в src/apothem/schemas/authorship-header.txt. Сообщает пофайловый diff и агрегированный % покрытия в сводке CI. Проваливает сборку при любом расхождении.

9. Механизмы самоприменения

Эта дисциплина должна пережить каждую будущую сессию и каждого будущего участника. Обязательные поверхности применения:

  1. src/apothem/schemas/authorship-header.txt — байт-точная каноническая фикстура; единый источник истины.
  2. scripts/inject-header.{sh,py} — механический инжектор (§7).
  3. Валидатор CI file-header (§8) — проваливает сборку при любом расхождении.
  4. Pre-commit-хук — запускает валидатор с --fix на застейдженных файлах, подключён к инжектору.
  5. Блок обязательного поведения CLAUDE.md — инструктирует помощника внедрять каноническую строку SPDX всякий раз при создании применимого файла.
  6. Файл инструкций для поддерживаемого harness по каноническому пути .github/ — инструктирует среду выполнения harness делать то же при генерации файла.
  7. PreToolUse-хуки в src/apothem/hooks/messages/pretooluse-{write,edit}-header-guard.md — перехватывают вызовы инструментов Write/Edit на применимых путях, так что строка SPDX внедряется при создании файла, а не обнаруживается позже как сбой CI.
  8. Чекбокс шаблона PR — ориентированное на участника утверждение, что каждый новый файл несёт каноническую строку SPDX.
  9. Этот документ (site/content/docs/reference/authorship-header.mdx) — канонический нормативный разъяснитель.

См. также

Соглашения для многоповерхностных окружений

Каноническая нормативная справка по конфигурации и согласованности многоповерхностных ассистентов по написанию кода в чат-консолях, IDE-автодополнении и средах проверки PR.

Манифест закрепления зависимостей

Политика объявления зависимостей, охватывающая диапазоны среды выполнения Python, инструменты разработки, lock-файлы инструментов выпуска и утверждённые нижние границы версий для каждой поверхности сборки.

On this page

1. Каноническая строка заголовка1.1 Информационное содержимое (инвариант)1.2 Эталонная форма (семейство #-комментариев)2. Варианты по типам файлов (байт-точные)3. Список исключений (категорически освобождены)4. Взаимодействие лицензий5. Позиция вставки6. Политика видимости заголовка7. Инжектор — scripts/inject-header.{sh,py}8. Валидатор — file-header (CI)9. Механизмы самопримененияСм. также