@venizia/ardor 0.4.8-0 → 0.4.8-10

package/README.md

@@ -13,6 +13,8 @@ control comes from `@venizia/ignis-inversion`, and the data layer speaks the que
 bun add @venizia/ardor @venizia/ignis-inversion @venizia/ignis-filter @venizia/ignis-kernel @venizia/ignis-helpers reflect-metadata
 ```
 
+The React-side peers (`react`, `react-dom`, `react-redux`, `@reduxjs/toolkit`, `@tanstack/react-query`, `ra-core`, `ra-i18n-polyglot`, `react-router-dom`) are installed too; the full `bun add` line is in the [setup guide](https://ardor.venizia.ai/guides/get-started/setup).
+
 ## The `Ardor` namespace
 
 `Ardor` gathers every React hook of the react and admin packages under one name: `Ardor.useRepository(...)`, `Ardor.useTranslate()`. It is the same function as the bare `useRepository`, the Rules of Hooks check the call, and a bundler keeps only the hooks you use, so it adds no bytes to an app.
@@ -20,8 +22,10 @@ bun add @venizia/ardor @venizia/ignis-inversion @venizia/ignis-filter @venizia/i
 ```tsx
 import { Ardor } from '@venizia/ardor';
 
+import { OrdersRepository } from './orders.repository';
+
 export const Orders = () => {
-  const repository = Ardor.useRepository({ key: 'repositories.Orders' });
+  const repository = Ardor.useRepository({ target: OrdersRepository });
 
   return <div>{String(repository)}</div>;
 };
