@maggioli-design-system/magma-codemods 2.0.0-beta.0

package/dist/surfaces/shared/attribute-ops.js

@@ -0,0 +1,62 @@
+/**
+ * Surface-agnostic transformation core. These functions take a parsed value
+ * (see {@link AttrValue}) plus the primitive parameters of a manifest rule and
+ * return an *outcome* describing what the surface should render — they never
+ * touch a concrete AST, so the logic is written and tested once.
+ */
+import { resolveBoolean } from './value-model.js';
+import { negateExprText } from './negate.js';
+/**
+ * Invert a boolean prop's value (category B). The new prop's value is the
+ * logical negation of the old one; `newDefault` decides whether that value can
+ * be omitted. `oldDefault` is intentionally unused — for a boolean prop the
+ * shorthand always means `true` regardless of the declared default.
+ */
+export const invertBoolean = (current, newDefault) => {
+    const resolved = resolveBoolean(current);
+    if (resolved.kind === 'literal') {
+        return outcomeForLiteral(!resolved.value, newDefault);
+    }
+    const negated = negateExprText(resolved.expr);
+    // The negation may collapse to a literal (e.g. the expr was `true`/`false`).
+    if (negated === 'true')
+        return outcomeForLiteral(true, newDefault);
+    if (negated === 'false')
+        return outcomeForLiteral(false, newDefault);
+    return { action: 'expr', expr: negated };
+};
+const outcomeForLiteral = (value, newDefault) => {
+    if (value === newDefault)
+        return { action: 'omit' };
+    return value ? { action: 'shorthandTrue' } : { action: 'explicitFalse' };
+};
+/**
+ * Remap an enum literal, validating the target against the component's v2 enum
+ * set when available. Dynamic values, map targets that are `null` (no 1:1
+ * replacement) and literals absent from the v2 set are flagged for the report
+ * instead of being rewritten blindly.
+ */
+export const remapEnum = (current, map, v2set) => {
+    if (current.kind === 'dynamic') {
+        return { action: 'flag', reason: 'dynamic value, cannot remap enum' };
+    }
+    if (current.kind !== 'stringLiteral') {
+        return { action: 'flag', reason: `non-string value for enum prop (${current.kind})` };
+    }
+    const value = current.value;
+    if (Object.prototype.hasOwnProperty.call(map, value)) {
+        const target = map[value];
+        if (target === null || target === undefined) {
+            return { action: 'flag', reason: `"${value}" has no v2 equivalent, migrate manually` };
+        }
+        if (v2set && !v2set.includes(target)) {
+            return { action: 'flag', reason: `mapped target "${target}" is not in the v2 set` };
+        }
+        return { action: 'rename', value: target };
+    }
+    // Not in the map: keep it if it is already a valid v2 value, otherwise flag.
+    if (v2set && !v2set.includes(value)) {
+        return { action: 'flag', reason: `"${value}" is not a valid v2 value for this prop` };
+    }
+    return { action: 'keep' };
+};

