Setup TypeScript Deep Modules — Experimental

What it does

The experimental setup-ts-deep-modules skill makes a specific TypeScript packaging convention enforceable: files at a package root are public entry points, while subfolders hold private implementation. Code inside a package can use its internals; other packages must enter through the public root files. Multiple entry points are allowed, so the approach does not require one enormous barrel export. The source uses dependency-cruiser and merges existing configuration instead of replacing it. It also forbids dependency cycles and expects tests to exercise public boundaries. This is an architectural lint setup, not a TypeScript path-alias migration.

When to use it

• Prevent a web package from importing another package’s private parser implementation.
• Turn an agreed public-module convention into a repeatable CI check.
• Keep tests resilient to internal file moves by routing them through public entry points.

Step-by-step workflow

1. Inspect the package structure, existing lint configuration and package-manager conventions before choosing rule scopes.
2. Add dependency-cruiser as a development dependency only if it is not already available and preserve existing configuration.
3. Express public root files, private subfolders, allowed internal imports and cycle restrictions for the actual repository.
4. Wire the boundary check into the normal lint path and document where public interfaces live.
5. Prove pass, deliberate forbidden-import failure and pass again after removing the probe; retain no test violation in the finished tree.

Example request

Use setup-ts-deep-modules experimentally in our TypeScript monorepo. Package-root files are public and subfolders private. Preserve the existing dependency-cruiser rules and package-manager lockfile. Show one permitted public import and one forbidden cross-package internal import. Demonstrate that lint rejects the probe, remove it and rerun. Do not add tsconfig aliases or collapse every export into one barrel.

Worked example

Assume packages/cart/index.ts exports the supported cart API, while packages/cart/internal/totals.ts is private. A checkout package should import the root API; cart’s own code may use totals directly. A useful negative check adds a checkout import of that private file and confirms the boundary rule fails for that reason. Removing the probe must restore a passing check. If the initial check already fails because of an unrelated cycle, report and resolve the existing condition rather than claiming the new rule was demonstrated.

What you get

Merged import rules, a normal lint entry point and a documented, exercised public-module boundary.

How to evaluate the result

• A public cross-package import passes and a private one fails.
• The negative probe is removed and the final lint run passes.
• Existing rules and unrelated package settings remain intact.

What you need

A TypeScript repository, Node tooling, the project’s package manager and an agreed package layout. Existing boundary violations need a deliberate migration decision.

Setup and activation

Experimental source: this folder is under skills/in-progress and is not a stable-release recommendation. Its frontmatter disables automatic model invocation, so explicitly select it in a host that supports that behavior. This directory reviewed source only; it did not install or execute the skill. Before adopting it, scan the exact version, inspect requested tools and permissions, and test on disposable non-sensitive inputs. A compatible instruction format does not establish identical host capabilities.

Limits and considerations

The convention may not fit every repository or generated-code layout. This in-progress skill does not prevent runtime misuse or validate business logic. Broad exceptions can nullify the intended boundary, so each exception needs review.

Related workflows

• Use codebase-design analysis to agree the boundary before enforcing it.
• Use behavior-level TDD to verify the public interface after internal refactoring.

License and reuse

MIT at repository level. Preserve copyright and license notices; check companion files and external dependencies for their own terms.

Further reading

• Publisher setup and compatibility instructions
• Reviewed source at immutable commit