@aventara/client 0.1.0-pilot.3 → 0.1.0-pilot.4

package/dist/output/output.validator.d.ts

@@ -1,33 +1,5 @@
 import type * as ts from "typescript";
 import type { ClientEmission } from "../emit/emitted-tree.interface.js";
-/**
- * It judges a directory the writer has just filled with `tree`, and answers with a
- * value — the writer decides what a rejection means for the previous output.
- *
- * # Three checks, the strongest available first
- *
- * - **Shape**, always: the directory holds exactly `tree` — no file missing, none
- *   extra, every one byte-for-byte what was emitted — every file carries the
- *   ownership line, and every module a file names is a file of the tree, spelled
- *   the project's way. The ownership line is not decoration: the NEXT run reads it
- *   to decide that this directory is a previous generation it may replace whole,
- *   so a file without it would make the next run refuse. The imports are read
- *   lexically (`module-specifier.scanner.ts`), with no compiler — so a wrongly
- *   spelled import is refused even where the type check cannot run (TypeScript 7).
- * - **Types**, when the `typescript` optional peer resolves FROM THE PROJECT in
- *   its peer range: a real program over the tree under a consumer's strictest
- *   plausible settings, in the project's module resolution and format
- *   (`compilerOptionsFor`). The tree is judged ALONE — the compiler host serves
- *   nothing outside the directory but TypeScript's own `lib` files, so an import
- *   the tree cannot satisfy itself fails here even when a `node_modules` beside
- *   the output could satisfy it.
- * - **Syntax**, when it does not — or when the `typescript` that resolves has no
- *   classic compiler API: each file through Node's own TypeScript parser
- *   (`node:module`'s `stripTypeScriptTypes`, its ExperimentalWarning held back),
- *   with a loud warning of our own that the output was NOT type-checked. Degraded,
- *   never skipped, and never a refusal: the developer's own `tsc` still checks the
- *   tree when their project compiles.
- */
 /** The `typescript` module, as the validator uses it. */
 export type TypeScriptCompiler = typeof ts;
 /**
@@ -41,18 +13,7 @@ export type TypeScriptResolver = () => Promise<TypeScriptCompiler | undefined>;
  * a package from a file there: its `node_modules`, then each parent's.
  */
 export declare function typeScriptResolverFor(specifier: string, directory: string): TypeScriptResolver;
-/**
- * The `typescript` of the project that compiles the client, resolved from its
- * `generateAt`. Never this package's own: run through `npx`, the generator is
- * installed in npm's cache, where its optional peer never is — and the type check
- * is a stand-in for the project's own `tsc`, so the project's compiler is the one
- * that answers.
- */
 export declare function projectTypeScriptResolver(generateAt: string): TypeScriptResolver;
-/**
- * The lowest `typescript` the generator type-checks with: this package's
- * optional peer range, `>=5.5.0` (`packaging-gate.spec.ts` holds the two equal).
- */
 export declare const MINIMUM_TYPESCRIPT = "5.5.0";
 /** How deeply the tree was judged. */
 export type OutputCheck = "types" | "syntax" | "shape";

package/dist/output/output.writer.d.ts

@@ -2,74 +2,6 @@ import * as fsPromises from "node:fs/promises";
 import type { AbsolutePath } from "../config/client-config.interface.js";
 import { type ClientEmission, type EmittedTree } from "../emit/emitted-tree.interface.js";
 import { type OutputCheck, type TypeScriptResolver } from "./output.validator.js";
