@rse/specbook 1.3.1 → 1.4.0

package/dst/specbook-format.yaml

@@ -267,6 +267,7 @@
                 states a fact or event, not a decision (a deliberate exclusion is the `SCOPE` of
                 the Solution Vision or a `WONT` requirement instead).
             format:
+                type: compact
                 maxTableColumns: 5
             props:
                 -   name: TYPE
@@ -341,6 +342,7 @@
                 term from its siblings (e.g. `A Message submitted by an Attendee as ...`), so that
                 the hierarchy and the definitions cross-check each other.
             format:
+                type: compact
                 maxTableColumns: 5
             referenced:
                 -   "[[*]]"
@@ -352,8 +354,9 @@
                 labeled: true
                 qualified: true
                 config:
-                    size-node-width-max: 440
+                    size-node-width-max:    440
                     size-node-height-scale: 1.75
+                    hub-node-count-max:     3
             props:
                 -   name: TYPE
                     desc: >
@@ -661,6 +664,17 @@
                 maxTableColumns: 6
             referenced:
                 -   "[[USE-CASE:*]]"
+            diagram:
+                type: hub
+                center: self
+                nodes: "[[FR.REQUIREMENT:*]], [[NR.REQUIREMENT:*]], [[PREMISE:*]], [[RULE:*]],
+                    [[USE-CASE:*]], [[DM.ENTITY:*]], [[FV.COMPONENT:*]], [[TEST-CASE:*]]"
+                labeled: true
+                qualified: true
+                config:
+                    size-node-width-max: 440
+                    size-node-height-scale: 1.75
+                    hub-node-count-max: 3
             props:
                 -   name: PRIORITY
                     desc: >
@@ -734,6 +748,7 @@
                 config:
                     size-node-width-max: 440
                     size-node-height-scale: 1.75
+                    hub-node-count-max: 3
             props:
                 -   name: PRIORITY
                     desc: >
@@ -827,6 +842,18 @@
                 maxTableColumns: 5
             referenced:
                 -   "[[TEST-CASE:*]]"
+            diagram:
+                type: hub
+                center: self
+                nodes: "[[RULE:*]], [[TERM:*]], [[FR.REQUIREMENT:*]], [[NR.REQUIREMENT:*]],
+                    [[PREMISE:*]], [[WORKFLOW:*]], [[HANDOFF:*]], [[USE-CASE:*]], [[TRANSITION:*]],
+                    [[PERMISSION:*]], [[TEST-CASE:*]]"
+                labeled: true
+                qualified: true
+                config:
+                    size-node-width-max: 440
+                    size-node-height-scale: 1.75
+                    hub-node-count-max: 3
             props:
                 -   name: CATEGORY
                     desc: >
@@ -1599,7 +1626,19 @@
                 roles against entities. Any operation, state, or condition not covered by a
                 permission of the role (or of a role it `INHERITS`) is forbidden.
             format:
+                type: compact
                 maxTableColumns: 8
+            diagram:
+                type: hub
+                center: self
+                nodes: "[[PERMISSION:*]], [[ROLE:*]], [[DM.ENTITY:*]], [[STATE:*]], [[TRANSITION:*]],
+                    [[RULE:*]], [[USE-CASE:*]], [[SCENARIO:*]], [[ENDPOINT:*]], [[TEST-CASE:*]]"
+                labeled: true
+                qualified: true
+                config:
+                    size-node-width-max: 440
+                    size-node-height-scale: 1.75
+                    hub-node-count-max: 3
             props:
                 -   name: ROLE
                     desc: >
@@ -2188,12 +2227,14 @@
                 it rejects is its `TRADE-OFF`), and is not verifiable by a metric (a measurable
                 quality bound is a Non-Functional Requirement instead).
             referenced:
-                -   "[[PATTERN:*]]"
+                -   "[[DIALOG-PATTERN:*]]"
+            format:
+                type: compact
             diagram:
                 type: hub
                 center: self
                 nodes: "[[PRINCIPLE:*]], [[PERSONA:*]], [[STEP:*]], [[USE-CASE:*]], [[CONVENTION:*]],
