@aventara/client 0.0.0-stage → 0.1.0-pilot.1

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

@@ -0,0 +1,75 @@
+import type * as ts from "typescript";
+import type { EmittedTree } from "../emit/emitted-tree.interface.js";
+/**
+ * §15.3's "type/sanity validation" step, between emit-to-temp and the replace:
+ * the gate that makes the atomicity worth having (plan §4 Q6). 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 — and every file carries the
+ *   ownership line. That last 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.
+ * - **Types**, when the `typescript` optional peer resolves (Q5, Q6): a real
+ *   program over the tree under a consumer's strictest plausible settings. 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
+ *   (§15.5).
+ * - **Syntax**, when it does not — or when the `typescript` that resolves has no
+ *   classic compiler API (TypeScript 7, plan B3; pilot.1): 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
+ *   (S7), 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;
+/**
+ * Finds the `typescript` optional peer: the module, or `undefined` when it is not
+ * installed. Anything else — an installation that resolves but fails to load — is
+ * not "absent" and is thrown.
+ */
+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.
+ */
+export declare function typeScriptResolverFor(specifier: string): TypeScriptResolver;
+/** The `typescript` this package's optional peer names (Q5). */
+export declare const resolveInstalledTypeScript: TypeScriptResolver;
+/** How deeply the tree was judged. */
+export type OutputCheck = "types" | "syntax" | "shape";
+export interface OutputAccepted {
+    readonly accepted: true;
+    readonly checked: OutputCheck;
+    /** Said once to the person running the generator; empty when nothing degraded. */
+    readonly warnings: readonly string[];
+}
+export interface OutputRejected {
+    readonly accepted: false;
+    readonly checked: OutputCheck;
+    /** What is wrong, one line per finding, paths relative to the tree. */
+    readonly findings: readonly string[];
+}
+export type OutputValidation = OutputAccepted | OutputRejected;
+/**
+ * The warning a run without `typescript` carries. Loud on purpose, in its words:
+ * the prefix is the CLI's one `warning:`, so the text carries none of its own.
+ */
+export declare const TYPESCRIPT_UNRESOLVED_WARNING: string;
+/** The warning a run with neither `typescript` nor Node's parser carries. */
+export declare const SYNTAX_CHECK_UNAVAILABLE_WARNING: string;
+/**
+ * The warning a run carries when the `typescript` that resolves is one the
+ * generator cannot type-check with (TypeScript 7): what was checked instead,
+ * and where the type check still happens.
+ */
+export declare function typeScriptWithoutCompilerApiWarning(version: string, checked: "syntax" | "shape"): string;
+/**
+ * Judges `directory`, which the caller has just filled with `tree`.
+ */
+export declare function validateOutputTree(directory: string, tree: EmittedTree, resolveTypeScript?: TypeScriptResolver): Promise<OutputValidation>;

package/dist/output/output.validator.js

