@valbuild/core 0.117.0 → 0.121.0

package/dist/declarations/src/settingsModule.d.ts

@@ -0,0 +1,60 @@
+import { SerializedSchema } from "./schema/index.js";
+import { ModuleFilePath } from "./val/index.js";
+/**
+ * Where a settings module goes unless a project has a reason not to.
+ *
+ * A convention, not a rule: any module file path at the root of the content
+ * tree may hold `s.settings()` — see {@link resolveSettingsModule}.
+ */
+export declare const SETTINGS_MODULE_CONVENTION: ModuleFilePath;
+/**
+ * Whether a module file path is at the root of the content tree.
+ *
+ * `/settings.val.ts` is; `/content/settings.val.ts` is not. The settings module
+ * is the project's, not a folder's, and a project-wide setting found three
+ * directories down reads as one section's — so the position is part of what it
+ * means.
+ */
+export declare function isRootModuleFilePath(moduleFilePath: string): boolean;
+export type ResolvedSettingsModule = {
+    /**
+     * The project's settings module, if it has exactly one valid one.
+     *
+     * `null` both when there is no settings module and when what there is cannot
+     * be used (nested, or ambiguous). A caller that reads settings therefore does
+     * not have to consider the broken cases: it gets nothing, and the errors are
+     * reported by whoever is in a position to report them.
+     */
+    moduleFilePath: ModuleFilePath | null;
+    /**
+     * What is wrong with how settings are declared, ready to print.
+     *
+     * Empty in the ordinary cases — one settings module, or none. Reported as
+     * MODULE errors, each attributed to the file it is about: extraction appends
+     * them, which is what puts them in front of the reader in all three places at
+     * once — the dev server refuses to serve sources with a module error,
+     * `val validate` reports them against the file, and the Studio shows them.
+     *
+     * A duplicate produces one error per offending module, each naming all of
+     * them, so the message is there whichever of the files you happen to open.
+     */
+    errors: SettingsModuleError[];
+};
+/**
+ * Structurally an `ExtractedModuleError`, declared here rather than imported to
+ * keep `extractValModules` -> `settingsModule` a one-way dependency.
+ */
+export type SettingsModuleError = {
+    message: string;
+    path: ModuleFilePath;
+};
+/**
+ * Find the project's settings module among all its schemas.
+ *
+ * One per project, at the root: a settings module in a subdirectory is an
+ * error, and so is a second one. Both are reported rather than resolved by
+ * picking a winner — a project with two settings modules has a question to
+ * answer, and answering it by sort order means the answer changes when a file
+ * is renamed.
+ */
+export declare function resolveSettingsModule(schemas: Record<ModuleFilePath, SerializedSchema> | Record<ModuleFilePath, SerializedSchema | undefined>): ResolvedSettingsModule;

package/dist/declarations/src/source/index.d.ts

@@ -1,7 +1,8 @@
 import { JsonSource } from "./json.js";
 import { MediaSource } from "./media.js";
 import { RichTextOptions, RichTextSource } from "./richtext.js";
