@dsivd/prestations-ng 19.0.7 → 19.0.8

package/eslint/signal-kinds.mjs

@@ -0,0 +1,57 @@
+/**
+ * Classification of a signal member, shared by the TypeScript-API resolution of
+ * `signal-names.mjs` and the ESLint-AST checks of the rules, which read the same names out
+ * of two different trees.
+ *
+ * The value of a signal is never to be mutated, whatever its kind — a mutation notifies
+ * none of its dependents. `VIEW_QUERY` is the single exception: it hands out a DOM element
+ * or a component instance, and mutating that is the reason for asking for it.
+ *
+ * The kinds beyond `WRITABLE` differ only in the advice that applies, since none of them
+ * has a `.set()`.
+ */
+
+export const WRITABLE = "writable";
+export const COMPUTED = "computed";
+export const INPUT = "input";
+export const FROM_OBSERVABLE = "fromObservable";
+export const VIEW_QUERY = "viewQuery";
+// A read-only signal whose factory its declaration does not name: it may be a view query.
+export const AMBIGUOUS = "ambiguous";
+
+// `output()` is absent: an output is never called, it is emitted.
+const KIND_BY_FACTORY = new Map([
+  ["signal", WRITABLE],
+  ["model", WRITABLE],
+  ["linkedSignal", WRITABLE],
+  ["computed", COMPUTED],
+  ["input", INPUT],
+  ["toSignal", FROM_OBSERVABLE],
+  ["viewChild", VIEW_QUERY],
+  ["viewChildren", VIEW_QUERY],
+  ["contentChild", VIEW_QUERY],
+  ["contentChildren", VIEW_QUERY],
+]);
+
+/**
+ * Declaration files qualify the types with the namespace they were imported under —
+ * `readonly icon: _angular_core.ModelSignal<IconProp>` — hence the comparison on the last
+ * segment only.
+ *
+ * `Signal<T>` is where a published declaration loses the information: a `computed()`, a
+ * `toSignal()` and a view query all end up spelled that way. It has to stay `AMBIGUOUS`,
+ * because this library alone publishes 54 view queries — `AbstractPageComponent` and
+ * `FoehnInputComponent` among them — and reporting them would break every project that
+ * extends one and touches the element it queried.
+ */
+const KIND_BY_TYPE = new Map([
+  ["WritableSignal", WRITABLE],
+  ["ModelSignal", WRITABLE],
+  ["InputSignal", INPUT],
+  ["InputSignalWithTransform", INPUT],
+  ["Signal", AMBIGUOUS],
+]);
+
+export const factoryKind = (name) => KIND_BY_FACTORY.get(name);
+
+export const typeKind = (name) => KIND_BY_TYPE.get(name);

package/eslint/signal-names.mjs

@@ -2,8 +2,10 @@ import { readFileSync, statSync } from "node:fs";
 import { dirname } from "node:path";
 import ts from "typescript";
 
+import { factoryKind, typeKind } from "./signal-kinds.mjs";
+
 /**
- * Collects the signal member names of a component, walking up its inheritance chain.
+ * Collects the signal members of a component, walking up its inheritance chain.
  *
  * Base classes are resolved automatically: the `extends` clause is matched against the
  * imports of the file, the module is resolved the way TypeScript would (relative paths,
@@ -11,31 +13,6 @@ import ts from "typescript";
  * to be declared by hand.
  */
 
-// `output()` is absent: an output is never called, it is emitted.
-const SIGNAL_FACTORIES = new Set([
-  "input",
-  "model",
-  "computed",
-  "signal",
-  "linkedSignal",
-  "toSignal",
-  "viewChild",
-  "viewChildren",
-  "contentChild",
-  "contentChildren",
-]);
-
-// Types of a signal member. Declaration files qualify them with the namespace they were
-// imported under: `readonly icon: _angular_core.ModelSignal<IconProp>`, hence the
-// comparison on the last segment only.
-const SIGNAL_TYPES = new Set([
-  "Signal",
-  "WritableSignal",
-  "InputSignal",
-  "InputSignalWithTransform",
-  "ModelSignal",
-]);
-
 const parsedFiles = new Map();
 const compilerOptionsByDirectory = new Map();
 
@@ -96,31 +73,33 @@ const resolveModule = (specifier, containingFile) =>
 const lastSegmentOf = (entityName) =>
   ts.isQualifiedName(entityName) ? entityName.right.text : entityName.text;
 
