@timiagama/ecr 0.0.1 → 0.1.0

package/dist/ecr.js

@@ -0,0 +1,216 @@
+/**
+ * ECR Public API -- Ecr Facade
+ *
+ * Top-level public API for the ECR structural linter.
+ *
+ * Derived from section 1#13 (Public Interface Contract) and
+ * section 1#10 (Output Schema) of the ECR Structural Specification (doc 1).
+ *
+ * This module provides the {@link Ecr} facade, which delegates
+ * per-document validation to {@link PerDocumentVisitor} and
+ * corpus-wide integrity checks to {@link CorpusValidator}.
+ *
+ * Per-document results are returned exactly as the visitor produces
+ * them: every severity is set by the rule that reports the finding.
+ *
+ * The facade applies one orchestration-level policy:
+ *
+ * **Cross-document duplicate SectionID detection**: The corpus
+ *    validator only sees SectionIDs that survive per-document
+ *    extraction (i.e., those that pass ECR102). A heading like
+ *    `## 3.1#1 - X` inside a document with DocID `4.1` fails ECR102
+ *    (it names another document) and is never extracted — yet its
+ *    SectionID text is still globally significant. The facade
+ *    performs an additional cross-document duplicate check by
+ *    collecting SectionIDs from both extracted sections and
+ *    per-document diagnostics that carry a `sectionId` field.
+ */
+import { PerDocumentVisitor } from "./per-document-visitor.js";
+import { CorpusValidator } from "./corpus-validator.js";
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/**
+ * The corpus-level rule ID for duplicate SectionIDs detected by the facade.
+ */
+const CORPUS_DUPLICATE_SECTION_ID_RULE_ID = 'corpus/duplicate-section-id';
+// ---------------------------------------------------------------------------
+// Public Facade
+// ---------------------------------------------------------------------------
+/**
+ * Top-level public API for the ECR structural linter.
+ *
+ * Provides two operations:
+ * - Single-document linting via {@link Ecr.lintDocument}
+ * - Corpus-wide validation via {@link Ecr.validateCorpus}
+ *
+ * This class is stateless across invocations. Successive calls with
+ * identical inputs produce identical results.
+ */
+export class Ecr {
+    /**
+     * Lint a single Markdown document against per-document ECR structural invariants.
+     *
+     * Creates a {@link PerDocumentVisitor} for the given document and delegates
+     * the linting operation to it.
+     *
+     * @param uri - Opaque, host-provided URI identifying the document instance.
+     * @param markdownText - Raw Markdown text of the document.
+     * @param version - Optional version tag propagated through to the result.
+     * @returns Structured lint result containing diagnostics and optionally extracted artefacts.
+     */
+    lintDocument(uri, markdownText, version) {
+        const visitor = new PerDocumentVisitor({
+            uri,
+            ...(version !== undefined ? { version } : {}),
+        });
+        return visitor.lint(markdownText);
+    }
+    /**
+     * Validate a corpus of Markdown documents.
+     *
+     * Executes per-document linting on every document (Pass 1), then performs
+     * corpus-wide integrity checks on successfully linted documents (Pass 2).
+     *
+     * After the standard corpus validation, the facade performs an additional
+     * cross-document duplicate SectionID check that considers SectionIDs from
+     * per-document diagnostics (not just extracted sections), ensuring that
+     * headings rejected by ECR102 (e.g., wrong DocID prefix) still participate
+     * in global uniqueness enforcement.
+     *
+     * @param documents - Collection of documents to validate.
+     * @returns Corpus result containing per-document results, corpus-wide diagnostics, and an optional global identifier index.
+     */
+    validateCorpus(documents) {
+        // Pass 1: Per-document linting
+        const entries = documents.map((document) => {
+            const lintResult = this.lintDocument(document.uri, document.markdownText, document.version);
+            return {
+                uri: document.uri,
+                result: lintResult,
+            };
+        });
+        // Pass 2: Corpus-wide validation (standard checks)
+        const validator = new CorpusValidator();
+        const baseCorpusResult = validator.validateCorpus(entries);
+        // Pass 2b: Additional facade-level cross-document duplicate SectionID check
+        const additionalDiagnostics = this.detectCrossDocumentDuplicateSectionIds(entries);
+        if (additionalDiagnostics.length === 0) {
+            return baseCorpusResult;
+        }
+        // Merge additional diagnostics into the corpus result
+        const mergedDiagnostics = [
+            ...baseCorpusResult.diagnostics,
+            ...additionalDiagnostics,
+        ];
+        const corpusResult = {
+            documents: baseCorpusResult.documents,
+            diagnostics: mergedDiagnostics,
+            ...(baseCorpusResult.index !== undefined
+                ? { index: baseCorpusResult.index }
+                : {}),
+        };
+        return corpusResult;
+    }
+    // -------------------------------------------------------------------------
+    // Private: Cross-document duplicate SectionID detection
+    // -------------------------------------------------------------------------
+    /**
+     * Detects duplicate SectionIDs across documents by examining both
+     * extracted sections and per-document diagnostics.
+     *
+     * The standard {@link CorpusValidator} only checks extracted sections
+     * (those that pass ECR102). This method extends coverage to include
+     * SectionIDs mentioned in per-document diagnostics — for example,
+     * a heading `## 3.1#1 - X` inside a document with DocID `4.1` fails
+     * ECR102 (it names another document) but the SectionID `3.1#1` is still
+     * present in the diagnostic's `sectionId` field. If document `3.1` also
+     * defines `3.1#1`, that is a corpus-level duplicate.
+     *
+     * This method only emits diagnostics for duplicates NOT already
+     * detected by the standard corpus validator (i.e., duplicates involving
+     * at least one SectionID from a diagnostic rather than an extracted section).
+     *
+     * @param entries - The per-document lint entries from Pass 1
+     * @returns Additional corpus-level diagnostics for duplicate SectionIDs
+     */
+    detectCrossDocumentDuplicateSectionIds(entries) {
+        // Collect all SectionIDs per document from both extracted sections
+        // and per-document diagnostics
+        const sectionIdToUris = new Map();
+        for (const entry of entries) {
+            const documentSectionIds = new Set();
+            // Collect from extracted sections
+            if (entry.result.extracted !== undefined) {
+                for (const section of entry.result.extracted.sections) {
+                    // Skip root H1 nodes — their id is the DocID, handled separately
+                    if (section.headingDepth === 1) {
+                        continue;
+                    }
+                    documentSectionIds.add(section.id);
+                }
+            }
+            // Collect from per-document diagnostics that carry a sectionId field
+            for (const diagnostic of entry.result.diagnostics) {
+                if (diagnostic.sectionId !== undefined) {
+                    documentSectionIds.add(diagnostic.sectionId);
+                }
+            }
+            // Register each SectionID from this document
+            for (const sectionId of documentSectionIds) {
+                const existingUris = sectionIdToUris.get(sectionId);
+                if (existingUris !== undefined) {
+                    // Only add this URI if it is not already listed
+                    // (a document may have both an extracted section and a diagnostic
+                    // for the same SectionID)
+                    if (!existingUris.includes(entry.uri)) {
+                        existingUris.push(entry.uri);
+                    }
+                }
+                else {
+                    sectionIdToUris.set(sectionId, [entry.uri]);
+                }
+            }
+        }
+        // Find duplicates — SectionIDs that appear in more than one document
+        const additionalDiagnostics = [];
+        for (const [sectionId, uris] of sectionIdToUris) {
+            if (uris.length <= 1) {
+                continue;
+            }
+            // The corpus validator detects a duplicate when the SectionID
+            // appears in extracted.sections of 2+ documents. Count how many
+            // of the duplicate URIs have this SectionID in their extracted
+            // sections to avoid emitting redundant diagnostics.
+            let extractedCount = 0;
+            for (const uri of uris) {
+                const entryForUri = entries.find((candidateEntry) => candidateEntry.uri === uri);
+                if (entryForUri?.result.extracted !== undefined) {
+                    const hasExtractedSection = entryForUri.result.extracted.sections.some((section) => section.headingDepth !== 1 && section.id === sectionId);
+                    if (hasExtractedSection) {
+                        extractedCount = extractedCount + 1;
+                    }
+                }
+            }
+            // If 2+ documents have this SectionID in their extracted sections,
+            // the corpus validator already detected the duplicate. Skip.
+            if (extractedCount >= 2) {
+                continue;
+            }
+            // Emit diagnostics for this duplicate
+            for (const uri of uris) {
+                const diagnosticForUri = {
+                    severity: 'error',
+                    ruleId: CORPUS_DUPLICATE_SECTION_ID_RULE_ID,
+                    message: `Duplicate SectionID '${sectionId}' found in multiple documents`,
+                    uri,
+                    sectionId,
+                    data: { duplicateUris: uris },
+                };
+                additionalDiagnostics.push(diagnosticForUri);
+            }
+        }
+        return additionalDiagnostics;
+    }
+}
+//# sourceMappingURL=ecr.js.map

