@cardanvil/frame-kit 0.5.0 → 0.6.0

package/dist/cli/studio/edit/impact.js

@@ -0,0 +1,87 @@
+import { resolveFramePath } from "./resolvePath.js";
+/** Splits a leaf path into its box-set prefix and the tail inside that set. */
+function splitTarget(target, boxSets) {
+    for (const set of boxSets) {
+        if (target.length > set.path.length &&
+            set.path.every((segment, i) => target[i] === segment)) {
+            return { set, tail: target.slice(set.path.length) };
+        }
+    }
+    return undefined;
+}
+/**
+ * Every box set that reads the same literal as `target`.
+ *
+ * Frames share geometry heavily — `frame-borderless` spreads
+ * `borderlessNormalBoxes` into most of its layouts, and
+ * `withCollectorInfoDefaults` hands one `collectorInfo` to all ten box sets of
+ * every layout. Moving such a box moves it everywhere, so the studio has to be
+ * able to say so *before* it writes, rather than surprising the author after.
+ *
+ * Identity is the exact source range: two paths are the same value only when
+ * they resolve to the same characters in the same file.
+ *
+ * The scan is per-frame. A literal exported through `/extend` and read by a
+ * different frame package is not counted here; `resolveFramePath` reports that
+ * separately by way of the file it landed in.
+ */
+export function impactOf(options) {
+    const { ctx, entryFile, exportName, boxSets, target } = options;
+    const split = splitTarget(target, boxSets);
+    if (!split) {
+        return [];
+    }
+    const anchor = resolveFramePath(ctx, entryFile, exportName, target);
+    if (!anchor.editable) {
+        return [];
+    }
+    const shared = [];
+    for (const set of boxSets) {
+        const path = [...set.path, ...split.tail];
+        if (path.length === target.length &&
+            path.every((s, i) => s === target[i])) {
+            continue; // the value being edited
+        }
+        const resolution = resolveFramePath(ctx, entryFile, exportName, path);
+        if (resolution.editable &&
+            resolution.file === anchor.file &&
+            resolution.start === anchor.start &&
+            resolution.end === anchor.end) {
+            shared.push({
+                variant: set.variant,
+                layout: set.layout,
+                boxSet: set.key,
+                path,
+            });
+        }
+    }
+    return shared;
+}
+/**
+ * Memoises impact scans for one loaded revision of a frame.
+ *
+ * The scan resolves the same tail against every box set, which for a frame
+ * like `frame-borderless` is ~100 resolutions; the inspector asks for one per
+ * field. Parses are already cached by `sourceIndex`, so this only has to stop
+ * the walk itself from repeating.
+ */
+export function createImpactCache() {
+    let cachedRevision = -1;
+    let entries = new Map();
+    return {
+        get(revision, options) {
+            if (revision !== cachedRevision) {
+                cachedRevision = revision;
+                entries = new Map();
+            }
+            const key = options.target.join(".");
+            const hit = entries.get(key);
+            if (hit) {
+                return hit;
+            }
+            const computed = impactOf(options);
+            entries.set(key, computed);
+            return computed;
+        },
+    };
+}

package/dist/cli/studio/edit/resolveModule.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Absolute path a specifier resolves to from `importer`, or `undefined`.
+ *
+ * Relative specifiers are probed on disk; bare ones go through Node's own
+ * resolver, which honours `exports` maps and pnpm's workspace links. That
+ * matters because frame packages point their exports straight at TypeScript
+ * source (`"./extend": "./src/extend.ts"`), so `@cardanvil/frame-m15/extend`
+ * resolves to a file this can actually parse.
+ */
+export declare function resolveModuleFile(specifier: string, importer: string): string | undefined;

package/dist/cli/studio/edit/resolveModule.js

