# 37. Dépendances et scopes

## 37.1 Deux axes indépendants — V1 REQUIS — FIGÉ

Une dépendance est décrite selon deux axes distincts :

```text
kind   = nature logique de la dépendance
source = moyen utilisé pour la localiser/résoudre
```

V1 fixe au minimum les `kind` suivants :

```text
saselang
native
```

Les sources prévues par le schéma V1 sont :

```text
workspace
registry
local
git
artifact
system
```

Toutes les combinaisons ne sont pas nécessairement implémentées dès la première toolchain V1. Le schéma doit néanmoins permettre de les représenter sans refonte ultérieure.

Les dépendances npm/JVM/WASM et autres écosystèmes sont FUTUR V3+, mais doivent pouvoir être ajoutées comme nouveaux `kind`/modes de résolution sans changer l'identité canonique des dépendances.

## 37.2 Syntaxe unique des dépendances — V1 REQUIS — FIGÉE EN PRINCIPE

Tous les scopes et toutes les sources utilisent la même enveloppe TOML :

```toml
[dependencies."vendor/package@requirement"]
kind = "saselang"
source = "registry"
locator = "saselang"
```

Il n'existe pas en parallèle des raccourcis incompatibles de type :

```toml
foo = "^1.2"
foo = "../foo"
```

La clé canonique reste :

```text
vendor/package@requirement
```

`locator` désigne le moyen physique de retrouver la dépendance selon `source`. Sa sémantique exacte dépend de cette source, mais son rôle reste unique.

Exemples :

```toml
[dependencies."acme/math@^2.4"]
kind = "saselang"
source = "git"
locator = "https://example.org/acme/math.git"
```

```toml
[dependencies."acme/local-tools@^1.0"]
kind = "saselang"
source = "local"
locator = "../local-tools"
```

```toml
[dependencies."acme/parser@=1.4.2"]
kind = "saselang"
source = "artifact"
locator = "../libs/parser.saselib"
```

```toml
[dependencies."sdl/sdl@^3.0"]
kind = "native"
source = "system"
locator = "SDL3"
```

## 37.3 Dépendance workspace — V1 REQUIS — FIGÉE EN PRINCIPE

Le workspace peut définir un catalogue :

```toml
[workspace.dependencies."sdl/sdl@^3.0"]
kind = "native"
source = "system"
locator = "SDL3"
```

Un projet doit sélectionner explicitement l'entrée :

```toml
[dependencies."sdl/sdl@^3.0"]
kind = "native"
source = "workspace"
```

Le `kind` doit correspondre à celui défini par le catalogue. Une entrée du catalogue n'est jamais injectée automatiquement dans tous les projets.

## 37.4 Scopes V1 — V1 REQUIS — FIGÉS

Les scopes requis en V1 sont :

```text
dependencies
build.dependencies

dev.dependencies
dev.unit.dependencies
dev.integration.dependencies
dev.environment.dependencies
```

Les scopes suivants sont réservés mais non normatifs tant que leurs workflows ne sont pas définis :

```text
dev.benchmark.dependencies
dev.documentation.dependencies
dev.example.dependencies
```

`dependencies` contient les dépendances du produit.

`build.dependencies` constitue un graphe de visibilité séparé destiné aux outils/hooks de build ; une build-dependency ne devient pas importable par le produit.

`dev.dependencies` est commun aux contextes de développement.

Les scopes `dev.unit`, `dev.integration` et `dev.environment` spécialisent respectivement les tests unitaires, les tests d'intégration et les environnements/outils externes de développement/test.

## 37.5 Héritage des scopes — V1 REQUIS — FIGÉ

```text
dev.unit effective =
    dependencies
  + dev.dependencies
  + dev.unit.dependencies
```

Même règle pour `dev.integration` et `dev.environment`.

`build.dependencies` n'est pas ajouté à la visibilité des imports du produit ni des tests ; il appartient au graphe du système de build.

## 37.6 Remplacement entre scopes — V1 REQUIS — FIGÉ

L'unité de shadowing entre scopes est l'identité :

```text
vendor/package
```

Dès qu'un scope enfant déclare au moins une entrée pour cette identité, toutes les entrées héritées de cette même identité sont masquées dans ce scope.

Si plusieurs versions doivent réellement coexister dans le scope enfant, toutes leurs contraintes disjointes sont redéclarées explicitement dans ce scope.

Aucune fusion implicite champ par champ n'est effectuée.

## 37.7 Multi-version direct — V1 REQUIS — FIGÉ

Un même scope effectif peut contenir plusieurs selectors d'une même identité uniquement si leurs ensembles de versions sont deux à deux disjoints.

Valide :

```text
sdl/sdl@2.1.*
sdl/sdl@^3.0
```

Interdit :

```text
sdl/sdl@^3.0
sdl/sdl@3.1.*
```

Le resolver doit détecter les intersections de ranges et produire une erreur de manifest déterministe avant compilation.

## 37.8 Dépendance Saselang normale — V1 REQUIS — FIGÉ

Une dépendance de `kind = "saselang"` désigne toujours un package logique :

```text
vendor/package@requirement
```

L'artifact de bibliothèque Saselang consommé après résolution/build est une `.saselib`.

Une source `local` ou `git` désigne normalement les sources du package ; `artifact` peut désigner directement une `.saselib` précompilée.

## 37.9 Dépendances natives — V1 REQUIS — FIGÉ EN PRINCIPE

