@nipe-solutions/flex-layout-codemod 2.0.0-beta.1 → 2.0.0-beta.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +15 -0
- package/README.md +118 -47
- package/dist/cli.js +8736 -4139
- package/dist/cli.js.map +1 -1
- package/package.json +30 -3
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,20 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 2.0.0-beta.2
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- 89c6f92: Make migration planning the default, require `--write` to apply project changes, and publish schema-2 reports with explicit execution and application state.
|
|
8
|
+
- 77391e3: Launch the public documentation site and browser-only single-template migration playground, and point package metadata to the production documentation homepage.
|
|
9
|
+
- f058c0b: Add opt-in Tailwind conversion for the archived orientation breakpoints and project-configured print fallback behavior.
|
|
10
|
+
- 40e3719: Add an explicit native CSS target that updates templates and one owned companion stylesheet as a recoverable transaction.
|
|
11
|
+
- 029562c: Add opt-in migration of safe literal responsive image sources to native picture markup with atomic template validation and report-based review locations.
|
|
12
|
+
- 6f8ef7a: Convert literal Angular Flex-Layout Grid directives, including standard responsive aliases, when Tailwind compiler output and element ownership prove an exact migration.
|
|
13
|
+
|
|
14
|
+
### Patch Changes
|
|
15
|
+
|
|
16
|
+
- 4715a71: Add an executable compatibility inventory and rewrite beta onboarding around safe previews, pinned team installation, exact support boundaries, and copyable CLI workflows.
|
|
17
|
+
|
|
3
18
|
## 2.0.0-beta.1
|
|
4
19
|
|
|
5
20
|
### Minor Changes
|
package/README.md
CHANGED
|
@@ -1,90 +1,161 @@
|
|
|
1
1
|
# Angular Flex-Layout Codemod
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Version 2 remains a prerelease. This beta migrates supported Angular Flex-Layout template attributes to Tailwind CSS v4 utilities. It uses the Angular compiler and source-range edits, preserving unrelated template text, comments, interpolation, control flow, and line endings.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
Documentation and the single-template playground are available at [angular-flex-layout-codemod.nipesolutions.com](https://angular-flex-layout-codemod.nipesolutions.com). The playground previews Tailwind or native CSS output entirely in browser memory; your template is not sent to a server or persisted. Only the installed CLI performs project discovery, project validation, reporting, transactional writes, rollback, and multi-file work.
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
## Why this exists
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
Angular Flex-Layout is archived. Replacing it safely requires more than substituting class names: responsive aliases, display restoration, existing classes, inline styles, and runtime bindings can change the result. This codemod converts only cases it can represent exactly and leaves the rest in place with diagnostics for review.
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
## Compatibility at a glance
|
|
12
12
|
|
|
13
|
-
|
|
13
|
+
Tailwind CSS v4 remains the default target. A native CSS target is available with `--target css --stylesheet <path>` for exactly eight Flex semantic families at base and the 13 standard viewport aliases. Grid, visibility, responsive class/style, orientation, print, and custom aliases remain preserved for CSS. Conversion is deliberately limited: dynamic bindings, ambiguous responsive precedence, unsafe class or style ownership, and unsupported directives are preserved for review.
|
|
14
14
|
|
|
15
|
-
|
|
15
|
+
The complete directive-by-directive status, including grid, image, breakpoint, and class/style boundaries, is in [docs/compatibility.md](docs/compatibility.md). Treat that reference as the beta’s compatibility contract.
|
|
16
16
|
|
|
17
|
-
|
|
18
|
-
<!-- input -->
|
|
19
|
-
<div ngClass.sm="flex items-center"></div>
|
|
20
|
-
<div ngStyle.lt-md="font-size.px: 14; color: #334155"></div>
|
|
17
|
+
## Quick start
|
|
21
18
|
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
19
|
+
Evaluate the published beta without installing it. This safely previews the migration and does not write templates:
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
npx @nipe-solutions/flex-layout-codemod@beta ./src
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
Read the terminal summary and diagnostics before applying any migration. A clean Git worktree makes the resulting template diff easy to inspect.
|
|
26
|
+
|
|
27
|
+
## Install for a team or CI
|
|
28
|
+
|
|
29
|
+
Install the beta as an exact development dependency. `--save-exact` records the prerelease resolved from the `beta` tag, so the package manifest and lockfile keep the team on that reviewed version:
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
npm install --save-dev --save-exact @nipe-solutions/flex-layout-codemod@beta
|
|
29
33
|
```
|
|
30
34
|
|
|
31
|
-
|
|
35
|
+
Use `npm ci` in CI to install the committed lockfile. The package exposes the `flex-layout-codemod` executable through the local npm binary path; no global installation is required.
|
|
32
36
|
|
|
33
|
-
|
|
37
|
+
## Preview, review, and apply
|
|
38
|
+
|
|
39
|
+
Preview the local dependency and write a JSON report for review:
|
|
40
|
+
|
|
41
|
+
```bash
|
|
42
|
+
npx flex-layout-codemod ./src --report ./reports/flex-layout.json
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
The command plans and validates without changing project templates or stylesheets by default. `--report` is intentional reporting output: the report is an explicit side effect and is written atomically in both plan and write modes, even though a plan does not create template-output directories.
|
|
46
|
+
|
|
47
|
+
If any template has a parse error, no project changes are applied and terminal output labels the remaining edits as planned. In the default plan mode, `application` remains `{ "status": "skipped", "reason": "plan-only" }` even when parsing fails. When `--write` was requested, a parse error produces `{ "status": "skipped", "reason": "parse-errors" }`. Neither outcome presents proposed template or stylesheet actions as applied writes.
|
|
48
|
+
|
|
49
|
+
After reviewing the report and committing or branching your work, apply the migration in place:
|
|
50
|
+
|
|
51
|
+
```bash
|
|
52
|
+
npx flex-layout-codemod ./src --target tailwind --write
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
`--write` explicitly applies the validated plan. Without it, `--output` names only the proposed destination. With it, omitting `--output` applies changed templates in place; add `--output ./migrated-src` to apply them elsewhere. Review the Git diff before accepting the changes. If an in-place run is unwanted, inspect `git diff` before taking further action, then restore only the intended files deliberately through your normal Git workflow from a clean worktree or committed branch.
|
|
56
|
+
|
|
57
|
+
### Native CSS companion stylesheet
|
|
58
|
+
|
|
59
|
+
Use the native CSS target when the documented Flex-only surface is appropriate:
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
npx flex-layout-codemod ./src --target css --stylesheet ./src/flex-layout-migration.css --write
|
|
63
|
+
```
|
|
34
64
|
|
|
35
|
-
|
|
65
|
+
The migration updates templates and the one named companion stylesheet as a transaction. It owns only the marked `flex-layout-codemod` block, preserves handwritten CSS surrounding that block, retains unmatched owned rules because the stylesheet may serve templates outside the selected invocation, and keeps shared rules deduplicated across files. The current CLI has no complete-project pruning mode. On ordinary failures or handled interruption it rolls the changed templates and stylesheet back together.
|
|
66
|
+
|
|
67
|
+
The stylesheet path may use any filename accepted as a regular file. If it ends in `.html` and is inside a folder input, that exact selected path is excluded from template discovery so reruns remain byte-idempotent. Stylesheet, template, and JSON-report destinations must remain physically distinct; existing file identity and conservative case/Unicode-normalized aliases for missing paths are checked before application and again before report replacement.
|
|
68
|
+
|
|
69
|
+
No filesystem workflow can promise durable rollback after abrupt process termination, power loss, or a storage failure. If the command reports unconfirmed recovery, stop and inspect the listed paths, reconcile them with Git or a verified backup, then rerun only after the project is consistent.
|
|
70
|
+
|
|
71
|
+
## Examples
|
|
72
|
+
|
|
73
|
+
This converted example is the same static layout and gap case exercised by the migration fixtures:
|
|
36
74
|
|
|
37
75
|
```html
|
|
38
76
|
<!-- input -->
|
|
39
|
-
<div fxLayout="column"
|
|
77
|
+
<div fxLayout="column" fxLayoutGap="4"></div>
|
|
40
78
|
|
|
41
79
|
<!-- output -->
|
|
42
|
-
<div
|
|
43
|
-
class="flex flex-col box-border hidden [@media_screen_and_(min-width:_600px)_and_(max-width:_959.98px)]:flex"
|
|
44
|
-
></div>
|
|
80
|
+
<div class="flex flex-col box-border gap-[4px]"></div>
|
|
45
81
|
```
|
|
46
82
|
|
|
47
|
-
|
|
83
|
+
Literal Grid containers and children use compiler-verified arbitrary properties when no exact built-in utility exists:
|
|
48
84
|
|
|
49
|
-
|
|
85
|
+
```html
|
|
86
|
+
<!-- input -->
|
|
87
|
+
<section gdColumns="12rem 1fr" gdGap="1rem"><div gdColumn="2"></div></section>
|
|
50
88
|
|
|
51
|
-
|
|
89
|
+
<!-- output -->
|
|
90
|
+
<section class="grid [grid-template-columns:12rem_1fr] [grid-gap:1rem]"><div class="[grid-column:2]"></div></section>
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
Orientation and print conversion require explicit source-configuration evidence. These flags assert settings you have already verified in the Angular application's Flex-Layout configuration; the codemod does not discover them:
|
|
52
94
|
|
|
53
95
|
```bash
|
|
54
|
-
|
|
96
|
+
# Source uses addOrientationBps: true and printWithBreakpoints: ['md', 'handset']
|
|
97
|
+
npx flex-layout-codemod ./src --orientation-breakpoints --print-with-breakpoints md,handset --write
|
|
98
|
+
|
|
99
|
+
# Source explicitly uses printWithBreakpoints: []
|
|
100
|
+
npx flex-layout-codemod ./src --print-with-breakpoints none --write
|
|
55
101
|
```
|
|
56
102
|
|
|
57
|
-
|
|
103
|
+
With orientation enabled, all nine archived aliases are available: `handset`, `handset.portrait`, `handset.landscape`, `tablet`, `tablet.portrait`, `tablet.landscape`, `web`, `web.portrait`, and `web.landscape`. Print conversion reproduces configured responsive fallback values, while an explicit `.print` value takes precedence.
|
|
104
|
+
|
|
105
|
+
Responsive image migration is a separate opt-in because introducing `<picture>` changes the image's parent and may affect CSS or test selectors. After reviewing that risk, enable literal standard-breakpoint sources with `--responsive-images`:
|
|
58
106
|
|
|
59
107
|
```bash
|
|
60
|
-
flex-layout-codemod ./src --
|
|
108
|
+
npx flex-layout-codemod ./src --responsive-images --report ./reports/flex-layout.json --write
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
```html
|
|
112
|
+
<!-- input -->
|
|
113
|
+
<img src="hero.png" src.lt-sm="hero-mobile.png" alt="Hero" />
|
|
114
|
+
|
|
115
|
+
<!-- output -->
|
|
116
|
+
<picture
|
|
117
|
+
><source media="screen and (max-width: 599.98px)" srcset="hero-mobile.png" />
|
|
118
|
+
<img src="hero.png" alt="Hero"
|
|
119
|
+
/></picture>
|
|
61
120
|
```
|
|
62
121
|
|
|
63
|
-
Only
|
|
122
|
+
Only literal values using the 13 standard viewport aliases convert. Dynamic values, orientation, print, custom aliases, ambiguous URLs, structural directives on the image, and images already inside `<picture>` remain unchanged. Use the JSON report's file paths and source offsets to review every converted `imgSrc` occurrence and check selectors that assume the `<img>` has its former parent. Interactive file navigation is deferred to the CLI upgrade.
|
|
64
123
|
|
|
65
|
-
|
|
124
|
+
This fixture is intentionally preserved because the value is a runtime Angular expression. The report records a `dynamic-binding` review diagnostic and the source remains unchanged:
|
|
66
125
|
|
|
67
|
-
```
|
|
68
|
-
|
|
126
|
+
```html
|
|
127
|
+
<div [fxFlex]="basis"></div>
|
|
69
128
|
```
|
|
70
129
|
|
|
71
|
-
|
|
130
|
+
## Reports and exit codes
|
|
131
|
+
|
|
132
|
+
Reports use JSON schema version `2` and include required `mode` and `application` fields alongside per-file results, diagnostics, and a summary. `mode` records whether `plan` or `write` was requested. `application` records whether project changes were `applied` or were `skipped` because the run was plan-only or parsing failed. File `changed` values and stylesheet actions always describe proposed destination differences; consult `application` to determine whether those proposals reached the project.
|
|
72
133
|
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
|
134
|
+
Schema 2 removes the schema-1 `dryRun` field. Existing scripts that relied on implicit writes must add `--write`. Existing preview scripts must remove `--dry-run`, because planning is now the default and the obsolete option is rejected. Report consumers must replace `dryRun` checks with `mode` plus the required `application` state.
|
|
135
|
+
|
|
136
|
+
The default exit policy is strict:
|
|
137
|
+
|
|
138
|
+
| Code | Meaning |
|
|
139
|
+
| ---: | ---------------------------------------------------------------------------------------------------------- |
|
|
140
|
+
| `0` | Planning or application completed cleanly, or unresolved work was accepted with `--allow-unresolved`. |
|
|
141
|
+
| `1` | Configuration, parsing, project I/O, transaction, report writing, or an internal invariant failed. |
|
|
142
|
+
| `2` | Planning or application completed safely, but `review`, `unsupported`, or `invalid` results remain strict. |
|
|
143
|
+
|
|
144
|
+
For an informational CI report that accepts unresolved work while retaining every diagnostic, use:
|
|
145
|
+
|
|
146
|
+
```bash
|
|
147
|
+
npx flex-layout-codemod ./src --report ./reports/flex-layout.json --allow-unresolved
|
|
148
|
+
```
|
|
78
149
|
|
|
79
|
-
|
|
150
|
+
`--allow-unresolved` changes only the final exit code; it does not hide diagnostics or alter the migration output.
|
|
80
151
|
|
|
81
|
-
|
|
152
|
+
## Known boundaries
|
|
82
153
|
|
|
83
|
-
|
|
154
|
+
Tailwind CSS v4 remains the default target. A native CSS target is available with `--target css --stylesheet <path>` for exactly eight Flex semantic families at base and the 13 standard viewport aliases. Grid, visibility, responsive class/style, orientation, print, and custom aliases remain preserved for CSS. Responsive `imgSrc` remains an independent opt-in native `<picture>` migration. See [docs/compatibility.md](docs/compatibility.md) for exact supported forms and diagnostic codes before planning a large migration.
|
|
84
155
|
|
|
85
|
-
The
|
|
156
|
+
The CSS target does not inspect project styles, Tailwind configuration, Sass, or Less; it updates only its one owned companion block. Dynamic Angular bindings are not evaluated.
|
|
86
157
|
|
|
87
|
-
##
|
|
158
|
+
## Contributing and support
|
|
88
159
|
|
|
89
160
|
The repository requires Node.js 24 and npm 11.
|
|
90
161
|
|
|
@@ -93,7 +164,7 @@ npm ci
|
|
|
93
164
|
npm run verify
|
|
94
165
|
```
|
|
95
166
|
|
|
96
|
-
|
|
167
|
+
Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request. Security reports belong in [GitHub private vulnerability reporting](https://github.com/NIPE-Solutions/flex-layout-migrator/security/advisories/new); other support routes are listed in [docs/SUPPORT.md](docs/SUPPORT.md). Maintainers should follow the reviewed [release process](docs/architecture/release-process.md).
|
|
97
168
|
|
|
98
169
|
## License
|
|
99
170
|
|