@trojanbox-vcp-test/site-edit-engine 0.1.0

package/dist/internal/ast/primitives/values/value-primitives.js

@@ -0,0 +1,158 @@
+import { objectProperty } from "@babel/types";
+import { primitiveFailure } from "../../diagnostics/index.js";
+import { resolveLocatorPath } from "../../locators/index.js";
+import { objectPropertyKey, parseMutationSource, printMutationWithOperation, valueToExpression, } from "../shared.js";
+export function updateValue(params) {
+    const { source, locator, next } = params;
+    const resolved = resolveValuePathForMutation(source, locator);
+    if (!resolved.ok) {
+        return resolved.result;
+    }
+    resolved.path.replaceWith(valueToExpression(next));
+    return printMutationWithOperation(resolved.ast, source, {
+        kind: "update-value",
+        target: "value",
+        inverse: "restore-value",
+    });
+}
+export function insertArrayElement(params) {
+    const { source, locator, index, value } = params;
+    const resolved = resolveValuePathForMutation(source, locator);
+    if (!resolved.ok) {
+        return resolved.result;
+    }
+    if (!resolved.path.isArrayExpression()) {
+        return primitiveFailure(source, "unsupported-syntax", "Array operations require array expression target", "value");
+    }
+    if (resolved.path.node.elements.some((element) => element?.type === "SpreadElement")) {
+        /* node:coverage ignore next */
+        return primitiveFailure(source, "unsupported-syntax", "Spread array elements are not supported", "value");
+    }
+    if (index < 0 || index > resolved.path.node.elements.length) {
+        return primitiveFailure(source, "array-index-out-of-range", `Array index ${index} is out of range`, "value");
+    }
+    resolved.path.node.elements.splice(index, 0, valueToExpression(value));
+    return printMutationWithOperation(resolved.ast, source, {
+        kind: "insert-array-element",
+        target: "value",
+        inverse: "remove-array-element",
+    });
+}
+export function removeArrayElement(params) {
+    const { source, locator, index } = params;
+    const resolved = resolveValuePathForMutation(source, locator);
+    if (!resolved.ok) {
+        return resolved.result;
+    }
+    if (!resolved.path.isArrayExpression()) {
+        return primitiveFailure(source, "unsupported-syntax", "Array operations require array expression target", "value");
+    }
+    if (resolved.path.node.elements.some((element) => element?.type === "SpreadElement")) {
+        return primitiveFailure(source, "unsupported-syntax", "Spread array elements are not supported", "value");
+    }
+    if (index < 0 || index >= resolved.path.node.elements.length) {
+        return primitiveFailure(source, "array-index-out-of-range", `Array index ${index} is out of range`, "value");
+    }
+    resolved.path.node.elements.splice(index, 1);
+    return printMutationWithOperation(resolved.ast, source, {
+        kind: "remove-array-element",
+        target: "value",
+        inverse: "insert-array-element",
+    });
+}
+export function moveArrayElement(params) {
+    const { source, locator, fromIndex, toIndex } = params;
+    const resolved = resolveValuePathForMutation(source, locator);
+    if (!resolved.ok) {
+        return resolved.result;
+    }
+    if (!resolved.path.isArrayExpression()) {
+        return primitiveFailure(source, "unsupported-syntax", "Array operations require array expression target", "value");
+    }
+    if (resolved.path.node.elements.some((element) => element?.type === "SpreadElement")) {
+        return primitiveFailure(source, "unsupported-syntax", "Spread array elements are not supported", "value");
+    }
+    if (fromIndex < 0 ||
+        fromIndex >= resolved.path.node.elements.length ||
+        toIndex < 0 ||
+        toIndex > resolved.path.node.elements.length) {
+        return primitiveFailure(source, "array-index-out-of-range", "Array move indices are out of range", "value");
+    }
+    const [moved] = resolved.path.node.elements.splice(fromIndex, 1);
+    const insertionIndex = Math.min(toIndex, resolved.path.node.elements.length);
+    resolved.path.node.elements.splice(insertionIndex, 0, moved);
+    return printMutationWithOperation(resolved.ast, source, {
+        kind: "move-array-element",
+        target: "value",
+        inverse: "move-array-element-back",
+    });
+}
+export function insertObjectProperty(params) {
+    const { source, locator, property } = params;
+    const resolved = resolveValuePathForMutation(source, locator);
+    if (!resolved.ok) {
+        return resolved.result;
+    }
+    if (!resolved.path.isObjectExpression()) {
+        return primitiveFailure(source, "unsupported-syntax", "Object operations require object expression target", "value");
+    }
+    if (resolved.path.node.properties.some((item) => item.type !== "ObjectProperty")) {
+        return primitiveFailure(source, "unsupported-syntax", "Spread properties are not supported", "value");
+    }
+    resolved.path.node.properties.push(objectProperty(objectPropertyKey(property.key), valueToExpression(property.value)));
+    return printMutationWithOperation(resolved.ast, source, {
+        kind: "insert-object-property",
+        target: "value",
+        inverse: "remove-object-property",
+    });
+}
+export function removeObjectProperty(params) {
+    const { source, locator, key } = params;
+    const resolved = resolveValuePathForMutation(source, locator);
+    if (!resolved.ok) {
+        return resolved.result;
+    }
+    if (!resolved.path.isObjectExpression()) {
+        return primitiveFailure(source, "unsupported-syntax", "Object operations require object expression target", "value");
+    }
+    if (resolved.path.node.properties.some((item) => item.type !== "ObjectProperty")) {
+        return primitiveFailure(source, "unsupported-syntax", "Spread properties are not supported", "value");
+    }
+    const nextProperties = resolved.path.node.properties.filter((item) => item.type !== "ObjectProperty" ||
+        (item.key.type === "Identifier"
+            ? item.key.name
+            : item.key.type === "StringLiteral"
+                ? item.key.value
+                : null) !== key);
+    if (nextProperties.length === resolved.path.node.properties.length) {
+        return primitiveFailure(source, "property-not-found", `Property '${key}' not found`, "value");
+    }
+    resolved.path.node.properties = nextProperties;
+    return printMutationWithOperation(resolved.ast, source, {
+        kind: "remove-object-property",
+        target: "value",
+        inverse: "insert-object-property",
+    });
+}
+function resolveValuePathForMutation(source, locator) {
+    const parsed = parseMutationSource(source, "value");
+    if (!parsed.ok) {
+        return { ok: false, result: parsed.result };
+    }
+    const resolved = resolveLocatorPath(parsed.ast, locator);
+    if (!resolved.ok) {
+        return {
+            ok: false,
+            result: {
+                ok: false,
+                source,
+                diagnostic: resolved.diagnostic,
+            },
+        };
+    }
+    return {
+        ok: true,
+        ast: parsed.ast,
+        path: resolved.match.path,
+    };
+}

