@omega.js/extension 0.1.0

package/dist/test/suites/build/setup-scripts.test.js

@@ -0,0 +1,172 @@
+// Build-layer tests for ensure-target's package.json write (#572).
+//
+// `jetpack.write(path, object)` serializes with no trailing newline, and the write
+// rewrote the consumer's package.json unconditionally — so every `npm run build`
+// re-stripped the newline npm itself writes, and the
+// consumer's lint hook or editor put it back, forever.
+//
+// setupScripts defaults to the cwd project, so each test stages a
+// temp project, chdirs into it, and requires the command fresh — the same model
+// as package-task.test.js's inProject().
+
+const path = require('path');
+const fs   = require('fs');
+const os   = require('os');
+const defineCases = require('../../../vendor/devkit/test/define-cases.js');
+
+const SRC        = path.join(__dirname, '..', '..', '..');
+const SETUP_PATH = path.join(SRC, 'commands', 'lib', 'ensure-target.js');
+
+const CONSUMER_PKG = {
+  name: 'staged-ext',
+  version: '3.1.4',
+  scripts: { start: 'echo consumer' },
+  devDependencies: { '@omega.js/extension': '^0.1.0' },
+};
+
+// Stage a temp consumer project holding `pkg`, written the way npm writes it.
+function stageProject(pkg) {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'extension-setup-scripts-'));
+  fs.writeFileSync(path.join(tmp, 'package.json'), `${JSON.stringify(pkg, null, 2)}\n`);
+  return tmp;
+}
+
+// Run `fn(setup)` with cwd pinned to `dir` and the command module loaded fresh.
+async function inProject(dir, fn) {
+  const oldCwd = process.cwd();
+  const flush = () => {
+    for (const key of Object.keys(require.cache)) {
+      if (key.startsWith(SRC + path.sep)) delete require.cache[key];
+    }
+  };
+
+  flush();
+  try {
+    process.chdir(dir);
+    return await fn(require(SETUP_PATH));
+  } finally {
+    process.chdir(oldCwd);
+    flush();
+  }
+}
+
+module.exports = defineCases({
+  type: 'suite',
+  layer: 'build',
+  description: 'ensure-target — the consumer package.json write',
+  tests: [
+    {
+      name: 'the written package.json ends with exactly one trailing newline (#572)',
+      run: async (ctx) => {
+        const tmp = stageProject(CONSUMER_PKG);
+        const pkgPath = path.join(tmp, 'package.json');
+
+        try {
+          await inProject(tmp, async (setup) => {
+            setup.setupScripts();
+
+            const contents = fs.readFileSync(pkgPath, 'utf8');
+            ctx.expect(contents.endsWith('}\n')).toBe(true);
+            ctx.expect(contents.endsWith('}\n\n')).toBe(false);
+
+            // The framework's project scripts landed, npm's own 2-space shape kept
+            const written = JSON.parse(contents);
+            ctx.expect(written.scripts.build).toBe('omega build');
+            ctx.expect(written.private).toBe(true);
+            ctx.expect(contents).toContain('\n  "name": "staged-ext"');
+          });
+        } finally {
+          fs.rmSync(tmp, { recursive: true, force: true });
+        }
+      },
+    },
+    {
+      name: 'an unchanged package.json is not rewritten (#572)',
+      run: async (ctx) => {
+        const tmp = stageProject(CONSUMER_PKG);
+        const pkgPath = path.join(tmp, 'package.json');
+
+        try {
+          await inProject(tmp, async (setup) => {
+            setup.setupScripts();
+            const afterFirst = fs.readFileSync(pkgPath, 'utf8');
+
+            // Backdate the file: a second setup that writes shows up as a new mtime
+            const past = new Date(Date.now() - 60000);
+            fs.utimesSync(pkgPath, past, past);
+
+            setup.setupScripts();
+
+            ctx.expect(Math.round(fs.statSync(pkgPath).mtimeMs)).toBe(Math.round(past.getTime()));
+            ctx.expect(fs.readFileSync(pkgPath, 'utf8')).toBe(afterFirst);
+          });
+        } finally {
+          fs.rmSync(tmp, { recursive: true, force: true });
+        }
+      },
+    },
+    {
+      name: 'a package.json that DID change is written (#572)',
+      run: async (ctx) => {
+        const tmp = stageProject(CONSUMER_PKG);
+        const pkgPath = path.join(tmp, 'package.json');
+
+        try {
+          await inProject(tmp, async (setup) => {
+            setup.setupScripts();
+
+            // A consumer edit setup has to heal — the skip is content-based, not a latch
+            const drifted = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+            drifted.scripts.build = 'echo hand-edited';
+            fs.writeFileSync(pkgPath, `${JSON.stringify(drifted, null, 2)}\n`);
+
+            setup.setupScripts();
+
+            const healed = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+            ctx.expect(healed.scripts.build).toBe('omega build');
+            ctx.expect(fs.readFileSync(pkgPath, 'utf8').endsWith('}\n')).toBe(true);
+          });
+        } finally {
+          fs.rmSync(tmp, { recursive: true, force: true });
+        }
+      },
+    },
+    {
+      name: 'a target still carrying the `npx omega` spelling heals to the bare verb (#748)',
+      run: async (ctx) => {
+        // Package scripts spell the verb bare, web's form — the `npx` prefix
+        // is redundant inside a script (npm puts node_modules/.bin on the
+        // path) and stays canonical only for docs and the terminal. Every
+        // framework-owned key is rewritten on the next verb's ensure pass.
+        const tmp = stageProject({
+          ...CONSUMER_PKG,
+          scripts: { ...CONSUMER_PKG.scripts, test: 'npx omega test', lint: 'npx eslint .' },
+        });
+        const pkgPath = path.join(tmp, 'package.json');
+
+        try {
+          await inProject(tmp, async (setup) => {
+            setup.setupScripts();
+
+            const healed = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+            ctx.expect(healed.scripts.test).toBe('omega test');
+            ctx.expect(healed.scripts.build.includes('npx omega')).toBe(false);
+            ctx.expect(healed.scripts.lint).toBe('npx eslint .');
+
+            // Converged: the second pass writes nothing at all
+            const afterFirst = fs.readFileSync(pkgPath, 'utf8');
+            const past = new Date(Date.now() - 60000);
+            fs.utimesSync(pkgPath, past, past);
+
+            setup.setupScripts();
+
+            ctx.expect(Math.round(fs.statSync(pkgPath).mtimeMs)).toBe(Math.round(past.getTime()));
+            ctx.expect(fs.readFileSync(pkgPath, 'utf8')).toBe(afterFirst);
+          });
+        } finally {
+          fs.rmSync(tmp, { recursive: true, force: true });
+        }
+      },
+    },
+  ],
+});