-/**
- * The output is written into `generateAt`, a directory the developer SHARES: it
- * may hold their own files. The generator owns exactly these entries in it — the
- * entry file `AvClient.ts` and `generated/` — and reads, refuses on, moves or
- * deletes nothing else there, apart from the transient entries it names itself
- * (`.aventara-next-*`, `.aventara-ready-*`, `.generated.aventara-previous`) and an
- * unreleased build's entry files, `AvClient.mjs` and `AvClient.d.mts`, which it
- * removes only while they carry the ownership line.
- *
- * - `generated/` is replaced WHOLE, never merged: a file the previous run emitted
- *   and this one does not is gone — an unreleased build's `.mjs` modules included.
- *   It is replaced only when every file in it carries the generated banner's
- *   ownership line (an empty directory owns nothing and is fine); otherwise the
- *   run is refused, naming the foreign files.
- * - Each entry file is replaced only when it is absent or carries the ownership
- *   line; otherwise the run is refused, naming it.
- * - `AvClient.mjs` and `AvClient.d.mts` — an unreleased build's entry — are
- *   removed when they carry the ownership line, so no stale JavaScript is left
- *   beside `AvClient.ts`. Without the line each is the developer's own file: never
- *   read beyond its head, never named, never removed. (pilot.0's and pilot.1's
- *   `AvClient.ts` is the entry file itself, replaced in place.)
- *
- * # The order, and its one window
- *
- * The whole tree — the entry files and `generated/` together — is written into a
- * staging directory inside `generateAt` (same filesystem, so every move is one
- * atomic `rename`) and validated there as one program. Then:
- *
- * 1. the staging directory is renamed `.aventara-ready-*`: from here it is known
- *    to be validated;
- * 2. the previous `generated/` → `.generated.aventara-previous`;
- * 3. the staged `generated/` → `generated/`;
- * 4. the previous entry files, and an owned earlier entry, move aside into the
- *    ready directory; then each staged entry file moves in;
- * 5. the previous `generated/` and the staging directory are removed.
- *
- * A failed step 3 renames the previous `generated/` straight back; a failed step 4
- * moves what it moved back — the new entry files out, the previous ones in — then
- * the new `generated/` out and the previous back, so a failure at any step leaves
- * the previous output. Node has no atomic exchange of two entries, so two windows
- * remain for a process KILLED mid-replace, and the next run's recovery closes each
- * before it does anything else:
- *
- * - between 2 and 3, `generated/` does not exist: the previous one is put back;
- * - between 3 and the end of 4, the new `generated/` sits beside the old entry
- *   files, or beside only some new ones: the validated entry files still staged in
- *   `.aventara-ready-*` are moved in, completing the new output rather than
- *   leaving a mismatched one.
- *
- * Staging directories that never reached step 1 were not validated and are
- * removed.
- *
- * # Failure is a sentence
- *
- * A refusal, a rejected tree or a filesystem error (an `Error` with a `code`) is
- * an `OutputWriteError` naming its stage — the person running the generator can
- * act on it. Any other error is a defect and propagates with its stack — the very
- * error thrown, not a wrapper — and what the run said before it is kept beside it,
- * read by `warningsRaisedBeforeDefect`.
- *
- * A refusal carries every warning the run raised before it stopped, in the order a
- * success would have returned them: a crash recovered in `prepare` changed the
- * disk, and the person has to hear that even when the run then fails.
- *
- * A failed run removes the directories it created to reach `generateAt` — and only
- * those, and only while empty — so a first run that fails leaves no empty
- * `generateAt` behind.
- */
 /** The four stages a write passes through, in order. */
 export type OutputWriteStage = "prepare" | "temp" | "validate" | "replace";
 /** A write that stopped; the previous output is intact unless it says otherwise. */
