vouchington-tooling 0.32.0 → 0.34.0

package/dist/finite-enum-ripple/structured-route-check.mjs

@@ -0,0 +1,94 @@
+import { hasConfiguredObjectDeclaration } from './ast.mjs';
+import { parseStructuredRouteConfigEntries } from './parsers.mjs';
+import { checkCollectionPagePathLiterals, compareSets, finiteEnumError, hasAllFiles, routePageSlugs, uniqueSorted, } from './compare.mjs';
+import { checkStructuredCollectionComponentPathLiterals } from './component-paths.mjs';
+export function checkStructuredRouteConfigs(errors, files, readTracked, config, backendEntries, backendSlugByValue) {
+    const routeConfigsPath = config.routeConfigsPath;
+    const backendStructuredsPath = config.backendPath;
+    if (hasAllFiles(files, [routeConfigsPath])) {
+        const routeConfigContent = readTracked(routeConfigsPath);
+        if (hasConfiguredObjectDeclaration(routeConfigContent, config.routeConfigObject, routeConfigsPath)) {
+            const routeConfigs = parseStructuredRouteConfigEntries(routeConfigContent, routeConfigsPath, config.routeConfigObject, config.typeArrayProperty, config.routeExemptionProperty, config.pluralPathProperty, config.singularPathProperty);
+            const slugPluralByValue = new Map(backendEntries.map((entry) => [entry.value, entry.slugPlural]));
+            const valueBySlug = new Map(backendEntries.map((entry) => [entry.slug, entry.value]));
+            const typedRouteConfigs = routeConfigs.map((routeConfig) => ({
+                ...routeConfig,
+                inferredStructuredType: valueBySlug.get(routeConfig.singularPath),
+            }));
+            for (const routeConfig of typedRouteConfigs) {
+                if (routeConfig.structuredTypes.length > 0 ||
+                    routeConfig.routeExempt ||
+                    routeConfig.inferredStructuredType === undefined ||
+                    config.routeConfigExceptions.includes(routeConfig.key)) {
+                    continue;
+                }
+                errors.push(finiteEnumError(routeConfigsPath, `${config.routeConfigObject}.${routeConfig.key} has ${config.singularPathProperty} "${routeConfig.singularPath}" but does not declare ${config.typeArrayProperty}`));
+            }
+            const enumRouteConfigs = typedRouteConfigs.filter((routeConfig) => routeConfig.structuredTypes.length > 0);
+            for (const routeConfig of routeConfigs) {
+                if (routeConfig.key === routeConfig.pluralPath)
+                    continue;
+                errors.push(finiteEnumError(routeConfigsPath, `${config.routeConfigObject}.${routeConfig.key} has ${config.pluralPathProperty} "${routeConfig.pluralPath}" but the route config key is "${routeConfig.key}"`));
+            }
+            for (const routeConfig of enumRouteConfigs) {
+                const structuredType = routeConfig.structuredTypes[0];
+                const expectedSlug = backendSlugByValue.get(structuredType);
+                const expectedSlugPlural = slugPluralByValue.get(structuredType);
+                if (routeConfig.structuredTypes.length === 1 &&
+                    routeConfig.singularPath === expectedSlug &&
+                    routeConfig.pluralPath === expectedSlugPlural) {
+                    continue;
+                }
+                errors.push(finiteEnumError(routeConfigsPath, `${config.routeConfigObject}.${routeConfig.key} maps ${config.singularPathProperty} "${routeConfig.singularPath}" and ${config.pluralPathProperty} "${routeConfig.pluralPath}" to [${routeConfig.structuredTypes.join(', ')}] but ${config.typeObject} expects "${expectedSlug ?? 'missing'}" and "${expectedSlugPlural ?? 'missing'}"`));
+            }
+            compareSets(errors, {
+                label: `${config.collectionLabel} route config values`,
+                actualLabel: `${routeConfigsPath} ${config.routeConfigObject}`,
+                actualFile: routeConfigsPath,
+                actualValues: typedRouteConfigs.flatMap((routeConfig) => routeConfig.structuredTypes.length > 0
+                    ? routeConfig.structuredTypes
+                    : routeConfig.inferredStructuredType !== undefined &&
+                        (routeConfig.routeExempt || config.routeConfigExceptions.includes(routeConfig.key))
+                        ? [routeConfig.inferredStructuredType]
+                        : []),
+                expectedLabel: backendStructuredsPath,
+                expectedFile: backendStructuredsPath,
+                expectedValues: backendEntries
+                    .filter((entry) => !config.collectionRouteExclusions.includes(entry.value))
+                    .map((entry) => entry.value),
+            });
+            compareSets(errors, {
+                label: `${config.collectionLabel} collection route config paths`,
+                actualLabel: `${routeConfigsPath} ${config.routeConfigObject}`,
+                actualFile: routeConfigsPath,
+                actualValues: enumRouteConfigs.map((routeConfig) => routeConfig.pluralPath),
+                expectedLabel: `${backendStructuredsPath} ${config.typeObject} ${config.slugPluralProperty}`,
+                expectedFile: backendStructuredsPath,
+                expectedValues: enumRouteConfigs.flatMap((routeConfig) => {
+                    const slugPlural = slugPluralByValue.get(routeConfig.structuredTypes[0]);
+                    return slugPlural ? [slugPlural] : [];
+                }),
+            });
+            compareSets(errors, {
+                label: `${config.collectionLabel} top-level collection route directories`,
+                actualLabel: config.routeLabels.collectionTop,
+                actualFile: files.structuredCollectionPages[0]?.file ?? routeConfigsPath,
+                actualValues: routePageSlugs(files.structuredCollectionPages, true),
+                expectedLabel: `${routeConfigsPath} ${config.routeConfigObject} ${config.pluralPathProperty}`,
+                expectedFile: routeConfigsPath,
+                expectedValues: routeConfigs.map((routeConfig) => routeConfig.pluralPath),
+            });
+            compareSets(errors, {
+                label: `${config.collectionLabel} collection routed pages`,
+                actualLabel: config.routeLabels.collection,
+                actualFile: files.structuredCollectionPages[0]?.file ?? routeConfigsPath,
+                actualValues: uniqueSorted(files.structuredCollectionPages.map((page) => page.slug)),
+                expectedLabel: `${routeConfigsPath} ${config.routeConfigObject} ${config.pluralPathProperty}`,
+                expectedFile: routeConfigsPath,
+                expectedValues: routeConfigs.map((routeConfig) => routeConfig.pluralPath),
+            });
+            checkCollectionPagePathLiterals(files.structuredCollectionPages, errors, config.collectionLabel, new Set(routeConfigs.map((routeConfig) => routeConfig.pluralPath)), readTracked, config.collectionPathLiteralPattern);
+            checkStructuredCollectionComponentPathLiterals(errors, routeConfigs, files.structuredComponentFiles, new Set(config.ignoredNavigationPaths), readTracked, config.collectionLabel, config.navigationPathLiteralPattern);
+        }
+    }
+}

