@astryxdesign/cli 0.7.2-canary.ebcc404 → 0.7.2-canary.f8f7cf1

package/authoring/doctypes/template/integration-template.doc.mjs

@@ -0,0 +1,49 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file SchemaDoc for the `IntegrationTemplateDoc` doc-type — the template
+ * metadata an integration package ships: TemplateDoc, with the package's own
+ * `category`. Colocated with the type it describes (`type.ts`).
+ * @position packages/cli/authoring/doctypes/template — doc-type documentation
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').SchemaDoc} */
+export const doc = {
+  type: 'schema',
+  name: 'integration-template-doc',
+  displayName: 'IntegrationTemplateDoc',
+  namespace: 'authoring',
+  description:
+    "The doc-type for an integration package's template metadata. It has every " +
+    "TemplateDoc field and rule, except that `category` is the package's own " +
+    'string instead of a TemplateCategory value.',
+  appliesTo: '<Name>.doc.mjs',
+  fields: [
+    {
+      name: 'category',
+      type: 'string',
+      description:
+        "The package's own category. Bare `astryx template` groups the package's templates by it.",
+    },
+  ],
+  examples: [
+    {
+      label: 'Block template in an integration package',
+      code: `/** @type {import('@astryxdesign/cli/authoring').IntegrationTemplateDoc} */
+export default {
+  type: 'block',
+  name: 'acme-pricing-table',
+  displayName: 'Pricing Table',
+  description: 'Plans side by side, with the chosen plan highlighted.',
+  aspectRatio: 16 / 9,
+  category: 'Acme - Commerce',
+};`,
+    },
+  ],
+  notes: [
+    {
+      type: 'prose',
+      text: "Every other field, and the page and block variants, are TemplateDoc's. Core's own templates use TemplateDoc, whose `category` is a TemplateCategory value. `astryx doctor integration validate` checks an integration's template docs against IntegrationTemplateDoc.",
+    },
+  ],
+};

package/authoring/doctypes/template/parse.d.mts

@@ -18,7 +18,9 @@ export type BlockTemplateDoc = import("./type.js").BlockTemplateDoc;
  * Templates as they load. Integration templates already published omit
  * `displayName` and `aspectRatio` and group themselves under their own
  * `category`, so the loader accepts those (template discovery falls back to an
- * aspect ratio of 1). The published types keep asking authors for all three.
+ * aspect ratio of 1). The published `TemplateDoc` keeps asking authors for all
+ * three; `IntegrationTemplateDoc`, for an integration package's templates,
+ * takes the package's own `category`.
  */
 export type LoadedPageTemplateDoc = Omit<PageTemplateDoc, "displayName" | "category"> & {
     displayName?: string;
@@ -28,7 +30,9 @@ export type LoadedPageTemplateDoc = Omit<PageTemplateDoc, "displayName" | "categ
  * Templates as they load. Integration templates already published omit
  * `displayName` and `aspectRatio` and group themselves under their own
  * `category`, so the loader accepts those (template discovery falls back to an
- * aspect ratio of 1). The published types keep asking authors for all three.
+ * aspect ratio of 1). The published `TemplateDoc` keeps asking authors for all
+ * three; `IntegrationTemplateDoc`, for an integration package's templates,
+ * takes the package's own `category`.
  */
 export type LoadedBlockTemplateDoc = Omit<BlockTemplateDoc, "displayName" | "aspectRatio" | "category"> & {
     displayName?: string;

package/authoring/doctypes/template/parse.mjs

@@ -78,7 +78,9 @@ const blockTemplateSchema = z
  * Templates as they load. Integration templates already published omit
  * `displayName` and `aspectRatio` and group themselves under their own
  * `category`, so the loader accepts those (template discovery falls back to an
- * aspect ratio of 1). The published types keep asking authors for all three.
+ * aspect ratio of 1). The published `TemplateDoc` keeps asking authors for all
+ * three; `IntegrationTemplateDoc`, for an integration package's templates,
+ * takes the package's own `category`.
  *
  * @typedef {Omit<PageTemplateDoc, 'displayName' | 'category'>
  *   & {displayName?: string, category?: string}} LoadedPageTemplateDoc

package/authoring/doctypes/template/template.doc.mjs

