@koobiq/components 20.4.2 → 21.0.1

package/schematics/migrations/link-signals/data.cjs

@@ -0,0 +1,116 @@
+'use strict';
+
+/**
+ * Data for the `link-signals` migration.
+ *
+ * The three inputs the automated signal migration skipped were all accessors, and each of them did
+ * something beyond storing a value.
+ *
+ * - `link.disabled` → `link.disabled()` (auto-fixed, with a caveat about what it reports)
+ * - `link.tabIndex` → a signal whose value changed: the getter folded in the disabled state (warn)
+ * - `link.print` → was write-only (a setter with no getter), so it has no read to rewrite (warn on writes)
+ * - the icon and print bookkeeping → `protected`, `private` or gone (warn)
+ *
+ * `disabledSignal` stays a public `WritableSignal<boolean>`: `kbqTooltip` accepts a link through
+ * `forDisabledComponent` and reads it, and that contract is typed on the tooltip side.
+ */
+/** Members of `KbqLink` a read of which must become a call. Auto-fixed. */
+const SIGNAL_MEMBERS = ['disabled'];
+/** Signal-API methods reachable on a signal; a read followed by one is already migrated. */
+const SIGNAL_API_METHODS = new Set(['set', 'update', 'asReadonly', 'subscribe']);
+/** TypeScript type annotation that marks a receiver as a link. */
+const LINK_TYPE = 'KbqLink';
+/** Import specifier that marks a file as a link consumer. */
+const LINK_PACKAGE = '@koobiq/components/link';
+/**
+ * `tabIndex` became a read-only `InputSignal` AND changed its value: the getter returned `-1` for a
+ * disabled link, it now reports what was bound. The host attribute still goes to `-1` while the link is
+ * disabled, so nothing about focus behavior changed — only a programmatic read sees the difference, and a
+ * mechanical `()` append would silently change it.
+ */
+const VALUE_CHANGED_MEMBERS = ['tabIndex'];
+/** The write-only input: a setter with no getter, so there is no read to rewrite. */
+const WRITE_ONLY_MEMBERS = ['print'];
+/** Icon and print bookkeeping that became `protected`: a subclass still sees it, nothing outside does. */
+const PROTECTED_MEMBERS = ['hasIcon', 'printMode', 'printUrl'];
+/** Members that became `private`, so not even a subclass can name them. */
+const PRIVATE_MEMBERS = ['icons', 'nativeElement'];
+/** Members that are gone from the class altogether, including the lifecycle hook a subclass could call. */
+const REMOVED_MEMBERS = ['icon', 'destroyRef', 'ngAfterContentInit'];
+/** Every member a consumer can no longer read, whichever visibility it landed on. */
+const HIDDEN_MEMBERS = [...PROTECTED_MEMBERS, ...PRIVATE_MEMBERS, ...REMOVED_MEMBERS];
+/** Every member the access pass looks at, whatever it ends up doing with it. */
+const KNOWN_MEMBERS = [
+    ...SIGNAL_MEMBERS,
+    ...VALUE_CHANGED_MEMBERS,
+    ...WRITE_ONLY_MEMBERS,
+    ...HIDDEN_MEMBERS
+];
+const protectedMessage = (members) => `These KbqLink members are \`protected\` now: ${[...members].join(', ')}. They are the print and icon ` +
+    'bookkeeping: the classes and the `print` attribute the directive puts on the anchor are the contract, ' +
+    'not the state behind them.';
+const privateMessage = (members) => `These KbqLink members are \`private\` now, so a subclass cannot name them either: ` +
+    `${[...members].join(', ')}. \`nativeElement\` has a public accessor - call \`getHostElement()\`; the ` +
+    'icon query is internal, and the icon spacing classes are what it produces.';
+const removedMessage = (members) => `These KbqLink members are gone: ${[...members].join(', ')}. \`icon\` is dropped - \`icons\` already ` +
+    'answered the one question it was asked - `destroyRef` is not held any more, so inject `DestroyRef` ' +
+    'yourself if a subclass needs it, and `ngAfterContentInit` is not implemented, so an override calling ' +
+    '`super.ngAfterContentInit()` no longer compiles: the icon classes follow the content query on their own.';
+/** Reported for a programmatic write: every member is an `input()`, so the write no longer compiles. */
+const writeMessage = (members) => `These are \`input()\`s now, so a programmatic write no longer compiles: ${[...members].join(', ')}. ` +
+    'Bind them in the template instead. `print` was a write-only input - a setter with no getter - and ' +
+    '`tabIndex` had a setter too. The write is left untouched so the error points at your call site.';
+const valueChangedMessage = (members) => `${[...members].join(', ')} is a read-only InputSignal - read it as \`link.tabIndex()\`. Its value also ` +
+    'changed: the getter used to fold in the disabled state and report -1 for a disabled link, it now ' +
+    'reports what was bound. The host attribute still goes to -1 while the link is disabled. Migrate by hand.';
+/**
+ * Emitted next to the files the rewrite touched, because the call it writes is correct but does not report
+ * quite the same value. The old getter mirrored `disabledSignal`, which `kbqTooltip` writes directly through
+ * `forDisabledComponent`; the input reports only what was bound.
+ */
+const DISABLED_CAVEAT = '  `disabled` reads here were rewritten to `disabled()`. That reports the bound input, while the old ' +
+    'getter mirrored `disabledSignal` - the effective state the host bindings render. The two differ only ' +
+    'if something writes `disabledSignal` directly, which is what `kbqTooltip` does through ' +
+    '`forDisabledComponent`: read `disabledSignal()` at those call sites.';
+/**
+ * Reported for a read through a signal query, which is a signal holding the directive: the read needs two
+ * calls rather than one. Emitted from the AST pass rather than a regex, so it follows the same receiver
+ * resolution as the rewrite - the decorator form is a plain annotated field that the rewrite handles.
+ *
+ * `viewChild()` without `.required` is typed `Signal<KbqLink | undefined>`, so the safe spelling differs
+ * between the two forms.
+ */
+const signalQueryMessage = (member, required) => `A signal query holds the directive behind a call of its own, so reading \`${member}\` through it needs ` +
+    `a double call: \`this.link()${required ? '' : '?'}.${member}()\`.` +
+    (required ? '' : ' The query is optional, so keep the `?.`.') +
+    ' Those reads are left untouched - migrate them by hand.';
+/** Printed once per project, after the per-file reports. */
+const SUMMARY = [
+    '  `print` accepts `string | null` instead of `any`, and `[print]="undefined"` no longer marks the link ' +
+        'as printable. The old setter tested `value !== null`, so an explicit `undefined` passed it and added ' +
+        '`kbq-link_print` while printing the href; the input tests `!= null`, which covers both. An unbound ' +
+        'link behaves exactly as before: no class, and the href still lands in the `print` attribute.',
+    '  A disabled link carries `aria-disabled` instead of the `disabled` attribute, which is not valid HTML ' +
+        'on an anchor and told assistive tech nothing. If you styled `a[kbq-link][disabled]`, match ' +
+        '`.kbq-disabled` or `[aria-disabled]` instead.'
+];
+
+exports.DISABLED_CAVEAT = DISABLED_CAVEAT;
+exports.HIDDEN_MEMBERS = HIDDEN_MEMBERS;
+exports.KNOWN_MEMBERS = KNOWN_MEMBERS;
+exports.LINK_PACKAGE = LINK_PACKAGE;
+exports.LINK_TYPE = LINK_TYPE;
+exports.PRIVATE_MEMBERS = PRIVATE_MEMBERS;
+exports.PROTECTED_MEMBERS = PROTECTED_MEMBERS;
+exports.REMOVED_MEMBERS = REMOVED_MEMBERS;
+exports.SIGNAL_API_METHODS = SIGNAL_API_METHODS;
+exports.SIGNAL_MEMBERS = SIGNAL_MEMBERS;
+exports.SUMMARY = SUMMARY;
+exports.VALUE_CHANGED_MEMBERS = VALUE_CHANGED_MEMBERS;
+exports.WRITE_ONLY_MEMBERS = WRITE_ONLY_MEMBERS;
+exports.privateMessage = privateMessage;
+exports.protectedMessage = protectedMessage;
+exports.removedMessage = removedMessage;
+exports.signalQueryMessage = signalQueryMessage;
+exports.valueChangedMessage = valueChangedMessage;
+exports.writeMessage = writeMessage;

