@nipe-solutions/flex-layout-codemod 2.0.0-beta.2 → 2.0.0-beta.4

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.
Files changed (5) hide show
  1. package/CHANGELOG.md +20 -0
  2. package/README.md +25 -138
  3. package/dist/cli.js +1206 -569
  4. package/dist/cli.js.map +1 -1
  5. package/package.json +7 -5
package/CHANGELOG.md CHANGED
@@ -1,5 +1,25 @@
1
1
  # Changelog
2
2
 
3
+ ## 2.0.0-beta.4
4
+
5
+ ### Minor Changes
6
+
7
+ - bf4d213: Add declared Tailwind v4 target profiles, prefix and breakpoint awareness, static configuration analysis, target environment reports, custom source breakpoint configuration, and shared generated-template validation for browser previews. Preserve exact media semantics and unknown source directives.
8
+
9
+ - Lower the CLI runtime requirement to Node 22.12, with Node 22 and 24 core/package CI coverage.
10
+ - Resolve declarative Tailwind v4 target profiles with static stylesheet analysis, prefix, breakpoint reset/removal, provenance, assumptions, and fingerprints.
11
+ - Generate prefix-first utilities and exact responsive variants; use named pixel minimums only with equivalent screen semantics. Compile regression output with Tailwind 4.3.3.
12
+ - Accept explicit source breakpoint media queries and priorities. Preserve unknown source aliases.
13
+ - Detect legacy `@config`, plugins, remote/unsafe imports, and source exclusions without executing project code. Reject detected configuration drift before writes.
14
+ - Share generated-template validation between CLI and browser preview; reject malformed proposals.
15
+ - Add target settings to the playground, configuration documentation, legacy Angular syntax fixtures, and a real not-found page with static 404 output.
16
+
17
+ ## 2.0.0-beta.3
18
+
19
+ ### Minor Changes
20
+
21
+ - ca82744: Expand the documentation site into a comprehensive migration reference with production-verified CLI, diagnostic, compatibility, report, and transformation contracts. Add review-first workflow guidance, target-specific explorers and examples, responsive documentation navigation, and keyboard-accessible code regions.
22
+
3
23
  ## 2.0.0-beta.2
4
24
 
5
25
  ### Minor Changes
package/README.md CHANGED
@@ -1,171 +1,58 @@
1
1
  # Angular Flex-Layout Codemod
2
2
 
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.
3
+ Angular Flex-Layout Codemod is a review-first CLI for migrating supported Angular Flex-Layout template directives to Tailwind CSS v4 or native CSS. Version 2 remains a prerelease.
4
4
 
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.
5
+ > Plan first. Review unresolved cases. Write only when you are ready.
6
6
 