-                    [[PATTERN:*]], [[ELEMENT:*]], [[DECISION:*]]"
+                    [[DIALOG-PATTERN:*]], [[ELEMENT:*]], [[DECISION:*]]"
                 labeled: true
                 qualified: true
                 config:
@@ -2284,6 +2325,18 @@
                 solution phrases what it says, not what it does (a behavior is an Interaction
                 Concept principle instead) and not what a term means (a definition is a Domain
                 Glossary term instead).
+            format:
+                type: compact
+            diagram:
+                type: hub
+                center: self
+                nodes: "[[CONVENTION:*]], [[PERSONA:*]], [[PRINCIPLE:*]], [[TERM:*]], [[DECISION:*]]"
+                labeled: true
+                qualified: true
+                config:
+                    size-node-width-max: 440
+                    size-node-height-scale: 1.75
+                    hub-node-count-max: 3
             props:
                 -   name: CATEGORY
                     desc: >
@@ -2338,7 +2391,7 @@
     optional: true
     diagram:
         type: grid
-        nodes: "[[PATTERN:*]]"
+        nodes: "[[DIALOG-PATTERN:*]]"
         properties:
             -   CATEGORY
         config:
@@ -2346,7 +2399,7 @@
             size-node-height-scale: 2
             grid-columns-max: 4
     children:
-        -   kind: PATTERN
+        -   kind: DIALOG-PATTERN
             desc: >
                 A single reusable dialog pattern, named with a short (2-5 word) summary (e.g.
                 `Master-Detail`, `Wizard`, `Inline Edit`) and described in a concise (1-3 sentence)
@@ -2360,7 +2413,7 @@
             diagram:
                 type: hub
                 center: self
-                nodes: "[[PATTERN:*]], [[PRINCIPLE:*]], [[STORYBOARD:*]], [[DECISION:*]]"
+                nodes: "[[DIALOG-PATTERN:*]], [[PRINCIPLE:*]], [[STORYBOARD:*]], [[DECISION:*]]"
                 deep: true
                 labeled: true
                 qualified: true
@@ -2405,7 +2458,7 @@
                         pattern is composed of (e.g. a `Master-Detail` using an `Inline Edit` in
                         its detail), so that the patterns form a language of related structures
                         rather than a flat catalogue.
-                    value: list([[PATTERN:*]])
+                    value: list([[DIALOG-PATTERN:*]])
                     optional: true
                 -   name: TRADE-OFF
                     desc: >
@@ -2450,7 +2503,7 @@
             diagram:
                 type: hub
                 center: self
-                nodes: "[[STORYBOARD:*]], [[PERSONA:*]], [[SCENARIO:*]], [[PATTERN:*]], [[MOCKUP:*]]"
+                nodes: "[[STORYBOARD:*]], [[PERSONA:*]], [[SCENARIO:*]], [[DIALOG-PATTERN:*]], [[MOCKUP:*]]"
                 deep: true
                 labeled: true
                 qualified: true
@@ -2502,7 +2555,7 @@
                                 Comma-separated references to the DIALOG-PATTERNS objects the frame
                                 instantiates, so that a pattern is shown to recur across the
                                 concrete flows rather than merely being catalogued.
-                            value: list([[PATTERN:*]])
+                            value: list([[DIALOG-PATTERN:*]])
                             optional: true
                         -   name: SKETCH
                             desc: >
@@ -2559,6 +2612,7 @@
                 list of token values (the values are in the design system) or a measurable bound
                 (a bound is a Non-Functional Requirement instead).
             format:
+                type: compact
                 maxTableColumns: 5
             diagram:
                 type: hub
@@ -2568,6 +2622,7 @@
                 qualified: true
                 config:
                     size-node-width-max: 440
+                    hub-node-count-max: 3
             props:
                 -   name: CATEGORY
                     desc: >