package/dist/test/suites/build/strip-dev-blocks.test.js

@@ -0,0 +1,122 @@
+// @dev-only strip, extension bundle lane (#18): production extension bundles must
+// not carry the dev-only blocks their inputs hold — @omega.js/client's src and the
+// vendored theme assets both use the markers, and every one of them reaches a
+// popup / options / sidepanel bundle. The mechanism is @omega.js/devkit's bundle
+// wrapper, which registers the strip for PRODUCTION builds only
+// ([#738](https://github.com/Omega-JS-Stack/omega/issues/738) replaced the
+// webpack loader this suite used to drive), so these tests build a real fixture
+// entry through that wrapper from the extension framework root and read the
+// emitted bundle back.
+//
+// The marker + cut themselves are @omega.js/devkit's (one home); pinned there.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const FRAMEWORK_ROOT = path.join(__dirname, '..', '..', '..', '..');
+const { bundle } = require('../../../vendor/devkit/bundle.js');
+const Manager = new (require(path.join(FRAMEWORK_ROOT, 'src', 'build.js')));
+const defineCases = require('../../../vendor/devkit/test/define-cases.js');
+
+const FIXTURE = [
+  '/* @dev-only:start */',
+  'console.log("DEV_ONLY_SENTINEL");',
+  '/* @dev-only:end */',
+  'globalThis.alwaysShips = "PROD_SENTINEL";',
+  '',
+].join('\n');
+
+// Build the fixture the way the extension lane builds a component entry — `dev`
+// is the ONE switch, so the strip is the only variable. Minify stays out of the
+// assertion's way by reading sentinels, which minification preserves.
+async function compile(isProd) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'omega-extension-strip-'));
+  fs.writeFileSync(path.join(dir, 'entry.js'), FIXTURE);
+  const outfile = path.join(dir, 'dist', 'entry.bundle.js');
+
+  try {
+    await bundle({
+      frameworkRoot: FRAMEWORK_ROOT,
+      entries: [path.join(dir, 'entry.js')],
+      outfile,
+      platform: 'browser',
+      format: 'iife',
+      dev: !isProd,
+    });
+    return fs.readFileSync(outfile, 'utf8');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+function restoreEnv(key, value) {
+  if (value === undefined) {
+    delete process.env[key];
+  } else {
+    process.env[key] = value;
+  }
+}
+
+module.exports = defineCases({
+  type: 'suite',
+  layer: 'build',
+  description: 'strip-dev-blocks — the extension bundle lane cuts @dev-only blocks from production bundles',
+  timeout: 60000,
+  tests: [
+    {
+      name: 'production bundle drops the dev-only block and keeps the real code',
+      run: async (ctx) => {
+        const built = await compile(true);
+        ctx.expect(built).toContain('PROD_SENTINEL');
+        ctx.expect(built.includes('DEV_ONLY_SENTINEL')).toBe(false);
+      },
+    },
+
+    {
+      name: 'development bundle keeps the dev-only block',
+      run: async (ctx) => {
+        const built = await compile(false);
+        ctx.expect(built).toContain('PROD_SENTINEL');
+        ctx.expect(built).toContain('DEV_ONLY_SENTINEL');
+      },
+    },
+
+    {
+      // `actLikeProduction()` is the rule, not `isBuildMode()`: an audit run
+      // (OMEGA_AUDIT_FORCE) inspects the artifact a release would ship, so it
+      // has to be built the way a release is — dev blocks cut. The old webpack
+      // loader gated on the build-mode flag alone and left them in.
+      name: 'OMEGA_AUDIT_FORCE builds like production — the dev-only block is cut there too',
+      run: async (ctx) => {
+        const previous = { build: process.env.OMEGA_BUILD_MODE, audit: process.env.OMEGA_AUDIT_FORCE };
+        delete process.env.OMEGA_BUILD_MODE;
+        process.env.OMEGA_AUDIT_FORCE = 'true';
+
+        try {
+          ctx.expect(Manager.isBuildMode()).toBe(false);
+          ctx.expect(Manager.actLikeProduction()).toBe(true);
+
+          const built = await compile(Manager.actLikeProduction());
+          ctx.expect(built).toContain('PROD_SENTINEL');
+          ctx.expect(built.includes('DEV_ONLY_SENTINEL')).toBe(false);
+        } finally {
+          restoreEnv('OMEGA_BUILD_MODE', previous.build);
+          restoreEnv('OMEGA_AUDIT_FORCE', previous.audit);
+        }
+      },
+    },
+
+    {
+      // The strip existing is not the bug #18 reports — the bug was a bundle
+      // WITHOUT it. Pin the wiring itself: the task derives the production rule
+      // from the same helper the rest of the build gates on, which is what
+      // registers the strip inside the wrapper.
+      name: 'the one bundle call takes the production rule',
+      run: (ctx) => {
+        const task = fs.readFileSync(path.join(FRAMEWORK_ROOT, 'src', 'gulp', 'tasks', 'bundle.js'), 'utf8');
+        ctx.expect(task).toContain('dev: !Manager.actLikeProduction()');
+      },
+    },
+  ],
+});

package/dist/test/suites/build/template-replace.test.js

@@ -0,0 +1,116 @@
+// The `%%%key%%%` substitution, extension bundle lane
+// ([#738](https://github.com/Omega-JS-Stack/omega/issues/738)).
+//
+// Consumer and framework browser code writes build-time tokens (`%%%version%%%`,
+// `%%%brand.name%%%`) and the build fills them with the project's own facts.
+// webpack did it as a processAssets hook that
+// rewrote every emitted asset; esbuild has no mutate-then-rewrite pass, so the
+// bundle task fills the emitted files itself. What that has to survive is
+// MINIFICATION — a production bundle is minified before anything sees it, and a
+// token that came out mangled would be an unreplaced marker shipped to a store.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const FRAMEWORK_ROOT = path.join(__dirname, '..', '..', '..', '..');
+const { bundle } = require('../../../vendor/devkit/bundle.js');
+const task = require(path.join(FRAMEWORK_ROOT, 'src', 'gulp', 'tasks', 'bundle.js'));
+const defineCases = require('../../../vendor/devkit/test/define-cases.js');
+
+const FIXTURE = [
+  "export const stamp = 'v%%%version%%% of %%%brand.name%%%';",
+  "export const spaced = '%%% environment %%%';",
+  'globalThis.probe = { stamp, spaced };',
+  '',
+].join('\n');
+
+// Bundle the fixture the way the extension lane bundles a component entry — a
+// PRODUCTION build, so the tokens go through esbuild's minifier before the
+// substitution runs.
+async function buildFixture() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'omega-extension-template-'));
+  fs.writeFileSync(path.join(dir, 'entry.js'), FIXTURE);
+  const outfile = path.join(dir, 'dist', 'entry.bundle.js');
+
+  await bundle({
+    frameworkRoot: FRAMEWORK_ROOT,
+    entries: [path.join(dir, 'entry.js')],
+    outfile,
+    platform: 'browser',
+    format: 'iife',
+    dev: false,
+  });
+
+  return { dir, outfile };
+}
+
+module.exports = defineCases({
+  type: 'suite',
+  layer: 'build',
+  description: 'template-replace — the bundle lane fills %%%key%%% tokens in the emitted bundles',
+  timeout: 60000,
+  tests: [
+    {
+      name: 'tokens survive minification and are filled with the project facts',
+      run: async (ctx) => {
+        const { dir, outfile } = await buildFixture();
+
+        try {
+          ctx.expect(fs.readFileSync(outfile, 'utf8')).toContain('%%%version%%%');
+
+          task.substituteTemplates([outfile], {
+            version: '9.9.9',
+            brand: { name: 'Fixture Brand' },
+            environment: 'production',
+          });
+
+          const after = fs.readFileSync(outfile, 'utf8');
+          ctx.expect(after).toContain('v9.9.9 of Fixture Brand');
+          ctx.expect(after).toContain('production');
+          ctx.expect(after.includes('%%%')).toBe(false);
+        } finally {
+          fs.rmSync(dir, { recursive: true, force: true });
+        }
+      },
+    },
+
+    {
+      name: 'a token nothing answers is left intact rather than emptied',
+      run: async (ctx) => {
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'omega-extension-template-miss-'));
+        const file = path.join(dir, 'entry.bundle.js');
+        fs.writeFileSync(file, "var a = '%%%version%%%';\nvar b = '%%%nothingAnswersThis%%%';\n");
+
+        try {
+          task.substituteTemplates([file], { version: '1.0.0' });
+
+          const after = fs.readFileSync(file, 'utf8');
+          ctx.expect(after).toContain("var a = '1.0.0';");
+          ctx.expect(after).toContain('%%%nothingAnswersThis%%%');
+        } finally {
+          fs.rmSync(dir, { recursive: true, force: true });
+        }
+      },
+    },
+
+    {
+      // The keys the build promises consumer code (packages/extension/docs/build-system.md):
+      // the substitution being wired proves nothing if the set it fills from lost
+      // a key. `webManagerConfiguration` was in this set and is gone (#743): it
+      // composed a SECOND, diverging copy of the @omega.js/client runtime blob
+      // for a token no source file anywhere carried — the snapshot the contexts
+      // actually read is the one bundle.js bakes.
+      name: 'the replacement set carries the keys the build promises',
+      run: (ctx) => {
+        const options = task.getTemplateReplaceOptions();
+
+        ctx.expect(options).toHaveProperty('environment');
+        ctx.expect(options).toHaveProperty('version');
+        ctx.expect(typeof options.liveReloadPort).toBe('number');
+        ctx.expect(typeof options.firebaseVersion).toBe('string');
+        ctx.expect(options.webManagerConfiguration).toBeUndefined();
+      },
+    },
+  ],
+});