7
- ## Why this exists
7
+ The codemod changes only cases for which it can produce a supported equivalent. When it cannot prove that boundary, it leaves the source in place and reports a diagnostic instead of guessing.
8
8
 
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.
9
+ Read the [detailed documentation](https://angular-flex-layout-codemod.nipesolutions.com/docs), or try a single template in the separate [browser playground](https://angular-flex-layout-codemod.nipesolutions.com/#playground).
10
10
 
11
- ## Compatibility at a glance
11
+ ## Requirements and installation
12
12
 
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
-
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
-
17
- ## Quick start
18
-
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:
13
+ The CLI requires Node.js 22.12 or newer (tested on Node 22 and 24). This runtime can differ from your legacy Angular build runtime; the codemod reads source without loading the application dependencies. Install the current beta as an exact development dependency so your package manifest and lockfile retain the reviewed version:
30
14
 
31
15
  ```bash
32
16
  npm install --save-dev --save-exact @nipe-solutions/flex-layout-codemod@beta
33
17
  ```
34
18
 
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.
36
-
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.
19
+ See [Installation and requirements](https://angular-flex-layout-codemod.nipesolutions.com/docs/installation) for the project-baseline checklist.
46
20
 
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.
21
+ ## Plan, review, write
48
22
 
49
- After reviewing the report and committing or branching your work, apply the migration in place:
23
+ Create a plan and an optional JSON report without changing project templates or stylesheets:
50
24
 
51
25
  ```bash
52
- npx flex-layout-codemod ./src --target tailwind --write
26
+ npx flex-layout-codemod ./src --target tailwind --tailwind-stylesheet ./src/styles.css --plan --report ./reports/flex-layout.json
53
27
  ```
54
28
 
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.
29
+ The Tailwind stylesheet is optional. Supplying it lets the codemod respect a project-specific v4 prefix and breakpoint configuration. See [target configuration](https://angular-flex-layout-codemod.nipesolutions.com/docs/configuration), [responsive mapping](https://angular-flex-layout-codemod.nipesolutions.com/docs/configuration#responsive-mapping), and the [safety model](https://angular-flex-layout-codemod.nipesolutions.com/docs/safety).
56
30
 
57
- ### Native CSS companion stylesheet
31
+ Review the proposed output and every unresolved diagnostic. The report is the command's intentional filesystem output in plan mode.
58
32
 
59
- Use the native CSS target when the documented Flex-only surface is appropriate:
33
+ Apply the reviewed Tailwind CSS plan explicitly:
60
34
 
61
35
  ```bash
62
- npx flex-layout-codemod ./src --target css --stylesheet ./src/flex-layout-migration.css --write
36
+ npx flex-layout-codemod ./src --target tailwind --tailwind-stylesheet ./src/styles.css --write
63
37
  ```
64
38
 
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.
39
+ For native CSS output, target limits, output paths, and recovery behavior, follow the [migration workflow](https://angular-flex-layout-codemod.nipesolutions.com/docs/workflow). Keep the migration on a clean branch and review the resulting diff and application tests.
66
40
 
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.
41
+ ## Documentation
68
42
 
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:
74
-
75
- ```html
76
- <!-- input -->
77
- <div fxLayout="column" fxLayoutGap="4"></div>
78
-
79
- <!-- output -->
80
- <div class="flex flex-col box-border gap-[4px]"></div>
81
- ```
82
-
83
- Literal Grid containers and children use compiler-verified arbitrary properties when no exact built-in utility exists:
84
-
85
- ```html
86
- <!-- input -->
87
- <section gdColumns="12rem 1fr" gdGap="1rem"><div gdColumn="2"></div></section>
88
-
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:
94
-
95
- ```bash
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
101
- ```
102
-
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`:
106
-
107
- ```bash
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>
120
- ```
121
-
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.
123
-
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:
125
-
126
- ```html
127
- <div [fxFlex]="basis"></div>
128
- ```
129
-
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.
133
-
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
- ```
149
-
150
- `--allow-unresolved` changes only the final exit code; it does not hide diagnostics or alter the migration output.
151
-
152
- ## Known boundaries
153
-
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.
155
-
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.
43
+ - [Migration guide](https://angular-flex-layout-codemod.nipesolutions.com/docs)
44
+ - [Compatibility by target and directive](https://angular-flex-layout-codemod.nipesolutions.com/docs/compatibility)
45
+ - [Diagnostics and remediation](https://angular-flex-layout-codemod.nipesolutions.com/docs/diagnostics)
46
+ - [Complete CLI reference](https://angular-flex-layout-codemod.nipesolutions.com/docs/cli)
47
+ - [JSON reports and CI](https://angular-flex-layout-codemod.nipesolutions.com/docs/reports)
48
+ - [Safety, transactions, and recovery](https://angular-flex-layout-codemod.nipesolutions.com/docs/safety)
157
49
 
158
50
  ## Contributing and support
159
51
 
160
- The repository requires Node.js 24 and npm 11.
161
-
162
- ```bash
163
- npm ci
164
- npm run verify
165
- ```
52
+ Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request. Use [GitHub Issues](https://github.com/NIPE-Solutions/flex-layout-migrator/issues) for reproducible, redacted migration cases. Report vulnerabilities only through [GitHub private vulnerability reporting](https://github.com/NIPE-Solutions/flex-layout-migrator/security/advisories/new); see [SECURITY.md](SECURITY.md) and [support guidance](docs/SUPPORT.md).
166
53
 
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).
54
+ Maintainers should follow the reviewed [release process](docs/architecture/release-process.md).
168
55
 
169
56
  ## License
170
57
 
171
- MIT
58
+ [MIT](LICENSE)