@astryxdesign/cli 0.7.2-canary.fe2c655 → 0.7.2

package/api/integration/authoring-checks.mjs

@@ -3,6 +3,10 @@
 /**
  * @file Integration authoring diagnostics against the built-in Core catalog.
  *
+ * The components check also compares each component doc's props with the
+ * component's TypeScript props (foundation/discovery/prop-drift.mjs); those
+ * findings are warnings under `propDrift`.
+ *
  * Templates may intentionally replace Core identities; undeclared same-id
  * overlaps stay fail-closed and require package selection. The CLI package
  * version gates replacement-specific fields so 0.6.x keeps its released shape.
@@ -14,17 +18,25 @@
  * @position Public integration-authoring API over private discovery adapters.
  */
 
+import path from 'node:path';
 import {getCliInvocation} from '../../foundation/env/package-manager.mjs';
 import {
+  packageComponentLinkProblems,
   packageDocsProblems,
   packageReferenceProblems,
 } from '../docs/_adapter.mjs';
-import {findCoreDir} from '../../foundation/fs/paths.mjs';
+import {findProjectCoreDir} from '../../foundation/fs/paths.mjs';
 import {
   discoverIntegrationComponents,
   discoverOwnedComponents,
 } from '../../foundation/discovery/component-discovery.mjs';
 import {loadComponentReplacements} from '../component/_adapter.mjs';
+import {
+  integrationCopiedPassages,
+  integrationFluff,
+  integrationPropDrift,
+  integrationStrayPointers,
+} from './_adapter.mjs';
 import {
   discoverBuiltinTopics,
   discoverIntegrationDocs,
@@ -242,7 +254,24 @@ export async function integrationComponentConflicts(pkg, options = {}) {
     };
   }
 
-  const coreDir = findCoreDir(cwd);
+  // Each documented prop against the component's TypeScript props, read with
+  // the project's own compiler; without one the report says it was skipped.
+  const propDrift = await integrationPropDrift(resolved.integration, cwd);
+
+  // A link in a component doc's text reads as the command that opens its doc,
+  // as one in a topic does; one that names no doc prints as written, so it is
+  // a warning (spec:AST-047 FR9). The package's own topics are linkable.
+  const ownDocs = resolved.integration.docs
+    ? await discoverIntegrationDocs(resolved.integration)
+    : null;
+  for (const {severity, message} of await packageComponentLinkProblems(
+    resolved.integration,
+    ownDocs,
+  )) {
+    issues.push({code: 'invalid_doc_graph', severity, message});
+  }
+
+  const coreDir = findProjectCoreDir(cwd);
   if (!coreDir) {
     issues.push({
       code: 'core_not_found',
@@ -252,7 +281,7 @@ export async function integrationComponentConflicts(pkg, options = {}) {
     });
     return {
       type: 'integration.component-conflicts',
-      data: {validated, name, version, conflicts: [], issues},
+      data: {validated, name, version, conflicts: [], issues, propDrift},
     };
   }
 
@@ -296,7 +325,7 @@ export async function integrationComponentConflicts(pkg, options = {}) {
 
   return {
     type: 'integration.component-conflicts',
-    data: {validated, name, version, conflicts, issues},
+    data: {validated, name, version, conflicts, issues, propDrift},
   };
 }
 
@@ -314,10 +343,47 @@ export async function integrationDocConflicts(pkg, options = {}) {
   const version = resolved.found ? (resolved.version ?? null) : null;
   const issues = [...resolved.issues];
 
+  /** @type {import('./authoring-checks.type.mjs').CopiedPassage[]} */
+  const copiedPassages = [];
+  /** @type {import('./authoring-checks.type.mjs').DocFluff[]} */
+  const fluff = [];
+  /** @type {import('./authoring-checks.type.mjs').StrayPointer[]} */
+  const strayPointers = [];
+  // Like the other findings' `doc`, a fluff or stray-pointer `file` is
+  // relative to the package root.
+  const packageDir = /** @type {any} */ (resolved.integration)?.__packageDir;
+  const fromPackage = (/** @type {string} */ file) =>
+    typeof packageDir === 'string'
+      ? path.relative(packageDir, file).split(path.sep).join('/')
+      : file;
   if (!resolved.integration?.docs || name == null) {
+    // A package that ships components and no topics still has component docs
+    // a written pointer can sit in.
+    if (name != null && resolved.integration?.components) {
+      strayPointers.push(
+        ...(
+          await integrationStrayPointers(
+            {records: [], guides: []},
+            resolved.integration,
+          )
+        ).map(each => ({...each, file: fromPackage(each.file)})),
+      );
+      for (const {message} of strayPointers) {
+        issues.push({code: 'stray_doc_pointer', severity: 'warning', message});
+      }
+    }
     return {
       type: 'integration.doc-conflicts',
-      data: {validated, name, version, findings: [], issues},
+      data: {
+        validated,
+        name,
+        version,
+        findings: [],
+        copiedPassages,
+        fluff,
+        strayPointers,
+        issues,
+      },
     };
   }
 
@@ -407,10 +473,48 @@ export async function integrationDocConflicts(pkg, options = {}) {
     )) {
       issues.push({code: 'invalid_doc_reference', severity: 'error', message});
     }
+
+    // One fact has one owner: a passage two topics repeat goes stale in one
+    // of them. Each is listed and is a warning (architecture:cli-surface
+    // DEC-8), so `integration check --strict` fails until it is fixed;
+    // `doctor integration docs` keeps its exit code, as it fails on errors.
+    copiedPassages.push(...(await integrationCopiedPassages(discovered)));
+    for (const {message} of copiedPassages) {
+      issues.push({code: 'copied_passage', severity: 'warning', message});
+    }
+    // Docs should be dense: padding phrases and mostly-glue topics, listed
+    // and warned about the same way (DEC-8).
+    fluff.push(
+      ...(await integrationFluff(discovered)).map(each => ({
+        ...each,
+        file: fromPackage(each.file),
+      })),
+    );
+    for (const {message} of fluff) {
+      issues.push({code: 'doc_fluff', severity: 'warning', message});
+    }
+    // A pointer to a doc is a link, so doctor checks it (DEC-8).
+    strayPointers.push(
+      ...(await integrationStrayPointers(discovered, resolved.integration)).map(
+        each => ({...each, file: fromPackage(each.file)}),
+      ),
+    );
+    for (const {message} of strayPointers) {
+      issues.push({code: 'stray_doc_pointer', severity: 'warning', message});
+    }
   }
 
   return {
     type: 'integration.doc-conflicts',
-    data: {validated, name, version, findings, issues},
+    data: {
+      validated,
+      name,
+      version,
+      findings,
+      copiedPassages,
+      fluff,
+      strayPointers,
+      issues,
+    },
   };
 }