feat(lib): canonical asset hashes behind the canonicalAssetHashes feature flag

[vincenthsh]

Description

Closes #322. Stacked on #321 — #321 has merged and this branch is rebased onto current main; the diff is now the single canonical-hash commit.

Adds the canonical entry-framed asset hash as a canonicalAssetHashes feature flag (FUTURE_FLAGS: enabled for new projects by cdktn init, opt-in via cdktf.json context for existing projects, becomes the default at the next major). The legacy scheme — including #321's compatibility-preserving symlink handling — stays untouched as the default.

The canonical representation

Modeled on git trees and Nix NAR, which serialize a full metadata model rather than payload framing alone. Every record contains what affects the emitted artifact:

entry	frame
file	F <mode> <relPath>\0<size>\0 + content
symlink	L <mode> <relPath>\0<target byte length>\0 + target
directory (incl. empty)	D <relPath>\0

• <mode> is the octal permission mask (0o7777 bits) — exactly the bits archiveSync preserves in zip external attributes, closing the hole found in review where 0644 → 0755 changed archive bytes but not the hash.
• Directories contribute explicit records (no mode — neither archiveSync nor copySync preserves directory permissions), so adding/removing an empty directory is visible.
• Entries are framed in sorted directory order with /-separated relative paths; a symlink at the root is followed, matching how the asset source path is opened when the artifact is emitted.

Acceptance criteria from #322

Each has a dedicated test in packages/cdktn/test/canonical-asset-hash.test.ts:

• File rename changes the canonical hash (and a paired assertion that legacy cannot see it)
• Entry-boundary shifts change the canonical hash
• File/symlink swaps and symlink retargeting change the canonical hash
• 0644 → 0755 changes the canonical hash
• Adding/removing an empty directory changes the canonical hash
• Identical logical trees hash deterministically (two locations + repeated runs)
• Legacy hashing remains available (flag off; Testing.app({ enableFutureFlags: false }) covers the compat case per the features.ts test rule)

Testing

Full cdktn suite green (464 passing; the pre-existing environmental matchers.test.ts → toPlanSuccessfully failure shells out to a real terraform plan and is unrelated). jsii build green. Docs for the flag are being handled separately in the docs repository (the stacked docs PR #324 was closed in favor of that).

Checklist

• I have updated the PR title to match CDKTN's style guide
• I have run the linter on my code locally
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation if applicable (stacked docs PR follows)
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works if applicable
• New and existing unit tests pass locally with my changes

🤖 Generated with Claude Code

[sakul-learning]

Two emitted-artifact/hash consistency issues need resolution; details are inline. I’ll post the configured-check and test-gap summary separately.

[sakul-learning]

Testing and coverage evaluation

All configured checks passed at 9d97256b344349da0a8218cb369c83e0892f0625:

• pnpm exec jest packages/cdktn/test/validations.test.ts --runInBand — 1 suite, 31 tests, 9 snapshots passed.
• pnpm exec nx build cdktn — passed with 0 errors and 0 warnings.
• pnpm exec nx test cdktn --runInBand — 40 suites, 465 tests, and 288 snapshots passed.

The canonical hash suite runs through the normal Nx/Jest target and provides useful behavioral coverage for renames, entry-boundary shifts, permission changes, empty directories, file/symlink distinctions, symlink retargeting, and deterministic trees.

Two output-level gaps remain and correspond to the inline correctness findings:

1. The empty-directory test covers copySync/directory semantics but not AssetType.ARCHIVE, where archiveSync currently omits directory entries. An archive regression should establish that hash changes correspond to emitted ZIP changes.
2. The feature integration test covers TerraformAsset, but not TerraformModuleAsset, whose emitted tree is assembled separately in tmpDir. A module test should prove that only selected/copied module sources affect the automatic hash and that unrelated siblings do not cause asset-path churn.

Ponytail/artifact-value pass: the core framing tests earn their maintenance cost and run in normal CI. Some canonical symlink cases overlap the stacked #321 coverage, but they still exercise a separate implementation. I would prioritize the two missing emitted-artifact regressions over adding further helper-level cases.

No workflow files changed, and I found no new security issue in the touched code.

[sakul-learning]

The rebase onto merged #321 leaves both previously identified emitted-artifact/hash consistency blockers unresolved. Reposting them on the current diff.

[sakul-learning]

All previously requested changes are resolved at c79fc67.

• Canonical archive hashes now omit directory records that ZIP emission omits.
• Canonical TerraformModuleAsset hashing uses the staged emitted tree.
• archiveSync traversal is sorted to match canonical hash ordering, with deterministic reversed-enumeration coverage.
• Configured validation, build, and full cdktn test checks pass (40 suites, 473 tests, 288 snapshots).

Approved.