package/dist/surfaces/shared/class-ops.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Utility-class rewriting shared by the HTML / React / Angular / CSS surfaces
+ * (category J). The manifest lists BARE utility names; markup carries them
+ * under Tailwind variant prefixes (`hover:`, `md:`, arbitrary variants like
+ * `[&>li]:`) and important markers (leading `!` in v1's Tailwind 3, trailing
+ * `!` in Tailwind 4), so tokens are matched on the bare segment and only that
+ * segment is rewritten. The lookup is a single pass per token: the rename map
+ * contains chains (`rounded-xl → rounded-md` while `rounded-md → rounded-2xs`),
+ * and one lookup per token guarantees a rename never cascades.
+ */
+import { type ClassRenameRule, type ClassReportRule, type Manifest } from '../../manifest/schema.js';
+export interface ClassRenameEntry {
+    rule: ClassRenameRule;
+    id: string;
+}
+export interface ClassReportEntry {
+    rule: ClassReportRule;
+    id: string;
+}
+export interface ClassRules {
+    renames: Map<string, ClassRenameEntry>;
+    reports: Map<string, ClassReportEntry>;
+    /** Cheap probe: does this chunk of source mention any migrated class at all? */
+    candidateRe: RegExp | null;
+}
+export declare const classRulesOf: (manifest: Manifest) => ClassRules;
+export declare const hasClassRules: (rules: ClassRules) => boolean;
+interface SplitToken {
+    /** Variant prefix including its trailing colon(s): `hover:`, `md:[&>li]:`. */
+    prefix: string;
+    /** Leading important marker (Tailwind 3). */
+    bang: string;
+    /** The bare utility name the manifest rules are keyed on. */
+    base: string;
+    /** Trailing important marker (Tailwind 4). */
+    trailingBang: string;
+}
+/**
+ * Split one class token into variant prefix, important markers and the bare
+ * utility. The prefix ends at the last `:` outside square brackets, so
+ * arbitrary variants (`[&>li]:`, `[@media(hover)]:`) never leak into the base.
+ */
+export declare const splitClassToken: (token: string) => SplitToken;
+export interface ClassListResult {
+    value: string;
+    changed: boolean;
+}
+/**
+ * Rewrite a whitespace-separated class list. Whitespace (including newlines in
+ * multi-line `class` attributes) is preserved verbatim; each non-whitespace
+ * token is looked up once by its bare utility name. `onRename` / `onReport`
+ * fire once per occurrence with the full token as written.
+ */
+export declare const rewriteClassList: (value: string, rules: ClassRules, enabled: (id: string) => boolean, onRename: (entry: ClassRenameEntry, before: string, after: string) => void, onReport: (entry: ClassReportEntry, token: string) => void) => ClassListResult;
+export {};

package/dist/surfaces/shared/class-ops.js

@@ -0,0 +1,91 @@
+import { ruleId } from '../../manifest/registry.js';
+/** Tag used for the manifest-global class rules, which no component owns. */
+const GLOBAL_TAG = 'global';
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+const cache = new WeakMap();
+export const classRulesOf = (manifest) => {
+    const cached = cache.get(manifest);
+    if (cached)
+        return cached;
+    const renames = new Map();
+    const reports = new Map();
+    for (const rule of manifest.global.classes ?? []) {
+        if (rule.kind === 'classRename')
+            renames.set(rule.from, { rule, id: ruleId(GLOBAL_TAG, rule) });
+        else
+            reports.set(rule.name, { rule, id: ruleId(GLOBAL_TAG, rule) });
+    }
+    const names = [...renames.keys(), ...reports.keys()];
+    // Word-ish boundaries so a short name like `gap` never matches inside
+    // `gap-4` or prose; `-` counts as a word character in utility names.
+    const rules = {
+        renames,
+        reports,
+        candidateRe: names.length > 0
+            ? new RegExp(`(?<![\\w-])(?:${names.map(escapeRe).join('|')})(?![\\w-])`)
+            : null,
+    };
+    cache.set(manifest, rules);
+    return rules;
+};
+export const hasClassRules = (rules) => rules.renames.size > 0 || rules.reports.size > 0;
+/**
+ * Split one class token into variant prefix, important markers and the bare
+ * utility. The prefix ends at the last `:` outside square brackets, so
+ * arbitrary variants (`[&>li]:`, `[@media(hover)]:`) never leak into the base.
+ */
+export const splitClassToken = (token) => {
+    let depth = 0;
+    let cut = -1;
+    for (let i = 0; i < token.length; i++) {
+        const ch = token[i];
+        if (ch === '[')
+            depth += 1;
+        else if (ch === ']')
+            depth = Math.max(0, depth - 1);
+        else if (ch === ':' && depth === 0)
+            cut = i;
+    }
+    let rest = token.slice(cut + 1);
+    let bang = '';
+    let trailingBang = '';
+    if (rest.startsWith('!')) {
+        bang = '!';
+        rest = rest.slice(1);
+    }
+    if (rest.endsWith('!')) {
+        trailingBang = '!';
+        rest = rest.slice(0, -1);
+    }
+    return { prefix: token.slice(0, cut + 1), bang, base: rest, trailingBang };
+};
+/**
+ * Rewrite a whitespace-separated class list. Whitespace (including newlines in
+ * multi-line `class` attributes) is preserved verbatim; each non-whitespace
+ * token is looked up once by its bare utility name. `onRename` / `onReport`
+ * fire once per occurrence with the full token as written.
+ */
+export const rewriteClassList = (value, rules, enabled, onRename, onReport) => {
+    if (!rules.candidateRe || !rules.candidateRe.test(value))
+        return { value, changed: false };
+    let changed = false;
+    const parts = value.split(/(\s+)/);
+    for (let i = 0; i < parts.length; i++) {
+        const token = parts[i];
+        if (token === '' || /\s/.test(token))
+            continue;
+        const { prefix, bang, base, trailingBang } = splitClassToken(token);
+        const rename = rules.renames.get(base);
+        if (rename && enabled(rename.id)) {
+            const after = `${prefix}${bang}${rename.rule.to}${trailingBang}`;
+            parts[i] = after;
+            changed = true;
+            onRename(rename, token, after);
+            continue;
+        }
+        const report = rules.reports.get(base);
+        if (report && enabled(report.id))
+            onReport(report, token);
+    }
+    return { value: changed ? parts.join('') : value, changed };
+};