package/dist/ecr.js.map

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

package/dist/glob-pattern.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Glob Patterns
+ *
+ * The minimal glob syntax used by `--ignore` and `.ecrignore`: `*` matches any
+ * run of characters except `/`, `**` matches any run including `/`, a `**`
+ * immediately before a slash matches zero or more whole directories, and `?`
+ * matches one character other than `/`. Everything else matches literally, and
+ * a pattern must match a whole path.
+ *
+ * A pattern is matched by walking the path once for each part of the pattern,
+ * so the work is bounded by the pattern's length times the path's length. An
+ * equivalent regular expression is not: patterns such as `*a*a*a*a*a*a*a*ab`
+ * make a backtracking engine explore exponentially many ways to divide the
+ * path between the wildcards, which let a single crafted ignore pattern hang
+ * the linter. Matching here is a table, so no such pattern exists.
+ */
+/**
+ * A compiled glob pattern that can be matched against a path.
+ */
+export declare class GlobPattern {
+    /** The pattern's parts, in order. */
+    private readonly parts;
+    /**
+     * Compiles a pattern.
+     *
+     * @param pattern - The glob pattern
+     */
+    constructor(pattern: string);
+    /**
+     * Determines whether a path matches the whole pattern.
+     *
+     * @param path - The path to match, using forward slashes
+     * @returns `true` when the pattern matches all of it
+     */
+    matches(path: string): boolean;
+    /**
+     * Works out, for every position in the path, whether one part followed by
+     * the parts after it can match the rest of the path from there.
+     *
+     * @param part - The part being added in front
+     * @param path - The path being matched
+     * @param following - The same answer for the parts after this one
+     * @returns The answer for this part and everything after it
+     */
+    private static matchPart;
+    /**
+     * Matches characters that must appear exactly.
+     *
+     * @param text - The characters the pattern gives
+     * @param path - The path being matched
+     * @param following - Where the parts after this one can match from
+     * @returns Where this part and everything after it can match from
+     */
+    private static matchLiteral;
+    /**
+     * Matches `?`: exactly one character, which may not be a separator.
+     *
+     * @param path - The path being matched
+     * @param following - Where the parts after this one can match from
+     * @returns Where this part and everything after it can match from
+     */
+    private static matchOneCharacter;
+    /**
+     * Matches `*` or `**`: a run of any length.
+     *
+     * A wildcard either stops where it is and lets the parts after it match, or
+     * takes one more character and asks itself the same question. Answering
+     * from the end of the path backwards means each position is settled once,
+     * whereas a regular expression would try the divisions one after another.
+     *
+     * @param path - The path being matched
+     * @param following - Where the parts after this one can match from
+     * @param withinSegment - Whether the run must stay inside one path segment
+     * @returns Where this part and everything after it can match from
+     */
+    private static matchWildcard;
+    /**
+     * Matches a `**` immediately before a slash: zero or more whole directories.
+     *
+     * @param path - The path being matched
+     * @param following - Where the parts after this one can match from
+     * @returns Where this part and everything after it can match from
+     */
+    private static matchWholeDirectories;
+    /**
+     * Splits a pattern into its parts, gathering runs of ordinary characters
+     * into one literal.
+     *
+     * @param pattern - The glob pattern
+     * @returns The parts, in order
+     */
+    private static compile;
+}
+//# sourceMappingURL=glob-pattern.d.ts.map