package/dist/finite-enum-ripple/types.d.mts

@@ -0,0 +1,2 @@
+import type { FiniteEnumFiles, FiniteEnumRippleConfig, ReadTrackedFile } from './model.mts';
+export declare function checkStructuredTypes(errors: string[], files: FiniteEnumFiles, readTracked: ReadTrackedFile, config: NonNullable<FiniteEnumRippleConfig['structured']>): void;

package/dist/finite-enum-ripple/types.mjs

@@ -0,0 +1,60 @@
+import { parseStructuredRouteFactoryArgs, parseStructuredTypeEntries } from './parsers.mjs';
+import { compareSets, finiteEnumError, hasAllFiles, routePageSlugs } from './compare.mjs';
+import { checkStructuredRouteConfigs } from './structured-route-check.mjs';
+export function checkStructuredTypes(errors, files, readTracked, config) {
+    const backendStructuredsPath = config.backendPath;
+    const webStructuredsPath = config.webPath;
+    if (!hasAllFiles(files, [backendStructuredsPath, webStructuredsPath]))
+        return;
+    const backendEntries = parseStructuredTypeEntries(readTracked(backendStructuredsPath), backendStructuredsPath, config.typeObject, config.slugProperty, config.slugPluralProperty);
+    const webEntries = parseStructuredTypeEntries(readTracked(webStructuredsPath), webStructuredsPath, config.typeObject, config.slugProperty, config.slugPluralProperty);
+    const backendSlugByValue = new Map(backendEntries.map((entry) => [entry.value, entry.slug]));
+    const backendSlugPluralByValue = new Map(backendEntries.map((entry) => [entry.value, entry.slugPlural]));
+    compareSets(errors, {
+        label: `${config.collectionLabel} values`,
+        actualLabel: `${webStructuredsPath} ${config.typeObject}`,
+        actualFile: webStructuredsPath,
+        actualValues: webEntries.map((entry) => entry.value),
+        expectedLabel: `${backendStructuredsPath} ${config.typeObject}`,
+        expectedFile: backendStructuredsPath,
+        expectedValues: backendEntries.map((entry) => entry.value),
+    });
+    for (const webEntry of webEntries) {
+        const backendSlug = backendSlugByValue.get(webEntry.value);
+        if (backendSlug && backendSlug !== webEntry.slug) {
+            errors.push(finiteEnumError(webStructuredsPath, `${config.typeObject}.${webEntry.value}.${config.slugProperty} is "${webEntry.slug}" but ${backendStructuredsPath} uses "${backendSlug}"`));
+        }
+        const backendSlugPlural = backendSlugPluralByValue.get(webEntry.value);
+        if (backendSlugPlural && backendSlugPlural !== webEntry.slugPlural) {
+            errors.push(finiteEnumError(webStructuredsPath, `${config.typeObject}.${webEntry.value}.${config.slugPluralProperty} is "${webEntry.slugPlural}" but ${backendStructuredsPath} uses "${backendSlugPlural}"`));
+        }
+    }
+    const topRouteSlugs = routePageSlugs(files.structuredDetailPages, true);
+    const routeSlugs = routePageSlugs(files.structuredDetailPages);
+    compareSets(errors, {
+        label: `${config.collectionLabel} route directories`,
+        actualLabel: config.routeLabels.detailTop,
+        actualFile: files.structuredDetailPages[0]?.file ?? backendStructuredsPath,
+        actualValues: topRouteSlugs,
+        expectedLabel: `${backendStructuredsPath} ${config.typeObject} slugs`,
+        expectedFile: backendStructuredsPath,
+        expectedValues: backendEntries.map((entry) => entry.slug),
+    });
+    compareSets(errors, {
+        label: `${config.collectionLabel} routed pages`,
+        actualLabel: config.routeLabels.detail,
+        actualFile: files.structuredDetailPages[0]?.file ?? backendStructuredsPath,
+        actualValues: routeSlugs,
+        expectedLabel: `${backendStructuredsPath} ${config.typeObject} slugs`,
+        expectedFile: backendStructuredsPath,
+        expectedValues: backendEntries.map((entry) => entry.slug),
+    });
+    checkStructuredRouteConfigs(errors, files, readTracked, config, backendEntries, backendSlugByValue);
+    for (const page of files.structuredDetailPages) {
+        for (const args of parseStructuredRouteFactoryArgs(readTracked(page.file), page.file, config.factoryCallPattern)) {
+            if (page.slug === args.slug)
+                continue;
+            errors.push(finiteEnumError(page.file, `${config.collectionLabel} route factory slug mismatch; route directory is "${page.slug}" but factory uses "${args.slug}"`));
+        }
+    }
+}

