@omega.js/web 0.1.0

package/dist/migrate/consumer-assets.js

@@ -0,0 +1,130 @@
+/**
+ * consumer-assets.js — the consumer asset-layer migration step (JS + CSS).
+ *
+ * JS: UJM consumers ship `src/assets/js/main.js` importing
+ * 'ultimate-jekyll-manager' (webpack bundled the runtime through it). In
+ * @omega.js/web the core asset layer OWNS main.js and the boot runtime does
+ * the initialize dance — a consumer main.js SHADOWS the core one entirely.
+ * - Seed-identical main.js (the untouched UJM scaffold) → deleted; the core
+ *   main takes over. Detected by comment/whitespace-insensitive comparison.
+ * - Customized main.js → error finding with the port recipe (compose the
+ *   core main: `import coreMain from '__main_assets__/js/main.js'` inside an
+ *   `export default async ({ manager, options })` module). Custom logic is
+ *   not mechanically separable from the seed boilerplate.
+ * - Any OTHER src/assets/js file importing 'ultimate-jekyll-manager' →
+ *   error finding (no equivalent module exists to alias).
+ *
+ * CSS: consumers customize theme variables via
+ * `@use 'ultimate-jekyll-manager' as * with ($primary: …)` in
+ * `src/assets/css/main.scss`. The migrated spelling is `omega:main` — the
+ * layered sass importer resolves it to the main bundle from the layers BELOW
+ * the consumer (theme → core), and core main.scss forwards `omega:theme`, so
+ * `with (…)` configuration reaches the theme variables. Mechanical rewrite,
+ * applied to every scss file referencing the old package name.
+ *
+ * Page css (`css/pages/<key>.scss`): the UJM seed pulls the theme's page
+ * styles with a same-name `@use 'pages/<key>'` (webpack-era single bundle).
+ * The new pipeline compiles EVERY layer's sheet for a key and the head links
+ * them all in layer order (#624), so the self-@use would double every
+ * framework rule AND self-loop through the loadPaths. The line is dropped.
+ *
+ * Page modules (`js/pages/**`) already match the new `{ manager, options }`
+ * export-default convention and import '@omega.js/client' (aliased by the asset
+ * pipeline) — they port verbatim, nothing to do.
+ */
+const fs = require('node:fs');
+const path = require('node:path');
+
+// The UJM consumer seed, as scaffolded into every consumer
+const SEED_MAIN = `
+import Manager from 'ultimate-jekyll-manager';
+const manager = new Manager();
+manager.initialize()
+.then(() => {
+  console.log('Ultimate Jekyll Manager initialized successfully');
+});
+`;
+
+const UJM_IMPORT = /from\s+['"]ultimate-jekyll-manager['"]|require\(\s*['"]ultimate-jekyll-manager['"]\s*\)/;
+const UJM_SCSS_USE = /(@(?:use|forward|import)\s+["'])ultimate-jekyll-manager(["'])/g;
+
+/**
+ * Comment- and whitespace-insensitive normalization for seed comparison.
+ */
+function normalizeJs(text) {
+  return text
+    .replace(/\/\/[^\n]*/g, '')
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+const SEED_NORMALIZED = normalizeJs(SEED_MAIN);
+
+/**
+ * Migrate the consumer asset layer (JS deletion/flagging + scss rewrites).
+ * @param {string} root - consumer project root
+ * @param {object} [options]
+ * @param {boolean} [options.write]
+ * @returns {{ removed: string[], edits: object[], findings: object[] }}
+ */
+function migrateConsumerAssets(root, options = {}) {
+  const assetsDir = path.join(root, 'src', 'assets');
+  const removed = [];
+  const edits = [];
+  const findings = [];
+  if (!fs.existsSync(assetsDir)) return { removed, edits, findings };
+
+  for (const entry of fs.readdirSync(assetsDir, { recursive: true, withFileTypes: true })) {
+    if (!entry.isFile()) continue;
+    const full = path.join(entry.parentPath, entry.name);
+    const rel = path.relative(root, full);
+
+    // ---- scss: rewrite the package reference to the layered importer, and
+    // drop the page-css self-@use (theme page styles now load separately)
+    if (entry.name.endsWith('.scss')) {
+      const text = fs.readFileSync(full, 'utf8');
+      let rewritten = text;
+
+      if (UJM_SCSS_USE.test(rewritten)) {
+        UJM_SCSS_USE.lastIndex = 0;
+        rewritten = rewritten.replace(UJM_SCSS_USE, '$1omega:main$2');
+        edits.push({ rule: 'scss-package-use', file: rel, before: "@use 'ultimate-jekyll-manager'", after: "@use 'omega:main'" });
+      }
+
+      const relCss = path.relative(path.join(assetsDir, 'css'), full);
+      if (relCss.startsWith(`pages${path.sep}`)) {
+        const selfKey = relCss.replace(/\.scss$/, '').split(path.sep).join('/');
+        const selfUse = new RegExp(`^\\s*@use\\s+["']${selfKey}["'][^\\n]*\\n?`, 'm');
+        if (selfUse.test(rewritten)) {
+          rewritten = rewritten.replace(selfUse, '');
+          edits.push({ rule: 'scss-page-self-use', file: rel, before: `@use '${selfKey}'`, after: '(removed — every layer\'s page sheet already loads)' });
+        }
+      }
+
+      if (rewritten !== text && options.write) fs.writeFileSync(full, rewritten);
+      continue;
+    }
+
+    if (!entry.name.endsWith('.js')) continue;
+    const text = fs.readFileSync(full, 'utf8');
+    if (!UJM_IMPORT.test(text)) continue;
+
+    if (rel === path.join('src', 'assets', 'js', 'main.js') && normalizeJs(text) === SEED_NORMALIZED) {
+      if (options.write) fs.rmSync(full);
+      removed.push(rel);
+      continue;
+    }
+
+    findings.push({
+      file: rel, line: 1, check: 'ujm-import', severity: 'error',
+      message: rel.endsWith(`${path.sep}main.js`)
+        ? 'customized main.js imports ultimate-jekyll-manager — port manually: `import coreMain from \'__main_assets__/js/main.js\'` inside `export default async (context) => { await coreMain(context); /* custom code */ }`'
+        : 'imports ultimate-jekyll-manager — no such module in @omega.js/web; port to @omega.js/client or a core module',
+    });
+  }
+
+  return { removed, edits, findings };
+}
+
+module.exports = { migrateConsumerAssets };

package/dist/migrate/index.js

@@ -0,0 +1,223 @@
+/**
+ * index.js — the `omega migrate` orchestrator: one call converts a UJM
+ * consumer to @omega.js/web.
+ *
+ *   1. Config: _config.yml + ultimate-jekyll-manager.json → config/omega.json5
+ *      (validated through the real @omega.js/config loader after writing).
+ *   2. Codemod: the rule tables over src/** templates and consumer JS
+ *      (rules.js), plus the consumer asset layer (consumer-assets.js).
+ *   3. Lint: the liquid-lint scanner over the (rewritten) templates.
+ *   4. Hygiene: legacy files removed (Gemfile, lockfile, the old configs).
+ *   5. Tests: the legacy UJM harness, reported (never rewritten).
+ *   6. Dependencies: bare requires the consumer never declared, reported and
+ *      never installed. The scan is @omega.js/devkit's `src/bare-requires.js`,
+ *      shared with @omega.js/backend's own migrate (#600); web supplies its
+ *      bundler aliases.
+ *
+ * `check: true` runs everything IN MEMORY — full report, zero writes.
+ */
+const fs = require('node:fs');
+const path = require('node:path');
+const { loadConfig, resolveConfigPath, findBrandConfigPath } = require('../vendor/config/index.js');
+const { convertConfig, readLegacyConfigs, serializeOmega } = require('./config-convert.js');
+const { runCodemod, collectTemplateFiles } = require('./codemod.js');
+const { configReads: configReadsRule } = require('./rules.js');
+const { lintText } = require('./lint.js');
+const { migrateConsumerAssets } = require('./consumer-assets.js');
+const { collectBareRequires } = require('../vendor/devkit/bare-requires.js');
+
+const BUNDLER_ALIASES = ['__main_assets__', '__theme__', '@omega.js/client'];
+
+// Legacy files deleted by a real migration (relative to the consumer root)
+const LEGACY_FILES = [
+  'src/_config.yml',
+  'config/ultimate-jekyll-manager.json',
+  'Gemfile',
+  'Gemfile.lock',
+  '.ruby-version',
+];
+
+// The legacy UJM harness. Its runner discovered ALL of `test/**/*.js`
+// (excluding `_`-prefixed files and any `_`-prefixed directory — helpers,
+// fixtures, `_init.js`) and read the layer from the module's own export, never
+// from the path; `omega test` runs `node --test 'test/**/*.test.js'`, which
+// matches almost none of them and reports a green `pass 0` — a migrated
+// brand's whole regression suite goes dark without a word
+// ([#248](https://github.com/Omega-JS-Stack/omega/issues/248)).
+//
+// Detection is by SHAPE, not by name: a harness module named `config.test.js`
+// IS discovered by node:test, loads, registers no tests, and counts as a pass —
+// the loudest false green there is. So a file that exports a module and never
+// touches node:test is legacy whatever it is called, and a file that requires
+// node:test is ported whatever it is called. Cheap enough to read: no execution.
+const NODE_TEST_IMPORT = /(?:require\(\s*|from\s+)['"]node:test['"]/;
+const MODULE_EXPORT = /(?:^|\n)\s*(?:module\.exports\s*=|exports\.[\w$]+\s*=|export\s+default\b)/;
+
+/**
+ * Whether a test-dir file is a legacy-harness module rather than a node:test
+ * file, judged by its content.
+ * @param {string} text - the file's source
+ * @returns {boolean}
+ */
+function isLegacyHarnessFile(text) {
+  if (NODE_TEST_IMPORT.test(text)) return false;
+  return MODULE_EXPORT.test(text);
+}
+
+/**
+ * Collect the legacy-harness test files `omega test` cannot discover (or
+ * discovers and silently counts as an empty pass).
+ * @param {string} root - consumer project root
+ * @returns {string[]} paths relative to the root
+ */
+function collectLegacyTests(root) {
+  const testDir = path.join(root, 'test');
+  if (!fs.existsSync(testDir)) return [];
+
+  const files = [];
+  const walk = (current) => {
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      if (entry.name.startsWith('_')) continue;
+      const full = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        walk(full);
+        continue;
+      }
+      if (!entry.isFile() || path.extname(entry.name) !== '.js') continue;
+      if (isLegacyHarnessFile(fs.readFileSync(full, 'utf8'))) files.push(path.relative(root, full));
+    }
+  };
+  walk(testDir);
+  return files.sort();
+}
+
+/**
+ * Migrate a UJM consumer in place (or preview with `check`).
+ * @param {string} root - consumer project root
+ * @param {object} [options]
+ * @param {boolean} [options.check] - report only, write nothing
+ * @returns {object} report
+ */
+function runMigration(root, options = {}) {
+  const write = !options.check;
+  const report = { root, check: !write, config: null, codemod: null, lint: [], removed: [], legacyTests: [], bareRequires: [], errors: [] };
+
+  // ---- 1. Config conversion
+  const { jekyll, ujm, files: legacySources } = readLegacyConfigs(root);
+  const omegaPath = path.join(root, 'config', 'omega.json5');
+  // The legacy guard runs FIRST, and stays first: a root that still carries
+  // _config.yml / ultimate-jekyll-manager.json is MID-conversion — the
+  // omega.json5 beside (or above) it is an earlier partial run or the brand
+  // layer, and the legacy sources are the truth to convert from. Probing for a
+  // converted config before this check would skip those roots forever.
+  if (!jekyll && !ujm) {
+    // Pre-converted is the fleet-standard order, not a failure
+    // ([#297](https://github.com/Omega-JS-Stack/omega/issues/297)): the brand
+    // root's omega.json5 lands first and the target's UJM configs are gone before
+    // migrate ever runs, so the config step is DONE and the codemods below are
+    // the rest of the job. Only a root with neither legacy configs NOR a
+    // resolvable omega.json5 is genuinely broken.
+    //
+    // The omega.json5 the loadConfig contract resolves for this root: its own
+    // file, else its brand root's (a target inside a brand monorepo rides the
+    // brand config alone — the local-layer file is optional there).
+    const converted = resolveConfigPath(root) || findBrandConfigPath(root);
+    if (converted) {
+      report.config = { skipped: true, path: path.relative(root, converted) };
+      // "Already converted" is a claim about a config that WORKS, so the skip
+      // branch runs the same loader validation the conversion branch does —
+      // a file that throws (unparseable, secrets, bad targets) or carries
+      // schema findings is a loud error here, never a silent exit 0.
+      try {
+        const { errors } = loadConfig(root, 'web');
+        report.config.validation = errors.map((error) => error.message || String(error));
+      } catch (e) {
+        report.config.validation = [e.message];
+      }
+      report.errors.push(...report.config.validation);
+    } else {
+      report.errors.push('no legacy configs found (src/_config.yml / config/ultimate-jekyll-manager.json)');
+    }
+  } else {
+    const { omega, notes } = convertConfig({ jekyll, ujm });
+    report.config = { path: path.relative(root, omegaPath), sources: legacySources.map((file) => path.relative(root, file)), notes, omega };
+    if (write) {
+      fs.mkdirSync(path.dirname(omegaPath), { recursive: true });
+      fs.writeFileSync(omegaPath, serializeOmega(omega));
+
+      // Validate through the real loader — findings surface in the report
+      const { errors } = loadConfig(root, 'web');
+      report.config.validation = errors.map((error) => error.message || String(error));
+    }
+  }
+
+  // ---- 2. Codemod over src/** templates + the consumer asset layer
+  report.codemod = runCodemod(root, { write });
+  const assets = migrateConsumerAssets(root, { write });
+  report.removed.push(...assets.removed);
+  report.lint.push(...assets.findings);
+  if (assets.edits.length > 0) {
+    report.codemod.files.push(...assets.edits.map((edit) => ({ path: edit.file, edits: [edit] })));
+    report.codemod.totalEdits += assets.edits.length;
+  }
+
+  // ---- 2b. The CONFIG file's own string values (#671). `targets.web.meta.title:
+  // "Agency - {{ site.brand.name }}"` is a read like any other and has rendered
+  // empty since #611 — but the codemod walks `src/**` and the build census is
+  // per-template, so nothing saw it. Rewritten in the FILE, not the parsed
+  // object: a brand's omega.json5 carries comments, and re-serializing would
+  // eat them.
+  //
+  // A CHECK run on a legacy root has no file to read — it wrote nothing — so
+  // the scan runs over the config the run WOULD have written. Skipping it there
+  // reported a clean bill for exactly the pre-flight case `--check` is for.
+  const resolvedConfigPath = report.config && report.config.path && path.resolve(root, report.config.path);
+  const configExists = Boolean(resolvedConfigPath) && fs.existsSync(resolvedConfigPath);
+  const configText = configExists ? fs.readFileSync(resolvedConfigPath, 'utf8')
+    : (resolvedConfigPath && report.config.omega ? serializeOmega(report.config.omega) : null);
+  if (configText !== null) {
+    const rel = path.relative(root, resolvedConfigPath);
+    const { text, edits, findings } = configReadsRule.apply(configText);
+    if (edits.length > 0) {
+      // `write` implies the file exists: the conversion branch above wrote it,
+      // and the skip branch resolved one that was already there.
+      if (write) fs.writeFileSync(resolvedConfigPath, text);
+      report.codemod.files.push({ path: rel, edits });
+      report.codemod.totalEdits += edits.length;
+      report.lint.push(...findings.map((finding) => ({ ...finding, file: rel })));
+    }
+  }
+
+  // ---- 3. Liquid-lint over the (post-rewrite) templates
+  for (const filePath of collectTemplateFiles(path.join(root, 'src'))) {
+    report.lint.push(...lintText(fs.readFileSync(filePath, 'utf8'), path.relative(root, filePath)));
+  }
+  report.lint.push(...report.codemod.findings);
+
+  // ---- 4. Legacy file hygiene
+  for (const rel of LEGACY_FILES) {
+    const full = path.join(root, rel);
+    if (!fs.existsSync(full)) continue;
+    if (write) fs.rmSync(full);
+    report.removed.push(rel);
+  }
+
+  // ---- 5. Legacy test harness (reported, never rewritten — porting a suite
+  // to node:test is by hand)
+  report.legacyTests = collectLegacyTests(root);
+
+  // ---- 6. Dependency resolution (#600): a bare require that only the legacy
+  // FLAT install answered. Reported with the fix, never installed. The scan is
+  // devkit's, shared with @omega.js/backend's own migrate; what web adds is its
+  // BUNDLER ALIASES, the specifiers the build resolves for the consumer,
+  // subpaths included ([index.md](../../../../docs/web/index.md): `__main_assets__/*`
+  // to the core layer, `__theme__/*` to the active theme, `@omega.js/client` to
+  // the client package). None is a dependency a consumer may declare, since
+  // installing `@omega.js/client` beside the framework is a SECOND client
+  // runtime, so naming them would hand the report a fix that breaks the project.
+  report.bareRequires = collectBareRequires(root, { aliases: BUNDLER_ALIASES });
+
+  return report;
+}
+
+module.exports = { runMigration, LEGACY_FILES };

package/dist/migrate/lint.js

@@ -0,0 +1,108 @@
+/**
+ * lint.js — the liquid-lint scanner: checks the codemod cannot express as a
+ * safe rewrite. Runs over the SAME file set as the codemod (post-rewrite in
+ * a real migration, pre-flight in --check).
+ *
+ * Known filter/tag names are derived at runtime from the REAL engine
+ * registration path (a LiquidJS instance + template-kit's registerLiquid +
+ * the framework's own section/component tags) — the same SSOT the build uses,
+ * so the lists can't drift.
+ */
+const { Liquid } = require('liquidjs');
+const { registerLiquid } = require('../vendor/template-kit/index.js');
+const { registerSectionTags } = require('../sections.js');
+
+// Jekyll-only tags with no LiquidJS/engine equivalent — hard findings
+const JEKYLL_ONLY_TAGS = {
+  post_url: 'link to the post URL directly (e.g. /blog/<slug>/)',
+  link: 'use the file\'s output URL directly',
+  highlight: 'use fenced code blocks (markdown-it)',
+  endhighlight: 'use fenced code blocks (markdown-it)',
+  include_relative: 'move the include into _includes and use {% include %}',
+  feed_meta: 'the engine renders feeds — remove the tag',
+  seo: 'the core head include owns SEO tags — remove',
+};
+
+// Names Eleventy adds on top of LiquidJS + template-kit
+const ELEVENTY_NAMES = ['log', 'slugify', 'url', 'getCollectionItem', 'getPreviousCollectionItem', 'getNextCollectionItem', 'renderFile', 'inputPathToUrl'];
+
+let registry = null;
+
+/**
+ * Build (once) the known filter/tag name sets from the real registration path.
+ * @returns {{ filters: Set<string>, tags: Set<string> }}
+ */
+function knownNames() {
+  if (registry) return registry;
+  const engine = new Liquid({ jekyllInclude: true });
+  registerLiquid(engine, {});
+  // The target shape the lane converts INTO (#489): `{% section %}` and its
+  // siblings are registered by the framework, not template-kit, so without
+  // them a fully converted tree could never lint clean. No resolution roots —
+  // the lint asks which NAMES the engine knows, never what they render.
+  registerSectionTags(engine, { baseDirs: [], warn: () => {} });
+  const filters = new Set([...Object.keys(engine.filters), ...ELEVENTY_NAMES]);
+  const tags = new Set(Object.keys(engine.tags));
+  // Block tags close with end<name>; Liquid's own end tags are parser-internal
+  for (const tag of [...tags]) tags.add(`end${tag}`);
+  ['else', 'elsif', 'when', 'endif', 'endfor', 'endunless', 'endcase', 'endcapture', 'endcomment', 'endraw', 'endtablerow'].forEach((tag) => tags.add(tag));
+  registry = { filters, tags };
+  return registry;
+}
+
+/**
+ * Strip {% raw %}…{% endraw %} spans and {% comment %}…{% endcomment %}
+ * spans so their contents don't produce findings.
+ */
+function stripInertSpans(text) {
+  return text
+    .replace(/\{%-?\s*raw\s*-?%\}[\s\S]*?\{%-?\s*endraw\s*-?%\}/g, (span) => span.replace(/\S/g, ' '))
+    .replace(/\{%-?\s*comment\s*-?%\}[\s\S]*?\{%-?\s*endcomment\s*-?%\}/g, (span) => span.replace(/\S/g, ' '));
+}
+
+/**
+ * Lint one file's text.
+ * @param {string} text
+ * @param {string} filePath
+ * @returns {object[]} findings ({ file, line, check, severity, message })
+ */
+function lintText(text, filePath) {
+  const { filters, tags } = knownNames();
+  const findings = [];
+  const lines = stripInertSpans(text).split('\n');
+
+  lines.forEach((line, index) => {
+    // Unknown tags: {% name … %}
+    for (const [, name] of line.matchAll(/\{%-?\s*([a-z_][\w]*)/g)) {
+      if (tags.has(name)) continue;
+      if (JEKYLL_ONLY_TAGS[name]) {
+        findings.push({
+          file: filePath, line: index + 1, check: 'jekyll-only-tag', severity: 'error',
+          message: `Jekyll-only tag \`{% ${name} %}\` — ${JEKYLL_ONLY_TAGS[name]}`,
+        });
+      } else {
+        findings.push({
+          file: filePath, line: index + 1, check: 'unknown-tag', severity: 'warning',
+          message: `unknown tag \`{% ${name} %}\` — not registered by the engine; verify`,
+        });
+      }
+    }
+
+    // Unknown filters: | name inside {{ }} or {% %} spans (quoted strings
+    // stripped first — a literal "|" inside an arg is not a filter pipe)
+    for (const span of line.matchAll(/\{\{.*?\}\}|\{%.*?%\}/g)) {
+      const unquoted = span[0].replace(/"[^"]*"|'[^']*'/g, '""');
+      for (const [, name] of unquoted.matchAll(/\|\s*([a-z_][\w]*)/g)) {
+        if (filters.has(name)) continue;
+        findings.push({
+          file: filePath, line: index + 1, check: 'unknown-filter', severity: 'warning',
+          message: `unknown filter \`| ${name}\` — not registered by the engine; verify`,
+        });
+      }
+    }
+  });
+
+  return findings;
+}
+
+module.exports = { lintText, knownNames, JEKYLL_ONLY_TAGS };