@ethlete/cli 3.0.0-next.26 → 3.0.0-next.28

package/src/lib/design/system/sketch/sample-mark-drift.d.ts

@@ -0,0 +1,33 @@
+import { ResolvedProduct } from '../resolve-product';
+import { Sketch } from './sketch';
+import { SketchPartLoader } from './unchanged-states';
+export declare const SAMPLE_MARK_DRIFT = "SAMPLE-MARK-DRIFT";
+type Sample = {
+    part: string;
+    id: string;
+    marks: Record<string, unknown>;
+};
+type Drawn = {
+    state: string;
+    sample: Sample;
+};
+export type SampleMarkDrift = {
+    part: string;
+    id: string;
+    first: Drawn;
+    other: Drawn;
+};
+/**
+ * Each embedded sample whose marks differ between two states of the part `definition`: renders every state and
+ * compares the marks of the instances that carry the same part and `id`, see `PartSample`. A state that fails to
+ * render is skipped.
+ */
+export declare const sampleMarkDriftsOf: (definition: unknown) => Promise<SampleMarkDrift[]>;
+export declare const sampleMarkDriftLineOf: (drift: SampleMarkDrift) => string;
+/** One `SAMPLE-MARK-DRIFT` line per sample whose marks differ between two states of a target of a live variant. */
+export declare const sampleMarkDriftLinesOf: (options: {
+    product: ResolvedProduct;
+    sketch: Sketch;
+    load: SketchPartLoader;
+}) => Promise<string[]>;
+export {};

package/src/lib/design/system/sketch/sample-mark-drift.js

@@ -0,0 +1,88 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sampleMarkDriftLinesOf = exports.sampleMarkDriftLineOf = exports.sampleMarkDriftsOf = exports.SAMPLE_MARK_DRIFT = void 0;
+const resolve_product_1 = require("../resolve-product");
+const overlay_1 = require("./overlay");
+const sketch_1 = require("./sketch");
+exports.SAMPLE_MARK_DRIFT = 'SAMPLE-MARK-DRIFT';
+const SAMPLES = Symbol.for('@ethlete/cli/design/samples');
+const isRecord = (value) => typeof value === 'object' && value !== null;
+const samplesOf = (render, props) => __awaiter(void 0, void 0, void 0, function* () {
+    const samples = [];
+    const scope = globalThis;
+    scope[SAMPLES] = (sample) => samples.push(sample);
+    try {
+        yield render(props);
+    }
+    finally {
+        delete scope[SAMPLES];
+    }
+    return samples;
+});
+const marksDifferOf = (first, other) => [...new Set([...Object.keys(first.marks), ...Object.keys(other.marks)])].filter((mark) => { var _a, _b; return JSON.stringify((_a = first.marks[mark]) !== null && _a !== void 0 ? _a : null) !== JSON.stringify((_b = other.marks[mark]) !== null && _b !== void 0 ? _b : null); });
+/**
+ * Each embedded sample whose marks differ between two states of the part `definition`: renders every state and
+ * compares the marks of the instances that carry the same part and `id`, see `PartSample`. A state that fails to
+ * render is skipped.
+ */
+const sampleMarkDriftsOf = (definition) => __awaiter(void 0, void 0, void 0, function* () {
+    if (!isRecord(definition) || typeof definition['render'] !== 'function' || !isRecord(definition['states']))
+        return [];
+    const render = definition['render'];
+    const seen = new Map();
+    const drifts = new Map();
+    for (const [state, props] of Object.entries(definition['states'])) {
+        const samples = yield samplesOf(render, props).catch(() => []);
+        for (const sample of samples) {
+            const key = `${sample.part}\n${sample.id}`;
+            const first = seen.get(key);
+            if (!first)
+                seen.set(key, { state, sample });
+            else if (!drifts.has(key) && marksDifferOf(first.sample, sample).length > 0)
+                drifts.set(key, { part: sample.part, id: sample.id, first, other: { state, sample } });
+        }
+    }
+    return [...drifts.values()];
+});
+exports.sampleMarkDriftsOf = sampleMarkDriftsOf;
+const marksOf = (sample, marks) => marks.map((mark) => { var _a; return `${mark}=${JSON.stringify((_a = sample.marks[mark]) !== null && _a !== void 0 ? _a : null)}`; }).join(' ');
+const sampleMarkDriftLineOf = (drift) => {
+    const marks = marksDifferOf(drift.first.sample, drift.other.sample);
+    return (`${drift.part} "${drift.id}" draws ${marksOf(drift.first.sample, marks)} in ${drift.first.state} but ` +
+        `${marksOf(drift.other.sample, marks)} in ${drift.other.state} - give it the same marks in every state, or ` +
+        `another id where the state shows another sample`);
+};
+exports.sampleMarkDriftLineOf = sampleMarkDriftLineOf;
+/** One `SAMPLE-MARK-DRIFT` line per sample whose marks differ between two states of a target of a live variant. */
+const sampleMarkDriftLinesOf = (options) => __awaiter(void 0, void 0, void 0, function* () {
+    var _a;
+    const { product, sketch, load } = options;
+    const lines = [];
+    for (const variant of sketch.variants.filter((entry) => !(0, sketch_1.rejectionOf)(sketch, entry))) {
+        const parts = (0, overlay_1.overlaySketch)({ product, sketch, variant }).parts;
+        for (const target of sketch.targets) {
+            const file = (_a = parts.find((entry) => (0, resolve_product_1.partKeyOf)(entry) === target)) === null || _a === void 0 ? void 0 : _a.file;
+            if (!file)
+                continue;
+            const loaded = (yield load({
+                file,
+                product: product.name,
+                sketch: { target: sketch.target, variant },
+            }).catch(() => null));
+            for (const drift of yield (0, exports.sampleMarkDriftsOf)(loaded === null || loaded === void 0 ? void 0 : loaded.default))
+                lines.push(`${exports.SAMPLE_MARK_DRIFT} ${sketch.target} ${variant} ${target}: ${(0, exports.sampleMarkDriftLineOf)(drift)}`);
+        }
+    }
+    return lines;
+});
+exports.sampleMarkDriftLinesOf = sampleMarkDriftLinesOf;
+//# sourceMappingURL=sample-mark-drift.js.map