@@ -2617,6 +2672,15 @@
                 applied rather than stating them (a rule is an `ELEMENT` instead).
             format:
                 type: complex
+            diagram:
+                type: hub
+                center: self
+                nodes: "[[MOCKUP:*]], [[PERSONA:*]], [[STORYBOARD:*]], [[ELEMENT:*]]"
+                labeled: true
+                qualified: true
+                config:
+                    size-node-width-max: 440
+                    hub-node-count-max: 3
             props:
                 -   name: ACTORS
                     desc: >
@@ -2691,6 +2755,7 @@
                 Deployment View node instead -- only a party or system the solution merely consumes
                 or serves belongs to the system context.
             format:
+                type: compact
                 maxTableColumns: 5
             props:
                 -   name: KIND
@@ -2808,12 +2873,14 @@
                 with the components it depends on, plus a 1-sentence rationale ("why") for the
                 component's existence and boundary.
             format:
+                type: compact
                 maxTableColumns: 5
             diagram:
                 type: hub
                 center: self
                 nodes: "[[FV.COMPONENT:*]], [[FR.REQUIREMENT:*]], [[INTERFACE:*]], [[DM.ENTITY:*]],
-                    [[UNIT:*]], [[NODE:*]], [[CONCERN:*]], [[TACTIC:*]], [[DECISION:*]]"
+                    [[UNIT:*]], [[NODE:*]], [[CONCERN:*]], [[TACTIC:*]], [[DECISION:*]],
+                    [[CODE-PATTERN:*]]"
                 labeled: true
                 qualified: true
                 properties:
@@ -2821,6 +2888,7 @@
                 config:
                     size-node-width-max:    440
                     size-node-height-scale: 1.75
+                    hub-node-count-max:     3
             props:
                 -   name: KIND
                     desc: |
@@ -2950,11 +3018,13 @@
                         carrying trade-off behind the choice is a Design Decisions decision
                         referencing the component through `DECIDES`, and the functional components
                         depending on the product reference it through `USED-BY`.
+                    format:
+                        type: compact
                     diagram:
                         type: hub
                         center: self
                         nodes: "[[TS.TIER:*.COMPONENT:*]], [[FV.COMPONENT:*]], [[CONCERN:*]],
-                            [[TACTIC:*]], [[DECISION:*]]"
+                            [[TACTIC:*]], [[DECISION:*]], [[CODE-PATTERN:*]]"
                         labeled: true
                         qualified: true
                         properties:
@@ -2963,6 +3033,7 @@
                         config:
                             size-node-width-max:    440
                             size-node-height-scale: 1.75
+                            hub-node-count-max:     3
                     props:
                         -   name: PRODUCT
                             desc: >
@@ -3276,9 +3347,11 @@
                 process: it names no concrete products (a Technology Stack `Build-Time` component
                 states the product choice), does not restate the runtime structure (a Functionality
                 View `Module` or `Subsystem` groups the logic), does not cover production
-                procedures (an Operations View concern does), and the trade-off that produced a
-                rule is a Design Decisions decision referencing the aspect through `AFFECTS`,
-                while the quality the rule protects (usually a `Maintainability` requirement) is
+                procedures (an Operations View concern does), does not prescribe how a concern is
+                coded (a Code Patterns pattern shows that as a listing), and the trade-off that
+                produced a rule is a Design Decisions decision referencing the aspect through
+                `AFFECTS`, while the quality the rule protects (usually a `Maintainability`
+                requirement) is
                 addressed by a Quality Perspectives tactic referencing the aspect through
                 `AFFECTS`, too, so the hub diagram of an aspect shows the decision and the tactic
                 behind it.
@@ -3353,6 +3426,7 @@
                 config:
                     size-node-width-max:    440
                     size-node-height-scale: 1.75
+                    hub-node-count-max:     3
             props:
                 -   name: KIND
                     desc: |
@@ -3455,6 +3529,7 @@
                 config:
                     size-node-width-max:    440
                     size-node-height-scale: 1.75
+                    hub-node-count-max:     3
             props:
                 -   name: PART-OF
                     desc: >