package/dist/finite-enum-ripple/union-factory-check.d.mts

@@ -0,0 +1,2 @@
+import type { FiniteEnumRippleConfig, ReadTrackedFile, RoutedPage } from './model.mts';
+export declare function checkUnionFactories(errors: string[], pages: readonly RoutedPage[], readTracked: ReadTrackedFile, config: NonNullable<FiniteEnumRippleConfig['union']>, slugToType: ReadonlyMap<string, string>, routeSlugs: readonly string[]): void;

package/dist/finite-enum-ripple/union-factory-check.mjs

@@ -0,0 +1,34 @@
+import { compareSets, finiteEnumError, uniqueSorted } from './compare.mjs';
+import { parseUnionDetailRouteFactoryArgs } from './parsers.mjs';
+export function checkUnionFactories(errors, pages, readTracked, config, slugToType, routeSlugs) {
+    const routeConfigsPath = config.routeConfigsPath;
+    const detailFactoryArgs = pages.flatMap((page) => parseUnionDetailRouteFactoryArgs(readTracked(page.file), page.file, config.factoryCallPattern).map((args) => ({
+        ...args,
+        file: page.file,
+        routeSlug: page.slug,
+    })));
+    compareSets(errors, {
+        label: `${config.collectionLabel} route factory slugs`,
+        actualLabel: config.routeLabels.factory,
+        actualFile: pages[0]?.file ?? routeConfigsPath,
+        actualValues: uniqueSorted(detailFactoryArgs.map((args) => args.slug)),
+        expectedLabel: config.routeLabels.detail,
+        expectedFile: pages[0]?.file ?? routeConfigsPath,
+        expectedValues: routeSlugs,
+    });
+    compareSets(errors, {
+        label: `${config.collectionLabel} route factory values`,
+        actualLabel: config.routeLabels.factory,
+        actualFile: pages[0]?.file ?? routeConfigsPath,
+        actualValues: uniqueSorted(detailFactoryArgs.map((args) => args.unionType)),
+        expectedLabel: `${routeConfigsPath} ${config.slugMapObject} values`,
+        expectedFile: routeConfigsPath,
+        expectedValues: [...slugToType.values()],
+    });
+    for (const args of detailFactoryArgs) {
+        const expectedType = slugToType.get(args.routeSlug);
+        if (args.slug === args.routeSlug && expectedType === args.unionType)
+            continue;
+        errors.push(finiteEnumError(args.file, `${config.collectionLabel} route factory args mismatch; route directory is "${args.routeSlug}" and expected type is "${expectedType ?? 'missing'}" but factory uses "${args.unionType}", "${args.slug}"`));
+    }
+}