package/src/lib/design/system/sketch/sample-mark-drift.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sample-mark-drift.js","sourceRoot":"","sources":["../../../../../../../libs/cli/src/lib/design/system/sketch/sample-mark-drift.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,wDAAgE;AAChE,uCAA0C;AAC1C,qCAA+C;AAGlC,QAAA,iBAAiB,GAAG,mBAAmB,CAAC;AAErD,MAAM,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,6BAA6B,CAAC,CAAC;AAQ1D,MAAM,QAAQ,GAAG,CAAC,KAAc,EAAoC,EAAE,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,CAAC;AAEnH,MAAM,SAAS,GAAG,CAAO,MAAmC,EAAE,KAAc,EAAqB,EAAE;IACjG,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,MAAM,KAAK,GAAG,UAAqC,CAAC;IAEpD,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,MAAc,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAE1D,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,KAAK,CAAC,CAAC;IACtB,CAAC;YAAS,CAAC;QACT,OAAO,KAAK,CAAC,OAAO,CAAC,CAAC;IACxB,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC,CAAA,CAAC;AAEF,MAAM,aAAa,GAAG,CAAC,KAAa,EAAE,KAAa,EAAE,EAAE,CACrD,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAC7E,CAAC,IAAI,EAAE,EAAE,eAAC,OAAA,IAAI,CAAC,SAAS,CAAC,MAAA,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,mCAAI,IAAI,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,MAAA,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,mCAAI,IAAI,CAAC,CAAA,EAAA,CAClG,CAAC;AAEJ;;;;GAIG;AACI,MAAM,kBAAkB,GAAG,CAAO,UAAmB,EAA8B,EAAE;IAC1F,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,OAAO,UAAU,CAAC,QAAQ,CAAC,KAAK,UAAU,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;QAAE,OAAO,EAAE,CAAC;IAEtH,MAAM,MAAM,GAAG,UAAU,CAAC,QAAQ,CAAgC,CAAC;IACnE,MAAM,IAAI,GAAG,IAAI,GAAG,EAAiB,CAAC;IACtC,MAAM,MAAM,GAAG,IAAI,GAAG,EAA2B,CAAC;IAElD,KAAK,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC;QAClE,MAAM,OAAO,GAAG,MAAM,SAAS,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,KAAK,CAAC,GAAa,EAAE,CAAC,EAAE,CAAC,CAAC;QAEzE,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;YAC7B,MAAM,GAAG,GAAG,GAAG,MAAM,CAAC,IAAI,KAAK,MAAM,CAAC,EAAE,EAAE,CAAC;YAC3C,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAE5B,IAAI,CAAC,KAAK;gBAAE,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC;iBACxC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,aAAa,CAAC,KAAK,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,MAAM,GAAG,CAAC;gBACzE,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,CAAC;QAC3F,CAAC;IACH,CAAC;IAED,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;AAC9B,CAAC,CAAA,CAAC;AArBW,QAAA,kBAAkB,sBAqB7B;AAEF,MAAM,OAAO,GAAG,CAAC,MAAc,EAAE,KAAe,EAAE,EAAE,CAClD,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,WAAC,OAAA,GAAG,IAAI,IAAI,IAAI,CAAC,SAAS,CAAC,MAAA,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,mCAAI,IAAI,CAAC,EAAE,CAAA,EAAA,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAElF,MAAM,qBAAqB,GAAG,CAAC,KAAsB,EAAE,EAAE;IAC9D,MAAM,KAAK,GAAG,aAAa,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAEpE,OAAO,CACL,GAAG,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC,EAAE,WAAW,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,OAAO,KAAK,CAAC,KAAK,CAAC,KAAK,OAAO;QACtG,GAAG,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,OAAO,KAAK,CAAC,KAAK,CAAC,KAAK,+CAA+C;QAC5G,iDAAiD,CAClD,CAAC;AACJ,CAAC,CAAC;AARW,QAAA,qBAAqB,yBAQhC;AAEF,mHAAmH;AAC5G,MAAM,sBAAsB,GAAG,CAAO,OAI5C,EAAqB,EAAE;;IACtB,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,OAAO,CAAC;IAC1C,MAAM,KAAK,GAAa,EAAE,CAAC;IAE3B,KAAK,MAAM,OAAO,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,IAAA,oBAAW,EAAC,MAAM,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC;QACrF,MAAM,KAAK,GAAG,IAAA,uBAAa,EAAC,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC;QAEhE,KAAK,MAAM,MAAM,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACpC,MAAM,IAAI,GAAG,MAAA,KAAK,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,IAAA,2BAAS,EAAC,KAAK,CAAC,KAAK,MAAM,CAAC,0CAAE,IAAI,CAAC;YAEtE,IAAI,CAAC,IAAI;gBAAE,SAAS;YAEpB,MAAM,MAAM,GAAG,CAAC,MAAM,IAAI,CAAC;gBACzB,IAAI;gBACJ,OAAO,EAAE,OAAO,CAAC,IAAI;gBACrB,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE;aAC3C,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAiC,CAAC;YAEtD,KAAK,MAAM,KAAK,IAAI,MAAM,IAAA,0BAAkB,EAAC,MAAM,aAAN,MAAM,uBAAN,MAAM,CAAE,OAAO,CAAC;gBAC3D,KAAK,CAAC,IAAI,CAAC,GAAG,yBAAiB,IAAI,MAAM,CAAC,MAAM,IAAI,OAAO,IAAI,MAAM,KAAK,IAAA,6BAAqB,EAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAC9G,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC,CAAA,CAAC;AA5BW,QAAA,sBAAsB,0BA4BjC"}

