@cashscript/utils 0.13.0-next.3 → 0.13.0-next.5

package/dist/artifact.d.ts

@@ -1,3 +1,6 @@
+export interface CompilerOptions {
+    enforceFunctionParameterTypes?: boolean;
+}
 export interface AbiInput {
     name: string;
     type: string;
@@ -11,6 +14,7 @@ export interface DebugInformation {
     sourceMap: string;
     logs: readonly LogEntry[];
     requires: readonly RequireStatement[];
+    sourceTags?: string;
 }
 export interface LogEntry {
     ip: number;
@@ -39,6 +43,7 @@ export interface Artifact {
     compiler: {
         name: string;
         version: string;
+        options?: CompilerOptions;
     };
     updatedAt: string;
 }

package/dist/bitauth-script.d.ts

@@ -1,6 +1,7 @@
 import { Script } from './script.js';
+import { FullLocationData } from './types.js';
 export type LineToOpcodesMap = Record<string, Script>;
 export type LineToAsmMap = Record<string, string>;
-export declare function buildLineToOpcodesMap(bytecode: Script, sourceMap: string): LineToOpcodesMap;
-export declare function buildLineToAsmMap(bytecode: Script, sourceMap: string): LineToAsmMap;
-export declare function formatBitAuthScript(bytecode: Script, sourceMap: string, sourceCode: string): string;
+export declare function buildLineToOpcodesMap(bytecode: Script, sourceMapOrLocationData: string | FullLocationData): LineToOpcodesMap;
+export declare function buildLineToAsmMap(bytecode: Script, sourceMapOrLocationData: string | FullLocationData): LineToAsmMap;
+export declare function formatBitAuthScript(bytecode: Script, sourceMap: string, sourceCode: string, sourceTags?: string): string;

package/dist/bitauth-script.js

@@ -1,33 +1,98 @@
+import { range } from './data.js';
 import { scriptToBitAuthAsm } from './script.js';
-import { sourceMapToLocationData } from './source-map.js';
+import { parseSourceTags, sourceMapToLocationData } from './source-map.js';
 import { PositionHint } from './types.js';
-export function buildLineToOpcodesMap(bytecode, sourceMap) {
-    const locationData = sourceMapToLocationData(sourceMap);
-    return locationData.reduce((lineToOpcodeMap, { location, positionHint }, index) => {
+export function buildLineToOpcodesMap(bytecode, sourceMapOrLocationData) {
+    const locationData = typeof sourceMapOrLocationData === 'string' ? sourceMapToLocationData(sourceMapOrLocationData) : sourceMapOrLocationData;
+    return locationData.reduce((lineToOpcodeMap, singleLocation, index) => {
         const opcode = bytecode[index];
-        const line = positionHint === PositionHint.END ? location?.end.line : location?.start.line;
+        const line = getDisplayLine(singleLocation);
         return {
             ...lineToOpcodeMap,
             [line]: [...(lineToOpcodeMap[line] || []), opcode],
         };
     }, {});
 }
-export function buildLineToAsmMap(bytecode, sourceMap) {
-    const lineToOpcodesMap = buildLineToOpcodesMap(bytecode, sourceMap);
+export function buildLineToAsmMap(bytecode, sourceMapOrLocationData) {
+    const lineToOpcodesMap = buildLineToOpcodesMap(bytecode, sourceMapOrLocationData);
     return Object.fromEntries(Object.entries(lineToOpcodesMap).map(([lineNumber, opcodeList]) => [lineNumber, scriptToBitAuthAsm(opcodeList)]));
 }
-export function formatBitAuthScript(bytecode, sourceMap, sourceCode) {
-    const lineToAsmMap = buildLineToAsmMap(bytecode, sourceMap);
-    const escapedSourceCode = sourceCode.replaceAll('/*', '\\/*').replaceAll('*/', '*\\/');
-    const sourceCodeLines = escapedSourceCode.split('\n');
-    const sourceCodeLineLengths = sourceCodeLines.map((line) => line.length);
-    const bytecodeLineLengths = Object.values(lineToAsmMap).map((line) => line.length);
-    const maxSourceCodeLength = Math.max(...sourceCodeLineLengths);
-    const maxBytecodeLength = Math.max(...bytecodeLineLengths);
-    const annotatedAsmLines = sourceCodeLines.map((line, index) => {
-        const lineAsm = lineToAsmMap[index + 1];
-        return `${(lineAsm || '').padEnd(maxBytecodeLength)} /* ${line.padEnd(maxSourceCodeLength)} */`;
+export function formatBitAuthScript(bytecode, sourceMap, sourceCode, sourceTags) {
+    const locationData = sourceMapToLocationData(sourceMap);
+    const sourceLines = sourceCode.split('\n');
+    // Splice synthetic annotation lines (e.g. for-loop updates) into source and remap opcode lines
+    const insertions = buildInsertions(locationData, sourceLines, sourceTags);
+    const splicedSourceLines = spliceSyntheticSourceLines(sourceLines, insertions);
+    const splicedLocationData = updateLocationData(locationData, insertions);
+    // Group opcodes by display line and convert to ASM
+    const lineToAsm = buildLineToAsmMap(bytecode, splicedLocationData);
+    // Format output
+    const escapedLines = splicedSourceLines.map(escapeCommentChars);
+    const maxAsmLen = Math.max(...escapedLines.map((_, i) => (lineToAsm[i + 1] || '').length));
+    const maxSrcLen = Math.max(...escapedLines.map((l) => l.length));
+    return escapedLines.map((src, i) => {
+        const asm = lineToAsm[i + 1] || '';
+        return `${asm.padEnd(maxAsmLen)} /* ${src.padEnd(maxSrcLen)} */`;
+    }).join('\n');
+}
+// --- Helpers ---
+function getDisplayLine(singleLocation) {
+    const { location, positionHint } = singleLocation;
+    return positionHint === PositionHint.END ? location.end.line : location.start.line;
+}
+function escapeCommentChars(text) {
+    return text.replaceAll('/*', '\\/*').replaceAll('*/', '*\\/');
+}
+function buildInsertions(locationData, sourceLines, sourceTags) {
+    const tags = (sourceTags ? parseSourceTags(sourceTags) : []);
+    return tags.map((tag) => {
+        const annotation = deriveTagLabel(tag, locationData, sourceLines);
+        const insertAfterLine = getDisplayLine(locationData[Math.max(tag.startIndex - 1, 0)]);
+        return { insertAfterLine, annotation, startIndex: tag.startIndex, endIndex: tag.endIndex };
     });
-    return annotatedAsmLines.join('\n');
+}
+function spliceSyntheticSourceLines(sourceLines, insertions) {
+    return insertions.reduceRight((lines, ins) => [...lines.slice(0, ins.insertAfterLine), ins.annotation, ...lines.slice(ins.insertAfterLine)], sourceLines);
+}
+function updateLocationData(locationData, insertions) {
+    return insertions.reduceRight((location, insertion) => {
+        return location.map((entry, opcodeIndex) => {
+            const currentLineNumber = getDisplayLine(location[opcodeIndex]);
+            const updatedLineNumber = getUpdatedLineNumber(currentLineNumber, insertion, opcodeIndex);
+            if (updatedLineNumber === currentLineNumber)
+                return entry;
+            return {
+                location: {
+                    start: { line: updatedLineNumber, column: 0 },
+                    end: { line: updatedLineNumber, column: 0 },
+                },
+                positionHint: PositionHint.START,
+            };
+        });
+    }, locationData);
+}
+const getUpdatedLineNumber = (currentLineNumber, insertion, opcodeIndex) => {
+    const newLineNumber = insertion.insertAfterLine + 1;
+    const inTagRange = opcodeIndex >= insertion.startIndex && opcodeIndex <= insertion.endIndex;
+    if (inTagRange)
+        return newLineNumber;
+    if (currentLineNumber > insertion.insertAfterLine)
+        return currentLineNumber + 1;
+    return currentLineNumber;
+};
+/** Derive the annotation text (e.g. ">>> for-loop update (i = i + 1)") for a source tag. */
+function deriveTagLabel(tag, locationData, sourceLines) {
+    const headerLine = getDisplayLine(locationData[tag.startIndex]);
+    // Find the column span of the update expression using single-line locations in the tag range
+    const singleLineLocations = range(tag.startIndex, tag.endIndex)
+        .map((idx) => locationData[idx].location)
+        .filter((loc) => loc.start.line === loc.end.line);
+    const startCol = Math.min(...singleLineLocations.map((loc) => loc.start.column));
+    const endCol = Math.max(...singleLineLocations.map((loc) => loc.end.column));
+    const expression = sourceLines[headerLine - 1].substring(startCol, endCol);
+    // Indentation: use first non-empty line after header
+    const bodyLine = sourceLines.slice(headerLine).find((l) => l.trim().length > 0);
+    const indent = bodyLine?.match(/^(\s*)/)?.[1] ?? '';
+    return `${indent}>>> for-loop update (${expression})`;
 }
 //# sourceMappingURL=bitauth-script.js.map

package/dist/data.d.ts

@@ -5,3 +5,4 @@ export declare function decodeInt(encodedInt: Uint8Array, maxLength?: number): b
 export declare function encodeString(str: string): Uint8Array;
 export declare function decodeString(encodedString: Uint8Array): string;
 export declare function placeholder(size: number): Uint8Array;
+export declare function range(start: number, end: number): number[];

package/dist/data.js

@@ -34,4 +34,7 @@ export function decodeString(encodedString) {
 export function placeholder(size) {
     return new Uint8Array(size).fill(0);
 }
+export function range(start, end) {
+    return Array.from({ length: end - start + 1 }, (_, i) => start + i);
+}
 //# sourceMappingURL=data.js.map

package/dist/script.d.ts

@@ -1,4 +1,4 @@
-import { FullLocationData } from './types.js';
+import { FullLocationData, SourceTagEntry } from './types.js';
 import { LogEntry, RequireStatement } from './artifact.js';
 export declare const Op: {
     [x: number]: string;
@@ -284,13 +284,14 @@ export declare function bytecodeToBitAuthAsm(bytecode: Uint8Array): string;
 export declare function countOpcodes(script: Script): number;
 export declare function calculateBytesize(script: Script): number;
 export declare function encodeNullDataScript(chunks: OpOrData[]): Uint8Array;
-export declare function generateRedeemScript(baseScript: Script, encodedConstructorArgs: Script): Script;
+export declare function generateContractBytecodeScript(baseScript: Script, encodedConstructorArgs: Script): Script;
 interface OptimiseBytecodeResult {
     script: Script;
     locationData: FullLocationData;
     logs: LogEntry[];
     requires: RequireStatement[];
+    sourceTags: SourceTagEntry[];
 }
-export declare function optimiseBytecode(script: Script, locationData: FullLocationData, logs: LogEntry[], requires: RequireStatement[], constructorParamLength: number, runs?: number): OptimiseBytecodeResult;
+export declare function optimiseBytecode(script: Script, locationData: FullLocationData, logs: LogEntry[], requires: RequireStatement[], sourceTags: SourceTagEntry[], constructorParamLength: number, runs?: number): OptimiseBytecodeResult;
 export declare function optimiseBytecodeOld(script: Script, runs?: number): Script;
 export {};

package/dist/script.js

@@ -102,13 +102,13 @@ function getPushDataOpcode(data) {
         return Uint8Array.from([0x4c, byteLength]);
     throw Error('Pushdata too large');
 }
-export function generateRedeemScript(baseScript, encodedConstructorArgs) {
+export function generateContractBytecodeScript(baseScript, encodedConstructorArgs) {
     return [...encodedConstructorArgs.slice().reverse(), ...baseScript];
 }
-export function optimiseBytecode(script, locationData, logs, requires, constructorParamLength, runs = 1000) {
+export function optimiseBytecode(script, locationData, logs, requires, sourceTags, constructorParamLength, runs = 1000) {
     for (let i = 0; i < runs; i += 1) {
         const oldScript = script;
-        const { script: newScript, locationData: newLocationData, logs: newLogs, requires: newRequires, } = replaceOps(script, locationData, logs, requires, constructorParamLength, optimisationReplacements);
+        const { script: newScript, locationData: newLocationData, logs: newLogs, requires: newRequires, sourceTags: newSourceTags, } = replaceOps(script, locationData, logs, requires, sourceTags, constructorParamLength, optimisationReplacements);
         // Break on fixed point
         if (scriptToAsm(oldScript) === scriptToAsm(newScript))
             break;
@@ -116,8 +116,9 @@ export function optimiseBytecode(script, locationData, logs, requires, construct
         locationData = newLocationData;
         logs = newLogs;
         requires = newRequires;
+        sourceTags = newSourceTags;
     }
-    return { script, locationData, logs, requires };
+    return { script, locationData, logs, requires, sourceTags };
 }
 export function optimiseBytecodeOld(script, runs = 1000) {
     const optimisations = OptimisationsEquivFile
@@ -162,11 +163,12 @@ function replaceOpsOld(script, optimisations) {
     asm = asm.replace(/\s+/g, ' ').trim();
     return asmToScript(asm);
 }
-function replaceOps(script, locationData, logs, requires, constructorParamLength, optimisations) {
+function replaceOps(script, locationData, logs, requires, sourceTags, constructorParamLength, optimisations) {
     let asm = scriptToAsm(script);
     let newLocationData = [...locationData];
     let newLogs = [...logs];
     let newRequires = [...requires];
+    let newSourceTags = [...sourceTags];
     optimisations.forEach(([pattern, replacement]) => {
         let processedAsm = '';
         let asmToSearch = asm;
@@ -249,6 +251,12 @@ function replaceOps(script, locationData, logs, requires, constructorParamLength
                     }),
                 };
             });
+            // Source tags use raw script indices (no constructor offset), so we adjust using scriptIndex directly
+            newSourceTags = newSourceTags.map((tag) => ({
+                ...tag,
+                startIndex: tag.startIndex >= scriptIndex ? Math.max(scriptIndex, tag.startIndex - lengthDiff) : tag.startIndex,
+                endIndex: tag.endIndex >= scriptIndex ? Math.max(scriptIndex, tag.endIndex - lengthDiff) : tag.endIndex,
+            }));
             // We add the replacement to the processed asm
             processedAsm = mergeAsm(processedAsm, replacement);
             // We do not add the matched pattern anywhere since it gets replaced
@@ -267,6 +275,7 @@ function replaceOps(script, locationData, logs, requires, constructorParamLength
         locationData: newLocationData,
         logs: newLogs,
         requires: newRequires,
+        sourceTags: newSourceTags,
     };
 }
 const getHighestEndLocation = (locations) => {

package/dist/source-map.d.ts

@@ -1,3 +1,5 @@
-import { FullLocationData } from './types.js';
+import { FullLocationData, SourceTagEntry } from './types.js';
 export declare function generateSourceMap(locationData: FullLocationData): string;
 export declare const sourceMapToLocationData: (sourceMap: string) => FullLocationData;
+export declare function parseSourceTags(sourceTags: string): SourceTagEntry[];
+export declare function generateSourceTags(entries: SourceTagEntry[]): string;

package/dist/source-map.js

@@ -1,4 +1,4 @@
-import { PositionHint } from './types.js';
+import { PositionHint, SourceTagKind } from './types.js';
 /*
  * The source mappings for the bytecode use the following notation (similar to Solidity):
  *
@@ -100,4 +100,25 @@ const parsePositionHint = (hint) => {
         return PositionHint.START;
     return undefined;
 };
+const SOURCE_TAG_KIND_VALUES = new Set(Object.values(SourceTagKind));
+/*
+ * Format: "startIndex:endIndex:kind;..." e.g. "14:16:fu;38:42:fu"
+ * (currently only `fu` (For-Update) is supported as source tag kind)
+ */
+export function parseSourceTags(sourceTags) {
+    if (!sourceTags)
+        return [];
+    return sourceTags.split(';').map((segment) => {
+        const [startStr, endStr, kindStr] = segment.split(':');
+        if (!SOURCE_TAG_KIND_VALUES.has(kindStr)) {
+            throw new Error(`Unknown source tag kind: ${kindStr}`);
+        }
+        return { startIndex: Number(startStr), endIndex: Number(endStr), kind: kindStr };
+    });
+}
+export function generateSourceTags(entries) {
+    if (entries.length === 0)
+        return '';
+    return entries.map((entry) => `${entry.startIndex}:${entry.endIndex}:${entry.kind}`).join(';');
+}
 //# sourceMappingURL=source-map.js.map

package/dist/types.d.ts

@@ -51,3 +51,11 @@ export declare enum PositionHint {
     START = 0,
     END = 1
 }
+export declare enum SourceTagKind {
+    FOR_UPDATE = "fu"
+}
+export interface SourceTagEntry {
+    startIndex: number;
+    endIndex: number;
+    kind: SourceTagKind;
+}

package/dist/types.js

@@ -82,9 +82,9 @@ export function explicitlyCastable(from, to) {
         return false;
     }
     if (from instanceof BytesType) {
-        // Can cast unbounded bytes or <=4 bytes to int
+        // Can cast any bytes to int
         if (to === PrimitiveType.INT)
-            return !from.bound || from.bound <= 8;
+            return true;
         // Can't cast bytes to bool or string
         if (to === PrimitiveType.BOOL)
             return false;
@@ -191,4 +191,10 @@ export var PositionHint;
     PositionHint[PositionHint["START"] = 0] = "START";
     PositionHint[PositionHint["END"] = 1] = "END";
 })(PositionHint || (PositionHint = {}));
+// Semantic tags for opcodes that need special treatment in debugging output (e.g. synthetic labels).
+// Currently used for loop constructs where opcode order diverges from source line order.
+export var SourceTagKind;
+(function (SourceTagKind) {
+    SourceTagKind["FOR_UPDATE"] = "fu";
+})(SourceTagKind || (SourceTagKind = {}));
 //# sourceMappingURL=types.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cashscript/utils",
-  "version": "0.13.0-next.3",
+  "version": "0.13.0-next.5",
   "description": "CashScript utilities and types",
   "keywords": [
     "bitcoin cash",
@@ -48,5 +48,5 @@
     "typescript": "^5.9.2",
     "vitest": "^4.0.15"
   },
-  "gitHead": "d4e9ee295be4f48ea89da87d551cf369d1b33871"
+  "gitHead": "672ddcaf8d8bd464e518c4902c4ee8062407512f"
 }