package/dist/finite-enum-ripple/union-types.d.mts

@@ -0,0 +1,2 @@
+import type { FiniteEnumFiles, FiniteEnumRippleConfig, ReadTrackedFile } from './model.mts';
+export declare function checkUnionTypes(errors: string[], files: FiniteEnumFiles, readTracked: ReadTrackedFile, config: NonNullable<FiniteEnumRippleConfig['union']>): void;

package/dist/finite-enum-ripple/union-types.mjs

@@ -0,0 +1,129 @@
+import { hasConfiguredObjectDeclaration } from './ast.mjs';
+import { checkUnionFactories } from './union-factory-check.mjs';
+import { checkCollectionPagePathLiterals, checkUnionCreatePageTypes, compareSets, finiteEnumError, hasAllFiles, routePageSlugs, uniqueSorted, } from './compare.mjs';
+import { parseUnionRouteConfigEntries, parseUnionSlugToType, parseUnionTypeUnion, } from './parsers.mjs';
+export function checkUnionTypes(errors, files, readTracked, config) {
+    const unionTypesPath = config.typesPath;
+    const routeConfigsPath = config.routeConfigsPath;
+    if (!hasAllFiles(files, [unionTypesPath, routeConfigsPath]))
+        return;
+    const unionTypes = parseUnionTypeUnion(readTracked(unionTypesPath), unionTypesPath, config.typeAlias);
+    const publicUnionTypes = unionTypes.filter((value) => !config.internalTypes.includes(value));
+    const routeConfigContent = readTracked(routeConfigsPath);
+    const slugToType = parseUnionSlugToType(routeConfigContent, routeConfigsPath, config.slugMapObject);
+    const topRouteSlugs = routePageSlugs(files.unionDetailPages, true);
+    const routeSlugs = routePageSlugs(files.unionDetailPages);
+    compareSets(errors, {
+        label: `${config.collectionLabel} route config values`,
+        actualLabel: `${routeConfigsPath} ${config.slugMapObject}`,
+        actualFile: routeConfigsPath,
+        actualValues: [...slugToType.values()],
+        expectedLabel: `${unionTypesPath} public ${config.typeAlias} values`,
+        expectedFile: unionTypesPath,
+        expectedValues: publicUnionTypes,
+    });
+    compareSets(errors, {
+        label: `${config.collectionLabel} route directories`,
+        actualLabel: config.routeLabels.detailTop,
+        actualFile: files.unionDetailPages[0]?.file ?? routeConfigsPath,
+        actualValues: topRouteSlugs,
+        expectedLabel: `${routeConfigsPath} ${config.slugMapObject} slugs`,
+        expectedFile: routeConfigsPath,
+        expectedValues: [...slugToType.keys()],
+    });
+    compareSets(errors, {
+        label: `${config.collectionLabel} routed pages`,
+        actualLabel: config.routeLabels.detail,
+        actualFile: files.unionDetailPages[0]?.file ?? routeConfigsPath,
+        actualValues: routeSlugs,
+        expectedLabel: `${routeConfigsPath} ${config.slugMapObject} slugs`,
+        expectedFile: routeConfigsPath,
+        expectedValues: [...slugToType.keys()],
+    });
+    if (hasConfiguredObjectDeclaration(routeConfigContent, config.routeConfigObject, routeConfigsPath)) {
+        const routeConfigs = parseUnionRouteConfigEntries(routeConfigContent, routeConfigsPath, config.routeConfigObject, config.typeArrayProperty, config.pluralPathProperty, config.singularPathProperty);
+        const typedRouteConfigs = routeConfigs.filter((routeConfig) => routeConfig.unionTypes.length > 0);
+        const effectiveSingleTypeRouteConfigs = routeConfigs.flatMap((routeConfig) => {
+            if (routeConfig.unionTypes.length === 1)
+                return [routeConfig];
+            if (!config.routeConfigExceptions.includes(routeConfig.key))
+                return [];
+            const inferredType = slugToType.get(routeConfig.singularPath);
+            return inferredType === undefined ? [] : [{ ...routeConfig, unionTypes: [inferredType] }];
+        });
+        for (const routeConfig of routeConfigs) {
+            if (routeConfig.unionTypes.length > 0 ||
+                config.routeConfigExceptions.includes(routeConfig.key))
+                continue;
+            errors.push(finiteEnumError(routeConfigsPath, `${config.routeConfigObject}.${routeConfig.key} has ${config.singularPathProperty} "${routeConfig.singularPath}" but does not declare ${config.typeArrayProperty}`));
+        }
+        for (const routeConfig of routeConfigs) {
+            if (routeConfig.key === routeConfig.pluralPath)
+                continue;
+            errors.push(finiteEnumError(routeConfigsPath, `${config.routeConfigObject}.${routeConfig.key} has ${config.pluralPathProperty} "${routeConfig.pluralPath}" but the route config key is "${routeConfig.key}"`));
+        }
+        compareSets(errors, {
+            label: `${config.collectionLabel} collection route config values`,
+            actualLabel: `${routeConfigsPath} ${config.routeConfigObject}`,
+            actualFile: routeConfigsPath,
+            actualValues: routeConfigs.flatMap((routeConfig) => {
+                if (routeConfig.unionTypes.length > 0)
+                    return routeConfig.unionTypes;
+                if (!config.routeConfigExceptions.includes(routeConfig.key))
+                    return [];
+                const inferredType = slugToType.get(routeConfig.singularPath);
+                return inferredType === undefined ? [] : [inferredType];
+            }),
+            expectedLabel: `${unionTypesPath} public ${config.typeAlias} values`,
+            expectedFile: unionTypesPath,
+            expectedValues: publicUnionTypes,
+        });
+        compareSets(errors, {
+            label: `${config.collectionLabel} collection route config singular paths`,
+            actualLabel: `${routeConfigsPath} ${config.routeConfigObject}`,
+            actualFile: routeConfigsPath,
+            actualValues: routeConfigs.flatMap((routeConfig) => {
+                if (routeConfig.unionTypes.length > 0)
+                    return [routeConfig.singularPath];
+                if (config.routeConfigExceptions.includes(routeConfig.key) &&
+                    slugToType.has(routeConfig.singularPath)) {
+                    return [routeConfig.singularPath];
+                }
+                return [];
+            }),
+            expectedLabel: `${routeConfigsPath} ${config.slugMapObject} slugs`,
+            expectedFile: routeConfigsPath,
+            expectedValues: [...slugToType.keys()],
+        });
+        for (const routeConfig of typedRouteConfigs) {
+            const expectedType = slugToType.get(routeConfig.singularPath);
+            if (expectedType !== undefined &&
+                routeConfig.unionTypes.length === 1 &&
+                routeConfig.unionTypes[0] === expectedType) {
+                continue;
+            }
+            errors.push(finiteEnumError(routeConfigsPath, `${config.routeConfigObject}.${routeConfig.key} maps ${config.singularPathProperty} "${routeConfig.singularPath}" to [${routeConfig.unionTypes.join(', ')}] but ${config.slugMapObject} expects "${expectedType ?? 'missing'}"`));
+        }
+        compareSets(errors, {
+            label: `${config.collectionLabel} top-level collection route directories`,
+            actualLabel: config.routeLabels.collectionTop,
+            actualFile: files.unionCollectionPages[0]?.file ?? routeConfigsPath,
+            actualValues: routePageSlugs(files.unionCollectionPages, true),
+            expectedLabel: `${routeConfigsPath} ${config.routeConfigObject} ${config.pluralPathProperty}`,
+            expectedFile: routeConfigsPath,
+            expectedValues: routeConfigs.map((routeConfig) => routeConfig.pluralPath),
+        });
+        compareSets(errors, {
+            label: `${config.collectionLabel} collection routed pages`,
+            actualLabel: config.routeLabels.collection,
+            actualFile: files.unionCollectionPages[0]?.file ?? routeConfigsPath,
+            actualValues: uniqueSorted(files.unionCollectionPages.map((page) => page.slug)),
+            expectedLabel: `${routeConfigsPath} ${config.routeConfigObject} ${config.pluralPathProperty}`,
+            expectedFile: routeConfigsPath,
+            expectedValues: routeConfigs.map((routeConfig) => routeConfig.pluralPath),
+        });
+        checkUnionCreatePageTypes(errors, effectiveSingleTypeRouteConfigs, files.unionCreatePages, readTracked, config.createPageTypeProperties, config.collectionLabel);
+        checkCollectionPagePathLiterals(files.unionCollectionPages, errors, config.collectionLabel, new Set(effectiveSingleTypeRouteConfigs.map((routeConfig) => routeConfig.pluralPath)), readTracked, config.collectionPathLiteralPattern);
+    }
+    checkUnionFactories(errors, files.unionDetailPages, readTracked, config, slugToType, routeSlugs);
+}