package/src/lib/design/system/sketch/sketch-check-cache.d.ts

@@ -0,0 +1,11 @@
+type CheckRequest = {
+    kind: string;
+    target: string;
+    product: string;
+};
+/**
+ * Wraps a synchronous check so it runs again only when a file or folder listing its last run for the same request
+ * read prints differently; a throwing run keeps nothing.
+ */
+export declare const cachedCheckOf: <TRequest extends CheckRequest, T>(check: (request: TRequest) => T) => (request: TRequest) => T;
+export {};

package/src/lib/design/system/sketch/sketch-check-cache.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cachedCheckOf = void 0;
+const tracked_reads_1 = require("../tracked-reads");
+/**
+ * Wraps a synchronous check so it runs again only when a file or folder listing its last run for the same request
+ * read prints differently; a throwing run keeps nothing.
+ */
+const cachedCheckOf = (check) => {
+    const entries = new Map();
+    return (request) => {
+        const key = `${request.kind}\n${request.target}\n${request.product}`;
+        const held = entries.get(key);
+        if (held && (0, tracked_reads_1.inputsUnchanged)(held.inputs))
+            return held.value;
+        const { value, inputs } = (0, tracked_reads_1.trackedRun)(() => check(request));
+        entries.set(key, { inputs, value });
+        return value;
+    };
+};
+exports.cachedCheckOf = cachedCheckOf;
+//# sourceMappingURL=sketch-check-cache.js.map