@@ -162,7 +162,7 @@ export default {
   notes: [
     {
       type: 'prose',
-      text: 'When it loads, a template may leave out `displayName` and `aspectRatio` and use its own `category`, as integration templates already published do; a block with no `aspectRatio` previews at 1. Write to the type anyway; it is the contract.',
+      text: 'When it loads, a template may leave out `displayName` and `aspectRatio` and use its own `category`, as integration templates already published do; a block with no `aspectRatio` previews at 1. Write to the type anyway; it is the contract, and `astryx doctor integration validate` warns about an integration template that leaves out `displayName` or `aspectRatio`.',
     },
     {
       type: 'prose',

package/authoring/doctypes/template/type.ts

@@ -201,3 +201,25 @@ export type TemplateCategory =
   | 'Shell - Blank';
 
 export type TemplateDoc = PageTemplateDoc | BlockTemplateDoc;
+
+/** A page template an integration package ships, with its own `category`. */
+export interface IntegrationPageTemplateDoc extends Omit<
+  PageTemplateDoc,
+  'category'
+> {
+  category?: string;
+}
+
+/** A block template an integration package ships, with its own `category`. */
+export interface IntegrationBlockTemplateDoc extends Omit<
+  BlockTemplateDoc,
+  'category'
+> {
+  category?: string;
+}
+
+/** The doc-type for an integration package's template metadata: TemplateDoc,
+ *  with `category` the package's own string (bare `astryx template` groups
+ *  the package's templates by it) instead of a TemplateCategory value. */
+export type IntegrationTemplateDoc =
+  IntegrationPageTemplateDoc | IntegrationBlockTemplateDoc;

package/authoring/index.d.ts

@@ -28,6 +28,7 @@ export type {HookDoc} from './doctypes/types.js'; //         useToast.doc.mjs
 export type {FunctionDoc} from './doctypes/types.js'; //     search.doc.mjs (hook | api)
 export type {ReferenceDoc} from './doctypes/types.js'; //    theming.doc.mjs
 export type {TemplateDoc} from './doctypes/types.js'; //     Foo.doc.mjs
+export type {IntegrationTemplateDoc} from './doctypes/types.js'; // an integration's Foo.doc.mjs
 export type {SchemaDoc} from './doctypes/types.js'; //       config.doc.mjs (object shape)
 export type {CommandDoc} from './doctypes/types.js'; //      search.doc.mjs (CLI command)
 export type {EnumDoc} from './doctypes/types.js'; //         error-codes.doc.mjs (vocabulary)

package/authoring/integration/integration.doc.mjs

@@ -74,6 +74,13 @@ export const doc = {
       description: 'Where to file issues/feedback for this integration.',
       example: "'https://github.com/acme/widgets/issues'",
     },
+    {
+      name: 'docsiteUrl',
+      type: 'string',
+      description:
+        "Link to this integration's docs site, such as its home page. Catalogs that list the package may show it.",
+      example: "'https://widgets.acme.dev'",
+    },
   ],
   examples: [
     {
@@ -118,7 +125,7 @@ export const doc = {
       text:
         'Validate the manifest with `astryx doctor integration validate`. At the ' +
         'load boundary, a known field of the wrong type is an error, issuesUrl ' +
-        'must be a valid URL, and unknown fields become warnings so an older CLI ' +
+        'and docsiteUrl must be valid URLs, and unknown fields become warnings so an older CLI ' +
         'can still load the fields it understands. Before publishing, also run ' +
         '`templates`, `components`, and `docs` under the same `doctor integration` ' +
         'group. Those leaves compare authored identities with Core and explain ' +

package/authoring/integration/parse.test.mjs

@@ -87,6 +87,16 @@ describe('parseIntegration (load boundary)', () => {
     expect(reason({issuesUrl: 'nope'})).toContain('issuesUrl');
   });
 
+  it('accepts a docsiteUrl as a known key', () => {
+    const manifest = {docsiteUrl: 'https://widgets.example.com'};
+    expect(parseIntegration(manifest)).toEqual(manifest);
+    expect(unknownIntegrationKeys(manifest)).toEqual([]);
+  });
+
+  it('rejects a non-URL docsiteUrl', () => {
+    expect(reason({docsiteUrl: 'nope'})).toContain('docsiteUrl');
+  });
+
   it('rejects a noncanonical providerId', () => {
     expect(reason({providerId: 'Acme Widgets'})).toContain('providerId');
   });

package/authoring/integration/schema.d.mts

@@ -39,6 +39,7 @@ export const integrationBaseSchema: z.ZodObject<{
     docs: z.ZodOptional<z.ZodString>;
     themes: z.ZodOptional<z.ZodString>;
     issuesUrl: z.ZodOptional<z.ZodString>;
+    docsiteUrl: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export const integrationSchema: z.ZodObject<{
     providerId: z.ZodOptional<z.ZodString>;
@@ -48,6 +49,7 @@ export const integrationSchema: z.ZodObject<{
     docs: z.ZodOptional<z.ZodString>;
     themes: z.ZodOptional<z.ZodString>;
     issuesUrl: z.ZodOptional<z.ZodString>;
+    docsiteUrl: z.ZodOptional<z.ZodString>;
     agentDocs: z.ZodOptional<z.ZodObject<{
         append: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
     }, z.core.$strip>>;

package/authoring/integration/schema.mjs

@@ -78,6 +78,7 @@ export const integrationBaseSchema = z.object({
   docs: z.string().optional(),
   themes: z.string().optional(),
   issuesUrl: z.string().url().optional(),
+  docsiteUrl: z.string().url().optional(),
 });
 
 // Unknown top-level keys are stripped rather than rejected. `.strict()` made a key from a

package/authoring/integration/type.ts

@@ -44,6 +44,10 @@ export interface AstryxIntegration {
   };
   /** Where to file issues/feedback for this integration. */
   issuesUrl?: string;
+  /** Link to this integration's docs site, such as its home page. The CLI
+   *  accepts it as a known field; catalogs that list the package may show
+   *  it. */
+  docsiteUrl?: string;
 }
 
 /**

package/clients/cli/commands/build-theme.batch-report.test.mjs

@@ -168,7 +168,9 @@ describe('theme build report', () => {
     }
     expect(count(out, 'Install in your app')).toBe(1);
     expect(count(out, 'Or with a <link> tag:')).toBe(1);
-    expect(count(out, "import { Theme } from '@astryxdesign/core';")).toBe(2);
+    expect(
+      count(out, "import { Theme } from '@astryxdesign/core/theme';"),
+    ).toBe(2);
     expect(count(out, '[note]')).toBe(1);
     expect(count(out, 'note: Font')).toBe(0);
     expect(count(out, 'fonts.googleapis.com/css2')).toBe(1);

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

@@ -397,7 +397,7 @@ function printThemeApp(result) {
   emit(
     text('Wire the generated module once in the app root:'),
     code(
-      "import {Theme} from '@astryxdesign/core';\n" +
+      "import {Theme} from '@astryxdesign/core/theme';\n" +
         `import {themes, defaultThemeSlug} from './${stem}';\n\n` +
         '<Theme theme={themes[defaultThemeSlug]}>\n  <App />\n</Theme>',
     ),

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

@@ -9,9 +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 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.
+ *   - 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.
  */
@@ -25,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});
@@ -62,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);
@@ -95,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();
@@ -117,41 +126,88 @@ 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('reports an absolute --out path outside the project as ERR_PATH_TRAVERSAL, with --check too', async () => {
+  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 = writeTheme(path.join(project, 'themes'), 'ocean');
+    const themeFile = path.relative(
+      project,
+      writeTheme(path.join(project, 'themes'), 'ocean'),
+    );
     const out = path.join(outside, 'ocean.css');
 
-    for (const extra of [[], ['--check']]) {
-      const {result, envelope} = await buildJson(
-        [path.relative(project, themeFile), '--out', out, ...extra],
-        project,
-      );
+    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([]);
 
-      expect(result.code).toBe(1);
-      expect(envelope.code).toBe(ERROR_CODES.ERR_PATH_TRAVERSAL);
+    // 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));
     }
-    expect(fs.readdirSync(outside)).toEqual([]);
+    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', async () => {
+  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');
@@ -162,10 +218,82 @@ describe('theme build output-path failures carry registered codes', () => {
 
       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');
@@ -243,7 +371,7 @@ describe('theme build output-path failures carry registered codes', () => {
     });
   });
 
-  it('themeBuild() rejects an output outside cwd: an absolute out path, or the default beside a theme file outside cwd', async () => {
+  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');
@@ -257,6 +385,12 @@ describe('theme build output-path failures carry registered codes', () => {
       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/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'],