package/dist/test/suites/build/test-discovery.test.js

@@ -0,0 +1,64 @@
+// Build-layer tests for test-suite discovery — specifically the
+// "underscore = not a suite" convention: `_`-prefixed files and everything
+// under `_`-prefixed directories (at ANY depth) must be excluded, so consumers
+// can keep helpers and fixture trees (e.g. test/_helpers/harness.js)
+// next to their suites.
+
+const path = require('path');
+const defineCases = require('../../../vendor/devkit/test/define-cases.js');
+
+module.exports = defineCases({
+  type: 'suite',
+  layer: 'build',
+  description: 'test discovery — underscore exclusion convention',
+  tests: [
+    {
+      name: 'runner exports DISCOVERY_IGNORE',
+      run: (ctx) => {
+        const runner = require(path.join(__dirname, '..', '..', 'runner.js'));
+        ctx.expect(Array.isArray(runner.DISCOVERY_IGNORE)).toBe(true);
+        ctx.expect(runner.DISCOVERY_IGNORE.length >= 2).toBe(true);
+      },
+    },
+    {
+      name: 'glob with DISCOVERY_IGNORE skips _ files and _ dirs at any depth',
+      run: (ctx) => {
+        const fs = require('fs');
+        const os = require('os');
+        const glob = require('glob').globSync;
+        const { DISCOVERY_IGNORE } = require(path.join(__dirname, '..', '..', 'runner.js'));
+
+        const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'extension-discovery-test-'));
+        const write = (rel) => {
+          const file = path.join(tmp, rel);
+          fs.mkdirSync(path.dirname(file), { recursive: true });
+          fs.writeFileSync(file, 'module.exports = {};\n');
+        };
+
+        // Should be DISCOVERED:
+        write('build/config.test.js');
+        write('page/runner.test.js');
+        write('boot/nested/deep.test.js');
+
+        // Should be EXCLUDED:
+        write('_init.js');                                  // top-level _ file
+        write('page/_helper.js');                           // nested _ file
+        write('_helpers/harness.js');                       // file in top-level _ dir
+        write('_fixtures/packages/runner/mod/index.js');    // deep inside a _ dir
+        write('boot/_private/util.js');                     // _ dir below a layer dir
+
+        const found = glob('**/*.js', { cwd: tmp, ignore: [...DISCOVERY_IGNORE] }).sort();
+
+        try {
+          ctx.expect(found).toEqual([
+            'boot/nested/deep.test.js',
+            'build/config.test.js',
+            'page/runner.test.js',
+          ]);
+        } finally {
+          fs.rmSync(tmp, { recursive: true, force: true });
+        }
+      },
+    },
+  ],
+});