package/src/lib/design/system/sketch/sketch-check-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sketch-check-cache.js","sourceRoot":"","sources":["../../../../../../../libs/cli/src/lib/design/system/sketch/sketch-check-cache.ts"],"names":[],"mappings":";;;AAAA,oDAA6E;AAI7E;;;GAGG;AACI,MAAM,aAAa,GAAG,CAAmC,KAA+B,EAAE,EAAE;IACjG,MAAM,OAAO,GAAG,IAAI,GAAG,EAAgD,CAAC;IAExE,OAAO,CAAC,OAAiB,EAAK,EAAE;QAC9B,MAAM,GAAG,GAAG,GAAG,OAAO,CAAC,IAAI,KAAK,OAAO,CAAC,MAAM,KAAK,OAAO,CAAC,OAAO,EAAE,CAAC;QACrE,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAE9B,IAAI,IAAI,IAAI,IAAA,+BAAe,EAAC,IAAI,CAAC,MAAM,CAAC;YAAE,OAAO,IAAI,CAAC,KAAK,CAAC;QAE5D,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,IAAA,0BAAU,EAAC,GAAG,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;QAE3D,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC;QAEpC,OAAO,KAAK,CAAC;IACf,CAAC,CAAC;AACJ,CAAC,CAAC;AAfW,QAAA,aAAa,iBAexB"}

package/src/lib/design/system/sketch/sketch-check-worker.d.ts

@@ -0,0 +1 @@
+export {};

package/src/lib/design/system/sketch/sketch-check-worker.js

@@ -0,0 +1,32 @@
+"use strict";
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const worker_threads_1 = require("worker_threads");
+const sketch_check_cache_1 = require("./sketch-check-cache");
+const sketch_checker_1 = require("./sketch-checker");
+const checkOf = (0, sketch_check_cache_1.cachedCheckOf)((_a) => {
+    var { kind } = _a, request = __rest(_a, ["kind"]);
+    return kind === 'rules' ? (0, sketch_checker_1.ruleProblemsAt)(request) : (0, sketch_checker_1.openSketchListingAt)(request);
+});
+const answerOf = (_a) => {
+    var { id } = _a, request = __rest(_a, ["id"]);
+    try {
+        const listing = checkOf(request);
+        return typeof listing === 'string' ? { id, error: listing } : { id, result: listing };
+    }
+    catch (error) {
+        return { id, error: error instanceof Error ? error.message : String(error) };
+    }
+};
+worker_threads_1.parentPort === null || worker_threads_1.parentPort === void 0 ? void 0 : worker_threads_1.parentPort.on('message', (request) => worker_threads_1.parentPort === null || worker_threads_1.parentPort === void 0 ? void 0 : worker_threads_1.parentPort.postMessage(answerOf(request)));
+//# sourceMappingURL=sketch-check-worker.js.map

