diff --git a/packages/cashc/src/compiler.ts b/packages/cashc/src/compiler.ts index dcfcf5fac..816bd2139 100644 --- a/packages/cashc/src/compiler.ts +++ b/packages/cashc/src/compiler.ts @@ -162,6 +162,7 @@ function compileCode( requires: optimisationResult.requires, sourceTags: generateSourceTags(optimisationResult.sourceTags) || undefined, functions: traversal.frames.length > 0 ? traversal.frames : undefined, + sources: Object.keys(traversal.sources).length > 0 ? traversal.sources : undefined, inlineRanges: generateInlineRanges(optimisationResult.inlineRanges) || undefined, }; diff --git a/packages/cashc/src/dependency-resolution.ts b/packages/cashc/src/dependency-resolution.ts index aaa621fc4..8cb13752e 100644 --- a/packages/cashc/src/dependency-resolution.ts +++ b/packages/cashc/src/dependency-resolution.ts @@ -21,6 +21,8 @@ export interface ImportResolver { read(canonicalPath: string): string | undefined; dirname(canonicalPath: string): string; sourceName(canonicalPath: string): string; + // A name no other file resolves to, used when two files share a `sourceName` + uniqueSourceName(canonicalPath: string): string; } export function createDiskResolver(rootDir: string): ImportResolver { @@ -41,6 +43,9 @@ export function createDiskResolver(rootDir: string): ImportResolver { const relativePath = getPackageImportPath(canonicalPath) ?? path.relative(rootDir, canonicalPath); return relativePath.split(path.sep).join(path.posix.sep); }, + // The path relative to the root is unique per file, unlike the package path, which a local file + // or another installed copy of the package can share + uniqueSourceName: (canonicalPath) => path.relative(rootDir, canonicalPath).split(path.sep).join(path.posix.sep), }; } @@ -59,6 +64,7 @@ export function createMemoryResolver(files: Record): ImportResol read: (canonicalPath) => normalisedFiles[canonicalPath], dirname: (canonicalPath) => path.posix.dirname(canonicalPath), sourceName: (canonicalPath) => canonicalPath, + uniqueSourceName: (canonicalPath) => canonicalPath, }; } @@ -99,6 +105,7 @@ function collectImports( ): ImportedDefinitions { const visitedPaths = new Set(); const activePaths = new Set(); + const importedFiles: ImportedFile[] = []; const collect = (currentImports: ImportNode[], currentDir: string): ImportedDefinitions[] => currentImports.flatMap((importNode) => { @@ -126,15 +133,7 @@ function collectImports( const importedAst = parseCode(importedSource, errorListener); checkVersionConstraints(importedAst.pragmas, resolver.sourceName(canonicalPath)); - // Record source provenance so debug frames can attribute to the imported file - importedAst.functions.forEach((func) => { - func.sourceCode = importedSource; - func.sourceFile = resolver.sourceName(canonicalPath); - }); - importedAst.constants.forEach((constant) => { - constant.sourceCode = importedSource; - constant.sourceFile = resolver.sourceName(canonicalPath); - }); + importedFiles.push({ canonicalPath, source: importedSource, ast: importedAst }); activePaths.add(canonicalPath); const transitiveDefinitions = collect(importedAst.imports, resolver.dirname(canonicalPath)); @@ -147,12 +146,46 @@ function collectImports( }); const collected = collect(imports, resolver.rootDir); + recordSourceProvenance(importedFiles, resolver); return { functions: collected.flatMap((definitions) => definitions.functions), constants: collected.flatMap((definitions) => definitions.constants), }; } +interface ImportedFile { + canonicalPath: string; + source: string; + ast: SourceFileNode; +} + +// Record source provenance so debug frames can attribute to the imported file. The artifact keeps each +// file's source once, keyed by this name, so two different files must never share one. Files start out +// with their short name, and any name held by more than one file is replaced by each file's unique name, +// repeated until no name is shared: a replacement can itself equal another file's short name when the +// contract lives inside node_modules. Unique names never collide, so this ends +function recordSourceProvenance(importedFiles: ImportedFile[], resolver: ImportResolver): void { + const names = new Map(importedFiles.map(({ canonicalPath }) => [canonicalPath, resolver.sourceName(canonicalPath)])); + + const sharedNames = (): Set => { + const counts = new Map(); + names.forEach((name) => counts.set(name, (counts.get(name) ?? 0) + 1)); + return new Set([...counts].filter(([, count]) => count > 1).map(([name]) => name)); + }; + + for (let shared = sharedNames(); shared.size > 0; shared = sharedNames()) { + names.forEach((name, canonicalPath) => { + if (shared.has(name)) names.set(canonicalPath, resolver.uniqueSourceName(canonicalPath)); + }); + } + + importedFiles.forEach(({ canonicalPath, source, ast }) => { + [...ast.functions, ...ast.constants].forEach((definition) => { + definition.sourceCode = source; + definition.sourceFile = names.get(canonicalPath); + }); + }); +} function isPackageImport(importPath: string): boolean { return !importPath.startsWith('./') && !importPath.startsWith('../') && !importPath.startsWith('/'); diff --git a/packages/cashc/src/generation/GenerateTargetTraversal.ts b/packages/cashc/src/generation/GenerateTargetTraversal.ts index ddc25171a..e7c0bfd38 100644 --- a/packages/cashc/src/generation/GenerateTargetTraversal.ts +++ b/packages/cashc/src/generation/GenerateTargetTraversal.ts @@ -92,6 +92,8 @@ export default class GenerateTargetTraversal extends AstTraversal { requires: RequireStatement[] = []; sourceTags: SourceTagEntry[] = []; frames: DebugFrame[] = []; + // Full text of each imported file that a frame refers to by its `sourceFile` + sources: Record = {}; finalStackUsage: Record = {}; private scopeDepth = 0; @@ -276,6 +278,10 @@ export default class GenerateTargetTraversal extends AstTraversal { optimised: OptimiseBytecodeResult, functionId?: number, ): DebugFrame { + if (node.sourceFile !== undefined && node.sourceCode !== undefined) { + this.sources[node.sourceFile] = node.sourceCode; + } + return { id: functionId, name: node.name, @@ -284,7 +290,6 @@ export default class GenerateTargetTraversal extends AstTraversal { bytecode: binToHex(scriptToBytecode(optimised.script)), sourceMap: generateSourceMap(optimised.locationData), sourceTags: generateSourceTags(optimised.sourceTags) || undefined, - source: node.sourceCode, sourceFile: node.sourceFile, logs: optimised.logs, requires: optimised.requires, diff --git a/packages/cashc/test/generation/fixtures/import-fixtures/diamond.ts b/packages/cashc/test/generation/fixtures/import-fixtures/diamond.ts index 12d7dc67d..66d1bc28c 100644 --- a/packages/cashc/test/generation/fixtures/import-fixtures/diamond.ts +++ b/packages/cashc/test/generation/fixtures/import-fixtures/diamond.ts @@ -2,6 +2,11 @@ import fs from 'fs'; import { URL } from 'url'; import { Fixture } from '../../fixture-utils.js'; +const readImportFixture = (name: string): string => fs.readFileSync( + new URL(`../../../import-fixtures/${name}`, import.meta.url), + { encoding: 'utf-8' }, +); + export const fixtures: Fixture[] = [ { artifact: { @@ -23,7 +28,6 @@ export const fixtures: Fixture[] = [ inputs: [{ name: 'a', type: 'int' }], bytecode: '8b', sourceMap: '2:11:2:16:1', - source: fs.readFileSync(new URL('../../../import-fixtures/leaf.cash', import.meta.url), { encoding: 'utf-8' }), sourceFile: 'leaf.cash', logs: [], requires: [], @@ -33,7 +37,6 @@ export const fixtures: Fixture[] = [ inputs: [{ name: 'a', type: 'int' }], bytecode: '8b5295', sourceMap: '3:11:3:18:1;:21::22:0;:11:::1', - source: fs.readFileSync(new URL('../../../import-fixtures/mid1.cash', import.meta.url), { encoding: 'utf-8' }), sourceFile: 'mid1.cash', logs: [], requires: [], @@ -44,13 +47,17 @@ export const fixtures: Fixture[] = [ inputs: [{ name: 'a', type: 'int' }], bytecode: '8b5393', sourceMap: '3:11:3:18:1;:21::22:0;:11:::1', - source: fs.readFileSync(new URL('../../../import-fixtures/mid2.cash', import.meta.url), { encoding: 'utf-8' }), sourceFile: 'mid2.cash', logs: [], requires: [], inlineRanges: '0:0:leaf', }, ], + sources: { + 'leaf.cash': readImportFixture('leaf.cash'), + 'mid1.cash': readImportFixture('mid1.cash'), + 'mid2.cash': readImportFixture('mid2.cash'), + }, inlineRanges: '1:3:m1;5:7:m2', }, }, @@ -90,7 +97,6 @@ export const fixtures: Fixture[] = [ sourceMap: '2:11:2:16:1', logs: [], requires: [], - source: fs.readFileSync(new URL('../../../import-fixtures/leaf.cash', import.meta.url), { encoding: 'utf-8' }), sourceFile: 'leaf.cash', }, { @@ -101,7 +107,6 @@ export const fixtures: Fixture[] = [ sourceMap: '3:11:3:18:1;;:21::22:0;:11:::1', logs: [], requires: [], - source: fs.readFileSync(new URL('../../../import-fixtures/mid1.cash', import.meta.url), { encoding: 'utf-8' }), sourceFile: 'mid1.cash', }, { @@ -112,10 +117,14 @@ export const fixtures: Fixture[] = [ sourceMap: '3:11:3:18:1;;:21::22:0;:11:::1', logs: [], requires: [], - source: fs.readFileSync(new URL('../../../import-fixtures/mid2.cash', import.meta.url), { encoding: 'utf-8' }), sourceFile: 'mid2.cash', }, ], + sources: { + 'leaf.cash': readImportFixture('leaf.cash'), + 'mid1.cash': readImportFixture('mid1.cash'), + 'mid2.cash': readImportFixture('mid2.cash'), + }, }, fingerprint: '316a3305152ec0695bf80303736c79dd1f9cc2f1dbccf57d9965094401363307', }, diff --git a/packages/cashc/test/global-definitions.test.ts b/packages/cashc/test/global-definitions.test.ts index 8560e86cb..f7263967d 100644 --- a/packages/cashc/test/global-definitions.test.ts +++ b/packages/cashc/test/global-definitions.test.ts @@ -291,9 +291,9 @@ describe('Inlining and shared definitions', () => { expect(artifact.debug?.functions).toContainEqual(expect.objectContaining({ name: 'assertPositive', sourceFile: 'helpers.cash', - source: importedSource, requires: [expect.objectContaining({ line: 2, message: 'must be positive' })], })); + expect(artifact.debug?.sources).toEqual({ 'helpers.cash': importedSource }); expect(artifact.debug?.functions?.[0].id).toBeUndefined(); expect(artifact.debug?.inlineRanges).toMatch(/^\d+:\d+:assertPositive$/); }); @@ -368,9 +368,46 @@ describe('Global constants', () => { expect(artifact.debug?.functions?.[0]).toMatchObject({ name: 'IMPORTED_HASH', kind: 'constant', - source: importedSource, sourceFile: 'constants.cash', }); + expect(artifact.debug?.sources).toEqual({ 'constants.cash': importedSource }); + }); + + it('keeps the text of an imported file once, however many of its definitions are used', () => { + const importedSource = ` + int constant FIRST = 1; + int constant SECOND = 2; + int constant THIRD = 3; + function addFirst(int a) returns (int) { return a + FIRST; }`; + const source = ` + import "./constants.cash"; + contract Imported(int x) { + function spend() { + require(addFirst(x) == SECOND + THIRD); + } + }`; + + const artifact = compileString(source, { files: { './constants.cash': importedSource } }); + const frames = artifact.debug?.functions ?? []; + expect(frames.map((frame) => frame.name).sort()).toEqual(['FIRST', 'SECOND', 'THIRD', 'addFirst']); + frames.forEach((frame) => { + expect(frame.sourceFile).toBe('constants.cash'); + expect(frame).not.toHaveProperty('source'); + }); + expect(artifact.debug?.sources).toEqual({ 'constants.cash': importedSource }); + expect(JSON.stringify(artifact).split('SECOND = 2').length - 1).toBe(1); + }); + + it('omits debug sources when nothing is imported', () => { + const source = ` + int constant LOCAL = 7; + contract Local(int x) { + function spend() { + require(x == LOCAL); + } + }`; + + expect(compileString(source).debug?.sources).toBeUndefined(); }); it('folds constant definitions to literals at compile time', () => { diff --git a/packages/cashc/test/import-fixtures/clash/mathlib/math.cash b/packages/cashc/test/import-fixtures/clash/mathlib/math.cash new file mode 100644 index 000000000..7428d3907 --- /dev/null +++ b/packages/cashc/test/import-fixtures/clash/mathlib/math.cash @@ -0,0 +1,3 @@ +function localDouble(int a) returns (int) { + return a * 2; +} diff --git a/packages/cashc/test/import-fixtures/clash/nm_clash_main.cash b/packages/cashc/test/import-fixtures/clash/nm_clash_main.cash new file mode 100644 index 000000000..d1927364f --- /dev/null +++ b/packages/cashc/test/import-fixtures/clash/nm_clash_main.cash @@ -0,0 +1,8 @@ +import "mathlib/math.cash"; +import "./mathlib/math.cash"; + +contract NodeModulesClash() { + function spend(int x) { + require(nmAdd(localDouble(x), 3) == 13); + } +} diff --git a/packages/cashc/test/import-fixtures/clash/node_modules/bar/node_modules/foo/lib/x.cash b/packages/cashc/test/import-fixtures/clash/node_modules/bar/node_modules/foo/lib/x.cash new file mode 100644 index 000000000..0e1276149 --- /dev/null +++ b/packages/cashc/test/import-fixtures/clash/node_modules/bar/node_modules/foo/lib/x.cash @@ -0,0 +1,4 @@ +function nestedCheck(int v) returns (int) { + require(v != 2, "fails in bar's copy of foo/lib/x.cash"); + return v; +} diff --git a/packages/cashc/test/import-fixtures/clash/node_modules/bar/y.cash b/packages/cashc/test/import-fixtures/clash/node_modules/bar/y.cash new file mode 100644 index 000000000..04ddc5b96 --- /dev/null +++ b/packages/cashc/test/import-fixtures/clash/node_modules/bar/y.cash @@ -0,0 +1,5 @@ +import "foo/lib/x.cash"; + +function viaBar(int v) returns (int) { + return nestedCheck(v); +} diff --git a/packages/cashc/test/import-fixtures/clash/node_modules/foo/lib/x.cash b/packages/cashc/test/import-fixtures/clash/node_modules/foo/lib/x.cash new file mode 100644 index 000000000..ad14c066e --- /dev/null +++ b/packages/cashc/test/import-fixtures/clash/node_modules/foo/lib/x.cash @@ -0,0 +1,4 @@ +function localCheck(int v) returns (int) { + require(v != 1, "fails in the local lib/x.cash"); + return v; +} diff --git a/packages/cashc/test/import-fixtures/clash/node_modules/foo/main.cash b/packages/cashc/test/import-fixtures/clash/node_modules/foo/main.cash new file mode 100644 index 000000000..a72194135 --- /dev/null +++ b/packages/cashc/test/import-fixtures/clash/node_modules/foo/main.cash @@ -0,0 +1,9 @@ +import "./lib/x.cash"; +import "bar/y.cash"; +import "lib/x.cash"; + +contract NodeModulesInsidePackage() { + function spend(int v) { + require(localCheck(v) + viaBar(v) + packageCheck(v) > 0); + } +} diff --git a/packages/cashc/test/import-fixtures/clash/node_modules/foo/node_modules/lib/x.cash b/packages/cashc/test/import-fixtures/clash/node_modules/foo/node_modules/lib/x.cash new file mode 100644 index 000000000..87dcfcabb --- /dev/null +++ b/packages/cashc/test/import-fixtures/clash/node_modules/foo/node_modules/lib/x.cash @@ -0,0 +1,4 @@ +function packageCheck(int v) returns (int) { + require(v != 3, "fails in the lib package's x.cash"); + return v; +} diff --git a/packages/cashc/test/imports.test.ts b/packages/cashc/test/imports.test.ts index 862522f8e..6a7178f6d 100644 --- a/packages/cashc/test/imports.test.ts +++ b/packages/cashc/test/imports.test.ts @@ -213,6 +213,41 @@ describe('Imports from node_modules (package imports)', () => { .toEqual(['mathlib/helper.cash', 'mathlib/main.cash']); }); + it('gives two different files that share a package path distinct provenance', () => { + // clash/nm_clash_main.cash imports the package mathlib/math.cash and a local ./mathlib/math.cash, + // whose short names are both 'mathlib/math.cash'; each must keep its own source in the artifact + const artifact = compileFile(fixture('clash/nm_clash_main.cash'), { disableInlining: true }); + const frames = artifact.debug?.functions ?? []; + const sourceFileOf = (name: string): string | undefined => frames.find((frame) => frame.name === name)?.sourceFile; + + expect(sourceFileOf('localDouble')).toEqual('mathlib/math.cash'); + expect(sourceFileOf('nmAdd')).toEqual('../node_modules/mathlib/math.cash'); + expect(artifact.debug?.sources).toEqual({ + 'mathlib/math.cash': readFixture('clash/mathlib/math.cash'), + '../node_modules/mathlib/math.cash': readFixture('node_modules/mathlib/math.cash'), + }); + }); + + it('keeps provenance distinct when a renamed file would take another file\'s name', () => { + // A contract inside node_modules names even its local files by package path. Its ./lib/x.cash and bar's + // nested copy of foo/lib/x.cash both start as 'foo/lib/x.cash'; renaming the local one to 'lib/x.cash' + // then meets the package lib/x.cash, which is renamed in turn + const artifact = compileFile(fixture('clash/node_modules/foo/main.cash'), { disableInlining: true }); + const frames = artifact.debug?.functions ?? []; + const sourceFileOf = (name: string): string | undefined => frames.find((frame) => frame.name === name)?.sourceFile; + + expect(sourceFileOf('localCheck')).toEqual('lib/x.cash'); + expect(sourceFileOf('nestedCheck')).toEqual('../bar/node_modules/foo/lib/x.cash'); + expect(sourceFileOf('packageCheck')).toEqual('node_modules/lib/x.cash'); + expect(sourceFileOf('viaBar')).toEqual('bar/y.cash'); + expect(artifact.debug?.sources).toEqual({ + 'lib/x.cash': readFixture('clash/node_modules/foo/lib/x.cash'), + '../bar/node_modules/foo/lib/x.cash': readFixture('clash/node_modules/bar/node_modules/foo/lib/x.cash'), + 'node_modules/lib/x.cash': readFixture('clash/node_modules/foo/node_modules/lib/x.cash'), + 'bar/y.cash': readFixture('clash/node_modules/bar/y.cash'), + }); + }); + it('throws when a package import cannot be found in any node_modules directory', () => { expect(() => compileFile(fixture('nm_missing_main.cash'))).toThrow(ImportResolutionError); expect(() => compileFile(fixture('nm_missing_main.cash'))).toThrow( diff --git a/packages/cashscript/src/debug-frame.ts b/packages/cashscript/src/debug-frame.ts index 234131c93..a46243291 100644 --- a/packages/cashscript/src/debug-frame.ts +++ b/packages/cashscript/src/debug-frame.ts @@ -16,6 +16,7 @@ import { RequireStatement, Script, bytecodeToScript, + getDebugFrameSource, parseAndResolveInlineRanges, sourceMapToLocationData, } from '@cashscript/utils'; @@ -68,7 +69,7 @@ const resolveFrameByBytecode = (artifact: Artifact, activeBytecode: string): Res const resolveDebugFrame = (artifact: Artifact, frame: DebugFrame): ResolvedFrame => ({ sourceMap: frame.sourceMap, - source: frame.source ?? artifact.source, + source: getDebugFrameSource(artifact.debug?.sources, frame) ?? artifact.source, sourceName: frame.sourceFile ?? `${artifact.contractName}.cash`, ipOffset: 0, // function bodies have no constructor-arg prefix; their ips start at 0 requires: frame.requires, diff --git a/packages/cashscript/test/debugging.test.ts b/packages/cashscript/test/debugging.test.ts index 36fe4f473..6977afa14 100644 --- a/packages/cashscript/test/debugging.test.ts +++ b/packages/cashscript/test/debugging.test.ts @@ -19,6 +19,7 @@ import { artifactTestFunctionIntermediateResults, artifactTestImportedFunctionDebugging, artifactTestImportedFunctionDebuggingDefined, + artifactTestImportedFunctionDebuggingLegacy, artifactTestMultiReturn, artifactTestMultilineFunctionRequire, artifactTestNestedFunctions, @@ -840,6 +841,9 @@ describe('Debugging tests - user-defined function frames', () => { const importedDefinedContract = new Contract(artifactTestImportedFunctionDebuggingDefined, [], { provider }); const importedDefinedUtxo = provider.addUtxo(importedDefinedContract.address, randomUtxo()); + const legacyContract = new Contract(artifactTestImportedFunctionDebuggingLegacy, [], { provider }); + const legacyUtxo = provider.addUtxo(legacyContract.address, randomUtxo()); + it('attributes a console.log inside an inlined function to the function source line', () => { const transaction = new TransactionBuilder({ provider }) .addInput(contractUtxo, contract.unlock.spend(5n)) @@ -1000,6 +1004,21 @@ describe('Debugging tests - user-defined function frames', () => { expect(transaction).toFailRequireWith('Failing statement: require(value > 0, "value must be positive")'); }); + it('still debugs an artifact whose imported frames carry their own source, as 0.14.0-next pre-releases wrote them', () => { + expect(artifactTestImportedFunctionDebuggingLegacy.debug?.sources).toBeUndefined(); + + const transaction = new TransactionBuilder({ provider }) + .addInput(legacyUtxo, legacyContract.unlock.spend(0n)) + .addOutput({ to: legacyContract.address, amount: 10000n }); + + expect(transaction).toFailRequireWith('function_helpers.cash:3 Require statement failed at input 0 in contract Test, function assertPositive (function_helpers.cash, line 3) with the following message: value must be positive.'); + expect(transaction).toFailRequireWith('Failing statement: require(value > 0, "value must be positive")'); + + const lockScript = transaction.getLibauthTemplate().scripts[getLockScriptName(legacyContract)].script; + expect(lockScript).toContain('>>> imported from function_helpers.cash'); + expect(lockScript).toContain('/* function assertPositive(int value) {'); + }); + it('binds multi-return values to destructuring targets in declared order', () => { const multiReturnContract = new Contract(artifactTestMultiReturn, [], { provider }); const multiReturnUtxo = provider.addUtxo(multiReturnContract.address, randomUtxo()); diff --git a/packages/cashscript/test/fixture/debugging/debugging_contracts.ts b/packages/cashscript/test/fixture/debugging/debugging_contracts.ts index 417f76198..9eafb3fd7 100644 --- a/packages/cashscript/test/fixture/debugging/debugging_contracts.ts +++ b/packages/cashscript/test/fixture/debugging/debugging_contracts.ts @@ -1,3 +1,4 @@ +import { Artifact } from '@cashscript/utils'; import { compileFile, compileString } from 'cashc/dist/internal.js'; const CONTRACT_TEST_FUNCTION_DEBUGGING = ` @@ -622,3 +623,16 @@ export const artifactTestImportedFunctionDebuggingDefined = compileFile( new URL('./function_importer.cash', import.meta.url), { disableInlining: true }, ); + +// The same artifact in the layout of 0.14.0-next pre-releases, where every imported frame carried the full +// text of its file rather than the artifact keeping it once in `debug.sources` +const withSourcesOnFrames = (artifact: Artifact): Artifact => { + const { sources, ...debug } = artifact.debug!; + const functions = debug.functions?.map((frame) => ( + frame.sourceFile === undefined ? frame : { ...frame, source: sources![frame.sourceFile] } + )); + return { ...artifact, debug: { ...debug, functions } }; +}; +export const artifactTestImportedFunctionDebuggingLegacy = withSourcesOnFrames( + artifactTestImportedFunctionDebuggingDefined, +); diff --git a/packages/utils/src/artifact.ts b/packages/utils/src/artifact.ts index ba2c34d41..4eb61684a 100644 --- a/packages/utils/src/artifact.ts +++ b/packages/utils/src/artifact.ts @@ -20,6 +20,7 @@ export interface DebugInformation { requires: readonly RequireStatement[]; // messages for failing `require` statements sourceTags?: string; // semantic tags for opcodes (e.g. loop update/condition ranges) functions?: readonly DebugFrame[]; // Debug metadata for each global definition (defined frames first, then inlined ones) + sources?: { readonly [sourceFile: string]: string }; // full text of each imported file, keyed by the frames' `sourceFile` inlineRanges?: string; // runs where inlined callables' bodies were emitted (see `generateInlineRanges`) } @@ -31,7 +32,7 @@ export interface DebugFrame { bytecode: string; // hex of the function body bytecode (exactly what OP_DEFINE stores and the VM runs) sourceMap: string; // frame-local source map (ips starting from 0) sourceTags?: string; // frame-local semantic tags for opcodes (e.g. loop update/condition ranges) - source?: string; // full text of the defining file; absent means the function lives in the contract's own source file + source?: string; // deprecated, 0.14.0-next pre-releases only: text of the defining file, now kept once in `debug.sources` sourceFile?: string; // originating file name for imported functions; absent means the contract's file logs: readonly LogEntry[]; // frame-local log entries requires: readonly RequireStatement[]; // frame-local require statements @@ -90,6 +91,14 @@ export interface Artifact { fingerprint?: string; // SHA256 of the normalized bytecode pattern (BCH bytecode fingerprinting standard) } +// Full text of the file an imported frame was defined in; undefined for frames from the contract's own file. +// Artifacts from 0.14.0-next pre-releases carry the text on the frame itself rather than in `debug.sources` +export function getDebugFrameSource(sources: DebugInformation['sources'], frame: DebugFrame): string | undefined { + if (frame.source !== undefined) return frame.source; + if (frame.sourceFile === undefined) return undefined; + return sources?.[frame.sourceFile]; +} + export function formatArtifact(artifact: Artifact, format: 'json' | 'ts'): string { if (format === 'ts') { // We remove any undefined values to make the artifact serializable @@ -165,7 +174,11 @@ function formatObject( if (entries.length === 0) return '{}'; - const formatKey = (key: string): string => (format === 'json' ? JSON.stringify(key) : key); + // TS keys stay bare when they are identifiers; others (e.g. file names in `debug.sources`) are quoted + const formatKey = (key: string): string => { + if (format === 'json') return JSON.stringify(key); + return /^[A-Za-z_$][\w$]*$/.test(key) ? key : formatString(key, format); + }; const formatted = entries.map( ([key, value]) => `${formatKey(key)}: ${stringify(value, format, indentationLevel + 1)}`, ); diff --git a/packages/utils/src/bitauth-script.ts b/packages/utils/src/bitauth-script.ts index 1a137b7a8..09417700b 100644 --- a/packages/utils/src/bitauth-script.ts +++ b/packages/utils/src/bitauth-script.ts @@ -1,5 +1,5 @@ import { hexToBin } from '@bitauth/libauth'; -import { DebugFrame, DebugInformation } from './artifact.js'; +import { DebugFrame, DebugInformation, getDebugFrameSource } from './artifact.js'; import { encodeInt, range } from './data.js'; import { Op, Script, bytecodeToScript, scriptToBitAuthAsm } from './script.js'; import { parseSourceTags, sourceMapToLocationData } from './source-map.js'; @@ -13,6 +13,7 @@ export function formatBitAuthScript(debug: DebugInformation, sourceCode: string) sourceMap: debug.sourceMap, sourceTags: debug.sourceTags, functions: debug.functions, + sources: debug.sources, sourceLines, startLine: 1, endLine: sourceLines.length, @@ -27,6 +28,7 @@ interface WalkParams { sourceMap: string; sourceTags?: string; functions?: readonly DebugFrame[]; + sources?: DebugInformation['sources']; sourceLines: string[]; startLine: number; endLine: number; @@ -155,7 +157,7 @@ function renderSegments(segments: Segment[], params: WalkParams): Row[] { function deriveFunctionSectionLines(segments: Segment[], sourceLines: string[]): Set { const localFunctionSegments = segments.filter( - (segment): segment is FunctionDefinitionSegment => segment.kind === 'functionDefinition' && segment.frame.source === undefined, + (segment): segment is FunctionDefinitionSegment => segment.kind === 'functionDefinition' && segment.frame.sourceFile === undefined, ); return new Set(localFunctionSegments.flatMap(({ location }) => { @@ -202,7 +204,7 @@ function renderFunctionDefinition( ): RenderState { const { frame, location } = segment; const isImported = frame.sourceFile !== undefined; - const sourceLines = isImported ? frame.source!.split('\n') : context.sourceLines; + const sourceLines = isImported ? getDebugFrameSource(context.sources, frame)!.split('\n') : context.sourceLines; const headerRows = isImported ? [{ asm: '', comment: `>>> imported from ${frame.sourceFile}` }] diff --git a/packages/utils/test/artifact.test.ts b/packages/utils/test/artifact.test.ts new file mode 100644 index 000000000..60d745a2e --- /dev/null +++ b/packages/utils/test/artifact.test.ts @@ -0,0 +1,63 @@ +import { + Artifact, + DebugFrame, + formatArtifact, + getDebugFrameSource, +} from '../src/index.js'; + +const frame = (overrides: Partial): DebugFrame => ({ + name: 'f', + inputs: [], + bytecode: '', + sourceMap: '', + logs: [], + requires: [], + ...overrides, +}); + +describe('artifact utilities', () => { + describe('getDebugFrameSource()', () => { + it('should return undefined for a frame from the contract\'s own file', () => { + expect(getDebugFrameSource({ 'lib.cash': 'lib text' }, frame({}))).toBeUndefined(); + }); + + it('should read an imported frame\'s source from debug.sources', () => { + expect(getDebugFrameSource({ 'lib.cash': 'lib text' }, frame({ sourceFile: 'lib.cash' }))).toEqual('lib text'); + }); + + it('should prefer a source on the frame itself, as written by 0.14.0-next pre-releases', () => { + const legacyFrame = frame({ sourceFile: 'lib.cash', source: 'legacy text' }); + expect(getDebugFrameSource(undefined, legacyFrame)).toEqual('legacy text'); + }); + }); + + describe('formatArtifact()', () => { + const artifact: Artifact = { + contractName: 'Test', + constructorInputs: [], + abi: [], + bytecode: 'OP_1', + source: 'contract Test() {}', + debug: { + bytecode: '51', + sourceMap: '', + logs: [], + requires: [], + sources: { 'lib.cash': 'int constant A = 1;', '@scope/pkg/lib.cash': 'int constant B = 2;' }, + }, + compiler: { name: 'cashc', version: '0.14.0' }, + updatedAt: '2026-01-01T00:00:00.000Z', + }; + + it('should quote debug.sources file names as keys in TS output', () => { + const ts = formatArtifact(artifact, 'ts'); + expect(ts).toContain('\'lib.cash\': \'int constant A = 1;\''); + expect(ts).toContain('\'@scope/pkg/lib.cash\': \'int constant B = 2;\''); + expect(ts).toContain('contractName: \'Test\''); + }); + + it('should round-trip debug.sources through JSON output', () => { + expect(JSON.parse(formatArtifact(artifact, 'json')).debug.sources).toEqual(artifact.debug?.sources); + }); + }); +}); diff --git a/website/docs/compiler/artifacts.md b/website/docs/compiler/artifacts.md index 766dc907f..cdc37288b 100644 --- a/website/docs/compiler/artifacts.md +++ b/website/docs/compiler/artifacts.md @@ -28,6 +28,7 @@ interface Artifact { requires: RequireStatement[] // messages for failing `require` statements sourceTags?: string // semantic tags for opcodes (e.g. loop update/condition ranges) functions?: DebugFrame[] // debug metadata for each global definition (defined frames first, then inlined ones) + sources?: { [sourceFile: string]: string } // full source code of each imported file, stored once and referenced by the frames' `sourceFile` inlineRanges?: string // "startIp:endIp:name;..." — runs where inlined callables' bodies were emitted } updatedAt: string // Last datetime this artifact was updated (in ISO format) @@ -71,7 +72,7 @@ interface DebugFrame { bytecode: string; // hex-encoded bytecode of the function body (exactly what OP_DEFINE stores) sourceMap: string; // source map of the function body (instruction pointers starting from 0) sourceTags?: string; // semantic tags for opcodes within the function body - source?: string; // full source code of the defining file (only present for imported functions) + source?: string; // deprecated: only written by 0.14.0-next pre-releases, newer artifacts keep the file's source once in `debug.sources` sourceFile?: string; // file name the function is imported from (absent for the contract's own file) logs: LogEntry[]; // log entries within the function body requires: RequireStatement[]; // messages for failing `require` statements within the function body diff --git a/website/docs/releases/release-notes.md b/website/docs/releases/release-notes.md index 9b6f938e6..32adddce2 100644 --- a/website/docs/releases/release-notes.md +++ b/website/docs/releases/release-notes.md @@ -15,6 +15,7 @@ This release contains several breaking changes, please refer to the [migration n - :hammer_and_wrench: Update `compileString` to take an optional `files` object for filesystem-free import resolution. - :hammer_and_wrench: Unused variables that are not marked `unused` now produce a compiler warning instead of a compilation error. Warnings are printed with `console.warn`, or passed to the new `warningListener` compiler option. - :hammer_and_wrench: Add a compiler warning for values assigned to a variable that are never read afterwards. +- :hammer_and_wrench: Artifacts keep the source code of each imported file once, in `debug.sources`, which the debug frames of imported functions and constants refer to by their `sourceFile`. - :bug: Fix bug where date literal parsing was different per locale, it now uses UTC. - :racehorse: Add new `OP_SWAP OP_MUL`, `OP_NOT OP_NOT` and `TO_ALTSTACK OP_FROMALTSTACK` optimisations. - :racehorse: Greatly improve compiler speed for very large contracts.