vouchington-tooling 0.33.0 → 0.35.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.collectionPathLabel ?? 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.collectionPathLabel ?? config.collectionLabel, new Set(effectiveSingleTypeRouteConfigs.map((routeConfig) => routeConfig.pluralPath)), readTracked, config.collectionPathLiteralPattern);
+    }
+    checkUnionFactories(errors, files.unionDetailPages, readTracked, config, slugToType, routeSlugs);
+}

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[];

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

@@ -0,0 +1,87 @@
+import ts from '../../contract-schema/typescript-api.mjs';
+import { terminalSqlExecutorBindings } from './sql-executors.mjs';
+import { identifierName, staticComputedPropertyName, staticSqlTemplateText, unparenthesized, walk, } from './sql-template.mjs';
+/**
+ * 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 function extractStaticSqlTemplateQuasis(content, options) {
+    // TypeScript's source-file parser recovers from syntax errors. Reject those first,
+    // preserving the previous strict parser's failure contract instead of trusting recovery.
+    const result = ts.transpileModule(content, {
+        fileName: 'reader.mts',
+        reportDiagnostics: true,
+        compilerOptions: { target: ts.ScriptTarget.ESNext, module: ts.ModuleKind.ESNext },
+    });
+    if (result.diagnostics?.length)
+        throw new SyntaxError(ts.flattenDiagnosticMessageText(result.diagnostics[0].messageText, '\n'));
+    const ast = ts.createSourceFile('reader.mts', content, ts.ScriptTarget.Latest, true);
+    const executors = terminalSqlExecutorBindings(ast, options);
+    const statements = new Map();
+    const consumed = new Set();
+    const direct = [];
+    walk(ast, (node) => {
+        if (!ts.isVariableDeclaration(node))
+            return;
+        const binding = identifierName(node.name);
+        const text = staticSqlTemplateText(node.initializer, options);
+        if (binding && text)
+            statements.set(binding, { text, offset: node.getStart(ast) });
+    });
+    walk(ast, (node) => {
+        if (ts.isVariableStatement(node) &&
+            node.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword)) {
+            for (const declaration of node.declarationList.declarations) {
+                const binding = identifierName(declaration.name);
+                if (binding)
+                    consumed.add(binding);
+            }
+        }
+        if (ts.isReturnStatement(node) && node.expression) {
+            const binding = identifierName(node.expression);
+            if (binding)
+                consumed.add(binding);
+            const text = staticSqlTemplateText(node.expression, options);
+            if (text)
+                direct.push(text);
+            return;
+        }
+        if (!ts.isCallExpression(node))
+            return;
+        const callee = unparenthesized(node.expression);
+        if (!ts.isIdentifier(callee) || !executors.has(callee.text))
+            return;
+        for (const argument of node.arguments) {
+            const binding = identifierName(argument);
+            if (binding)
+                consumed.add(binding);
+            const text = staticSqlTemplateText(argument, options);
+            if (text)
+                direct.push(text);
+        }
+    });
+    walk(ast, (node) => {
+        if (!ts.isCallExpression(node))
+            return;
+        const callee = unparenthesized(node.expression);
+        if (!ts.isPropertyAccessExpression(callee) && !ts.isElementAccessExpression(callee))
+            return;
+        const method = ts.isPropertyAccessExpression(callee)
+            ? callee.name.text
+            : callee.argumentExpression
+                ? staticComputedPropertyName(callee.argumentExpression)
+                : undefined;
+        if (method !== options.appendMethod)
+            return;
+        const receiver = identifierName(callee.expression);
+        const statement = receiver ? statements.get(receiver) : undefined;
+        const appended = staticSqlTemplateText(node.arguments[0], options);
+        if (statement && appended && node.getStart(ast) > statement.offset)
+            statement.text += appended;
+    });
+    return [
+        ...direct,
+        ...[...statements].flatMap(([binding, statement]) => consumed.has(binding) ? [statement.text] : []),
+    ];
+}

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

@@ -0,0 +1,12 @@
+import ts from '../../contract-schema/typescript-api.mts';
+export interface ReaderSqlTemplateOptions {
+    readonly templateTag: string;
+    readonly appendMethod: string;
+    readonly executorImports: ReadonlyMap<string, ReadonlySet<string>>;
+    readonly placeholderPrefix: string;
+}
+export declare function identifierName(node: ts.Node): string | undefined;
+export declare function staticComputedPropertyName(node: ts.Node): string | undefined;
+export declare function unparenthesized(node: ts.Node): ts.Node;
+export declare function staticSqlTemplateText(node: ts.Node | undefined, options: ReaderSqlTemplateOptions): string | undefined;
+export declare function walk(root: ts.Node, visit: (node: ts.Node) => void): void;