@ucm-kit/adapter-typescript 0.1.0 → 0.1.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 speckaina
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,20 +1,85 @@
 # @ucm-kit/adapter-typescript
 
-Adaptateur optionnel pour les repositories TypeScript qui consomment des
-contrats UCM. Il ajoute deux capacités sans faire dépendre `@ucm-kit/core` du
-compilateur TypeScript :
-
-- `ucm check` le découvre automatiquement lorsqu'il est installé dans le
-  repository et compare les props, les BOOLEAN lues et les compositions ;
-- `ucm-typescript` génère les unions d'enums dans
-  `src/generated/contracts/` (ou dans le dossier donné à `--out`).
+Optional adapter for TypeScript repositories that consume UCM contracts. It adds
+two capabilities without making [`@ucm-kit/core`](https://www.npmjs.com/package/@ucm-kit/core)
+depend on the TypeScript compiler, a 23 MB dependency no other consumer should
+pay for.
 
 ```sh
-npm install --save-dev @ucm-kit/adapter-typescript@0.1.0 @ucm-kit/cli@0.1.7
+npm install --save-dev @ucm-kit/adapter-typescript@0.1.5 @ucm-kit/cli@0.1.12
 npx ucm-typescript
 npx --no-install ucm check
 ```
 
-La parité exige un `tsconfig.json` à la racine. Les valeurs d'enum réellement
-traitées par le comportement du composant restent hors de la garantie statique :
-le contrat décrit les vues disponibles, pas la logique qui en choisit une.
+## Static parity
+
+`ucm check` discovers this package when it is installed in the repository, and
+compares each contract to the component that implements it. Six gaps are
+reported:
+
+| Gap | What it means |
+|---|---|
+| Missing prop | The contract declares a prop the component's public API does not expose |
+| Incompatible type | The prop exists, with a type the contract does not allow |
+| Value the code does not offer | The contract publishes an enum value the declared union leaves out |
+| Unused boolean | A `BOOLEAN` prop is declared but never read by the component |
+| Unused enum | An enum prop is declared but never read by the component |
+| Wrong composition cardinality | A declared dependency is rendered a different number of times than the contract says |
+
+Parity requires a `tsconfig.json` at the root. Props are read with the
+TypeScript type checker; compositions are counted by their occurrences in JSX.
+
+Every one of these **warns without blocking**. They accuse the code, not the
+contract, and fixing them is a developer's job, not a re-export.
+
+## The convention composition counting assumes
+
+**Counting is static: a dependency rendered by a loop is not counted.** Keep
+every occurrence explicit in the source, and neutralise in place the one a
+given view does not show, rather than removing it. Without that, a list built
+with `.map()` reports a cardinality gap the contract did not intend.
+
+This is a convention, not a mechanism: there is no exception list, no
+annotation, and no per-component opt-out. The warning itself says what it does
+not see, and it blocks nothing.
+
+## What it does not measure
+
+Enum values are compared by the **declared union only**. A union smaller than
+the contract is reported; a union that accepts more is not, because accepting
+more contradicts nothing. On a widened type such as `string`, no value is
+resolved and nothing is reported.
+
+What the component does with a value stays outside the static guarantee. A
+`switch` with a `default`, a partial mapping table, a value forwarded to a
+child, a table held in another file and a business rule that substitutes one
+value for another are all legitimate; telling them apart from an oversight
+would require the contract to describe behaviour. A contract describes the
+views that exist; it says nothing about the logic that picks one.
+
+A prop relayed through `{...rest}` without being read is reported as unused.
+Following a spread would mean knowing the child's contract, and the warning
+blocks nothing.
+
+Nothing here executes a render. Parity is a comparison of surfaces.
+
+None of this exists for a repository without this adapter, so the **absence of
+these messages means nothing**: it is a capability of one adapter, never a
+guarantee of the format.
+
+## Generated types
+
+```sh
+npx ucm-typescript            # writes to src/generated/contracts/
+npx ucm-typescript --out <dir>
+```
+
+It derives the enum unions from the contracts, so that a component's props can
+be typed against the contract rather than against a hand-copied list.
+
+## Status
+
+**0.x, the public surface is not frozen.** Pin an exact version, without `^`.
+
+- [Repository and issues](https://github.com/Vassili-g/UCM-Exporter)
+- [MIT licensed](https://github.com/Vassili-g/UCM-Exporter/blob/main/LICENSE)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ucm-kit/adapter-typescript",
-  "version": "0.1.0",
+  "version": "0.1.5",
   "description": "Adaptateur TypeScript UCM : parité statique des composants et génération des types dérivés des contrats.",
   "type": "module",
   "license": "MIT",
@@ -20,7 +20,8 @@
   },
   "files": [
     "src",
-    "README.md"
+    "README.md",
+    "LICENSE"
   ],
   "exports": {
     ".": {
@@ -34,7 +35,7 @@
     "test": "node scripts/run-tests.cjs"
   },
   "dependencies": {
-    "@ucm-kit/core": "0.1.11",
+    "@ucm-kit/core": "0.1.16",
     "typescript": ">=5.5.0 <6"
   }
 }

package/src/index.d.mts

@@ -18,7 +18,9 @@ export function ecartsDeParite(
   fonctionAbsente: string | null;
   manquantes: string[];
   typesIncorrects: Array<{ prop: string; attendu: string; recu: string }>;
+  valeursNonImplementees: Array<{ prop: string; valeurs: string[] }>;
   booleensNonUtilises: string[];
+  enumsSansEffet: Array<{ prop: string; valeurs: string[] }>;
   compositionsIncorrectes: Array<{ component: string; attendu: number; rendu: number }>;
 };
 export function typesDuContrat(contrat: unknown): null | {

package/src/parite.mjs

@@ -285,9 +285,18 @@ export function lireApiPublique(fichiers, racine) {
         const estBoolean = significatifs.length > 0 && significatifs.every(
           (item) => Boolean(item.flags & (ts.TypeFlags.Boolean | ts.TypeFlags.BooleanLiteral)),
         );
+        // Le texte écrit dans le source ne dit rien d'un alias : `Ton | undefined`
+        // masque autant une union complète qu'une union amputée. La résolution,
+        // elle, rend les littéraux même dérivés d'un `as const`, et ne rend rien
+        // d'un type élargi, donc silence plutôt que faux positif.
+        const valeurs = significatifs.length > 0
+          && significatifs.every((item) => item.isStringLiteral())
+          ? significatifs.map((item) => item.value)
+          : null;
         return [membre.getName(), {
           type: estBoolean ? "boolean" : "autre",
           typescript: verificateur.typeToString(typeMembre),
+          valeurs,
           utilisee: consommees.has(membre.getName()),
         }];
       }));
@@ -312,7 +321,9 @@ export function ecartsDeParite(contrat, releve, nomInterface, options = {}) {
     fonctionAbsente: null,
     manquantes: [],
     typesIncorrects: [],
+    valeursNonImplementees: [],
     booleensNonUtilises: [],
+    enumsSansEffet: [],
     compositionsIncorrectes: [],
   };
   if (!releve) {
@@ -360,8 +371,35 @@ export function ecartsDeParite(contrat, releve, nomInterface, options = {}) {
     ))
     .map(([nom]) => nom)
     .sort();
+  const enums = declarees.filter(([nom, prop]) => (
+    nom in props && prop?.type === "enum" && Array.isArray(prop.values)
+  ));
+  // Une union plus large que le contrat ne se rapporte pas : accepter plus ne
+  // contredit rien, et le dire ferait du contrat un plafond.
+  const valeursNonImplementees = enums
+    .filter(([nom]) => Array.isArray(props[nom].valeurs))
+    .map(([nom, prop]) => ({
+      prop: nom,
+      valeurs: prop.values.filter((valeur) => !props[nom].valeurs.includes(valeur)),
+    }))
+    .filter(({ valeurs }) => valeurs.length > 0)
+    .sort((gauche, droite) => gauche.prop.localeCompare(droite.prop));
+  // Le même signal que `booleensNonUtilises`, sur le même relevé : le taire ici
+  // quand on le dit là serait une incohérence, pas une décision.
+  const enumsSansEffet = enums
+    .filter(([nom]) => props[nom].utilisee !== true)
+    .map(([nom, prop]) => ({ prop: nom, valeurs: [...prop.values] }))
+    .sort((gauche, droite) => gauche.prop.localeCompare(droite.prop));
 
-  return { ...vide, manquantes, typesIncorrects, booleensNonUtilises, compositionsIncorrectes };
+  return {
+    ...vide,
+    manquantes,
+    typesIncorrects,
+    valeursNonImplementees,
+    booleensNonUtilises,
+    enumsSansEffet,
+    compositionsIncorrectes,
+  };
 }
 
 /** Surface que `@ucm-kit/core/lecteurs` attend d'un adaptateur. */