@astryxdesign/cli 0.7.2-canary.fe2c655 → 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
@@ -47,6 +178,14 @@ export type IntegrationTemplateConflictResponse = {
         issues: import("../../foundation/integrations/issue").AstryxIntegrationIssue[];
     };
 };
+/**
+ * Documented props compared with the component's TypeScript props. Present
+ * when the manifest loads and declares a components root. `status: 'skipped'`
+ * means nothing was compared (no TypeScript in the project) and `reason` says
+ * why. Every finding is a warning.
+ */
+export type PropDriftReport = import("../../foundation/discovery/prop-drift.mjs").PropDriftReport;
+export type PropDriftFinding = import("../../foundation/discovery/prop-drift.mjs").PropDriftFinding;
 export type IntegrationComponentConflictResponse = {
     type: "integration.component-conflicts";
     data: {
@@ -55,6 +194,7 @@ export type IntegrationComponentConflictResponse = {
         version: string | null;
         conflicts: IntegrationComponentConflict[];
         issues: import("../../foundation/integrations/issue").AstryxIntegrationIssue[];
+        propDrift?: PropDriftReport;
     };
 };
 export type IntegrationDocConflictResponse = {
@@ -64,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
@@ -58,16 +117,29 @@
  * @property {{validated: boolean, name: string | null, version: string | null, conflicts: IntegrationTemplateConflict[], issues: import('../../foundation/integrations/issue').AstryxIntegrationIssue[]}} data
  */
 
+/**
+ * Documented props compared with the component's TypeScript props. Present
+ * when the manifest loads and declares a components root. `status: 'skipped'`
+ * means nothing was compared (no TypeScript in the project) and `reason` says
+ * why. Every finding is a warning.
+ *
+ * @typedef {import('../../foundation/discovery/prop-drift.mjs').PropDriftReport} PropDriftReport
+ */
+
+/**
+ * @typedef {import('../../foundation/discovery/prop-drift.mjs').PropDriftFinding} PropDriftFinding
+ */
+
 /**
  * @typedef {object} IntegrationComponentConflictResponse
  * @property {'integration.component-conflicts'} type
- * @property {{validated: boolean, name: string | null, version: string | null, conflicts: IntegrationComponentConflict[], issues: import('../../foundation/integrations/issue').AstryxIntegrationIssue[]}} data
+ * @property {{validated: boolean, name: string | null, version: string | null, conflicts: IntegrationComponentConflict[], issues: import('../../foundation/integrations/issue').AstryxIntegrationIssue[], propDrift?: PropDriftReport}} data
  */
 
 /**
  * @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/check/check.d.mts

@@ -0,0 +1,96 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * The code a skipped comparison carries under `--strict`: its key in the
+ * check's result, in snake case, then `_skipped` (`propDrift` is
+ * `prop_drift_skipped`).
+ * @param {string} key
+ */
+export function skippedCode(key: string): string;
+/**
+ * Whether a value is a report a check carries beside its issues: a
+ * comparison with a `status` of `checked` or `skipped` and its `findings`.
+ * @param {unknown} value
+ * @returns {value is IntegrationCheckReport}
+ */
+export function isCheckReport(value: unknown): value is IntegrationCheckReport;
+/**
+ * Every warning in one check's result, and every piece of work it skipped,
+ * as issues: what `--strict` reports as errors. The counts come from the
+ * same list, so the default run and the strict run read the same data.
+ * @param {IntegrationCheckName} check
+ * @param {IntegrationCheckResponse} response
+ * @param {{noPackage?: boolean}} [context] `noPackage`: validate found no
+ *   package.json, which only it reports; then no other check names a
+ *   missing manifest as skipped work
+ * @returns {{warnings: Array<Omit<IntegrationCheckFailure, 'check' | 'severity'>>, skipped: Array<Omit<IntegrationCheckFailure, 'check' | 'severity'>>}}
+ */
+export function strictIssues(check: IntegrationCheckName, response: IntegrationCheckResponse, context?: {
+    noPackage?: boolean;
+}): {
+    warnings: Array<Omit<IntegrationCheckFailure, "check" | "severity">>;
+    skipped: Array<Omit<IntegrationCheckFailure, "check" | "severity">>;
+};
+/**
+ * Count one check's result the way its own subcommand exits. Errors are what
+ * make it exit 1: error-severity issues, and for `docs` error findings.
+ * Warnings are warning issues, conflicts and findings, and the findings of
+ * any report the check carries. Skipped names work that did not run: no
+ * integration manifest, or a report that was skipped.
+ * @param {IntegrationCheckResponse} response
+ * @param {{noPackage?: boolean}} [context] as {@link strictIssues} takes it
+ * @returns {Omit<IntegrationCheckResult, 'check' | 'response'>}
+ */
+export function summarizeCheck(response: IntegrationCheckResponse, context?: {
+    noPackage?: boolean;
+}): Omit<IntegrationCheckResult, "check" | "response">;
+/**
+ * Run every `doctor integration` check against the integration package in
+ * `cwd`, as its own build does, and return the `integration.check` envelope.
+ *
+ * @param {IntegrationCheckOptions} [options]
+ * @returns {Promise<IntegrationCheckCommandResponse>}
+ */
+export function integrationCheck(options?: IntegrationCheckOptions): Promise<IntegrationCheckCommandResponse>;
+/**
+ * Count the four checks' results into one summary. Each check's own row
+ * counts as its subcommand exits; the totals and `failures` count validate's
+ * issues once, though the other checks repeat them, and every other finding
+ * on its own, so two findings with one message stay two.
+ * @param {IntegrationCheckResponse[]} responses validate first
+ * @param {boolean} strict
+ */
+export function combineChecks(responses: IntegrationCheckResponse[], strict: boolean): {
+    checks: import("../integration-check.type.mjs").IntegrationCheckResult[];
+    errors: number;
+    warnings: number;
+    skipped: string[];
+    unchecked: number;
+    failures: import("../integration-check.type.mjs").IntegrationCheckFailure[];
+    failed: boolean;
+};
+/** @typedef {import('../integration-check.type.mjs').IntegrationCheckName} IntegrationCheckName */
+/** @typedef {import('../integration-check.type.mjs').IntegrationCheckReport} IntegrationCheckReport */
+/** @typedef {import('../integration-check.type.mjs').IntegrationCheckResponse} IntegrationCheckResponse */
+/** @typedef {import('../integration-check.type.mjs').IntegrationCheckResult} IntegrationCheckResult */
+/** @typedef {import('../integration-check.type.mjs').IntegrationCheckOptions} IntegrationCheckOptions */
+/** @typedef {import('../integration-check.type.mjs').IntegrationCheckCommandResponse} IntegrationCheckCommandResponse */
+/** @typedef {import('../integration-check.type.mjs').IntegrationCheckFailure} IntegrationCheckFailure */
+/** The checks `integration check` runs, in the order it runs them. */
+export const INTEGRATION_CHECKS: readonly ["validate", "components", "templates", "docs"];
+/** The skipped-work line for a package with no integration manifest. */
+export const NO_MANIFEST_SKIP: "No astryx.integration.* found next to package.json, so nothing was checked.";
+export namespace CONFLICT_CODES {
+    let components: "component_name_conflict";
+    let templates: "template_id_conflict";
+}
+/** The code a check with no integration manifest carries under `--strict`. */
+export const NO_MANIFEST_CODE: "missing_manifest";
+export type IntegrationCheckName = import("../integration-check.type.mjs").IntegrationCheckName;
+export type IntegrationCheckReport = import("../integration-check.type.mjs").IntegrationCheckReport;
+export type IntegrationCheckResponse = import("../integration-check.type.mjs").IntegrationCheckResponse;
+export type IntegrationCheckResult = import("../integration-check.type.mjs").IntegrationCheckResult;
+export type IntegrationCheckOptions = import("../integration-check.type.mjs").IntegrationCheckOptions;
+export type IntegrationCheckCommandResponse = import("../integration-check.type.mjs").IntegrationCheckCommandResponse;
+export type IntegrationCheckFailure = import("../integration-check.type.mjs").IntegrationCheckFailure;