-export type Source = SourcePrimitive | SourceObject | SourceArray | MediaSource | JsonSource | RichTextSource<RichTextOptions>;
+import { SettingsSource } from "./settings.js";
+export type Source = SourcePrimitive | SourceObject | SourceArray | MediaSource | JsonSource | SettingsSource | RichTextSource<RichTextOptions>;
 export type SourceObject = {
     [key in string]: Source;
 } & {

package/dist/declarations/src/source/richtext.d.ts

@@ -3,71 +3,60 @@ import { RouteSchema, SerializedRouteSchema } from "../schema/route.js";
 import { StringSchema, SerializedStringSchema } from "../schema/string.js";
 import { ImageSource } from "./media.js";
 export type RichTextOptions = Partial<{
-    style: Partial<{
-        bold: boolean;
-        italic: boolean;
-        lineThrough: boolean;
-    }>;
-    block: Partial<{
-        h1: boolean;
-        h2: boolean;
-        h3: boolean;
-        h4: boolean;
-        h5: boolean;
-        h6: boolean;
-        ul: boolean;
-        ol: boolean;
-    }>;
-    inline: Partial<{
-        a: boolean | RouteSchema<string> | StringSchema<string>;
-        img: boolean | ImageSchema<ImageSource>;
-    }>;
+    bold: boolean;
+    italic: boolean;
+    lineThrough: boolean;
+    h1: boolean;
+    h2: boolean;
+    h3: boolean;
+    h4: boolean;
+    h5: boolean;
+    h6: boolean;
+    ul: boolean;
+    ol: boolean;
+    a: boolean | RouteSchema<string> | StringSchema<string>;
+    img: boolean | ImageSchema<ImageSource>;
 }>;
 export type SerializedRichTextOptions = Partial<{
-    style: Partial<{
-        bold: boolean;
-        italic: boolean;
-        lineThrough: boolean;
-    }>;
-    block: Partial<{
-        h1: boolean;
-        h2: boolean;
-        h3: boolean;
-        h4: boolean;
-        h5: boolean;
-        h6: boolean;
-        ul: boolean;
-        ol: boolean;
-    }>;
-    inline: Partial<{
-        a: boolean | SerializedRouteSchema | SerializedStringSchema;
-        img: boolean | SerializedImageSchema;
-    }>;
+    /**
+     * `.maxLength()` / `.minLength()` are not authored in the options argument,
+     * but they serialize into the same object - so the wire type has to name
+     * them, or a parser that strips unknown keys drops them in transit.
+     */
+    maxLength: number;
+    minLength: number;
+    bold: boolean;
+    italic: boolean;
+    lineThrough: boolean;
+    h1: boolean;
+    h2: boolean;
+    h3: boolean;
+    h4: boolean;
+    h5: boolean;
+    h6: boolean;
+    ul: boolean;
+    ol: boolean;
+    a: boolean | SerializedRouteSchema | SerializedStringSchema;
+    img: boolean | SerializedImageSchema;
 }>;
 export type AllRichTextOptions = {
-    style: {
-        bold: true;
-        italic: true;
-        lineThrough: true;
-    };
-    block: {
-        h1: true;
-        h2: true;
-        h3: true;
-        h4: true;
-        h5: true;
-        h6: true;
-        ul: true;
-        ol: true;
-    };
-    inline: {
-        a: true;
-        img: true;
-    };
+    bold: true;
+    italic: true;
+    lineThrough: true;
+    h1: true;
+    h2: true;
+    h3: true;
+    h4: true;
+    h5: true;
+    h6: true;
+    ul: true;
+    ol: true;
+    a: true;
+    img: true;
 };
-export type LineThrough<O extends RichTextOptions> = NonNullable<O["style"]>["lineThrough"] extends true ? "line-through" : never;
-export type Italic<O extends RichTextOptions> = NonNullable<O["style"]>["italic"] extends true ? "italic" : never;
-export type Bold<O extends RichTextOptions> = NonNullable<O["style"]>["bold"] extends true ? "bold" : never;
+export type LineThrough<O extends RichTextOptions> = O["lineThrough"] extends true ? "line-through" : never;
+export type Italic<O extends RichTextOptions> = O["italic"] extends true ? "italic" : never;
+export type Bold<O extends RichTextOptions> = O["bold"] extends true ? "bold" : never;
 export type Styles<O extends RichTextOptions> = LineThrough<O> | Italic<O> | Bold<O>;
 export type GenericRichTextSourceNode = {
     tag: string;
@@ -88,10 +77,10 @@ export type SpanNode<O extends RichTextOptions> = {
     styles: Styles<O>[];
     children: [string];
 };
-export type ImageNode<O extends RichTextOptions> = NonNullable<O["inline"]>["img"] extends true ? {
+export type ImageNode<O extends RichTextOptions> = O["img"] extends true ? {
     tag: "img";
     src: ImageSource;
-} : NonNullable<O["inline"]>["img"] extends ImageSchema<infer Src> ? Src extends ImageSource ? {
+} : O["img"] extends ImageSchema<infer Src> ? Src extends ImageSource ? {
     tag: "img";
     src: Src;
 } : never : never;
@@ -100,21 +89,22 @@ type LinkTagNode<O extends RichTextOptions> = {
     href: string;
     children: (string | SpanNode<O> | ImageNode<O> | CustomInlineNode<O>)[];
 };
-export type LinkNode<O extends RichTextOptions> = NonNullable<O["inline"]>["a"] extends true ? LinkTagNode<O> : NonNullable<O["inline"]>["a"] extends RouteSchema<string> | StringSchema<string> ? LinkTagNode<O> : never;
+export type LinkNode<O extends RichTextOptions> = O["a"] extends true ? LinkTagNode<O> : O["a"] extends RouteSchema<string> | StringSchema<string> ? LinkTagNode<O> : never;
 type ListItemTagNode<O extends RichTextOptions> = {
     tag: "li";
     children: (ParagraphNode<O> | UnorderedListNode<O> | OrderedListNode<O>)[];
 };
-export type ListItemNode<O extends RichTextOptions> = NonNullable<O["block"]>["ul"] extends true ? ListItemTagNode<O> : never | NonNullable<O["block"]>["ol"] extends true ? ListItemTagNode<O> : never;
-export type UnorderedListNode<O extends RichTextOptions> = NonNullable<O["block"]>["ul"] extends true ? {
+export type ListItemNode<O extends RichTextOptions> = O["ul"] extends true ? ListItemTagNode<O> : O["ol"] extends true ? ListItemTagNode<O> : never;
+export type UnorderedListNode<O extends RichTextOptions> = O["ul"] extends true ? {
     tag: "ul";
     children: ListItemNode<O>[];
 } : never;
-export type OrderedListNode<O extends RichTextOptions> = NonNullable<O["block"]>["ol"] extends true ? {
+export type OrderedListNode<O extends RichTextOptions> = O["ol"] extends true ? {
     tag: "ol";
     children: ListItemNode<O>[];
 } : never;
-export type HeadingTagOf<S extends keyof NonNullable<NonNullable<O["block"]>>, O extends RichTextOptions> = NonNullable<NonNullable<O["block"]>>[S] extends true ? {
+export type HeadingTag = "h1" | "h2" | "h3" | "h4" | "h5" | "h6";
+export type HeadingTagOf<S extends HeadingTag, O extends RichTextOptions> = O[S] extends true ? {
     tag: S;
     children: (string | SpanNode<O> | CustomInlineNode<O> | LinkNode<O> | BrNode | ImageNode<O>)[];
 } : never;

package/dist/declarations/src/source/settings.d.ts

@@ -0,0 +1,94 @@
+/**
+ * The source of the project's settings module — `s.settings()`.
+ *
+ * **Every key is optional, at every level, and that is the whole point.** A
+ * settings module is written as
+ *
+ * ```typescript
+ * export default c.define("/settings.val.ts", s.settings(), {});
+ * ```
+ *
+ * and `{}` has to keep validating as sections are added to it. A project that
+ * never touched the assistant's settings should not have to edit its settings
+ * file the day `locales` or `permissions` land.
+ *
+ * That is why settings is not sugar over `s.object()`: an object schema errors
+ * with `Expected key 'assistant' not found in object` for any absent key (see
+ * `ObjectSchema.executeAssert`), and `.nullable()` permits `null`, not absence.
+ * `SettingsSchema` gives absent keys the meaning "unset" instead.
+ *
+ * `null` means unset too, so the editor can clear a field it has already
+ * written without removing the key.
+ */
+export type SettingsSource = {
+    assistant?: AssistantSettingsSource;
+};
+/**
+ * The assistant: whether editors have one, and what it is told about the
+ * project on every message.
+ *
+ * `context` and `tone` are prose the model reads, not instructions Val
+ * interprets, and both are capped (see {@link ASSISTANT_SETTINGS_MAX_LENGTH}):
+ * they are prepended to every request the chat makes, so an unbounded field
+ * here is an unbounded cost on every turn.
+ */
+export type AssistantSettingsSource = {
+    /**
+     * Whether editors have an assistant in this project.
+     *
+     * Three states, not two — see {@link assistantAvailability}, which is the one
+     * place that reads them. Unset is NOT "on": it is "nobody has decided", and
+     * the Studio treats that as an offer rather than as an answer.
+     */
+    enabled?: boolean | null;
+    /**
+     * Background the model would otherwise have to guess: what this site is, who
+     * runs it, what the product does, names and spellings that matter.
+     */
+    context?: string | null;
+    /**
+     * How the model should write when it writes content — formal or playful,
+     * British or American, sentence case in headings, no exclamation marks.
+     *
+     * Named `tone` rather than `toneOfVoice` so it reads as one hint among
+     * several inside `assistant`, leaving room for siblings (`audience`,
+     * `glossary`) rather than a field that looks like it should absorb them.
+     */
+    tone?: string | null;
+};
+/**
+ * The cap on each of the assistant's prose fields, in characters.
+ *
+ * Roughly a thousand tokens each. Generous enough for a paragraph of
+ * background and a house style, small enough that the two of them together do
+ * not dominate the system prompt they are appended to.
+ */
+export declare const ASSISTANT_SETTINGS_MAX_LENGTH = 4000;
+/**
+ * Whether a project has an assistant — and the answer is not a boolean.
+ *
+ * - `"on"`: use it.
+ * - `"off"`: every trace of it goes. No button in the top bar, no row in the
+ *   quick actions, no panel, nothing sent. A project that says `false` has
+ *   decided, and the Studio does not keep offering.
+ * - `"unconfigured"`: nobody has said. The affordances are SHOWN, and asking to
+ *   use the assistant asks to turn it on first. That is the difference between
+ *   this and `"off"`, and the reason `enabled` is a tri-state: hiding an
+ *   unconfigured assistant means nobody discovers it, and quietly enabling one
+ *   means a project starts sending its content to a model because it did not
+ *   know to say no.
+ *
+ * A project with NO settings module is `"on"`. There is nowhere to record a
+ * decision, so there is nothing to prompt for and nothing to prompt INTO — the
+ * prompt writes to a settings module, and that project has none.
+ *
+ * This is the only answer to "does this project have an assistant":
+ * `config.ai.chat` is gone, and with it the chat's title, description and
+ * suggestions, which nothing replaces. The AI commit-message summariser is
+ * deliberately not part of this — `config.ai.commitMessages` stays where it is,
+ * and gets settings of its own later.
+ */
+export type AssistantAvailability = "on" | "off" | "unconfigured";
+export declare function assistantAvailability(
+/** The settings module's source, or `undefined` where the project has none. */
+settings: SettingsSource | undefined): AssistantAvailability;