`semanticDiff()`

함수, 도구 분류

Compare two modules at the IR and reflection layer.

import { semanticDiff } from 'typeshade'

시그니처, 설명, 예제는 커밋 c66579bf의 컴파일러 소스에서 그대로 가져온 영어 원문입니다.

구문

function semanticDiff(
  a: ModuleDecl,
  b: ModuleDecl,
  opts: SemanticDiffOptions & { readonly transforms: readonly EmitPlugin[] },
): ClassifiedSemanticDiff;
function semanticDiff(
  a: ModuleDecl,
  b: ModuleDecl,
  opts?: SemanticDiffOptions,
): SemanticDiff;

매개변수

a ModuleDecl: the reference module, the development side when transforms is declared.
b ModuleDecl: the module to compare against it, the transformed side.
opts SemanticDiffOptions & { readonly transforms: readonly EmitPlugin[] }: the axes to disregard, names and declOrder by default, and optionally the declared transform pipeline.

반환값

ClassifiedSemanticDiff

the four buckets, and explained when transforms was declared.

설명

A textual diff of emitted source is hard to read once the optimizer and the production plugins have run; this comparison works above that noise.

It reports four buckets: the entry and vertex interface, the bind-group and layout resources, the constants (module consts, overrides, and the multiset of body literals), and the per-statement controlFlow skeleton. Empty in all four means the two modules agree on everything a host binds to and everything the code does. Each line is prefixed - for a fact only in a and + for one only in b, and isSemanticallyEqual is the all-empty test.

A pass that legitimately changes the program is not expected to be empty here. Inlining rewrites call sites and duplicates literals, which is exactly what the buckets report. Declare such a pass in transforms, the same plugin array the production emit takes, and every difference the declared pipeline provably causes moves into explained, one entry naming the plugin, the bucket and the line.

A line moves to explained only when applying that plugin’s own transformIR to the reference side actually removes the line from the diff. A regression that merely looks like an optimizer rewrite stays in its bucket, so a check that compares a development build against a production build fails only on the unexplained differences.

Text-stage plugins explain nothing, because the comparison never sees emitted text. Declaring the full production array is therefore safe: minify and aliasTypes contribute no explained entries and remove no coverage, so you can pass the array you actually ship.

Renaming with mangle produces no differences under the default options, because 'names' canonicalizes exactly the identifiers that pass is free to rewrite.

예제

import { semanticDiff, isSemanticallyEqual } from 'typeshade'
import { inline, obfuscate } from 'typeshade/emit-prod'

const d = semanticDiff(devModule, prodModule, { transforms: [inline(), ...obfuscate()] })
isSemanticallyEqual(d) // true when prod differs from dev only as the declared pipeline dictates
d.explained // [{ transform: 'inline', bucket: 'controlFlow', line: '…' }, …]