package/schematics/migrations/link-signals/index.cjs

@@ -0,0 +1,416 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var ts = require('typescript');
+var utils_messages = require('../../utils/messages.cjs');
+var utils_packageConfig = require('../../utils/package-config.cjs');
+var utils_projectFiles = require('../../utils/project-files.cjs');
+var migrations_linkSignals_data = require('./data.cjs');
+require('@angular-devkit/schematics');
+require('@schematics/angular/utility');
+
+const LABEL = '[link-signals]';
+const TS_EXT = '.ts';
+/** Factories whose single argument gives the type of the declaration they set up. */
+const TYPING_FACTORIES = new Set(['inject', 'viewChild', 'contentChild']);
+/** Applies text-span edits to `content`, right-to-left, so earlier edits don't shift later offsets. */
+function applyEdits(content, edits) {
+    const sorted = [...edits].sort((a, b) => b.start - a.start || b.end - a.end);
+    let result = content;
+    for (const { start, end, text } of sorted) {
+        result = result.slice(0, start) + text + result.slice(end);
+    }
+    return result;
+}
+/** Walks up from `node` to the nearest ancestor matching `predicate`. */
+function findAncestor(node, predicate) {
+    let current = node.parent;
+    while (current) {
+        if (predicate(current))
+            return current;
+        current = current.parent;
+    }
+    return undefined;
+}
+/**
+ * Nodes that open a new binding scope. `ts.isFunctionLike` rather than a hand-rolled list of declarations,
+ * so a parameter of a `FunctionTypeNode` or a `MethodSignature` is bounded by its type instead of falling
+ * back to the whole file. Blocks and loops are included because `let`/`const` are block-scoped.
+ */
+const opensScope = (node) => ts.isFunctionLike(node) ||
+    ts.isBlock(node) ||
+    ts.isCaseBlock(node) ||
+    ts.isModuleBlock(node) ||
+    ts.isForStatement(node) ||
+    ts.isForInStatement(node) ||
+    ts.isForOfStatement(node) ||
+    ts.isCatchClause(node) ||
+    ts.isClassLike(node) ||
+    ts.isSourceFile(node);
+/** Nodes that rebind `this`, so `this.link` inside them is a different object. Arrows don't. */
+const rebindsThis = (node) => ts.isFunctionDeclaration(node) || ts.isFunctionExpression(node) || ts.isClassLike(node);
+/** Whether `node` sits inside `scope` without crossing a `barrier` node on the way up. */
+function reachesScope(node, scope, barrier) {
+    let current = node.parent;
+    while (current && current !== scope) {
+        if (barrier(current))
+            return false;
+        current = current.parent;
+    }
+    return current === scope;
+}
+/** Whether a type annotation names one of `typeNames` directly (not through a union or type argument). */
+function isTypeReference(type, typeNames) {
+    return (!!type &&
+        ts.isTypeReferenceNode(type) &&
+        ts.isIdentifier(type.typeName) &&
+        typeNames.includes(type.typeName.text));
+}
+const FIELD_MODIFIERS = new Set([
+    ts.SyntaxKind.PrivateKeyword,
+    ts.SyntaxKind.PublicKeyword,
+    ts.SyntaxKind.ProtectedKeyword,
+    ts.SyntaxKind.ReadonlyKeyword
+]);
+/** Every value declaration that introduces a plain identifier, with the scope it is visible in. */
+function collectBindings(sourceFile) {
+    const bindings = [];
+    const add = (name, declaration, scope) => bindings.push({ name, declaration, scope: scope ?? sourceFile });
+    const visit = (node) => {
+        if (ts.isParameter(node) && ts.isIdentifier(node.name)) {
+            add(node.name.text, node, findAncestor(node, ts.isFunctionLike));
+        }
+        else if ((ts.isVariableDeclaration(node) || ts.isBindingElement(node)) && ts.isIdentifier(node.name)) {
+            add(node.name.text, node, findAncestor(node, opensScope));
+        }
+        else if ((ts.isFunctionDeclaration(node) || ts.isClassDeclaration(node)) && node.name) {
+            add(node.name.text, node, findAncestor(node, opensScope));
+        }
+        else if ((ts.isImportSpecifier(node) || ts.isImportClause(node)) && node.name) {
+            add(node.name.text, node, sourceFile);
+        }
+        node.forEachChild(visit);
+    };
+    visit(sourceFile);
+    return bindings;
+}
+/** The declaration `name` binds to at `pos`: the innermost enclosing scope that declares it. */
+function resolveBinding(bindings, name, pos) {
+    let best;
+    let bestWidth = Number.POSITIVE_INFINITY;
+    for (const binding of bindings) {
+        if (binding.name !== name)
+            continue;
+        const start = binding.scope.getStart();
+        const end = binding.scope.getEnd();
+        if (pos < start || pos > end)
+            continue;
+        const width = end - start;
+        if (width < bestWidth) {
+            best = binding;
+            bestWidth = width;
+        }
+    }
+    return best?.declaration;
+}
+/** Local names `KbqLink` is bound to in this file, including aliased imports. */
+function localTypeNames(sourceFile) {
+    const names = new Set([migrations_linkSignals_data.LINK_TYPE]);
+    const visit = (node) => {
+        if (ts.isImportSpecifier(node) && (node.propertyName?.text ?? node.name.text) === migrations_linkSignals_data.LINK_TYPE) {
+            names.add(node.name.text);
+        }
+        node.forEachChild(visit);
+    };
+    visit(sourceFile);
+    return [...names];
+}
+/**
+ * The link-ness of an initializer, for the shapes a modern Angular consumer writes: `inject(KbqLink)`,
+ * `viewChild(KbqLink)`, `viewChild.required(…)`, `contentChild(…)`.
+ */
+function initializerTypeOf(initializer, typeNames) {
+    const none = { link: false, signalQuery: false, required: false };
+    if (!initializer || !ts.isCallExpression(initializer))
+        return none;
+    const callee = initializer.expression;
+    const qualified = ts.isPropertyAccessExpression(callee) && ts.isIdentifier(callee.expression);
+    const name = ts.isIdentifier(callee) ? callee.text : qualified ? callee.expression.text : undefined;
+    if (!name || !TYPING_FACTORIES.has(name))
+        return none;
+    const [arg] = initializer.arguments;
+    if (!arg || !ts.isIdentifier(arg) || !typeNames.includes(arg.text))
+        return none;
+    // `viewChild.required(...)` is `Signal<KbqLink>`; the bare form adds `| undefined`.
+    const required = qualified && callee.name.text === 'required';
+    return { link: true, signalQuery: name !== 'inject', required };
+}
+/**
+ * Collects the link receivers: method/function params, class fields (incl. `@ViewChild(KbqLink) x: KbqLink`,
+ * constructor parameter-properties and the `inject()` / `viewChild()` initializer forms) and typed locals.
+ */
+function collectReceivers(sourceFile, typeNames) {
+    const receivers = [];
+    const add = (text, declaration, scope, signalQuery = false, required = false) => receivers.push({ text, declaration, scope: scope ?? sourceFile, signalQuery, required });
+    const visit = (node) => {
+        if (ts.isParameter(node) && ts.isIdentifier(node.name) && isTypeReference(node.type, typeNames)) {
+            add(node.name.text, node, findAncestor(node, ts.isFunctionLike));
+            // A constructor parameter-property is also a class field, reachable as `this.<name>`.
+            if (node.modifiers?.some((modifier) => FIELD_MODIFIERS.has(modifier.kind))) {
+                const owner = findAncestor(node, ts.isClassDeclaration);
+                if (owner)
+                    add(`this.${node.name.text}`, node, owner);
+            }
+        }
+        else if (ts.isPropertyDeclaration(node) && ts.isIdentifier(node.name)) {
+            const owner = findAncestor(node, ts.isClassDeclaration);
+            const { link, signalQuery, required } = initializerTypeOf(node.initializer, typeNames);
+            if (owner && (isTypeReference(node.type, typeNames) || link)) {
+                add(`this.${node.name.text}`, node, owner, signalQuery, required);
+            }
+        }
+        else if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name)) {
+            const { link, signalQuery, required } = initializerTypeOf(node.initializer, typeNames);
+            if (isTypeReference(node.type, typeNames) || link) {
+                add(node.name.text, node, findAncestor(node, opensScope), signalQuery, required);
+            }
+        }
+        node.forEachChild(visit);
+    };
+    visit(sourceFile);
+    return receivers;
+}
+/** Strips the wrappers that do not change which object an access reads from. */
+function unwrapReceiver(node) {
+    let current = node;
+    while (ts.isNonNullExpression(current) ||
+        ts.isParenthesizedExpression(current) ||
+        ts.isAsExpression(current) ||
+        ts.isTypeAssertionExpression(current)) {
+        current = current.expression;
+    }
+    return current;
+}
+/** The receiver a property access resolves to at this exact position, if any. */
+function resolveReceiver(expression, at, sourceFile, receivers, bindings) {
+    const inner = unwrapReceiver(expression);
+    // A receiver is `this.<name>` or a bare identifier, so its own text is a single token: `this . link`
+    // and `this /* x */ . link` already spell `this.link`, because the trivia between the token and the
+    // member lies outside both of their spans.
+    const text = ts.isPropertyAccessExpression(inner)
+        ? `${unwrapReceiver(inner.expression).getText(sourceFile)}.${inner.name.text}`
+        : inner.getText(sourceFile);
+    return receivers.find((receiver) => {
+        if (receiver.text !== text)
+            return false;
+        // For `this.link`, a nested `function` or class changes what `this` is; an arrow does not.
+        // For a bare `link`, a nested redeclaration of the same name shadows the receiver.
+        if (receiver.text.startsWith('this.'))
+            return reachesScope(at, receiver.scope, rebindsThis);
+        return (reachesScope(at, receiver.scope, () => false) &&
+            resolveBinding(bindings, receiver.text, at.getStart(sourceFile)) === receiver.declaration);
+    });
+}
+/** Binary operators that make their left operand a write target rather than a read. */
+const ASSIGNMENT_OPERATORS = new Set([
+    ts.SyntaxKind.EqualsToken,
+    ts.SyntaxKind.PlusEqualsToken,
+    ts.SyntaxKind.MinusEqualsToken,
+    ts.SyntaxKind.AsteriskEqualsToken,
+    ts.SyntaxKind.AsteriskAsteriskEqualsToken,
+    ts.SyntaxKind.SlashEqualsToken,
+    ts.SyntaxKind.PercentEqualsToken,
+    ts.SyntaxKind.LessThanLessThanEqualsToken,
+    ts.SyntaxKind.GreaterThanGreaterThanEqualsToken,
+    ts.SyntaxKind.GreaterThanGreaterThanGreaterThanEqualsToken,
+    ts.SyntaxKind.AmpersandEqualsToken,
+    ts.SyntaxKind.BarEqualsToken,
+    ts.SyntaxKind.CaretEqualsToken,
+    ts.SyntaxKind.BarBarEqualsToken,
+    ts.SyntaxKind.AmpersandAmpersandEqualsToken,
+    ts.SyntaxKind.QuestionQuestionEqualsToken
+]);
+/** Unary operators that write their operand back. Every other prefix operator is a plain read. */
+const INCREMENT_OPERATORS = new Set([ts.SyntaxKind.PlusPlusToken, ts.SyntaxKind.MinusMinusToken]);
+/** Whether `node` sits on the left of a destructuring assignment, where it is written rather than read. */
+function isDestructuringTarget(node) {
+    let current = node;
+    while (ts.isPropertyAssignment(current.parent) ||
+        ts.isShorthandPropertyAssignment(current.parent) ||
+        ts.isSpreadAssignment(current.parent) ||
+        ts.isSpreadElement(current.parent) ||
+        ts.isObjectLiteralExpression(current.parent) ||
+        ts.isArrayLiteralExpression(current.parent)) {
+        current = current.parent;
+    }
+    return (ts.isBinaryExpression(current.parent) &&
+        current.parent.left === current &&
+        ASSIGNMENT_OPERATORS.has(current.parent.operatorToken.kind));
+}
+/**
+ * Classifies a matched property access and appends the resulting edit, if any. Only a plain read is
+ * rewritten: every `KbqLink` signal member is an `input()`, so a write has no mechanical translation, and
+ * appending `()` to it would produce unparseable TypeScript instead of the read-only error to fix by hand.
+ */
+function classifyAccess(node, edits, rewritable) {
+    const parent = node.parent;
+    // Already migrated: `x.disabled()` (call) or the signal API on it.
+    if (ts.isCallExpression(parent) && parent.expression === node)
+        return 'migrated';
+    if (ts.isPropertyAccessExpression(parent) && parent.expression === node && migrations_linkSignals_data.SIGNAL_API_METHODS.has(parent.name.text))
+        return 'migrated';
+    // Write target: `x.disabled = RHS` and every compound form (`+=`, `??=`, `||=`, …).
+    if (ts.isBinaryExpression(parent) && parent.left === node && ASSIGNMENT_OPERATORS.has(parent.operatorToken.kind))
+        return 'write';
+    // `x.disabled++` / `--x.disabled` and `delete x.disabled` are writes too. Only the increment operators
+    // count: a `PrefixUnaryExpression` is also how `!x.disabled` and `-x.tabIndex` are spelled, and those
+    // are reads.
+    if (ts.isPostfixUnaryExpression(parent) && parent.operand === node)
+        return 'write';
+    if (ts.isPrefixUnaryExpression(parent) && parent.operand === node && INCREMENT_OPERATORS.has(parent.operator))
+        return 'write';
+    if (ts.isDeleteExpression(parent))
+        return 'write';
+    if (isDestructuringTarget(node))
+        return 'write';
+    // Read (incl. optional chain `x?.disabled`): append `()`.
+    if (rewritable)
+        edits.push({ start: node.getEnd(), end: node.getEnd(), text: '()' });
+    return 'read';
+}
+/** Collects the edits and the findings for every access on a known link receiver. */
+function collectAccesses(sourceFile, receivers, bindings) {
+    const edits = [];
+    const writes = new Set();
+    const hidden = new Set();
+    const valueChanged = new Set();
+    const signalQueryReads = [];
+    const visit = (node) => {
+        if (ts.isPropertyAccessExpression(node) && ts.isIdentifier(node.name)) {
+            const member = node.name.text;
+            const receiver = migrations_linkSignals_data.KNOWN_MEMBERS.includes(member)
+                ? resolveReceiver(node.expression, node, sourceFile, receivers, bindings)
+                : undefined;
+            if (receiver) {
+                // A hidden member has no reachable spelling left, so classification would have nothing to
+                // offer: report it whether it is read or written.
+                if (migrations_linkSignals_data.HIDDEN_MEMBERS.includes(member)) {
+                    hidden.add(member);
+                }
+                else if (receiver.signalQuery) {
+                    // A signal query holds the directive behind a call of its own, so the read is
+                    // `query().disabled()`. Appending one `()` would be wrong in both halves.
+                    signalQueryReads.push({ member, required: receiver.required });
+                }
+                else if (classifyAccess(node, edits, migrations_linkSignals_data.SIGNAL_MEMBERS.includes(member)) === 'write') {
+                    writes.add(member);
+                }
+                else if (migrations_linkSignals_data.VALUE_CHANGED_MEMBERS.includes(member)) {
+                    valueChanged.add(member);
+                }
+            }
+        }
+        node.forEachChild(visit);
+    };
+    visit(sourceFile);
+    return { edits, writes, hidden, valueChanged, signalQueryReads };
+}
+/** Rewrites the value-safe programmatic reads in one TypeScript file and reports the rest. */
+function migrateTsExpressions(content, fileName) {
+    const sourceFile = ts.createSourceFile(fileName, content, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    const typeNames = localTypeNames(sourceFile);
+    const receivers = collectReceivers(sourceFile, typeNames);
+    const empty = {
+        edits: [],
+        writes: new Set(),
+        hidden: new Set(),
+        valueChanged: new Set(),
+        signalQueryReads: []
+    };
+    if (receivers.length === 0)
+        return { ...empty, content };
+    const bindings = collectBindings(sourceFile);
+    const findings = collectAccesses(sourceFile, receivers, bindings);
+    return { ...findings, content: findings.edits.length > 0 ? applyEdits(content, findings.edits) : content };
+}
+/** Emits the per-file report for everything the rewrite could not do on its own. */
+function report(context, filePath, findings) {
+    const lines = [];
+    const subset = (members) => members.filter((member) => findings.hidden.has(member));
+    const protectedMembers = subset(migrations_linkSignals_data.PROTECTED_MEMBERS);
+    const privateMembers = subset(migrations_linkSignals_data.PRIVATE_MEMBERS);
+    const removedMembers = subset(migrations_linkSignals_data.REMOVED_MEMBERS);
+    if (protectedMembers.length > 0)
+        lines.push(`  ${migrations_linkSignals_data.protectedMessage(protectedMembers)}`);
+    if (privateMembers.length > 0)
+        lines.push(`  ${migrations_linkSignals_data.privateMessage(privateMembers)}`);
+    if (removedMembers.length > 0)
+        lines.push(`  ${migrations_linkSignals_data.removedMessage(removedMembers)}`);
+    if (findings.valueChanged.size > 0)
+        lines.push(`  ${migrations_linkSignals_data.valueChangedMessage(findings.valueChanged)}`);
+    if (findings.writes.size > 0)
+        lines.push(`  ${migrations_linkSignals_data.writeMessage(findings.writes)}`);
+    // The rewrite this file just got is correct but not value-identical, so the caveat belongs next to the
+    // file it was applied to rather than in a summary printed once, after every edit has landed.
+    if (findings.edits.length > 0)
+        lines.push(migrations_linkSignals_data.DISABLED_CAVEAT);
+    for (const { member, required } of findings.signalQueryReads) {
+        lines.push(`  ${migrations_linkSignals_data.signalQueryMessage(member, required)}`);
+    }
+    if (lines.length === 0)
+        return;
+    utils_messages.logMessage(context.logger, [`${LABEL} ${filePath}`, ...lines]);
+}
+/**
+ * A `.ts` file is a link consumer if it names any of the exported symbols or imports the package. There is
+ * no element to look for: `kbq-link` is an attribute on an anchor.
+ */
+function referencesLink(content) {
+    return /\bKbqLink\w*\b/.test(content) || content.includes(migrations_linkSignals_data.LINK_PACKAGE);
+}
+function linkSignals(options) {
+    return async (tree, context) => {
+        const { project } = options;
+        // `ng update` runs a migration with no options at all, and `migrations.json` declares no schema, so
+        // the schema default never reaches the rule: without this the migration would only ever report.
+        const fix = options.fix ?? true;
+        const projectDefinition = await utils_packageConfig.setupOptions(project, tree);
+        const root = projectDefinition?.root ?? '';
+        const rootDir = root ? tree.getDir(root) : tree.root;
+        const tsPaths = [];
+        utils_projectFiles.visitProjectFiles(rootDir, (filePath) => {
+            if (filePath.endsWith(TS_EXT))
+                tsPaths.push(filePath);
+        });
+        let touched = 0;
+        let consumers = 0;
+        for (const filePath of tsPaths) {
+            const original = tree.read(filePath)?.toString();
+            if (!original || !referencesLink(original))
+                continue;
+            consumers++;
+            const findings = migrateTsExpressions(original, filePath);
+            report(context, filePath, findings);
+            if (findings.content === original)
+                continue;
+            touched++;
+            if (fix) {
+                tree.overwrite(filePath, findings.content);
+            }
+            else {
+                utils_messages.logMessage(context.logger, [`${LABEL} would update ${filePath}`]);
+            }
+        }
+        // Nothing here uses the link, so the summary would only be noise.
+        if (consumers === 0)
+            return;
+        utils_messages.logMessage(context.logger, [
+            `${LABEL} processed tree under "${root || '<workspace root>'}", ` +
+                `${fix ? 'updated' : 'would update'} ${touched} file(s).`,
+            ...migrations_linkSignals_data.SUMMARY
+        ]);
+    };
+}
+
+exports.default = linkSignals;

package/schematics/migrations/link-signals/schema.json

@@ -0,0 +1,20 @@
+{
+    "$schema": "http://json-schema.org/schema",
+    "$id": "koobiq-components-link-signals",
+    "title": "Koobiq components link signals migration",
+    "type": "object",
+    "properties": {
+        "project": {
+            "type": "string",
+            "description": "Name of the project to migrate. If omitted, the migration runs over the whole tree.",
+            "$default": {
+                "$source": "projectName"
+            }
+        },
+        "fix": {
+            "type": "boolean",
+            "default": true,
+            "description": "When true, applies all auto-fix replacements. When false, prints what would change without writing."
+        }
+    }
+}

package/schematics/migrations/list-signals/README.md

@@ -0,0 +1,22 @@
+# list-signals
+
+Migration schematic invoked automatically by `ng update @koobiq/components@21` (registered for `21.0.0-0`).
+Reports programmatic writes to the signal inputs of `KbqListSelection` and `KbqListOption`. It never writes to the
+tree.
+
+## Background
+
+The inputs of the list are signal inputs read through a getter. A read is unchanged; a write no longer compiles.
+
+| Member                                                                                         | Write                            |
+| ---------------------------------------------------------------------------------------------- | -------------------------------- |
+| `KbqListSelection`: `autoSelect`, `noUnselectLast`, `multiple`, `tabIndex`, `selectAllHandler` | Bind it                          |
+| `KbqListSelection.disabled`                                                                    | Bind it, or use the form control |
+| `KbqListOption`: `value`, `disabled`, `draggable`, `showCheckbox`                              | Bind it                          |
+| `KbqListOption.selected`, `KbqListSelection.multipleMode`                                      | Still writable                   |
+
+## Running it manually
+
+```bash
+ng g @koobiq/components:list-signals --project "<your project>"
+```

package/schematics/migrations/list-signals/data.cjs

@@ -0,0 +1,35 @@
+'use strict';
+
+/**
+ * Data for the `list-signals` migration.
+ *
+ * The inputs of `KbqListSelection` and `KbqListOption` are signal inputs read through a getter now. Reads are
+ * unchanged; a programmatic write no longer compiles, except `KbqListOption.selected`, which stays writable.
+ * Warn-only: the write belongs in a binding or a form control.
+ */
+const LIST_ANCHOR = '\\bKbqList(?:Selection|Option)\\b';
+const warnPatterns = [
+    {
+        anchor: LIST_ANCHOR,
+        pattern: '\\.\\s*(?:autoSelect|noUnselectLast|multiple|tabIndex|selectAllHandler)\\s*=[^=]',
+        message: 'KbqListSelection.autoSelect, .noUnselectLast, .multiple, .tabIndex and .selectAllHandler are signal ' +
+            'inputs read through a getter now, so a programmatic write no longer compiles. Bind them in the ' +
+            'template; multipleMode stays writable. This pattern also matches a write to an unrelated object in ' +
+            'the same file — check before changing it.'
+    },
+    {
+        anchor: LIST_ANCHOR,
+        pattern: '\\.\\s*(?:value|disabled|draggable|showCheckbox)\\s*=[^=]',
+        message: 'The value, disabled, draggable and showCheckbox of KbqListOption, and the disabled and draggable of ' +
+            'KbqListSelection, are signal inputs read through a getter now, so a programmatic write no longer ' +
+            'compiles. Bind them in the template, or disable the list through its form control. ' +
+            'KbqListOption.selected stays writable. This pattern also matches a write to an unrelated object in ' +
+            'the same file — check before changing it.'
+    }
+];
+const SUMMARY = [
+    'KbqListSelection and KbqListOption are read as before; only programmatic writes to their inputs are gone.'
+];
+
+exports.SUMMARY = SUMMARY;
+exports.warnPatterns = warnPatterns;

package/schematics/migrations/list-signals/index.cjs

@@ -0,0 +1,18 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var utils_warnOnlyMigration = require('../../utils/warn-only-migration.cjs');
+var migrations_listSignals_data = require('./data.cjs');
+require('../../utils/messages.cjs');
+require('../../utils/package-config.cjs');
+require('@angular-devkit/schematics');
+require('@schematics/angular/utility');
+require('../../utils/project-files.cjs');
+
+/** Reports programmatic writes to the signal inputs of `KbqListSelection` and `KbqListOption`. Never writes. */
+function listSignals(options) {
+    return utils_warnOnlyMigration.warnOnlyRule({ label: '[list-signals]', warnPatterns: migrations_listSignals_data.warnPatterns, summary: migrations_listSignals_data.SUMMARY }, options);
+}
+
+exports.default = listSignals;

package/schematics/migrations/list-signals/schema.json

@@ -0,0 +1,15 @@
+{
+    "$schema": "http://json-schema.org/schema",
+    "$id": "koobiq-components-list-signals",
+    "title": "Koobiq components list signals migration",
+    "type": "object",
+    "properties": {
+        "project": {
+            "type": "string",
+            "description": "Name of the project to inspect. If omitted, the migration runs over the whole tree.",
+            "$default": {
+                "$source": "projectName"
+            }
+        }
+    }
+}