@astryxdesign/cli 0.7.2-canary.fe2c655 → 0.7.2

package/api/integration/integrationCheck.doc.mjs

@@ -0,0 +1,73 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file FunctionDoc for `integrationCheck()` / `astryx integration check`.
+ * Colocated with the API function it documents; the shape source of truth stays
+ * in `integration-check.type.mjs`.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').FunctionDoc} */
+export const doc = {
+  type: 'function',
+  kind: 'api',
+  name: 'integrationCheck',
+  namespace: 'cli/api',
+  displayName: 'integrationCheck()',
+  summary:
+    'Run every source check against the integration package in the current folder, as its build does: validate, components, templates, and docs.',
+  description:
+    'Runs `validateIntegration`, `integrationComponentConflicts`, ' +
+    '`integrationTemplateConflicts`, and `integrationDocConflicts` against the ' +
+    'integration package in `options.cwd`, and counts each result the way that ' +
+    "check's own subcommand exits. The run fails when any of the four would fail on " +
+    'its own. With `strict` it also fails on any warning and on any check that did ' +
+    'not run: a package with no integration manifest, or a comparison a check ' +
+    "carries that was skipped, such as one that needs the project's TypeScript. " +
+    '`strict` adds no check: it reports those warnings and skipped work again, as ' +
+    "errors in the checks' own issue format. " +
+    'A new check, or a new failure code, joins only in a minor release, named in the release notes.',
+  importPath: '@astryxdesign/cli/api',
+  signature:
+    'integrationCheck(options?: IntegrationCheckOptions): Promise<IntegrationCheckCommandResponse>',
+  keywords: ['integration', 'check', 'build', 'strict', 'validate', 'doctor'],
+  params: [
+    {
+      name: 'options.cwd',
+      type: 'string',
+      default: 'process.cwd()',
+      description: 'The integration package folder to check.',
+    },
+    {
+      name: 'options.strict',
+      type: 'boolean',
+      default: 'false',
+      description:
+        'Also fail on any warning and on any check that did not run, not only on errors. A malformed `cliCommand` is reported as a note (`invalid_cli_command`) in `data.notes` of the validate check, which fails nothing until a minor release names it.',
+    },
+  ],
+  returns: [
+    {
+      type: 'integration.check',
+      description:
+        "`data.validated` (false when no integration manifest was found, so nothing was checked), `data.name` and `data.version` of the package, `data.strict`, and `data.checks`, one entry per check in the order they run (`validate`, `components`, `templates`, `docs`), each with `check`, `errors` (what makes that check's own subcommand exit 1), `warnings`, `skipped` (why work did not run), `failed` (whether that subcommand exits 1), and `response`, the envelope the check returns on its own. The totals are `data.errors`, `data.warnings`, and `data.skipped` (each reason prefixed with its check); an issue every check starts from, such as one about the manifest, counts once, and every other finding counts on its own. `data.unchecked` counts the items the checks list as not compared, which never fail it. With `strict`, `data.failures` lists each warning and each piece of skipped work once again as an error in the checks' own issue format ({check, severity: `error`, code, message, component, prop, fix, file, line}, each where it applies); it is empty without `strict`. `data.failed` decides the exit code.",
+    },
+  ],
+  examples: [
+    {
+      label: 'Check the local package',
+      code: 'const r = await integrationCheck();',
+    },
+    {
+      label: 'Fail on warnings too',
+      code: 'const {data} = await integrationCheck({strict: true});\nif (data.failed) process.exitCode = 1;',
+    },
+  ],
+  command: 'integration check',
+  related: [
+    'validateIntegration',
+    'integrationComponentConflicts',
+    'integrationTemplateConflicts',
+    'integrationDocConflicts',
+    'integrationPackCheck',
+  ],
+};

package/api/integration/integrationComponentConflicts.doc.mjs

