feat(lib)!: add asset pipeline foundation types and hash utilities

[eduardomourar]

Related issue

Spin-off from #339

Description

Foundational layer for the asset pipeline, per the #380 scope discussion:

• IAsset, AssetOptions, AssetHashType — identity types. TerraformAsset now implements IAsset and consumes AssetHashType: SOURCE (default) hashes the source, CUSTOM uses an explicit assetHash, OUTPUT throws until bundling exists.
• IAssetPackaging + AssetPackaging.FILE/DIRECTORY/ZIP, with pack() taking a PackOptions struct (source, target, ignoreStrategy?) so it stays extensible without a breaking change. TerraformAsset packages through AssetPackaging and derives its on-disk layout and artifact name from producesDirectory/extension rather than a local switch.
• StagedAsset (assetHash, path, isDirectory) — publisher input, replaces the earlier FileAssetSource.
• IIgnoreStrategy + ExcludeIgnoreStrategy, and AssetHash.of() for content identity without staging. ignores() takes an IgnoreQuery (relativePath, isDirectory) so .gitignore/.dockerignore-style directory-only patterns are expressible; pruneExcludedDirectories lets a strategy opt into descending excluded directories for negation patterns; optional cacheKey supports future result caching.
• archiveSync gained an exclude predicate to match copySync, so packaging and hashing agree on what's excluded.
• AssetHash.of() pins to the canonical hash scheme, resolves relative paths against cdktf.json (matching TerraformAsset), and throws if both exclude and ignoreStrategy are passed.

Held back per #380: Docker/container asset types (DockerImageAssetSource, DockerImageAssetLocation, DockerCacheOption) and FileAssetLocation — these model synth-resolved locations that don't fit the publish-at-apply model this pipeline is built on.

This is the foundation PR (1 of 3) for the asset staging pipeline. Later PRs will add AssetStaging, TerraformAsset integration, and Docker bundling on top of these primitives.

Breaking changes

• TerraformAsset.assetHash is now readonly (required by implements IAsset). The generated setter is removed in Java, C#, Python, and Go. It was only ever assigned at construction, so this removes an assignment that would have desynced assetHash from path.

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
• 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

[so0k]

@sakul-learning — picking up your review threads from #339 (comment) here, since the shapes have moved into this slice.

On temporarily removing extraHash / bundling / assetHashType and their index.ts exports

I follow the reasoning, but I'm not sure I agree with pulling them.

The split into stacked PRs is a review-ergonomics device — it exists to keep each diff small enough to review properly, not to create independent release boundaries. The slices are intended to land together, so the enums and option shapes won't reach consumers ahead of the implementation that gives them meaning. The cross-language commitment you describe is real, but it's incurred at release, and there's no release in between.

Worth noting too that your recommendation was explicitly conditional on finishing the unification being too large for #339's scope — and the unified fingerprinting has since landed in d212d56, standardising on the existing MD5-derived identity rather than introducing the second SHA-256 walker. So the dual-path compatibility migration you were guarding against shouldn't materialise.

Stating the assumption explicitly so it's on the record rather than implied: if this foundation slice would ever ship on its own, ahead of the slices that implement it, your concern applies in full and we should revisit.

On symlinks

Your catch on #339 was a good one, and it's worth noting that this slice is on the right side of it. private/fs.ts keeps the lstatSync()-based walkers, and the behaviour is now documented rather than incidental:

Symlinks are recreated as symlinks rather than dereferenced, which keeps the copy consistent with hashPath (it hashes links by their target) and makes dangling links and link cycles harmless.

The new shouldExclude predicate threads through both the legacy and canonical schemes without touching symlink handling, so the #321 baseline is preserved here.

One gap in the same area: the new fixtures under test/fs/fixtures/test1/ (a local symlink and a dangling absolute one) aren't referenced by anything — test/fs/ contains no test file at all. That looks like exactly where the symlink coverage should land, and having the fixtures pre-staged makes it cheap.

