@ethlete/cli 3.0.0-next.21 → 3.0.0-next.22

package/src/lib/design/system/sketch/sketch.d.ts

@@ -0,0 +1,221 @@
+import { Layer } from '../layers';
+import { ResolvedProduct } from '../resolve-product';
+export declare const SKETCH_STATUSES: readonly ["in progress", "ready"];
+export type SketchStatus = (typeof SKETCH_STATUSES)[number];
+export type SketchTarget = {
+    layer: Layer;
+    name: string;
+};
+/** What the user decided in Studio: a variant to merge, or the whole sketch to drop. */
+export type SketchDecision = {
+    kind: 'pick';
+    variant: string;
+    comment?: string;
+    decidedAt: string;
+} | {
+    kind: 'discard';
+    comment?: string;
+    decidedAt: string;
+};
+/**
+ * What `sketch.json` knows about one variant: the model ids that reported on it, in the order of their first report,
+ * the key of its round, and its note - what it is and what it costs - kept apart from the part's merged note.
+ */
+export type SketchVariantInfo = {
+    authors?: string[];
+    round?: string;
+    note?: string;
+};
+/** One round of variants: its title, the note on what it shows, and why its variants lost once a newer round runs. */
+export type SketchRound = {
+    key: string;
+    title: string;
+    note: string;
+    lost?: string;
+    drops?: string[];
+};
+export type SketchFile = {
+    target: string;
+    status: SketchStatus;
+    createdAt: string;
+    /** The content hash of each part and of the fixtures in the product when the sketch was created or rebased. */
+    baseline?: Record<string, string>;
+    decision?: SketchDecision;
+    variantInfo?: Record<string, SketchVariantInfo>;
+    rounds?: SketchRound[];
+};
+/** A sketch as read: `rounds` holds at least one round, and `variantInfo` names the round of every variant. */
+export type Sketch = SketchFile & {
+    rounds: SketchRound[];
+    variantInfo: Record<string, SketchVariantInfo>;
+    product: string;
+    layer: Layer;
+    name: string;
+    dir: string;
+    variants: string[];
+};
+export declare const SKETCH_FILE = "sketch.json";
+export declare const sketchesDirOf: (productDir: string) => string;
+export declare const sketchFolderOf: (target: SketchTarget) => string;
+export declare const sketchDirOf: (options: {
+    productDir: string;
+    sketch: SketchTarget;
+}) => string;
+export declare const variantDirOf: (sketch: Sketch, variant: string) => string;
+/** The folder of a sketch that holds no variant: code every variant imports as `@shared/<path>`. */
+export declare const SHARED_FOLDER = "shared";
+export declare const sharedDirOf: (sketch: Pick<Sketch, "dir">) => string;
+/** A variant's own `shared/` folder: a file there wins over the sketch's `shared/` file of the same path. */
+export declare const variantSharedDirOf: (sketch: Sketch, variant: string) => string;
+export declare const sourceFilesIn: (dir: string) => string[];
+/** Reads `<layer>/<name>` as a sketch target, or answers with why it is not one. */
+export declare const parseTarget: (value: string | undefined) => SketchTarget | string;
+export declare const isVariantName: (name: string) => boolean;
+/** The round new variants join: the last one. */
+export declare const runningRoundOf: (sketch: Pick<Sketch, "rounds">) => SketchRound;
+/** The model ids that reported on a variant, in the order of their first report; none for old data. */
+export declare const authorsOf: (sketch: Pick<Sketch, "variantInfo">, variant: string) => string[];
+/** The sketch in a sketch folder, or why it cannot be read. */
+export declare const readSketch: (options: {
+    product: string;
+    dir: string;
+}) => Sketch | string;
+/** Every sketch folder of a product, read; a folder that cannot be read answers with its problem. */
+export declare const listSketches: (options: {
+    productDir: string;
+    product: string;
+}) => (string | Sketch)[];
+export declare const findSketch: (options: {
+    productDir: string;
+    product: string;
+    sketch: SketchTarget;
+}) => string | Sketch | null;
+export declare const writeSketchFile: (sketch: Sketch) => void;
+/** Where `sketch new --like` copies from: a part folder, its part name, and the `shared/` folder of the sketch it comes from. */
+export type SketchSource = {
+    folder: string;
+    name: string;
+    shared: string | null;
+};
+/**
+ * Reads `--like`: `<layer>/<name>` is the part the product resolves under that key, `<layer>/<name>:<variant>` that
+ * part in a variant of the open sketch on it, together with the sketch's `shared/` folder.
+ */
+export declare const sketchSourceOf: (options: {
+    product: ResolvedProduct;
+    like: string;
+}) => SketchSource | string;
+/**
+ * Opens a sketch on a target, in progress, with one folder per variant, all in round 1 and with `author` as their
+ * author. Each variant starts from `like` when given - renamed to the target, without its `madeBy`, and with its
+ * sketch's `shared/` folder - else from the part the product resolves for the target, or from an empty part when the
+ * target is new. A part's own `shared/` folder becomes the sketch's, imported as `@shared/`. A target holds one open
+ * sketch at a time.
+ */
+export declare const createSketch: (options: {
+    product: ResolvedProduct;
+    sketch: SketchTarget;
+    variants: string[];
+    roundTitle?: string;
+    roundNote?: string;
+    author?: string;
+    like?: SketchSource;
+    variantNotes?: Map<string, string>;
+}) => Sketch | string;
+/** The sketch with `author` among the authors of `variant`; the same sketch when it is there already. */
+export declare const withAuthor: (options: {
+    sketch: Sketch;
+    variant: string;
+    author: string;
+}) => Sketch;
+/** Where the live report of the agent on a sketch is kept, next to the call statuses. */
+export declare const sketchReportPath: (options: {
+    checkout: string;
+    sketch: Sketch;
+}) => string;
+/**
+ * Records what an agent builds on a variant of a sketch right now ("phone, outline state"), for Studio to show,
+ * and adds the agent's model id to the variant's authors in `sketch.json` unless it is there already.
+ */
+export declare const reportSketch: (options: {
+    checkout: string;
+    sketch: Sketch;
+    variant: string;
+    author: string;
+    message: string;
+}) => Sketch | string;
+/** The live report of an agent on a sketch: its message, the variant and the model id it named. `variant` and `author` are `null` in a report written before they were recorded. */
+export type SketchReport = {
+    message: string;
+    updatedAt: string;
+    variant: string | null;
+    author: string | null;
+};
+/** The live report of the agent on a sketch, or `null` when none is running. */
+export declare const readSketchReport: (options: {
+    checkout: string;
+    sketch: Sketch;
+}) => SketchReport | null;
+export declare const clearSketchReport: (options: {
+    checkout: string;
+    sketch: Sketch;
+}) => void;
+/** Ends the live report on a sketch when it belongs to `variant`, and says whether there was one to end. */
+export declare const finishSketchReport: (options: {
+    checkout: string;
+    sketch: Sketch;
+    variant: string;
+}) => boolean;
+/**
+ * Marks an in-progress sketch ready for the user to pick, ends its live report, and records `author` on each variant
+ * that has no author yet.
+ */
+export declare const markSketchReady: (options: {
+    checkout: string;
+    sketch: Sketch;
+    author?: string;
+}) => Sketch | string;
+/** Records the user's pick or discard on a sketch, the decision Studio writes and the agent acts on. */
+export declare const decideSketch: (options: {
+    sketch: Sketch;
+    decision: {
+        kind: "pick";
+        variant: string;
+        comment?: string;
+    } | {
+        kind: "discard";
+        comment?: string;
+    };
+}) => Sketch | string;
+/**
+ * Records the product as it is now as the sketch's baseline, once the agent has brought each variant
+ * up to date with the parts that changed in the product since the sketch was created.
+ */
+export declare const rebaseSketch: (options: {
+    product: ResolvedProduct;
+    sketch: Sketch;
+}) => Sketch;
+/**
+ * Copies variant `from` into a new variant by `author`, sets the sketch back to in progress and clears a pick. A discard decision is refused.
+ * The new variant joins the running round, or starts the round `round` names, with `note` as its note, after writing
+ * `lostNote` into the running round's `lost`.
+ */
+export declare const addVariant: (options: {
+    sketch: Sketch;
+    variant: string;
+    from: string;
+    round?: {
+        title: string;
+        lostNote: string;
+        note?: string;
+    };
+    author?: string;
+}) => Sketch | string;
+/** Changes the title, the note and the dropped states of the round with key `round`; a field left out stays as it is. */
+export declare const editRound: (options: {
+    sketch: Sketch;
+    round: string;
+    title?: string;
+    note?: string;
+    drops?: string[];
+}) => Sketch | string;