@astryxdesign/cli 0.7.2-canary.fdd384f → 0.7.2

package/foundation/discovery/copied-passages.d.mts

@@ -0,0 +1,216 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * The number of distinct content words in a run: words that are not function
+ * words, with surrounding punctuation set aside.
+ *
+ * @param {{word: string}[]} words
+ * @param {number} start
+ * @param {number} length
+ */
+export function contentWords(words: {
+    word: string;
+}[], start: number, length: number): number;
+/**
+ * The words a passage is compared by: lowercase, with links and Markdown
+ * emphasis set aside. A token with no letter or digit (the `.` after a link)
+ * is not a word.
+ *
+ * @param {string} text
+ * @returns {string[]}
+ */
+export function passageWords(text: string): string[];
+/**
+ * Every word of a doc file, in order, with its 1-based line. Words are runs of
+ * letters and digits, so punctuation, code ticks, quotes and escapes in the
+ * source neither join nor split them.
+ *
+ * @param {string} source
+ * @returns {{word: string, line: number}[]}
+ */
+export function fileWords(source: string): {
+    word: string;
+    line: number;
+}[];
+/**
+ * The words of a string the way {@link fileWords} reads a file, each with its
+ * offset in the string.
+ *
+ * @param {string} text
+ * @returns {{word: string, at: number}[]}
+ */
+export function textWords(text: string): {
+    word: string;
+    at: number;
+}[];
+/**
+ * Where a string's whole run of words starts among a file's words, looking
+ * from `from` on, or -1.
+ *
+ * @param {{word: string}[]} file
+ * @param {{word: string}[]} words
+ * @param {number} [from]
+ * @returns {number}
+ */
+export function locateWords(file: {
+    word: string;
+}[], words: {
+    word: string;
+}[], from?: number): number;
+/**
+ * The file line of the character at offset `at` of a string whose words start
+ * at `index` among the file's words.
+ *
+ * @param {{line: number}[]} file
+ * @param {number} index
+ * @param {{at: number}[]} words the string's words
+ * @param {number} at
+ * @returns {number | null}
+ */
+export function lineAtOffset(file: {
+    line: number;
+}[], index: number, words: {
+    at: number;
+}[], at: number): number | null;
+/**
+ * A shared run with the boilerplate trimmed off its ends, judged window by
+ * window: every word a leading boilerplate window covers, and every word from
+ * the first trailing one on. A lead-in many topics open with thus never hides
+ * the copy after it. Null when less than {@link PASSAGE_WORDS} words are left.
+ *
+ * @param {{start: number, length: number}} run
+ * @param {(at: number) => boolean} boilerplate whether the window of
+ *   {@link PASSAGE_WORDS} words starting at `at` is boilerplate
+ * @returns {{start: number, length: number} | null}
+ */
+export function trimBoilerplate({ start, length }: {
+    start: number;
+    length: number;
+}, boilerplate: (at: number) => boolean): {
+    start: number;
+    length: number;
+} | null;
+/**
+ * The words of one string as passageWords reads them, each with where it sits
+ * in the string as written, so a passage can be quoted with its case,
+ * punctuation and code ticks.
+ *
+ * @param {string} text
+ * @returns {{word: string, start: number, end: number}[]}
+ */
+export function wordSpans(text: string): {
+    word: string;
+    start: number;
+    end: number;
+}[];
+/**
+ * Each prose string of a doc, in order, with the title of the section it is
+ * in (null before the first section). Code, examples, reference blocks, and
+ * identifier fields are left out.
+ *
+ * @param {unknown} doc an authored doc object
+ * @returns {{text: string, section: string | null}[]}
+ */
+export function proseStrings(doc: unknown): {
+    text: string;
+    section: string | null;
+}[];
+/**
+ * Each prose word of a doc, in order, with the title of the section it is in
+ * (null before the first section) and the number of the string it came from.
+ * A passage never runs from one string into the next, so two fields that
+ * happen to sit side by side are not read as one sentence.
+ *
+ * @param {unknown} doc an authored doc object
+ * @returns {{word: string, section: string | null, block: number}[]}
+ */
+export function proseWords(doc: unknown): {
+    word: string;
+    section: string | null;
+    block: number;
+}[];
+/**
+ * The runs of at least `size` words that both docs have, each inside one
+ * string of each doc, longest first, as its start in `mine` and its length.
+ *
+ * @param {{word: string, block?: number}[]} mine
+ * @param {{word: string, block?: number}[]} other
+ * @param {number} [size]
+ * @returns {{start: number, length: number}[]}
+ */
+export function sharedPassages(mine: {
+    word: string;
+    block?: number;
+}[], other: {
+    word: string;
+    block?: number;
+}[], size?: number): {
+    start: number;
+    length: number;
+}[];
+/**
+ * @param {string} file
+ * @returns {Promise<any>} the doc, or null for one that does not load (the
+ *   load problem is reported elsewhere)
+ */
+export function loadQuietly(file: string): Promise<any>;
+/** @returns {Promise<IndexedGuides>} the CLI's own guides, read and indexed once */
+export function loadCoreGuides(): Promise<IndexedGuides>;
+/**
+ * One entry for each pair of topics that repeat a passage word for word: two
+ * of the package's own topics, or one of them and a Core topic, except the
+ * Core topic it replaces (a replacement takes that topic's place, so it may
+ * carry its text).
+ *
+ * @param {{records: {name: string, path: string, replaces?: string | null, extendsTopic?: string | null}[], guides?: {name: string, ref?: {topicFile?: string}}[]}} discovered
+ *   the package's docs, as discoverIntegrationDocs returns them
+ * @returns {Promise<import('../../api/integration/authoring-checks.type.mjs').CopiedPassage[]>}
+ */
+export function findCopiedPassages(discovered: {
+    records: {
+        name: string;
+        path: string;
+        replaces?: string | null;
+        extendsTopic?: string | null;
+    }[];
+    guides?: {
+        name: string;
+        ref?: {
+            topicFile?: string;
+        };
+    }[];
+}): Promise<import("../../api/integration/authoring-checks.type.mjs").CopiedPassage[]>;
+/** The shortest run of identical words reported as a copy. */
+export const PASSAGE_WORDS: 10;
+/**
+ * A copy carries at least this many distinct content words, so a run of
+ * glue words ("and it is in the way that you can…") is a phrase, not a fact.
+ */
+export const MIN_CONTENT_WORDS: 4;
+/**
+ * A run that this many topics share is boilerplate, such as a lead-in every
+ * guide of a series opens with, not a copy of one topic's fact.
+ */
+export const BOILERPLATE_TOPICS: 3;
+export type GuideWords = {
+    name: string;
+    title?: string;
+    file?: string;
+    doc?: unknown;
+    words: {
+        word: string;
+        section: string | null;
+        block: number;
+    }[];
+    replaces: string | null;
+    extendsTopic?: string | null;
+};
+/**
+ * Guides with an index from each run of words to the guides that have it, so
+ * a topic is compared in full only with the guides it shares a run with.
+ */
+export type IndexedGuides = {
+    guides: GuideWords[];
+    index: Map<string, number[]>;
+};