Une bibliothèque native est également encapsulée derrière :

```text
vendor/package@requirement
```

Par exemple :

```text
sdl/sdl@^3.0
```

peut représenter physiquement :

```text
Linux   -> libSDL3.so / SONAME approprié
Windows -> SDL3.dll + import library éventuelle
macOS   -> libSDL3.dylib ou framework approprié
```

Le nom physique n'est jamais l'identité logique de la dépendance.

Le même schéma de dépendance doit pouvoir porter des mappings conditionnés par target/platform/ABI/distribution. La syntaxe exacte du mapping natif sera finalisée avec la FFI et le linker, mais aucune nouvelle forme d'identité ne devra être introduite.

## 37.9.1 Variants natifs et sélection par environnement — V1 REQUIS — SQUELETTE FIGÉ

Une dépendance native possède une déclaration logique commune et peut ajouter une liste homogène de `variants` lorsque sa représentation physique dépend de l'environnement.

Exemple conceptuel :

```toml
[dependencies."sdl/sdl@^3.0"]
kind = "native"
source = "system"
locator = "SDL3"

[[dependencies."sdl/sdl@^3.0".variants]]
platform = "linux"
library = "SDL3"

[[dependencies."sdl/sdl@^3.0".variants]]
platform = "windows"
library = "SDL3"
```

Un variant peut contraindre une combinaison des dimensions suivantes :

```text
target-family
platform
architecture
abi
distribution
distribution-version
capabilities
```

Les variants n'introduisent jamais une nouvelle identité de dépendance : l'identité logique reste `vendor/package@requirement`.

Un variant plus spécifique prévaut sur un variant strictement moins spécifique lorsque les deux correspondent. Si plusieurs variants applicables sont incomparables en spécificité et qu'aucun n'est l'unique meilleur candidat, le manifest est ambigu et la toolchain doit produire une erreur déterministe. L'ordre textuel des variants ne départage jamais un conflit.

Exemple d'ambiguïté à refuser pour un target Linux x86_64 GNU :

```text
variant A : platform=linux, architecture=x86_64
variant B : platform=linux, abi=gnu
```

Aucun des deux n'est strictement plus spécifique que l'autre.

Le noyau V1 des propriétés physiques peut comprendre :

```text
library
linkage = auto | static | shared
deployment = auto | external | bundled
search-paths
include-paths
```

Le modèle réserve sans obligation d'implémentation complète en V1 :

```text
runtime-files
link-files/import-libraries
frameworks
system-packages
resources
plugins
```

Une dépendance native représente donc un package natif logique pouvant comporter plusieurs composants physiques ; elle n'est jamais réduite au modèle « une dépendance = un unique fichier .so/.dll ».

## 37.10 Requirements SemVer — V1 REQUIS — FIGÉ

Les versions suivent strictement SemVer 2.0.0.

Les requirements V1 doivent au minimum pouvoir exprimer :

```text
=1.4.7
^4.5
~1.4.2
3.1.*
>=1.0
>=1.2,<2.0
```

Une version exacte canonique comporte toujours `MAJOR.MINOR.PATCH`.

Une forme abrégée telle que `2.1` ne peut être acceptée que comme requirement/range dont la signification est définie sans ambiguïté ; elle n'est jamais une version exacte SemVer incomplète.

## 37.11 Imports de dépendances — V1 REQUIS — FIGÉ EN PRINCIPE

Toute utilisation d'un symbole provenant d'une dépendance externe au package courant passe par un import explicite :

```text
import type namespace.Type
    from "vendor/package@requirement"
    as LocalType;
```

Même principe pour `func`, `const` et `var`.

`as` est facultatif tant que le nom local est unique ; il devient obligatoire en cas de collision locale.

Le `from` doit référencer un selector effectivement déclaré dans le graphe effectif du fichier. Il ne déclenche aucune résolution indépendante.

La qualification complète sans import reste limitée aux symboles du package courant.


## 37.10 Politique de bootstrap natif et remplacement progressif — DIRECTION FIGÉE

Les premières générations de Saselang peuvent s'appuyer largement sur des bibliothèques natives existantes afin d'accélérer le bootstrap de la toolchain et de l'écosystème.

Cette dépendance initiale n'est pas considérée comme l'architecture finale souhaitée.

La trajectoire retenue consiste à réimplémenter, porter, adapter ou améliorer progressivement les composants pertinents en Saselang, puis à les distribuer sous forme de bibliothèques `.saselib`.

Les familles envisagées peuvent inclure notamment :

```text
MapDB-like
RocksDB-like
PostgreSQL-compatible components
SDL-like multimedia
WebKit/WebView integrations ou remplacements
bibliothèques image/audio/vidéo
outils UI et multimedia
```

Ces noms désignent des directions d'écosystème, pas des APIs déjà réservées.

L'objectif à long terme est de réduire les dépendances natives au strict minimum nécessaire au target. La libc ou son équivalent peut rester utilisée si sa substitution complète n'est pas raisonnable ou n'apporte pas de bénéfice suffisant.

Une réimplémentation Saselang n'est pas tenue de reproduire aveuglément l'architecture d'origine : elle peut corriger, simplifier, étendre ou améliorer l'API et l'implémentation.

L'ambition est de permettre progressivement un écosystème de bibliothèques comparable ou supérieur en richesse fonctionnelle à de grands ensembles tels que Qt ou GTK, sans transformer ces bibliothèques spécialisées en obligations du langage/Core/SDK.

---