@astryxdesign/cli 0.7.2-canary.f16dc9f → 0.7.2-canary.f2b60a0

package/clients/cli/commands/doctor.mjs

@@ -98,6 +98,85 @@ function issueBlocks(issues) {
   ];
 }
 
+/**
+ * The docs checked against the authoring types: a visible line when it was
+ * skipped, the findings (all warnings), the files it could not check, or an
+ * [ok] (never after a failed check).
+ * @param {import('../../../api/integration/validate-integration.type.mjs').DocTypesReport | undefined} report
+ * @param {boolean} failed
+ */
+function docTypesBlocks(report, failed) {
+  if (!report) return [];
+  if (
+    report.status === 'checked' &&
+    report.docs === 0 &&
+    report.findings.length === 0 &&
+    report.unchecked.length === 0
+  ) {
+    return [
+      text('[info] No doc files to type-check.'),
+      ...(report.fixtures
+        ? [text(`[info] ${report.fixtures} test fixture doc(s) not checked.`)]
+        : []),
+    ];
+  }
+  if (report.status === 'skipped') {
+    return [text(`[skip] Docs not type-checked: ${report.reason}`)];
+  }
+  const blocks = [
+    section(
+      `Checking ${report.docs} doc(s) against the authoring types${report.typescript ? ` (TypeScript ${report.typescript})` : ''}`,
+    ),
+  ];
+  if (report.findings.length > 0) {
+    const files = new Set(report.findings.map(f => f.doc)).size;
+    blocks.push(
+      records(report.findings, {
+        fields: [
+          'severity',
+          'doc',
+          'line',
+          'export',
+          'type',
+          'field',
+          'problem',
+          'message',
+          'fix',
+        ],
+        format: {severity: statusToken},
+      }),
+      text(
+        `${report.findings.length} doc field(s) in ${files} file(s) do not match the authoring types. ` +
+          'These are warnings; `astryx docs authoring` lists every field.',
+      ),
+    );
+  }
+  if (report.unchecked.length > 0) {
+    blocks.push(
+      text(`[info] Not type-checked: ${report.unchecked.length} doc file(s):`),
+      records(report.unchecked, {fields: ['doc', 'reason']}),
+    );
+  }
+  if (report.fixtures) {
+    blocks.push(
+      text(`[info] ${report.fixtures} test fixture doc(s) not checked.`),
+    );
+  }
+  if (report.findings.length === 0 && report.docs > 0) {
+    // After a failed check an [ok] reads as a pass, but the result still shows.
+    blocks.push(
+      text(
+        failed
+          ? `[info] No doc field differs from its authoring type (${report.docs} checked).`
+          : report.unchecked.length > 0
+            ? `[ok] Every doc that was checked matches its authoring type (${report.docs} checked).`
+            : `[ok] Every doc matches its authoring type (${report.docs} checked).`,
+      ),
+    );
+  }
+  return blocks;
+}
+
 /**
  * @param {import('../../../api/integration/validate-integration.type.mjs').ValidateIntegrationResponse['data']} data
  */
@@ -119,6 +198,7 @@ function printIntegrationValidation(data) {
       `Summary: ${errors} error${errors === 1 ? '' : 's'}, ` +
         `${warnings} warning${warnings === 1 ? '' : 's'}`,
     ),
+    ...docTypesBlocks(data.docTypes, errors > 0),
   );
 }
 
@@ -173,6 +253,98 @@ function printTemplateConflicts(data) {
   emit(...output);
 }
 