package/src/lib/design/system/sketch/sketch-check-worker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sketch-check-worker.js","sourceRoot":"","sources":["../../../../../../../libs/cli/src/lib/design/system/sketch/sketch-check-worker.ts"],"names":[],"mappings":";;;;;;;;;;;;;AAAA,mDAA4C;AAC5C,6DAAqD;AACrD,qDAAgH;AAEhH,MAAM,OAAO,GAAG,IAAA,kCAAa,EAAC,CAAC,EAAoD,EAAE,EAAE;QAAxD,EAAE,IAAI,OAA8C,EAAzC,OAAO,cAAlB,QAAoB,CAAF;IAC/C,OAAA,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,IAAA,+BAAc,EAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAA,oCAAmB,EAAC,OAAO,CAAC,CAAA;CAAA,CAC1E,CAAC;AAEF,MAAM,QAAQ,GAAG,CAAC,EAAsC,EAAuB,EAAE;QAA/D,EAAE,EAAE,OAAkC,EAA7B,OAAO,cAAhB,MAAkB,CAAF;IAChC,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;QAEjC,OAAO,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;IACxF,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;IAC/E,CAAC;AACH,CAAC,CAAC;AAEF,2BAAU,aAAV,2BAAU,uBAAV,2BAAU,CAAE,EAAE,CAAC,SAAS,EAAE,CAAC,OAA2B,EAAE,EAAE,CAAC,2BAAU,aAAV,2BAAU,uBAAV,2BAAU,CAAE,WAAW,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC"}

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

@@ -0,0 +1,40 @@
+import { Problem } from '../problem';
+import { OpenSketchListing } from './check-sketches';
+export type SketchCheckRequest = {
+    id: number;
+    target: string;
+    product: string;
+    kind: 'sketches' | 'rules';
+};
+export type SketchCheckResponse = {
+    id: number;
+    result?: OpenSketchListing | Problem[];
+    error?: string;
+};
+export type CheckSketches = (options: {
+    target: string;
+    product: string;
+}) => Promise<OpenSketchListing>;
+/** The problems the rules find in a product, read from the files as they are when it runs. */
+export type CheckRules = (options: {
+    target: string;
+    product: string;
+}) => Promise<Problem[]>;
+/** The rule checks of `product`'s open sketches in `target`, on this thread; a string when the product does not resolve. */
+export declare const openSketchListingAt: ({ target, product }: {
+    target: string;
+    product: string;
+}) => string | OpenSketchListing;
+/** {@link ruleProblemsOf} of `product` in `target`, on this thread; a string when the product does not resolve. */
+export declare const ruleProblemsAt: ({ target, product }: {
+    target: string;
+    product: string;
+}) => string | Problem[];
+/**
+ * Runs the rule checks of a product's open sketches in a worker, so the server keeps answering
+ * while they run. A listing asked while one for the same product runs gets that one's result.
+ */
+export declare const createSketchChecker: () => CheckSketches & {
+    rules: CheckRules;
+    close: () => Promise<void>;
+};

package/src/lib/design/system/sketch/sketch-checker.js

