From 3b0125c2cb1749abcc12ebb2957b70f4a5b9f295 Mon Sep 17 00:00:00 2001 From: Mathieu Geukens Date: Thu, 24 Sep 2026 14:46:29 +0200 Subject: [PATCH] fix: store each imported file's source once per artifact Every debug frame of an imported function or constant carried the full text of its declaring file, so an artifact embedded that file once per distinct definition it used. The text now lives once in `debug.sources`, keyed by the frames' `sourceFile`. Readers resolve a frame's text through `getDebugFrameSource`, which still accepts the per-frame `source` of artifacts from earlier 0.14.0-next pre-releases. Since frames now share one entry per `sourceFile`, two different files must never get the same name. The short package path could collide with a local file or another installed copy of the package, so any name held by more than one imported file is replaced by each file's path relative to the contract, repeated until no name is shared. Names that don't clash are unchanged. TS artifacts quote object keys that are not identifiers, since the `debug.sources` keys are file names. Closes #449 Co-Authored-By: Claude Opus 5.5 (1M context) --- packages/cashc/src/compiler.ts | 1 + packages/cashc/src/dependency-resolution.ts | 51 ++++++++++++--- .../src/generation/GenerateTargetTraversal.ts | 7 ++- .../fixtures/import-fixtures/diamond.ts | 21 +++++-- .../cashc/test/global-definitions.test.ts | 41 +++++++++++- .../import-fixtures/clash/mathlib/math.cash | 3 + .../import-fixtures/clash/nm_clash_main.cash | 8 +++ .../bar/node_modules/foo/lib/x.cash | 4 ++ .../clash/node_modules/bar/y.cash | 5 ++ .../clash/node_modules/foo/lib/x.cash | 4 ++ .../clash/node_modules/foo/main.cash | 9 +++ .../node_modules/foo/node_modules/lib/x.cash | 4 ++ packages/cashc/test/imports.test.ts | 35 +++++++++++ packages/cashscript/src/debug-frame.ts | 3 +- packages/cashscript/test/debugging.test.ts | 19 ++++++ .../fixture/debugging/debugging_contracts.ts | 14 +++++ packages/utils/src/artifact.ts | 17 ++++- packages/utils/src/bitauth-script.ts | 8 ++- packages/utils/test/artifact.test.ts | 63 +++++++++++++++++++ website/docs/compiler/artifacts.md | 3 +- website/docs/releases/release-notes.md | 1 + 21 files changed, 296 insertions(+), 25 deletions(-) create mode 100644 packages/cashc/test/import-fixtures/clash/mathlib/math.cash create mode 100644 packages/cashc/test/import-fixtures/clash/nm_clash_main.cash create mode 100644 packages/cashc/test/import-fixtures/clash/node_modules/bar/node_modules/foo/lib/x.cash create mode 100644 packages/cashc/test/import-fixtures/clash/node_modules/bar/y.cash create mode 100644 packages/cashc/test/import-fixtures/clash/node_modules/foo/lib/x.cash create mode 100644 packages/cashc/test/import-fixtures/clash/node_modules/foo/main.cash create mode 100644 packages/cashc/test/import-fixtures/clash/node_modules/foo/node_modules/lib/x.cash create mode 100644 packages/utils/test/artifact.test.ts 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.