package/dist/markdown/content-facts.d.mts

@@ -0,0 +1,6 @@
+import type { MarkdownSourceSpan } from './types.mts';
+/**
+ * Returns source spans for fenced/indented code, inline code, and raw HTML. Offsets are JavaScript
+ * string offsets; positions retain the parser's 1-indexed line and column coordinates.
+ */
+export declare function markdownLiteralSpans(markdown: string): MarkdownSourceSpan[];

package/dist/markdown/content-facts.mjs

@@ -0,0 +1,18 @@
+import { parseGfmMarkdown, walkMarkdown } from './ast.mjs';
+/**
+ * Returns source spans for fenced/indented code, inline code, and raw HTML. Offsets are JavaScript
+ * string offsets; positions retain the parser's 1-indexed line and column coordinates.
+ */
+export function markdownLiteralSpans(markdown) {
+    const spans = [];
+    walkMarkdown(parseGfmMarkdown(markdown), (node) => {
+        if (node.type !== 'code' && node.type !== 'inlineCode' && node.type !== 'html')
+            return;
+        spans.push({
+            kind: node.type === 'inlineCode' ? 'inline-code' : node.type,
+            position: node.position,
+            value: node.value,
+        });
+    });
+    return spans;
+}

package/dist/markdown/html-blocks.d.mts

