The VS Code of video editing, built for agents.
TypeScript
/* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
import { randomInt } from "node:crypto";
import { readdir, readFile } from "node:fs/promises";
import { join } from "node:path";
import { IndentationText, Project, SyntaxKind } from "ts-morph";
import { ID_ATTR, INSPECT_TAG, formatSource, isCompositionTag, isLoopTag, parseSource } from "@diffusionstudio/jsx";
import { writeFileAtomic } from "./atomic";
import type { PropValue } from "@diffusionstudio/jsx";
import type {
ArrowFunction,
FunctionExpression,
JsxAttribute,
JsxElement,
JsxFragment,
JsxOpeningElement,
JsxSelfClosingElement,
Node,
SourceFile,
} from "ts-morph";
export type * from "./edit-types";
import type {
SourceContext,
SourceEdit,
SourceInsert,
SourceIteration,
SourceMove,
SourceRemove,
SourceUnroll,
SourceVariable,
WriteResult,
} from "./edit-types";
/** The opening half of a JSX element — where its attributes live. */
type JsxTag = JsxOpeningElement | JsxSelfClosingElement;
const SOURCE_FILE = /\.[jt]sx?$/;
const absolute = (dir: string, file: string): string => join(dir, ...file.split("/"));
// ---------------------------------------------------------------------------
// The numbering
/**
* Every JSX element in document order — the same sequence `./source` numbers,
* so the nth entry here is the element the nth position refers to. Walked
* rather than collected: `getDescendants` would wrap every token in the file
* to find the handful that are elements.
*/
function tags(sourceFile: SourceFile): JsxTag[] {
return tagsIn(sourceFile);
}
/** The JSX elements at and under `node`, in document order. */
function tagsIn(node: Node): JsxTag[] {
const found: JsxTag[] = [];
const visit = (candidate: Node): void => {
if (candidate.isKind(SyntaxKind.JsxSelfClosingElement)) found.push(candidate);
else if (candidate.isKind(SyntaxKind.JsxElement)) found.push(candidate.getOpeningElement());
};
visit(node);
node.forEachDescendant(visit);
return found;
}
const tagName = (tag: JsxTag): string => tag.getTagNameNode().getText();
const attributeOf = (tag: JsxTag, name: string): JsxAttribute | undefined =>
tag.getAttribute(name)?.asKind(SyntaxKind.JsxAttribute);
const idOf = (tag: JsxTag): string | undefined =>
attributeOf(tag, ID_ATTR)?.getInitializer()?.asKind(SyntaxKind.StringLiteral)?.getLiteralValue();
/**
* Ids live in text, which can be copied, so two elements can end up claiming
* one. An ambiguous id resolves to nothing and the write is reported instead.
*/
function findTag(sourceFile: SourceFile, locator: number | string): JsxTag | undefined {
const all = tags(sourceFile);
if (typeof locator === "number") return all[locator];
const matches = all.filter((tag) => idOf(tag) === locator);
return matches.length === 1 ? matches[0] : undefined;
}
const idsIn = (sourceFile: SourceFile): Set<string> =>
new Set(tags(sourceFile).flatMap((tag) => idOf(tag) ?? []));
const ID_LENGTH = 6;
const ID_SPACE = 36 ** ID_LENGTH;
/**
* Ids only need to be unique within their file, so a fresh one is simply
* drawn until it misses everything already taken.
*/
function idAllocator(taken: Set<string>): () => string {
return () => {
while (true) {
const id = randomInt(ID_SPACE).toString(36).padStart(ID_LENGTH, "0");
if (taken.has(id)) continue;
taken.add(id);
return id;
}
};
}
// ---------------------------------------------------------------------------
// Values
const round = (value: number): number => Math.round(value * 100) / 100;
const IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
/** A prop value as the JavaScript that would have produced it. */
function literalText(value: PropValue): string {
if (typeof value === "string") return JSON.stringify(value);
if (typeof value === "number") return String(round(value));
if (typeof value === "boolean" || value === null) return String(value);
if (Array.isArray(value)) return `[${value.map(literalText).join(", ")}]`;
const entries = Object.entries(value).map(
([key, nested]) => `${IDENTIFIER.test(key) ? key : JSON.stringify(key)}: ${literalText(nested)}`,
);
return entries.length ? `{ ${entries.join(", ")} }` : "{}";
}
/**
* What a quoted JSX attribute cannot carry as itself: the quote that would end
* it, the `&` that would start an entity, and the control characters that have
* no spelling there — an attribute string is raw text, not JavaScript, so a
* backslash escapes nothing.
*/
const UNQUOTABLE = /["&\p{Cc}\u2028\u2029]/u;
/**
* A prop value as it appears after `=` in a JSX attribute. Strings are written
* the way they are read — `fill="#ff0000"` — and fall back to an expression,
* where JavaScript's escapes are available again, when they cannot be.
*/
const initializerText = (value: PropValue): string =>
typeof value === "string" && !UNQUOTABLE.test(value)
? `"${value}"`
: `{${literalText(value)}}`;
/**
* Writes a prop onto a tag as one would write it: `muted`, not `muted={true}`,
* and no attribute at all rather than `muted={false}`, since absence is what a
* boolean prop's false reads as.
*/
function setProp(tag: JsxTag, name: string, value: PropValue): void {
const attribute = attributeOf(tag, name);
if (value === true) {
if (attribute) attribute.removeInitializer();
else tag.addAttribute({ name });
return;
}
if (value === false) {
attribute?.remove();
return;
}
if (attribute) attribute.setInitializer(initializerText(value));
else tag.addAttribute({ name, initializer: initializerText(value) });
}
/**
* Text content as JSX spells it: bare when JSX would read it back verbatim,
* otherwise as a string expression (JSX collapses whitespace around line
* breaks and reads `{`, `}`, `<`, `>`, `&` as syntax).
*/
function jsxText(text: string): string {
return /^[^\s{}<>&][^\n{}<>&]*[^\s{}<>&]$|^[^\s{}<>&]$/.test(text) ? text : `{${JSON.stringify(text)}}`;
}
/**
* Replaces what an element says between its tags; a self-closing one is opened
* up around the new text. Only the text is replaced: the elements it holds
* besides (its paint, a stroke, a range) stay, and so does everything outside
* the body, so an element that says something else is otherwise the element
* it was.
*/
function setText(sourceFile: SourceFile, tag: JsxTag, text: string): void {
const element = elementOf(tag);
const content = text ? jsxText(text) : "";
if (element.isKind(SyntaxKind.JsxSelfClosingElement)) {
const opening = element.getText().replace(/\s*\/>$/, ">");
sourceFile.replaceText([element.getStart(), element.getEnd()], `${opening}${content}</${tagName(tag)}>`);
return;
}
const ranges = element.getJsxChildren().filter(isSaid).map(saidRange);
// Nothing said yet: it is said first, the way an insert spells it.
if (!ranges.length) {
if (content) sourceFile.insertText(element.getOpeningElement().getEnd(), content);
return;
}
// The first part says all of it and the rest say nothing. Later parts go
// first, so the positions of the earlier ones still hold.
for (const range of ranges.slice(1).reverse()) sourceFile.replaceText(range, "");
sourceFile.replaceText(ranges[0]!, content);
}
/**
* Whether a child of an element is part of what it says: text JSX keeps, or
* an expression with no element in it. A comment (an expression with nothing
* in it) says nothing.
*/
function isSaid(child: Node): boolean {
if (child.isKind(SyntaxKind.JsxText)) return !child.containsOnlyTriviaWhiteSpaces();
const expression = child.asKind(SyntaxKind.JsxExpression)?.getExpression();
if (!expression) return false;
return !JSX_KINDS.some((kind) => expression.isKind(kind) || expression.getFirstDescendantByKind(kind));
}
const JSX_KINDS = [SyntaxKind.JsxElement, SyntaxKind.JsxSelfClosingElement, SyntaxKind.JsxFragment] as const;
/**
* Where a part of what an element says is spelled. For text, that is without
* the whitespace JSX drops around line breaks: the layout of the body is the
* file's, not the text's.
*/
function saidRange(child: Node): [number, number] {
if (!child.isKind(SyntaxKind.JsxText)) return [child.getStart(), child.getEnd()];
const raw = child.getFullText();
const leading = /^[ \t]*\n\s*/.exec(raw)?.[0].length ?? 0;
const trailing = /\s*\n[ \t]*$/.exec(raw)?.[0].length ?? 0;
return [child.getPos() + leading, child.getEnd() - trailing];
}
// ---------------------------------------------------------------------------
// Layout
/**
* ts-morph measures indentation in units of its `indentationText` setting and
* does not learn a file's from the file, so before it is asked about one the
* setting is matched to what the file's first indented line uses (two spaces
* when there is none to learn from).
*/
function matchIndentation(sourceFile: SourceFile): void {
const lead = /^([ \t]+)\S/m.exec(sourceFile.getFullText())?.[1] ?? "";
const indentationText = lead.startsWith("\t")
? IndentationText.Tab
: lead.length >= 8
? IndentationText.EightSpaces
: lead.length >= 4
? IndentationText.FourSpaces
: IndentationText.TwoSpaces;
sourceFile.getProject().manipulationSettings.set({ indentationText });
}
/** The whole element a tag opens — the tag itself when it is self-closing. */
const elementOf = (tag: JsxTag): JsxElement | JsxSelfClosingElement =>
tag.isKind(SyntaxKind.JsxOpeningElement) ? tag.getParentIfKindOrThrow(SyntaxKind.JsxElement) : tag;
// ---------------------------------------------------------------------------
// Loops
type JsxBody = JsxElement | JsxSelfClosingElement | JsxFragment;
type LoopCallback = ArrowFunction | FunctionExpression;
const isLoopElement = (node: Node): node is JsxElement =>
node.isKind(SyntaxKind.JsxElement) && isLoopTag(tagName(node.getOpeningElement()));
/**
* The nearest `<For>`/`<Index>` an element sits in the body of, if any. An
* element there is rendered once per item, so a write to it — a prop, a child,
* a move, a cut — would reach every iteration at once; the writer refuses
* those, and unrolls the loop instead when asked to (see `SourceUnroll`).
*/
const loopOf = (element: Node): JsxElement | undefined => element.getAncestors().find(isLoopElement);
const inLoop = (tag: JsxTag): boolean => loopOf(elementOf(tag)) !== undefined;
const isBlankText = (node: Node): boolean =>
node.isKind(SyntaxKind.JsxText) && node.containsOnlyTriviaWhiteSpaces();
/**
* What a loop renders per item: the JSX its callback returns, when the
* callback is written out and returns nothing but JSX. Anything else — a
* reference to a function declared elsewhere, a body with statements of its
* own — computes its element in a way the source cannot be asked to spell out.
*/
function loopBody(loop: JsxElement): { callback: LoopCallback; body: JsxBody } | undefined {
const children = loop.getJsxChildren().filter((child) => !isBlankText(child));
if (children.length !== 1) return undefined;
const expression = children[0]!.asKind(SyntaxKind.JsxExpression)?.getExpression();
const callback = expression?.asKind(SyntaxKind.ArrowFunction) ?? expression?.asKind(SyntaxKind.FunctionExpression);
if (!callback) return undefined;
let returned: Node | undefined = callback.getBody();
if (returned.isKind(SyntaxKind.Block)) {
const statements = returned.getStatements();
if (statements.length !== 1) return undefined;
returned = statements[0]!.asKind(SyntaxKind.ReturnStatement)?.getExpression();
}
while (returned?.isKind(SyntaxKind.ParenthesizedExpression)) returned = returned.getExpression();
const body =
returned?.asKind(SyntaxKind.JsxElement) ??
returned?.asKind(SyntaxKind.JsxSelfClosingElement) ??
returned?.asKind(SyntaxKind.JsxFragment);
return body === undefined ? undefined : { callback, body };
}
/**
* The names a loop's callback binds — the item, the index, whatever it
* destructured (over-approximated: every identifier in the parameter list).
* These are what an unrolled copy no longer has a value for.
*/
function boundNames(callback: LoopCallback): Set<string> {
const names = new Set<string>();
for (const parameter of callback.getParameters()) {
const name = parameter.getNameNode();
if (name.isKind(SyntaxKind.Identifier)) names.add(name.getText());
for (const identifier of name.getDescendantsOfKind(SyntaxKind.Identifier)) names.add(identifier.getText());
}
return names;
}
/** Whether an attribute's value mentions any of `names`. */
function mentions(attribute: JsxAttribute, names: Set<string>): boolean {
const initializer = attribute.getInitializer();
if (!initializer) return false;
if (initializer.isKind(SyntaxKind.Identifier) && names.has(initializer.getText())) return true;
return initializer.getDescendantsOfKind(SyntaxKind.Identifier).some((identifier) => names.has(identifier.getText()));
}
const isTextTag = (tag: JsxTag): boolean => {
const name = tagName(tag);
return name === "text" || name === "Text";
};
/**
* Puts `child` (element text) under `parent`, in front of `before` (a direct
* child of it) or last. ts-morph has no operation for either without
* re-printing the parent's body, so these are text edits at positions it
* supplies; the child takes the indentation of its new neighbours and
* everything else in the file keeps its bytes.
*/
function insertChild(sourceFile: SourceFile, parent: JsxTag, child: string, before?: JsxTag): void {
matchIndentation(sourceFile);
const element = elementOf(parent);
const indent = element.getIndentationText();
const childIndent = element.getChildIndentationText();
// A self-closing parent is opened up around the child.
if (element.isKind(SyntaxKind.JsxSelfClosingElement)) {
const opening = element.getText().replace(/\s*\/>$/, ">");
sourceFile.replaceText(
[element.getStart(), element.getEnd()],
`${opening}\n${childIndent}${child}\n${indent}</${tagName(parent)}>`,
);
return;
}
if (before) {
const anchor = elementOf(before);
if (anchor.isFirstNodeOnLine()) sourceFile.insertText(anchor.getStartLinePos(), `${anchor.getIndentationText()}${child}\n`);
else sourceFile.insertText(anchor.getStart(), `${child} `);
return;
}
const closing = element.getClosingElement();
if (closing.isFirstNodeOnLine()) sourceFile.insertText(closing.getStartLinePos(), `${childIndent}${child}\n`);
else sourceFile.insertText(closing.getStart(), `\n${childIndent}${child}\n${indent}`);
}
/**
* Takes an element out of the tree, and the line it stood on when it had one
* to itself, so what is left reads as if it had never been there.
*/
function cutElement(sourceFile: SourceFile, element: JsxElement | JsxSelfClosingElement): void {
let start = element.getStart();
let end = element.getEnd();
if (element.isFirstNodeOnLine()) {
const rest = sourceFile.getFullText().slice(end);
const breakAt = rest.indexOf("\n");
const trailing = breakAt === -1 ? rest : rest.slice(0, breakAt + 1);
if (!trailing.trim()) {
start = element.getStartLinePos();
end += trailing.length;
}
}
sourceFile.removeText(start, end);
}
/**
* An element's text at a new indentation level. Every line after the first
* moves by the same amount, so the block keeps the shape its author gave it;
* a line indented less than the element itself is left where it is.
*/
function reindent(text: string, from: string, to: string): string {
if (from === to) return text;
return text
.split("\n")
.map((line, index) => (index === 0 || !line.startsWith(from) ? line : `${to}${line.slice(from.length)}`))
.join("\n");
}
/** Whether an expression is a value rather than a way of computing one. */
function isLiteral(node: Node): boolean {
if (
node.isKind(SyntaxKind.StringLiteral) ||
node.isKind(SyntaxKind.NumericLiteral) ||
node.isKind(SyntaxKind.TrueKeyword) ||
node.isKind(SyntaxKind.FalseKeyword) ||
node.isKind(SyntaxKind.NullKeyword)
) {
return true;
}
if (node.isKind(SyntaxKind.PrefixUnaryExpression)) {
const operator = node.getOperatorToken();
const signed = operator === SyntaxKind.MinusToken || operator === SyntaxKind.PlusToken;
return signed && isLiteral(node.getOperand());
}
if (node.isKind(SyntaxKind.ArrayLiteralExpression)) {
return node.getElements().every(isLiteral);
}
if (node.isKind(SyntaxKind.ObjectLiteralExpression)) {
return node.getProperties().every((property) => {
const assignment = property.asKind(SyntaxKind.PropertyAssignment);
if (!assignment || assignment.getNameNode().isKind(SyntaxKind.ComputedPropertyName)) return false;
const initializer = assignment.getInitializer();
return initializer !== undefined && isLiteral(initializer);
});
}
return false;
}
// ---------------------------------------------------------------------------
// Files
/** Every project source file, project-relative and `/`-separated. */
export async function sourceFiles(dir: string, prefix = ""): Promise<string[]> {
let entries;
try {
entries = await readdir(prefix ? join(dir, ...prefix.split("/")) : dir, { withFileTypes: true });
} catch {
return [];
}
const files: string[] = [];
for (const entry of entries) {
if (entry.name.startsWith(".") || entry.name === "node_modules") continue;
const path = prefix ? `${prefix}/${entry.name}` : entry.name;
if (entry.isDirectory()) files.push(...(await sourceFiles(dir, path)));
else if (SOURCE_FILE.test(entry.name)) files.push(path);
}
return files;
}
/** A file as it was read, alongside the tree edits are made against. */
interface OpenFile {
sourceFile: SourceFile;
text: string;
}
/** What one file's edits came to. */
interface FileWrite {
skipped: string[];
ids: Record<string, string>;
unrolled: string[];
}
/** How an edit is named in `WriteResult.skipped`: its source, or the variable's `file:name`. */
export const editLabel = (edit: SourceEdit): string =>
edit.kind === "variable" ? formatSource(edit.file, edit.name) : edit.source;
/**
* The element a source names, resolved through the names this write has
* already handed out: an insert answers with a real source, and anything
* addressed by the pending one from then on means the new element.
*/
function locate(
source: string,
ids: Record<string, string>,
): { file: string; locator: number | string } | undefined {
return parseSource(ids[source] ?? source);
}
/**
* One write against a project's sources. ts-morph parses into a file system of
* its own: bytes come off disk and go back to it here, and every file a write
* touches is read once, edited in place, and saved at the end.
*
* One instance is one operation — construct it, run it, discard it. That is
* what keeps a later write from editing a tree parsed before the project
* changed underneath it.
*/
class SourceWriter {
// Nothing here asks a question about types, so the standard library is never
// loaded: parsing it costs more than everything else this class does.
private readonly project = new Project({
useInMemoryFileSystem: true,
skipLoadingLibFiles: true,
});
private readonly files = new Map<string, OpenFile>();
private readonly context: SourceContext;
public constructor(context: SourceContext) {
this.context = context;
}
/** Reads a file into the project, or does nothing if it cannot be read. */
private async load(path: string): Promise<void> {
if (this.files.has(path)) return;
let text: string;
try {
text = await readFile(absolute(this.context.dir, path), "utf8");
} catch {
return;
}
// Created under the name it has in the project, so the extension still
// decides the dialect: in `.ts`, `<T>value` is a type assertion rather
// than an element.
const sourceFile = this.project.createSourceFile(`/${path}`, text, { overwrite: true });
this.files.set(path, { sourceFile, text });
}
/**
* Drops every file the parser had to guess at, since re-printing one would
* hand back source no one wrote — a file mid-edit is not a file to write to.
*
* Checked in one pass because ts-morph builds a program to answer for a
* file, and that program is rebuilt every time another file arrives or one
* is edited: asking per file would cost a program per file.
*/
private dropUnparsed(paths: Iterable<string> = this.files.keys()): void {
const program = this.project.getProgram();
for (const path of [...paths]) {
const open = this.files.get(path);
if (!open) continue;
if (program.getSyntacticDiagnostics(open.sourceFile).length) this.discard(path);
}
}
/** Drops a file from the write set, leaving what is on disk untouched. */
private discard(path: string): void {
const open = this.files.get(path);
if (!open) return;
this.files.delete(path);
this.project.removeSourceFile(open.sourceFile);
}
/** Writes back the files an edit actually changed, and only those. */
private async save(): Promise<void> {
for (const [path, open] of this.files) {
const text = open.sourceFile.getFullText();
if (text === open.text) continue;
open.text = text;
// Claimed before the write lands: a watcher must never see this change
// arrive without knowing whose it was, and what says whose it is are the
// bytes themselves — so they go with the claim. Written whole, because
// the same watcher reads the file straight back.
this.context.onWrite?.(path, text);
await writeFileAtomic(absolute(this.context.dir, path), text);
}
}
/**
* Names every composition element in the project, so identity does not have
* to be earned one write at a time: without an id, an element is only a
* position, and any edit that adds an element above it moves it. Idempotent —
* a project where nothing is missing an id is not written to, which is what
* makes this safe to run before every compile.
*/
public async stampProject(paths: string[]): Promise<void> {
for (const path of paths) await this.load(path);
this.dropUnparsed();
for (const path of [...this.files.keys()]) this.stampFile(path);
// Nothing ts-morph will not vouch for reaches the disk.
this.dropUnparsed();
await this.save();
}
private stampFile(path: string): void {
const sourceFile = this.files.get(path)!.sourceFile;
const nextId = idAllocator(idsIn(sourceFile));
// Every id in one manipulation: each tag says where its own name goes —
// after the attributes it already has — and the file is reparsed once
// rather than once per element.
const changes = tags(sourceFile).flatMap((tag) => {
if (!isCompositionTag(tagName(tag)) || idOf(tag)) return [];
const at = (tag.getAttributes().at(-1) ?? tag.getTagNameNode()).getEnd();
return [{ span: { start: at, length: 0 }, newText: ` ${ID_ATTR}="${nextId()}"` }];
});
if (!changes.length) return;
try {
sourceFile.applyTextChanges(changes);
} catch {
this.discard(path);
}
}
/**
* Writes prop values back into the JSX that produced them, over whatever
* was there — a literal or an expression. An element that is written to and
* has no id gets one, so that the next edit to renumber the file cannot
* strand it.
*/
public async applyEdits(edits: SourceEdit[]): Promise<WriteResult> {
const skipped: string[] = [];
const ids: Record<string, string> = {};
const unrolled: string[] = [];
// Grouped by file: one parse and one write per file, however many elements
// of it an edit touched. An insert lives in its parent's file, and a
// pending source in the file of the insert (or the unroll) that made it;
// edits arrive in the order they were made, so a parent is filed before
// its children.
const fileOf = new Map<string, string>();
const byFile = new Map<string, SourceEdit[]>();
for (const edit of edits) {
let file: string | undefined;
if (edit.kind === "variable") {
// A variable names its file itself; nothing about it is pending.
file = edit.file;
} else {
const address = edit.kind === "insert" ? edit.parent : edit.source;
file = parseSource(address)?.file ?? fileOf.get(address);
}
if (!file) {
skipped.push(editLabel(edit));
continue;
}
if (edit.kind === "insert") fileOf.set(edit.source, file);
if (edit.kind === "unroll") {
for (const iteration of edit.iterations) {
for (const { pending } of Object.values(iteration)) {
if (pending) fileOf.set(pending, file);
}
}
}
byFile.set(file, [...(byFile.get(file) ?? []), edit]);
}
for (const file of byFile.keys()) await this.load(file);
this.dropUnparsed(byFile.keys());
for (const [file, entries] of byFile) {
const sourceFile = this.files.get(file)?.sourceFile;
const written = sourceFile ? this.editFile(file, sourceFile, entries) : undefined;
// All or nothing per file: a file whose tree an edit left in a state
// ts-morph will not vouch for is dropped rather than half written.
if (!written) {
this.discard(file);
skipped.push(...entries.map(editLabel));
continue;
}
skipped.push(...written.skipped);
Object.assign(ids, written.ids);
unrolled.push(...written.unrolled);
}
await this.save();
return {
skipped,
...(Object.keys(ids).length ? { ids } : {}),
...(unrolled.length ? { unrolled } : {}),
};
}
/**
* One file's worth of edits, applied to the tree: the ids it handed out and
* the sources it would not write, or undefined if the file is to be left
* alone entirely.
*/
private editFile(file: string, sourceFile: SourceFile, entries: SourceEdit[]): FileWrite | undefined {
const nextId = idAllocator(idsIn(sourceFile));
const skipped: string[] = [];
const ids: Record<string, string> = {};
const unrolled: string[] = [];
try {
for (const edit of entries) {
if (edit.kind === "variable") {
if (!this.setVariable(sourceFile, edit)) skipped.push(`${editLabel(edit)} (variable)`);
continue;
}
if (edit.kind === "insert") {
if (!this.insertElement(file, sourceFile, edit, ids, nextId)) skipped.push(edit.source);
continue;
}
if (edit.kind === "move") {
if (!this.moveElement(file, sourceFile, edit, ids, nextId)) skipped.push(edit.source);
continue;
}
if (edit.kind === "remove") {
if (!this.removeElement(file, sourceFile, edit, ids)) skipped.push(edit.source);
continue;
}
if (edit.kind === "unroll") {
if (this.unrollLoop(file, sourceFile, edit, ids, nextId)) unrolled.push(edit.source);
else skipped.push(`${edit.source} (loop)`);
continue;
}
const locator = locate(edit.source, ids)?.locator;
if (locator === undefined) {
skipped.push(edit.source);
continue;
}
let wrote = false;
for (const [name, value] of Object.entries(edit.props)) {
// Re-resolved per prop: editing one attribute forgets its siblings.
const tag = findTag(sourceFile, locator);
if (!tag) {
skipped.push(edit.source);
break;
}
// One element of a loop cannot take a value the others do not:
// the loop has to be unrolled first (and would have been, in this
// same write, had the canvas been able to spell it out).
if (inLoop(tag)) {
skipped.push(`${edit.source} (loop)`);
break;
}
// Whatever the source held for it: the user wins. An expression
// there (`x={MARGIN}`) is replaced by the value like a literal is —
// the canvas already shows the edit, and an export and the next open
// render the file, so a prop left as it was would move back.
setProp(tag, name, value);
wrote = true;
}
// What the element says, after its props: same rules as a prop, and
// only a `<text>` has anything to say.
if (edit.text !== undefined) {
const tag = findTag(sourceFile, locator);
if (!tag) skipped.push(edit.source);
else if (inLoop(tag)) skipped.push(`${edit.source} (loop)`);
else if (!isTextTag(tag)) skipped.push(`${edit.source} (text)`);
else {
setText(sourceFile, tag, edit.text);
wrote = true;
}
}
// Named only once something was written: failing to write to an
// element is no reason to touch the file.
const tag = wrote ? findTag(sourceFile, locator) : undefined;
if (!tag || idOf(tag)) continue;
const id = nextId();
tag.addAttribute({ name: ID_ATTR, initializer: `"${id}"` });
ids[edit.source] = formatSource(file, id);
}
} catch {
return undefined;
}
// The tree an edit leaves behind answers for itself before it is printed.
this.dropUnparsed([file]);
return this.files.has(file) ? { skipped, ids, unrolled } : undefined;
}
/**
* Overwrites the initializer of an `@inspect`-annotated top-level const.
* False when no top-level const of that name carries the annotation, or when
* its initializer is not a literal anymore: the annotation promises the
* inspector a value, and an expression there is no longer one.
*/
private setVariable(sourceFile: SourceFile, edit: SourceVariable): boolean {
for (const statement of sourceFile.getVariableStatements()) {
const declaration = statement.getDeclarations().find((candidate) => candidate.getName() === edit.name);
if (!declaration) continue;
// The same leniency the compile step reads with: any leading comment
// carrying the tag at the start of a line (past the comment markers).
const annotated = statement.getLeadingCommentRanges().some((range) =>
new RegExp(`(?:^|\\n)[\\s/*]*@${INSPECT_TAG}\\b`).test(range.getText()),
);
if (!annotated) continue;
const initializer = declaration.getInitializer();
if (!initializer || !isLiteral(initializer)) return false;
declaration.setInitializer(literalText(edit.value));
return true;
}
return false;
}
/**
* Adds one element to the tree, named on the spot: the canvas is already
* showing it and will address it by that name with its next edit, so it
* cannot wait for a write to earn one. False when the parent (or the anchor)
* is not an element this file can be asked to hold a child under.
*/
private insertElement(
file: string,
sourceFile: SourceFile,
edit: SourceInsert,
ids: Record<string, string>,
nextId: () => string,
): boolean {
if (!isCompositionTag(edit.tag)) return false;
const parentLocator = locate(edit.parent, ids)?.locator;
const parent = parentLocator === undefined ? undefined : findTag(sourceFile, parentLocator);
// A child of a looped element would be a child of every iteration's.
if (!parent || inLoop(parent)) return false;
let before: JsxTag | undefined;
if (edit.before !== undefined) {
const anchorLocator = locate(edit.before, ids)?.locator;
before = anchorLocator === undefined ? undefined : findTag(sourceFile, anchorLocator);
// "In front of" only means something for a child of the same parent.
if (!before || elementOf(before).getParent() !== elementOf(parent)) return false;
}
// Placed bare and named, then given its props the way any element is:
// one attribute at a time, re-found by name after each (editing one
// attribute forgets its siblings).
const id = nextId();
const opening = `<${edit.tag} ${ID_ATTR}="${id}"`;
const child = edit.text === undefined ? `${opening} />` : `${opening}>${jsxText(edit.text)}</${edit.tag}>`;
insertChild(sourceFile, parent, child, before);
for (const [name, value] of Object.entries(edit.props)) {
setProp(findTag(sourceFile, id)!, name, value);
}
ids[edit.source] = formatSource(file, id);
return true;
}
/**
* Moves one element to another parent: its text is cut from where it stands
* and put back under the new one. False when either end is not an element of
* this file, or when the move is one no tree can hold (an element into
* itself or into its own subtree).
*
* Everything is addressed by id first, since cutting the text renumbers the
* positions the sources of an unnamed element would otherwise rely on.
*/
private moveElement(
file: string,
sourceFile: SourceFile,
edit: SourceMove,
ids: Record<string, string>,
nextId: () => string,
): boolean {
const named = (source: string): string | undefined => {
const address = locate(source, ids);
// Ids are allocated per file, so one from elsewhere could name an
// element here that has nothing to do with it.
const locator = address?.file === file ? address.locator : undefined;
const tag = locator === undefined ? undefined : findTag(sourceFile, locator);
// Nothing in a loop moves, or is moved into: it is every iteration's.
if (!tag || inLoop(tag)) return undefined;
const id = idOf(tag);
if (id) return id;
const minted = nextId();
tag.addAttribute({ name: ID_ATTR, initializer: `"${minted}"` });
// The write answers with it: the canvas addresses this element by
// position until it hears otherwise, and the move invalidates that.
ids[source] = formatSource(file, minted);
return minted;
};
// Named before anything is cut, and each stamp re-parses, so the tags are
// re-found from the ids afterwards rather than held across the edits.
const id = named(edit.source);
const parentId = named(edit.parent);
if (!id || !parentId || id === parentId) return false;
const beforeId = edit.before === undefined ? undefined : named(edit.before);
if (edit.before !== undefined && !beforeId) return false;
const element = elementOf(findTag(sourceFile, id)!);
const parentElement = elementOf(findTag(sourceFile, parentId)!);
if (parentElement.getAncestors().includes(element)) return false;
if (beforeId !== undefined) {
const anchor = elementOf(findTag(sourceFile, beforeId)!);
if (anchor.getParent() !== parentElement) return false;
}
// Before any indentation is measured: ts-morph counts it in units of a
// setting it does not learn from the file on its own.
matchIndentation(sourceFile);
const text = element.getText();
const indent = element.getIndentationText();
cutElement(sourceFile, element);
const parent = findTag(sourceFile, parentId);
const before = beforeId === undefined ? undefined : findTag(sourceFile, beforeId);
// Neither can have gone with the cut (a destination inside what is being
// moved was refused above), and the element is out of the tree by now, so
// this is the file dropping out of the write rather than a skipped edit.
if (!parent || (beforeId !== undefined && !before)) throw new Error("the element's new parent is gone");
insertChild(sourceFile, parent, reindent(text, indent, elementOf(parent).getChildIndentationText()), before);
return true;
}
/**
* Cuts one element, subtree and all, out of the tree. False when the source
* does not name an element of this file — including one already gone: a
* remove of what a remove in this same write took along with its parent
* finds nothing, and that is not a failure of the file.
*/
private removeElement(
file: string,
sourceFile: SourceFile,
edit: SourceRemove,
ids: Record<string, string>,
): boolean {
const address = locate(edit.source, ids);
const locator = address?.file === file ? address.locator : undefined;
const tag = locator === undefined ? undefined : findTag(sourceFile, locator);
// Cutting a looped element would cut it from every iteration.
if (!tag || inLoop(tag)) return false;
matchIndentation(sourceFile);
cutElement(sourceFile, elementOf(tag));
return true;
}
/**
* Replaces the loop around one element with its iterations written out.
* The body — the JSX the loop's callback returns — is copied once per
* iteration, keeping the author's layout; then each copy's elements take
* the props that iteration rendered, spelled as literals, and lose the
* spreads those props came from. The first copy keeps the body's ids, the
* rest are named afresh and answered for in `ids`.
*
* False when the loop is not one the source can be asked to spell out: no
* loop around the element, a loop within a loop, a callback that computes
* rather than returns JSX, a body with anything but composition elements in
* it (a component's props are its own, and control flow renders on its own
* terms), an attribute that leans on the item and that the canvas did not
* report a value for, or an iteration the canvas knows less about than the
* body asks.
*/
private unrollLoop(
file: string,
sourceFile: SourceFile,
edit: SourceUnroll,
ids: Record<string, string>,
nextId: () => string,
): boolean {
const locator = locate(edit.source, ids)?.locator;
const tag = locator === undefined ? undefined : findTag(sourceFile, locator);
const loop = tag === undefined ? undefined : loopOf(elementOf(tag));
if (!tag || !loop || loopOf(loop)) return false;
const shape = loopBody(loop);
if (!shape) return false;
const bound = boundNames(shape.callback);
// What the canvas said, by id: every key must name an element of this file.
const iterations: Map<string, SourceIteration[string]>[] = [];
for (const iteration of edit.iterations) {
const byId = new Map<string, SourceIteration[string]>();
for (const [source, record] of Object.entries(iteration)) {
const address = parseSource(source);
if (address?.file !== file || typeof address.locator !== "string") return false;
byId.set(address.locator, record);
}
iterations.push(byId);
}
if (!iterations.length) return false;
// The body's top-level elements: the copies are their text.
const roots: (JsxElement | JsxSelfClosingElement)[] = [];
for (const child of shape.body.isKind(SyntaxKind.JsxFragment) ? shape.body.getJsxChildren() : [shape.body]) {
if (isBlankText(child)) continue;
if (child.isKind(SyntaxKind.JsxElement) || child.isKind(SyntaxKind.JsxSelfClosingElement)) roots.push(child);
else return false;
}
if (!roots.length) return false;
// Checked before anything is touched: every element of the body is a named
// composition element every iteration accounts for, holds only what a copy
// can hold, and keeps no attribute that would be left pointing at the item.
const bodyTags = roots.flatMap(tagsIn);
const bodyIds: string[] = [];
for (const bodyTag of bodyTags) {
const id = idOf(bodyTag);
if (!isCompositionTag(tagName(bodyTag)) || !id || bodyIds.includes(id)) return false;
if (!iterations.every((iteration) => iteration.has(id))) return false;
bodyIds.push(id);
for (const attribute of bodyTag.getAttributes()) {
if (!attribute.isKind(SyntaxKind.JsxAttribute)) continue;
const name = attribute.getNameNode().getText();
if (name === ID_ATTR) continue;
if (iterations.every((iteration) => name in iteration.get(id)!.props)) continue;
if (mentions(attribute, bound)) return false;
}
const element = elementOf(bodyTag);
if (element.isKind(SyntaxKind.JsxSelfClosingElement)) continue;
const text = isTextTag(bodyTag);
for (const child of element.getJsxChildren()) {
if (isBlankText(child)) continue;
if (child.isKind(SyntaxKind.JsxText) || child.isKind(SyntaxKind.JsxExpression)) {
if (!text) return false;
} else if (child.isKind(SyntaxKind.JsxElement) || child.isKind(SyntaxKind.JsxSelfClosingElement)) {
if (text) return false;
} else {
return false;
}
}
}
// Before any indentation is measured: ts-morph counts it in units of a
// setting it does not learn from the file on its own.
matchIndentation(sourceFile);
const indent = loop.getIndentationText();
// Each copy: the roots' text at the loop's indentation, with the ids of
// every copy but the first swapped for fresh ones — by span, so the copies
// read exactly as the body does otherwise.
const minted: Map<string, string>[] = iterations.map(() => new Map());
const copies = iterations.map((iteration, index) =>
roots
.map((root) => {
let text = root.getText();
if (index > 0) {
const swaps = tagsIn(root)
.map((bodyTag) => {
const id = idOf(bodyTag)!;
const initializer = attributeOf(bodyTag, ID_ATTR)!.getInitializer()!;
const fresh = nextId();
minted[index]!.set(id, fresh);
const pending = iteration.get(id)!.pending;
if (pending) ids[pending] = formatSource(file, fresh);
return { start: initializer.getStart() - root.getStart(), end: initializer.getEnd() - root.getStart(), fresh };
})
.sort((a, b) => b.start - a.start);
for (const swap of swaps) text = `${text.slice(0, swap.start)}"${swap.fresh}"${text.slice(swap.end)}`;
}
return reindent(text, root.getIndentationText(), indent);
})
.join(`\n${indent}`),
);
sourceFile.replaceText([loop.getStart(), loop.getEnd()], copies.join(`\n${indent}`));
// Now every copy's elements answer to a name of their own: give each what
// its iteration rendered, one attribute at a time and re-found after each
// (editing one attribute forgets its siblings).
for (const [index, iteration] of iterations.entries()) {
for (const bodyId of bodyIds) {
const id = minted[index]!.get(bodyId) ?? bodyId;
const record = iteration.get(bodyId)!;
const found = (): JsxTag => {
const copy = findTag(sourceFile, id);
if (!copy) throw new Error(`the copy of ${bodyId} for iteration ${index} is gone`);
return copy;
};
// The spreads are what the recorded props stand in for.
for (let spread = found().getAttributes().find((a) => a.isKind(SyntaxKind.JsxSpreadAttribute)); spread; ) {
spread.remove();
spread = found().getAttributes().find((a) => a.isKind(SyntaxKind.JsxSpreadAttribute));
}
for (const [name, value] of Object.entries(record.props)) {
setProp(found(), name, value);
}
const element = elementOf(found());
if (element.isKind(SyntaxKind.JsxElement) && isTextTag(element.getOpeningElement())) {
const content = record.text ? jsxText(record.text) : "";
sourceFile.replaceText([element.getOpeningElement().getEnd(), element.getClosingElement().getStart()], content);
}
}
}
return true;
}
}
/** Stamps every source file of the project. Writes nothing to a fully named project. */
export async function stampProject(context: SourceContext): Promise<void> {
await new SourceWriter(context).stampProject(await sourceFiles(context.dir));
}
/** Writes values the editor arrived at back into the JSX that produced them. */
export function applyEdits(context: SourceContext, edits: SourceEdit[]): Promise<WriteResult> {
return new SourceWriter(context).applyEdits(edits);
}