+/**
+ * The documented-props comparison, with every field its JSON carries: a
+ * visible line when it was skipped, the findings (all warnings), the
+ * components it could not read, and how many were compared with which
+ * TypeScript, as an [ok] when nothing differs (never after a failed check).
+ * Then how many documented prop types were judged and which were not.
+ * @param {import('../../../api/integration/authoring-checks.type.mjs').PropDriftReport | undefined} report
+ * @param {boolean} failed
+ */
+function propDriftBlocks(report, failed) {
+  if (!report) return [];
+  if (report.status === 'skipped') {
+    return [text(`[skip] Props not compared: ${report.reason}`)];
+  }
+  const blocks = [];
+  if (report.findings.length > 0) {
+    // Two docs of one name are two components.
+    const components = new Set(
+      report.findings.map(f => `${f.doc}\0${f.component}`),
+    ).size;
+    blocks.push(
+      records(report.findings, {
+        fields: [
+          'severity',
+          'component',
+          'prop',
+          'kind',
+          'message',
+          'doc',
+          'source',
+          'docType',
+          'codeType',
+          'docRequired',
+          'codeRequired',
+        ],
+        format: {severity: statusToken},
+      }),
+      text(
+        `${report.findings.length} prop(s) differ between the docs and the code in ${components} of ${report.components} component(s) compared (TypeScript ${report.typescript}). ` +
+          'These are warnings: update the doc, or the code if the doc is right.',
+      ),
+    );
+  }
+  if (report.unchecked.length > 0) {
+    blocks.push(
+      text(
+        `[info] Props not compared for ${report.unchecked.length} documented component(s):`,
+      ),
+      records(report.unchecked, {fields: ['component', 'doc', 'reason']}),
+    );
+  }
+  const notChecked = report.propsNotChecked ?? [];
+  if (notChecked.length > 0) {
+    blocks.push(
+      text(
+        `[info] Props not checked for a doc entry in ${notChecked.length} component(s):`,
+      ),
+      records(notChecked, {fields: ['component', 'doc', 'reason', 'props']}),
+    );
+  }
+  if (report.findings.length === 0) {
+    const apart =
+      notChecked.length > 0 ? ', apart from the props not checked' : '';
+    blocks.push(
+      text(
+        !failed && report.components > 0
+          ? `[ok] Documented prop names and required flags match the code in ${report.components} component(s)${apart} (TypeScript ${report.typescript}).`
+          : `[info] Props compared in ${report.components} component(s) (TypeScript ${report.typescript}).`,
+      ),
+    );
+  }
+  if (report.typesSkipped) {
+    blocks.push(text(`[skip] Prop types not judged: ${report.typesSkipped}.`));
+    return blocks;
+  }
+  const notCompared = report.typesNotCompared.flatMap(entry => entry.props);
+  blocks.push(
+    text(
+      `[info] Documented prop types judged: ${report.typesCompared}; not compared: ${notCompared.length}. ` +
+        'A type is judged when the doc writes it the same as the source (exactly, if it contains `readonly`), or when both are primitives, literals, arrays and unions of those, or names for them.',
+    ),
+  );
+  if (notCompared.length > 0) {
+    blocks.push(
+      records(report.typesNotCompared, {
+        fields: ['component', 'doc', 'reason', 'props'],
+      }),
+    );
+  }
+  return blocks;
+}
+
 /**
  * @param {import('../../../api/integration/authoring-checks.type.mjs').IntegrationComponentConflictResponse['data']} data
  */
@@ -205,6 +377,7 @@ function printComponentConflicts(data) {
       ),
     );
   }
+  output.push(...propDriftBlocks(data.propDrift, failed));
   emit(...output);
 }
 
@@ -242,6 +415,23 @@ function printDocConflicts(data) {
   emit(...output);
 }
 