@@ -99,42 +31,18 @@ export declare function precedeDefect(defect: unknown, earlier: readonly string[
  * its warnings; empty when nothing was, or for an error no run threw.
  */
 export declare function warningsRaisedBeforeDefect(defect: unknown): readonly string[];
-/**
- * The filesystem calls the writer makes, `node:fs/promises` by default. A seam
- * because the filesystem is the writer's one external collaborator, and the only
- * way to prove a failure at the replace stage leaves the previous output intact
- * is to make a real rename fail.
- */
 export type OutputFileSystem = Pick<typeof fsPromises, "lstat" | "mkdir" | "open" | "readdir" | "rename" | "rm" | "rmdir" | "writeFile">;
 export interface ClientOutputWriteInput {
     /** What `emitClientTree` returned: the tree, and the warnings it raised. */
     readonly emission: ClientEmission;
-    /** The resolved `generateAt`. Created when missing. */
     readonly generateAt: AbsolutePath;
-    /**
-     * Content in the entry files or `generated/` the generator did not produce, which
-     * the person running it confirmed may be overwritten or removed — the paths
-     * `findForeignOutputContent` listed. Anything foreign that is not listed here is
-     * refused.
-     */
     readonly overrideForeign?: readonly string[];
-    /**
-     * The `typescript` optional peer; by default the project's own, resolved from
-     * `generateAt`.
-     */
     readonly resolveTypeScript?: TypeScriptResolver;
     readonly fileSystem?: OutputFileSystem;
 }
 export interface ClientOutputWritten {
     readonly generateAt: AbsolutePath;
-    /** How deeply the tree was validated before it replaced the output. */
     readonly checked: OutputCheck;
-    /**
-     * Everything the run has to say without failing, in order: the emission's own
-     * warnings (the rename ladder's), then the validator's (a degraded check), then
-     * the writer's (a recovered crash, a leftover it could not remove). Returned,
-     * never printed: the CLI owns the terminal.
-     */
     readonly warnings: readonly string[];
 }
 /**
@@ -145,25 +53,8 @@ export interface ClientOutputWritten {
  */
 export declare function writeClientOutput(input: ClientOutputWriteInput): Promise<ClientOutputWritten>;
 /**
- * Lists what in the entry files and `<generateAt>/generated/` the generator did
- * not produce — a file without the ownership line, a symbolic link, anything that
- * is not a regular file — so the person running it can be asked before a
- * generation overwrites or removes it. Reads only; looks at nothing else in
- * `generateAt`. Empty when `generateAt` does not exist yet.
- *
- * It sees what the write will see once it has recovered a killed run, without
- * recovering it: a `generated/` the killed run moved aside with nothing in its
- * place is read where it lies and its files named where recovery puts them back
- * (`generated/…`). So the question asked, and `--yes`, cover them too — and a run
- * that stops here has still touched nothing.
- *
  * @throws OutputWriteError when `generateAt` is not a directory, `generated` is
- * not a directory or an entry file is not a file: no confirmation repairs that.
+ *   not a directory or an entry file is not a file: no confirmation repairs that.
  */
 export declare function findForeignOutputContent(generateAt: AbsolutePath, fileSystem?: OutputFileSystem): Promise<readonly string[]>;
-/**
- * Whether the entry files and `generated/` in `generateAt` hold exactly `tree` —
- * every file byte for byte, no other file, no owned entry of an earlier build, and
- * nothing a killed run moved aside — so that writing `tree` would change nothing.
- */
 export declare function ownedOutputMatches(generateAt: AbsolutePath, tree: EmittedTree): Promise<boolean>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aventara/client",
-  "version": "0.1.0-pilot.3",
+  "version": "0.1.0-pilot.4",
   "license": "SEE LICENSE IN LICENSE",
   "description": "Development-time generator for Aventara typed remote clients.",
   "type": "module",
@@ -23,7 +23,7 @@
     "LICENSE-ADDITIONAL-PERMISSION.md"
   ],
   "dependencies": {
-    "@aventara/core": "0.1.0-pilot.3",
+    "@aventara/core": "0.1.0-pilot.4",
     "c12": "3.3.4",
     "get-tsconfig": "4.10.0"
   },
@@ -39,7 +39,7 @@
     "access": "public"
   },
   "devDependencies": {
-    "@aventara/testing": "0.1.0-pilot.3",
+    "@aventara/testing": "0.1.0-pilot.4",
     "@types/node": "24.10.1",
     "typescript": "^5.9.2"
   },