@cudoment/cudoc 0.3.0 → 0.5.0

package/dist/node/report.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Human-readable rendering of a {@link CheckResult}.
+ *
+ * Issues are grouped by document and carry source coordinates, so an editor or
+ * a terminal that linkifies `path:line:column` jumps straight to the reference.
+ */
+import type { CheckResult } from "./check.js";
+export declare function formatCheckResult(result: CheckResult): string;
+//# sourceMappingURL=report.d.ts.map

package/dist/node/report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.d.ts","sourceRoot":"","sources":["../../src/node/report.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAkB,MAAM,YAAY,CAAA;AAU7D,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CA6C7D"}

package/dist/node/report.js

@@ -0,0 +1,48 @@
+/**
+ * Human-readable rendering of a {@link CheckResult}.
+ *
+ * Issues are grouped by document and carry source coordinates, so an editor or
+ * a terminal that linkifies `path:line:column` jumps straight to the reference.
+ */
+/** How many real anchor names to show before summarising the rest. */
+const SHOWN_ANCHORS = 4;
+const location = (issue) => issue.position
+    ? `${issue.position.start.line}:${issue.position.start.column}`
+    : "";
+export function formatCheckResult(result) {
+    const errors = result.issues.filter((i) => i.severity === "error").length;
+    const warnings = result.issues.length - errors;
+    if (!result.issues.length)
+        return `checked ${result.checkedReferences} references in ${result.documentCount} documents; no problems found`;
+    const byDocument = new Map();
+    for (const issue of result.issues) {
+        const list = byDocument.get(issue.sourcePath) ?? [];
+        list.push(issue);
+        byDocument.set(issue.sourcePath, list);
+    }
+    const width = Math.max(...result.issues.map((issue) => location(issue).length));
+    const lines = [];
+    for (const [sourcePath, issues] of byDocument) {
+        lines.push(sourcePath);
+        for (const issue of issues) {
+            lines.push(`  ${location(issue).padStart(width)}  ${issue.severity.padEnd(7)} ${issue.code.padEnd(20)} ${issue.reference}`);
+            lines.push(`  ${" ".repeat(width)}  ${issue.message}`);
+            if (issue.available?.length) {
+                const shown = issue.available.slice(0, SHOWN_ANCHORS);
+                const rest = issue.available.length - shown.length;
+                lines.push(`  ${" ".repeat(width)}  available: ${shown.map((id) => `#${id}`).join(", ")}${rest > 0 ? ` (+${rest} more)` : ""}`);
+            }
+            else if (issue.available) {
+                lines.push(`  ${" ".repeat(width)}  available: none`);
+            }
+        }
+        lines.push("");
+    }
+    const counts = [
+        errors ? `${errors} error${errors === 1 ? "" : "s"}` : "",
+        warnings ? `${warnings} warning${warnings === 1 ? "" : "s"}` : "",
+    ].filter(Boolean);
+    lines.push(`${counts.join(", ")} in ${byDocument.size} of ${result.documentCount} documents`);
+    return lines.join("\n");
+}
+//# sourceMappingURL=report.js.map

package/dist/node/report.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.js","sourceRoot":"","sources":["../../src/node/report.ts"],"names":[],"mappings":"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"}

package/dist/node/resolve-embed.d.ts

@@ -7,12 +7,37 @@ export type Replacement = {
     regex?: boolean;
     flags?: string;
 };
+/**
+ * Where a table cell's text comes from.
+ *
+ * `title`, `summary` and `parent` read the row's section; the coordinate form
+ * reads one cell of one table inside it, counting tables after those whose
+ * header row names a heading in `skipTablesWithHeaders`; `extractor` names a
+ * function the collection config registered.
+ */
+export type CellValue = "title" | "summary" | "parent" | {
+    table?: number;
+    row: number;
+    column: number;
+    skipTablesWithHeaders?: string[];
+} | {
+    extractor: string;
+};
+/** Where a cell links to: the row's section, the heading above it, or its document. */
+export type CellLink = "section" | "parent" | "document";
+export type TableColumn = "title" | "link" | "summary" | {
+    header?: string;
+    value: CellValue;
+    link?: CellLink;
+    /** A CSS length written onto the header cell's `style` as `min-width`. */
+    minWidth?: string;
+};
 export type EmbedSpec = {
     sources: string[];
     select?: SectionSelection;
     render?: "section" | {
         type: "table";
-        columns?: ("title" | "link" | "summary")[];
+        columns?: TableColumn[];
     };
     replace?: Replacement[];
 };
@@ -20,11 +45,73 @@ export type EmbedContext = {
     documentId: string;
     prefix?: string;
 };
+/** What a cell shows: text, and a link when the column or extractor gives one. */
+export type ExtractedCell = {
+    text: string;
+    url?: string;
+};
+/** One row of an extracted table: the selected section and where it sits. */
+export type EmbedRow = {
+    document: StoredDocument;
+    section: {
+        anchorId?: string;
+        title: string;
+        tree: Root;
+    };
+    /** The nearest heading above the section that is shallower than it. */
+    parent?: {
+        title: string;
+        anchorId?: string;
+    };
+    /** The row section's own address. */
+    url: string;
+};
+/**
+ * A function the collection config registers to compute a cell. `version`
+ * enters the library configuration, so changing what the function returns
+ * for the same input invalidates prepared embeds.
+ */
+export type TableExtractor = {
+    version: string;
+    extract: (row: EmbedRow, context: {
+        library: Library;
+        documentId: string;
+        column: TableColumn;
+    }) => string | ExtractedCell | undefined;
+};
 export declare function parseEmbedSpec(value: string): EmbedSpec;
+/**
+ * Parses one fenced block, naming the document and block when it fails.
+ *
+ * A bare YAML error reads `Missing closing "quote at line 3, column 24` and
+ * stops there, which is a poor thing to hand an author: line 3 of which block
+ * of which document? Every caller that walks fenced blocks knows both, so the
+ * context is attached here instead of being repeated at each of them.
+ */
+export declare function parseEmbedBlock(value: string, documentId: string, number?: number): EmbedSpec;
 export declare function resolveDocumentReference(library: Library, reference: string, from: string): {
     document: StoredDocument;
     anchor?: string;
 };
+/** The default columns of a summary table, as they have always been. */
+export declare const DEFAULT_TABLE_COLUMNS: TableColumn[];
+/**
+ * One row for a selected section: what it is called, where it lives and which
+ * heading introduces the part of the document it sits in.
+ */
+export declare function buildEmbedRow(document: StoredDocument, anchorId: string | undefined, tree: Root): EmbedRow;
+/**
+ * The text and link one column shows for one row, and why it is empty when it
+ * is. The resolver renders the cell either way; the checker reports the
+ * problem, which is worded as what the column asked for and what the section
+ * has, so an author can tell a wrong coordinate from a missing table.
+ */
+export declare function extractCell(library: Library, column: TableColumn, row: EmbedRow, context: EmbedContext): {
+    cell: ExtractedCell;
+    problem?: string;
+};
+/** The mdast table the extracted cells make, header cells carrying any width. */
+export declare function buildEmbedTable(library: Library, columns: TableColumn[], rows: EmbedRow[], context: EmbedContext): Root;
 /** Resolve a configured embed from immutable persisted documents. */
 export declare function resolveEmbed(library: Library, input: EmbedSpec, context: EmbedContext): Root;
 export declare function resolveDocumentEmbeds(library: Library, documentId: string): Root;

package/dist/node/resolve-embed.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolve-embed.d.ts","sourceRoot":"","sources":["../../src/node/resolve-embed.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,OAAO,CAAA;AAGjC,OAAO,EAAmB,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AAGvE,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAE3D,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,KAAK,CAAC,EAAE,MAAM,CAAA;CACf,CAAA;AACD,MAAM,MAAM,SAAS,GAAG;IACtB,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,MAAM,CAAC,EAAE,gBAAgB,CAAA;IACzB,MAAM,CAAC,EACL,SAAS,GAAG;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC,OAAO,GAAG,MAAM,GAAG,SAAS,CAAC,EAAE,CAAA;KAAE,CAAA;IAC3E,OAAO,CAAC,EAAE,WAAW,EAAE,CAAA;CACxB,CAAA;AACD,MAAM,MAAM,YAAY,GAAG;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAA;AAElE,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CA2DvD;AAED,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,GACX;IAAE,QAAQ,EAAE,cAAc,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAwB/C;AAwLD,qEAAqE;AACrE,wBAAgB,YAAY,CAC1B,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,SAAS,EAChB,OAAO,EAAE,YAAY,GACpB,IAAI,CA8HN;AAED,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,OAAO,EAChB,UAAU,EAAE,MAAM,GACjB,IAAI,CAmBN;AAmDD,eAAO,MAAM,iBAAiB,GAC5B,SAAS,OAAO,EAChB,MAAM,SAAS,EACf,SAAS,YAAY,KACpB,OAAO,CAAC,IAAI,CAGZ,CAAA;AACH,eAAO,MAAM,0BAA0B,GACrC,SAAS,OAAO,EAChB,YAAY,MAAM,KACjB,OAAO,CAAC,IAAI,CAGZ,CAAA"}
+{"version":3,"file":"resolve-embed.d.ts","sourceRoot":"","sources":["../../src/node/resolve-embed.ts"],"names":[],"mappings":"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"}