@@ -0,0 +1,109 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSketchChecker = exports.ruleProblemsAt = exports.openSketchListingAt = void 0;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const url_1 = require("url");
+const worker_threads_1 = require("worker_threads");
+const package_root_1 = require("../../package-root");
+const design_config_1 = require("../../design-config");
+const check_system_1 = require("../check-system");
+const check_sketches_1 = require("./check-sketches");
+const cli_args_1 = require("./cli-args");
+/** The rule checks of `product`'s open sketches in `target`, on this thread; a string when the product does not resolve. */
+const openSketchListingAt = ({ target, product }) => {
+    const config = (0, design_config_1.readConfig)(target);
+    const resolved = config ? (0, cli_args_1.oneProductOf)({ target, config, asked: product }) : 'no design config';
+    return typeof resolved === 'string' ? resolved : (0, check_sketches_1.openSketchListingOf)(resolved);
+};
+exports.openSketchListingAt = openSketchListingAt;
+/** {@link ruleProblemsOf} of `product` in `target`, on this thread; a string when the product does not resolve. */
+const ruleProblemsAt = ({ target, product }) => {
+    const config = (0, design_config_1.readConfig)(target);
+    const resolved = config ? (0, cli_args_1.oneProductOf)({ target, config, asked: product }) : 'no design config';
+    return typeof resolved === 'string' ? resolved : (0, check_system_1.ruleProblemsOf)(resolved);
+};
+exports.ruleProblemsAt = ruleProblemsAt;
+const startWorker = () => {
+    const built = (0, package_root_1.packageFileOf)((0, path_1.resolve)(__dirname, 'sketch-check-worker.js'));
+    // Specs run this file from source, where only the `.ts` worker exists.
+    return (0, fs_1.existsSync)(built)
+        ? new worker_threads_1.Worker(built)
+        : new worker_threads_1.Worker((0, path_1.resolve)(__dirname, 'sketch-check-worker.ts'), {
+            execArgv: [
+                '--import',
+                (0, url_1.pathToFileURL)((0, path_1.resolve)(require.resolve('jiti/package.json'), '../lib/jiti-register.mjs')).href,
+            ],
+        });
+};
+/**
+ * Runs the rule checks of a product's open sketches in a worker, so the server keeps answering
+ * while they run. A listing asked while one for the same product runs gets that one's result.
+ */
+const createSketchChecker = () => {
+    const pending = new Map();
+    const running = new Map();
+    let worker = null;
+    let nextId = 0;
+    const failAll = (error) => {
+        for (const [id, settle] of pending)
+            settle({ id, error });
+        pending.clear();
+        worker = null;
+    };
+    const start = () => {
+        const started = startWorker();
+        started.unref();
+        started.on('message', (response) => {
+            var _a;
+            (_a = pending.get(response.id)) === null || _a === void 0 ? void 0 : _a(response);
+            pending.delete(response.id);
+        });
+        started.on('error', (error) => {
+            if (started === worker)
+                failAll(`the sketch check worker failed: ${error.message}`);
+        });
+        started.on('exit', () => {
+            if (started === worker)
+                failAll('the sketch check worker exited before it answered');
+        });
+        return started;
+    };
+    const run = (request) => __awaiter(void 0, void 0, void 0, function* () {
+        worker !== null && worker !== void 0 ? worker : (worker = start());
+        const id = nextId++;
+        const answered = new Promise((settle) => pending.set(id, settle));
+        worker.postMessage(Object.assign(Object.assign({}, request), { id }));
+        const { result, error } = yield answered;
+        if (!result)
+            throw new Error(error !== null && error !== void 0 ? error : 'the sketch check worker answered nothing');
+        return result;
+    });
+    const check = (request) => {
+        const key = `${request.target}\n${request.product}`;
+        const known = running.get(key);
+        if (known)
+            return known;
+        const started = run(Object.assign(Object.assign({}, request), { kind: 'sketches' })).finally(() => running.delete(key));
+        running.set(key, started);
+        return started;
+    };
+    const close = () => __awaiter(void 0, void 0, void 0, function* () {
+        const stopping = worker;
+        failAll('the sketch checker closed');
+        yield (stopping === null || stopping === void 0 ? void 0 : stopping.terminate());
+    });
+    const rules = (request) => run(Object.assign(Object.assign({}, request), { kind: 'rules' }));
+    return Object.assign(check, { rules, close });
+};
+exports.createSketchChecker = createSketchChecker;
+//# sourceMappingURL=sketch-checker.js.map

package/src/lib/design/system/sketch/sketch-checker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sketch-checker.js","sourceRoot":"","sources":["../../../../../../../libs/cli/src/lib/design/system/sketch/sketch-checker.ts"],"names":[],"mappings":"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"}

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

@@ -1,23 +1,26 @@
 import { SHARED_FOLDER } from '../imports';
 import { Layer } from '../layers';
 import { ResolvedProduct } from '../resolve-product';
+import { WriteOrigin } from '../write-origin';
 export declare const SKETCH_STATUSES: readonly ["in progress", "ready"];
 export type SketchStatus = (typeof SKETCH_STATUSES)[number];
+/** A part, and `sketch` when it names one of several sketches on that part; a sketch without a name is the part's only one. */
 export type SketchTarget = {
     layer: Layer;
     name: string;
+    sketch?: string;
 };
 /** What the user decided in Studio: a variant to merge, or the whole sketch to drop. */