package/dist/surfaces/shared/edits.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Offset-based text edits. Surfaces that edit source by character range (HTML
+ * via parse5 locations) collect {@link Edit}s and apply them all at once;
+ * applying right-to-left keeps earlier offsets valid.
+ */
+export interface Edit {
+    start: number;
+    end: number;
+    text: string;
+}
+/** Apply edits to `source`. Non-overlapping edits are assumed; ties break by widest-first. */
+export declare const applyEdits: (source: string, edits: readonly Edit[]) => string;
+/** 1-based line/column for a character offset. */
+export declare const offsetToLineCol: (source: string, offset: number) => {
+    line: number;
+    column: number;
+};
+/** The leading whitespace of the line containing `offset` (used to indent injected comments). */
+export declare const lineIndentAt: (source: string, offset: number) => string;

package/dist/surfaces/shared/edits.js

@@ -0,0 +1,30 @@
+/** Apply edits to `source`. Non-overlapping edits are assumed; ties break by widest-first. */
+export const applyEdits = (source, edits) => {
+    const sorted = [...edits].sort((a, b) => b.start - a.start || b.end - a.end);
+    let out = source;
+    for (const edit of sorted)
+        out = out.slice(0, edit.start) + edit.text + out.slice(edit.end);
+    return out;
+};
+/** 1-based line/column for a character offset. */
+export const offsetToLineCol = (source, offset) => {
+    let line = 1;
+    let lineStart = 0;
+    for (let i = 0; i < offset && i < source.length; i++) {
+        if (source[i] === '\n') {
+            line++;
+            lineStart = i + 1;
+        }
+    }
+    return { line, column: offset - lineStart + 1 };
+};
+/** The leading whitespace of the line containing `offset` (used to indent injected comments). */
+export const lineIndentAt = (source, offset) => {
+    let start = offset;
+    while (start > 0 && source[start - 1] !== '\n')
+        start--;
+    let end = start;
+    while (end < source.length && (source[end] === ' ' || source[end] === '\t'))
+        end++;
+    return source.slice(start, end);
+};

package/dist/surfaces/shared/negate.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Build the logical negation of an expression's source text, with light,
+ * always-safe simplification. When in doubt the expression is wrapped in
+ * parentheses — over-parenthesising never changes meaning.
+ *
+ *   negateExprText('x')          === '!x'
+ *   negateExprText('a && b')     === '!(a && b)'
+ *   negateExprText('!x')         === 'x'
+ *   negateExprText('!(a && b)')  === '(a && b)'
+ *   negateExprText('true')       === 'false'
+ *   negateExprText('foo.bar()')  === '!foo.bar()'
+ */
+export declare const negateExprText: (expr: string) => string;

