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

package/dist/init/client-init.questions.d.ts

@@ -1,11 +1,8 @@
 export declare const PACKAGE_MANAGERS: readonly ["npm", "pnpm"];
 export type PackageManager = (typeof PACKAGE_MANAGERS)[number];
 export type ClientInitAnswers = {
-    /** The deployment's entrypoint. */
     readonly entrypoint: string;
-    /** The variable `framework.client.ts` reads it from, or `undefined` for a literal. */
     readonly envVar: string | undefined;
-    /** Where the client is generated. */
     readonly generateAt: string;
     readonly packageManager: PackageManager;
 };
@@ -27,7 +24,6 @@ export type ClientInitQuestion = {
     /** @throws ClientInitAnswerError */
     readonly parse: (raw: string) => string;
 };
-/** The project convention for the variable. */
 export declare const DEFAULT_ENV_VAR = "AVENTARA_API_URL";
 export declare const CLIENT_INIT_QUESTIONS: readonly ClientInitQuestion[];
 export type ClientInitSources = {
@@ -40,9 +36,5 @@ export type ClientInitSources = {
     readonly say: (line: string) => void;
     readonly detectedPackageManager: PackageManager;
 };
-/**
- * Flag → `--yes`'s default → the prompt → the refusal naming exactly the
- * unanswered flags.
- */
 export declare function resolveClientInitAnswers(sources: ClientInitSources): Promise<ClientInitAnswers>;
 export {};

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

@@ -1,31 +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: 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`), with a loud warning 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;
 /**
@@ -35,12 +9,12 @@ export type TypeScriptCompiler = typeof ts;
  */
 export type TypeScriptResolver = () => Promise<TypeScriptCompiler | undefined>;
 /**
- * A resolver for `specifier`, looked up from this package the way Node would look
- * it up: an optional peer is linked beside the package that declares it.
+ * A resolver for `specifier`, looked up from `directory` the way Node looks up
+ * a package from a file there: its `node_modules`, then each parent's.
  */
-export declare function typeScriptResolverFor(specifier: string): TypeScriptResolver;
-/** The `typescript` this package's optional peer names. */
-export declare const resolveInstalledTypeScript: TypeScriptResolver;
+export declare function typeScriptResolverFor(specifier: string, directory: string): TypeScriptResolver;
+export declare function projectTypeScriptResolver(generateAt: string): TypeScriptResolver;
+export declare const MINIMUM_TYPESCRIPT = "5.5.0";
 /** How deeply the tree was judged. */
 export type OutputCheck = "types" | "syntax" | "shape";
 export interface OutputAccepted {
@@ -70,6 +44,15 @@ export declare const SYNTAX_CHECK_UNAVAILABLE_WARNING: string;
  */
 export declare function typeScriptWithoutCompilerApiWarning(version: string, checked: "syntax" | "shape"): string;
 /**
- * Judges `directory`, which the caller has just filled with `tree`.
+ * The warning a run carries when the project's `typescript` is older than the
+ * peer range: its compiler API lacks options the check sets (`Bundler`
+ * resolution, `verbatimModuleSyntax`), so its verdict would not be the one a
+ * supported compiler gives.
+ */
+export declare function typeScriptBelowRangeWarning(version: string, checked: "syntax" | "shape"): string;
+/**
+ * Judges `directory`, which the caller has just filled with `tree`, with the
+ * `typescript` `resolveTypeScript` finds — the project's
+ * ({@link projectTypeScriptResolver}).
  */
-export declare function validateOutputTree(directory: string, emission: Pick<ClientEmission, "style" | "tree">, resolveTypeScript?: TypeScriptResolver): Promise<OutputValidation>;
+export declare function validateOutputTree(directory: string, emission: Pick<ClientEmission, "style" | "tree">, resolveTypeScript: TypeScriptResolver): Promise<OutputValidation>;

package/dist/output/output.validator.js

@@ -5,11 +5,11 @@ import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { carriesGeneratedOwnership } from "../emit/banner.emitter.js";
 import { scanModuleSpecifiers } from "../emit/module-specifier.scanner.js";
-export function typeScriptResolverFor(specifier) {
+export function typeScriptResolverFor(specifier, directory) {
     return async () => {
         let resolved;
         try {
-            resolved = createRequire(import.meta.url).resolve(specifier);
+            resolved = createRequire(path.join(directory, "package.json")).resolve(specifier);
         }
         catch (error) {
             if (isErrorWithCode(error, "MODULE_NOT_FOUND")) {
@@ -21,7 +21,25 @@ export function typeScriptResolverFor(specifier) {
         return loaded.default ?? loaded;
     };
 }
-export const resolveInstalledTypeScript = typeScriptResolverFor("typescript");
+export function projectTypeScriptResolver(generateAt) {
+    return typeScriptResolverFor("typescript", generateAt);
+}
+export const MINIMUM_TYPESCRIPT = "5.5.0";
+function meetsMinimum(version) {
+    const parts = /^(\d+)\.(\d+)\.(\d+)/.exec(version);
+    const minimum = MINIMUM_TYPESCRIPT.split(".").map(Number);
+    if (parts === null) {
+        return false;
+    }
+    for (let at = 0; at < 3; at += 1) {
+        const have = Number(parts[at + 1]);
+        const need = minimum[at];
+        if (have !== need) {
+            return have > need;
+        }
+    }
+    return true;
+}
 function hasClassicCompilerApi(compiler) {
     return (typeof compiler.createProgram ===
         "function");
@@ -41,14 +59,34 @@ export function typeScriptWithoutCompilerApiWarning(version, checked) {
         `output was NOT type-checked${checked === "shape" ? " or parsed — only its shape was" : " — only its shape and syntax were"}. ` +
         "Your project's own `tsc` checks it when it compiles; a `typescript` 5.5 to 6 restores the generator's own type check.");
 }
-export async function validateOutputTree(directory, emission, resolveTypeScript = resolveInstalledTypeScript) {
+export function typeScriptBelowRangeWarning(version, checked) {
+    return (`the installed \`typescript\` ${version} is older than ${MINIMUM_TYPESCRIPT}, the lowest @aventara/client supports, so the generated ` +
+        `output was NOT type-checked${checked === "shape" ? " or parsed — only its shape was" : " — only its shape and syntax were"}. ` +
+        `Upgrade the project's \`typescript\` to ${MINIMUM_TYPESCRIPT} or later to restore the type check.`);
+}
+function degradedWarning(compiler, checked) {
+    if (compiler === undefined) {
+        return checked === "syntax"
+            ? TYPESCRIPT_UNRESOLVED_WARNING
+            : SYNTAX_CHECK_UNAVAILABLE_WARNING;
+    }
+    if (!hasClassicCompilerApi(compiler)) {
+        return typeScriptWithoutCompilerApiWarning(versionOf(compiler), checked);
+    }
+    if (!meetsMinimum(versionOf(compiler))) {
+        return typeScriptBelowRangeWarning(versionOf(compiler), checked);
+    }
+    return undefined;
+}
+export async function validateOutputTree(directory, emission, resolveTypeScript) {
     const { tree, style } = emission;
     const shapeFindings = await shapeFindingsOf(directory, tree, style);
     if (shapeFindings.length > 0) {
         return { accepted: false, checked: "shape", findings: shapeFindings };
     }
     const compiler = await resolveTypeScript();
-    if (compiler !== undefined && hasClassicCompilerApi(compiler)) {
+    if (compiler !== undefined &&
+        degradedWarning(compiler, "syntax") === undefined) {
         const findings = typeFindingsOf(compiler, directory, tree, style);
         return findings.length > 0
             ? { accepted: false, checked: "types", findings }
@@ -59,11 +97,7 @@ export async function validateOutputTree(directory, emission, resolveTypeScript
         return {
             accepted: true,
             checked: "shape",
-            warnings: [
-                compiler === undefined
-                    ? SYNTAX_CHECK_UNAVAILABLE_WARNING
-                    : typeScriptWithoutCompilerApiWarning(versionOf(compiler), "shape"),
-            ],
+            warnings: [degradedWarning(compiler, "shape")],
         };
     }
     const findings = syntaxFindingsOf(strip, tree);
@@ -72,11 +106,7 @@ export async function validateOutputTree(directory, emission, resolveTypeScript
         : {
             accepted: true,
             checked: "syntax",
-            warnings: [
-                compiler === undefined
-                    ? TYPESCRIPT_UNRESOLVED_WARNING
-                    : typeScriptWithoutCompilerApiWarning(versionOf(compiler), "syntax"),
-            ],
+            warnings: [degradedWarning(compiler, "syntax")],
         };
 }
 async function shapeFindingsOf(directory, tree, style) {
@@ -225,7 +255,29 @@ function isInside(directory, file) {
 }
 function nodeTypeScriptParser() {
     const candidate = nodeModule.stripTypeScriptTypes;
-    return typeof candidate === "function" ? candidate : undefined;
+    if (typeof candidate !== "function") {
+        return undefined;
+    }
+    return (source) => {
+        const emitWarning = process.emitWarning;
+        process.emitWarning = function (warning, ...rest) {
+            const [kind] = rest;
+            const type = typeof kind === "string"
+                ? kind
+                : kind?.type;
+            if (type === "ExperimentalWarning" &&
+                String(warning).startsWith("stripTypeScriptTypes ")) {
+                return;
+            }
+            emitWarning.call(this, warning, ...rest);
+        };
+        try {
+            return candidate(source);
+        }
+        finally {
+            process.emitWarning = emitWarning;
+        }
+    };
 }
 function syntaxFindingsOf(strip, tree) {
     const decoder = new TextDecoder("utf-8");

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,39 +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; the installed one by default. */
     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[];
 }
 /**
@@ -142,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/dist/output/output.writer.js

@@ -3,7 +3,7 @@ import * as fsPromises from "node:fs/promises";
 import path from "node:path";
 import { carriesGeneratedOwnership, GENERATED_OWNERSHIP_HEAD_BYTES, } from "../emit/banner.emitter.js";
 import { CLIENT_ENTRY_FILES, GENERATED_DIRECTORY, LEGACY_CLIENT_ENTRY_FILES, } from "../emit/emitted-tree.interface.js";
-import { resolveInstalledTypeScript, validateOutputTree, } from "./output.validator.js";
+import { projectTypeScriptResolver, validateOutputTree, } from "./output.validator.js";
 export class OutputWriteError extends Error {
     stage;
     name = "OutputWriteError";
@@ -94,7 +94,7 @@ export async function writeClientOutput(input) {
                     await fs.writeFile(target, file.bytes);
                 }
             });
-            const validation = await stage("validate", paths, () => validateOutputTree(staging, input.emission, input.resolveTypeScript ?? resolveInstalledTypeScript));
+            const validation = await stage("validate", paths, () => validateOutputTree(staging, input.emission, input.resolveTypeScript ?? projectTypeScriptResolver(generateAt)));
             if (validation.accepted) {
                 validationWarnings = validation.warnings;
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aventara/client",
-  "version": "0.1.0-pilot.2",
+  "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.2",
+    "@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.2",
+    "@aventara/testing": "0.1.0-pilot.4",
     "@types/node": "24.10.1",
     "typescript": "^5.9.2"
   },