@@ -0,0 +1,262 @@
+import { readdir, readFile } from "node:fs/promises";
+import * as nodeModule from "node:module";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { carriesGeneratedOwnership } from "../emit/banner.emitter.js";
+/**
+ * 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.
+ */
+export function typeScriptResolverFor(specifier) {
+    return async () => {
+        let resolved;
+        try {
+            resolved = createRequire(import.meta.url).resolve(specifier);
+        }
+        catch (error) {
+            if (isErrorWithCode(error, "MODULE_NOT_FOUND")) {
+                return undefined;
+            }
+            throw error;
+        }
+        const loaded = (await import(pathToFileURL(resolved).href));
+        return loaded.default ?? loaded;
+    };
+}
+/** The `typescript` this package's optional peer names (Q5). */
+export const resolveInstalledTypeScript = typeScriptResolverFor("typescript");
+/**
+ * Whether `compiler` has the classic compiler API {@link typeFindingsOf} uses.
+ * TypeScript 7 does not (plan B3: its package exports its version and nothing
+ * else); before pilot.1 the generator refused it, and its peer range stopped
+ * below it — which made `npm i` fail with ERESOLVE in any frontend whose
+ * `typescript` is the current `latest`.
+ */
+function hasClassicCompilerApi(compiler) {
+    // One member, not `Partial<typeof ts>`: a mapped type over the whole
+    // compiler namespace costs thousands of instantiations to ask one question.
+    return (typeof compiler.createProgram ===
+        "function");
+}
+/** The version a resolved `typescript` names, whatever its API. */
+function versionOf(compiler) {
+    const { version } = compiler;
+    return typeof version === "string" ? version : "(no version)";
+}
+/**
+ * The warning a run without `typescript` carries. Loud on purpose, in its words:
+ * the prefix is the CLI's one `warning:`, so the text carries none of its own.
+ */
+export const TYPESCRIPT_UNRESOLVED_WARNING = "`typescript` could not be resolved, so the generated output was NOT type-checked — " +
+    "only its shape and syntax were. Install `typescript` (an optional peer of @aventara/client) " +
+    "in this project to restore the type check.";
+/** The warning a run with neither `typescript` nor Node's parser carries. */
+export const SYNTAX_CHECK_UNAVAILABLE_WARNING = "neither `typescript` nor Node's TypeScript parser is available, so the generated " +
+    "output was NOT type-checked or parsed — only its shape was. Install `typescript` (an " +
+    "optional peer of @aventara/client) in this project to restore the type check.";
+/**
+ * The warning a run carries when the `typescript` that resolves is one the
+ * generator cannot type-check with (TypeScript 7): what was checked instead,
+ * and where the type check still happens.
+ */
+export function typeScriptWithoutCompilerApiWarning(version, checked) {
+    return (`the installed \`typescript\` ${version} has no classic compiler API (\`createProgram\`), so the generated ` +
+        `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.");
+}
+/**
+ * Judges `directory`, which the caller has just filled with `tree`.
+ */
+export async function validateOutputTree(directory, tree, resolveTypeScript = resolveInstalledTypeScript) {
+    const shapeFindings = await shapeFindingsOf(directory, tree);
+    if (shapeFindings.length > 0) {
+        return { accepted: false, checked: "shape", findings: shapeFindings };
+    }
+    const compiler = await resolveTypeScript();
+    if (compiler !== undefined && hasClassicCompilerApi(compiler)) {
+        const findings = typeFindingsOf(compiler, directory, tree);
+        return findings.length > 0
+            ? { accepted: false, checked: "types", findings }
+            : { accepted: true, checked: "types", warnings: [] };
+    }
+    const strip = nodeTypeScriptParser();
+    if (strip === undefined) {
+        return {
+            accepted: true,
+            checked: "shape",
+            warnings: [
+                compiler === undefined
+                    ? SYNTAX_CHECK_UNAVAILABLE_WARNING
+                    : typeScriptWithoutCompilerApiWarning(versionOf(compiler), "shape"),
+            ],
+        };
+    }
+    const findings = syntaxFindingsOf(strip, tree);
+    return findings.length > 0
+        ? { accepted: false, checked: "syntax", findings }
+        : {
+            accepted: true,
+            checked: "syntax",
+            warnings: [
+                compiler === undefined
+                    ? TYPESCRIPT_UNRESOLVED_WARNING
+                    : typeScriptWithoutCompilerApiWarning(versionOf(compiler), "syntax"),
+            ],
+        };
+}
+/* ------------------------------------------------------------------ *
+ * Shape                                                                *
+ * ------------------------------------------------------------------ */
+async function shapeFindingsOf(directory, tree) {
+    const findings = [];
+    const expected = new Map(tree.map((file) => [file.path, file.bytes]));
+    const entries = await readdir(directory, {
+        recursive: true,
+        withFileTypes: true,
+    });
+    const present = new Set();
+    for (const entry of entries) {
+        if (entry.isDirectory()) {
+            continue;
+        }
+        const relative = path
+            .relative(directory, path.join(entry.parentPath, entry.name))
+            .split(path.sep)
+            .join("/");
+        present.add(relative);
+        if (!entry.isFile() || !expected.has(relative)) {
+            findings.push(`${relative}: not part of the emitted tree`);
+        }
+    }
+    const decoder = new TextDecoder("utf-8", { fatal: true });
+    for (const [relative, bytes] of expected) {
+        if (!present.has(relative)) {
+            findings.push(`${relative}: missing`);
+            continue;
+        }
+        const written = await readFile(path.join(directory, relative));
+        if (!Buffer.from(bytes).equals(written)) {
+            findings.push(`${relative}: not the bytes that were emitted`);
+            continue;
+        }
+        let text;
+        try {
+            text = decoder.decode(written);
+        }
+        catch {
+            findings.push(`${relative}: not UTF-8`);
+            continue;
+        }
+        if (!carriesGeneratedOwnership(text)) {
+            findings.push(`${relative}: does not carry the generated banner`);
+        }
+    }
+    return findings.sort();
+}
+/* ------------------------------------------------------------------ *
+ * Types: a real program over the tree, and nothing outside it          *
+ * ------------------------------------------------------------------ */
+/**
+ * The emitted-tree fixture's settings (`__fixtures__/emitted-tree.fixture.ts`),
+ * restated here because production code does not import a test fixture: a
+ * consumer's strictest plausible configuration, with no DOM and no Node (§15.7:
+ * both are first-class targets, so the tree may assume neither).
+ */
+function compilerOptionsFor(compiler) {
+    return {
+        target: compiler.ScriptTarget.ES2022,
+        module: compiler.ModuleKind.NodeNext,
+        moduleResolution: compiler.ModuleResolutionKind.NodeNext,
+        lib: ["lib.es2022.d.ts"],
+        types: [],
+        strict: true,
+        noUncheckedIndexedAccess: true,
+        exactOptionalPropertyTypes: true,
+        verbatimModuleSyntax: true,
+        isolatedModules: true,
+        erasableSyntaxOnly: true,
+        noUnusedLocals: true,
+        noUnusedParameters: true,
+        noImplicitReturns: true,
+        noImplicitOverride: true,
+        noFallthroughCasesInSwitch: true,
+        noPropertyAccessFromIndexSignature: true,
+        skipDefaultLibCheck: true,
+        noEmit: true,
+    };
+}
+/**
+ * The tree is served as an ES module package of its own: NodeNext reads the
+ * nearest `package.json` to decide a `.ts` file's module format, and the one a
+ * consumer's project happens to have must not decide this verdict.
+ */
+const VIRTUAL_PACKAGE_JSON = '{ "type": "module" }';
+function typeFindingsOf(compiler, directory, tree) {
+    const root = path.resolve(directory);
+    const options = compilerOptionsFor(compiler);
+    const libraryDirectory = path.dirname(compiler.getDefaultLibFilePath(options));
+    const virtualPackageJson = path.join(root, "package.json");
+    const servable = (file) => isInside(root, file) || isInside(libraryDirectory, file);
+    const host = compiler.createCompilerHost(options, true);
+    const baseFileExists = host.fileExists.bind(host);
+    const baseReadFile = host.readFile.bind(host);
+    const baseDirectoryExists = host.directoryExists?.bind(host);
+    host.fileExists = (file) => path.resolve(file) === virtualPackageJson ||
+        (servable(path.resolve(file)) && baseFileExists(file));
+    host.readFile = (file) => path.resolve(file) === virtualPackageJson
+        ? VIRTUAL_PACKAGE_JSON
+        : servable(path.resolve(file))
+            ? baseReadFile(file)
+            : undefined;
+    host.directoryExists = (candidate) => {
+        const resolved = path.resolve(candidate);
+        return ((servable(resolved) || isInside(resolved, root)) &&
+            (baseDirectoryExists?.(candidate) ?? true));
+    };
+    host.getCurrentDirectory = () => root;
+    const program = compiler.createProgram({
+        rootNames: tree.map((file) => path.join(root, file.path)),
+        options,
+        host,
+    });
+    const diagnostics = compiler.getPreEmitDiagnostics(program);
+    return diagnostics.map((diagnostic) => compiler
+        .formatDiagnostic(diagnostic, {
+        getCanonicalFileName: (file) => file,
+        getCurrentDirectory: () => root,
+        getNewLine: () => "\n",
+    })
+        .trimEnd());
+}
+/** Whether `file` is `directory` or lies beneath it. */
+function isInside(directory, file) {
+    const relative = path.relative(directory, file);
+    return (relative === "" ||
+        (!relative.startsWith("..") && !path.isAbsolute(relative)));
+}
+/** Node's TypeScript parser, where this Node has one. */
+function nodeTypeScriptParser() {
+    const candidate = nodeModule.stripTypeScriptTypes;
+    return typeof candidate === "function" ? candidate : undefined;
+}
+function syntaxFindingsOf(strip, tree) {
+    const decoder = new TextDecoder("utf-8");
+    const findings = [];
+    for (const file of tree) {
+        try {
+            strip(decoder.decode(file.bytes));
+        }
+        catch (error) {
+            if (isErrorWithCode(error, "ERR_INVALID_TYPESCRIPT_SYNTAX")) {
+                findings.push(`${file.path}: ${error.message}`);
+                continue;
+            }
+            throw error;
+        }
+    }
+    return findings;
+}
+function isErrorWithCode(error, code) {
+    return error instanceof Error && error.code === code;
+}

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

@@ -0,0 +1,162 @@
+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";
+/**
+ * §15.3's last two steps as one call — emit into a temporary directory, validate
+ * it, atomically replace the generated output — and the property that makes them
+ * one: **a failed generation leaves the previous valid output intact**, byte for
+ * byte.
+ *
+ * # What it owns (architect, 2026-10-04)
+ *
+ * The output is written into `generateAt`, a directory the developer SHARES: it
+ * may hold their own files. The generator owns exactly two entries in it —
+ * `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`).
+ *
+ * - `generated/` is replaced WHOLE, never merged: a file the previous run emitted
+ *   and this one does not is gone. 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.
+ * - `AvClient.ts` is replaced only when it is absent or carries the ownership
+ *   line; otherwise the run is refused, naming it.
+ *
+ * # The order, and its one window
+ *
+ * The whole tree — `AvClient.ts` 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 staged `AvClient.ts` → `AvClient.ts`, one rename over the old file;
+ * 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 the new `generated/` out again and the previous back, so a failure at
+ * any step leaves the previous pair. 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 4, the new `generated/` sits beside the old `AvClient.ts`: the
+ *   validated `AvClient.ts` is still staged in `.aventara-ready-*`, so it is
+ *   moved in, completing the new pair 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 (M3). 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. */
+export declare class OutputWriteError extends Error {
+    readonly stage: OutputWriteStage;
+    readonly name = "OutputWriteError";
+    /**
+     * What the run said before it stopped, in the order a success returns its
+     * warnings: the emission's, the validator's, the writer's. Printed before the
+     * refusal's sentence.
+     */
+    readonly warnings: readonly string[];
+    constructor(stage: OutputWriteStage, message: string, options?: {
+        readonly cause?: unknown;
+        readonly warnings?: readonly string[];
+    });
+    /** The same refusal, with `earlier` said before the warnings it already carries. */
+    precededBy(earlier: readonly string[]): OutputWriteError;
+}
+/**
+ * Records `earlier` as said before `defect`, ahead of anything already recorded,
+ * and returns `defect` unchanged so the caller rethrows the same error.
+ */
+export declare function precedeDefect(defect: unknown, earlier: readonly string[]): unknown;
+/**
+ * What the run said before `defect` stopped it, in the order a success returns
+ * 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` (§15.2, architect 2026-10-04). Created when missing. */
+    readonly generateAt: AbsolutePath;
+    /**
+     * Content in `AvClient.ts` or `generated/` the generator did not produce, which
+     * the person running it confirmed may be overwritten or removed (architect,
+     * 2026-10-04) — 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 (Q6). */
+    readonly resolveTypeScript?: TypeScriptResolver;
+    readonly fileSystem?: OutputFileSystem;
+}
+export interface ClientOutputWritten {
+    readonly generateAt: AbsolutePath;
+    /** How deeply the tree was validated before it replaced the output (Q6). */
+    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[];
+}
+/**
+ * Writes `emission.tree` as `<generateAt>/AvClient.ts` and `<generateAt>/generated/`.
+ *
+ * @throws OutputWriteError when the write stops; the previous output is intact.
+ */
+export declare function writeClientOutput(input: ClientOutputWriteInput): Promise<ClientOutputWritten>;
+/**
+ * Lists what in `<generateAt>/AvClient.ts` 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 (architect, 2026-10-04). 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 `AvClient.ts` is not a file: no confirmation repairs that.
+ */
+export declare function findForeignOutputContent(generateAt: AbsolutePath, fileSystem?: OutputFileSystem): Promise<readonly string[]>;
+/**
+ * Whether `AvClient.ts` and `generated/` in `generateAt` hold exactly `tree` —
+ * every file byte for byte, no other file, and nothing a killed run moved aside —
+ * so that writing `tree` would change nothing (Phase 12-rest Q6: "up to date").
+ */
+export declare function ownedOutputMatches(generateAt: AbsolutePath, tree: EmittedTree): Promise<boolean>;