@astryxdesign/cli 0.6.5-canary.1bbbf63 → 0.6.5-canary.1d8fca6

package/api/gap-report/gap-report.d.mts

@@ -4,7 +4,9 @@
 /**
  * Collect the effective handler set in delivery order: project config first,
  * then integrations in config order. Valid handlers dedupe by handle identity;
- * malformed integration exports retain their position as failed deliveries.
+ * malformed integration exports and integrations that failed to load retain
+ * their position as failed deliveries. An unloadable integration may export a
+ * handler, so it never counts as an empty set that enables the fallback.
  *
  * @param {Project} project
  * @returns {HandlerEntry[]}

package/api/gap-report/gap-report.mjs

@@ -189,7 +189,9 @@ async function selectTarget(project, component, packageName) {
 /**
  * Collect the effective handler set in delivery order: project config first,
  * then integrations in config order. Valid handlers dedupe by handle identity;
- * malformed integration exports retain their position as failed deliveries.
+ * malformed integration exports and integrations that failed to load retain
+ * their position as failed deliveries. An unloadable integration may export a
+ * handler, so it never counts as an empty set that enables the fallback.
  *
  * @param {Project} project
  * @returns {HandlerEntry[]}
@@ -214,7 +216,15 @@ export function collectGapReportHandlers(project) {
   }
 
   for (const integration of project.loadedIntegrations) {
-    if (integration.__loadError) continue;
+    if (integration.__loadError) {
+      entries.push({
+        kind: 'malformed',
+        handlerType: 'integration',
+        handlerName: integration.name,
+        error: `Integration failed to load, so it could not receive this report: ${integration.__loadError}. Fix the package or remove it from integrations in astryx.config, then rerun.`,
+      });
+      continue;
+    }
     if (integration.__gapReportError) {
       entries.push({
         kind: 'malformed',

package/api/gap-report/gap-report.test.mjs

@@ -105,6 +105,45 @@ function addIntegration({
   return {dir};
 }
 
+/**
+ * Add an integration whose module throws on import, so it never loads.
+ * @param {string} name
+ */
+function addBrokenIntegration(name) {
+  const dir = packageDir(name);
+  fs.mkdirSync(dir, {recursive: true});
+  fs.writeFileSync(
+    path.join(dir, 'package.json'),
+    JSON.stringify({name, version: '1.0.0', type: 'module'}),
+  );
+  fs.writeFileSync(
+    path.join(dir, 'astryx.integration.mjs'),
+    "throw new Error('intentional integration load failure');\n",
+  );
+}
+
+/**
+ * Put a fake `gh` first on PATH that records its arguments if it is called.
+ * @returns {string} the file the fake writes when invoked
+ */
+function stubGh() {
+  const binDir = path.join(projectDir, 'bin');
+  const argsFile = path.join(projectDir, 'gh-args.json');
+  fs.mkdirSync(binDir, {recursive: true});
+  fs.writeFileSync(
+    path.join(binDir, 'gh'),
+    `#!/usr/bin/env node
+import fs from 'node:fs';
+fs.writeFileSync(${JSON.stringify(argsFile)}, JSON.stringify(process.argv.slice(2)));
+console.log('https://github.com/acme/core/issues/42');
+`,
+    {mode: 0o755},
+  );
+  fs.chmodSync(path.join(binDir, 'gh'), 0o755);
+  vi.stubEnv('PATH', `${binDir}${path.delimiter}${process.env.PATH ?? ''}`);
+  return argsFile;
+}
+
 const reportOptions = {
   category: 'missing_variant',
   reason: 'Need a compact size',
@@ -681,6 +720,73 @@ describe('gapReport handler isolation', () => {
     });
   });
 