package/dist/glob-pattern.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"glob-pattern.d.ts","sourceRoot":"","sources":["../src/glob-pattern.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAeH;;GAEG;AACH,qBAAa,WAAW;IACtB,qCAAqC;IACrC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAsB;IAE5C;;;;OAIG;gBACgB,OAAO,EAAE,MAAM;IAIlC;;;;;OAKG;IACI,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAkBrC;;;;;;;;OAQG;IACH,OAAO,CAAC,MAAM,CAAC,SAAS;IAmBxB;;;;;;;OAOG;IACH,OAAO,CAAC,MAAM,CAAC,YAAY;IAc3B;;;;;;OAMG;IACH,OAAO,CAAC,MAAM,CAAC,iBAAiB;IAUhC;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,MAAM,CAAC,aAAa;IAkB5B;;;;;;OAMG;IACH,OAAO,CAAC,MAAM,CAAC,qBAAqB;IAgBpC;;;;;;OAMG;IACH,OAAO,CAAC,MAAM,CAAC,OAAO;CA2CvB"}

package/dist/glob-pattern.js

@@ -0,0 +1,188 @@
+/**
+ * Glob Patterns
+ *
+ * The minimal glob syntax used by `--ignore` and `.ecrignore`: `*` matches any
+ * run of characters except `/`, `**` matches any run including `/`, a `**`
+ * immediately before a slash matches zero or more whole directories, and `?`
+ * matches one character other than `/`. Everything else matches literally, and
+ * a pattern must match a whole path.
+ *
+ * A pattern is matched by walking the path once for each part of the pattern,
+ * so the work is bounded by the pattern's length times the path's length. An
+ * equivalent regular expression is not: patterns such as `*a*a*a*a*a*a*a*ab`
+ * make a backtracking engine explore exponentially many ways to divide the
+ * path between the wildcards, which let a single crafted ignore pattern hang
+ * the linter. Matching here is a table, so no such pattern exists.
+ */
+/**
+ * A compiled glob pattern that can be matched against a path.
+ */
+export class GlobPattern {
+    /** The pattern's parts, in order. */
+    parts;
+    /**
+     * Compiles a pattern.
+     *
+     * @param pattern - The glob pattern
+     */
+    constructor(pattern) {
+        this.parts = GlobPattern.compile(pattern);
+    }
+    /**
+     * Determines whether a path matches the whole pattern.
+     *
+     * @param path - The path to match, using forward slashes
+     * @returns `true` when the pattern matches all of it
+     */
+    matches(path) {
+        const length = path.length;
+        // `reached[index]` says whether the parts considered so far can match the
+        // rest of the path from `index`. It starts as the answer for no parts at
+        // all: only a path already consumed to its end matches nothing more.
+        let reached = new Array(length + 1).fill(false);
+        reached[length] = true;
+        // Each part is added in front of the answer for the parts after it, so
+        // they are considered last one first.
+        for (const part of [...this.parts].reverse()) {
+            reached = GlobPattern.matchPart(part, path, reached);
+        }
+        return reached[0] ?? false;
+    }
+    /**
+     * Works out, for every position in the path, whether one part followed by
+     * the parts after it can match the rest of the path from there.
+     *
+     * @param part - The part being added in front
+     * @param path - The path being matched
+     * @param following - The same answer for the parts after this one
+     * @returns The answer for this part and everything after it
+     */
+    static matchPart(part, path, following) {
+        switch (part.kind) {
+            case 'literal':
+                return GlobPattern.matchLiteral(part.text, path, following);
+            case 'oneCharacter':
+                return GlobPattern.matchOneCharacter(path, following);
+            case 'withinSegment':
+                return GlobPattern.matchWildcard(path, following, true);
+            case 'acrossSegments':
+                return GlobPattern.matchWildcard(path, following, false);
+            case 'wholeDirectories':
+                return GlobPattern.matchWholeDirectories(path, following);
+        }
+    }
+    /**
+     * Matches characters that must appear exactly.
+     *
+     * @param text - The characters the pattern gives
+     * @param path - The path being matched
+     * @param following - Where the parts after this one can match from
+     * @returns Where this part and everything after it can match from
+     */
+    static matchLiteral(text, path, following) {
+        const reached = new Array(path.length + 1).fill(false);
+        for (let index = 0; index + text.length <= path.length; index += 1) {
+            reached[index] = path.startsWith(text, index) && (following[index + text.length] ?? false);
+        }
+        return reached;
+    }
+    /**
+     * Matches `?`: exactly one character, which may not be a separator.
+     *
+     * @param path - The path being matched
+     * @param following - Where the parts after this one can match from
+     * @returns Where this part and everything after it can match from
+     */
+    static matchOneCharacter(path, following) {
+        const reached = new Array(path.length + 1).fill(false);
+        for (let index = 0; index < path.length; index += 1) {
+            reached[index] = path[index] !== '/' && (following[index + 1] ?? false);
+        }
+        return reached;
+    }
+    /**
+     * Matches `*` or `**`: a run of any length.
+     *
+     * A wildcard either stops where it is and lets the parts after it match, or
+     * takes one more character and asks itself the same question. Answering
+     * from the end of the path backwards means each position is settled once,
+     * whereas a regular expression would try the divisions one after another.
+     *
+     * @param path - The path being matched
+     * @param following - Where the parts after this one can match from
+     * @param withinSegment - Whether the run must stay inside one path segment
+     * @returns Where this part and everything after it can match from
+     */
+    static matchWildcard(path, following, withinSegment) {
+        const reached = new Array(path.length + 1).fill(false);
+        for (let index = path.length; index >= 0; index -= 1) {
+            const canTakeOneMore = index < path.length && (!withinSegment || path[index] !== '/');
+            reached[index] =
+                (following[index] ?? false) || (canTakeOneMore && (reached[index + 1] ?? false));
+        }
+        return reached;
+    }
+    /**
+     * Matches a `**` immediately before a slash: zero or more whole directories.
+     *
+     * @param path - The path being matched
+     * @param following - Where the parts after this one can match from
+     * @returns Where this part and everything after it can match from
+     */
+    static matchWholeDirectories(path, following) {
+        // Whole directories are taken whole, so this part matches either nothing
+        // at all, or a run of characters ending at a separator.
+        const endsAtSlash = new Array(path.length + 1).fill(false);
+        for (let index = path.length - 1; index >= 0; index -= 1) {
+            endsAtSlash[index] =
+                (path[index] === '/' && (following[index + 1] ?? false)) ||
+                    (endsAtSlash[index + 1] ?? false);
+        }
+        return endsAtSlash.map((endsHere, index) => (following[index] ?? false) || endsHere);
+    }
+    /**
+     * Splits a pattern into its parts, gathering runs of ordinary characters
+     * into one literal.
+     *
+     * @param pattern - The glob pattern
+     * @returns The parts, in order
+     */
+    static compile(pattern) {
+        const parts = [];
+        let literal = '';
+        /** Closes off any literal gathered so far. */
+        const flushLiteral = () => {
+            if (literal !== '') {
+                parts.push({ kind: 'literal', text: literal });
+                literal = '';
+            }
+        };
+        for (let index = 0; index < pattern.length; index += 1) {
+            const character = pattern[index] ?? '';
+            if (character === '*') {
+                flushLiteral();
+                if (pattern[index + 1] === '*' && pattern[index + 2] === '/') {
+                    parts.push({ kind: 'wholeDirectories' });
+                    index += 2;
+                }
+                else if (pattern[index + 1] === '*') {
+                    parts.push({ kind: 'acrossSegments' });
+                    index += 1;
+                }
+                else {
+                    parts.push({ kind: 'withinSegment' });
+                }
+                continue;
+            }
+            if (character === '?') {
+                flushLiteral();
+                parts.push({ kind: 'oneCharacter' });
+                continue;
+            }
+            literal += character;
+        }
+        flushLiteral();
+        return parts;
+    }
+}
+//# sourceMappingURL=glob-pattern.js.map

