accel2spa 0.0.0-stage → 0.1.0

package/dist/cli.js

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+import { readFileSync, realpathSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { analyzeStorefront, writeOutputs } from './index.js';
+const HELP = `accel2spa - turn a SAP Commerce Accelerator storefront into Spartacus migration specs
+
+Usage:
+  accel2spa analyze <storefront-path> [--out <dir>] [--occ-fields <file>]
+
+Options:
+  --out <dir>          Output root (default: out). Writes <dir>/<storefront-name>/model.json
+                       and <dir>/<storefront-name>/specs/<page>.md
+  --occ-fields <file>  JSON file that extends/overrides the bundled OCC field reference
+  -h, --help           Show this help
+  -v, --version        Show version
+`;
+/** Safe folder name for a storefront path: its last segment, resolved when it is `.`, `..` or a drive root. */
+export function storefrontFolderName(target) {
+    const bs = String.fromCharCode(92);
+    const sep = bs + bs + '/';
+    const lastSegment = (p) => p.replace(new RegExp(`[${sep}]+$`), '').split(new RegExp(`[${sep}]`)).pop() ?? '';
+    let last = lastSegment(target);
+    if (!last || last === '.' || last === '..' || /^[A-Za-z]:$/.test(last))
+        last = lastSegment(path.resolve(target));
+    const safe = last
+        .replace(/[<>:"|?*\u0000-\u001f]/g, '-')
+        .replace(/\s+/g, '-')
+        .replace(/^[.\s-]+|[.\s-]+$/g, '');
+    return safe || 'storefront';
+}
+function version() {
+    const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+    return pkg.version;
+}
+export function main(argv) {
+    const args = argv.slice(2);
+    if (!args.length || args.includes('-h') || args.includes('--help')) {
+        process.stdout.write(HELP);
+        return 0;
+    }
+    if (args.includes('-v') || args.includes('--version')) {
+        process.stdout.write(version() + '\n');
+        return 0;
+    }
+    const [command, ...rest] = args;
+    if (command !== 'analyze') {
+        process.stderr.write(`Unknown command: ${command}\n\n${HELP}`);
+        return 2;
+    }
+    let target;
+    let out = 'out';
+    let occFields;
+    for (let i = 0; i < rest.length; i++) {
+        const a = rest[i];
+        if (a === '--out' || a === '--occ-fields') {
+            const v = rest[++i];
+            if (!v) {
+                process.stderr.write(`Missing value for ${a}\n`);
+                return 2;
+            }
+            if (a === '--out')
+                out = v;
+            else
+                occFields = v;
+        }
+        else if (a.startsWith('--out='))
+            out = a.slice(6);
+        else if (a.startsWith('--occ-fields='))
+            occFields = a.slice(13);
+        else if (a.startsWith('-')) {
+            process.stderr.write(`Unknown option: ${a}\n`);
+            return 2;
+        }
+        else if (!target)
+            target = a;
+        else {
+            process.stderr.write(`Unexpected argument: ${a}\n`);
+            return 2;
+        }
+    }
+    if (!target) {
+        process.stderr.write(`Missing <storefront-path>\n\n${HELP}`);
+        return 2;
+    }
+    try {
+        const model = analyzeStorefront(target, { occFieldsPath: occFields });
+        const outDir = path.join(out, storefrontFolderName(target));
+        const written = writeOutputs(model, outDir);
+        const show = (p) => p.split(path.sep).join('/');
+        const s = model.summary;
+        process.stdout.write([
+            `Analyzed ${model.storefront}: ${s.pages} page(s), ${s.components} CMS component(s), ${s.tagFiles} tag file(s), ${s.languages} language(s)`,
+            `  conditionals: ${s.conditionals}`,
+            `  OCC data gaps: ${s.dataGaps}`,
+            `  missing endpoints: ${s.missingEndpoints}`,
+            `  missing i18n keys: ${s.missingI18nKeys}`,
+            `  hardcoded strings: ${s.hardcodedStrings}`,
+            `Wrote ${show(path.join(outDir, 'model.json'))} and ${written.length} spec(s) in ${show(path.join(outDir, 'specs'))}`
+        ].join('\n') + '\n');
+        if (model.warnings.length)
+            process.stdout.write(`${model.warnings.length} warning(s); see model.json\n`);
+        return 0;
+    }
+    catch (e) {
+        process.stderr.write(`Error: ${e.message}\n`);
+        return 1;
+    }
+}
+const entry = process.argv[1];
+if (entry && realpathSync(entry) === realpathSync(fileURLToPath(import.meta.url))) {
+    process.exitCode = main(process.argv);
+}

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+import type { Model } from './model.js';
+export { analyzeStorefront } from './analyze.js';
+export type { AnalyzeOptions } from './analyze.js';
+export { renderSpec } from './renderers/spec.js';
+export { loadOccFields, OccReference } from './occ/reference.js';
+export { scanTemplate } from './scanners/jsp.js';
+export { scanJsEndpoints } from './scanners/js.js';
+export { parseProperties } from './scanners/properties.js';
+export { parseImpex, parseItemsXml, buildCmsTypes } from './scanners/cms.js';
+export type * from './model.js';
+/** Render every spec of a model, keyed by file name (`<id>.md`). */
+export declare function renderAllSpecs(model: Model): Map<string, string>;
+/** Write `model.json` and `specs/*.md` into `outDir`. Returns the written spec paths. */
+export declare function writeOutputs(model: Model, outDir: string): string[];
+/** Convenience: analyze and write in one call. */
+export declare function analyzeAndWrite(storefrontPath: string, outDir: string, occFieldsPath?: string): Model;

package/dist/index.js

@@ -0,0 +1,39 @@
+/** Public API of accel2spa (reused by the CLI and, later, an MCP wrapper). */
+import { mkdirSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { analyzeStorefront } from './analyze.js';
+import { renderSpec } from './renderers/spec.js';
+export { analyzeStorefront } from './analyze.js';
+export { renderSpec } from './renderers/spec.js';
+export { loadOccFields, OccReference } from './occ/reference.js';
+export { scanTemplate } from './scanners/jsp.js';
+export { scanJsEndpoints } from './scanners/js.js';
+export { parseProperties } from './scanners/properties.js';
+export { parseImpex, parseItemsXml, buildCmsTypes } from './scanners/cms.js';
+/** Render every spec of a model, keyed by file name (`<id>.md`). */
+export function renderAllSpecs(model) {
+    const out = new Map();
+    for (const unit of [...model.pages, ...model.components]) {
+        out.set(`${unit.id}.md`, renderSpec(unit, model));
+    }
+    return out;
+}
+/** Write `model.json` and `specs/*.md` into `outDir`. Returns the written spec paths. */
+export function writeOutputs(model, outDir) {
+    const specsDir = path.join(outDir, 'specs');
+    mkdirSync(specsDir, { recursive: true });
+    writeFileSync(path.join(outDir, 'model.json'), JSON.stringify(model, null, 2) + '\n');
+    const written = [];
+    for (const [name, content] of renderAllSpecs(model)) {
+        const p = path.join(specsDir, name);
+        writeFileSync(p, content);
+        written.push(p);
+    }
+    return written;
+}
+/** Convenience: analyze and write in one call. */
+export function analyzeAndWrite(storefrontPath, outDir, occFieldsPath) {
+    const model = analyzeStorefront(storefrontPath, { occFieldsPath });
+    writeOutputs(model, outDir);
+    return model;
+}

package/dist/model.d.ts

@@ -0,0 +1,179 @@
+/** Types of the intermediate `model.json` produced by `analyze`. */
+export interface SourceRef {
+    file: string;
+    line: number;
+}
+export type ConditionalKind = 'if' | 'when' | 'otherwise';
+export type ConditionalLayout = 'block' | 'row' | 'column' | 'item' | 'text';
+export interface Conditional {
+    id: string;
+    kind: ConditionalKind;
+    /** The raw EL test expression (without `${ }`). Absent for `otherwise`. */
+    test?: string;
+    file: string;
+    line: number;
+    endLine: number;
+    /** Heuristic: what kind of layout element the condition controls. */
+    layout: ConditionalLayout;
+    depth: number;
+    parent?: string;
+    /** Shared by the `when`/`otherwise` branches of the same `c:choose`. */
+    chooseGroup?: string;
+    containsTags: string[];
+    containsI18nKeys: string[];
+    label: string;
+}
+export interface TagInclude {
+    /** e.g. `order:orderTotals` */
+    name: string;
+    /** Resolved .tag file, when found in the storefront. */
+    tagFile?: string;
+    file: string;
+    line: number;
+}
+export interface I18nUsage {
+    key: string;
+    refs: Array<SourceRef & {
+        tag: string;
+    }>;
+    /** Fallback text given inline (e.g. `<spring:theme code=".." text="..">`). */
+    defaultText?: string;
+    /** Text per language where the key is defined. */
+    texts: Record<string, string>;
+    /** Languages (among those found) in which the key is not defined. */
+    missingIn: string[];
+}
+export interface HardcodedText {
+    text: string;
+    file: string;
+    line: number;
+    kind: 'text' | 'attribute';
+    attribute?: string;
+}
+export type DataStatus = 'exposed' | 'missing' | 'unchecked';
+export interface DataUse {
+    /** EL path, e.g. `order.deliveryCost.value` */
+    path: string;
+    root: string;
+    /** OCC type the root resolved to, e.g. `Order`. */
+    occType?: string;
+    status: DataStatus;
+    /** For `missing`: the first field that OCC does not expose. */
+    missingField?: string;
+    note?: string;
+    refs: SourceRef[];
+}
+export interface EndpointUse {
+    kind: 'ajax' | 'fetch' | 'xhr' | 'c:url' | 'form';
+    method: string;
+    /** Normalized URL; dynamic parts are `{param}`. */
+    url: string;
+    status: 'mapped' | 'missing' | 'external';
+    /** For `mapped`: the OCC endpoint it corresponds to. */
+    occEquivalent?: string;
+    refs: SourceRef[];
+    requestFields: string[];
+    responseFields: string[];
+}
+export interface Gap {
+    kind: 'data' | 'endpoint' | 'i18n' | 'hardcoded-text';
+    id: string;
+    summary: string;
+    refs: SourceRef[];
+}
+export interface ComponentNode {
+    /** `prefix:tag` for tag files, or the page/component file name for the root. */
+    name: string;
+    file: string;
+    /** Line of the usage in the parent. */
+    line?: number;
+    /** Already expanded earlier in the tree. */
+    repeated?: boolean;
+    children: ComponentNode[];
+}
+export interface I18nCoverage {
+    lang: string;
+    file: string;
+    present: number;
+    total: number;
+}
+export interface UnitModel {
+    id: string;
+    kind: 'page' | 'component';
+    /** Entry file (JSP). */
+    file: string;
+    /** All source files that contribute to this unit (entry, tags, includes, JS). */
+    files: string[];
+    currentUrl?: string;
+    route: string;
+    routeSource: 'known' | 'derived';
+    /** CMS type code for components. */
+    cmsType?: string;
+    cmsSlots: Array<SourceRef & {
+        position: string;
+    }>;
+    tree: ComponentNode;
+    tagIncludes: TagInclude[];
+    conditionals: Conditional[];
+    i18n: I18nUsage[];
+    dynamicI18n: Array<SourceRef & {
+        tag: string;
+        expression: string;
+    }>;
+    i18nCoverage: I18nCoverage[];
+    hardcoded: HardcodedText[];
+    data: DataUse[];
+    endpoints: EndpointUse[];
+    gaps: Gap[];
+    dependsOn: string[];
+    complexity: {
+        score: number;
+        level: 'low' | 'medium' | 'high';
+    };
+    warnings: string[];
+}
+export interface CmsComponentType {
+    code: string;
+    extends?: string;
+    attributes: Array<{
+        name: string;
+        type?: string;
+        file: string;
+        line: number;
+        source: 'items.xml' | 'impex';
+    }>;
+    instances: Array<{
+        uid: string;
+        name?: string;
+        file: string;
+        line: number;
+    }>;
+    jsp?: string;
+}
+export interface LanguageInfo {
+    lang: string;
+    file: string;
+    keyCount: number;
+}
+export interface Model {
+    version: 1;
+    storefront: string;
+    occFieldsSource: string;
+    languages: LanguageInfo[];
+    referenceLanguage?: string;
+    cmsComponentTypes: CmsComponentType[];
+    pages: UnitModel[];
+    components: UnitModel[];
+    summary: {
+        pages: number;
+        components: number;
+        tagFiles: number;
+        languages: number;
+        conditionals: number;
+        dataGaps: number;
+        missingEndpoints: number;
+        missingI18nKeys: number;
+        hardcodedStrings: number;
+    };
+    warnings: string[];
+}

package/dist/model.js

@@ -0,0 +1,2 @@
+/** Types of the intermediate `model.json` produced by `analyze`. */
+export {};

package/dist/occ/endpoints.json

@@ -0,0 +1,15 @@
+{
+  "_note": "APPROXIMATION: storefront (Accelerator) URL patterns and the OCC endpoint that typically replaces them. `{param}` matches one path segment, `**` matches anything. Extend via `--occ-fields <file>` using an `endpoints` array of the same shape.",
+  "endpoints": [
+    { "accelerator": "/cart/add", "method": "POST", "occ": "POST /users/{userId}/carts/{cartId}/entries" },
+    { "accelerator": "/cart/update", "method": "POST", "occ": "PATCH /users/{userId}/carts/{cartId}/entries/{entryNumber}" },
+    { "accelerator": "/cart/remove", "method": "POST", "occ": "DELETE /users/{userId}/carts/{cartId}/entries/{entryNumber}" },
+    { "accelerator": "/search/autocomplete/{param}", "occ": "GET /products/suggestions" },
+    { "accelerator": "/search/**", "occ": "GET /products/search" },
+    { "accelerator": "/store-finder/**", "occ": "GET /stores" },
+    { "accelerator": "/my-account/orders", "occ": "GET /users/{userId}/orders" },
+    { "accelerator": "/my-account/order/{param}", "occ": "GET /users/{userId}/orders/{orderCode}" },
+    { "accelerator": "/my-account/address-book/**", "occ": "GET /users/{userId}/addresses" },
+    { "accelerator": "/my-account/update-profile", "method": "POST", "occ": "PATCH /users/{userId}" }
+  ]
+}

package/dist/occ/fields.json

@@ -0,0 +1,187 @@
+{
+  "_note": "APPROXIMATION of fields typically returned by the SAP Commerce OCC API (FULL field set), written from general knowledge of the public OCC documentation. Real projects customize OCC mappings, so verify against your own /v2/api-docs. Override or extend with `accel2spa analyze --occ-fields <file>` (same shape; only the keys you provide are merged).",
+  "rootVars": {
+    "order": "Order",
+    "orderData": "Order",
+    "cart": "Cart",
+    "cartData": "Cart",
+    "product": "Product",
+    "productData": "Product",
+    "entry": "OrderEntry",
+    "orderEntry": "OrderEntry",
+    "address": "Address",
+    "deliveryAddress": "Address",
+    "component": "CMSComponent"
+  },
+  "types": {
+    "Price": {
+      "currencyIso": "string",
+      "value": "number",
+      "formattedValue": "string",
+      "priceType": "string",
+      "minQuantity": "number",
+      "maxQuantity": "number"
+    },
+    "Principal": { "uid": "string", "name": "string" },
+    "Address": {
+      "id": "string",
+      "title": "string",
+      "titleCode": "string",
+      "firstName": "string",
+      "lastName": "string",
+      "line1": "string",
+      "line2": "string",
+      "town": "string",
+      "postalCode": "string",
+      "phone": "string",
+      "email": "string",
+      "country": "Country",
+      "region": "Region",
+      "defaultAddress": "boolean",
+      "formattedAddress": "string",
+      "shippingAddress": "boolean",
+      "billingAddress": "boolean"
+    },
+    "Country": { "isocode": "string", "name": "string" },
+    "Region": { "isocode": "string", "name": "string", "countryIso": "string" },
+    "DeliveryMode": { "code": "string", "name": "string", "description": "string", "deliveryCost": "Price" },
+    "PaymentDetails": {
+      "id": "string",
+      "accountHolderName": "string",
+      "cardType": "CardType",
+      "cardNumber": "string",
+      "expiryMonth": "string",
+      "expiryYear": "string",
+      "billingAddress": "Address",
+      "defaultPayment": "boolean"
+    },
+    "CardType": { "code": "string", "name": "string" },
+    "Promotion": { "code": "string", "title": "string", "description": "string", "promotionType": "string" },
+    "PromotionResult": { "description": "string", "promotion": "Promotion" },
+    "Image": { "imageType": "string", "format": "string", "url": "string", "altText": "string", "galleryIndex": "number" },
+    "Stock": { "stockLevelStatus": "string", "stockLevel": "number", "isValueRounded": "boolean" },
+    "Category": { "code": "string", "name": "string", "url": "string", "image": "Image" },
+    "Product": {
+      "code": "string",
+      "name": "string",
+      "summary": "string",
+      "description": "string",
+      "url": "string",
+      "price": "Price",
+      "images": "Image[]",
+      "stock": "Stock",
+      "categories": "Category[]",
+      "manufacturer": "string",
+      "purchasable": "boolean",
+      "averageRating": "number",
+      "numberOfReviews": "number",
+      "baseOptions": "object",
+      "availableForPickup": "boolean"
+    },
+    "OrderEntry": {
+      "entryNumber": "number",
+      "quantity": "number",
+      "basePrice": "Price",
+      "totalPrice": "Price",
+      "product": "Product",
+      "updateable": "boolean",
+      "deliveryMode": "DeliveryMode",
+      "deliveryPointOfService": "object",
+      "statusSummaryList": "object[]",
+      "cancellableQuantity": "number",
+      "returnableQuantity": "number"
+    },
+    "Consignment": {
+      "code": "string",
+      "status": "string",
+      "statusDate": "date",
+      "trackingID": "string",
+      "entries": "object[]",
+      "shippingAddress": "Address"
+    },
+    "Order": {
+      "code": "string",
+      "guid": "string",
+      "user": "Principal",
+      "created": "date",
+      "status": "string",
+      "statusDisplay": "string",
+      "net": "boolean",
+      "calculated": "boolean",
+      "site": "string",
+      "store": "string",
+      "guestCustomer": "boolean",
+      "entries": "OrderEntry[]",
+      "totalItems": "number",
+      "totalUnitCount": "number",
+      "subTotal": "Price",
+      "totalPrice": "Price",
+      "totalPriceWithTax": "Price",
+      "totalTax": "Price",
+      "totalDiscounts": "Price",
+      "orderDiscounts": "Price",
+      "productDiscounts": "Price",
+      "deliveryCost": "Price",
+      "deliveryAddress": "Address",
+      "deliveryMode": "DeliveryMode",
+      "deliveryItemsQuantity": "number",
+      "pickupItemsQuantity": "number",
+      "paymentInfo": "PaymentDetails",
+      "appliedOrderPromotions": "PromotionResult[]",
+      "appliedProductPromotions": "PromotionResult[]",
+      "appliedVouchers": "object[]",
+      "consignments": "Consignment[]",
+      "unconsignedEntries": "OrderEntry[]",
+      "purchaseOrderNumber": "string",
+      "costCenter": "object"
+    },
+    "Cart": {
+      "code": "string",
+      "guid": "string",
+      "user": "Principal",
+      "entries": "OrderEntry[]",
+      "totalItems": "number",
+      "totalUnitCount": "number",
+      "subTotal": "Price",
+      "totalPrice": "Price",
+      "totalPriceWithTax": "Price",
+      "totalTax": "Price",
+      "totalDiscounts": "Price",
+      "orderDiscounts": "Price",
+      "productDiscounts": "Price",
+      "deliveryCost": "Price",
+      "deliveryAddress": "Address",
+      "deliveryMode": "DeliveryMode",
+      "paymentInfo": "PaymentDetails",
+      "net": "boolean",
+      "appliedOrderPromotions": "PromotionResult[]",
+      "appliedProductPromotions": "PromotionResult[]",
+      "appliedVouchers": "object[]",
+      "potentialOrderPromotions": "PromotionResult[]",
+      "potentialProductPromotions": "PromotionResult[]"
+    },
+    "CMSComponent": {
+      "uid": "string",
+      "uuid": "string",
+      "typeCode": "string",
+      "name": "string",
+      "modifiedtime": "date",
+      "container": "string",
+      "otherProperties": "object"
+    },
+    "CMSParagraphComponent": { "$extends": "CMSComponent", "content": "string" },
+    "CMSLinkComponent": {
+      "$extends": "CMSComponent",
+      "linkName": "string",
+      "url": "string",
+      "target": "string",
+      "external": "boolean"
+    },
+    "SimpleBannerComponent": {
+      "$extends": "CMSComponent",
+      "media": "Image",
+      "urlLink": "string",
+      "external": "boolean"
+    }
+  }
+}

package/dist/occ/reference.d.ts

@@ -0,0 +1,38 @@
+import type { AliasDecl } from '../scanners/jsp.js';
+export type OccTypeDef = Record<string, string>;
+export interface OccFields {
+    rootVars: Record<string, string>;
+    types: Record<string, OccTypeDef>;
+    endpoints: Array<{
+        accelerator: string;
+        method?: string;
+        occ: string;
+    }>;
+}
+export interface OccOverride {
+    rootVars?: Record<string, string>;
+    types?: Record<string, OccTypeDef>;
+    endpoints?: OccFields['endpoints'];
+}
+export declare function loadOccFields(overridePath?: string): {
+    fields: OccFields;
+    source: string;
+};
+export interface DataCheck {
+    status: 'exposed' | 'missing' | 'unchecked';
+    occType?: string;
+    missingField?: string;
+}
+export declare class OccReference {
+    readonly fields: OccFields;
+    constructor(fields: OccFields);
+    private lookup;
+    hasType(name: string): boolean;
+    /** Type of an EL root variable, following `forEach`/`set` aliases and tag attribute types. */
+    rootType(root: string, aliases: Record<string, AliasDecl>, overrides: Record<string, string>, depth?: number): string | undefined;
+    checkPath(path: string, aliases: Record<string, AliasDecl>, overrides: Record<string, string>, depth?: number): DataCheck & {
+        resultType?: string;
+    };
+    /** Which OCC endpoint replaces this storefront URL, if known. */
+    matchEndpoint(url: string, method: string): string | undefined;
+}