@docsworth/cli 0.0.0-stage → 0.3.0

package/dist/core/printable.d.ts

@@ -0,0 +1,4 @@
+/** `text` with control and bidirectional characters written as escapes (`\x1b`, `\u202e`). */
+export declare function printable(text: string): string;
+/** `value` as JSON, every such character a `\u` escape: JSON.stringify leaves C1 and bidirectional ones as they are. */
+export declare function printableJson(value: unknown): string;

package/dist/core/printable.js

@@ -0,0 +1,16 @@
+// Text a page holds, made safe to print on a terminal: a decoded link, a frontmatter value or a
+// file name could carry escape sequences that clear or spoof a report, line breaks that fake
+// another line, or bidirectional overrides that reorder it.
+// C0 and C1 controls, Unicode's Bidi_Control set, and its line and paragraph separators.
+const UNPRINTABLE = /[\u0000-\u001f\u007f-\u009f\u061c\u200e\u200f\u2028\u2029\u202a-\u202e\u2066-\u2069]/g;
+// The same but C0, which JSON.stringify escapes inside strings and uses outside them (a newline).
+const UNPRINTABLE_IN_JSON = /[\u007f-\u009f\u061c\u200e\u200f\u2028\u2029\u202a-\u202e\u2066-\u2069]/g;
+const hex = (c, width) => c.charCodeAt(0).toString(16).padStart(width, "0");
+/** `text` with control and bidirectional characters written as escapes (`\x1b`, `\u202e`). */
+export function printable(text) {
+    return text.replace(UNPRINTABLE, (c) => (c.charCodeAt(0) < 0x100 ? `\\x${hex(c, 2)}` : `\\u${hex(c, 4)}`));
+}
+/** `value` as JSON, every such character a `\u` escape: JSON.stringify leaves C1 and bidirectional ones as they are. */
+export function printableJson(value) {
+    return JSON.stringify(value, null, 2).replace(UNPRINTABLE_IN_JSON, (c) => `\\u${hex(c, 4)}`);
+}

package/dist/core/references.d.ts

@@ -0,0 +1,87 @@
+import type { Page, Repo } from "./repo.js";
+/**
+ * HTML's named character references that hold an ASCII character: all 49 of them. Every
+ * other name stands for non-ASCII characters only. test/references.test.ts checks this
+ * table against the `entities` package.
+ */
+export declare const ASCII_REFERENCES: Readonly<Record<string, string>>;
+/**
+ * HTML's named references to invisible format characters only (soft hyphen, zero-width
+ * space and joiners, word joiner, bidi marks): all 17. The rendered view drops them.
+ * test/references.test.ts checks this list against the `entities` package.
+ */
+export declare const INVISIBLE_REFERENCES: ReadonlySet<string>;
+/** The pages `who` can't see, as a sweep reads names. Built once per repo and audience. */
+export interface PageNames {
+    /** The knowledge root, without a trailing slash. */
+    root: string;
+    /** Skeleton of each repo path → whether it's hidden (hidden wins a collision). */
+    paths: Map<string, boolean>;
+    /** The same for each path under the knowledge root, when it has two segments or more. */
+    under: Map<string, boolean>;
+    /** Skeletons of hidden pages' file names, by length. */
+    names: Map<number, Set<string>>;
+    /** For each such file name, the hidden pages' repo paths. */
+    spelled: Map<string, string[]>;
+    /** For each such file name, the hidden pages' paths under the root (two segments or more). */
+    spelledUnder: Map<string, string[]>;
+    /** The most segments in a repo path: a longer tail can't name one. */
+    depth: number;
+    /** The knowledge repo's URL prefixes on GitHub (`github.com/acme/knowledge/`), if it's there. */
+    repoUrls: string[];
+    /** Each page's one route on a docs site (`pageRoute`) → whether it's hidden (hidden wins a shared route). */
+    routes: Map<string, boolean>;
+    /** Hidden pages' paths under the root without `.md`: a link by a file's stem (`sec/1.0-release`). */
+    stems: Set<string>;
+    /** For each loaded page's repo path, the directories its URL reads a relative link from. */
+    urlDirs: Map<string, string[]>;
+    /** `site_url`'s host (port included), path prefix (no trailing slash), host name, and where that name starts a token's URL. */
+    site?: {
+        host: string;
+        prefix: string;
+        name: string;
+        at: RegExp;
+    };
+    /** Whether a repo path, as written (not folded), is a file or directory in the repo. */
+    exists: (repoPath: string) => boolean;
+    /** The same, folded as rendered text (`foldRendered`), for the rendered view. */
+    rendered?: PageNames;
+}
+export declare function pageNames(repo: Repo, hidden: (page: Page) => boolean): PageNames;
+/**
+ * Whether a link destination, as written on page `from`, leads to a hidden page: one
+ * that resolves to it, or a URL that ends with its path. A path under the knowledge root
+ * that is no loaded page fails closed: a page that didn't load has no trustworthy ACL.
+ * `html` for an attribute in raw HTML, where backslash escapes don't apply. `links`, the
+ * text's CommonMark links (`linkPaths`): a route naming nothing fails closed only where it's
+ * one of them (or an attribute's), not where only the liberal reading finds it (`[^1]: The
+ * note`, `[term]: word`); a hidden page's route hides it wherever it stands.
+ */
+export declare function destinationHides(dest: string, from: string, names: PageNames, html?: boolean, links?: ReadonlySet<string>): boolean;
+/** The paths of `text`'s links and images, as commonmark.js parses them (`commonmarkPath`). */
+export declare function linkPaths(text: string): Set<string>;
+/**
+ * CommonMark's link definitions in `text`, the first for each label (keyed as `normalLabel`
+ * keys a label) → its destination; undefined where commonmark.js doesn't say.
+ */
+export declare function definitionsIn(text: string): Map<string, string> | undefined;
+/**
+ * The lines of `text` holding a reference to one of `labels` (definitions that go): left, a
+ * reference shows its label as text, in whatever container (code review, round 1: `> [HSM]`
+ * over `> [HSM]: …`), or before a `:` (`[ref]:` that can't start a definition is one).
+ * Matched as CommonMark matches labels (case, runs of space, and space inside the brackets
+ * aside), anywhere on a line.
+ */
+export declare function labelLines(text: string, labels: Iterable<string>): Set<number>;
+/** A label as CommonMark compares labels: runs of space one space, case folded as Unicode folds it (`ß` is `SS`: code review, round 2). */
+export declare const normalLabel: (s: string) => string;
+/** The lines of `text`, on page `from`, that name a hidden page: see the module comment. */
+export declare function namingLines(text: string, from: string, names: PageNames, depth?: number, inherited?: string[], liberal?: boolean, gone?: Set<string>): Set<number>;
+/**
+ * The lines of `text` where `find`, run over each view the sweep reads (as prose and
+ * joined, with and without CommonMark's escapes, and as rendered), reports a span. For
+ * names that aren't paths: a mirrored page's id, say.
+ */
+export declare function linesWhere(text: string, find: (view: string, cased: string) => Iterable<[number, number]>, depth?: number, inherited?: string[]): Set<number>;
+/** `text` with each line in `lines` replaced by its container markers and `placeholder`. */
+export declare function replaceLines(text: string, lines: Set<number>, placeholder: string): string;