@koobiq/components 20.4.2 → 21.0.1

package/schematics/migrations/code-block-highlight-js-core/index.cjs

@@ -0,0 +1,319 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var schematics = require('@angular-devkit/schematics');
+var utility = require('@schematics/angular/utility');
+var ts$1 = 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 utils_safeRule = require('../../utils/safe-rule.cjs');
+var migrations_codeBlockHighlightJsCore_data = require('./data.cjs');
+var ts = require('@schematics/angular/third_party/github.com/Microsoft/TypeScript/lib/typescript');
+var astUtils = require('@schematics/angular/utility/ast-utils');
+var ngAstUtils = require('@schematics/angular/utility/ng-ast-utils');
+var app_config = require('@schematics/angular/utility/standalone/app_config');
+var util = require('@schematics/angular/utility/standalone/util');
+require('rxjs');
+
+// `@schematics/angular`'s own bundled copy of the TypeScript compiler, not the `typescript` package: the nodes its
+// utilities return were created by it, and `SyntaxKind` values differ between versions.
+const nameOf$1 = (node) => {
+    if (ts.isIdentifier(node))
+        return node.text;
+    if (ts.isPropertyAccessExpression(node))
+        return node.name.text;
+    return undefined;
+};
+const isNamed = (property, name) => !!property.name &&
+    (ts.isIdentifier(property.name) || ts.isStringLiteral(property.name)) &&
+    property.name.text === name;
+/**
+ * The elements of the `providers` of a configuration or `@NgModule`, none when it declares no providers, or `null` when
+ * `addRootProvider` cannot add one to them safely: it would declare `providers` a second time next to a value that is
+ * not an array literal, leave an `@NgModule` alone, or override the providers of a spread.
+ */
+function providersOf(literal) {
+    if (literal.properties.some(ts.isSpreadAssignment))
+        return null;
+    const providers = literal.properties.find((property) => isNamed(property, 'providers'));
+    if (!providers)
+        return [];
+    return ts.isPropertyAssignment(providers) && ts.isArrayLiteralExpression(providers.initializer)
+        ? providers.initializer.elements
+        : null;
+}
+/**
+ * The root providers of an application, where `addRootProvider` adds one: `null` when it cannot add one there safely,
+ * since it throws on a bootstrap it cannot analyze only after adding the import, and breaks the configuration or does
+ * nothing on providers it cannot extend.
+ */
+async function findRootProviders(tree, project) {
+    try {
+        const mainFilePath = await util.getMainFilePath(tree, project);
+        if (ngAstUtils.isStandaloneApp(tree, mainFilePath)) {
+            const bootstrapCall = util.findBootstrapApplicationCall(tree, mainFilePath);
+            const appConfig = app_config.findAppConfig(bootstrapCall, tree, mainFilePath);
+            // Without a configuration it can read, `addRootProvider` adds one to `bootstrapApplication(App)` only.
+            if (!appConfig)
+                return bootstrapCall.arguments.length === 1 ? [] : null;
+            return providersOf(appConfig.node);
+        }
+        const modulePath = ngAstUtils.getAppModulePath(tree, mainFilePath);
+        const [metadata] = astUtils.getDecoratorMetadata(util.getSourceFile(tree, modulePath), 'NgModule', '@angular/core');
+        return metadata && ts.isObjectLiteralExpression(metadata) ? providersOf(metadata) : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Whether a root provider is a highlight.js configuration of the code block. */
+function isHighlightJsConfig(provider) {
+    if (ts.isCallExpression(provider))
+        return nameOf$1(provider.expression) === migrations_codeBlockHighlightJsCore_data.CONFIG_PROVIDER;
+    return (ts.isObjectLiteralExpression(provider) &&
+        provider.properties.some((property) => isNamed(property, 'provide') &&
+            ts.isPropertyAssignment(property) &&
+            nameOf$1(property.initializer) === migrations_codeBlockHighlightJsCore_data.CONFIG_TOKEN));
+}
+
+const LABEL = '[code-block-highlight-js-core]';
+const TS_EXT = '.ts';
+/** Files that render code blocks outside the application, with providers of their own. */
+const TEST_FILE = /\.(spec|test|stories|cy)\.ts$/;
+/** The name of a callee or of a referenced token: `x` for `x` and `ns.x`. */
+const nameOf = (node) => {
+    if (ts$1.isIdentifier(node))
+        return node.text;
+    if (ts$1.isPropertyAccessExpression(node))
+        return node.name.text;
+    return undefined;
+};
+/** The name of a property, `undefined` for a computed one other than a string literal. */
+const propertyName = (property) => {
+    const name = property.name;
+    if (!name)
+        return undefined;
+    if (ts$1.isIdentifier(name) || ts$1.isStringLiteral(name))
+        return name.text;
+    if (ts$1.isComputedPropertyName(name) && ts$1.isStringLiteralLike(name.expression))
+        return name.expression.text;
+    return undefined;
+};
+const findProperty = (literal, name) => literal.properties.find((property) => propertyName(property) === name);
+/** The names a file gives to an export of the code block: its own, and those of `import { name as alias }`. */
+function localNames(sourceFile, exported) {
+    const names = new Set([exported]);
+    for (const statement of sourceFile.statements) {
+        if (!ts$1.isImportDeclaration(statement) || !ts$1.isStringLiteral(statement.moduleSpecifier))
+            continue;
+        if (statement.moduleSpecifier.text !== migrations_codeBlockHighlightJsCore_data.CODE_BLOCK_PACKAGE)
+            continue;
+        const bindings = statement.importClause?.namedBindings;
+        if (!bindings || !ts$1.isNamedImports(bindings))
+            continue;
+        for (const element of bindings.elements) {
+            if ((element.propertyName ?? element.name).text === exported)
+                names.add(element.name.text);
+        }
+    }
+    return names;
+}
+/**
+ * Adds `core: () => import('highlight.js')` to every highlight.js configuration written as an object literal without
+ * `core` - the argument of `kbqCodeBlockHighlightJsConfigProvider` and the `useValue` of a provider of
+ * `KBQ_CODE_BLOCK_HIGHLIGHT_JS_CONFIG` - since the code block loaded the full bundle for it. A configuration it
+ * cannot read, such as a variable, a spread or a factory, is reported rather than guessed at.
+ */
+function migrateSource(content, fileName) {
+    const sourceFile = ts$1.createSourceFile(fileName, content, ts$1.ScriptTarget.Latest, true, ts$1.ScriptKind.TS);
+    const newline = content.includes('\r\n') ? '\r\n' : '\n';
+    const providerNames = localNames(sourceFile, migrations_codeBlockHighlightJsCore_data.CONFIG_PROVIDER);
+    const tokenNames = localNames(sourceFile, migrations_codeBlockHighlightJsCore_data.CONFIG_TOKEN);
+    const edits = [];
+    const unreadLines = [];
+    let configs = 0;
+    const report = (node) => {
+        unreadLines.push(sourceFile.getLineAndCharacterOfPosition(node.getStart()).line + 1);
+    };
+    const isToken = (node) => !!node && tokenNames.has(nameOf(node) ?? '');
+    const addCore = (config, site) => {
+        configs++;
+        if (!config || !ts$1.isObjectLiteralExpression(config))
+            return report(config ?? site);
+        if (findProperty(config, 'core'))
+            return;
+        // A spread or a computed name may hold `core`.
+        if (config.properties.some((property) => ts$1.isSpreadAssignment(property) || !propertyName(property))) {
+            return report(config);
+        }
+        const [first] = config.properties;
+        const open = config.getStart() + 1;
+        if (!first) {
+            const inner = content.slice(open, config.getEnd() - 1);
+            if (!inner.trim()) {
+                edits.push({ start: config.getStart(), end: config.getEnd(), text: `{ ${migrations_codeBlockHighlightJsCore_data.FULL_BUNDLE_CORE} }` });
+            }
+            else {
+                // A comment is all the literal holds: `core` goes above it.
+                const indent = /\n([ \t]*)\S/.exec(inner)?.[1];
+                edits.push({
+                    start: open,
+                    end: open,
+                    text: indent === undefined ? ` ${migrations_codeBlockHighlightJsCore_data.FULL_BUNDLE_CORE}` : `${newline}${indent}${migrations_codeBlockHighlightJsCore_data.FULL_BUNDLE_CORE}`
+                });
+            }
+            return;
+        }
+        // Above the comments of the first property, which describe it.
+        const [comment] = ts$1.getLeadingCommentRanges(content, first.getFullStart()) ?? [];
+        const start = comment?.pos ?? first.getStart();
+        const indent = content.slice(content.lastIndexOf('\n', start - 1) + 1, start);
+        const separator = /^[ \t]*$/.test(indent) ? `,${newline}${indent}` : ', ';
+        edits.push({ start, end: start, text: migrations_codeBlockHighlightJsCore_data.FULL_BUNDLE_CORE + separator });
+    };
+    // The `useValue` of a provider object; `TestBed.overrideProvider` takes one without `provide`.
+    const addCoreToProvider = (provider, site) => {
+        const useValue = provider && ts$1.isObjectLiteralExpression(provider) && findProperty(provider, 'useValue');
+        addCore(useValue && ts$1.isPropertyAssignment(useValue) ? useValue.initializer : undefined, site);
+    };
+    const visit = (node) => {
+        if (ts$1.isCallExpression(node)) {
+            const callee = nameOf(node.expression);
+            if (callee && providerNames.has(callee)) {
+                addCore(node.arguments[0], node);
+            }
+            else if (callee === 'overrideProvider' && isToken(node.arguments[0])) {
+                addCoreToProvider(node.arguments[1], node);
+            }
+        }
+        else if (ts$1.isObjectLiteralExpression(node)) {
+            const provide = findProperty(node, 'provide');
+            if (provide && ts$1.isPropertyAssignment(provide) && isToken(provide.initializer)) {
+                addCoreToProvider(node, node);
+            }
+        }
+        ts$1.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+    let result = content;
+    for (const { start, end, text } of edits.sort((a, b) => b.start - a.start)) {
+        result = result.slice(0, start) + text + result.slice(end);
+    }
+    return { content: result, changed: result !== content, unreadLines, configs };
+}
+/** The directory of a project's sources, as the paths `visitProjectFiles` passes start: `/src`, or `/` for the root. */
+const sourceDir = (project) => `/${(project.sourceRoot ?? project.root).replace(/^\/+|\/+$/g, '')}`;
+const isInside = (path, dir) => dir === '/' || path.startsWith(`${dir}/`);
+const fullBundleProviderRule = (project) => utility.addRootProvider(project, ({ code, external }) => {
+    const provider = external(migrations_codeBlockHighlightJsCore_data.CONFIG_PROVIDER, migrations_codeBlockHighlightJsCore_data.CODE_BLOCK_PACKAGE);
+    return code `${provider}({ ${migrations_codeBlockHighlightJsCore_data.FULL_BUNDLE_CORE} })`;
+});
+/**
+ * Keeps the full highlight.js bundle where the code block loaded it by default: in the root providers of an
+ * application that renders code blocks with no configuration there, and in every configuration without `core`.
+ */
+function codeBlockHighlightJsCore(options) {
+    return async (tree, context) => {
+        // `ng update` invokes migrations with no options at all, and migrations.json declares no schema, so the
+        // schema default never reaches us - applying the fix is the intended behaviour there.
+        const fix = options.fix ?? true;
+        const projectDefinition = await utils_packageConfig.setupOptions(options.project, tree);
+        // The source root rather than the root: the root of the first application can be the workspace root.
+        const rootDir = projectDefinition ? tree.getDir(sourceDir(projectDefinition)) : tree.root;
+        const providerRules = [];
+        let projects = [];
+        let consumers = 0;
+        let touched = 0;
+        try {
+            const workspace = await utility.readWorkspace(tree);
+            projects = [...workspace.projects].map(([name, definition]) => ({
+                name,
+                definition,
+                dir: sourceDir(definition)
+            }));
+        }
+        catch {
+            // The configurations are migrated all the same.
+            utils_messages.logMessage(context.logger, [LABEL, ...migrations_codeBlockHighlightJsCore_data.noWorkspaceMessage()]);
+        }
+        const usingCodeBlock = new Set();
+        const configured = new Set();
+        utils_projectFiles.visitProjectFiles(rootDir, (filePath, entry) => {
+            if (!filePath.endsWith(TS_EXT))
+                return;
+            // The innermost project: one whose sources sit at the workspace root holds the others too.
+            const containing = projects.filter(({ dir }) => isInside(filePath, dir));
+            const depth = Math.max(...containing.map(({ dir }) => dir.length));
+            const owners = containing.filter(({ dir }) => dir.length === depth).map(({ name }) => name);
+            if (options.project && !owners.includes(options.project))
+                return;
+            const original = entry.content.toString();
+            const isTest = TEST_FILE.test(filePath);
+            if (!isTest && original.includes(migrations_codeBlockHighlightJsCore_data.CODE_BLOCK_PACKAGE))
+                owners.forEach((name) => usingCodeBlock.add(name));
+            if (!original.includes(migrations_codeBlockHighlightJsCore_data.CONFIG_PROVIDER) && !original.includes(migrations_codeBlockHighlightJsCore_data.CONFIG_TOKEN))
+                return;
+            const { content, changed, unreadLines, configs } = migrateSource(original, filePath);
+            if (!isTest && configs)
+                owners.forEach((name) => configured.add(name));
+            for (const line of unreadLines) {
+                utils_messages.logMessage(context.logger, [`${LABEL} ${filePath}`, `  ${migrations_codeBlockHighlightJsCore_data.unreadConfigMessage(line)}`]);
+            }
+            if (!changed)
+                return;
+            touched++;
+            if (fix) {
+                tree.overwrite(filePath, content);
+            }
+            else {
+                utils_messages.logMessage(context.logger, [`${LABEL} would update ${filePath} (run with --fix to apply)`]);
+            }
+        });
+        for (const { name, definition } of projects) {
+            if (!usingCodeBlock.has(name) || (options.project && name !== options.project))
+                continue;
+            consumers++;
+            if (definition.extensions['projectType'] !== 'application') {
+                if (!configured.has(name))
+                    utils_messages.logMessage(context.logger, [LABEL, ...migrations_codeBlockHighlightJsCore_data.libraryMessage(name)]);
+                continue;
+            }
+            const rootProviders = await findRootProviders(tree, name);
+            if (!rootProviders) {
+                utils_messages.logMessage(context.logger, [LABEL, ...migrations_codeBlockHighlightJsCore_data.rootProviderFallback(name)]);
+                continue;
+            }
+            // A configuration in the root providers reaches every code block, and has its `core` by now.
+            if (rootProviders.some(isHighlightJsConfig))
+                continue;
+            const messages = [
+                ...migrations_codeBlockHighlightJsCore_data.addedRootProviderMessage(name, fix),
+                ...(configured.has(name) ? migrations_codeBlockHighlightJsCore_data.otherConfigsMessage(name) : [])
+            ];
+            if (!fix) {
+                utils_messages.logMessage(context.logger, [LABEL, ...messages]);
+                continue;
+            }
+            providerRules.push(utils_safeRule.safeRule(schematics.chain([
+                fullBundleProviderRule(name),
+                (_, ruleContext) => utils_messages.logMessage(ruleContext.logger, [LABEL, ...messages])
+            ]), migrations_codeBlockHighlightJsCore_data.rootProviderFallback(name)));
+        }
+        // Nothing here renders code blocks, so the summary would only be noise.
+        if (!consumers && !touched)
+            return;
+        // After the root providers, which say what they added only once it is there.
+        return schematics.chain([
+            ...providerRules,
+            (_, ruleContext) => utils_messages.logMessage(ruleContext.logger, [
+                `${LABEL} ${fix ? 'updated' : 'would update'} ${touched} highlight.js configuration file(s).`,
+                ...migrations_codeBlockHighlightJsCore_data.SUMMARY
+            ])
+        ]);
+    };
+}
+
+exports.default = codeBlockHighlightJsCore;
+exports.migrateSource = migrateSource;

package/schematics/migrations/code-block-highlight-js-core/schema.json

@@ -0,0 +1,20 @@
+{
+    "$schema": "http://json-schema.org/schema",
+    "$id": "koobiq-components-code-block-highlight-js-core",
+    "title": "Koobiq components code block highlight.js core 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 the rewrites. When false, prints what would change without writing."
+        }
+    }
+}

package/schematics/migrations/code-block-signals/README.md

@@ -0,0 +1,84 @@
+# code-block-signals
+
+Migration schematic invoked automatically by `ng update @koobiq/components@21` (registered for
+`21.0.0-0`). Moves `KbqCodeBlock` consumers onto its finished signal-based API and reports what has no
+mechanical translation.
+
+## Background
+
+`maxHeight` was published as `InputSignal<number>` over an `undefined!` default, so a code block with
+no `[maxHeight]` binding reported `undefined` from a non-nullable type:
+
+```ts
+const height: number = codeBlock.maxHeight(); // held undefined
+if (codeBlock.maxHeight() > 0) { … }          // NaN comparison, never true
+```
+
+It reports `number | undefined` now, and a value that is not cleanly numeric — a valueless
+`maxHeight` attribute, `'200px'` — reports `undefined` rather than `NaN`. `[maxHeight]="undefined"`
+used to hand back `NaN`; that is the one runtime change. The call sites that were quietly wrong now
+fail to compile.
+
+`KbqCodeBlockHighlight.file` was a write-only required input: a setter with no getter that kicked off
+highlighting as a side effect. It is `input.required()` driven by an effect now, so it can finally be
+read — and a programmatic write no longer compiles.
+
+## What it rewrites
+
+`KbqCodeBlock` has no decorator inputs left. `softWrap`, `viewAll`, `canDownload`, `files`,
+`activeFileIndex` and `hideTabs` are `WritableSignal`s over a backing `input()`, so both directions
+are mechanical:
+
+| Before                      | After                          |
+| --------------------------- | ------------------------------ |
+| `block.softWrap`            | `block.softWrap()`             |
+| `block.activeFileIndex = 2` | `block.activeFileIndex.set(2)` |
+
+On receivers explicitly typed `KbqCodeBlock`, on the `inject()` / `viewChild()` initializer forms, and
+through template reference variables on `<kbq-code-block>` in external and inline templates. Reads that
+are already calls are left alone, so the schematic is idempotent.
+
+A `model()` would have been the obvious shape for the six, but `ModelOptions` carries no `transform`,
+and every one of them needs `booleanAttribute` or `numberAttribute` to keep a valueless attribute such
+as `<kbq-code-block softWrap>` working.
+
+## What it does _not_ do
+
+Narrowing `number | undefined` back to `number` is a decision — `?? 0`, a non-null assertion, or
+handling the unset state — and turning a `file` write into a `[file]` binding is a template edit. A
+compound assignment (`||=`, `+=`) or an increment would need the receiver spelled twice, so it is
+reported rather than rewritten, and the backing inputs — `softWrapInput` and friends — cannot be
+written at all any more. The removed `canLoad` and `codeFiles` aliases are migrated by `v21-upgrade`.
+
+| Pattern                                  | Manual migration                                                    |
+| ---------------------------------------- | ------------------------------------------------------------------- |
+| `.maxHeight()` on a `KbqCodeBlock`       | `?? 0` for the common reading, or handle the unset state explicitly |
+| `.file = …` on a `KbqCodeBlockHighlight` | Bind `[file]`; the value is readable as `file()` now                |
+
+## Notes with no call site to point at
+
+- The `max-height` the code block applies while `viewAll` is off is a `computed`. It was a getter read
+  from a `[style.max-height.px]` binding, so it only re-evaluated when something else marked the view
+  dirty; it follows `maxHeight` and `viewAll` directly now.
+- `softWrap`, `viewAll`, `canDownload`, `activeFileIndex` and `files` are backed by signals. They are
+  accessor inputs with the same types and the same two-way outputs — they are written by the component
+  as well as by the binding, and a `model()` cannot carry the `booleanAttribute` /
+  `numberAttribute` transform they need. Four of the five were plain public fields before, so they are
+  no longer own properties: they do not appear in `Object.keys`, a spread or `JSON.stringify`, and a
+  subclass field of the same name shadows the accessor under `useDefineForClassFields`.
+- **`hideTabs` is derived rather than written.** A single file with no filename still hides the tab
+  bar, but the component no longer writes `true` into its own input to do it: the write latched the
+  bar off for good and re-emitted `hideTabsChange` on every `files` assignment. `[hideTabs]="false"`
+  no longer shows the bar for a lone unnamed file.
+- **An `activeFileIndex` outside `files` renders the first file, and an empty `files` renders no code
+  at all.** Both used to reach `files[activeFileIndex]` and throw on the undefined result. The index
+  itself is left as bound: resetting it wrote back into a `[(activeFileIndex)]` while the parent was
+  still updating.
+- A failed `highlight.js` load no longer latches `pending` on, and the line-numbers plugin installs
+  its `<style>` and its `copy` listener once instead of once per code block.
+
+## Running it manually
+
+```
+ng generate @koobiq/components:code-block-signals --project my-app
+```

package/schematics/migrations/code-block-signals/data.cjs

@@ -0,0 +1,121 @@
+'use strict';
+
+/**
+ * Data for the `code-block-signals` migration.
+ *
+ * `KbqCodeBlock` finished its move to signals: nothing on it is a decorator input any more.
+ *
+ * - `softWrap`, `viewAll`, `canDownload`, `files`, `activeFileIndex`, `hideTabs` → `WritableSignal`s over
+ *   a backing `input()`, so a read becomes a call and a plain write becomes `.set(…)` (auto-fixed)
+ * - `maxHeight` was already a signal input; only its type changed (warn)
+ *
+ * A `model()` would have been the obvious shape for the six, but `ModelOptions` carries no `transform`,
+ * and every one of them needs `booleanAttribute` or `numberAttribute` to keep a valueless attribute
+ * (`<kbq-code-block softWrap>`) working. Hence the backing input plus a `linkedSignal` over it.
+ */
+/** Members whose value is unchanged; a read must become a call, a write must become `.set(…)`. */
+const SIGNAL_MEMBERS = [
+    'softWrap',
+    'viewAll',
+    'canDownload',
+    'files',
+    'activeFileIndex',
+    'hideTabs'
+];
+/**
+ * Members the migration reports rather than rewrites: `maxHeight` was already a signal input and only
+ * changed its type, and `KbqCodeBlockHighlight.file` turned from a write-only setter into a required
+ * input. Both are reported per file, because a summary line names no call site.
+ */
+const REPORTED_MEMBERS = ['maxHeight', 'file'];
+/** 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']);
+/** `exportAs` name a template reference has to carry to be the code block rather than some other directive. */
+const CODE_BLOCK_EXPORT_AS = 'kbqCodeBlock';
+/** TypeScript type annotation that marks a receiver as a code block. */
+const CODE_BLOCK_TYPE = 'KbqCodeBlock';
+/** Type annotation that marks a receiver as the highlight directive, whose `file` input also changed. */
+const HIGHLIGHT_TYPE = 'KbqCodeBlockHighlight';
+/** Element selector whose template reference variables (`#ref`) point at a code block. */
+const CODE_BLOCK_ELEMENT = 'kbq-code-block';
+/** Import specifier that marks a file as a code block consumer. */
+const CODE_BLOCK_PACKAGE = '@koobiq/components/code-block';
+/**
+ * The backing inputs behind the six signals. Public, because a `protected` input cannot be bound from a
+ * consumer's template, but they are `@docs-private` plumbing: read the signal that carries the attribute's
+ * own name instead. The removed `canLoadInput` and `codeFilesInput` are reported by `v21-upgrade`.
+ */
+const PLUMBING_MEMBERS = [
+    'softWrapInput',
+    'viewAllInput',
+    'canDownloadInput',
+    'filesInput',
+    'activeFileIndexInput',
+    'hideTabsInput'
+];
+/** Reported for a write the rewrite cannot translate on its own. */
+const writeMessage = (members) => `These writes were left untouched: ${[...members].join(', ')}. A plain \`x.softWrap = value\` is ` +
+    'rewritten to `x.softWrap.set(value)`, but a compound assignment (`||=`, `+=`) or an increment would ' +
+    'need the receiver spelled twice.';
+const reportedMessage = (members) => `These KbqCodeBlock members changed shape without changing name: ${[...members].join(', ')}. ` +
+    '`maxHeight` reports `number | undefined` instead of `number` and never NaN, so decide per call site ' +
+    'between `?? 0` and handling the unset state. `KbqCodeBlockHighlight.file` was a write-only setter ' +
+    'and is a required input now: bind `[file]`, and read it as `file()`.';
+const plumbingMessage = (members) => `These KbqCodeBlock members are backing inputs: ${[...members].join(', ')}. They exist to carry the ` +
+    'attribute and its transform, they are read-only, and they report what was bound rather than what the ' +
+    'component currently holds. Bind the attribute they alias - `softWrap`, `viewAll`, `canDownload`, ' +
+    "`files`, `activeFileIndex`, `hideTabs` - and read the signal that carries the attribute's own name.";
+/**
+ * Reported for a read through a signal query, which is a signal holding the component: 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.
+ */
+const signalQueryMessage = (member, required) => `A signal query holds the component behind a call of its own, so reading \`${member}\` through it ` +
+    `needs two calls: \`this.codeBlock()${required ? '' : '?'}.${member}()\`.` +
+    (required ? '' : ' The query is optional, so keep the `?.`.') +
+    ' Those reads are left untouched - migrate them by hand.';
+/** Reported when a template renders the code block but cannot be parsed, so nothing in it was inspected. */
+const UNPARSEABLE_TEMPLATE_MESSAGE = 'This template renders <kbq-code-block> but could not be parsed, so it was left untouched. Migrate ' +
+    'reads through its template reference variables by hand. If every template is reported this way, ' +
+    '`@angular/compiler` could not be loaded from this install.';
+/**
+ * Reported when a file names `KbqCodeBlock` in a type position the receiver pass cannot scope to a single
+ * identifier - a union, an array, a `QueryList<…>`, a cast, a return type - or reads a member in a shape
+ * the access pass cannot reach.
+ */
+const UNRESOLVED_RECEIVER_MESSAGE = 'KbqCodeBlock is used here in a way this migration cannot resolve to a single receiver, so any signal ' +
+    'read through it was left untouched. Check these lines by hand:';
+/** Printed once per project, after the per-file reports. */
+const SUMMARY = [
+    '  `maxHeight` reports `number | undefined` instead of `number`, and a value that is not cleanly ' +
+        "numeric - a valueless `maxHeight` attribute, `'200px'` - reports `undefined` rather than NaN. " +
+        'It was declared non-nullable over an `undefined!` default, so a block with no binding always ' +
+        'handed back `undefined` behind a `number` type.',
+    '  `KbqCodeBlockHighlight.file` was a write-only required input that started highlighting as a side ' +
+        'effect. It is a required signal input driven by an effect now, so it can finally be read - and a ' +
+        'programmatic write no longer compiles.',
+    '  Reading `hideTabs` reports what was bound. What the header actually does is `tabsHidden()`, which ' +
+        'adds the rule that a single file with no filename hides the bar; the component used to write that ' +
+        'rule into `hideTabs` itself, which latched the bar off for good.',
+    '  An `activeFileIndex` outside `files` renders the first file instead of the indexed one, and an ' +
+        'empty `files` renders no code at all. Both used to reach `files[activeFileIndex]` and throw on ' +
+        'the undefined result. The index itself is left alone: resetting it wrote back into ' +
+        '`[(activeFileIndex)]` while the parent was still updating.'
+];
+
+exports.CODE_BLOCK_ELEMENT = CODE_BLOCK_ELEMENT;
+exports.CODE_BLOCK_EXPORT_AS = CODE_BLOCK_EXPORT_AS;
+exports.CODE_BLOCK_PACKAGE = CODE_BLOCK_PACKAGE;
+exports.CODE_BLOCK_TYPE = CODE_BLOCK_TYPE;
+exports.HIGHLIGHT_TYPE = HIGHLIGHT_TYPE;
+exports.PLUMBING_MEMBERS = PLUMBING_MEMBERS;
+exports.REPORTED_MEMBERS = REPORTED_MEMBERS;
+exports.SIGNAL_API_METHODS = SIGNAL_API_METHODS;
+exports.SIGNAL_MEMBERS = SIGNAL_MEMBERS;
+exports.SUMMARY = SUMMARY;
+exports.UNPARSEABLE_TEMPLATE_MESSAGE = UNPARSEABLE_TEMPLATE_MESSAGE;
+exports.UNRESOLVED_RECEIVER_MESSAGE = UNRESOLVED_RECEIVER_MESSAGE;
+exports.plumbingMessage = plumbingMessage;
+exports.reportedMessage = reportedMessage;
+exports.signalQueryMessage = signalQueryMessage;
+exports.writeMessage = writeMessage;