@astryxdesign/cli 0.7.2-canary.fc12a18 → 0.7.2-canary.fdd384f

package/clients/cli/commands/build-theme.path-safety.test.mjs

@@ -9,6 +9,12 @@
  *   - Multi-file write is atomic: if one file fails, none are left behind.
  *   - An `--out` escape, or an output directory that cannot be created, fails
  *     with a registered error code.
+ *   - Every output a build writes stays inside the working directory: an
+ *     absolute `--out` path or a theme file outside it fails before anything
+ *     is written, while absolute paths inside it build, also through a
+ *     symlinked spelling. `--check` writes nothing, so it compares those
+ *     outside outputs read-only, and a stale report for them ends with a
+ *     remedy that works: the directory to build and check from.
  *
  * Runs the CLI in-process (shared runCli harness) against a tiny synthetic theme file.
  */
@@ -22,6 +28,7 @@ import {runCli} from '../../../test-utils/run-cli.mjs';
 import {themeBuild} from '../../../api/theme/build/build.mjs';
 import {AstryxError} from '../../../api/error.mjs';
 import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
+import {getCliInvocation} from '../../../foundation/env/package-manager.mjs';
 
 function writeTheme(dir, name) {
   fs.mkdirSync(dir, {recursive: true});
@@ -59,7 +66,9 @@ describe('theme build path safety', () => {
     );
 
     expect(result.code).not.toBe(0);
-    expect(result.stderr + result.stdout).toMatch(/path separator|invalid theme name/i);
+    expect(result.stderr + result.stdout).toMatch(
+      /path separator|invalid theme name/i,
+    );
 
     // The traversal target must not exist.
     expect(fs.existsSync(path.join(tmpDir, 'escaped.js'))).toBe(false);
@@ -92,7 +101,10 @@ describe('theme build path safety', () => {
 
     const themeFile = writeTheme(themesDir, '../leak');
 
-    await runCli(['theme', 'build', path.relative(project, themeFile)], project);
+    await runCli(
+      ['theme', 'build', path.relative(project, themeFile)],
+      project,
+    );
 
     // Neither the CSS nor any sibling JS should have been written.
     const entries = fs.readdirSync(themesDir).sort();
@@ -114,19 +126,200 @@ describe('theme build output-path failures carry registered codes', () => {
     return {result, envelope: JSON.parse(result.stdout)};
   }
 
-  it('reports an --out path outside the project as ERR_PATH_TRAVERSAL', async () => {
+  it('reports a relative --out path outside the project as ERR_PATH_TRAVERSAL, with --check too', async () => {
     const project = path.join(tmpDir, 'project');
     const themeFile = writeTheme(path.join(project, 'themes'), 'ocean');
 
+    for (const extra of [[], ['--check']]) {
+      const {result, envelope} = await buildJson(
+        [
+          path.relative(project, themeFile),
+          '--out',
+          '../escaped.css',
+          ...extra,
+        ],
+        project,
+      );
+
+      expect(result.code).toBe(1);
+      expect(envelope.code).toBe(ERROR_CODES.ERR_PATH_TRAVERSAL);
+      expect(registered.has(envelope.code)).toBe(true);
+    }
+    expect(fs.existsSync(path.join(tmpDir, 'escaped.css'))).toBe(false);
+  });
+
+  it('reports an absolute --out path outside the project as ERR_PATH_TRAVERSAL', async () => {
+    const project = path.join(tmpDir, 'project');
+    const outside = path.join(tmpDir, 'outside');
+    fs.mkdirSync(outside, {recursive: true});
+    const themeFile = writeTheme(path.join(project, 'themes'), 'ocean');
+    const out = path.join(outside, 'ocean.css');
+
     const {result, envelope} = await buildJson(
-      [path.relative(project, themeFile), '--out', '../escaped.css'],
+      [path.relative(project, themeFile), '--out', out],
       project,
     );
 
     expect(result.code).toBe(1);
     expect(envelope.code).toBe(ERROR_CODES.ERR_PATH_TRAVERSAL);
-    expect(registered.has(envelope.code)).toBe(true);
-    expect(fs.existsSync(path.join(tmpDir, 'escaped.css'))).toBe(false);
+    expect(fs.readdirSync(outside)).toEqual([]);
+  });
+
+  it('checks an absolute --out path outside the project read-only', async () => {
+    const project = path.join(tmpDir, 'project');
+    const outside = path.join(tmpDir, 'outside');
+    fs.mkdirSync(outside, {recursive: true});
+    const themeFile = path.relative(
+      project,
+      writeTheme(path.join(project, 'themes'), 'ocean'),
+    );
+    const out = path.join(outside, 'ocean.css');
+
+    const missing = await buildJson(
+      [themeFile, '--out', out, '--check'],
+      project,
+    );
+    expect(missing.result.code).toBe(1);
+    expect(missing.envelope.type).toBe('theme.build.check');
+    expect(missing.envelope.data.upToDate).toBe(false);
+    expect(fs.readdirSync(outside)).toEqual([]);
+
+    // Outputs built inside the project compare equal once copied outside:
+    // only the volatile Command line, which --check ignores, names --out.
+    const dist = path.join(project, 'dist');
+    const built = await buildJson(
+      [themeFile, '--out', path.join(dist, 'ocean.css')],
+      project,
+    );
+    expect(built.result.code).toBe(0);
+    for (const file of fs.readdirSync(dist)) {
+      fs.copyFileSync(path.join(dist, file), path.join(outside, file));
+    }
+    const copied = fs.readdirSync(outside).sort();
+
+    const current = await buildJson(
+      [themeFile, '--out', out, '--check'],
+      project,
+    );
+    expect(current.result.code).toBe(0);
+    expect(current.envelope.type).toBe('theme.build.check');
+    expect(current.envelope.data.upToDate).toBe(true);
+    expect(fs.readdirSync(outside).sort()).toEqual(copied);
+  });
+
+  it('reports a theme file outside the project as ERR_PATH_TRAVERSAL, because its outputs go beside it; --check only compares them', async () => {
+    const project = path.join(tmpDir, 'project');
+    fs.mkdirSync(project, {recursive: true});
+    const shared = path.join(tmpDir, 'shared');
+    const themeFile = writeTheme(shared, 'ocean');
+
+    for (const file of [themeFile, path.relative(project, themeFile)]) {
+      const {result, envelope} = await buildJson([file], project);
+
+      expect(result.code).toBe(1);
+      expect(envelope.code).toBe(ERROR_CODES.ERR_PATH_TRAVERSAL);
+
+      const checked = await buildJson([file, '--check'], project);
+      expect(checked.result.code).toBe(1);
+      expect(checked.envelope.type).toBe('theme.build.check');
+      expect(checked.envelope.data.upToDate).toBe(false);
+    }
+    expect(fs.readdirSync(shared)).toEqual(['theme.mjs']);
+  });
+
+  /**
+   * Read the remedy that ends a stale report for outputs outside cwd: the
+   * directory to run from, then the build and check arguments after `theme
+   * build`. Each command starts with the install-aware invocation for it.
+   * @param {string} stderr
+   */
+  function readRemedy(stderr) {
+    const lines = stderr.split('\n').map(line => line.trim());
+    const cd = lines.find(line => line.startsWith('cd '));
+    expect(cd).toBeDefined();
+    const dir = /** @type {string} */ (cd).slice('cd '.length);
+    const stem = `${getCliInvocation(dir)} theme build `;
+    const commands = lines.filter(line => line.startsWith(stem));
+    expect(commands).toHaveLength(2);
+    const [build, check] = commands.map(line =>
+      line.slice(stem.length).split(' '),
+    );
+    expect(check).toEqual([...build, '--check']);
+    return {dir, build, check};
+  }
+
+  it('ends a stale report for outputs outside cwd with a remedy that works, and keeps the report for outputs inside it', async () => {
+    const project = path.join(tmpDir, 'project');
+    const inside = path.relative(
+      project,
+      writeTheme(path.join(project, 'themes'), 'ocean'),
+    );
+    const shared = writeTheme(path.join(tmpDir, 'shared'), 'ocean');
+    const outside = path.join(tmpDir, 'outside');
+
+    for (const args of [
+      [path.relative(project, shared)],
+      [inside, '--out', path.join(outside, 'ocean.css')],
+    ]) {
+      const stale = await runCli(
+        ['theme', 'build', ...args, '--check'],
+        project,
+      );
+      expect(stale.code).toBe(1);
+      // The old remedy ran the build from cwd, which refuses these outputs.
+      expect(stale.stderr).not.toContain('Rebuild with:');
+      expect(stale.stderr).not.toContain(`theme build ${args.join(' ')}`);
+
+      // Following the remedy builds, and the check from there passes.
+      const remedy = readRemedy(stale.stderr);
+      const built = await runCli(
+        ['theme', 'build', ...remedy.build],
+        remedy.dir,
+      );
+      expect(built.code).toBe(0);
+      const checked = await runCli(
+        ['--json', 'theme', 'build', ...remedy.check],
+        remedy.dir,
+      );
+      expect(checked.code).toBe(0);
+      expect(JSON.parse(checked.stdout).data.upToDate).toBe(true);
+    }
+
+    // Outputs inside cwd keep the plain rebuild line.
+    const local = await runCli(['theme', 'build', inside, '--check'], project);
+    expect(local.code).toBe(1);
+    expect(local.stderr).toContain(
+      `Rebuild with: astryx theme build ${inside}`,
+    );
+    expect(local.stderr).not.toMatch(/^\s*cd /m);
+  });
+
+  it('builds absolute paths inside the project, also when they reach it through a symlink', async () => {
+    const project = path.join(tmpDir, 'project');
+    const themeFile = writeTheme(path.join(project, 'themes'), 'ocean');
+    const alias = path.join(tmpDir, 'alias');
+    fs.symlinkSync(project, alias, 'dir');
+
+    for (const [args, written] of [
+      [
+        [themeFile, '--out', path.join(project, 'dist', 'direct.css')],
+        path.join(project, 'dist', 'direct.css'),
+      ],
+      [
+        [themeFile, '--out', path.join(alias, 'dist', 'aliased.css')],
+        path.join(project, 'dist', 'aliased.css'),
+      ],
+      [
+        [path.join(alias, 'themes', 'theme.mjs')],
+        path.join(project, 'themes', 'ocean.css'),
+      ],
+    ]) {
+      const {result, envelope} = await buildJson(args, project);
+
+      expect(result.code).toBe(0);
+      expect(envelope.type).toBe('theme.build');
+      expect(fs.existsSync(written)).toBe(true);
+    }
   });
 
   it('reports an --out path that escapes through a symlink as ERR_PATH_TRAVERSAL', async () => {
@@ -177,4 +370,29 @@ describe('theme build output-path failures carry registered codes', () => {
       code: ERROR_CODES.ERR_PATH_TRAVERSAL,
     });
   });
+
+  it('themeBuild() rejects an output outside cwd, an absolute out path or the default beside a theme file outside cwd, and checks it read-only', async () => {
+    const project = path.join(tmpDir, 'project');
+    const inside = writeTheme(path.join(project, 'themes'), 'ocean');
+    const shared = path.join(tmpDir, 'shared');
+    const outsideTheme = writeTheme(shared, 'ocean');
+    const outDir = path.join(tmpDir, 'out');
+
+    for (const [file, options] of [
+      [path.relative(project, inside), {out: path.join(outDir, 'ocean.css')}],
+      [outsideTheme, {}],
+    ]) {
+      await expect(
+        themeBuild(file, options, {cwd: project}),
+      ).rejects.toMatchObject({code: ERROR_CODES.ERR_PATH_TRAVERSAL});
+      await expect(
+        themeBuild(file, {...options, check: true}, {cwd: project}),
+      ).resolves.toMatchObject({
+        type: 'theme.build.check',
+        data: {upToDate: false},
+      });
+    }
+    expect(fs.existsSync(outDir)).toBe(false);
+    expect(fs.readdirSync(shared)).toEqual(['theme.mjs']);
+  });
 });

package/clients/cli/commands/build-theme.registry.test.mjs

@@ -126,7 +126,10 @@ describe('theme build emits a live TextInput selector (#4109)', () => {
         `};\n`,
     );
 
-    const result = await runCli(['theme', 'build', themeFile, '-o', outFile]);
+    const result = await runCli(
+      ['theme', 'build', themeFile, '-o', outFile],
+      tmpDir,
+    );
     const css = fs.readFileSync(outFile, 'utf8');
 
     expect(result.status).toBe(0);
@@ -148,7 +151,7 @@ describe('theme build emits a live TextInput selector (#4109)', () => {
         `};\n`,
     );
 
-    await runCli(['theme', 'build', themeFile, '-o', outFile]);
+    await runCli(['theme', 'build', themeFile, '-o', outFile], tmpDir);
     const css = fs.readFileSync(outFile, 'utf8');
 
     expect(css).toContain('.astryx-text-input');

package/clients/cli/commands/doctor-integration-components.doc.mjs

@@ -8,7 +8,8 @@ export const doc = {
   name: 'doctor integration components',
   displayName: 'astryx doctor integration components',
   namespace: 'cli/commands',
-  summary: 'Check integration component names and replacements against Core',
+  summary:
+    'Check integration component names, replacements, and documented props',
   description:
     'Compares one local or installed integration with Core component names. A ' +
     'conflict is allowed and exits successfully, but the report recommends ' +
@@ -17,7 +18,14 @@ export const doc = {
     'range that turns replacement on, a missing Core target, an invalid value, a ' +
     'component named after a different Core component, or two replacements for one ' +
     'Core component is an error. In a package without that range they are warnings, ' +
-    'with a warning for each such component, naming the range to declare.',
+    'with a warning for each such component, naming the range to declare. ' +
+    "Then it compares each component doc's props with the component's TypeScript " +
+    "props, using the project's own `typescript`, and warns about a documented prop " +
+    'the code lacks, a prop the package declares that the doc omits, a wrong ' +
+    '`required`, and a type that does not match where both sides read exactly ' +
+    '(it lists every other documented type as not compared, with the reason). ' +
+    'Without TypeScript it prints one ' +
+    'line saying the comparison was skipped.',
   fn: 'integrationComponentConflicts',
   args: [
     {
@@ -29,7 +37,10 @@ export const doc = {
     },
   ],
   examples: [
-    {label: 'Check the local integration', cli: 'astryx doctor integration components'},
+    {
+      label: 'Check the local integration',
+      cli: 'astryx doctor integration components',
+    },
     {
       label: 'Check an installed integration',
       cli: 'astryx doctor integration components @acme/widgets --json',
@@ -38,7 +49,7 @@ export const doc = {
   exitCodes: [
     {
       code: 0,
-      when: 'the check completed; component name conflicts, and replaces findings for a package without the CLI range, are warnings',
+      when: 'the check completed; component name conflicts, replaces findings for a package without the CLI range, and props that differ from the code are warnings',
     },
     {
       code: 1,

package/clients/cli/commands/doctor-integration-validate.doc.mjs

@@ -14,7 +14,13 @@ export const doc = {
   description:
     'Validates one integration at a time: the local package rooted at cwd, or an ' +
     'installed package resolved by name. It schema-checks the manifest, verifies ' +
-    'every declared contribution root, and reports every finding. Safe as a CI gate.',
+    'every declared contribution root, and reports every finding. Safe as a CI gate. ' +
+    'It then checks every doc the package ships under its roots against the ' +
+    "published authoring type for its kind, with the project's own `typescript`, and " +
+    'warns about each field that does not match, naming the field and a fix. A doc ' +
+    'it cannot fully check is listed with the reason, and test fixtures under ' +
+    '`__tests__` in the components or docs root are counted, not checked. Without ' +
+    'TypeScript it prints one line saying the docs were not type-checked.',
   fn: 'validateIntegration',
   args: [
     {
@@ -36,7 +42,10 @@ export const doc = {
     },
   ],
   exitCodes: [
-    {code: 0, when: 'no error-severity issues (warnings are allowed)'},
+    {
+      code: 0,
+      when: 'no error-severity issues (warnings, including doc type findings, are allowed)',
+    },
     {code: 1, when: 'one or more error-severity issues'},
   ],
   related: ['doctor integration templates', 'template'],