+/**
+ * Print one `doctor integration` check's result as its own subcommand prints
+ * it. `astryx integration check` prints each check it runs through this.
+ * @param {import('../../../api/integration/integration-check.type.mjs').IntegrationCheckResponse} response
+ */
+export function printIntegrationCheckResponse(response) {
+  if (response.type === 'integration.validate') {
+    printIntegrationValidation(response.data);
+  } else if (response.type === 'integration.component-conflicts') {
+    printComponentConflicts(response.data);
+  } else if (response.type === 'integration.template-conflicts') {
+    printTemplateConflicts(response.data);
+  } else {
+    printDocConflicts(response.data);
+  }
+}
+
 /** @param {import('commander').Command} program */
 async function runProjectDoctor(program) {
   const report = await runChecks();

package/clients/cli/commands/integration-check.doc.mjs

@@ -0,0 +1,85 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file CommandDoc for `astryx integration check`.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').CommandDoc} */
+export const doc = {
+  type: 'command',
+  name: 'integration check',
+  displayName: 'astryx integration check',
+  namespace: 'cli/commands',
+  summary:
+    "The CI check for an integration package's own build: every source check, run in continuous integration or a typecheck script, against the package in the current folder",
+  description:
+    'Takes no package argument: it runs the four `doctor integration` checks, ' +
+    '`validate`, `components`, `templates`, and `docs`, against the integration ' +
+    'package in the current folder, which is where its own build runs it. It prints ' +
+    'each result as that check ' +
+    'prints it, then a summary with the errors, warnings, and skipped work of each, ' +
+    'and exits 1 when any of the four would exit 1 on its own. With `--strict` it ' +
+    'also exits 1 on any warning and on any check, or comparison within a check, ' +
+    'that did not run, such as a package with no `astryx.integration.*` or a ' +
+    'comparison skipped because the project has no TypeScript, or prop types not ' +
+    'judged because its TypeScript is older than 4.8: it adds no check, ' +
+    'and lists each of those again as an error, after the checks, in their own ' +
+    'issue format. That is the line ' +
+    "for the package's own build, so its docs, types, and links stay in sync: run " +
+    'it as a `ci` step, or add ' +
+    '`"typecheck": "tsc --noEmit && astryx integration check --strict"` to the ' +
+    'scripts in package.json. Its exit codes and JSON are a contract for the builds ' +
+    'that run it: a new check, or a new failure code, joins only in a minor release ' +
+    'that names it in the release notes. A patch can still ship a Core component, ' +
+    'template, or CLI topic whose name conflicts with one of yours. Run ' +
+    '`integration check` on every build; run ' +
+    '`integration verify` before you publish, to check that the packed package ' +
+    'works in an app. To check an installed integration by name, run the ' +
+    '`doctor integration` subcommands with its package name.',
+  fn: 'integrationCheck',
+  options: [
+    {
+      flag: '--strict',
+      param: 'options.strict',
+      description:
+        'Also exit 1 on any warning and on any check that did not run. A new check or failure code joins only in a minor release, named in the release notes.',
+    },
+  ],
+  examples: [
+    {
+      label:
+        'In CI, as the typecheck script: add "typecheck": "tsc --noEmit && astryx integration check --strict" to package.json',
+      cli: 'integration check --strict',
+    },
+    {
+      label: 'Errors only, while you fix the warnings a package already has',
+      cli: 'integration check',
+    },
+    {
+      label: 'Read the result as JSON',
+      cli: 'integration check --strict --json',
+    },
+    {
+      label:
+        'Before you publish: check that the packed package works in an app',
+      cli: 'integration verify',
+    },
+  ],
+  exitCodes: [
+    {
+      code: 0,
+      when: 'no check fails on its own; with --strict, also no warning, and every check ran',
+    },
+    {
+      code: 1,
+      when: 'a check fails on its own (an error); with --strict, also any warning, or a check that did not run',
+    },
+  ],
+  related: [
+    'integration verify',
+    'doctor integration validate',
+    'doctor integration components',
+    'doctor integration templates',
+    'doctor integration docs',
+  ],
+};

package/clients/cli/commands/integration-check.test.mjs

@@ -0,0 +1,267 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx integration check`: every source check in one command, the
+ * summary, exit codes with and without `--strict`, and the `--strict`
+ * failures, in text and JSON alike.
+ */
+
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {runCli} from '../../../test-utils/run-cli.mjs';
+import {discoverCoreTemplates} from '../../../foundation/discovery/template-adapter.mjs';
+
+/** @type {string} */
+let tmpDir;
+
+beforeEach(() => {
+  // Under the repository, so the components check resolves Core.
+  tmpDir = fs.mkdtempSync(
+    path.join(process.cwd(), '.astryx-integration-check-cli-'),
+  );
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+/**
+ * A package whose one page template takes a Core template's id: one warning
+ * (`templates` conflict). The doc matches TemplateDoc, so no other check
+ * warns about it.
+ * @param {{id: string, replaces?: string, extraManifest?: string, dir?: string}} options
+ */
+function writePackage({id, replaces, extraManifest = '', dir = tmpDir}) {
+  fs.writeFileSync(
+    path.join(dir, 'package.json'),
+    JSON.stringify({name: '@acme/widgets', version: '1.2.3'}),
+  );
+  fs.writeFileSync(
+    path.join(dir, 'astryx.integration.mjs'),
+    `export default {templates: './templates'${extraManifest}};\n`,
+  );
+  fs.mkdirSync(path.join(dir, 'templates'), {recursive: true});
+  fs.writeFileSync(
+    path.join(dir, 'templates', `${id}.doc.mjs`),
+    `export default {type: 'page', name: 'Integration template', displayName: 'Integration template', description: 'fixture'${replaces == null ? '' : `, replaces: ${JSON.stringify(replaces)}`}};\n`,
+  );
+  fs.writeFileSync(
+    path.join(dir, 'templates', `${id}.tsx`),
+    'export default function Fixture() { return null; }\n',
+  );
+}
+
+async function coreTemplateId() {
+  const core = (await discoverCoreTemplates()).find(
+    template => template.type === 'page',
+  );
+  expect(core).toBeDefined();
+  return /** @type {{dirName: string}} */ (core).dirName;
+}
+
+describe('astryx integration check', () => {
+  it('runs validate, components, templates, and docs in order, then a summary, and exits 0 on a warning', async () => {
+    writePackage({id: await coreTemplateId()});
+
+    const run = await runCli(['integration', 'check'], tmpDir);
+
+    const order = [
+      'Validating integration: @acme/widgets@1.2.3',
+      'Checking integration components: @acme/widgets@1.2.3',
+      'Checking integration templates: @acme/widgets@1.2.3',
+      'Checking integration docs: @acme/widgets@1.2.3',
+      'Integration check: @acme/widgets@1.2.3',
+    ].map(line => run.stdout.indexOf(line));
+    expect(order.every(index => index >= 0)).toBe(true);
+    expect([...order].sort((a, b) => a - b)).toEqual(order);
+    expect(run.stdout).toContain('Consider renaming');
+    expect(run.stdout).not.toContain('Failing under --strict');
+    expect(run.stdout).toContain(
+      '[ok] 0 errors, 1 warning, 0 skipped. No check failed;',
+    );
+    // Each check's output stands apart from the next.
+    const lines = run.stdout.split('\n');
+    for (const header of [
+      'Checking integration components:',
+      'Checking integration templates:',
+      'Checking integration docs:',
+    ]) {
+      expect(lines[lines.findIndex(line => line.includes(header)) - 1]).toBe(
+        '',
+      );
+    }
+    expect(run.status).toBe(0);
+  });
+
+  it('--strict lists the warning again as an error, after the checks, and exits 1', async () => {
+    const id = await coreTemplateId();
+    writePackage({id});
+
+    const run = await runCli(['integration', 'check', '--strict'], tmpDir);
+
+    expect(run.stdout).toContain(
+      'Integration check: @acme/widgets@1.2.3 (strict)',
+    );
+    const block = run.stdout.indexOf('Failing under --strict');
+    expect(block).toBeGreaterThan(
+      run.stdout.indexOf('Checking integration docs:'),
+    );
+    expect(run.stdout.slice(block)).toMatch(
+      /severity: \[fail\]\ncheck: +templates\ncode: +template_id_conflict\n/,
+    );
+    expect(run.stdout).toContain(
+      '[fail] 0 errors, 1 warning, 0 skipped. --strict fails on every warning and on skipped work;',
+    );
+    expect(run.status).toBe(1);
+  });
+
+  it('--json carries each check with its own envelope, the --strict failures, and exits as the text does', async () => {
+    const id = await coreTemplateId();
+    writePackage({id});
+
+    const run = await runCli(
+      ['integration', 'check', '--strict', '--json'],
+      tmpDir,
+    );
+
+    const parsed = JSON.parse(run.stdout.trim());
+    expect(parsed.type).toBe('integration.check');
+    expect(parsed.data).toMatchObject({
+      validated: true,
+      name: '@acme/widgets',
+      version: '1.2.3',
+      strict: true,
+      errors: 0,
+      warnings: 1,
+      skipped: [],
+      failed: true,
+    });
+    expect(parsed.data.checks.map(check => check.check)).toEqual([
+      'validate',
+      'components',
+      'templates',
+      'docs',
+    ]);
+    const templates = parsed.data.checks[2];
+    expect(templates).toMatchObject({
+      check: 'templates',
+      errors: 0,
+      warnings: 1,
+      skipped: [],
+      failed: false,
+      response: {
+        type: 'integration.template-conflicts',
+        data: {conflicts: [expect.objectContaining({id, severity: 'warning'})]},
+      },
+    });
+    expect(parsed.data.failures).toEqual([
+      {
+        check: 'templates',
+        severity: 'error',
+        code: 'template_id_conflict',
+        message: templates.response.data.conflicts[0].message,
+      },
+    ]);
+    expect(run.status).toBe(1);
+  });
+
+  it('exits 1 without --strict when one check fails on its own, and lists no failures', async () => {
+    writePackage({id: 'acme-app-shell', replaces: 'missing-core-shell'});
+
+    const text = await runCli(['integration', 'check'], tmpDir);
+    const json = await runCli(['integration', 'check', '--json'], tmpDir);
+
+    expect(text.stdout).toContain('missing_template_replacement_target');
+    expect(text.stdout).toMatch(
+      /\[fail\] [1-9]\d* errors?, .*Address the items marked \[fail\] above\./,
+    );
+    expect(text.stdout).not.toContain('Failing under --strict');
+    expect(JSON.parse(json.stdout.trim()).data).toMatchObject({
+      strict: false,
+      failures: [],
+      failed: true,
+    });
+    expect(text.status).toBe(1);
+    expect(json.status).toBe(1);
+  });
+
+  it('counts a package with no manifest as skipped work: exit 0, and 1 with --strict', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({name: '@acme/plain', version: '1.0.0'}),
+    );
+
+    const loose = await runCli(['integration', 'check'], tmpDir);
+    expect(loose.stdout).toContain(
+      "Nothing was checked: no astryx.integration.* found next to package.json. Run this command in an integration package's folder.",
+    );
+    // One cause, however many checks it stops: counted once.
+    expect(loose.stdout).toContain('[ok] 0 errors, 0 warnings, 1 skipped.');
+    expect(loose.status).toBe(0);
+
+    const strict = await runCli(
+      ['integration', 'check', '--strict', '--json'],
+      tmpDir,
+    );
+    const {data} = JSON.parse(strict.stdout.trim());
+    expect(data).toMatchObject({validated: false, errors: 0, failed: true});
+    // One cause, however many checks it stops: listed once.
+    expect(data.failures).toEqual([
+      {
+        check: 'validate',
+        severity: 'error',
+        code: 'missing_manifest',
+        message:
+          'No astryx.integration.* found next to package.json, so nothing was checked.',
+      },
+    ]);
+    expect(strict.status).toBe(1);
+  });
+
+  it('exits 1 for no package.json, as validate does', async () => {
+    const empty = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-no-pkg-'));
+    try {
+      const run = await runCli(['integration', 'check'], empty);
+      expect(run.stdout).toContain(
+        'Nothing was checked: no package.json found.',
+      );
+      expect(run.stdout).toContain('Integration check: (no package.json)');
+      expect(run.stdout).toContain(
+        '[fail] 1 error, 0 warnings, 0 skipped. No package.json was found here, so nothing was checked.',
+      );
+      expect(run.stdout).not.toContain('marked [fail] above');
+      expect(run.status).toBe(1);
+    } finally {
+      fs.rmSync(empty, {recursive: true, force: true});
+    }
+  });
+
+  it('states in its help that it is the CI check, the line to add, and what --strict promises', async () => {
+    const run = await runCli(['integration', 'check', '--help'], tmpDir);
+
+    expect(run.stdout).toContain(
+      "The CI check for an integration package's own build",
+    );
+    expect(run.stdout).toContain(
+      '"typecheck": "tsc --noEmit && astryx integration check --strict"',
+    );
+    expect(run.stdout).toContain(
+      'A new check or failure code joins only in a minor release, named in the release notes.',
+    );
+    expect(run.stdout).toContain('integration verify');
+    expect(run.stdout).toContain('against the package in the current folder');
+    expect(run.stdout).not.toContain('[package]');
+  });
+
+  it('takes no package name: one passed is an error, not a check of the current folder', async () => {
+    writePackage({id: 'acme-page'});
+
+    const run = await runCli(['integration', 'check', '@acme/widgets'], tmpDir);
+
+    expect(run.stderr).toContain('too many arguments');
+    expect(run.stdout).not.toContain('Integration check:');
+    expect(run.status).toBe(1);
+  });
+});

package/clients/cli/commands/integration.doc.mjs

@@ -8,13 +8,17 @@ export const doc = {
   namespace: 'cli/commands',
   summary: 'Author and verify an Astryx integration package',
   description:
-    'Add contributions to your package, then check the packed package the way an app receives it. The guides start at {@link namespace:integrations}.',
-  subcommands: ['add', 'verify', 'pack'],
+    'Add contributions to your package, check them on every build with `integration check --strict`, then check the packed package the way an app receives it. The guides start at {@link namespace:integrations}.',
+  subcommands: ['add', 'check', 'verify', 'pack'],
   examples: [
     {
       label: 'Add a component',
       cli: 'astryx integration add component AcmeWidget',
     },
+    {
+      label: 'Check the package in CI, as part of its build',
+      cli: 'astryx integration check --strict',
+    },
     {
       label: 'Check the package before publishing',
       cli: 'astryx integration verify',