@@ -29,7 +33,13 @@ export const Orders = () => {
 
 ## Moving to the new names
 
-`bun run ardor codemod namespace src` lists the removed bare names that have a replacement (`getRuntimeConfig` to `RuntimeConfig.get`, `isDefined` to `ValueUtility.isDefined`, `NullableType` to `undefined | null | void`, `Logger.getInstance({ scope })` to `LoggerFactory.getLogger([scope])`, ...) and the removed names with none, and writes nothing; `--write` applies it, `--check` fails while any is left, and `--hooks` also moves hooks imported from `@venizia/ardor` to `Ardor.useX`. It needs the `typescript` package.
+`bun run ardor codemod namespace src` lists the removed bare names that have a replacement (`getRuntimeConfig` to `RuntimeConfig.get`, `isDefined` to `ValueUtility.isDefined`, `NullableType` to `undefined | null | void`, `Logger.getInstance({ scope })` to `LoggerFactory.getLogger([scope])`, ...) and the removed names with none, and writes nothing; `--write` applies it (it refuses a file with local changes unless you add `--allow-dirty`), `--check` fails while any is left, and `--hooks` also moves hooks imported from `@venizia/ardor` to `Ardor.useX`. It needs the `typescript` package.
+
+## Subpaths
+
+- `@venizia/ardor/repository` - `HttpRepository` and the datasource settings; needs the optional peer `@venizia/ignis-connectors`.
+- `@venizia/ardor/testing` - `assertArdorApplicationBoots` and fakes of `ResizeObserver`, `IntersectionObserver`, `matchMedia`, storage and the clipboard, for your test suite.
+- `@venizia/ardor/vite` - `buildInfoFile`, a Vite plugin that writes the build info file; needs the optional peers `@venizia/ignis-boot` and `vite`.
 
 ## Quick start
 
@@ -108,7 +118,8 @@ export class Application extends BaseArdorApplication {
 ```
 
 The full guide, including the root component and the typed hooks, is in the
-[repository README](https://github.com/VENIZIA-AI/ardor#readme).
+[Quickstart](https://ardor.venizia.ai/guides/get-started/5-minute-quickstart) and the
+[references](https://ardor.venizia.ai/references/hooks).
 
 ## Migrating from `@minimaltech/ra-core-infra`
 

package/dist/ardor.d.ts

@@ -1,3 +1,3 @@
-export { useDocumentTitle, useFeatures, useHtmlLang, useNotifyError, useRefreshToken, useRequestHeaderLocale, useTranslate, } from '@venizia/ardor-admin';
-export { useApplicationContext, useApplicationLogger, useAutosave, useBeforeUnload, useComponent, useConfiguration, useConfirm, useCopyToClipboard, useDebounce, useElementSize, useInjectable, useInjectableContainer, useProvider, useRepository, useService, useSizer, useStoredState, useWindowDimensions, } from '@venizia/ardor-react';
+export { useDocumentTitle, useFeatures, useHtmlLang, useNotifyError, useRefreshToken, useRequestHeaderLocale, useTranslate, useUntypedTranslate, } from '@venizia/ardor-admin';
+export { useApplicationContainer, useApplicationContext, useApplicationLogger, useAutosave, useBeforeUnload, useComponent, useConfiguration, useConfirm, useCopyToClipboard, useDebounce, useDocumentVisibility, useElementSize, useInjectable, useIntersection, useMediaQuery, useOnlineStatus, useProvider, useRepository, useResizeEffect, useService, useStoredState, useWindowDimensions, } from '@venizia/ardor-react';
 //# sourceMappingURL=ardor.d.ts.map

package/dist/ardor.js

@@ -6,6 +6,6 @@
 //
 // A module namespace, not an object literal: a bundler resolves `Ardor.useRepository` to that one
 // hook and drops the rest, where an object that lists them all would pull every hook in.
-export { useDocumentTitle, useFeatures, useHtmlLang, useNotifyError, useRefreshToken, useRequestHeaderLocale, useTranslate, } from '@venizia/ardor-admin';
-export { useApplicationContext, useApplicationLogger, useAutosave, useBeforeUnload, useComponent, useConfiguration, useConfirm, useCopyToClipboard, useDebounce, useElementSize, useInjectable, useInjectableContainer, useProvider, useRepository, useService, useSizer, useStoredState, useWindowDimensions, } from '@venizia/ardor-react';
+export { useDocumentTitle, useFeatures, useHtmlLang, useNotifyError, useRefreshToken, useRequestHeaderLocale, useTranslate, useUntypedTranslate, } from '@venizia/ardor-admin';
+export { useApplicationContainer, useApplicationContext, useApplicationLogger, useAutosave, useBeforeUnload, useComponent, useConfiguration, useConfirm, useCopyToClipboard, useDebounce, useDocumentVisibility, useElementSize, useInjectable, useIntersection, useMediaQuery, useOnlineStatus, useProvider, useRepository, useResizeEffect, useService, useStoredState, useWindowDimensions, } from '@venizia/ardor-react';
 //# sourceMappingURL=ardor.js.map

package/dist/codemod/bin.js

@@ -3,7 +3,7 @@ import { NamespaceCommand } from './cli.js';
 const USAGE = `Usage: ardor <command>
 
 Commands:
-  codemod namespace   move the deprecated bare names to the class members that replace them
+  codemod namespace   move the removed bare names to the class members that replace them
 
 Run "ardor codemod namespace --help" for the options.`;
 /** The `ardor` bin of `@venizia/ardor`: `ardor codemod namespace [paths...] [--write | --check]`. */

package/dist/codemod/cli.d.ts

@@ -1,6 +1,6 @@
 /** `ardor codemod namespace`: a dry run unless `--write`; `--check` is the dry run that fails on work left. */
 export declare class NamespaceCommand {
-    static readonly USAGE = "Usage: ardor codemod namespace [paths...] [--hooks] [--write [--allow-dirty] | --check]\n\nMoves the names removed from @venizia/ardor to what replaces them:\n\n  isDefined, isString, isNumber, isObject, isValidDate   ValueUtility.<name>\n  isBrowser                                             BrowserUtility.isBrowser\n  toDataUrl                                             FileUtility.toDataUrl\n  getRuntimeConfig                                      RuntimeConfig.get\n  createAppDispatch, createAppSelectors                 DispatchHooks.create, SelectorHooks.create\n  resolveApplicationProviders                           ApplicationProviders.resolve\n  hasPendingFeatureMessages, loadFeatureMessages        Features.hasPendingMessages, Features.loadMessages\n  NumberIdType, StringIdType, NullableType              number, string, undefined | null | void\n  BaseHelper, LogLevels, ILogger, TLogLevel             the same names from @venizia/ignis-helpers/core\n  Logger.getInstance({ scope }), new Logger({ scope })  LoggerFactory.getLogger([scope]) (enableDebug is dropped, with a note)\n  Logger (a type)                                       ILogger\n\nRemoved with nothing to write in their place, so only listed with their line: isEditableTarget,\nTDataCount, ISyncFC, App.DEFAULT_LOCALE, HeaderConstants.REQUEST_DEVICE_INFO, HeaderConstants.RESPONSE_FORMAT,\nthe enableDebug prop of ArdorApplication (pass logger instead), and a Logger use with no one-line form.\n\nIt rewrites a name imported from @venizia/ardor, @venizia/ardor-kernel, @venizia/ardor-react or\n@venizia/ardor-admin, its uses, and the import. It reads syntax only: a name the file also declares\nitself, a re-export by name and a class name already taken are listed with their line and left for you.\n\n  --hooks    also move a hook imported from @venizia/ardor to the Ardor namespace (useRepository()\n             becomes Ardor.useRepository()). A hook imported from @venizia/ardor-react or\n             @venizia/ardor-admin is never touched: those packages cannot import Ardor.\n  --write    write the changed files (without it, nothing is written)\n  --allow-dirty  with --write, also write a file that has local changes, such as one another codemod\n             just changed (devz codemod namespace-functions --write leaves the tree dirty)\n  --check    dry run that exits 1 when anything would change or is left (for CI)\n  --help     print this text and exit\n\nWith no flag it lists what would change and writes nothing. Inside a git repository it reads the\nfiles git knows (tracked, or untracked and not ignored), and --write refuses a file with local\nchanges (changed, staged or untracked), so git can undo the codemod: the file is listed as \"refused\"\nwith its path, the summary counts it and the run exits 1. Commit or stash it and run again, or run\nagain with --allow-dirty to write it anyway (it keeps the other codemod's edits). To run two codemods\none after the other in a dirty tree, give this one --write --allow-dirty.\nRun your formatter afterwards: the new names are appended to the import they join.";
+    static readonly USAGE = "Usage: ardor codemod namespace [paths...] [--hooks] [--write [--allow-dirty] | --check]\n\nMoves the names removed from @venizia/ardor to what replaces them:\n\n  isDefined, isString, isNumber, isObject, isValidDate   ValueUtility.<name>\n  isBrowser                                             BrowserUtility.isBrowser\n  toDataUrl                                             FileUtility.toDataUrl\n  getRuntimeConfig                                      RuntimeConfig.get\n  createAppDispatch, createAppSelectors                 DispatchHooks.create, SelectorHooks.create\n  resolveApplicationProviders                           ApplicationProviders.resolve\n  hasPendingFeatureMessages, loadFeatureMessages        Features.hasPendingMessages, Features.loadMessages\n  NumberIdType, StringIdType, NullableType              number, string, undefined | null | void\n  BaseHelper, LogLevels, ILogger, TLogLevel             the same names from @venizia/ignis-helpers/core\n  Logger.getInstance({ scope }), new Logger({ scope })  LoggerFactory.getLogger([scope]) (enableDebug is dropped, with a note)\n  Logger (a type)                                       ILogger\n  ISendResponse                                         INetworkResponse\n\nRemoved with nothing to write in their place, so only listed with their line: isEditableTarget,\nTDataCount, ISyncFC, IListFilter.offset (use skip; listed wherever a file that imports IListFilter or ListFilterBuilder reads or sets .offset), useSizer (use useElementSize), useInjectableContainer (renamed useApplicationContainer), App.DEFAULT_LOCALE, HeaderConstants.REQUEST_DEVICE_INFO, HeaderConstants.RESPONSE_FORMAT,\nthe enableDebug prop of ArdorApplication (pass logger instead), and a Logger use with no one-line form.\n\nIt rewrites a name imported from @venizia/ardor, @venizia/ardor-kernel, @venizia/ardor-react or\n@venizia/ardor-admin, its uses, and the import. It reads syntax only: a name the file also declares\nitself, a re-export by name and a class name already taken are listed with their line and left for you.\n\n  --hooks    also move a hook imported from @venizia/ardor to the Ardor namespace (useRepository()\n             becomes Ardor.useRepository()). A hook imported from @venizia/ardor-react or\n             @venizia/ardor-admin is never touched: those packages cannot import Ardor.\n  --write    write the changed files (without it, nothing is written)\n  --allow-dirty  with --write, also write a file that has local changes, such as one another codemod\n             just changed (devz codemod namespace-functions --write leaves the tree dirty)\n  --check    dry run that exits 1 when anything would change or is left (for CI)\n  --help     print this text and exit\n\n--write is all or nothing: it reads and rewrites every file in memory first, and writes only if every\nfile went through. A file that cannot be parsed or rewritten is listed as \"failed\" with its path, the\nrun exits 1 and nothing is written. A file that is not valid UTF-8 and would change is a failure too:\nit is left alone rather than damaged. Outside a git repository nothing can undo a write, so --write\nrefuses unless you give --allow-dirty.\n\nWith no flag it lists what would change and writes nothing. Inside a git repository it reads the\nfiles git knows (tracked, or untracked and not ignored), and --write refuses a file with local\nchanges (changed, staged or untracked), so git can undo the codemod: the file is listed as \"refused\"\nwith its path, the summary counts it and the run exits 1. Commit or stash it and run again, or run\nagain with --allow-dirty to write it anyway (it keeps the other codemod's edits). To run two codemods\none after the other in a dirty tree, give this one --write --allow-dirty.\nRun your formatter afterwards: the new names are appended to the import they join.";
     /** Runs the command and returns the exit code; prints to the console. */
     static run(opts: {
         root: string;
@@ -8,6 +8,15 @@ export declare class NamespaceCommand {
     }): Promise<number>;
     private static loadTypeScript;
     private static sweep;
+    /**
+     * Writes every file next to itself first, and renames them into place only when all were written,
+     * so a failure leaves no file changed. A file that is not the file that was read (a link swapped in,
+     * an edit made meanwhile) is refused: the rename replaces a link instead of following it, and a
+     * hard link is not written through.
+     */
+    private static writeAll;
+    /** Text for the terminal: control, format and line-separator characters, such as an escape sequence in a file name, become `?`. */
+    private static clean;
     private static report;
 }
 //# sourceMappingURL=cli.d.ts.map

package/dist/codemod/cli.js

@@ -1,4 +1,4 @@
-import { readFileSync, writeFileSync } from 'node:fs';
+import { chmodSync, existsSync, lstatSync, readFileSync, renameSync, rmSync, writeFileSync, } from 'node:fs';
 import { relative, resolve } from 'node:path';
 import { CodemodFiles } from './files.js';
 import { Migration } from './migrate.js';
@@ -17,9 +17,10 @@ Moves the names removed from @venizia/ardor to what replaces them:
   BaseHelper, LogLevels, ILogger, TLogLevel             the same names from @venizia/ignis-helpers/core
   Logger.getInstance({ scope }), new Logger({ scope })  LoggerFactory.getLogger([scope]) (enableDebug is dropped, with a note)
   Logger (a type)                                       ILogger
+  ISendResponse                                         INetworkResponse
 
 Removed with nothing to write in their place, so only listed with their line: isEditableTarget,
-TDataCount, ISyncFC, App.DEFAULT_LOCALE, HeaderConstants.REQUEST_DEVICE_INFO, HeaderConstants.RESPONSE_FORMAT,
+TDataCount, ISyncFC, IListFilter.offset (use skip; listed wherever a file that imports IListFilter or ListFilterBuilder reads or sets .offset), useSizer (use useElementSize), useInjectableContainer (renamed useApplicationContainer), App.DEFAULT_LOCALE, HeaderConstants.REQUEST_DEVICE_INFO, HeaderConstants.RESPONSE_FORMAT,
 the enableDebug prop of ArdorApplication (pass logger instead), and a Logger use with no one-line form.
 
 It rewrites a name imported from @venizia/ardor, @venizia/ardor-kernel, @venizia/ardor-react or
@@ -35,6 +36,12 @@ itself, a re-export by name and a class name already taken are listed with their
   --check    dry run that exits 1 when anything would change or is left (for CI)
   --help     print this text and exit
 
+--write is all or nothing: it reads and rewrites every file in memory first, and writes only if every
+file went through. A file that cannot be parsed or rewritten is listed as "failed" with its path, the
+run exits 1 and nothing is written. A file that is not valid UTF-8 and would change is a failure too:
+it is left alone rather than damaged. Outside a git repository nothing can undo a write, so --write
+refuses unless you give --allow-dirty.
+
 With no flag it lists what would change and writes nothing. Inside a git repository it reads the
 files git knows (tracked, or untracked and not ignored), and --write refuses a file with local
 changes (changed, staged or untracked), so git can undo the codemod: the file is listed as "refused"
@@ -97,6 +104,11 @@ export class NamespaceCommand {
         const paths = args.filter((argument) => !argument.startsWith('-'));
         const targets = (paths.length > 0 ? paths : ['.']).map((path) => resolve(root, path));
         const hooks = args.includes(CodemodFlags.HOOKS);
+        const missing = targets.filter((target) => !existsSync(target));
+        if (missing.length > 0) {
+            console.error(`ardor codemod: no such file or folder: ${missing.map(NamespaceCommand.clean).join(', ')}`);
+            return USAGE_ERROR_CODE;
+        }
         return NamespaceCommand.sweep({ root, ts, targets, hooks, isWrite, isCheck, isAllowDirty });
     }
     static async loadTypeScript() {
@@ -113,43 +125,118 @@ export class NamespaceCommand {
     static sweep(opts) {
         const { root, ts, targets, hooks, isWrite, isCheck, isAllowDirty } = opts;
         const files = [...new Set(targets.flatMap((target) => CodemodFiles.collect({ target })))];
-        const dirty = isWrite && !isAllowDirty
-            ? new Set(targets.flatMap((target) => [...(CodemodFiles.dirty({ target }) ?? [])]))
-            : new Set();
+        const dirtyOf = targets.map((target) => CodemodFiles.dirty({ target }));
+        if (isWrite && !isAllowDirty && dirtyOf.some((dirty) => dirty === undefined)) {
+            console.error(`ardor codemod: this is not a git repository, so nothing can undo ${CodemodFlags.WRITE}; run again with ${CodemodFlags.ALLOW_DIRTY} to write anyway`);
+            return 1;
+        }
+        const dirty = new Set(isAllowDirty ? [] : dirtyOf.flatMap((paths) => [...(paths ?? [])]));
         const changes = [];
+        const pending = [];
         const refused = [];
+        const failed = [];
         const left = [];
         const notes = [];
         for (const path of files) {
-            const text = readFileSync(path, 'utf8');
-            const result = Migration.run({ ts, fileName: path, text, hooks });
-            for (const finding of result.findings) {
-                (finding.kind === 'note' ? notes : left).push({ path, finding });
+            try {
+                const stat = lstatSync(path);
+                const bytes = readFileSync(path);
+                const text = bytes.toString('utf8');
+                const result = Migration.run({ ts, fileName: path, text, hooks });
+                for (const finding of result.findings) {
+                    (finding.kind === 'note' ? notes : left).push({ path, finding });
+                }
+                if (result.text === text) {
+                    continue;
+                }
+                if (!Buffer.from(text, 'utf8').equals(bytes)) {
+                    failed.push({ path, reason: 'it is not valid UTF-8, so a rewrite would damage it' });
+                    continue;
+                }
+                if (isWrite && dirty.has(path)) {
+                    refused.push(path);
+                    continue;
+                }
+                changes.push({ path, renamed: result.renamed });
+                pending.push({ path, text: result.text, stat });
             }
-            if (result.text === text) {
-                continue;
+            catch (error) {
+                failed.push({ path, reason: error instanceof Error ? error.message : String(error) });
             }
-            if (isWrite && dirty.has(path)) {
-                refused.push(path);
-                continue;
+        }
+        if (isWrite && failed.length === 0) {
+            failed.push(...NamespaceCommand.writeAll({ pending }));
+        }
+        return NamespaceCommand.report({
+            root,
+            isWrite,
+            isCheck,
+            changes,
+            refused,
+            failed,
+            left,
+            notes,
+        });
+    }
+    /**
+     * Writes every file next to itself first, and renames them into place only when all were written,
+     * so a failure leaves no file changed. A file that is not the file that was read (a link swapped in,
+     * an edit made meanwhile) is refused: the rename replaces a link instead of following it, and a
+     * hard link is not written through.
+     */
+    static writeAll(opts) {
+        const staged = [];
+        const failures = [];
+        for (const { path, text, stat } of opts.pending) {
+            const temp = `${path}.${process.pid}.codemod`;
+            try {
+                const now = lstatSync(path);
+                if (!now.isFile() || now.mtimeMs !== stat.mtimeMs || now.size !== stat.size) {
+                    failures.push({
+                        path,
+                        reason: 'it changed while the codemod ran, so it was not written',
+                    });
+                    continue;
+                }
+                writeFileSync(temp, text);
+                chmodSync(temp, now.mode & 0o7777);
+                staged.push({ path, temp });
+            }
+            catch (error) {
+                rmSync(temp, { force: true });
+                failures.push({ path, reason: error instanceof Error ? error.message : String(error) });
             }
-            changes.push({ path, renamed: result.renamed });
-            if (isWrite) {
-                writeFileSync(path, result.text);
+        }
+        if (failures.length > 0) {
+            for (const { temp } of staged) {
+                rmSync(temp, { force: true });
             }
+            return failures;
         }
-        return NamespaceCommand.report({ root, isWrite, isCheck, changes, refused, left, notes });
+        for (const { path, temp } of staged) {
+            renameSync(temp, path);
+        }
+        return [];
+    }
+    /** Text for the terminal: control, format and line-separator characters, such as an escape sequence in a file name, become `?`. */
+    static clean(text) {
+        return text.replace(/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/gu, '?');
     }
     static report(opts) {
-        const { root, isWrite, isCheck, changes, refused, left, notes } = opts;
-        const verb = isWrite ? 'changed' : 'would change';
-        const show = (path) => relative(root, path) || path;
+        const { root, isWrite, isCheck, changes, refused, failed, left, notes } = opts;
+        // Nothing is written when a file failed, so the files are not "changed".
+        const verb = isWrite && failed.length === 0 ? 'changed' : 'would change';
+        // A path comes from the file system: a control character in it is shown as `?`, never sent to the terminal.
+        const show = (path) => NamespaceCommand.clean(relative(root, path) || path);
         for (const change of changes) {
             console.log(`${verb} ${show(change.path)} (${change.renamed} use${change.renamed === 1 ? '' : 's'})`);
         }
         for (const path of refused) {
             console.error(`refused ${show(path)}: it has local changes, so git cannot undo the codemod there; commit or stash it and run again, or run again with ${CodemodFlags.ALLOW_DIRTY}`);
         }
+        for (const { path, reason } of failed) {
+            console.error(NamespaceCommand.clean(`failed ${show(path)}: ${reason}`));
+        }
         // A note is a change made on purpose that is worth knowing; it is not work left, so --check ignores it.
         for (const { path, finding } of notes) {
             console.log(`note ${show(path)}:${finding.line} ${finding.name}: ${finding.reason}`);
@@ -157,9 +244,14 @@ export class NamespaceCommand {
         for (const { path, finding } of left) {
             console.error(`left ${show(path)}:${finding.line} ${finding.name}: ${finding.reason}`);
         }
-        const refusedNote = refused.length > 0 ? `, ${refused.length} refused (listed above)` : '';
+        const refusedNote = [
+            refused.length > 0 ? `, ${refused.length} refused (listed above)` : '',
+            failed.length > 0
+                ? `, ${failed.length} failed (listed above)${isWrite ? ', nothing was written' : ''}`
+                : '',
+        ].join('');
         console.log(`${changes.length} file${changes.length === 1 ? '' : 's'} ${verb}${refusedNote}, ${left.length} left for you${isWrite || changes.length === 0 ? '' : '. Run again with --write to apply.'}`);
-        if (refused.length > 0) {
+        if (refused.length > 0 || failed.length > 0) {
             return 1;
         }
         return isCheck && (changes.length > 0 || left.length > 0) ? 1 : 0;

package/dist/codemod/files.d.ts

@@ -7,7 +7,7 @@ export declare class CodemodFiles {
     static isSource(opts: {
         name: string;
     }): boolean;
-    /** Every source file under `target`; a file target is returned as it is. */
+    /** Every source file under `target`; a file target is returned as it is. A symlink or a file that is not a source file is never returned. */
     static collect(opts: {
         target: string;
     }): string[];

package/dist/codemod/files.js

@@ -1,5 +1,5 @@
 import { execFileSync } from 'node:child_process';
-import { existsSync, readdirSync, statSync } from 'node:fs';
+import { lstatSync, readdirSync, statSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 const SKIPPED_DIRECTORIES = new Set(['node_modules', 'dist', 'build', '.git']);
 const SOURCE_PATTERN = /\.(?:ts|tsx|mts|cts)$/;
@@ -13,11 +13,15 @@ export class CodemodFiles {
     static isSource(opts) {
         return SOURCE_PATTERN.test(opts.name) && !DECLARATION_PATTERN.test(opts.name);
     }
-    /** Every source file under `target`; a file target is returned as it is. */
+    /** Every source file under `target`; a file target is returned as it is. A symlink or a file that is not a source file is never returned. */
     static collect(opts) {
         const { target } = opts;
-        if (statSync(target).isFile()) {
-            return [target];
+        // Read without following a link: a symlink is never a file to write, whatever it points to.
+        if (lstatSync(target).isFile()) {
+            return CodemodFiles.isSource({ name: target }) ? [target] : [];
+        }
+        if (!statSync(target).isDirectory()) {
+            return [];
         }
         return CodemodFiles.fromGit({ target }) ?? CodemodFiles.fromWalk({ target });
     }
@@ -42,7 +46,7 @@ export class CodemodFiles {
             .filter((path) => path !== '' && CodemodFiles.isSource({ name: path }))
             .filter((path) => !path.split('/').some((segment) => SKIPPED_DIRECTORIES.has(segment)))
             .map((path) => join(target, path))
-            .filter((path) => existsSync(path) && statSync(path).isFile());
+            .filter((path) => lstatSync(path, { throwIfNoEntry: false })?.isFile() === true);
     }
     static fromWalk(opts) {
         const files = [];

package/dist/codemod/logger.js

@@ -179,7 +179,7 @@ export class LoggerTransform {
                 findings.push({
                     line: lineOf(call),
                     name: 'enableDebug',
-                    reason: 'note: dropped. debug lines are off by default now (a browser, or `DEBUG` unset); turn them on with `LoggerFactory.use({ level: LogLevels.DEBUG })` at startup',
+                    reason: 'dropped. debug lines are off by default now (a browser, or `DEBUG` unset); turn them on with `LoggerFactory.use({ level: LogLevels.DEBUG })` at startup',
                     kind: 'note',
                 });
             }

package/dist/codemod/renames.d.ts

@@ -34,11 +34,23 @@ export declare class TypeRenames {
         name: string;
     }): string | undefined;
 }
+/** Types removed in favour of another export of the same packages: the import and each use are renamed. */
+export declare class TypeExportRenames {
+    static readonly TARGETS: Readonly<Record<string, string>>;
+    static find(opts: {
+        name: string;
+    }): string | undefined;
+}
 /** Exports and members removed with no code the codemod can write in their place. */
 export declare class RemovedNames {
     static readonly EXPORTS: Readonly<Record<string, string>>;
     /** Class name to removed static member to the reason. */
     static readonly MEMBERS: Readonly<Record<string, Readonly<Record<string, string>>>>;
+    /** A property removed from the list filter: listed in a file that imports one of `owners`, as the file may use it. */
+    static readonly PROPERTIES: Readonly<Record<string, {
+        owners: ReadonlySet<string>;
+        reason: string;
+    }>>;
     static findExport(opts: {
         name: string;
     }): string | undefined;

package/dist/codemod/renames.js

@@ -39,6 +39,7 @@ export class FunctionRenames {
 export class HookRenames {
     static { this.OWNER = 'Ardor'; }
     static { this.NAMES = new Set([
+        'useApplicationContainer',
         'useApplicationContext',
         'useApplicationLogger',
         'useAutosave',
@@ -49,20 +50,24 @@ export class HookRenames {
         'useCopyToClipboard',
         'useDebounce',
         'useDocumentTitle',
+        'useDocumentVisibility',
         'useElementSize',
         'useFeatures',
         'useHtmlLang',
         'useInjectable',
-        'useInjectableContainer',
+        'useIntersection',
+        'useMediaQuery',
         'useNotifyError',
+        'useOnlineStatus',
         'useProvider',
         'useRefreshToken',
         'useRepository',
         'useRequestHeaderLocale',
+        'useResizeEffect',
         'useService',
-        'useSizer',
         'useStoredState',
         'useTranslate',
+        'useUntypedTranslate',
         'useWindowDimensions',
     ]); }
     static find(opts) {
@@ -80,12 +85,23 @@ export class TypeRenames {
         return Object.hasOwn(this.TARGETS, opts.name) ? this.TARGETS[opts.name] : undefined;
     }
 }
+/** Types removed in favour of another export of the same packages: the import and each use are renamed. */
+export class TypeExportRenames {
+    static { this.TARGETS = {
+        ISendResponse: 'INetworkResponse',
+    }; }
+    static find(opts) {
+        return Object.hasOwn(this.TARGETS, opts.name) ? this.TARGETS[opts.name] : undefined;
+    }
+}
 /** Exports and members removed with no code the codemod can write in their place. */
 export class RemovedNames {
     static { this.EXPORTS = {
         isEditableTarget: 'nothing in ARDOR called it; check the event target in your own code',
         TDataCount: 'nothing in ARDOR used it; declare the shape you need',
         ISyncFC: 'write the function type, (props: TProps) => ReactNode',
+        useInjectableContainer: 'renamed: call useApplicationContainer',
+        useSizer: 'use useElementSize({ ref, box: "border-box", round: true }) with a ref in place of the id',
     }; }
     /** Class name to removed static member to the reason. */
     static { this.MEMBERS = {
@@ -95,6 +111,13 @@ export class RemovedNames {
             RESPONSE_FORMAT: 'nothing in ARDOR sent or read this header',
         },
     }; }
+    /** A property removed from the list filter: listed in a file that imports one of `owners`, as the file may use it. */
+    static { this.PROPERTIES = {
+        offset: {
+            owners: new Set(['IListFilter', 'ListFilterBuilder']),
+            reason: 'the list filter has no offset, use skip',
+        },
+    }; }
     static findExport(opts) {
         return Object.hasOwn(this.EXPORTS, opts.name) ? this.EXPORTS[opts.name] : undefined;
     }

package/dist/codemod/transform.d.ts

@@ -15,7 +15,7 @@ export interface INamespaceResult {
     findings: IFinding[];
 }
 /**
- * Rewrites the deprecated bare names of `@venizia/ardor` to their class members, in source text:
+ * Rewrites the removed bare names of `@venizia/ardor` to their class members, in source text:
  * `isDefined(x)` becomes `ValueUtility.isDefined(x)` and the import follows. With `hooks`, a hook
  * imported from `@venizia/ardor` itself becomes `Ardor.useX` (never one imported from the react or
  * admin package, which cannot import `Ardor`).

package/dist/codemod/transform.js

@@ -1,6 +1,6 @@
-import { FunctionRenames, HookRenames, NamespaceModules, RemovedNames, TypeRenames, } from './renames.js';
+import { FunctionRenames, HookRenames, NamespaceModules, RemovedNames, TypeExportRenames, TypeRenames, } from './renames.js';
 /**
- * Rewrites the deprecated bare names of `@venizia/ardor` to their class members, in source text:
+ * Rewrites the removed bare names of `@venizia/ardor` to their class members, in source text:
  * `isDefined(x)` becomes `ValueUtility.isDefined(x)` and the import follows. With `hooks`, a hook
  * imported from `@venizia/ardor` itself becomes `Ardor.useX` (never one imported from the react or
  * admin package, which cannot import `Ardor`).
@@ -66,13 +66,15 @@ export class NamespaceTransform {
                     });
                     continue;
                 }
-                const typeText = TypeRenames.find({ name: imported });
+                const exportName = TypeExportRenames.find({ name: imported });
+                const typeText = exportName ?? TypeRenames.find({ name: imported });
                 if (typeText) {
                     renames.push({
                         specifier,
                         declaration: statement,
                         local: specifier.name.text,
                         typeText,
+                        importName: exportName,
                         references: [],
                     });
                     continue;
@@ -139,7 +141,9 @@ export class NamespaceTransform {
             else if ((ts.isFunctionDeclaration(node) ||
                 ts.isClassDeclaration(node) ||
                 ts.isFunctionExpression(node) ||
-                ts.isClassExpression(node)) &&
+                ts.isClassExpression(node) ||
+                ts.isTypeAliasDeclaration(node) ||
+                ts.isInterfaceDeclaration(node)) &&
                 node.name) {
                 declared.add(node.name.text);
             }
@@ -162,6 +166,18 @@ export class NamespaceTransform {
                 });
                 return false;
             }
+            const { importName } = rename;
+            const takenBy = importName ? bindings.imported.get(importName) : undefined;
+            if (importName &&
+                (bindings.declared.has(importName) ||
+                    (takenBy && !NamespaceModules.isValid(takenBy.module)))) {
+                findings.push({
+                    line,
+                    name: rename.local,
+                    reason: `"${importName}" is already taken in this file; import it under another name and use it in place of ${rename.local}`,
+                });
+                return false;
+            }
             if (!owner || !rename.target) {
                 return true;
             }
@@ -240,7 +256,8 @@ export class NamespaceTransform {
         }
         if (rename.typeText !== undefined) {
             // A type is a name in a type position only: `NullableType[]` needs parentheses once replaced.
-            if (ts.isTypeReferenceNode(parent) && parent.typeName === node) {
+            if ((ts.isTypeReferenceNode(parent) && parent.typeName === node) ||
+                (ts.isExpressionWithTypeArguments(parent) && parent.expression === node)) {
                 const grand = parent.parent;
                 const wrap = rename.typeText.includes('|') &&
                     (ts.isArrayTypeNode(grand) ||
@@ -278,7 +295,32 @@ export class NamespaceTransform {
         if (owners.size === 0) {
             return;
         }
+        const imported = new Set(owners.values());
         const visit = (node) => {
+            let name;
+            if (ts.isPropertyAccessExpression(node) ||
+                ts.isPropertyAssignment(node) ||
+                ts.isShorthandPropertyAssignment(node)) {
+                name = node.name;
+            }
+            else if (ts.isBindingElement(node) && ts.isObjectBindingPattern(node.parent)) {
+                name = node.propertyName ?? node.name;
+            }
+            else if (ts.isElementAccessExpression(node) &&
+                ts.isStringLiteral(node.argumentExpression)) {
+                name = node.argumentExpression;
+            }
+            const key = name && (ts.isIdentifier(name) || ts.isStringLiteral(name)) ? name : undefined;
+            const property = key && Object.hasOwn(RemovedNames.PROPERTIES, key.text)
+                ? RemovedNames.PROPERTIES[key.text]
+                : undefined;
+            if (key && property && [...property.owners].some((owner) => imported.has(owner))) {
+                findings.push({
+                    line: sourceFile.getLineAndCharacterOfPosition(key.getStart(sourceFile)).line + 1,
+                    name: `.${key.text}`,
+                    reason: `removed: ${property.reason}`,
+                });
+            }
             if (ts.isPropertyAccessExpression(node) && ts.isIdentifier(node.expression)) {
                 const owner = owners.get(node.expression.text);
                 const reason = owner
@@ -323,7 +365,17 @@ export class NamespaceTransform {
             for (const owner of owners) {
                 added.add(owner);
             }
-            const names = [...kept, ...owners];
+            const types = [];
+            for (const { declaration: from, importName, specifier } of used) {
+                if (from === declaration &&
+                    importName &&
+                    !bindings.imported.has(importName) &&
+                    !added.has(importName)) {
+                    added.add(importName);
+                    types.push(`${specifier.isTypeOnly ? 'type ' : ''}${importName}`);
+                }
+            }
+            const names = [...kept, ...owners, ...types];
             if (names.length === 0) {
                 edits.push(NamespaceTransform.removeImport({ sourceFile, declaration, clause, named, ts }));
                 continue;

package/dist/index.d.ts

@@ -1,3 +1,24 @@
+/**
+ * Every ARDOR hook under one name: `Ardor.useRepository(...)` is the same function as
+ * `useRepository`. Call a member by its name; do not index with a computed key (`Ardor[name]`), which
+ * keeps every hook in a bundle.
+ *
+ * @example
+ * ```tsx
+ * import { Ardor, repository } from '@venizia/ardor';
+ *
+ * @repository()
+ * class OrdersRepository {
+ *   count() { return 3; }
+ * }
+ *
+ * export const Orders = () => {
+ *   const orders = Ardor.useRepository({ target: OrdersRepository });
+ *   const container = Ardor.useApplicationContainer();
+ *   return <span>{orders.count()} {container.isBound({ key: 'repositories.OrdersRepository' }) ? 'bound' : 'missing'}</span>;
+ * };
+ * ```
+ */
 export * as Ardor from './ardor.js';
 export * from '@venizia/ardor-kernel';
 export * from '@venizia/ardor-react';

package/dist/index.js

@@ -1,6 +1,27 @@
 // ARDOR - one entry point over the framework packages.
 // An application imports from `@venizia/ardor`; a consumer that needs only one layer installs that
 // package directly.
+/**
+ * Every ARDOR hook under one name: `Ardor.useRepository(...)` is the same function as
+ * `useRepository`. Call a member by its name; do not index with a computed key (`Ardor[name]`), which
+ * keeps every hook in a bundle.
+ *
+ * @example
+ * ```tsx
+ * import { Ardor, repository } from '@venizia/ardor';
+ *
+ * @repository()
+ * class OrdersRepository {
+ *   count() { return 3; }
+ * }
+ *
+ * export const Orders = () => {
+ *   const orders = Ardor.useRepository({ target: OrdersRepository });
+ *   const container = Ardor.useApplicationContainer();
+ *   return <span>{orders.count()} {container.isBound({ key: 'repositories.OrdersRepository' }) ? 'bound' : 'missing'}</span>;
+ * };
+ * ```
+ */
 export * as Ardor from './ardor.js';
 export * from '@venizia/ardor-kernel';
 export * from '@venizia/ardor-react';