-export type SketchDecision = {
+export type SketchDecision = ({
     kind: 'pick';
     variant: string;
     comment?: string;
     decidedAt: string;
-} | {
+} & Partial<WriteOrigin>) | ({
     kind: 'discard';
     comment?: string;
     decidedAt: string;
-};
+} & Partial<WriteOrigin>);
 /**
  * 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.
@@ -45,6 +48,9 @@ export type SketchRejection = {
     reason?: string;
     reasonBy?: SketchVerdictBy;
     reopened?: SketchReopening;
+    /** `withdrawn`: the agent that drew the variant took it out of the open set, `withdrawnBy` is its model id. Absent on a rejection. */
+    status?: 'withdrawn';
+    withdrawnBy?: 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 = {
@@ -60,6 +66,22 @@ export type SketchHold = {
     by: string;
     heldAt: string;
 };
+/** A rebase after the merge of `merged` that could not port `parts` by itself; the sketch's agent ports `reasons` by hand. */
+export type SketchPortMark = {
+    merged: string[];
+    parts: string[];
+    reasons: string[];
+    at: string;
+};
+/**
+ * Why the last `sketch ready` run left a ready sketch unmerged; only a ready sketch keeps it. `dirty` lists the
+ * uncommitted files that refused the automatic merge; the next sketch command retries it once they are committed.
+ */
+export type SketchMergeHold = {
+    reason: string;
+    at: string;
+    dirty?: string[];
+};
 export type SketchFile = {
     target: string;
     /** Every part the sketch targets, `target` first; absent on a sketch with one target. */
@@ -78,7 +100,13 @@ export type SketchFile = {
      * `into-base`, into the base, removing the product copy the sketch started from.
      */
     merge?: SketchMerge;
+    /** The compare DIFFs this sketch covers while it is open (ADR 0222): `<state>`, or `<state>@<x>,<y>,<w>,<h>` for one region of its picture. */
+    covers?: string[];
     hold?: SketchHold;
+    /** The content hash of each variant when `sketch ready` judged it; a change drops a ready sketch back to in progress. */
+    readyContent?: Record<string, string>;
+    portAfterMerge?: SketchPortMark;
+    mergeHold?: SketchMergeHold;
 };
 export declare const SKETCH_MERGES: readonly ["override", "into-base"];
 export type SketchMerge = (typeof SKETCH_MERGES)[number];
@@ -96,6 +124,7 @@ export type Sketch = SketchFile & {
 export declare const SKETCH_FILE = "sketch.json";
 export declare const sketchesDirOf: (productDir: string) => string;
 export declare const sketchFolderOf: (target: SketchTarget) => string;
+export declare const sketchIdOf: (target: SketchTarget) => string;
 export declare const sketchDirOf: (options: {
     productDir: string;
     sketch: SketchTarget;
@@ -105,10 +134,38 @@ export { SHARED_FOLDER };
 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 SOURCE_FILE: RegExp;
 export declare const sourceFilesIn: (dir: string) => string[];
+/** `source`, the file `file` of the part in `partDir`, with its relative imports of the part's own `shared/` folder as `@shared/`. */
+export declare const withSharedImports: (options: {
+    source: string;
+    file: string;
+    partDir: string;
+}) => string;
+export declare const relativeSpecifierOf: (options: {
+    from: string;
+    to: string;
+}) => string;
+/**
+ * Rewrites the relative imports of the files in `dir`, a copy of the folder `from`, that leave `from` - and `within`,
+ * when given - so they reach the same files from `dir`.
+ */
+export declare const rebaseOutsideImports: (options: {
+    dir: string;
+    from: string;
+    within?: string;
+    settledIn?: string;
+    skip?: string;
+}) => void;
+/** Rewrites the relative imports of the part's own `shared/` folder in its files to `@shared/`. */
+export declare const rewriteSharedImports: (partDir: string) => void;
 /** Reads `<layer>/<name>` as a sketch target, or answers with why it is not one. */
 export declare const parseTarget: (value: string | undefined) => SketchTarget | string;
+/** Reads a sketch id (`<layer>/<name>[@<sketch>]`), `<layer>/<name>.<sketch>` or a sketch folder name (`<layer>-<name>[.<sketch>]`) as a sketch id, or `null` when it is none of them. */
+export declare const sketchIdOfName: (value: string) => string | null;
 export declare const isVariantName: (name: string) => boolean;
+/** Deletes a sketch folder, then its `sketches/` folder when nothing else is left in it. */
+export declare const removeSketchDir: (dir: string) => void;
 /** The round new variants join: the last one. */
 export declare const runningRoundOf: (sketch: Pick<Sketch, "rounds">) => SketchRound;
 /** The rejection that holds on a variant now, or `null` when it is live. */
@@ -127,6 +184,11 @@ export declare const listSketches: (options: {
     productDir: string;
     product: string;
 }) => (string | Sketch)[];
+/** `listSketches`, letting the server answer other requests before each sketch it reads. */
+export declare const listSketchesInTurns: (options: {
+    productDir: string;
+    product: string;
+}) => Promise<(string | Sketch)[]>;
 /** The open sketch that targets `sketch`, found by its first target or by any other it names; `null` when none does. */
 export declare const findSketch: (options: {
     productDir: string;
@@ -153,7 +215,7 @@ export declare const sketchSourceOf: (options: {
  * 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. Each of `others` joins every variant the same way, as a further target; `like` takes one target only.
+ * sketch at a time, or one per sketch name when `sketch.sketch` names it. Each of `others` joins every variant the same way, as a further target; `like` takes one target only.
  * A target the product overrides in its base needs `merge`: `override` or `into-base`.
  */
 export declare const createSketch: (options: {
@@ -178,6 +240,14 @@ export declare const addTarget: (options: {
     part: SketchTarget;
     author?: string;
 }) => Sketch | string;
+/**
+ * Removes `part` from the targets of an open sketch and deletes its folder in every variant. The first target
+ * cannot be removed.
+ */
+export declare const removeTarget: (options: {
+    sketch: Sketch;
+    part: SketchTarget;
+}) => 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;
@@ -191,7 +261,8 @@ export declare const sketchReportPath: (options: {
 }) => 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.
+ * and adds the agent's model id to the variant's authors in `sketch.json` unless it is there already. A ready sketch
+ * refuses a report unless `reopen` moves it back to in progress.
  */
 export declare const reportSketch: (options: {
     checkout: string;
@@ -199,6 +270,7 @@ export declare const reportSketch: (options: {
     variant: string;
     author: string;
     message: string;
+    reopen?: boolean;
 }) => 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 = {
@@ -231,6 +303,16 @@ export declare const markSketchReady: (options: {
     sketch: Sketch;
     author?: string;
 }) => Sketch | string;
+/** The content hash of every file a variant draws from: its folder and the `shared/` folder of the sketch. */
+export declare const variantContentHashOf: (sketch: Sketch, variant: string) => string;
+/**
+ * Moves an undecided ready sketch back to in progress when a variant changed since `sketch ready` judged it, and
+ * answers the changed variants, or `null` when nothing changed or the sketch recorded no content.
+ */
+export declare const reopenChangedReady: (sketch: Sketch) => {
+    sketch: Sketch;
+    changed: string[];
+} | null;
 /** Why a held sketch cannot be ready, or `null` when it holds nothing. */
 export declare const heldProblemOf: (sketch: Pick<Sketch, "target" | "hold">) => string | null;
 /**
@@ -264,14 +346,24 @@ export type SketchVariantVerdict = {
     reason?: string;
     by: SketchVerdictBy;
 };
-export type SketchDecisionInput = {
+export type SketchDecisionInput = ({
     kind: 'pick';
     variant: string;
     comment?: string;
-} | {
+} & WriteOrigin) | ({
     kind: 'discard';
     comment?: string;
-} | SketchVariantVerdict;
+} & WriteOrigin) | SketchVariantVerdict;
+/**
+ * Takes a variant out of the open set as `withdrawn` by the agent `by`, with `reason`; refused when `by` did not draw
+ * the variant or it is rejected already. Writes sketch.json.
+ */
+export declare const withdrawVariant: (options: {
+    sketch: Sketch;
+    variant: string;
+    by: string;
+    reason: string;
+}) => Sketch | string;
 /**
  * Records the user's pick or discard on a sketch, the decision Studio writes and the agent acts on, or a verdict on
  * one variant. A rejected variant cannot be picked; rejecting the picked variant clears the pick.