+  it('an integration that fails to load is a failed delivery, not a missing handler', async () => {
+    addBrokenIntegration('@test/broken');
+    configure(['@test/broken'], {
+      issuesUrl: 'https://github.com/acme/core/issues/new',
+    });
+
+    const result = await gapReport('General', {
+      ...reportOptions,
+      cwd: projectDir,
+    });
+
+    expect(result.data.status).toBe('failed');
+    expect(result.data.deliveries).toEqual([
+      {
+        handlerType: 'integration',
+        handler: '@test/broken',
+        audience: null,
+        status: 'failed',
+        url: null,
+        message: expect.stringContaining(
+          'intentional integration load failure',
+        ),
+      },
+    ]);
+  });
+
+  it('an integration that fails to load keeps the public fallback off, even with consent', async () => {
+    addBrokenIntegration('@test/broken');
+    configure(['@test/broken'], {
+      issuesUrl: 'https://github.com/acme/core/issues/new',
+    });
+    const argsFile = stubGh();
+
+    const result = await gapReport('General', {
+      ...reportOptions,
+      confirmPublic: true,
+      cwd: projectDir,
+    });
+
+    expect(result.data.status).toBe('failed');
+    expect(result.data.deliveries.map(d => d.handlerType)).toEqual([
+      'integration',
+    ]);
+    expect(fs.existsSync(argsFile)).toBe(false);
+  });
+
+  it('an integration that fails to load keeps its place beside working handlers', async () => {
+    addBrokenIntegration('@test/broken');
+    addIntegration({
+      name: '@test/valid',
+      audience: 'internal',
+      handleBody: "return {status: 'filed', message: 'ok'};",
+    });
+    configure(['@test/broken', '@test/valid']);
+
+    const result = await gapReport('General', {
+      ...reportOptions,
+      cwd: projectDir,
+    });
+
+    expect(result.data.status).toBe('partial');
+    expect(result.data.deliveries.map(d => [d.handler, d.status])).toEqual([
+      ['@test/broken', 'failed'],
+      ['@test/valid', 'filed'],
+    ]);
+  });
+
   it('invalid handler receipt is recorded as failed delivery', async () => {
     addIntegration({
       name: '@test/bad-receipt',

package/assets/docs/tree/debug-and-gap-reports.doc.mjs

@@ -174,7 +174,7 @@ message:     Rerun with --confirm-public to file this report.`,
         },
         {
           type: 'prose',
-          text: 'One handler anywhere in the app, from the app or from any package, turns the fallback off for every report. See {@link command:gap-report}.',
+          text: 'One handler anywhere in the app, from the app or from any package, turns the fallback off for every report. So does a listed package that fails to load: the CLI cannot tell whether it has a handler, so the report fails for that package instead of going to another tracker. See {@link command:gap-report}.',
         },
       ],
     },

package/clients/cli/commands/gap-report.mjs

@@ -55,6 +55,18 @@ export function registerGapReport(program) {
         result.type === 'gap-report.file' &&
         (result.data.status === 'failed' || result.data.status === 'partial');
 
+      // stderr in both modes, so a caller that reads only the exit code or the
+      // JSON envelope still sees which delivery failed and why.
+      if (isFailure && result.type === 'gap-report.file') {
+        for (const delivery of result.data.deliveries) {
+          if (delivery.status === 'failed') {
+            console.error(
+              `gap-report: delivery to ${delivery.handler} failed: ${delivery.message ?? 'no message'}`,
+            );
+          }
+        }
+      }
+
       if (program.opts().json) {
         jsonOut(result);
         if (isFailure) process.exitCode = 1;

package/clients/cli/commands/gap-report.test.mjs

@@ -172,6 +172,69 @@ export default {};\n`,
     }
   });
 
+  it('exits nonzero and names the integration on stderr when one fails to load', async () => {
+    const cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-gap-broken-'));
+    try {
+      fs.writeFileSync(
+        path.join(cwd, 'package.json'),
+        JSON.stringify({name: 'fixture-app'}),
+      );
+      fs.writeFileSync(
+        path.join(cwd, 'astryx.config.mjs'),
+        "export default {integrations: ['@test/broken']};\n",
+      );
+      const integrationDir = path.join(cwd, 'node_modules', '@test', 'broken');
+      fs.mkdirSync(integrationDir, {recursive: true});
+      fs.writeFileSync(
+        path.join(integrationDir, 'package.json'),
+        JSON.stringify({
+          name: '@test/broken',
+          version: '1.0.0',
+          type: 'module',
+        }),
+      );
+      fs.writeFileSync(
+        path.join(integrationDir, 'astryx.integration.mjs'),
+        "throw new Error('intentional integration load failure');\n",
+      );
+
+      const cli = await runCli(
+        [
+          'gap-report',
+          'General',
+          '--category',
+          'docs_gap',
+          '--reason',
+          'Need a keyboard example',
+          '--json',
+        ],
+        {cwd},
+      );
+
+      expect(cli.status).toBe(1);
+      expect(JSON.parse(cli.stdout)).toMatchObject({
+        type: 'gap-report.file',
+        data: {
+          status: 'failed',
+          filedCount: 0,
+          deliveries: [
+            {
+              handlerType: 'integration',
+              handler: '@test/broken',
+              status: 'failed',
+            },
+          ],
+        },
+      });
+      expect(cli.stderr).toContain(
+        'gap-report: delivery to @test/broken failed:',
+      );
+      expect(cli.stderr).toContain('intentional integration load failure');
+    } finally {
+      fs.rmSync(cwd, {recursive: true, force: true});
+    }
+  });
+
   it('reports missing required fields through the JSON error contract', async () => {
     const cli = await runCli(['gap-report', 'Button', '--json']);
     expect(cli.status).toBe(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/cli",
-  "version": "0.6.5-canary.1bbbf63",
+  "version": "0.6.5-canary.1d8fca6",
   "displayName": "CLI",
   "description": "Scaffold projects, browse templates, generate themes, and get agent-ready docs from the command line.",
   "author": "Meta Open Source",
@@ -101,10 +101,10 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@astryxdesign/charts": "0.6.5-canary.1bbbf63",
-    "@astryxdesign/core": "0.6.5-canary.1bbbf63",
-    "@astryxdesign/lab": "0.6.5-canary.1bbbf63",
-    "@astryxdesign/theme-neutral": "0.6.5-canary.1bbbf63"
+    "@astryxdesign/charts": "0.6.5-canary.1d8fca6",
+    "@astryxdesign/core": "0.6.5-canary.1d8fca6",
+    "@astryxdesign/lab": "0.6.5-canary.1d8fca6",
+    "@astryxdesign/theme-neutral": "0.6.5-canary.1d8fca6"
   },
   "peerDependenciesMeta": {
     "@astryxdesign/charts": {
@@ -121,10 +121,10 @@
     }
   },
   "devDependencies": {
-    "@astryxdesign/charts": "0.6.5-canary.1bbbf63",
-    "@astryxdesign/core": "0.6.5-canary.1bbbf63",
-    "@astryxdesign/lab": "0.6.5-canary.1bbbf63",
-    "@astryxdesign/theme-neutral": "0.6.5-canary.1bbbf63",
+    "@astryxdesign/charts": "0.6.5-canary.1d8fca6",
+    "@astryxdesign/core": "0.6.5-canary.1d8fca6",
+    "@astryxdesign/lab": "0.6.5-canary.1d8fca6",
+    "@astryxdesign/theme-neutral": "0.6.5-canary.1d8fca6",
     "@heroicons/react": "^2.2.0",
     "@stylexjs/stylex": "^0.19.0",
     "@types/babel__core": "^7.20.5",