accel2spa 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 André Escocard
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,162 @@
-# Temporary Holding Version
+<h1>
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="assets/brand/wordmark-dark.svg">
+    <img src="assets/brand/wordmark.svg" alt="accel2spa" height="40">
+  </picture>
+</h1>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Reads a SAP Commerce Accelerator storefront and writes one migration spec per page for Spartacus (Composable Storefront). Each spec lists every conditional rule, translation gap, field OCC does not expose and endpoint with no OCC equivalent, with the `file:line` it comes from.
+
+![A terminal runs npx accel2spa analyze ./acme-storefront and reports 3 pages, 1 CMS component, 12 conditionals, 9 OCC data gaps, 3 missing endpoints and 25 missing i18n keys. Beside it, the generated spec for the order detail page lists 8 gaps in its frontmatter and a data table where four order fields are marked NO because OCC does not expose them.](assets/hero.svg)
+
+## Quickstart
+
+```bash
+npx accel2spa analyze <storefront-path> --out out
+```
+
+Requires Node.js 20+. To try it on the bundled synthetic fixture, run it from a clone:
+
+```bash
+npm install && npm run build
+node dist/cli.js analyze fixtures/acme-storefront --out out
+```
+
+Point it at the storefront extension (the folder that contains `web/webroot/WEB-INF`), or at a parent folder that also holds your core extension so its `*-items.xml` and ImpEx are read too. It writes:
+
+- `out/<storefront-name>/specs/<page>.md`: one spec per page (`pages/**/*.jsp`) and per CMS component (`cms/*.jsp`).
+- `out/<storefront-name>/model.json`: the intermediate model behind the specs (page, components, tags, conditionals, i18n keys, data used, endpoints, gaps).
+
+## What it finds
+
+Four kinds of work that a JSP hides and a Spartacus estimate usually misses.
+
+**1. Conditional layout.** Every `<c:if test>` and `<c:choose>/<c:when>/<c:otherwise>`, with nesting and what each one controls (block, row, column, item). Custom tags are followed through their taglib prefixes, so you get the page's real component tree, not just its top file. In the fixture, `orderDetail.tag:15` renders the invoice-number block only `when not empty order.invoiceNumber`.
+
+**2. i18n coverage.** Keys used per page (`<spring:theme>`, `<spring:message>`, `<fmt:message>`), checked against every `base_<lang>.properties`, plus literal text that should have been a key. The fixture's order detail page uses 22 keys; French defines 7 of them.
+
+**3. Data OCC does not expose.** EL expressions such as `${order.invoiceNumber}` are compared with a reference of OCC fields. A JSP could read any model attribute; Spartacus only gets what OCC returns, so each gap is backend work. Custom CMS attributes from `*-items.xml` and ImpEx are listed too.
+
+**4. Endpoints with no OCC equivalent.** `$.ajax`, `$.get/post`, `fetch`, `XMLHttpRequest`, forms and `<c:url>` values in JSPs and referenced scripts. For each unmapped call, the spec proposes a typed interface (from the request and response fields the code touches) and a mock, so the frontend can ship before the backend does.
+
+![Diagram. On the left, fields the Accelerator JSP reads on the order detail page. OCC sits in the middle as a filter. order.code, order.statusDisplay, order.entries, entry.quantity and order.created pass through to Spartacus; order.invoiceNumber, order.estimatedDeliveryWindow, order.giftWrapRequested and entry.giftMessage stop at OCC and are marked as gaps. Below, POST /cart/add maps to an OCC endpoint, while GET /my-account/wishlist/count and POST /promo/banner/{param}/impression have none.](assets/how-it-works.svg)
+
+## What a spec contains
+
+Markdown with YAML frontmatter (`id`, `kind`, `source`, `route`, `complexity`, `dependsOn`, `gaps`), written so a developer or an AI agent can build the page without reading the whole legacy codebase. Nine sections:
+
+1. **Context**: source page, target route, counts, complexity score.
+2. **Pointers, not copies**: source files and tag includes as `file:line`. Legacy code is never inlined.
+3. **Structure and conditional rules**: component tree and a table of every rule.
+4. **i18n**: keys with text, missing languages and location; hardcoded strings.
+5. **Data and endpoints**: each expression, its OCC type, whether OCC exposes it.
+6. **Acceptance criteria**: one verifiable check per rule, key and gap.
+7. **Visual parity**: current URL, Spartacus route, states to compare.
+8. **Blockers**: backend work, with a typed interface and mock to start from.
+9. **Tasks**: a checklist to work through.
+
+An excerpt from `out/specs/account-order-detail.md`, generated from the bundled fixture:
+
+```yaml
+id: account-order-detail
+kind: page
+route: /my-account/order/:orderCode
+complexity: high
+gaps:
+  - data:entry.giftMessage
+  - data:order.estimatedDeliveryWindow
+  - data:order.giftWrapRequested
+  - data:order.invoiceNumber
+  - i18n:de
+  - i18n:en
+  - i18n:fr
+  - hardcoded-text
+```
+
+```ts
+// 8. Blockers: suggested shape while the backend is pending (field types are guesses)
+export interface OrderExtension {
+  estimatedDeliveryWindow?: string;
+  giftWrapRequested?: boolean;
+  invoiceNumber?: number;
+}
+```
+
+## CLI
+
+```
+accel2spa analyze <storefront-path> [--out <dir>] [--occ-fields <file>]
+```
+
+| Option | Effect |
+|---|---|
+| `--out <dir>` | Output root. Default `out`. Writes `<dir>/<storefront-name>/model.json` and `<dir>/<storefront-name>/specs/<page>.md`. |
+| `--occ-fields <file>` | JSON that extends or overrides the bundled OCC reference. |
+| `-h`, `--help` | Show help. |
+| `-v`, `--version` | Show version. |
+
+Problems with odd input never stop the run; they are listed under `warnings` in `model.json`.
+
+### Your OCC is not the default OCC
+
+The bundled reference (`src/occ/fields.json`, `src/occ/endpoints.json`) was written from the public OCC documentation. Real projects extend OCC, so declare your additions and the gaps that are already closed disappear from the specs:
+
+```json
+{
+  "rootVars": { "myOrder": "Order" },
+  "types": { "Order": { "invoiceNumber": "string" } },
+  "endpoints": [{ "accelerator": "/my/endpoint", "method": "GET", "occ": "GET /users/{userId}/my" }]
+}
+```
+
+## Programmatic API
+
+The CLI is a thin layer over a library, so an MCP server or a CI check can reuse it.
+
+```ts
+import { analyzeStorefront, renderSpec, writeOutputs } from 'accel2spa';
+
+const model = analyzeStorefront('./storefront', { occFieldsPath: './my-occ.json' });
+console.log(model.summary.dataGaps, model.summary.missingEndpoints);
+
+const orderDetail = model.pages.find((p) => p.id === 'account-order-detail');
+if (orderDetail) console.log(renderSpec(orderDetail, model));
+
+writeOutputs(model, 'out'); // model.json + specs/*.md
+```
+
+Also exported: `renderAllSpecs`, `analyzeAndWrite`, the individual scanners (`scanTemplate`, `scanJsEndpoints`, `parseProperties`, `parseImpex`, `parseItemsXml`, `buildCmsTypes`), `loadOccFields`, `OccReference` and the model types.
+
+## Limitations
+
+- Regular expressions and a small tokenizer, not a full JSP parser.
+- EL variable types come from `<%@ attribute type="...Data" %>`, `c:forEach`/`c:set` and a table of root variables. Anything else is reported as "not verified".
+- The OCC reference is an approximation; pass `--occ-fields` for your project.
+- CMS slot to component wiring from ImpEx is not resolved yet. CMS components get their own specs.
+- Complexity is a simple weighted score, useful for ordering work, not for estimates.
+
+## Roadmap
+
+- A report renderer: one human-readable overview across all pages, for planning and estimates.
+- An MCP wrapper over the library, so coding agents can query the model directly.
+- Three more patterns:
+  - Third-party scripts (payment iframes, plugins): loaded browser-only, idempotent and safe under SSR.
+  - Session and country state carried by cookies and redirects: mapped to interceptors and state.
+  - Several sites in one codebase: mapped to `baseSite` and context configuration.
+
+## Development
+
+```bash
+npm test        # vitest: scanner unit tests + integration snapshot on the fixture
+npm run build   # tsc + copies the OCC reference JSON to dist/
+```
+
+## Legal note
+
+`fixtures/acme-storefront/` is synthetic: written from scratch for this project around a fictional "Acme" store, using only generic Accelerator patterns (taglib usage, `<c:if>`, `<spring:theme>`, and so on). It contains no code, names, endpoints, URLs or business rules from SAP's licensed `yacceleratorstorefront` templates or from any real client. Please keep it that way in contributions.
+
+SAP, SAP Commerce and Spartacus are trademarks of their respective owners. This project is independent and not affiliated with SAP.
+
+## License
+
+MIT. The images in `assets/` embed subsets of JetBrains Mono and Schibsted Grotesk (the wordmark as outlines) under the SIL Open Font License 1.1 (see `assets/fonts/`).