package/dist/glob-pattern.js.map

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

package/dist/heading-source-form.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Heading Source Form
+ *
+ * Checks that a heading carrying a DocID or SectionID is written in the one
+ * source form the published recipes can find (1#9.11 rule 1): an ATX heading
+ * whose line begins with its `#` characters, then exactly one space, then the
+ * identifier in literal characters.
+ *
+ * The Markdown parser accepts far more than that. A setext heading, an
+ * indented one, one inside a blockquote, one with a tab or two spaces after
+ * the hashes, and one whose identifier is emphasised, escaped or written as a
+ * character reference all parse to the same identifier -- and none of them is
+ * found by `^# 8\.1[^0-9.#]` or `^#+ 8\.1#3([^0-9]|$)`. So the check reads the
+ * heading's own source line and asks the question the recipe asks.
+ *
+ * It also asks whether that line is a line at all to a search engine. Two
+ * things can hide a correctly written heading from `^`: a lone carriage
+ * return before it, which Markdown treats as a line ending and the engines do
+ * not, and a byte-order mark before the first line, which ripgrep skips and
+ * GNU grep does not.
+ *
+ * Shared by ECR101 (the H1) and ECR102 (every deeper heading).
+ */
+import type { PositionRange } from './types.js';
+/** The `data.cause` of a heading whose source form no recipe can find. */
+export declare const HEADING_SOURCE_FORM_CAUSE: string;
+/**
+ * Why a heading cannot be found, carried as `data.obstruction`.
+ *
+ * - `form`: the heading line is not `#… identifier` from its first column.
+ * - `lone-carriage-return`: it is, but a lone CR precedes it, so to a search
+ *   it is the middle of the line before.
+ * - `byte-order-mark`: it is, but it is the first line and a byte-order mark
+ *   precedes it, which GNU grep reads as text before the `#`.
+ */
+export type HeadingObstruction = 'form' | 'lone-carriage-return' | 'byte-order-mark';
+/**
+ * Tells whether headings are written where the recipes look for them.
+ */
+export declare class HeadingSourceForm {
+    /** The document's source, by line; absent when none was supplied. */
+    private readonly lines;
+    /**
+     * @param sourceText - The document's raw Markdown. When absent, as in unit
+     *                     tests that supply only parsed heading text, there is
+     *                     no source to consult and every heading passes.
+     */
+    constructor(sourceText: string | undefined);
+    /**
+     * Finds what, if anything, stops the recipe for a heading from finding it.
+     *
+     * @param range - The heading node's range
+     * @param depth - The heading's depth, 1 for the H1
+     * @param identifier - The DocID or SectionID parsed from the heading
+     * @returns The obstruction, or `undefined` when the recipe would find it
+     */
+    findObstruction(range: PositionRange | undefined, depth: number, identifier: string): HeadingObstruction | undefined;
+    /**
+     * Reports whether a line reads as the recipe for its heading expects.
+     *
+     * @param line - The heading's source line
+     * @param depth - The heading's depth
+     * @param identifier - The DocID or SectionID parsed from the heading
+     * @returns `true` when the line is `#… identifier` followed by an allowed character
+     */
+    private static tellLineMatches;
+    /**
+     * The explanation a diagnostic gives for an unnavigable heading.
+     *
+     * @param obstruction - What stops the recipe from finding it
+     * @param depth - The heading's depth
+     * @param identifier - The DocID or SectionID parsed from the heading
+     * @returns A message naming the obstruction and the fix
+     */
+    static explain(obstruction: HeadingObstruction, depth: number, identifier: string): string;
+}
+//# sourceMappingURL=heading-source-form.d.ts.map

package/dist/heading-source-form.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"heading-source-form.d.ts","sourceRoot":"","sources":["../src/heading-source-form.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAGhD,0EAA0E;AAC1E,eAAO,MAAM,yBAAyB,EAAE,MAA8B,CAAC;AAEvE;;;;;;;;GAQG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,sBAAsB,GAAG,iBAAiB,CAAC;AAkBrF;;GAEG;AACH,qBAAa,iBAAiB;IAC5B,qEAAqE;IACrE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA0B;IAEhD;;;;OAIG;gBACgB,UAAU,EAAE,MAAM,GAAG,SAAS;IAIjD;;;;;;;OAOG;IACI,eAAe,CACpB,KAAK,EAAE,aAAa,GAAG,SAAS,EAChC,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,MAAM,GACjB,kBAAkB,GAAG,SAAS;IAyBjC;;;;;;;OAOG;IACH,OAAO,CAAC,MAAM,CAAC,eAAe;IAY9B;;;;;;;OAOG;WACW,OAAO,CACnB,WAAW,EAAE,kBAAkB,EAC/B,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,MAAM,GACjB,MAAM;CA8BV"}