@@ -0,0 +1,55 @@
+import { statSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { normalizeFile } from "./sourceIndex.js";
+/**
+ * Extensions tried for a relative import, in order.
+ *
+ * Frame packages import without extensions by convention (`./boxes`,
+ * `./base`), so a specifier names either a sibling module or a directory with
+ * a barrel. `.js` is mapped back to `.ts` for authors who write NodeNext-style
+ * specifiers.
+ */
+const CANDIDATES = [
+    (base) => `${base}.ts`,
+    (base) => `${base}.tsx`,
+    (base) => path.join(base, "index.ts"),
+    (base) => path.join(base, "index.tsx"),
+    (base) => base,
+];
+function firstExisting(base) {
+    for (const candidate of CANDIDATES) {
+        const file = candidate(base);
+        try {
+            if (statSync(file).isFile()) {
+                return normalizeFile(file);
+            }
+        }
+        catch {
+            /* not there; try the next candidate */
+        }
+    }
+    return undefined;
+}
+/**
+ * Absolute path a specifier resolves to from `importer`, or `undefined`.
+ *
+ * Relative specifiers are probed on disk; bare ones go through Node's own
+ * resolver, which honours `exports` maps and pnpm's workspace links. That
+ * matters because frame packages point their exports straight at TypeScript
+ * source (`"./extend": "./src/extend.ts"`), so `@cardanvil/frame-m15/extend`
+ * resolves to a file this can actually parse.
+ */
+export function resolveModuleFile(specifier, importer) {
+    if (specifier.startsWith(".")) {
+        const base = path.resolve(path.dirname(importer), specifier);
+        const stripped = base.replace(/\.js$/, "");
+        return firstExisting(base) ?? firstExisting(stripped);
+    }
+    try {
+        return normalizeFile(createRequire(importer).resolve(specifier));
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/cli/studio/edit/resolvePath.d.ts

@@ -0,0 +1,53 @@
+import { type FramePath } from "../../../manifest/walk.js";
+import { type SourceIndex } from "./sourceIndex.js";
+import type { TypeScriptApi } from "./ts.js";
+/** Why a value cannot be edited where it is written. */
+export type UnsupportedReason = "computed" | "helper-call" | "not-a-literal" | "outside-root" | "missing-property" | "unsupported-expression" | "no-export" | "unreadable";
+export interface SourceLocation {
+    /** Absolute, normalized. */
+    readonly file: string;
+    /** 1-based. */
+    readonly line: number;
+    /** 1-based. */
+    readonly column: number;
+}
+export interface ResolvedLiteral {
+    readonly editable: true;
+    readonly file: string;
+    /** Offsets of the literal itself, ready to splice. */
+    readonly start: number;
+    readonly end: number;
+    /** The literal exactly as written, e.g. `2446` or `-12`. */
+    readonly text: string;
+    readonly location: SourceLocation;
+    /**
+     * True when the value came from a default handed to a frame-kit helper
+     * rather than from the box set itself, so every set that omits it reads
+     * this one literal.
+     */
+    readonly sharedDefault: boolean;
+}
+export interface UnresolvedValue {
+    readonly editable: false;
+    readonly reason: UnsupportedReason;
+    /** A sentence naming the construct, for the inspector's lock tooltip. */
+    readonly detail: string;
+    /** Where the value really comes from, when that is known. */
+    readonly source?: SourceLocation;
+}
+export type Resolution = ResolvedLiteral | UnresolvedValue;
+export interface ResolveContext {
+    readonly api: TypeScriptApi;
+    readonly index: SourceIndex;
+    /** Nothing outside this directory may be reported as editable. */
+    readonly root: string;
+}
+/**
+ * Where the value at `framePath` is written in source, if it is written as a
+ * literal at all.
+ *
+ * Returns the exact text range so a caller can splice a new value in without
+ * reprinting anything — comments, formatting and import order survive because
+ * nothing else is touched.
+ */
+export declare function resolveFramePath(ctx: ResolveContext, entryFile: string, exportName: string, framePath: FramePath): Resolution;