@astryxdesign/cli 0.7.2-canary.fdd384f → 0.7.2

package/api/integration/authoring-checks.type.d.mts

@@ -32,6 +32,137 @@ export type IntegrationDocFinding = {
     coreTopic: string;
     message: string;
 };
+/**
+ * A passage two topics repeat word for word: two of the package's own topics,
+ * or one of them and a Core topic (never the Core topic it replaces). Only
+ * prose counts, and only a run of 10 or more identical words, so each entry
+ * is a real copy. Each is also a `copied_passage` warning, so
+ * `integration check --strict` fails on it (architecture:cli-surface DEC-8).
+ */
+export type CopiedPassage = {
+    /**
+     * the package topic to change: it repeats the passage
+     */
+    topic: string;
+    /**
+     * the title of the section the passage starts in
+     */
+    section: string | null;
+    /**
+     * the file line where the passage starts in `topic`, or null
+     */
+    line: number | null;
+    /**
+     * the topic that also has it
+     */
+    otherTopic: string;
+    /**
+     * the topic that should keep the text: a Core topic, or of two package topics the one it fits
+     */
+    owner: string;
+    /**
+     * the passage as `topic` writes it: what to replace
+     */
+    text: string;
+    /**
+     * whether that topic is the package's own or Core's
+     */
+    otherOwner: "package" | "core";
+    /**
+     * the length of the longest shared run, in words
+     */
+    words: number;
+    /**
+     * how many separate runs the two topics share
+     */
+    passages: number;
+    /**
+     * what is repeated, and the exact fix: the passage in `topic` replaced by a link to `owner`
+     */
+    message: string;
+};
+/**
+ * Fluff in a topic's prose: a padding phrase (`kind: 'phrase'`, with the
+ * phrase, its section, and the file line where it was found), or a topic of
+ * 80 or more prose words of which fewer than half are content words
+ * (`kind: 'density'`, with the share). Each is also a `doc_fluff` warning, so
+ * `integration check --strict` fails on it (architecture:cli-surface DEC-8).
+ */
+export type DocFluff = {
+    topic: string;
+    kind: "phrase" | "density";
+    /**
+     * the padding phrase, for `kind: 'phrase'`
+     */
+    phrase: string | null;
+    /**
+     * the title of the section it is in
+     */
+    section: string | null;
+    /**
+     * the doc file, relative to the package root
+     */
+    file: string;
+    /**
+     * the file line that holds the phrase, when one line does
+     */
+    line: number | null;
+    /**
+     * the share of content words, for `kind: 'density'`
+     */
+    density: number | null;
+    /**
+     * what to cut or write instead
+     */
+    message: string;
+};
+/**
+ * A code span in prose that is exactly `astryx docs <name>` for a doc that
+ * exists, where the doc's `{@link generic :<name>}` would be checked. Each is
+ * also a `stray_doc_pointer` warning, so `integration check --strict` fails on
+ * it (architecture:cli-surface DEC-8).
+ */
+export type StrayPointer = {
+    /**
+     * the package topic, or component doc, that has it
+     */
+    topic: string;
+    /**
+     * whether it sits in a topic or a
+     * component doc
+     */
+    kind: "topic" | "component";
+    /**
+     * the title of the section it is in
+     */
+    section: string | null;
+    /**
+     * the field it is in outside any section: a
+     * topic's `description` or `summary`, or a component doc's field path, such
+     * as `usage.bestPractices[0].description`
+     */
+    field: string | null;
+    /**
+     * the doc file, relative to the package root
+     */
+    file: string;
+    /**
+     * the file line that holds it, when found
+     */
+    line: number | null;
+    /**
+     * the written command, `astryx docs <name>`
+     */
+    pointer: string;
+    /**
+     * the link that replaces it
+     */
+    link: string;
+    /**
+     * the exact replacement
+     */
+    message: string;
+};
 /**
  * Each of the three authoring checks reports `validated`: false means no
  * integration manifest was found, so nothing was inspected and the empty
@@ -73,6 +204,9 @@ export type IntegrationDocConflictResponse = {
         name: string | null;
         version: string | null;
         findings: IntegrationDocFinding[];
+        copiedPassages: CopiedPassage[];
+        fluff: DocFluff[];
+        strayPointers: StrayPointer[];
         issues: import("../../foundation/integrations/issue").AstryxIntegrationIssue[];
     };
 };

package/api/integration/authoring-checks.type.mjs

@@ -48,6 +48,65 @@
  * @property {string} message
  */
 
