@astryxdesign/cli 0.7.2-canary.fe2c655 → 0.7.2

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

@@ -17,7 +17,18 @@
 import {Worker} from 'node:worker_threads';
 import {AstryxError} from '../error.mjs';
 import {Project} from '../../foundation/config/project.mjs';
-import {CORE_PACKAGE} from '../../foundation/discovery/component-discovery.mjs';
+import {
+  CORE_PACKAGE,
+  discoverIntegrationComponents,
+  docStem,
+  findComponentReadme,
+  findIntegrationComponent,
+  integrationRecordHold,
+  isIntegrationMember,
+  unscopedComponentOwners,
+} from '../../foundation/discovery/component-discovery.mjs';
+import {legacyExternalKeeps} from '../component/_adapter.mjs';
+import {findCoreDir} from '../../foundation/fs/paths.mjs';
 import {captureEnv} from '../../foundation/debug/event.mjs';
 import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
 import {parseGapReportReceipt} from '../../authoring/gap-report/parse.mjs';
@@ -44,6 +55,14 @@ export const GAP_REPORT_CATEGORIES = Object.freeze([
 export const PUBLIC_CONFIRMATION_MESSAGE =
   'Rerun with --confirm-public to file this report.';
 
+/** What an agent does when more than one destination exists. */
+export const ASK_DESTINATION_MESSAGE =
+  'Ask the person where to file this report, then pass their choice with --to <package>. Never pick a package destination yourself; leave --to out to use the default.';
+
+/**
+ * @typedef {import('./gap-report.type.mjs').GapReportDestination} GapReportDestination
+ */
+
 /**
  * @typedef {object} ReportTarget
  * @property {string} package
@@ -178,13 +197,65 @@ async function selectTarget(project, component, packageName) {
     coreName,
   );
   if (replacement) return targetForPackage(project, replacement.package);
+  // The owner rule runs over every owner discovery finds, loadable or not
+  // (a doc recorded under another export still answers to its file's name);
+  // then only owners whose docs load route a report.
+  const wanted = bareComponent.toLowerCase();
+  const loads = new Set(records.map(r => `${r.package}\0${r.docPath}`));
+  const recorded = project.loadedIntegrations.flatMap(integration =>
+    discoverIntegrationComponents(integration).flatMap(r =>
+      r.name.toLowerCase() === wanted
+        ? [{...r, hold: integrationRecordHold(r)}]
+        : docStem(r.docPath).toLowerCase() === wanted && !isIntegrationMember(r)
+          ? [{...r, hold: 'doc'}]
+          : [],
+    ),
+  );
+  // The checks below find files by name, so they run on every spelling the
+  // case-blind match above found, as well as the one typed.
+  const spellings = new Set([
+    bareComponent,
+    ...recorded.flatMap(r =>
+      [r.name, docStem(r.docPath)].filter(n => n.toLowerCase() === wanted),
+    ),
+  ]);
+  // Core also holds a name only its doc lookup finds, as in detail: a name a
+  // doc records yields to it, though it routes no report itself.
+  const coreDir = findCoreDir(project.cwd);
+  const coreDocs =
+    coreDir != null &&
+    [...spellings].some(name => findComponentReadme(coreDir, name) != null);
+  const ruled = unscopedComponentOwners([
+    ...records
+      .filter(
+        r => r.package === CORE_PACKAGE && r.name.toLowerCase() === wanted,
+      )
+      .map(r => ({...r, hold: 'core'})),
+    ...recorded,
+    // A hidden doc named after its file still holds that name, as the
+    // component lookup finds it; it routes no report.
+    ...project.loadedIntegrations.flatMap(integration =>
+      [...spellings].flatMap(spelling => {
+        const found = findIntegrationComponent(integration, spelling);
+        return found?.hold === 'file'
+          ? [{...found, package: integration.name}]
+          : [];
+      }),
+    ),
+  ]).filter(r => !coreDocs || r.hold !== 'doc');
+  // A legacy docs package keeps an export name a doc records, as in detail.
   const owners = [
     ...new Set(
-      records
+      ([...spellings].some(name =>
+        legacyExternalKeeps(project.cwd, name, ruled),
+      )
+        ? []
+        : ruled
+      )
         .filter(
-          record => record.name.toLowerCase() === bareComponent.toLowerCase(),
+          r => r.hold === 'core' || loads.has(`${r.package}\0${r.docPath}`),
         )
-        .map(record => record.package),
+        .map(r => r.package),
     ),
   ];
 
@@ -474,15 +545,14 @@ function githubRoute(issuesUrl) {
 }
 
 /**
- * Built-in GitHub fallback — runs only when the effective handler set is empty.
- * Requires confirmPublic.
+ * File a report on GitHub with `gh` — for the zero-handler fallback and for a
+ * destination the caller names. Requires confirmPublic.
  *
- * @param {ReportTarget} target
  * @param {{component: string, categoryLabel: string, intention: string, detail?: string, source: string, timestamp: string}} report
  * @param {{repo: string}} github
  * @returns {Promise<Pick<import('./gap-report.type.mjs').GapReportDelivery, 'status'|'url'|'message'>>}
  */
-async function runGithubFallback(target, report, github) {
+async function runGithubFallback(report, github) {
   const {execFile} = await import('node:child_process');
   const title = `[gap] ${report.component}: ${report.intention.slice(0, 70)}`;
   const body = [
@@ -544,6 +614,87 @@ async function runGithubFallback(target, report, github) {
   }
 }
 
+/**
+ * Send a report to an issues URL: a GitHub issues URL is filed with `gh` only
+ * with consent; any other URL comes back as routed_only. Serves the
+ * zero-handler fallback (spec:AST-031/FR8) and a destination named with `to`
+ * (architecture:cli-surface INV36).
+ *
+ * @param {string} issuesUrl
+ * @param {{component: string, categoryLabel: string, intention: string, detail?: string, source: string, timestamp: string}} report
+ * @param {boolean} confirmPublic
+ * @returns {Promise<import('./gap-report.type.mjs').GapReportDelivery>}
+ */
+async function deliverToIssuesUrl(issuesUrl, report, confirmPublic) {
+  const github = githubRoute(issuesUrl);
+  if (github != null && !confirmPublic) {
+    return {
+      handlerType: 'fallback',
+      handler: 'github',
+      audience: 'public',
+      status: 'consent_required',
+      url: null,
+      message: PUBLIC_CONFIRMATION_MESSAGE,
+    };
+  }
+  if (github) {
+    return {
+      handlerType: 'fallback',
+      handler: 'github',
+      audience: 'public',
+      ...(await runGithubFallback(report, github)),
+    };
+  }
+  return {
+    handlerType: 'fallback',
+    handler: 'issuesUrl',
+    audience: null,
+    status: 'routed_only',
+    url: issuesUrl,
+    message:
+      'No automatic handler is available; open the routed URL to file this report.',
+  };
+}
+
+/**
+ * Where a report can go: the default (the handlers, or with none the owning
+ * package's issues URL), then each loaded integration that names its own
+ * issues URL (architecture:cli-surface INV36).
+ *
+ * @param {Project} project
+ * @returns {GapReportDestination[]}
+ */
+function listDestinations(project) {
+  /** @type {GapReportDestination[]} */
+  const destinations = [{to: null, default: true, issuesUrl: null}];
+  for (const integration of project.loadedIntegrations) {
+    if (integration.__loadError || !integration.issuesUrl) continue;
+    if (destinations.some(destination => destination.to === integration.name))
+      continue;
+    destinations.push({
+      to: integration.name,
+      default: false,
+      issuesUrl: integration.issuesUrl,
+    });
+  }
+  return destinations;
+}
+
+/**
+ * The destinations of the project at `cwd`, or only the default when no
+ * project loads there.
+ * @param {string|undefined} cwd
+ * @returns {Promise<GapReportDestination[]>}
+ */
+async function destinationsAt(cwd) {
+  try {
+    const {resolve} = await import('node:path');
+    return listDestinations(await Project.load(resolve(cwd ?? process.cwd())));
+  } catch {
+    return [{to: null, default: true, issuesUrl: null}];
+  }
+}
+
 /**
  * Compute the aggregate status from the deliveries.
  * @param {import('./gap-report.type.mjs').GapReportDelivery[]} deliveries
@@ -602,6 +753,7 @@ export async function gapReport(component, options = {}) {
       options.detail ? '--additional-context' : null,
       options.package ? '--package' : null,
       options.confirmPublic ? '--confirm-public' : null,
+      options.to != null ? '--to' : null,
     ].filter(Boolean);
     if (ignored.length > 0) {
       throw new AstryxError(
@@ -610,9 +762,13 @@ export async function gapReport(component, options = {}) {
         ERROR_CODES.ERR_INVALID_ARGUMENT,
       );
     }
+    const destinations = await destinationsAt(options.cwd);
     return {
       type: 'gap-report.categories',
       data: GAP_REPORT_CATEGORIES.map(category => ({...category})),
+      ...(destinations.length > 1
+        ? {meta: {destinations, ask: ASK_DESTINATION_MESSAGE}}
+        : {}),
     };
   }
 
@@ -641,7 +797,33 @@ export async function gapReport(component, options = {}) {
     options.package,
   );
 
-  const entries = collectGapReportHandlers(project);
+  const destinations = listDestinations(project);
+  /** @type {GapReportDestination | undefined} */
+  let chosen;
+  // `to: null` is absent, like `package: null`; any other value is matched
+  // against the destinations as given, so an empty or unknown one lists them.
+  if (options.to != null) {
+    const to = options.to;
+    chosen = destinations.find(
+      destination => !destination.default && destination.to === to,
+    );
+    if (!chosen) {
+      const choices = destinations.filter(destination => !destination.default);
+      const named = JSON.stringify(String(to).slice(0, 214));
+      throw new AstryxError(
+        choices.length > 0
+          ? `No gap-report destination ${named}. Choose one of: ${choices.map(destination => destination.to).join(', ')}; or leave out --to for the default.`
+          : `No gap-report destination ${named}: no loaded integration names an issues URL. Leave out --to for the default.`,
+        choices.map(destination => ({
+          name: /** @type {string} */ (destination.to),
+          reason: /** @type {string} */ (destination.issuesUrl),
+        })),
+        ERROR_CODES.ERR_UNKNOWN_PACKAGE,
+      );
+    }
+  }
+
+  const entries = chosen ? [] : collectGapReportHandlers(project);
 
   const timestamp = new Date().toISOString();
   const source = captureEnv().invocationSource;
@@ -668,8 +850,24 @@ export async function gapReport(component, options = {}) {
 
   /** @type {import('./gap-report.type.mjs').GapReportDelivery[]} */
   const deliveries = [];
+  const routeReport = {
+    component: resolvedComponent,
+    categoryLabel: categoryEntry.label,
+    intention,
+    detail,
+    source,
+    timestamp,
+  };
 
-  if (entries.length > 0) {
+  if (chosen) {
+    deliveries.push(
+      await deliverToIssuesUrl(
+        /** @type {string} */ (chosen.issuesUrl),
+        routeReport,
+        options.confirmPublic === true,
+      ),
+    );
+  } else if (entries.length > 0) {
     deliveries.push(
       ...(await deliverGapReportHandlers(entries, report, {
         confirmPublic: options.confirmPublic === true,
@@ -683,47 +881,13 @@ export async function gapReport(component, options = {}) {
         ERROR_CODES.ERR_NOT_FOUND,
       );
     }
-
-    const github = githubRoute(target.issuesUrl);
-    if (github != null && options.confirmPublic !== true) {
-      deliveries.push({
-        handlerType: 'fallback',
-        handler: 'github',
-        audience: 'public',
-        status: 'consent_required',
-        url: null,
-        message: PUBLIC_CONFIRMATION_MESSAGE,
-      });
-    } else if (github) {
-      const outcome = await runGithubFallback(
-        target,
-        {
-          component: resolvedComponent,
-          categoryLabel: categoryEntry.label,
-          intention,
-          detail,
-          source,
-          timestamp,
-        },
-        github,
-      );
-      deliveries.push({
-        handlerType: 'fallback',
-        handler: 'github',
-        audience: 'public',
-        ...outcome,
-      });
-    } else {
-      deliveries.push({
-        handlerType: 'fallback',
-        handler: 'issuesUrl',
-        audience: null,
-        status: 'routed_only',
-        url: target.issuesUrl,
-        message:
-          'No automatic handler is available; open the routed URL to file this report.',
-      });
-    }
+    deliveries.push(
+      await deliverToIssuesUrl(
+        target.issuesUrl,
+        routeReport,
+        options.confirmPublic === true,
+      ),
+    );
   }
 
   const filedCount = deliveries.filter(d => d.status === 'filed').length;
@@ -737,10 +901,13 @@ export async function gapReport(component, options = {}) {
     data: {
       status,
       package: target.package,
-      issuesUrl: target.issuesUrl,
+      issuesUrl: chosen ? chosen.issuesUrl : target.issuesUrl,
       deliveries,
       filedCount,
       routedOnlyCount,
+      ...(!chosen && destinations.length > 1
+        ? {destinations, ask: ASK_DESTINATION_MESSAGE}
+        : {}),
     },
   };
 }

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

@@ -7,6 +7,7 @@ import * as path from 'node:path';
 import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
 import {Project} from '../../foundation/config/project.mjs';
 import {
+  ASK_DESTINATION_MESSAGE,
   GAP_REPORT_CATEGORIES,
   PUBLIC_CONFIRMATION_MESSAGE,
   collectGapReportHandlers,
@@ -1022,6 +1023,238 @@ console.log('https://github.com/acme/widgets/issues/42');
   });
 });
 
+describe('gapReport destinations and --to', () => {
+  /** A shared internal handler that records each call in a marker file. */
+  function addSharedHandler() {
+    const marker = path.join(projectDir, 'shared-called');
+    addIntegration({
+      name: '@test/shared',
+      audience: 'internal',
+      handleBody: `(await import('node:fs')).writeFileSync(${JSON.stringify(marker)}, 'x'); return {status: 'filed', message: 'shared'};`,
+    });
+    return marker;
+  }
+
+  function addWidgets(issuesUrl = 'https://github.com/acme/widgets/issues') {
+    addIntegration({name: '@test/widgets', handler: false, issuesUrl});
+  }
+
+  it('keeps the default route and lists the destinations with the ask line', async () => {
+    const marker = addSharedHandler();
+    addWidgets();
+    configure(['@test/shared', '@test/widgets']);
+    const argsFile = stubGh();
+
+    const result = await gapReport('General', {
+      ...reportOptions,
+      confirmPublic: true,
+      cwd: projectDir,
+    });
+
+    expect(result.data.deliveries).toEqual([
+      expect.objectContaining({handler: '@test/shared', status: 'filed'}),
+    ]);
+    expect(fs.existsSync(marker)).toBe(true);
+    expect(fs.existsSync(argsFile)).toBe(false);
+    expect(result.data.destinations).toEqual([
+      {to: null, default: true, issuesUrl: null},
+      {
+        to: '@test/widgets',
+        default: false,
+        issuesUrl: 'https://github.com/acme/widgets/issues',
+      },
+    ]);
+    expect(result.data.ask).toBe(ASK_DESTINATION_MESSAGE);
+    expect(ASK_DESTINATION_MESSAGE).toMatch(/ask the person/i);
+  });
+
+  it('lists no destinations when no integration names an issuesUrl', async () => {
+    addSharedHandler();
+    configure(['@test/shared']);
+
+    const result = await gapReport('General', {
+      ...reportOptions,
+      cwd: projectDir,
+    });
+
+    expect(result.data).not.toHaveProperty('destinations');
+    expect(result.data).not.toHaveProperty('ask');
+  });
+
+  it('files with the chosen integration GitHub issuesUrl only with consent, and runs no handler', async () => {
+    const marker = addSharedHandler();
+    addWidgets();
+    configure(['@test/shared', '@test/widgets']);
+    const argsFile = stubGh();
+
+    const pending = await gapReport('General', {
+      ...reportOptions,
+      to: '@test/widgets',
+      cwd: projectDir,
+    });
+    expect(pending.data.deliveries).toEqual([
+      {
+        handlerType: 'fallback',
+        handler: 'github',
+        audience: 'public',
+        status: 'consent_required',
+        url: null,
+        message: PUBLIC_CONFIRMATION_MESSAGE,
+      },
+    ]);
+    expect(pending.data.issuesUrl).toBe(
+      'https://github.com/acme/widgets/issues',
+    );
+    expect(pending.data).not.toHaveProperty('destinations');
+    expect(fs.existsSync(argsFile)).toBe(false);
+
+    const filed = await gapReport('General', {
+      ...reportOptions,
+      to: '@test/widgets',
+      confirmPublic: true,
+      cwd: projectDir,
+    });
+    expect(filed.data.deliveries).toHaveLength(1);
+    expect(filed.data.deliveries[0]).toMatchObject({
+      handlerType: 'fallback',
+      handler: 'github',
+      status: 'filed',
+    });
+    const args = JSON.parse(fs.readFileSync(argsFile, 'utf8'));
+    expect(args.slice(0, 4)).toEqual([
+      'issue',
+      'create',
+      '--repo',
+      'acme/widgets',
+    ]);
+    expect(fs.existsSync(marker)).toBe(false);
+  });
+
+  it('routes a chosen non-GitHub issuesUrl as routed_only', async () => {
+    addSharedHandler();
+    addWidgets('https://tracker.example/widgets');
+    configure(['@test/shared', '@test/widgets']);
+
+    const result = await gapReport('General', {
+      ...reportOptions,
+      to: '@test/widgets',
+      cwd: projectDir,
+    });
+
+    expect(result.data.deliveries).toEqual([
+      expect.objectContaining({
+        handlerType: 'fallback',
+        handler: 'issuesUrl',
+        status: 'routed_only',
+        url: 'https://tracker.example/widgets',
+      }),
+    ]);
+    expect(result.data.status).toBe('routed_only');
+  });
+
+  it.each([
+    ['a package that is not loaded', '@test/nope'],
+    ['a loaded integration without an issuesUrl', '@test/shared'],
+  ])(
+    'refuses --to naming %s, lists the choices, and sends nothing',
+    async (_label, to) => {
+      const marker = addSharedHandler();
+      addWidgets();
+      configure(['@test/shared', '@test/widgets']);
+
+      await expect(
+        gapReport('General', {...reportOptions, to, cwd: projectDir}),
+      ).rejects.toMatchObject({
+        code: 'ERR_UNKNOWN_PACKAGE',
+        suggestions: [
+          {
+            name: '@test/widgets',
+            reason: 'https://github.com/acme/widgets/issues',
+          },
+        ],
+      });
+      expect(fs.existsSync(marker)).toBe(false);
+    },
+  );
+
+  it.each([
+    ['an empty value', ''],
+    ['a blank value', '   '],
+    ['an over-long value', `@test/${'a'.repeat(300)}`],
+  ])('refuses %s for --to with the destination list', async (_label, to) => {
+    const marker = addSharedHandler();
+    addWidgets();
+    configure(['@test/shared', '@test/widgets']);
+
+    await expect(
+      gapReport('General', {...reportOptions, to, cwd: projectDir}),
+    ).rejects.toMatchObject({
+      code: 'ERR_UNKNOWN_PACKAGE',
+      suggestions: [{name: '@test/widgets'}],
+    });
+    expect(fs.existsSync(marker)).toBe(false);
+  });
+
+  it('treats to: null as absent', async () => {
+    const marker = addSharedHandler();
+    addWidgets();
+    configure(['@test/shared', '@test/widgets']);
+
+    const result = await gapReport('General', {
+      ...reportOptions,
+      to: /** @type {any} */ (null),
+      cwd: projectDir,
+    });
+
+    expect(result.data.deliveries).toHaveLength(1);
+    expect(fs.existsSync(marker)).toBe(true);
+    expect(result.data.destinations).toHaveLength(2);
+  });
+
+  it('lists the destinations with the categories', async () => {
+    addSharedHandler();
+    addWidgets();
+    configure(['@test/shared', '@test/widgets']);
+
+    const listed = await gapReport(undefined, {
+      listCategories: true,
+      cwd: projectDir,
+    });
+
+    expect(listed.data).toEqual(GAP_REPORT_CATEGORIES);
+    expect(listed.meta).toEqual({
+      destinations: [
+        {to: null, default: true, issuesUrl: null},
+        {
+          to: '@test/widgets',
+          default: false,
+          issuesUrl: 'https://github.com/acme/widgets/issues',
+        },
+      ],
+      ask: ASK_DESTINATION_MESSAGE,
+    });
+  });
+
+  it('adds no meta to the categories when there is only the default', async () => {
+    configure([]);
+    const listed = await gapReport(undefined, {
+      listCategories: true,
+      cwd: projectDir,
+    });
+    expect(listed).not.toHaveProperty('meta');
+  });
+
+  it('refuses --to with --list-categories', async () => {
+    await expect(
+      gapReport(undefined, {
+        listCategories: true,
+        to: '@test/widgets',
+        cwd: projectDir,
+      }),
+    ).rejects.toMatchObject({code: 'ERR_INVALID_ARGUMENT'});
+  });
+});
+
 describe('gapReport target selection', () => {
   it('routes to the unique component owner', async () => {
     addIntegration({

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

@@ -35,10 +35,42 @@ export type GapReportOptions = {
      * Return the category vocabulary without routing or writing.
      */
     listCategories?: boolean | undefined;
+    /**
+     * A destination the person chose: a loaded integration
+     * whose manifest names an issues URL. The report goes only there.
+     */
+    to?: string | undefined;
+};
+/**
+ * Where a report can go. The default entry (`to: null`) is the configured
+ * handlers, or with none the owning package's issues URL.
+ */
+export type GapReportDestination = {
+    /**
+     * The value to pass as `to`; null for the default.
+     */
+    to: string | null;
+    /**
+     * Whether this is the default destination.
+     */
+    default: boolean;
+    /**
+     * The integration's issues URL; null for the
+     * default.
+     */
+    issuesUrl: string | null;
 };
 export type GapReportCategoriesResponse = {
     type: "gap-report.categories";
     data: GapReportCategoryEntry[];
+    /**
+     * Present when a destination besides the default exists: every destination,
+     * and the line telling an agent to ask the person.
+     */
+    meta?: {
+        destinations: GapReportDestination[];
+        ask: string;
+    } | undefined;
 };
 export type GapReportAggregateStatus = "filed" | "partial" | "failed" | "routed_only" | "consent_required" | "skipped";
 export type GapReportDeliveryStatus = "filed" | "routed_only" | "skipped" | "failed" | "consent_required";
@@ -81,6 +113,15 @@ export type GapReportReceipt = {
      * Count of handlers that routed only.
      */
     routedOnlyCount: number;
+    /**
+     * For a run without `to`,
+     * when a destination besides the default exists: every destination.
+     */
+    destinations?: GapReportDestination[] | undefined;
+    /**
+     * With `destinations`: ask the person where to file.
+     */
+    ask?: string | undefined;
 };
 export type GapReportReceiptResponse = {
     type: "gap-report.file";

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

@@ -23,12 +23,27 @@
  * @property {string} [package] Explicit owner package for ambiguous routes.
  * @property {boolean} [confirmPublic] Explicit consent for public handlers or GitHub issue creation.
  * @property {boolean} [listCategories] Return the category vocabulary without routing or writing.
+ * @property {string} [to] A destination the person chose: a loaded integration
+ *   whose manifest names an issues URL. The report goes only there.
+ */
+
+/**
+ * Where a report can go. The default entry (`to: null`) is the configured
+ * handlers, or with none the owning package's issues URL.
+ * @typedef {object} GapReportDestination
+ * @property {string|null} to The value to pass as `to`; null for the default.
+ * @property {boolean} default Whether this is the default destination.
+ * @property {string|null} issuesUrl The integration's issues URL; null for the
+ *   default.
  */
 
 /**
  * @typedef {object} GapReportCategoriesResponse
  * @property {'gap-report.categories'} type
  * @property {GapReportCategoryEntry[]} data
+ * @property {{destinations: GapReportDestination[], ask: string}} [meta]
+ *   Present when a destination besides the default exists: every destination,
+ *   and the line telling an agent to ask the person.
  */
 
 /**
@@ -58,6 +73,9 @@
  * @property {GapReportDelivery[]} deliveries Ordered handler outcomes.
  * @property {number} filedCount Count of handlers that filed the report.
  * @property {number} routedOnlyCount Count of handlers that routed only.
+ * @property {GapReportDestination[]} [destinations] For a run without `to`,
+ *   when a destination besides the default exists: every destination.
+ * @property {string} [ask] With `destinations`: ask the person where to file.
  */
 
 /**