@@ -10,30 +10,69 @@ export const doc = {
   namespace: 'cli/api',
   displayName: 'integrationComponentConflicts()',
   summary:
-    'Check integration component names and replaces declarations against Core.',
+    'Check integration component names, replaces declarations, and documented props.',
   description:
     'Loads one local or installed integration, compares its component names with ' +
     'Core, and returns non-blocking conflicts with the exact package-qualified ' +
     "component command required to keep an intentional overlap. Each component's " +
     'replaces is checked too: its findings are issues, errors for a package that ' +
-    'declares the CLI range that turns replacement on and warnings otherwise.',
+    'declares the CLI range that turns replacement on and warnings otherwise. ' +
+    "A `{@link}` in a component doc's text that names no doc is an `invalid_doc_graph` " +
+    'warning, since it prints as written. ' +
+    "Each component doc's props are compared with the component's TypeScript props, " +
+    "read with the project's own `typescript` (or, where `typescript` is missing or has no " +
+    'JavaScript compiler API, as TypeScript 7 does, the `@typescript/typescript6` it ' +
+    'installs): a documented prop the code lacks, a ' +
+    'prop the package declares that the doc omits, a wrong `required`, or a type ' +
+    'that does not match. A type is judged only when it reads exactly: the same ' +
+    'text as the source, once whitespace, quotes and union order are set aside (exactly, if it contains `readonly`), ' +
+    'or primitives, literals, arrays and unions of those, or a name for one, on ' +
+    'both sides, a field such as `status.type` included, and for a union of ' +
+    "props types, the type of any one member. A field the prop's variants give " +
+    "different types is listed when the doc gives only some variants' types. A " +
+    'mutable array type matches a readonly one, because callers can pass it; a ' +
+    'readonly one documented for a mutable array is a mismatch. ' +
+    '`Name = …` with a union after it ' +
+    "must match in both parts; one value after it (`Size = 'md'`) is read as a " +
+    "default. A name only TypeScript's own libraries declare is not resolved, and " +
+    '`React.X` resolves through React where the prop is declared. Every ' +
+    'other type is listed as not compared, never reported, and so is a name an ' +
+    'index signature takes unless exactly one the package declares takes it; ' +
+    'with a TypeScript older than 4.8 no type is judged. ' +
+    'Those findings are warnings in `propDrift`; without TypeScript it is ' +
+    '`skipped` with a reason.',
   importPath: '@astryxdesign/cli/api',
   signature:
     'integrationComponentConflicts(pkg?: string, options?: IntegrationAuthoringOptions): Promise<IntegrationComponentConflictResponse>',
-  keywords: ['integration', 'component', 'conflict', 'authoring', 'doctor'],
+  keywords: [
+    'integration',
+    'component',
+    'conflict',
+    'authoring',
+    'doctor',
+    'props',
+    'drift',
+  ],
   params: [
-    {name: 'pkg', type: 'string', description: 'Installed package; omit for the local package.'},
+    {
+      name: 'pkg',
+      type: 'string',
+      description: 'Installed package; omit for the local package.',
+    },
     {name: 'options.cwd', type: 'string', description: 'Resolution directory.'},
   ],
   returns: [
     {
       type: 'integration.component-conflicts',
       description:
-        '`validated` (false when no integration manifest was found, so nothing was inspected), integration identity, structural and replaces issues, and Core component-name conflicts with package-qualified commands. An active replacement that keeps the Core name it replaces is not a conflict.',
+        "`validated` (false when no integration manifest was found, so nothing was inspected), integration identity, structural and replaces issues, and Core component-name conflicts with package-qualified commands. An active replacement that keeps the Core name it replaces is not a conflict. When the manifest loads and declares a components root, `propDrift` holds the props comparison: `status` (`checked` | `skipped`), `reason` when skipped, `typescript`, `components` compared, `typesCompared` (documented prop types judged), `typesSkipped` (why none was, with a TypeScript older than 4.8), `findings` ({component, prop, kind: `not_in_code` | `not_in_doc` | `required_mismatch` | `type_mismatch` | `default_mismatch`, severity: `warning`, message, doc, source, docType?, codeType?, docRequired?, codeRequired?, docDefault?, codeDefault?, fix?}), `unchecked` ({component, doc, reason}), `typesNotCompared` ({component, doc, reason, props}: every other documented prop type, grouped by why it was not judged: not a form the check judges exactly (a doc type that does not parse, or a prop a mapped type builds from keys the check cannot trace, included), a field the prop's variants give different types, a standard prop such as `className`, or a prop declared outside the package), and `propsNotChecked` when a mapped type builds props from keys the check cannot trace to the package ({component, doc, reason, props}: no warning is drawn for those props).",
     },
   ],
   examples: [
-    {label: 'Check the local integration', code: 'await integrationComponentConflicts();'},
+    {
+      label: 'Check the local integration',
+      code: 'await integrationComponentConflicts();',
+    },
   ],
   command: 'doctor integration components',
   related: ['integrationTemplateConflicts', 'component'],

package/api/integration/integrationDocConflicts.doc.mjs

@@ -9,28 +9,45 @@ export const doc = {
   name: 'integrationDocConflicts',
   namespace: 'cli/api',
   displayName: 'integrationDocConflicts()',
-  summary: 'Check an integration\'s docs: the docs tree they add, every link, and overlaps with Core topics.',
+  summary:
+    "Check an integration's docs: the docs tree they add, every link, and overlaps with Core topics.",
   description:
     'Loads one local or installed integration and classifies Core doc overlaps as ' +
     'intentional replacements, intentional extensions, or accidental same-name ' +
-    'conflicts that need an explicit relationship or a rename.',
+    'conflicts that need an explicit relationship or a rename. `copiedPassages` lists each ' +
+    'pair of topics that repeat 10 or more words of prose word for word: two of the ' +
+    "package's topics, or one of them and a Core topic other than the one it replaces. " +
+    'Code and examples are not compared. `fluff` lists each padding phrase, with its file ' +
+    'line, and each topic of 80 or more prose words in which fewer than half carry content. ' +
+    '`strayPointers` lists each code span that is exactly `astryx docs <name>` for a doc that ' +
+    "exists, in a topic's prose, description or summary or a component doc's text fields, " +
+    'with the `{@link}` that replaces it. ' +
+    'Each entry of these lists is also a warning (`copied_passage`, `doc_fluff`, `stray_doc_pointer`), so ' +
+    '`integration check --strict` fails on it; the check itself still fails only on errors.',
   importPath: '@astryxdesign/cli/api',
   signature:
     'integrationDocConflicts(pkg?: string, options?: IntegrationAuthoringOptions): Promise<IntegrationDocConflictResponse>',
   keywords: ['integration', 'docs', 'replace', 'extend', 'authoring', 'doctor'],
   params: [
-    {name: 'pkg', type: 'string', description: 'Installed package; omit for the local package.'},
+    {
+      name: 'pkg',
+      type: 'string',
+      description: 'Installed package; omit for the local package.',
+    },
     {name: 'options.cwd', type: 'string', description: 'Resolution directory.'},
   ],
   returns: [
     {
       type: 'integration.doc-conflicts',
       description:
-        '`validated` (false when no integration manifest was found, so nothing was inspected), integration identity, structural issues, and classified Core doc relationships.',
+        '`validated` (false when no integration manifest was found, so nothing was inspected), integration identity, structural issues, classified Core doc relationships, `copiedPassages`, `fluff`, and `strayPointers`.',
     },
   ],
   examples: [
-    {label: 'Check the local integration', code: 'await integrationDocConflicts();'},
+    {
+      label: 'Check the local integration',
+      code: 'await integrationDocConflicts();',
+    },
   ],
   command: 'doctor integration docs',
   related: ['validateIntegration', 'docs'],