+/**
+ * A passage two topics repeat word for word: two of the package's own topics,
+ * or one of them and a Core topic (never the Core topic it replaces). Only
+ * prose counts, and only a run of 10 or more identical words, so each entry
+ * is a real copy. Each is also a `copied_passage` warning, so
+ * `integration check --strict` fails on it (architecture:cli-surface DEC-8).
+ *
+ * @typedef {object} CopiedPassage
+ * @property {string} topic the package topic to change: it repeats the passage
+ * @property {string | null} section the title of the section the passage starts in
+ * @property {number | null} line the file line where the passage starts in `topic`, or null
+ * @property {string} otherTopic the topic that also has it
+ * @property {string} owner the topic that should keep the text: a Core topic, or of two package topics the one it fits
+ * @property {string} text the passage as `topic` writes it: what to replace
+ * @property {'package' | 'core'} otherOwner whether that topic is the package's own or Core's
+ * @property {number} words the length of the longest shared run, in words
+ * @property {number} passages how many separate runs the two topics share
+ * @property {string} message what is repeated, and the exact fix: the passage in `topic` replaced by a link to `owner`
+ */
+
+/**
+ * Fluff in a topic's prose: a padding phrase (`kind: 'phrase'`, with the
+ * phrase, its section, and the file line where it was found), or a topic of
+ * 80 or more prose words of which fewer than half are content words
+ * (`kind: 'density'`, with the share). Each is also a `doc_fluff` warning, so
+ * `integration check --strict` fails on it (architecture:cli-surface DEC-8).
+ *
+ * @typedef {object} DocFluff
+ * @property {string} topic
+ * @property {'phrase' | 'density'} kind
+ * @property {string | null} phrase the padding phrase, for `kind: 'phrase'`
+ * @property {string | null} section the title of the section it is in
+ * @property {string} file the doc file, relative to the package root
+ * @property {number | null} line the file line that holds the phrase, when one line does
+ * @property {number | null} density the share of content words, for `kind: 'density'`
+ * @property {string} message what to cut or write instead
+ */
+
+/**
+ * A code span in prose that is exactly `astryx docs <name>` for a doc that
+ * exists, where the doc's `{@link generic:<name>}` would be checked. Each is
+ * also a `stray_doc_pointer` warning, so `integration check --strict` fails on
+ * it (architecture:cli-surface DEC-8).
+ *
+ * @typedef {object} StrayPointer
+ * @property {string} topic the package topic, or component doc, that has it
+ * @property {'topic' | 'component'} kind whether it sits in a topic or a
+ *   component doc
+ * @property {string | null} section the title of the section it is in
+ * @property {string | null} field the field it is in outside any section: a
+ *   topic's `description` or `summary`, or a component doc's field path, such
+ *   as `usage.bestPractices[0].description`
+ * @property {string} file the doc file, relative to the package root
+ * @property {number | null} line the file line that holds it, when found
+ * @property {string} pointer the written command, `astryx docs <name>`
+ * @property {string} link the link that replaces it
+ * @property {string} message the exact replacement
+ */
+
 /**
  * Each of the three authoring checks reports `validated`: false means no
  * integration manifest was found, so nothing was inspected and the empty
@@ -80,7 +139,7 @@
 /**
  * @typedef {object} IntegrationDocConflictResponse
  * @property {'integration.doc-conflicts'} type
- * @property {{validated: boolean, name: string | null, version: string | null, findings: IntegrationDocFinding[], issues: import('../../foundation/integrations/issue').AstryxIntegrationIssue[]}} data
+ * @property {{validated: boolean, name: string | null, version: string | null, findings: IntegrationDocFinding[], copiedPassages: CopiedPassage[], fluff: DocFluff[], strayPointers: StrayPointer[], issues: import('../../foundation/integrations/issue').AstryxIntegrationIssue[]}} data
  */
 
 export {};

package/api/integration/integrationCheck.doc.mjs

@@ -42,7 +42,7 @@ export const doc = {
       type: 'boolean',
       default: 'false',
       description:
-        'Also fail on any warning and on any check that did not run, not only on errors.',
+        '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: [

package/api/integration/integrationComponentConflicts.doc.mjs

@@ -17,8 +17,12 @@ export const doc = {
     "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. ' +
+    "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`: a documented prop the code lacks, a " +
+    "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`), ' +
@@ -50,14 +54,18 @@ export const doc = {
     '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. 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`, severity: `warning`, message, doc, source, docType?, codeType?, docRequired?, codeRequired?}), `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).',
+        "`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: [

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'],