package/dist/internal/ast/printer/SourcePrinter.d.ts

@@ -0,0 +1,21 @@
+/**
+ * SourcePrinter - AST 打印器。
+ *
+ * 使用 Babel generator 将 AST 转换回源码字符串。
+ * 支持检测并保留原始缩进风格。
+ */
+import type * as t from "@babel/types";
+/**
+ * 打印 AST 为源码字符串。
+ */
+export declare function printAst(params: {
+    ast: t.File;
+    source: string;
+}): {
+    ok: true;
+    source: string;
+} | {
+    ok: false;
+    source: string;
+    diagnostic: import("../../domain/EditDiagnostic.js").EditDiagnostic;
+};

package/dist/internal/ast/printer/SourcePrinter.js

@@ -0,0 +1,76 @@
+/**
+ * SourcePrinter - AST 打印器。
+ *
+ * 使用 Babel generator 将 AST 转换回源码字符串。
+ * 支持检测并保留原始缩进风格。
+ */
+import generateModule from "@babel/generator";
+import { primitiveFailure } from "../../domain/EditDiagnostic.js";
+/* node:coverage ignore next */
+const generate = typeof generateModule === "function"
+    ? generateModule
+    : generateModule.default;
+/**
+ * 检测源码的主导缩进风格。
+ * 返回 '2'、'4' 或 'tab'。
+ */
+function detectIndent(source) {
+    const lines = source.split("\n");
+    const spaceCounts = [];
+    let hasTab = false;
+    for (const line of lines) {
+        const match = line.match(/^(\s+)/);
+        if (match) {
+            const indent = match[1];
+            if (indent.includes("\t")) {
+                hasTab = true;
+            }
+            else if (indent.length > 0) {
+                spaceCounts.push(indent.length);
+            }
+        }
+    }
+    if (hasTab) {
+        const allHaveTab = lines.every((l) => {
+            const m = l.match(/^(\s+)/);
+            return !m || m[1].includes("\t");
+        });
+        if (allHaveTab)
+            return "tab";
+    }
+    if (spaceCounts.length === 0)
+        return "2";
+    function gcd(a, b) {
+        return b === 0 ? a : gcd(b, a % b);
+    }
+    let baseUnit = spaceCounts[0];
+    for (let i = 1; i < spaceCounts.length; i++) {
+        baseUnit = gcd(baseUnit, spaceCounts[i]);
+    }
+    if (baseUnit >= 4)
+        return "4";
+    return "2";
+}
+/**
+ * 打印 AST 为源码字符串。
+ */
+export function printAst(params) {
+    const { ast, source } = params;
+    try {
+        const indent = detectIndent(source);
+        const result = generate(ast, {
+            comments: true,
+            jsescOption: {
+                minimal: true,
+                quotes: "single",
+            },
+        }, source);
+        return {
+            ok: true,
+            source: result.code,
+        };
+    }
+    catch (error) {
+        return primitiveFailure(source, "printer-failed", `AST print failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}

package/dist/internal/ast/printer/index.d.ts

@@ -0,0 +1,6 @@
+import type * as t from "@babel/types";
+import type { AstPrimitiveResult } from "../types.js";
+export declare function printAst(params: {
+    ast: t.File;
+    source: string;
+}): AstPrimitiveResult;

package/dist/internal/ast/printer/index.js

@@ -0,0 +1,126 @@
+import generateModule from "@babel/generator";
+import { primitiveFailure } from "../diagnostics/index.js";
+/* node:coverage ignore next */
+const generate = typeof generateModule === "function"
+    ? generateModule
+    : generateModule.default;
+/**
+ * Detect the dominant indentation style from source code.
+ * Returns the indent style as '2', '4', or 'tab'.
+ * Uses GCD of all indent lengths to determine the base unit.
+ */
+function detectIndent(source) {
+    const lines = source.split("\n");
+    const spaceCounts = [];
+    let hasTab = false;
+    for (const line of lines) {
+        const match = line.match(/^(\s+)/);
+        if (match) {
+            const indent = match[1];
+            if (indent.includes("\t")) {
+                hasTab = true;
+            }
+            else if (indent.length > 0) {
+                spaceCounts.push(indent.length);
+            }
+        }
+    }
+    if (hasTab) {
+        // Check if all indented lines have tabs
+        const allHaveTab = lines.every((l) => {
+            const m = l.match(/^(\s+)/);
+            return !m || m[1].includes("\t");
+        });
+        if (allHaveTab)
+            return "tab";
+    }
+    if (spaceCounts.length === 0)
+        return "2";
+    // Find GCD of all space counts to determine base unit
+    function gcd(a, b) {
+        return b === 0 ? a : gcd(b, a % b);
+    }
+    let baseUnit = spaceCounts[0];
+    for (let i = 1; i < spaceCounts.length; i++) {
+        baseUnit = gcd(baseUnit, spaceCounts[i]);
+    }
+    if (baseUnit >= 4)
+        return "4";
+    return "2";
+}
+/**
+ * Normalize a single line's indentation to the target style.
+ * Uses the minimum non-zero indent in the output as the base unit.
+ */
+function normalizeLineIndent(line, target) {
+    const match = line.match(/^(\s+)(.*)/s);
+    if (!match)
+        return line;
+    const rawIndent = match[1];
+    const content = match[2];
+    if (rawIndent.length === 0)
+        return line;
+    let levels = 0;
+    if (rawIndent.includes("\t")) {
+        levels = rawIndent.split("\t").length - 1;
+    }
+    else {
+        // Use the raw space count directly, scaled to target
+        const spaceCount = rawIndent.length;
+        if (target === "4") {
+            // Convert to 4-space: each 2 spaces becomes 1 level → 4 spaces
+            levels = Math.max(1, Math.round(spaceCount / 2));
+        }
+        else if (target === "tab") {
+            // Convert to tab: each 2 spaces becomes 1 tab
+            levels = Math.max(1, Math.round(spaceCount / 2));
+        }
+        else {
+            // Target is 2-space: keep as-is (each 2 spaces = 1 level)
+            levels = Math.max(1, Math.round(spaceCount / 2));
+        }
+    }
+    // Clamp levels to reasonable range
+    levels = Math.min(Math.max(levels, 0), 20);
+    if (target === "tab") {
+        return "\t".repeat(levels) + content;
+    }
+    else if (target === "4") {
+        return "    ".repeat(levels) + content;
+    }
+    else {
+        return "  ".repeat(levels) + content;
+    }
+}
+/**
+ * Post-process: normalize indentation to match source style.
+ */
+function normalizeSourceIndent(source, target) {
+    const lines = source.split("\n");
+    return lines.map((line) => normalizeLineIndent(line, target)).join("\n");
+}
+export function printAst(params) {
+    const { ast, source } = params;
+    try {
+        const indent = detectIndent(source);
+        const result = generate(ast, {
+            comments: true,
+            jsescOption: {
+                minimal: true,
+                quotes: "single",
+            },
+        }, source);
+        // Post-process: normalize indentation to match source style
+        let output = result.code;
+        if (indent !== "2") {
+            output = normalizeSourceIndent(output, indent);
+        }
+        return {
+            ok: true,
+            source: output,
+        };
+    }
+    catch (error) {
+        return primitiveFailure(source, "printer-failed", `AST print failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}

package/dist/internal/ast/types.d.ts

@@ -0,0 +1,190 @@
+import type * as t from "@babel/types";
+export interface SourceRange {
+    startLine: number;
+    startColumn: number;
+    endLine: number;
+    endColumn: number;
+}
+export type Placement = "prepend" | "append" | "before" | "after";
+export type ValuePathSegment = {
+    kind: "property";
+    name: string;
+} | {
+    kind: "index";
+    index: number;
+};
+export type ValueRootSelector = {
+    kind: "binding";
+    name: string;
+} | {
+    kind: "hook-state";
+    name: string;
+    hook: "useState" | "useReducer";
+} | {
+    kind: "named-export";
+    name: string;
+} | {
+    kind: "default-export";
+} | {
+    kind: "expression";
+    sourceRange: SourceRange;
+};
+export type JsxNodeLocator = {
+    kind: "jsx-node";
+    strategy: "source-range";
+    sourceRange: SourceRange;
+    expectedIdentity?: {
+        file: string;
+        component: string;
+        structuralPath: string;
+    };
+} | {
+    kind: "jsx-node";
+    strategy: "structural-path";
+    file: string;
+    component: string;
+    structuralPath: string;
+    expectedRange?: SourceRange;
+};
+export interface JsxAttributeLocator {
+    kind: "jsx-attribute";
+    element: JsxNodeLocator;
+    name: string;
+}
+export interface ValueLocator {
+    kind: "value";
+    root: ValueRootSelector;
+    path?: ValuePathSegment[];
+    expectedRange?: SourceRange;
+}
+export interface ExpressionLocator {
+    kind: "expression";
+    base: string;
+    path?: ValuePathSegment[];
+    expectedRange?: SourceRange;
+}
+export interface DirectiveLocator {
+    kind: "directive";
+    value: string;
+    expectedRange?: SourceRange;
+}
+export type ExportLocator = {
+    kind: "export";
+    exportKind: "named";
+    name: string;
+    expectedRange?: SourceRange;
+} | {
+    kind: "export";
+    exportKind: "metadata";
+    expectedRange?: SourceRange;
+} | {
+    kind: "export";
+    exportKind: "generate-metadata";
+    expectedRange?: SourceRange;
+} | {
+    kind: "export";
+    exportKind: "default";
+    expectedRange?: SourceRange;
+};
+export type AstLocator = JsxNodeLocator | JsxAttributeLocator | ValueLocator | ExpressionLocator | DirectiveLocator | ExportLocator;
+export type AstLocatorKind = AstLocator["kind"];
+export type AstDiagnosticCode = "parse-failed" | "locator-miss" | "unsupported-syntax" | "binding-not-found" | "export-not-found" | "property-not-found" | "array-index-out-of-range" | "directive-conflict" | "metadata-shape-unsupported" | "printer-failed" | "invalid-parent-child-relation" | "self-closing-element";
+export interface AstDiagnostic {
+    code: AstDiagnosticCode;
+    message: string;
+    locatorKind?: AstLocatorKind;
+    details?: Record<string, unknown>;
+}
+export interface LocatorMatch {
+    locatorKind: AstLocatorKind;
+    node: t.Node;
+    start: number;
+    end: number;
+}
+export type ResolveLocatorResult = {
+    ok: true;
+    match: LocatorMatch;
+} | {
+    ok: false;
+    source: string;
+    diagnostic: AstDiagnostic;
+};
+export interface OperationDescription {
+    type: string;
+    nodeId: string;
+    kind?: string;
+    target?: string;
+    timestamp?: number;
+    beforeSourceHash?: string;
+    afterSourceHash?: string;
+    inverse?: string;
+    meta?: Record<string, unknown>;
+}
+export interface HistoryEntry {
+    operation: OperationDescription;
+    timestamp: number;
+}
+export type AstPrimitiveResult = {
+    ok: true;
+    source: string;
+    operation?: OperationDescription;
+} | {
+    ok: false;
+    source: string;
+    diagnostic: AstDiagnostic;
+};
+export type PrimitiveValue = string | number | boolean | null | PrimitiveValue[] | {
+    [key: string]: PrimitiveValue;
+};
+/**
+ * 将 locator kind 映射到对应的 primitive 操作参数类型。
+ * 用于编译期验证 locator/primitive 组合的正确性。
+ */
+export type LocatorToPrimitiveMap = {
+    "jsx-node": {
+        updateText: "JsxNodeLocator";
+        removeNode: "JsxNodeLocator";
+        insertChild: "JsxNodeLocator";
+        moveNode: "JsxNodeLocator";
+    };
+    "jsx-attribute": {
+        setJsxAttribute: "JsxAttributeLocator";
+        removeJsxAttribute: "JsxAttributeLocator";
+        updateStyleProperty: "JsxAttributeLocator";
+        updateClassName: "JsxAttributeLocator";
+        addTailwindClass: "JsxAttributeLocator";
+        removeTailwindClass: "JsxAttributeLocator";
+        updateCssModuleClassReference: "JsxAttributeLocator";
+    };
+    value: {
+        updateValue: "ValueLocator";
+        insertArrayElement: "ValueLocator";
+        removeArrayElement: "ValueLocator";
+        moveArrayElement: "ValueLocator";
+        insertObjectProperty: "ValueLocator";
+        removeObjectProperty: "ValueLocator";
+    };
+    expression: {
+        updateValue: "ExpressionLocator";
+    };
+    directive: {
+        addDirective: "DirectiveLocator";
+        removeDirective: "DirectiveLocator";
+        updateDirective: "DirectiveLocator";
+    };
+    export: {
+        updateNamedExport: "ExportLocator";
+        updateMetadataField: "ExportLocator";
+        updateGenerateMetadata: "ExportLocator";
+    };
+};
+/**
+ * 根据 locator kind 推断对应的 primitive 操作类型。
+ * 用于编译期类型推断。
+ */
+export type PrimitiveOperationForLocator<K extends AstLocatorKind> = K extends keyof LocatorToPrimitiveMap ? keyof LocatorToPrimitiveMap[K] : never;
+/**
+ * 验证 locator/primitive 组合的编译期断言工具。
+ * 正确组合返回 true，错误组合返回 never。
+ */
+export type ValidatePrimitiveContract<K extends AstLocatorKind, Op extends string> = K extends keyof LocatorToPrimitiveMap ? Op extends keyof LocatorToPrimitiveMap[K] ? true : never : never;

package/dist/internal/ast/types.js

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

package/dist/internal/capability/capability-resolver.d.ts

@@ -0,0 +1,16 @@
+import type { NodeCapabilitySnapshot } from "../protocol.js";
+import type { EditableTopology } from "../topology/types.js";
+import type { RenderSourceGraph } from "../graph/types.js";
+/**
+ * 为指定节点计算能力快照。
+ *
+ * 规则:
+ *   - canMove = true 意味着支持全部 MoveTarget 位置（含跨文件）
+ *   - canInsertChild = true 意味着支持 native-tag + component-call
+ *   - 限制通过 constraints 显式返回
+ */
+export declare function resolveCapability(key: string, topology: EditableTopology, graph: RenderSourceGraph): NodeCapabilitySnapshot;
+/**
+ * 批量计算所有节点的能力快照。
+ */
+export declare function resolveAllCapabilities(topology: EditableTopology, graph: RenderSourceGraph): Map<string, NodeCapabilitySnapshot>;