-const isSignalType = (typeNode) =>
-  !!typeNode &&
-  ts.isTypeReferenceNode(typeNode) &&
-  SIGNAL_TYPES.has(lastSegmentOf(typeNode.typeName));
+const kindOfType = (typeNode) =>
+  typeNode && ts.isTypeReferenceNode(typeNode)
+    ? typeKind(lastSegmentOf(typeNode.typeName))
+    : undefined;
 
-const isSignalFactoryCall = (expression) => {
+const kindOfInitializer = (expression) => {
   if (!expression || !ts.isCallExpression(expression)) {
-    return false;
+    return undefined;
   }
   // `input.required<T>()` and `viewChild.required(…)` unwrap to their factory.
   let callee = expression.expression;
   while (ts.isPropertyAccessExpression(callee)) {
     callee = callee.expression;
   }
-  return ts.isIdentifier(callee) && SIGNAL_FACTORIES.has(callee.text);
+  return ts.isIdentifier(callee) ? factoryKind(callee.text) : undefined;
 };
 
-const isSignalMember = (member) => {
+// Kind of signal a class member holds, `undefined` when it holds none. The initializer
+// comes first: it names the factory, where the type may only say `Signal<T>`.
+const kindOfMember = (member) => {
   if (ts.isGetAccessor(member)) {
-    return isSignalType(member.type);
+    return kindOfType(member.type);
   }
-  return (
-    ts.isPropertyDeclaration(member) &&
-    (isSignalType(member.type) || isSignalFactoryCall(member.initializer))
-  );
+  if (!ts.isPropertyDeclaration(member)) {
+    return undefined;
+  }
+  return kindOfInitializer(member.initializer) ?? kindOfType(member.type);
 };
 
 const findClass = (sourceFile, className) => {
@@ -174,7 +153,7 @@ const reExportedModulesOf = (sourceFile) =>
     .filter((statement) => ts.isExportDeclaration(statement) && statement.moduleSpecifier)
     .map((statement) => statement.moduleSpecifier.text);
 
-const collect = (path, className, names, visited) => {
+const collect = (path, className, kinds, visited) => {
   const key = `${path}::${className ?? "*"}`;
   if (visited.has(key)) {
     return;
@@ -195,7 +174,7 @@ const collect = (path, className, names, visited) => {
     for (const specifier of reExportedModulesOf(sourceFile)) {
       const target = resolveModule(specifier, path);
       if (target) {
-        collect(target, className, names, visited);
+        collect(target, className, kinds, visited);
       }
     }
     return;
@@ -203,8 +182,13 @@ const collect = (path, className, names, visited) => {
 
   for (const classDeclaration of classDeclarations) {
     for (const member of classDeclaration.members) {
-      if (member.name && ts.isIdentifier(member.name) && isSignalMember(member)) {
-        names.add(member.name.text);
+      if (!member.name || !ts.isIdentifier(member.name)) {
+        continue;
+      }
+      const kind = kindOfMember(member);
+      // A subclass overriding a member wins: it is collected first.
+      if (kind && !kinds.has(member.name.text)) {
+        kinds.set(member.name.text, kind);
       }
     }
 
@@ -214,19 +198,29 @@ const collect = (path, className, names, visited) => {
     }
     // Declaration bundles are flattened: the base class often sits in the same file.
     if (findClass(sourceFile, baseName)) {
-      collect(path, baseName, names, visited);
+      collect(path, baseName, kinds, visited);
       continue;
     }
     const imported = importOf(sourceFile, baseName);
     const target = imported && resolveModule(imported.specifier, path);
     if (target) {
-      collect(target, imported.exportedName, names, visited);
+      collect(target, imported.exportedName, kinds, visited);
     }
   }
 };
 
-export const collectSignalNames = (componentPath) => {
-  const names = new Set();
-  collect(componentPath, undefined, names, new Set());
-  return names;
+/**
+ * Signal members of a component, mapped to their kind. `undefined` when the file
+ * cannot be read: unknown signals must be distinguished from a component that has none.
+ */
+export const collectSignalKinds = (componentPath) => {
+  if (!parseFile(componentPath)) {
+    return undefined;
+  }
+  const kinds = new Map();
+  collect(componentPath, undefined, kinds, new Set());
+  return kinds;
 };
+
+export const collectSignalNames = (componentPath) =>
+  new Set(collectSignalKinds(componentPath)?.keys() ?? []);