package/dist/surfaces/shared/negate.js

@@ -0,0 +1,51 @@
+/**
+ * Build the logical negation of an expression's source text, with light,
+ * always-safe simplification. When in doubt the expression is wrapped in
+ * parentheses — over-parenthesising never changes meaning.
+ *
+ *   negateExprText('x')          === '!x'
+ *   negateExprText('a && b')     === '!(a && b)'
+ *   negateExprText('!x')         === 'x'
+ *   negateExprText('!(a && b)')  === '(a && b)'
+ *   negateExprText('true')       === 'false'
+ *   negateExprText('foo.bar()')  === '!foo.bar()'
+ */
+export const negateExprText = (expr) => {
+    const t = expr.trim();
+    if (t === 'true')
+        return 'false';
+    if (t === 'false')
+        return 'true';
+    // Strip a leading `!` when it negates the whole expression (double negation).
+    if (t.startsWith('!')) {
+        const rest = t.slice(1).trim();
+        if (isAtomic(rest) || isFullyParenthesized(rest))
+            return rest;
+    }
+    return isAtomic(t) || isFullyParenthesized(t) ? `!${t}` : `!(${t})`;
+};
+/**
+ * A simple expression with no top-level operators: an identifier optionally
+ * followed by member access, calls or index chains (e.g. `a`, `a.b`, `a.b()`,
+ * `a[0].b`). These can be negated with a bare `!` prefix.
+ */
+const ATOMIC = /^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*|\([^()]*\)|\[[^[\]]*\])*$/;
+const isAtomic = (s) => ATOMIC.test(s.trim());
+/** True when the string is a single parenthesised group spanning its whole length, e.g. `(a && b)`. */
+const isFullyParenthesized = (s) => {
+    const t = s.trim();
+    if (t.length < 2 || t[0] !== '(' || t[t.length - 1] !== ')')
+        return false;
+    let depth = 0;
+    for (let i = 0; i < t.length; i++) {
+        if (t[i] === '(')
+            depth++;
+        else if (t[i] === ')') {
+            depth--;
+            // Closed the opening paren before the end → not a single enclosing group.
+            if (depth === 0 && i !== t.length - 1)
+                return false;
+        }
+    }
+    return depth === 0;
+};

package/dist/surfaces/shared/transform.d.ts

@@ -0,0 +1,17 @@
+/** Shared transformer contract used by every surface. */
+import { type Finding } from '../../report/types.js';
+export interface TransformContext {
+    /** Path of the file being transformed (for findings). */
+    file: string;
+    /** When set, only these rule ids run. */
+    only?: ReadonlySet<string>;
+    /** These rule ids are skipped. */
+    skip?: ReadonlySet<string>;
+}
+export interface TransformResult {
+    output: string;
+    changed: boolean;
+    findings: Finding[];
+}
+/** Whether a rule id passes the `--only` / `--skip` filters. */
+export declare const ruleEnabled: (ctx: TransformContext, id: string) => boolean;

package/dist/surfaces/shared/transform.js

@@ -0,0 +1,8 @@
+/** Whether a rule id passes the `--only` / `--skip` filters. */
+export const ruleEnabled = (ctx, id) => {
+    if (ctx.only && !ctx.only.has(id))
+        return false;
+    if (ctx.skip && ctx.skip.has(id))
+        return false;
+    return true;
+};