@@ -3534,6 +3609,7 @@
                 config:
                     size-node-width-max:    440
                     size-node-height-scale: 1.75
+                    hub-node-count-max:     3
             props:
                 -   name: KIND
                     desc: |
@@ -3629,6 +3705,7 @@
                 config:
                     size-node-width-max:    440
                     size-node-height-scale: 1.75
+                    hub-node-count-max:     3
             props:
                 -   name: SCOPE
                     desc: |
@@ -3700,6 +3777,7 @@
                 config:
                     size-node-width-max:    440
                     size-node-height-scale: 1.75
+                    hub-node-count-max:     3
             props:
                 -   name: CATEGORY
                     desc: |
@@ -3801,16 +3879,20 @@
                 Design Decisions decision referencing the tactic through `DECIDES`, the product
                 realizing the mechanism is a Technology Stack component referenced through
                 `TOOLS`, the developer-facing rule about the source structure is an aspect of the
-                Development Aspects, and a mechanism driven solely by a `Constraint` requirement
+                Development Aspects, the coded form of the mechanism is a Code Patterns pattern
+                referencing the tactic through `REALIZES`, and a mechanism driven solely by a
+                `Constraint` requirement
                 (e.g. a hosting or budget mandate) protects no quality and is a Design Decisions
                 decision alone -- only the mechanism, the quality it achieves, and the elements it
                 shapes belong here.
+            format:
+                type: compact
             diagram:
                 type: hub
                 center: self
                 nodes: "[[TACTIC:*]], [[NR.REQUIREMENT:*]], [[FV.COMPONENT:*]], [[UNIT:*]],
                     [[ASPECT:*]], [[NODE:*]], [[DM.ENTITY:*]], [[CONCERN:*]], [[DECISION:*]],
-                    [[TS.TIER:*.COMPONENT:*]], [[TEST-CASE:*]]"
+                    [[TS.TIER:*.COMPONENT:*]], [[CODE-PATTERN:*]], [[TEST-CASE:*]]"
                 labeled: true
                 qualified: true
                 properties:
@@ -3885,9 +3967,10 @@
     file: 30-ARCH-DD-Design-Decisions.md
     desc: >
         The major decisions related to the solution design, each recording the forces at play, the
-        chosen response, and the reasoning that justifies it. The artifact is the last one of the
-        architecture, as a decision references the requirements forcing it, the elements it
-        shapes, and the tactics and products it chose, all of which precede it.
+        chosen response, and the reasoning that justifies it. The artifact is the last
+        decision-level one of the architecture, as a decision references the requirements forcing
+        it, the elements it shapes, and the tactics and products it chose, all of which precede
+        it, while the Code Patterns following it reference the decisions they implement.
     optional: true
     refs: >
         -   Nygard: Documenting Architecture Decisions (2011),
@@ -3963,15 +4046,17 @@
                 decision is under-justified. The rationale should make the decision feel earned,
                 not asserted - if you delete the rationale and the decision suddenly looks
                 arbitrary, the rationale was doing its job.
+            format:
+                type: complex
             diagram:
                 type: hub
                 center: self
                 nodes: "[[DECISION:*]], [[NR.REQUIREMENT:*]], [[PREMISE:*]], [[DM.ENTITY:*]],
                     [[LIFECYCLE:*]], [[ROLE:*]], [[INTERFACE:*]], [[TYPE:*]], [[ENDPOINT:*]],
-                    [[PRINCIPLE:*]], [[CONVENTION:*]], [[PATTERN:*]], [[STORYBOARD:*]],
+                    [[PRINCIPLE:*]], [[CONVENTION:*]], [[DIALOG-PATTERN:*]], [[STORYBOARD:*]],
                     [[ELEMENT:*]], [[CV.ENTITY:*]], [[FV.COMPONENT:*]], [[UNIT:*]], [[ASPECT:*]],
                     [[DV.TIER:*]], [[AREA:*]], [[NODE:*]], [[NETWORK:*]], [[TACTIC:*]],