@@ -0,0 +1,5 @@
+import type { MarkdownHtmlFact } from './types.mts';
+/** Returns source-backed HTML facts, classifying inline occurrences separately from block nodes. */
+export declare function markdownHtmlFacts(markdown: string): MarkdownHtmlFact[];
+/** Returns block HTML facts for CommonMark types 1, 6, and 7, preserving their parser bounds. */
+export declare function markdownHtmlBlocks(markdown: string): MarkdownHtmlFact[];

package/dist/markdown/html-blocks.mjs

@@ -0,0 +1,51 @@
+import { parseGfmMarkdown } from './ast.mjs';
+const BLOCK_CONTAINERS = new Set(['root', 'blockquote', 'list', 'listItem', 'footnoteDefinition']);
+const TYPE1 = /^ {0,3}<(script|style|pre|textarea)(?:[\s>]|$)/i;
+const TYPE6_NAMES = 'address|article|aside|base|basefont|blockquote|body|caption|center|col|colgroup|dd|details|' +
+    'dialog|dir|div|dl|dt|fieldset|figcaption|figure|footer|form|frame|frameset|h[1-6]|head|header|' +
+    'hr|html|iframe|legend|li|link|main|menu|menuitem|nav|noframes|ol|optgroup|option|p|param|' +
+    'search|section|summary|table|tbody|td|tfoot|th|thead|title|tr|track|ul';
+const TYPE6 = new RegExp(`^ {0,3}</?(?:${TYPE6_NAMES})(?:[\\s>]|/>|$)`, 'i');
+function htmlType(value) {
+    if (TYPE1.test(value))
+        return 1;
+    if (/^ {0,3}<!--/.test(value))
+        return 2;
+    if (/^ {0,3}<\?/.test(value))
+        return 3;
+    if (/^ {0,3}<![A-Za-z]/.test(value))
+        return 4;
+    if (/^ {0,3}<!\[CDATA\[/i.test(value))
+        return 5;
+    if (TYPE6.test(value))
+        return 6;
+    // Parsed block HTML outside types 1–6 is CommonMark type 7 by definition.
+    return 7;
+}
+/** Returns source-backed HTML facts, classifying inline occurrences separately from block nodes. */
+export function markdownHtmlFacts(markdown) {
+    const facts = [];
+    const visit = (node, inBlockContainer) => {
+        if (node.type === 'html') {
+            const kind = inBlockContainer ? 'block' : 'inline';
+            facts.push({
+                kind,
+                commonMarkType: kind === 'block' ? htmlType(node.value) : null,
+                position: node.position,
+                value: node.value,
+            });
+        }
+        if (!('children' in node))
+            return;
+        const childIsBlockContainer = BLOCK_CONTAINERS.has(node.type);
+        for (const child of node.children)
+            visit(child, childIsBlockContainer);
+    };
+    visit(parseGfmMarkdown(markdown), true);
+    return facts;
+}
+/** Returns block HTML facts for CommonMark types 1, 6, and 7, preserving their parser bounds. */
+export function markdownHtmlBlocks(markdown) {
+    return markdownHtmlFacts(markdown).filter((fact) => fact.kind === 'block' &&
+        (fact.commonMarkType === 1 || fact.commonMarkType === 6 || fact.commonMarkType === 7));
+}

package/dist/markdown/index.d.mts

@@ -1,4 +1,6 @@
 export { findMarkdownNode, findMarkdownNodes, parseGfmMarkdown, walkMarkdown } from './ast.mts';
+export { markdownHtmlBlocks, markdownHtmlFacts } from './html-blocks.mts';
+export { markdownLiteralSpans } from './content-facts.mts';
 export { extractLooseMarkdownTableRows } from './loose-pipe-rows.mts';
 export { parseMarkdownSections } from './document-sections.mts';
 export { validateMarkdownSections } from './validate-sections.mts';
@@ -6,4 +8,5 @@ export type { MarkdownVisibleSection, MarkdownSectionsDiagnostic, MarkdownSectio
 export { markdownSectionBetweenHeadings } from './sections.mts';
 export { extractMarkdownTables, parseMarkdownTables } from './tables.mts';
 export { markdownNodeText } from './text.mts';
-export type { LooseMarkdownTableRow, LooseMarkdownTableRowsOptions, MarkdownNode, MarkdownSection, MarkdownSectionOptions, MarkdownTableRow, MarkdownTextOptions, ParseMarkdownTablesOptions, PositionedMarkdownTable, } from './types.mts';
+export { hasUncheckedMarkdownTask } from './tasks.mts';
+export type { LooseMarkdownTableRow, LooseMarkdownTableRowsOptions, MarkdownNode, MarkdownHtmlBlockType, MarkdownHtmlFact, MarkdownSourcePosition, MarkdownSourceSpan, MarkdownSection, MarkdownSectionOptions, MarkdownTableRow, MarkdownTextOptions, ParseMarkdownTablesOptions, PositionedMarkdownTable, } from './types.mts';

package/dist/markdown/index.mjs

@@ -1,7 +1,10 @@
 export { findMarkdownNode, findMarkdownNodes, parseGfmMarkdown, walkMarkdown } from './ast.mjs';
+export { markdownHtmlBlocks, markdownHtmlFacts } from './html-blocks.mjs';
+export { markdownLiteralSpans } from './content-facts.mjs';
 export { extractLooseMarkdownTableRows } from './loose-pipe-rows.mjs';
 export { parseMarkdownSections } from './document-sections.mjs';
 export { validateMarkdownSections } from './validate-sections.mjs';
 export { markdownSectionBetweenHeadings } from './sections.mjs';
 export { extractMarkdownTables, parseMarkdownTables } from './tables.mjs';
 export { markdownNodeText } from './text.mjs';
+export { hasUncheckedMarkdownTask } from './tasks.mjs';

package/dist/markdown/tasks.d.mts

@@ -0,0 +1,2 @@
+/** True when the GFM parse contains at least one unchecked task-list item. */
+export declare function hasUncheckedMarkdownTask(markdown: string): boolean;

package/dist/markdown/tasks.mjs

@@ -0,0 +1,10 @@
+import { parseGfmMarkdown, walkMarkdown } from './ast.mjs';
+/** True when the GFM parse contains at least one unchecked task-list item. */
+export function hasUncheckedMarkdownTask(markdown) {
+    let unchecked = false;
+    walkMarkdown(parseGfmMarkdown(markdown), (node) => {
+        if (node.type === 'listItem' && node.checked === false)
+            unchecked = true;
+    });
+    return unchecked;
+}

package/dist/markdown/types.d.mts

@@ -1,6 +1,33 @@
 import type { Heading, Root, RootContent } from 'mdast';
 import type { Position } from 'unist';
 export type MarkdownNode = Root | RootContent;
+/** A source range measured in JavaScript string offsets and 1-indexed source coordinates. */
+export type MarkdownSourcePosition = {
+    start: {
+        line: number;
+        column: number;
+        offset: number;
+    };
+    end: {
+        line: number;
+        column: number;
+        offset: number;
+    };
+};
+/** A source-backed Markdown span with no dependency on mdast node types. */
+export type MarkdownSourceSpan = {
+    kind: 'code' | 'inline-code' | 'html';
+    position: MarkdownSourcePosition;
+    value: string;
+};
+export type MarkdownHtmlBlockType = 1 | 2 | 3 | 4 | 5 | 6 | 7;
+/** HTML parser facts distinguish block parsing from inline HTML in a phrasing container. */
+export type MarkdownHtmlFact = {
+    commonMarkType: MarkdownHtmlBlockType | null;
+    kind: 'block' | 'inline';
+    position: MarkdownSourcePosition;
+    value: string;
+};
 export type MarkdownTableRow = {
     cells: string[];
     line: number;

package/dist/openapi-document/build-openapi-query.mjs

@@ -9,7 +9,7 @@ function queryParameter(name, descriptor) {
     return {
         name,
         in: 'query',
-        required: false,
+        required: descriptor.required === true,
         ...(descriptor.description ? { description: descriptor.description } : {}),
         ...(descriptor.kind === 'csv-array'
             ? { style: descriptor.style, explode: descriptor.explode }

package/dist/openapi-document/openapi-types.d.mts

@@ -29,7 +29,7 @@ export type OpenApiParameter = {
 } | {
     name: string;
     in: 'query';
-    required: false;
+    required: boolean;
     description?: string;
     style?: 'form';
     explode?: false;

package/dist/openapi-document/query-types.d.mts

@@ -1,4 +1,4 @@
-export type OpenApiQueryParameter = {
+export type OpenApiQueryParameterShape = {
     kind: 'string';
     format?: 'uuid' | 'uri';
     description?: string;
@@ -27,9 +27,15 @@ export type OpenApiQueryParameter = {
     description?: string;
 } | {
     kind: 'csv-array';
-    items: OpenApiQueryParameter;
+    items: OpenApiQueryParameterShape & {
+        required?: never;
+    };
     style: 'form';
     explode: false;
     description?: string;
 };
+/** Top-level parameters may be `required: true`; array `items` never are. */
+export type OpenApiQueryParameter = OpenApiQueryParameterShape & {
+    required?: true;
+};
 export type OpenApiQueryContract = Readonly<Record<string, OpenApiQueryParameter>>;

package/dist/post-publication-inventory/index.d.mts

@@ -0,0 +1,5 @@
+export { analyzePostPublicationWriterSource } from './writers/source.mts';
+export type { PostPublicationWriterSourceAnalysis } from './writers/source.mts';
+export type { PostPublicationWriterSourceOptions } from './writers/types.mts';
+export { extractStaticSqlTemplateQuasis } from './readers/sql-source.mts';
+export type { ReaderSqlTemplateOptions } from './readers/sql-template.mts';

package/dist/post-publication-inventory/index.mjs

@@ -0,0 +1,2 @@
+export { analyzePostPublicationWriterSource } from './writers/source.mjs';
+export { extractStaticSqlTemplateQuasis } from './readers/sql-source.mjs';

package/dist/post-publication-inventory/readers/sql-executors.d.mts

@@ -0,0 +1,3 @@
+import ts from '../../contract-schema/typescript-api.mts';
+import { type ReaderSqlTemplateOptions } from './sql-template.mts';
+export declare function terminalSqlExecutorBindings(ast: ts.SourceFile, options: ReaderSqlTemplateOptions): Set<string>;

package/dist/post-publication-inventory/readers/sql-executors.mjs

@@ -0,0 +1,32 @@
+import ts from '../../contract-schema/typescript-api.mjs';
+import { identifierName, unparenthesized, walk, } from './sql-template.mjs';
+export function terminalSqlExecutorBindings(ast, options) {
+    const bindings = new Set();
+    walk(ast, (node) => {
+        if (!ts.isImportDeclaration(node) || !ts.isStringLiteral(node.moduleSpecifier))
+            return;
+        const names = options.executorImports.get(node.moduleSpecifier.text);
+        const importClause = node.importClause;
+        const specifiers = importClause?.namedBindings;
+        if (importClause?.isTypeOnly)
+            return;
+        if (!names || !specifiers || !ts.isNamedImports(specifiers))
+            return;
+        for (const specifier of specifiers.elements) {
+            if (!specifier.isTypeOnly && names.has((specifier.propertyName ?? specifier.name).text))
+                bindings.add(specifier.name.text);
+        }
+    });
+    walk(ast, (node) => {
+        if (!ts.isVariableDeclaration(node) || !ts.isIdentifier(node.name))
+            return;
+        const initializer = node.initializer && unparenthesized(node.initializer);
+        if (!initializer || !ts.isConditionalExpression(initializer))
+            return;
+        const consequent = identifierName(initializer.whenTrue);
+        const alternate = identifierName(initializer.whenFalse);
+        if ((consequent && bindings.has(consequent)) || (alternate && bindings.has(alternate)))
+            bindings.add(node.name.text);
+    });
+    return bindings;
+}

package/dist/post-publication-inventory/readers/sql-source.d.mts

@@ -0,0 +1,7 @@
+import { type ReaderSqlTemplateOptions } from './sql-template.mts';
+/**
+ * Collect static SQL fragments returned, exported, or passed to configured executors.
+ * Interpolations become numbered placeholders; local append chains are reassembled.
+ * This preserves name-based collection heuristics, not binding or control-flow proof.
+ */
+export declare function extractStaticSqlTemplateQuasis(content: string, options: ReaderSqlTemplateOptions): string[];