package/dist/surfaces/shared/value-model.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Surface-agnostic model of an attribute / prop value.
+ *
+ * Every surface (HTML, React, Angular) parses its own syntax into one of these
+ * shapes so the shared transformation core (`attribute-ops`) can reason about
+ * values without knowing whether it is looking at `arrow`, `arrow={x}` or
+ * `[arrow]="x"`.
+ */
+export type AttrValue = 
+/** Shorthand presence: HTML `arrow`, JSX `arrow`, Angular `arrow` → logically `true`. */
+{
+    kind: 'bareTrue';
+}
+/** A boolean literal: JSX `arrow={true}`, Angular `[arrow]="false"`. */
+ | {
+    kind: 'boolLiteral';
+    value: boolean;
+}
+/** A static string value: HTML `tone="ghost"`, JSX `tone="ghost"`. */
+ | {
+    kind: 'stringLiteral';
+    value: string;
+}
+/** A dynamic expression whose text is preserved verbatim: JSX `arrow={x && y}`, Angular `[arrow]="x && y"`. */
+ | {
+    kind: 'dynamic';
+    expr: string;
+};
+export declare const bareTrue: () => AttrValue;
+export declare const boolLiteral: (value: boolean) => AttrValue;
+export declare const stringLiteral: (value: string) => AttrValue;
+export declare const dynamic: (expr: string) => AttrValue;
+/** True when the value is known at codemod time (not a runtime expression). */
+export declare const isStatic: (value: AttrValue) => boolean;
+/**
+ * Coerce a value to a boolean interpretation when the prop is boolean-typed.
+ * Returns the literal boolean, or the raw expression text when dynamic.
+ *
+ * String semantics follow Stencil's boolean prop parsing: the string `"false"`
+ * is `false`, every other present string is `true`.
+ */
+export type ResolvedBool = {
+    kind: 'literal';
+    value: boolean;
+} | {
+    kind: 'expr';
+    expr: string;
+};
+export declare const resolveBoolean: (value: AttrValue) => ResolvedBool;

package/dist/surfaces/shared/value-model.js

@@ -0,0 +1,18 @@
+export const bareTrue = () => ({ kind: 'bareTrue' });
+export const boolLiteral = (value) => ({ kind: 'boolLiteral', value });
+export const stringLiteral = (value) => ({ kind: 'stringLiteral', value });
+export const dynamic = (expr) => ({ kind: 'dynamic', expr });
+/** True when the value is known at codemod time (not a runtime expression). */
+export const isStatic = (value) => value.kind !== 'dynamic';
+export const resolveBoolean = (value) => {
+    switch (value.kind) {
+        case 'bareTrue':
+            return { kind: 'literal', value: true };
+        case 'boolLiteral':
+            return { kind: 'literal', value: value.value };
+        case 'stringLiteral':
+            return { kind: 'literal', value: value.value !== 'false' };
+        case 'dynamic':
+            return { kind: 'expr', expr: value.expr };
+    }
+};

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@maggioli-design-system/magma-codemods",
+  "version": "2.0.0-beta.0",
+  "description": "Codemods to migrate consumer code (HTML, React/JSX, Angular templates, CSS/SCSS) of @maggioli-design-system/magma from v1 to v2.",
+  "license": "ISC",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "magma-codemods": "dist/cli.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "generate.candidate": "tsx scripts/build-candidate-manifest.ts",
+    "test": "NODE_OPTIONS=--experimental-vm-modules jest",
+    "lint": "eslint ."
+  },
+  "dependencies": {
+    "@angular/compiler": "20.3.30",
+    "arg": "5.0.2",
+    "chalk": "5.6.2",
+    "globby": "14.1.0",
+    "parse5": "7.3.0",
+    "postcss": "8.5.28",
+    "postcss-scss": "4.0.9",
+    "ts-morph": "28.0.0"
+  },
+  "devDependencies": {
+    "@types/jest": "29.5.14",
+    "jest": "29.7.0",
+    "ts-jest": "29.2.5"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/magma-design-system/magma.git",
+    "directory": "projects/codemod"
+  },
+  "keywords": [
+    "codemod",
+    "migration",
+    "magma",
+    "design-system",
+    "jscodeshift",
+    "stencil"
+  ]
+}