package/dist/analyze.d.ts

@@ -0,0 +1,7 @@
+import type { Model, SourceRef } from './model.js';
+export interface AnalyzeOptions {
+    /** JSON file that extends/overrides the bundled OCC field reference. */
+    occFieldsPath?: string;
+}
+export declare function analyzeStorefront(storefrontPath: string, options?: AnalyzeOptions): Model;
+export type { SourceRef };

package/dist/analyze.js

@@ -0,0 +1,401 @@
+/** Core analysis: scan a storefront and build the `Model`. */
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { buildCmsTypes, parseImpex, parseItemsXml } from './scanners/cms.js';
+import { scanTemplate } from './scanners/jsp.js';
+import { isStaticUrl, scanJsEndpoints } from './scanners/js.js';
+import { bundleLang, parseProperties } from './scanners/properties.js';
+import { loadOccFields, OccReference } from './occ/reference.js';
+import { suggestRoute } from './routes.js';
+import { kebab, LineMap, walkFiles } from './util.js';
+/** EL roots provided by the container, never part of the OCC contract. */
+const INFRA_ROOTS = new Set([
+    'contextPath', 'themeResourcePath', 'siteRootUrl', 'request', 'pageContext', 'param', 'params', 'sessionScope',
+    'requestScope', 'applicationScope', 'cookie', 'header', 'initParam', 'jspContext', 'pageScope', 'fn'
+]);
+export function analyzeStorefront(storefrontPath, options = {}) {
+    const root = path.resolve(storefrontPath);
+    if (!existsSync(root) || !statSync(root).isDirectory()) {
+        throw new Error(`Storefront path not found or not a directory: ${storefrontPath}`);
+    }
+    const warnings = [];
+    const files = walkFiles(root, (m) => warnings.push(m));
+    const { fields, source: occSource } = loadOccFields(options.occFieldsPath);
+    const occ = new OccReference(fields);
+    const textCache = new Map();
+    const readText = (rel) => {
+        if (!textCache.has(rel)) {
+            try {
+                textCache.set(rel, readFileSync(path.join(root, rel), 'utf8'));
+            }
+            catch (e) {
+                warnings.push(`Cannot read ${rel}: ${e.message}`);
+                textCache.set(rel, undefined);
+            }
+        }
+        return textCache.get(rel);
+    };
+    // --- i18n bundles ---
+    const bundles = [];
+    for (const f of files) {
+        const lang = bundleLang(path.posix.basename(f));
+        if (!lang)
+            continue;
+        const text = readText(f);
+        if (text !== undefined)
+            bundles.push({ lang, file: f, entries: parseProperties(text) });
+    }
+    const langBundles = bundles.filter((b) => b.lang !== 'default').sort((a, b) => a.lang.localeCompare(b.lang));
+    const defaultBundle = bundles.find((b) => b.lang === 'default');
+    const referenceLanguage = langBundles.find((b) => b.lang === 'en')?.lang ?? langBundles[0]?.lang;
+    if (!langBundles.length)
+        warnings.push('No base_<lang>.properties files found: i18n coverage was not checked.');
+    // --- CMS ---
+    const impexSets = [];
+    const itemTypes = [];
+    for (const f of files) {
+        if (f.endsWith('.impex')) {
+            const t = readText(f);
+            if (t !== undefined)
+                impexSets.push(...parseImpex(t, f));
+        }
+        else if (/items\.xml$/.test(f)) {
+            const t = readText(f);
+            if (t !== undefined)
+                itemTypes.push(...parseItemsXml(t, f));
+        }
+    }
+    const cmsTypes = buildCmsTypes(impexSets, itemTypes);
+    // --- templates ---
+    const tagFiles = files.filter((f) => f.endsWith('.tag'));
+    const jspFiles = files.filter((f) => f.endsWith('.jsp'));
+    const jsFiles = files.filter((f) => f.endsWith('.js'));
+    const scanCache = new Map();
+    const getScan = (rel) => {
+        if (!scanCache.has(rel)) {
+            const t = readText(rel);
+            scanCache.set(rel, t === undefined ? undefined : scanTemplate(t, rel));
+        }
+        return scanCache.get(rel);
+    };
+    const jsEndpointCache = new Map();
+    const getJsEndpoints = (rel) => {
+        if (!jsEndpointCache.has(rel)) {
+            const t = readText(rel);
+            let eps = [];
+            if (t !== undefined) {
+                try {
+                    const lm = new LineMap(t);
+                    eps = scanJsEndpoints(t, (i) => lm.lineAt(i));
+                }
+                catch (e) {
+                    warnings.push(`${rel}: JS scanner error: ${e.message}`);
+                }
+            }
+            jsEndpointCache.set(rel, eps);
+        }
+        return jsEndpointCache.get(rel);
+    };
+    const endsWithPath = (list, suffix) => {
+        const s = suffix.replace(/^\/+/, '');
+        return list.find((f) => f === s || f.endsWith('/' + s));
+    };
+    const resolveTagFile = (tagdir, name) => endsWithPath(tagFiles, `${tagdir.replace(/^\/+|\/+$/g, '')}/${name}.tag`);
+    const resolveInclude = (target, from) => {
+        if (/\$\{/.test(target) || /^https?:/.test(target))
+            return undefined;
+        const rel = target.startsWith('/') ? target : path.posix.join(path.posix.dirname(from), target);
+        return endsWithPath(jspFiles, rel);
+    };
+    // --- unit builder ---
+    const buildUnit = (entry, kind, id, extra = {}) => {
+        const unitWarnings = [];
+        const unitFiles = [];
+        const visited = new Set();
+        const tagIncludes = [];
+        const conditionals = [];
+        const i18nMap = new Map();
+        const dynamicI18n = [];
+        const hardcoded = [];
+        const dataMap = new Map();
+        const endpointMap = new Map();
+        const cmsSlots = [];
+        const overrides = extra.overrides ?? {};
+        const addEndpoint = (ep, file) => {
+            if (isStaticUrl(ep.url))
+                return;
+            const key = `${ep.method} ${ep.url}`;
+            let e = endpointMap.get(key);
+            if (!e) {
+                const external = /^(https?:)?\/\//i.test(ep.url);
+                const occEquivalent = external ? undefined : occ.matchEndpoint(ep.url, ep.method);
+                e = {
+                    kind: ep.kind,
+                    method: ep.method,
+                    url: ep.url,
+                    status: external ? 'external' : occEquivalent ? 'mapped' : 'missing',
+                    occEquivalent,
+                    refs: [],
+                    requestFields: [],
+                    responseFields: []
+                };
+                endpointMap.set(key, e);
+            }
+            e.refs.push({ file, line: ep.line });
+            for (const f of ep.requestFields)
+                if (!e.requestFields.includes(f))
+                    e.requestFields.push(f);
+            for (const f of ep.responseFields)
+                if (!e.responseFields.includes(f))
+                    e.responseFields.push(f);
+        };
+        const visit = (file, name, line) => {
+            const node = { name, file, line, children: [] };
+            if (visited.has(file)) {
+                node.repeated = true;
+                return node;
+            }
+            visited.add(file);
+            unitFiles.push(file);
+            const scan = getScan(file);
+            if (!scan) {
+                unitWarnings.push(`${file}: could not be read`);
+                return node;
+            }
+            unitWarnings.push(...scan.warnings);
+            for (const c of scan.conditionals)
+                conditionals.push({ ...c, file });
+            for (const s of scan.cmsSlots)
+                cmsSlots.push({ file, ...s });
+            for (const r of scan.i18n) {
+                if (r.dynamic) {
+                    dynamicI18n.push({ file, line: r.line, tag: r.tag, expression: r.key });
+                    continue;
+                }
+                let u = i18nMap.get(r.key);
+                if (!u) {
+                    u = { key: r.key, refs: [], texts: {}, missingIn: [] };
+                    i18nMap.set(r.key, u);
+                }
+                u.refs.push({ file, line: r.line, tag: r.tag });
+                if (r.defaultText && !u.defaultText)
+                    u.defaultText = r.defaultText;
+            }
+            for (const h of scan.hardcoded)
+                hardcoded.push({ ...h, file });
+            for (const ref of scan.elRefs) {
+                const root0 = ref.path.split('.')[0];
+                if (INFRA_ROOTS.has(root0))
+                    continue;
+                let d = dataMap.get(ref.path);
+                if (!d) {
+                    const check = occ.checkPath(ref.path, scan.aliases, overrides);
+                    d = { path: ref.path, root: root0, occType: check.occType, status: check.status, missingField: check.missingField, refs: [] };
+                    if (check.status === 'missing') {
+                        const declared = extra.cmsType?.attributes.find((a) => a.name === check.missingField);
+                        d.note = declared
+                            ? `Custom CMS attribute declared at ${declared.file}:${declared.line} (${declared.source}); OCC only returns it if the component type is mapped in the OCC DTO configuration.`
+                            : `\`${check.missingField}\` is not part of the OCC reference for ${check.occType}.`;
+                    }
+                    dataMap.set(ref.path, d);
+                }
+                d.refs.push({ file, line: ref.line });
+            }
+            for (const ep of scan.endpoints)
+                if (ep.usage === 'ajax')
+                    addEndpoint(ep, file);
+            // JS files referenced by <script src>
+            for (const src of scan.scriptRefs) {
+                const js = endsWithPath(jsFiles, src.split(/[?#]/)[0].split('/').pop() ?? '');
+                if (!js)
+                    continue;
+                if (!unitFiles.includes(js))
+                    unitFiles.push(js);
+                for (const ep of getJsEndpoints(js))
+                    addEndpoint(ep, js);
+            }
+            // children: includes and tag usages, in source order
+            const children = [];
+            for (const inc of scan.includes) {
+                children.push({
+                    line: inc.line,
+                    build: () => {
+                        const target = resolveInclude(inc.target, file);
+                        if (target)
+                            node.children.push(visit(target, path.posix.basename(target), inc.line));
+                        else if (!/^https?:/.test(inc.target))
+                            unitWarnings.push(`${file}:${inc.line}: include target not found in storefront: ${inc.target}`);
+                    }
+                });
+            }
+            for (const u of scan.tagUsages) {
+                children.push({
+                    line: u.line,
+                    build: () => {
+                        const tagFile = resolveTagFile(u.tagdir, u.name);
+                        const label = `${u.prefix}:${u.name}`;
+                        tagIncludes.push({ name: label, tagFile, file, line: u.line });
+                        if (tagFile)
+                            node.children.push(visit(tagFile, label, u.line));
+                        else
+                            unitWarnings.push(`${file}:${u.line}: tag file not found for <${label}> (tagdir ${u.tagdir})`);
+                    }
+                });
+            }
+            children.sort((a, b) => a.line - b.line);
+            children.forEach((c) => c.build());
+            return node;
+        };
+        const tree = visit(entry, path.posix.basename(entry));
+        // --- i18n resolution ---
+        const i18n = [...i18nMap.values()].sort((a, b) => a.key.localeCompare(b.key));
+        for (const u of i18n) {
+            for (const b of langBundles) {
+                const hit = b.entries.get(u.key) ?? defaultBundle?.entries.get(u.key);
+                if (hit)
+                    u.texts[b.lang] = hit.value;
+                else
+                    u.missingIn.push(b.lang);
+            }
+            if (!langBundles.length && defaultBundle?.entries.get(u.key))
+                u.texts.default = defaultBundle.entries.get(u.key).value;
+        }
+        const i18nCoverage = langBundles.map((b) => ({
+            lang: b.lang,
+            file: b.file,
+            present: i18n.filter((u) => b.lang in u.texts).length,
+            total: i18n.length
+        }));
+        const data = [...dataMap.values()].sort((a, b) => a.path.localeCompare(b.path));
+        const endpoints = [...endpointMap.values()];
+        // --- gaps ---
+        const gaps = [];
+        for (const d of data.filter((x) => x.status === 'missing')) {
+            gaps.push({ kind: 'data', id: `data:${d.path}`, summary: `${d.path}: \`${d.missingField}\` is not exposed by OCC on ${d.occType}`, refs: d.refs });
+        }
+        for (const e of endpoints.filter((x) => x.status === 'missing')) {
+            gaps.push({ kind: 'endpoint', id: `endpoint:${e.method} ${e.url}`, summary: `${e.method} ${e.url} has no known OCC equivalent`, refs: e.refs });
+        }
+        for (const b of langBundles) {
+            const missing = i18n.filter((u) => u.missingIn.includes(b.lang));
+            if (missing.length) {
+                gaps.push({
+                    kind: 'i18n',
+                    id: `i18n:${b.lang}`,
+                    summary: `${missing.length} of ${i18n.length} keys missing in ${b.lang}`,
+                    refs: missing.flatMap((m) => m.refs.slice(0, 1).map(({ file, line }) => ({ file, line })))
+                });
+            }
+        }
+        if (hardcoded.length) {
+            gaps.push({
+                kind: 'hardcoded-text',
+                id: 'hardcoded-text',
+                summary: `${hardcoded.length} hardcoded literal string(s) in templates`,
+                refs: hardcoded.map(({ file, line }) => ({ file, line }))
+            });
+        }
+        const dataGaps = data.filter((d) => d.status === 'missing').length;
+        const epGaps = endpoints.filter((e) => e.status === 'missing').length;
+        const missingKeys = i18n.reduce((n, u) => n + u.missingIn.length, 0);
+        const score = conditionals.length * 2 + dataGaps * 2 + epGaps * 3 + (visited.size - 1) + missingKeys * 0.5 + hardcoded.length * 0.5;
+        const level = score < 10 ? 'low' : score < 25 ? 'medium' : 'high';
+        const dependsOn = [
+            ...new Set([
+                ...tagIncludes.map((t) => t.name),
+                ...data.filter((d) => d.status === 'missing' && d.occType).map((d) => `occ-extension:${d.occType}`),
+                ...endpoints.filter((e) => e.status === 'missing').map((e) => `endpoint:${e.method} ${e.url}`)
+            ])
+        ];
+        const routeInfo = kind === 'page' ? suggestRoute(id) : { route: `(CMS component, rendered inside a Spartacus page)`, routeSource: 'derived', currentUrl: undefined };
+        return {
+            id,
+            kind,
+            file: entry,
+            files: unitFiles,
+            currentUrl: routeInfo.currentUrl,
+            route: routeInfo.route,
+            routeSource: routeInfo.routeSource,
+            cmsType: extra.cmsType?.code,
+            cmsSlots,
+            tree,
+            tagIncludes,
+            conditionals,
+            i18n,
+            dynamicI18n,
+            i18nCoverage,
+            hardcoded,
+            data,
+            endpoints,
+            gaps,
+            dependsOn,
+            complexity: { score, level },
+            warnings: [...new Set(unitWarnings)]
+        };
+    };
+    // --- pages ---
+    const usedIds = new Set();
+    const uniqueId = (id) => {
+        let out = id;
+        let n = 2;
+        while (usedIds.has(out))
+            out = `${id}-${n++}`;
+        usedIds.add(out);
+        return out;
+    };
+    const pages = [];
+    for (const f of jspFiles.filter((x) => /(^|\/)pages\/.+\.jsp$/.test(x))) {
+        const rel = f.slice(f.lastIndexOf('pages/') + 'pages/'.length).replace(/\.jsp$/, '');
+        const parts = rel.split('/');
+        const last = kebab(parts.pop()).replace(/-page$/, '');
+        const dirs = parts.map(kebab);
+        const id = uniqueId(dirs.length && !last.startsWith(dirs[dirs.length - 1]) ? `${dirs.join('-')}-${last}` : last);
+        pages.push(buildUnit(f, 'page', id));
+    }
+    if (!pages.length)
+        warnings.push('No pages found (expected JSPs under a "pages/" directory).');
+    // --- CMS components ---
+    const components = [];
+    for (const f of jspFiles.filter((x) => /(^|\/)cms\/[^/]+\.jsp$/.test(x))) {
+        const base = path.posix.basename(f, '.jsp');
+        const type = cmsTypes.find((t) => t.code.toLowerCase() === base.toLowerCase());
+        if (type)
+            type.jsp = f;
+        let known = 'CMSComponent';
+        let cursor = type?.extends;
+        for (let i = 0; cursor && i < 10; i++) {
+            if (occ.hasType(cursor)) {
+                known = cursor;
+                break;
+            }
+            cursor = cmsTypes.find((t) => t.code === cursor)?.extends ?? itemTypes.find((t) => t.code === cursor)?.extends;
+        }
+        const stem = (type?.code ?? base).replace(/component$/i, '');
+        const id = uniqueId('component-' + kebab(type ? stem : base.replace(/component$/i, '')));
+        components.push(buildUnit(f, 'component', id, { cmsType: type, overrides: { component: known } }));
+    }
+    const all = [...pages, ...components];
+    const model = {
+        version: 1,
+        storefront: path.basename(root),
+        occFieldsSource: occSource,
+        languages: langBundles.map((b) => ({ lang: b.lang, file: b.file, keyCount: b.entries.size })),
+        referenceLanguage,
+        cmsComponentTypes: cmsTypes,
+        pages,
+        components,
+        summary: {
+            pages: pages.length,
+            components: components.length,
+            tagFiles: tagFiles.length,
+            languages: langBundles.length,
+            conditionals: all.reduce((n, u) => n + u.conditionals.length, 0),
+            dataGaps: all.reduce((n, u) => n + u.gaps.filter((g) => g.kind === 'data').length, 0),
+            missingEndpoints: all.reduce((n, u) => n + u.gaps.filter((g) => g.kind === 'endpoint').length, 0),
+            missingI18nKeys: all.reduce((n, u) => n + u.i18n.reduce((m, k) => m + k.missingIn.length, 0), 0),
+            hardcodedStrings: all.reduce((n, u) => n + u.hardcoded.length, 0)
+        },
+        warnings: [...warnings, ...all.flatMap((u) => u.warnings.map((w) => `[${u.id}] ${w}`))]
+    };
+    return model;
+}

package/dist/cli.d.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+/** Safe folder name for a storefront path: its last segment, resolved when it is `.`, `..` or a drive root. */
+export declare function storefrontFolderName(target: string): string;
+export declare function main(argv: string[]): number;