package/dist/test/suites/build/test-target-no-match.test.js

@@ -0,0 +1,119 @@
+// Build-layer tests for the no-match rule ([#814](https://github.com/Omega-JS-Stack/omega/issues/814)).
+//
+// `npx omega test view/popup-nope` with no such file printed "No test files
+// found.", "0 passing", and exited 0: a typo'd path target, or a suite renamed
+// out from under one, ran silently green.
+//
+// The rule lives in the runner's selection step, so these drive the REAL
+// extension runner from a consumer directory with no tests of its own.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const defineCases = require('../../../vendor/devkit/test/define-cases.js');
+
+const RUNNER = path.join(__dirname, '..', '..', 'runner.js');
+
+// A consumer directory with a package.json and no test/ dir at all.
+function makeEmptyConsumer() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'extension-no-match-'));
+  fs.writeFileSync(path.join(dir, 'package.json'), JSON.stringify({ name: 'no-match-fixture' }));
+  return dir;
+}
+
+// Run the real runner from `dir`, with its report silenced: the probe reports
+// like any run, and its report is not THIS run's.
+async function runFrom(dir, options) {
+  const { run } = require(RUNNER);
+  const previousCwd = process.cwd();
+  const realLog = console.log;
+
+  process.chdir(dir);
+  console.log = () => {};
+
+  try {
+    return await run(options);
+  } finally {
+    console.log = realLog;
+    process.chdir(previousCwd);
+  }
+}
+
+module.exports = defineCases({
+  type: 'suite',
+  layer: 'build',
+  description: 'test targets that match nothing',
+  tests: [
+    {
+      name: 'a named target that selects no file comes back flagged, not green',
+      run: async (ctx) => {
+        const dir = makeEmptyConsumer();
+
+        try {
+          // Every spelling of a path target: bare, framework-scoped, project-scoped.
+          for (const target of ['view/does-not-exist', 'extension:build/does-not-exist', 'project:does-not-exist']) {
+            const result = await runFrom(dir, { target });
+            ctx.expect(result.noMatch).toBe(target);
+            ctx.expect(result.passed).toBe(0);
+            ctx.expect(result.failed).toBe(0);
+          }
+        } finally {
+          fs.rmSync(dir, { recursive: true, force: true });
+        }
+      },
+    },
+    {
+      name: 'a run that named no file stays green with nothing to run',
+      run: async (ctx) => {
+        const dir = makeEmptyConsumer();
+
+        try {
+          // A bare run, and a bare source prefix, ask for a source rather than
+          // a file: an empty project is still an exit-0 run.
+          for (const options of [{}, { target: 'project:' }]) {
+            const result = await runFrom(dir, options);
+            ctx.expect(result.noMatch).toBe(null);
+            ctx.expect(result.passed).toBe(0);
+          }
+        } finally {
+          fs.rmSync(dir, { recursive: true, force: true });
+        }
+      },
+    },
+    {
+      name: 'a target naming a real framework suite still selects it',
+      run: async (ctx) => {
+        const dir = makeEmptyConsumer();
+
+        try {
+          const result = await runFrom(dir, { target: 'extension:build/test-discovery' });
+          ctx.expect(result.noMatch).toBe(null);
+          ctx.expect(result.passed > 0).toBe(true);
+        } finally {
+          fs.rmSync(dir, { recursive: true, force: true });
+        }
+      },
+    },
+    {
+      name: 'in a brand-root fan-out the same miss answers with its own exit code',
+      run: (ctx) => {
+        // The brand root forwards ONE target to every target, so a target that
+        // does not carry it is a no-op there, not a failure. The code is the
+        // whole difference, and this package ships its own copy of the rule.
+        const { noMatchExitCode, NO_MATCH_EXIT_CODE, FANOUT_ENV } = require('../../../vendor/devkit/test/scope.js');
+
+        ctx.expect(FANOUT_ENV).toBe('OMEGA_TEST_FANOUT');
+        ctx.expect(NO_MATCH_EXIT_CODE).toBe(3);
+        ctx.expect(noMatchExitCode({})).toBe(1);
+        ctx.expect(noMatchExitCode({ OMEGA_TEST_FANOUT: '1' })).toBe(3);
+      },
+    },
+    {
+      name: 'the line the CLI prints names the target',
+      run: (ctx) => {
+        const { noMatchMessage } = require('../../../vendor/devkit/test/scope.js');
+        ctx.expect(noMatchMessage('view/does-not-exist')).toBe('No test file matches "view/does-not-exist".');
+      },
+    },
+  ],
+});