On test quality

You already made this point on #339 — that the SOURCE vs OUTPUT tests asserted only toBeDefined() or hash length rather than the advertised contract — so treat this as an ack rather than a new finding. It carries directly into this slice: assets-types.test.ts is 280 lines asserting enum string values and that struct literals compile, which would pass against any implementation. Meanwhile excludeMatcher() and the shouldExclude threading are the genuinely new logic in this PR and currently have no tests or callers.

That's a very fixable shape of problem, and the groundwork is already there. The matcher's contract is well documented — I checked its stated limitations against 22 edge cases locally (bare *, **, ! negation, leading /, ./ prefixes, dir vs dirty/file, case sensitivity) and it behaves exactly as the docstring says. A behavioural suite over those cases plus the staged fixtures would lock it in, and it's a better use of the slice than the type-shape assertions currently there.

[eduardomourar]

Agreed. No release boundary between these slices, so keeping extraHash / bundling / assetHashType in place makes sense.

To back that up with real implementation, I'll fold in AssetStaging Core with no bundling: the AssetStaging class doing SOURCE/OUTPUT/CUSTOM hash resolution through the shared fingerprinting path (gated on canonicalAssetHashes, per the unification in d212d56), just without Docker bundling. That gives the types actual behavior instead of shipping ahead of it.

To keep that from bloating the PR, I'll move the Docker-specific bits — the docker* fields on DockerImageAssetSource and DockerCacheOption — into the Docker Bundling PR, since they've got no caller until bundling lands anyway.

So this PR ends up as: foundation types (minus Docker interfaces) + a working AssetStaging core (SOURCE/OUTPUT/CUSTOM, no bundling). Docker bundling PR gets the Docker interfaces plus the actual DockerImage/bind-mount/volume-copy execution.

@so0k and @jsteinich, could you both confirm if that is the approach we want to take? I know that is not the small API surface we had in mind, but, at least, we can release those slices separately if needed be.

[eduardomourar]

@jsteinich and @so0k, this is ready for review now fully based on the discussed from #380.

[jsteinich]

The trimmed assets.ts and the behavioural asset-hash.test.ts are big improvements. Wiring TerraformAsset through PACKAGING_BY_TYPE also gives IAssetPackaging a real consumer rather than shipping it ahead of one, which is better than what the delta asked for, and removing the unreferenced test/fs/fixtures/ closes an earlier thread.

Four notes below. The pack() signature is the one I'd want settled before merge, since it is public API. The canonical pinning is a decision worth making explicitly. The last two are cheap now and expensive later.

[jsteinich]

Thanks — all four items from the previous pass look good. PackOptions threads the strategy through to both copySync and archiveSync, and putting the shouldExclude check ahead of the lstatSync in the archive walk means excluding a directory correctly skips its whole subtree. The canonical pin, the conflicting-options throw, and cacheKey all read the way I'd hoped.

Two follow-ups on the new test, below. Both are fixed by the same rewrite.

[jsteinich]

Looks good to me.
What do you think @so0k ?

[so0k]

nitpicks, didn't get through it all (left draft comments where I haven't personally reviewed it again) - don't want to block this

[jsteinich]

Went through the latest round. The IgnoreQuery struct and the pruneExcludedDirectories opt-out both look right — carrying isDirectory from the walker's lstat is the only way a .gitignore-style strategy can honour directory-only patterns, and negation genuinely does require descending into an excluded parent.

Also confirmed the TerraformAsset refactor is behaviour-preserving for all three existing types: ARCHIVE resolves to "archive" + ".zip" exactly as the old ARCHIVE_NAME did, FILE and DIRECTORY keep basename, and producesDirectory maps onto the old type === DIRECTORY checks in both the path getter and _onSynthesize. canonical-asset-hash.test.ts is purely additive — nothing existing was rewritten.

Two notes below.

[jsteinich]

One more, on a change against main rather than against an earlier state of this PR.