aws / aws/jsii

Add --compile flag to jsii-rosetta markdown command

Open
#4,932 0 comments 0 reactions 0 assignees View on GitHub
feature-request p2
Dominant language
TypeScript
Stars
2.9k
Forks
267
Avg merge
1d 25m
Merged PRs (30d)
14

Description

## Describe the feature
Add a `--compile` flag to the `jsii-rosetta markdown` command that enables TypeScript compilation and type checking for code snippets, similar to the existing `extract` command.

## Use Case
The `markdown` command currently only does syntactic translation without type checking. This results in:
- Less accurate translations due to missing type information
- Undetected errors in documentation examples
- Inconsistent behavior compared to the `extract` command which supports `--compile`

For projects like AWS CDK generating polyglot documentation, compilation would improve translation accuracy and catch errors in examples.

## Proposed Solution
Add `--compile` and `--fail` flags to the markdown command, reusing the existing `Translator` class infrastructure:

```bash
# Enable compilation
npx jsii-rosetta markdown README.md --language python --compile

# Fail on compilation errors
npx jsii-rosetta markdown README.md --language python --compile --fail
```

Implementation would modify `src/main.ts` to add the CLI options and update `src/commands/convert.ts` to use the full `Translator` class instead of direct `SnippetTranslator`.

## Other Information
- Backwards compatible (compilation is opt-in)
- Reuses existing compilation infrastructure
- Aligns behavior with other jsii-rosetta commands
- Improves documentation quality through type checking

## Acknowledgements
- [x] I may be able to implement this feature request
- [ ] This feature might incur a breaking change

## CDK version used
N/A (jsii-rosetta feature)

## Environment details
macOS, Node.js, TypeScript

Contributor guide

Open the contributing guide

Research direction

Start in src/main.ts and src/commands/convert.ts, comparing the markdown command with the existing extract command and its --compile support. Trace how Translator differs from SnippetTranslator, then run the existing command tests or markdown command locally. Done means markdown accepts --compile and --fail, uses compilation when requested, and preserves current behavior by default.

Written by the indexing model from the issue text.

Assessment

Tech stack
node.js, typescript
Domain
cli, developer-experience
Issue type
Feature
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
52/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.