-                    [[TS.TIER:*.COMPONENT:*]]"
+                    [[TS.TIER:*.COMPONENT:*]], [[CODE-PATTERN:*]]"
                 labeled: true
                 qualified: true
                 properties:
@@ -4019,7 +4104,7 @@
                         integrated); omitted for a decision shaping no modeled element.
                     value: list([[DM.ENTITY:*]], [[LIFECYCLE:*]], [[ROLE:*]], [[INTERFACE:*]],
                         [[TYPE:*]], [[ENDPOINT:*]], [[PRINCIPLE:*]], [[CONVENTION:*]],
-                        [[PATTERN:*]], [[STORYBOARD:*]], [[ELEMENT:*]], [[CV.ENTITY:*]],
+                        [[DIALOG-PATTERN:*]], [[STORYBOARD:*]], [[ELEMENT:*]], [[CV.ENTITY:*]],
                         [[FV.COMPONENT:*]], [[UNIT:*]], [[ASPECT:*]], [[DV.TIER:*]], [[AREA:*]],
                         [[NODE:*]], [[NETWORK:*]])
                     optional: true
@@ -4115,10 +4200,123 @@
                             matrix of considered alternatives); and
                         -   links to strongly related decisions.
                     optional: true
+
+-   kind: ARCH
+    name: Code Patterns
+    id: CP
+    file: 31-ARCH-CP-Code-Patterns.md
+    desc: >
+        The implementation patterns the source code of the solution follows, each prescribing how
+        one recurring concern (e.g. authorization enforcement, entity persistence, error
+        propagation) is coded and showing it as a code listing. The artifact follows the Design
+        Decisions, as a pattern is the coded form of the tactics and decisions preceding it, and
+        is absent when the coding conventions are governed outside the specification (e.g. by
+        repository-level contributor instructions).
+    optional: true
+    refs: >
+        -   Starke/Hruschka: arc42 Template: Crosscutting Concepts (2005),
+            https://arc42.org/overview
+        -   Fowler: Patterns of Enterprise Application Architecture (2002),
+            https://martinfowler.com/books/eaa.html
+        -   Beck: Implementation Patterns (2007),
+            https://www.informit.com/store/implementation-patterns-9780321413093
+    diagram:
+        type: grid
+        nodes: "[[CODE-PATTERN:*]]"
+        config:
+            size-node-width-max: 440
+            grid-columns-max: 4
+    children:
+        -   kind: CODE-PATTERN
+            desc: >
+                A single code pattern, named with a short (2-5 word) summary of the concern it
+                codes (e.g. `Endpoint Authorization`, `Entity Persistence`, `Error Propagation`)
+                and described in a concise (1-3 sentence) paragraph by the rule the code follows
+                whenever the concern arises, plus a 1-sentence rationale ("why") for the rule.
+
+                The listing showing the pattern follows the description and its rationale as the
+                elaboration of the pattern: either a fenced code block in the language of the
+                pattern (e.g. ` ```ts start=10 mark=3-5 `, the parameters numbering the lines
+                from `start` and marking the essential ones) or an embedded excerpt of an existing
+                source file (e.g. `![Entity Persistence](src/persistence.ts#lines=10-30&mark=3-5)`,
+                the fragment selecting and marking the lines), the latter preferred once the code
+                exists, as the specification then never drifts from it. The listing is the
+                canonical, idealized form of the pattern, not an exhaustive example, so it is kept
+                short (typically 10-30 lines) and the prose names what the listing cannot: the
+                places the pattern applies and the deviation it rules out (`AVOID`).
+
+                A pattern states how a concern is coded, and nothing else: the quality mechanism
+                it implements is a Quality Perspectives tactic referenced through `REALIZES`, the
+                trade-off that chose its approach over alternatives is a Design Decisions decision
+                referenced through `DECIDED-BY` (a pattern weighs no alternatives itself), the
+                product it codes against is a Technology Stack component referenced through
+                `TOOLS`, and the rule about the source layout, build, or process it lives in is a
+                Development Aspects aspect -- only the recurring code shape, the elements written
+                that way, and the deviation ruled out belong here.
+            format:
+                type: complex
+            diagram:
+                type: hub
+                center: self
+                nodes: "[[CODE-PATTERN:*]], [[FV.COMPONENT:*]], [[UNIT:*]], [[DM.ENTITY:*]],
+                    [[ROLE:*]], [[INTERFACE:*]], [[ENDPOINT:*]], [[TS.TIER:*.COMPONENT:*]],
+                    [[TACTIC:*]], [[DECISION:*]]"
+                labeled: true
+                qualified: true
+                config:
+                    size-node-width-max: 440
+            props:
+                -   name: APPLIES-TO
+                    desc: >
+                        Comma-separated references to the FUNCTIONALITY-VIEW, CONCURRENCY-VIEW,
+                        DATA-MODEL, AUTHORIZATION-MODEL, INTERFACE-MODEL, or INTERFACE-ENDPOINTS
+                        objects whose code follows the pattern (e.g. the components persisting
+                        their entities this way, the roles and endpoints guarded by the check);
+                        omitted for a pattern applied throughout the code base.
+                    value: list([[FV.COMPONENT:*]], [[UNIT:*]], [[DM.ENTITY:*]], [[ROLE:*]],
+                        [[INTERFACE:*]], [[ENDPOINT:*]])
+                    optional: true
+                -   name: REALIZES
+                    desc: >
+                        Comma-separated references to the QUALITY-PERSPECTIVES tactics the pattern
+                        is the coded form of (e.g. the token check implementing the access
+                        security tactic); omitted for a pattern serving no modeled tactic.
+                    value: list([[TACTIC:*]])
+                    optional: true
+                -   name: DECIDED-BY
+                    desc: >
+                        Comma-separated references to the DESIGN-DECISIONS objects the pattern
+                        implements (e.g. the query builder usage following the decision against an
+                        ORM); omitted for a pattern behind which no recorded decision stands.
+                    value: list([[DECISION:*]])
+                    optional: true
+                -   name: TOOLS
+                    desc: >
+                        Comma-separated references to the TECHNOLOGY-STACK components the pattern
+                        codes against (e.g. the query builder, the logging library); omitted for a
+                        pattern using the language alone.
+                    value: list([[TS.TIER:*.COMPONENT:*]])
+                    optional: true
+                -   name: USES
+                    desc: >
+                        Comma-separated references to the smaller CODE-PATTERNS objects the pattern
+                        is composed of (e.g. an `Endpoint Authorization` using the `Error
+                        Propagation` for its rejections), so that the patterns form a language of
+                        related shapes rather than a flat catalogue.
+                    value: list([[CODE-PATTERN:*]])
+                    optional: true
+                    acyclic: true
+                -   name: AVOID
+                    desc: >
+                        The deviation the pattern rules out, stated as the concrete shape a
+                        developer would otherwise reach for (e.g. `SQL strings assembled in the
+                        request handlers`, `role checks in the client alone`); omitted when the
+                        rule has no tempting alternative.
+                    optional: true
 -   kind: TEST
     name: Test Cases
     id: TC
-    file: 31-TEST-TC-Test-Cases.md
+    file: 32-TEST-TC-Test-Cases.md
     desc: >
         The verifiable conditions and steps used to confirm that requirements, domain rules, use
         case scenarios, state transitions, and the mechanisms, procedures, and decisions of the
@@ -4182,6 +4380,8 @@
                 concurrency unit when its collaboration or contention is exercised, an aspect of
                 the Development Aspects or a Design Decisions decision when its rule is checked by
                 an architectural fitness function (e.g. no dependency edge against the layering).
+            format:
+                type: compact
             diagram:
                 type: hub
                 center: self
@@ -4195,6 +4395,7 @@
                 config:
                     size-node-width-max: 440
                     size-node-height-scale: 1.75
+                    hub-node-count-max: 3
             props:
                 -   name: VERIFIES
                     desc: >

package/dst/specbook-ignore.js

@@ -41,6 +41,8 @@ const compileRule = (line, base, nocase) => {
     const anchored = pattern.includes("/");
     if (pattern.startsWith("/"))
         pattern = pattern.slice(1);
+    if (pattern === "")
+        return null;
     /*  a negated character class is "[!...]" in the wildmatch of Git,
         while picomatch knows the "[^...]" spelling only  */
     pattern = pattern.replace(/\[!/g, "[^");

package/dst/specbook-link.js

@@ -5,9 +5,24 @@
 */
 /*  the Wiki-style reference syntax ("[[xxx]]")  */
 export const referenceRegex = /\[\[([^[\]]+)\]\]/g;
-/*  strip the inline code markup of a name or property value
-    (preserved in the AST for rendering) for matching and labeling  */
-export const plainText = (text) => text.replace(/`/g, "");
+/*  the fenced code blocks of a Markdown text (from the opening fence line
+    up to the closing fence line, or to the end of an unclosed one)  */
+const fenceRegex = /^[ \t]*(`{3,}|~{3,})[^\n]*(?:\n[\s\S]*?(?:\n[ \t]*\1[`~]*[ \t]*(?=\n|$)|(?![\s\S]))|(?![\s\S]))/gm;
+/*  apply a transformation to the parts of a text outside of its fenced
+    code blocks, which stay verbatim, as code carries no references  */
+const outsideFences = (text, apply) => {
+    let result = "";
+    let last = 0;
+    for (const m of text.matchAll(fenceRegex)) {
+        result += apply(text.slice(last, m.index)) + m[0];
+        last = m.index + m[0].length;
+    }
+    return result + apply(text.slice(last));
+};
+/*  strip the fenced code blocks of a description and the inline code
+    markup of a name, property value, or description (preserved in the
+    AST for rendering) for matching and labeling  */
+export const plainText = (text) => text.replace(fenceRegex, "").replace(/`/g, "");
 /*  provide the lookup structures of an index, built once on first use  */
 const lookups = new WeakMap();
 const lookup = (index) => {
@@ -184,5 +199,6 @@ export const anchorPaths = (index) => {
     }
     return paths;
 };
-/*  expand all references of a text via a per-reference replacer  */
-export const expandReferences = (text, replace) => text.replace(referenceRegex, (_, reference) => replace(reference.trim()));
+/*  expand all references of a text via a per-reference replacer
+    (except inside its fenced code blocks)  */
+export const expandReferences = (text, replace) => outsideFences(text, (part) => part.replace(referenceRegex, (_, reference) => replace(reference.trim())));

package/dst/specbook-parse-common.d.ts

@@ -31,6 +31,30 @@ export declare const becauseRegex: RegExp;
 export declare const embeddingRegex: RegExp;
 export declare const embeddingThemes: readonly ["light", "dark"];
 export declare const embeddingVariants: (reference: string) => string[];
+export declare const pdfType = "application/pdf";
+export declare const codeType = "text/x-code";
+export declare const codeLanguage: (name: string) => string | undefined;
+export declare const markedLines: (mark: string) => {
+    has: (line: number) => boolean;
+};
+type FenceInfo = {
+    lang: string;
+    params: Record<string, string>;
+    error?: string;
+};
+export declare const fenceInfo: (info: string | undefined) => FenceInfo;
+export declare const embeddingFragment: (reference: string, type: string) => {
+    file: string;
+    params: Record<string, string>;
+} | undefined;
+export declare const embeddingFileType: (reference: string) => string | undefined;
 export declare const embeddingMimeType: (reference: string) => string | undefined;
 export declare const embeddingCount: (reference: string | undefined) => number;
 export declare const embeddingDataRegex: RegExp;
+export type DarkMark = "invert" | "none";
+export declare const darkMark: (content: string) => {
+    content: string;
+    dark?: DarkMark;
+};
+export declare const markDark: (content: string, dark: DarkMark) => string;
+export {};