vouchington-tooling 0.32.0 → 0.34.0

package/dist/contract-schema/type-query-api.mjs

@@ -0,0 +1,10 @@
+export function programForQuery(program) {
+    return program;
+}
+export function validateTypeScriptApi(typescript, program, sourceFile) {
+    if (!typescript.isSourceFile(sourceFile) ||
+        sourceFile.kind !== typescript.SyntaxKind.SourceFile) {
+        throw new Error('TypeScript API does not recognize the supplied Program source file; pass the same compiler API instance that created the Program');
+    }
+    program.getTypeChecker();
+}

package/dist/contract-schema/type-query-call.d.mts

@@ -0,0 +1,16 @@
+import { type TypeFacts, type TypeFactsRequest } from './type-query.mts';
+import { type TypeScriptApi, type TypeScriptProgram } from './type-query-api.mts';
+export interface CallRowTypeFactsRequest extends TypeFactsRequest {
+    readonly program: TypeScriptProgram;
+    readonly typescript: TypeScriptApi;
+    readonly fileName: string;
+    readonly calleeText: string;
+    readonly rowSource: 'typeArgument' | 'awaitedRows';
+    readonly typeArgumentIndex?: number;
+    readonly typeArgumentText?: string;
+}
+export interface CallRowTypeFacts extends TypeFacts {
+    readonly line: number;
+    readonly column: number;
+}
+export declare function getCallRowTypeFacts(request: CallRowTypeFactsRequest): CallRowTypeFacts[];

package/dist/contract-schema/type-query-call.mjs

@@ -0,0 +1,52 @@
+import { sourceFileForQuery } from './type-query-export.mjs';
+import { factsForType } from './type-query.mjs';
+import { programForQuery, validateTypeScriptApi, } from './type-query-api.mjs';
+function rowType(typescript, checker, sourceFile, call, request) {
+    if (request.rowSource === 'typeArgument') {
+        const typeArgument = call.typeArguments?.[request.typeArgumentIndex ?? 0];
+        if (!typeArgument) {
+            throw new Error(`Missing row type argument for call "${request.calleeText}" in "${sourceFile.fileName}"`);
+        }
+        return { type: checker.getTypeFromTypeNode(typeArgument), at: typeArgument };
+    }
+    const result = checker.getAwaitedType(checker.getTypeAtLocation(call));
+    if (result && result.flags & (typescript.TypeFlags.Any | typescript.TypeFlags.Never))
+        return { type: result, at: call };
+    const rowsProperty = result && checker.getPropertyOfType(result, 'rows');
+    const rows = rowsProperty
+        ? checker.getTypeOfSymbolAtLocation(rowsProperty, call)
+        : result && checker.getIndexTypeOfType(result, typescript.IndexKind.String);
+    if (rows && rows.flags & (typescript.TypeFlags.Any | typescript.TypeFlags.Never)) {
+        return { type: rows, at: call };
+    }
+    const element = rows && checker.getIndexTypeOfType(rows, typescript.IndexKind.Number);
+    if (!element) {
+        throw new Error(`Missing awaited rows element for call "${request.calleeText}" in "${sourceFile.fileName}"`);
+    }
+    return { type: element, at: call };
+}
+export function getCallRowTypeFacts(request) {
+    const program = programForQuery(request.program);
+    const sourceFile = sourceFileForQuery(program, request.fileName);
+    validateTypeScriptApi(request.typescript, request.program, sourceFile);
+    const checker = program.getTypeChecker();
+    const facts = [];
+    function visit(node) {
+        if (request.typescript.isCallExpression(node) &&
+            node.expression.getText(sourceFile) === request.calleeText) {
+            const selectedText = node.typeArguments?.[request.typeArgumentIndex ?? 0]?.getText(sourceFile);
+            if (request.typeArgumentText === undefined || selectedText === request.typeArgumentText) {
+                const row = rowType(request.typescript, checker, sourceFile, node, request);
+                const location = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
+                facts.push({
+                    line: location.line + 1,
+                    column: location.character + 1,
+                    ...factsForType(request.typescript, program, checker, row.type, row.at, request),
+                });
+            }
+        }
+        request.typescript.forEachChild(node, visit);
+    }
+    visit(sourceFile);
+    return facts;
+}

package/dist/contract-schema/type-query-export.d.mts

@@ -0,0 +1,10 @@
+import type ts from './typescript-api.mts';
+import type { TypeScriptApi } from './type-query-api.mts';
+export interface ExportedTypeSelector {
+    readonly fileName: string;
+    readonly exportName: string;
+}
+export declare function sourceFileForQuery(program: ts.Program, fileName: string): ts.SourceFile;
+export declare function exportedType(typescript: TypeScriptApi, program: ts.Program, checker: ts.TypeChecker, selector: ExportedTypeSelector): ts.Type;
+export declare function exportedAssignableType(typescript: TypeScriptApi, program: ts.Program, checker: ts.TypeChecker, selector: ExportedTypeSelector): ts.Type;
+export declare function exportedDefaultType(typescript: TypeScriptApi, program: ts.Program, checker: ts.TypeChecker, selector: ExportedTypeSelector, parameterIndex: number): ts.Type;

package/dist/contract-schema/type-query-export.mjs

@@ -0,0 +1,91 @@
+export function sourceFileForQuery(program, fileName) {
+    const sourceFile = program.getSourceFile(fileName);
+    if (!sourceFile)
+        throw new Error(`Type-query source file "${fileName}" is not in the program`);
+    return sourceFile;
+}
+function exportedSymbol(typescript, checker, sourceFile, exportName) {
+    const moduleSymbol = checker.getSymbolAtLocation(sourceFile);
+    const exported = moduleSymbol &&
+        checker.getExportsOfModule(moduleSymbol).find((candidate) => candidate.name === exportName);
+    if (!exported) {
+        throw new Error(`Missing export "${exportName}" in "${sourceFile.fileName}"`);
+    }
+    return exported.flags & typescript.SymbolFlags.Alias
+        ? checker.getAliasedSymbol(exported)
+        : exported;
+}
+export function exportedType(typescript, program, checker, selector) {
+    const sourceFile = sourceFileForQuery(program, selector.fileName);
+    const symbol = exportedSymbol(typescript, checker, sourceFile, selector.exportName);
+    const declaration = symbol.valueDeclaration ?? symbol.declarations?.[0];
+    if (!declaration) {
+        throw new Error(`Export "${selector.exportName}" in "${selector.fileName}" could not be resolved to a declaration`);
+    }
+    if (symbol.flags & typescript.SymbolFlags.Type)
+        return checker.getDeclaredTypeOfSymbol(symbol);
+    return checker.getTypeOfSymbolAtLocation(symbol, declaration);
+}
+export function exportedAssignableType(typescript, program, checker, selector) {
+    const sourceFile = sourceFileForQuery(program, selector.fileName);
+    const symbol = exportedSymbol(typescript, checker, sourceFile, selector.exportName);
+    const genericDeclaration = symbol.declarations?.some((declaration) => {
+        const isGenericTypeDeclaration = typescript.isClassDeclaration(declaration) ||
+            typescript.isInterfaceDeclaration(declaration) ||
+            typescript.isTypeAliasDeclaration(declaration);
+        return (isGenericTypeDeclaration &&
+            Boolean(declaration.typeParameters?.length));
+    });
+    const type = exportedType(typescript, program, checker, selector);
+    const defaultedSignature = [...type.getCallSignatures(), ...type.getConstructSignatures()].some((signature) => signature.getDeclaration()?.typeParameters?.some((parameter) => parameter.default));
+    if (genericDeclaration ||
+        (!(symbol.flags & typescript.SymbolFlags.Value) && defaultedSignature)) {
+        throw new Error(`Assignable target "${selector.exportName}" in "${selector.fileName}" has generic or defaulted type parameters; export and select a named instantiated type instead`);
+    }
+    return type;
+}
+export function exportedDefaultType(typescript, program, checker, selector, parameterIndex) {
+    const sourceFile = sourceFileForQuery(program, selector.fileName);
+    const symbol = exportedSymbol(typescript, checker, sourceFile, selector.exportName);
+    const directDeclaration = symbol.declarations?.find((declaration) => !typescript.isFunctionDeclaration(declaration) &&
+        (typescript.isClassDeclaration(declaration) ||
+            typescript.isInterfaceDeclaration(declaration) ||
+            typescript.isTypeAliasDeclaration(declaration)));
+    const directParameters = directDeclaration?.typeParameters;
+    const type = exportedType(typescript, program, checker, selector);
+    const signatureParameters = [
+        ...type.getCallSignatures(),
+        ...type.getConstructSignatures(),
+    ][0]?.getDeclaration()?.typeParameters;
+    const parameters = directParameters !== undefined ? directParameters : signatureParameters;
+    const defaultNode = parameters?.[parameterIndex]?.default;
+    if (!defaultNode) {
+        throw new Error(`Missing default for type parameter ${parameterIndex} of export "${selector.exportName}" in "${selector.fileName}"`);
+    }
+    if (typescript.isTypeReferenceNode(defaultNode) &&
+        typescript.isIdentifier(defaultNode.typeName)) {
+        const referencedName = defaultNode.typeName.text;
+        const previousIndex = parameters?.findIndex((parameter, index) => index < parameterIndex && parameter.name.text === referencedName);
+        if (previousIndex !== undefined && previousIndex >= 0 && parameters?.[previousIndex]?.default) {
+            return exportedDefaultType(typescript, program, checker, selector, previousIndex);
+        }
+    }
+    const previousSymbols = new Set(parameters
+        ?.slice(0, parameterIndex)
+        .map((parameter) => checker.getSymbolAtLocation(parameter.name))
+        .filter((symbol) => symbol !== undefined));
+    let hasDependentReference = false;
+    function visit(node) {
+        const symbol = typescript.isIdentifier(node) ? checker.getSymbolAtLocation(node) : undefined;
+        if (symbol && previousSymbols.has(symbol)) {
+            hasDependentReference = true;
+            return;
+        }
+        typescript.forEachChild(node, visit);
+    }
+    visit(defaultNode);
+    if (hasDependentReference) {
+        throw new Error(`Unsupported dependent composite default for type parameter ${parameterIndex} of export "${selector.exportName}" in "${selector.fileName}"; export and query a named instantiated type instead`);
+    }
+    return checker.getTypeAtLocation(defaultNode);
+}

package/dist/contract-schema/type-query.d.mts

@@ -0,0 +1,22 @@
+import type ts from './typescript-api.mts';
+import { type ExportedTypeSelector } from './type-query-export.mts';
+import { type TypeScriptApi, type TypeScriptProgram } from './type-query-api.mts';
+export type { ExportedTypeSelector } from './type-query-export.mts';
+export type { TypeScriptApi, TypeScriptProgram } from './type-query-api.mts';
+export interface TypeFactsRequest {
+    readonly propertyNames?: readonly string[];
+    readonly assignableTo?: Readonly<Record<string, ExportedTypeSelector>>;
+}
+export interface TypeFacts {
+    readonly display: string;
+    readonly isAny: boolean;
+    readonly properties: Readonly<Record<string, string | undefined>>;
+    readonly assignableTo: Readonly<Record<string, boolean>>;
+}
+export interface ExportedTypeFactsRequest extends ExportedTypeSelector, TypeFactsRequest {
+    readonly program: TypeScriptProgram;
+    readonly typescript: TypeScriptApi;
+    readonly defaultTypeParameterIndex?: number;
+}
+export declare function factsForType(typescript: TypeScriptApi, program: ts.Program, checker: ts.TypeChecker, type: ts.Type, at: ts.Node, request: TypeFactsRequest): TypeFacts;
+export declare function getExportedTypeFacts(request: ExportedTypeFactsRequest): TypeFacts;

package/dist/contract-schema/type-query.mjs

@@ -0,0 +1,39 @@
+import { exportedAssignableType, exportedDefaultType, exportedType, sourceFileForQuery, } from './type-query-export.mjs';
+import { programForQuery, validateTypeScriptApi, } from './type-query-api.mjs';
+export function factsForType(typescript, program, checker, type, at, request) {
+    const properties = Object.fromEntries([...new Set(request.propertyNames ?? [])].sort().map((name) => {
+        const property = checker.getPropertyOfType(type, name);
+        const numericName = Number(name);
+        const numericKey = name.trim() !== '' && String(numericName) === name;
+        const propertyType = property
+            ? checker.getTypeOfSymbolAtLocation(property, at)
+            : (checker.getIndexTypeOfType(type, numericKey ? typescript.IndexKind.Number : typescript.IndexKind.String) ??
+                (numericKey ? checker.getIndexTypeOfType(type, typescript.IndexKind.String) : undefined));
+        const display = propertyType
+            ? checker.typeToString(propertyType, undefined, typescript.TypeFormatFlags.NoTruncation)
+            : undefined;
+        return [name, display];
+    }));
+    const assignableTo = Object.fromEntries(Object.entries(request.assignableTo ?? {})
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([label, target]) => [
+        label,
+        checker.isTypeAssignableTo(type, exportedAssignableType(typescript, program, checker, target)),
+    ]));
+    return {
+        display: checker.typeToString(type, undefined, typescript.TypeFormatFlags.NoTruncation),
+        isAny: Boolean(type.flags & typescript.TypeFlags.Any),
+        properties,
+        assignableTo,
+    };
+}
+export function getExportedTypeFacts(request) {
+    const program = programForQuery(request.program);
+    const checker = program.getTypeChecker();
+    const sourceFile = sourceFileForQuery(program, request.fileName);
+    validateTypeScriptApi(request.typescript, request.program, sourceFile);
+    const type = request.defaultTypeParameterIndex === undefined
+        ? exportedType(request.typescript, program, checker, request)
+        : exportedDefaultType(request.typescript, program, checker, request, request.defaultTypeParameterIndex);
+    return factsForType(request.typescript, program, checker, type, sourceFile, request);
+}

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

@@ -0,0 +1,9 @@
+import ts from '@typescript/typescript6';
+export declare function collectCallExpressions(content: string, file: string): ts.CallExpression[];
+export declare function findConstObjectLiteral(content: string, name: string, file: string): ts.ObjectLiteralExpression;
+export declare function hasConfiguredObjectDeclaration(content: string, name: string, file: string): boolean;
+export declare function findTypeAliasDeclaration(content: string, name: string, file: string): ts.TypeAliasDeclaration;
+export declare function getCallExpressionName(expression: ts.Expression): string | undefined;
+export declare function getPropertyNameText(name: ts.PropertyName): string | undefined;
+export declare function getStringLiteralValue(node: ts.Node | undefined): string | undefined;
+export declare function unwrapExpression<T extends ts.Node>(node: T): T;

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

@@ -0,0 +1,94 @@
+import ts from '@typescript/typescript6';
+export function collectCallExpressions(content, file) {
+    const sourceFile = createSourceFile(content, file);
+    const calls = [];
+    walkAst(sourceFile, (node) => {
+        if (ts.isCallExpression(node))
+            calls.push(node);
+    });
+    return calls;
+}
+export function findConstObjectLiteral(content, name, file) {
+    const sourceFile = createSourceFile(content, file);
+    const declaration = findConstVariableDeclaration(sourceFile, name);
+    if (!declaration)
+        throw new Error(`${file}: could not find ${name}`);
+    const initializer = declaration.initializer && unwrapExpression(declaration.initializer);
+    if (!initializer || !ts.isObjectLiteralExpression(initializer))
+        throw new Error(`${file}: could not find ${name}`);
+    if (!initializer.getText(sourceFile).trimEnd().endsWith('}'))
+        throw new Error(`${file}: could not find end of ${name}`);
+    return initializer;
+}
+export function hasConfiguredObjectDeclaration(content, name, file) {
+    const sourceFile = createSourceFile(content, file);
+    return sourceFile.statements.some((statement) => ts.isVariableStatement(statement) &&
+        statement.declarationList.declarations.some((declaration) => ts.isIdentifier(declaration.name) && declaration.name.text === name));
+}
+export function findTypeAliasDeclaration(content, name, file) {
+    const sourceFile = createSourceFile(content, file);
+    for (const statement of sourceFile.statements) {
+        if (ts.isTypeAliasDeclaration(statement) && statement.name.text === name)
+            return statement;
+    }
+    throw new Error(`${file}: could not parse ${name} union`);
+}
+export function getCallExpressionName(expression) {
+    const node = unwrapExpression(expression);
+    if (ts.isIdentifier(node))
+        return node.text;
+    if (ts.isPropertyAccessExpression(node))
+        return node.name.text;
+    if (ts.isElementAccessExpression(node))
+        return getStringLiteralValue(node.argumentExpression);
+    return undefined;
+}
+export function getPropertyNameText(name) {
+    if (ts.isIdentifier(name))
+        return name.text;
+    if (ts.isStringLiteral(name))
+        return name.text;
+    if (ts.isNumericLiteral(name))
+        return name.text;
+    return undefined;
+}
+export function getStringLiteralValue(node) {
+    if (!node)
+        return undefined;
+    const value = unwrapExpression(node);
+    if (ts.isStringLiteral(value) || ts.isNoSubstitutionTemplateLiteral(value))
+        return value.text;
+    return undefined;
+}
+export function unwrapExpression(node) {
+    let current = node;
+    while (ts.isParenthesizedExpression(current) ||
+        ts.isAsExpression(current) ||
+        ts.isTypeAssertionExpression(current) ||
+        ts.isSatisfiesExpression(current) ||
+        ts.isNonNullExpression(current)) {
+        current = current.expression;
+    }
+    return current;
+}
+function walkAst(node, onNode) {
+    onNode(node);
+    ts.forEachChild(node, (child) => walkAst(child, onNode));
+}
+function createSourceFile(content, file) {
+    const scriptKind = file.endsWith('.tsx') || file.endsWith('.jsx') ? ts.ScriptKind.TSX : ts.ScriptKind.TS;
+    return ts.createSourceFile(file, content, ts.ScriptTarget.Latest, true, scriptKind);
+}
+function findConstVariableDeclaration(sourceFile, name) {
+    for (const statement of sourceFile.statements) {
+        if (!ts.isVariableStatement(statement))
+            continue;
+        if ((statement.declarationList.flags & ts.NodeFlags.Const) === 0)
+            continue;
+        for (const declaration of statement.declarationList.declarations) {
+            if (ts.isIdentifier(declaration.name) && declaration.name.text === name)
+                return declaration;
+        }
+    }
+    return undefined;
+}

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

@@ -0,0 +1,3 @@
+import type { SharedContext } from '../shared-context/index.mts';
+import type { FiniteEnumRippleConfig } from './model.mts';
+export declare function checkFiniteEnumRipple(ctx: SharedContext, config: FiniteEnumRippleConfig): string[];

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

@@ -0,0 +1,62 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { checkStructuredTypes } from './types.mjs';
+import { checkUnionTypes } from './union-types.mjs';
+import { escapeWorkflowData, finiteEnumError } from './compare.mjs';
+export function checkFiniteEnumRipple(ctx, config) {
+    const errors = [];
+    const readTracked = (file) => {
+        if (!config.files.existingFileSet.has(file))
+            throw new Error(`Not tracked: ${file}`);
+        const content = ctx.readTrackedFile?.(file);
+        if (content !== undefined) {
+            if (content === null)
+                throw new Error(`Cannot read tracked file: ${file}`);
+            return content;
+        }
+        try {
+            return readFileSync(join(ctx.repoRoot, file), 'utf8');
+        }
+        catch (cause) {
+            throw new Error(`${file}: ${String(cause)}`);
+        }
+    };
+    if (config.structured) {
+        try {
+            checkStructuredTypes(errors, config.files, readTracked, config.structured);
+        }
+        catch (cause) {
+            errors.push(familyError(cause, config.structured.backendPath, config.files, [
+                config.structured.webPath,
+                config.structured.routeConfigsPath,
+            ]));
+        }
+    }
+    if (config.union) {
+        try {
+            checkUnionTypes(errors, config.files, readTracked, config.union);
+        }
+        catch (cause) {
+            errors.push(familyError(cause, config.union.typesPath, config.files, [config.union.routeConfigsPath]));
+        }
+    }
+    return errors.map((error) => `${error}${escapeWorkflowData(config.diagnosticSuffix ?? '')}`);
+}
+function familyError(cause, defaultFile, files, otherPaths) {
+    const message = String(cause instanceof Error ? cause.message : cause);
+    const selectedPaths = [
+        defaultFile,
+        ...otherPaths,
+        ...files.structuredDetailPages.map((page) => page.file),
+        ...files.structuredCollectionPages.map((page) => page.file),
+        ...files.structuredComponentFiles.map((page) => page.file),
+        ...files.unionDetailPages.map((page) => page.file),
+        ...files.unionCollectionPages.map((page) => page.file),
+        ...files.unionCreatePages.map((page) => page.file),
+    ];
+    const file = [...selectedPaths]
+        .sort((a, b) => b.length - a.length)
+        .find((path) => message.startsWith(`${path}:`) || message.endsWith(`: ${path}`)) ??
+        defaultFile;
+    return finiteEnumError(file, message.startsWith(`${file}: `) ? message.slice(file.length + 2) : message);
+}

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

@@ -0,0 +1,20 @@
+import type { FiniteEnumFiles, ReadTrackedFile, RoutedPage } from './model.mts';
+export declare function hasAllFiles(files: FiniteEnumFiles, paths: readonly string[]): boolean;
+export declare function checkUnionCreatePageTypes(errors: string[], routeConfigs: {
+    pluralPath: string;
+    unionTypes: string[];
+}[], pages: readonly RoutedPage[], readTracked: ReadTrackedFile, createPageTypeProperties: readonly string[], label: string): void;
+export declare function checkCollectionPagePathLiterals(pages: readonly RoutedPage[], errors: string[], group: string, routeSlugs: ReadonlySet<string>, readTracked: ReadTrackedFile, pathPattern: RegExp): void;
+export declare function compareSets(errors: string[], options: {
+    label: string;
+    actualLabel: string;
+    actualFile: string;
+    actualValues: readonly string[];
+    expectedLabel: string;
+    expectedFile: string;
+    expectedValues: readonly string[];
+}): void;
+export declare function uniqueSorted(values: readonly string[]): string[];
+export declare function routePageSlugs(pages: readonly RoutedPage[], topOnly?: boolean): string[];
+export declare function finiteEnumError(file: string, message: string): string;
+export declare function escapeWorkflowData(value: string): string;

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

@@ -0,0 +1,90 @@
+import { collectCreatePageLiterals } from './create-page-literals.mjs';
+import { collectActivePatternCaptures } from './pattern-captures.mjs';
+export function hasAllFiles(files, paths) {
+    return paths.every((file) => files.existingFileSet.has(file));
+}
+export function checkUnionCreatePageTypes(errors, routeConfigs, pages, readTracked, createPageTypeProperties, label) {
+    const typeByPluralPath = new Map(routeConfigs.flatMap((config) => config.unionTypes.length === 1 ? [[config.pluralPath, config.unionTypes[0]]] : []));
+    for (const page of pages) {
+        const expectedType = typeByPluralPath.get(page.slug);
+        if (expectedType === undefined) {
+            errors.push(finiteEnumError(page.file, `${label} create page has no matching single-type route config for "${page.slug}"`));
+            continue;
+        }
+        const content = readTracked(page.file);
+        const actualTypes = collectCreatePageLiterals(content, page.file, createPageTypeProperties);
+        if (actualTypes.length === 0)
+            errors.push(finiteEnumError(page.file, `${label} create page has no inspectable type literal`));
+        for (const actualType of actualTypes) {
+            if (actualType === expectedType)
+                continue;
+            errors.push(finiteEnumError(page.file, `${label} create page literal uses "${actualType}" but ${page.slug} expects "${expectedType}"`));
+        }
+    }
+}
+export function checkCollectionPagePathLiterals(pages, errors, group, routeSlugs, readTracked, pathPattern) {
+    for (const page of pages) {
+        if (!routeSlugs.has(page.slug))
+            continue;
+        const content = readTracked(page.file);
+        for (const literalPath of collectActivePatternCaptures(content, pathPattern, page.file)) {
+            if (literalPath === page.slug || literalPath.startsWith(`${page.slug}/`))
+                continue;
+            errors.push(finiteEnumError(page.file, `${group} collection path literal "/${literalPath}" does not match route directory "${page.slug}"`));
+        }
+    }
+}
+export function compareSets(errors, options) {
+    for (const duplicate of duplicateValues(options.actualValues)) {
+        errors.push(finiteEnumError(options.actualFile, `${options.label} duplicate in actual values: ${duplicate}`));
+    }
+    for (const duplicate of duplicateValues(options.expectedValues)) {
+        errors.push(finiteEnumError(options.expectedFile, `${options.label} duplicate in expected values: ${duplicate}`));
+    }
+    const actual = uniqueSorted(options.actualValues);
+    const expected = uniqueSorted(options.expectedValues);
+    const missing = expected.filter((value) => !actual.includes(value));
+    const extra = actual.filter((value) => !expected.includes(value));
+    if (missing.length === 0 && extra.length === 0)
+        return;
+    const parts = [
+        `${options.label} mismatch`,
+        missing.length > 0 ? `missing from ${options.actualLabel}: ${missing.join(', ')}` : '',
+        extra.length > 0 ? `stale in ${options.actualLabel}: ${extra.join(', ')}` : '',
+        `expected from ${options.expectedLabel}: ${expected.join(', ')}`,
+    ].filter(Boolean);
+    errors.push(finiteEnumError(options.actualFile, parts.join('; ')));
+}
+export function uniqueSorted(values) {
+    return [...new Set(values)].toSorted();
+}
+export function routePageSlugs(pages, topOnly = false) {
+    const slugs = new Set();
+    for (const page of pages) {
+        if (!topOnly || page.isTopLevel)
+            slugs.add(page.slug);
+    }
+    return [...slugs].toSorted();
+}
+function duplicateValues(values) {
+    const seen = new Set();
+    const duplicates = new Set();
+    for (const value of values) {
+        if (seen.has(value))
+            duplicates.add(value);
+        seen.add(value);
+    }
+    return [...duplicates].toSorted();
+}
+export function finiteEnumError(file, message) {
+    const escapeProperty = (value) => value
+        .replaceAll('%', '%25')
+        .replaceAll('\r', '%0D')
+        .replaceAll('\n', '%0A')
+        .replaceAll(':', '%3A')
+        .replaceAll(',', '%2C');
+    return `::error file=${escapeProperty(file)}::${escapeWorkflowData(`${file}: ${message}.`)}`;
+}
+export function escapeWorkflowData(value) {
+    return value.replaceAll('%', '%25').replaceAll('\r', '%0D').replaceAll('\n', '%0A');
+}

package/dist/finite-enum-ripple/component-paths.d.mts

@@ -0,0 +1,8 @@
+import type { ReadTrackedFile } from './model.mts';
+export declare function checkStructuredCollectionComponentPathLiterals(errors: string[], routeConfigs: {
+    pluralPath: string;
+    singularPath: string;
+}[], componentFiles: readonly {
+    file: string;
+    slug: string;
+}[], ignoredNavigationPaths: ReadonlySet<string>, readTracked: ReadTrackedFile, label: string, navigationPattern: RegExp): void;

package/dist/finite-enum-ripple/component-paths.mjs

@@ -0,0 +1,30 @@
+import { collectActivePatternCaptures } from './pattern-captures.mjs';
+import { finiteEnumError } from './compare.mjs';
+export function checkStructuredCollectionComponentPathLiterals(errors, routeConfigs, componentFiles, ignoredNavigationPaths, readTracked, label, navigationPattern) {
+    const configByPluralPath = new Map(routeConfigs.map((config) => [config.pluralPath, config]));
+    for (const { file, slug } of componentFiles) {
+        const config = configByPluralPath.get(slug);
+        if (!config) {
+            errors.push(finiteEnumError(file, `${label} component has no matching route config for "${slug}"`));
+            continue;
+        }
+        const content = readTracked(file);
+        for (const literalPath of collectNavigationPathLiterals(content, file, ignoredNavigationPaths, navigationPattern)) {
+            if (matchesConfiguredPath(literalPath, config.pluralPath) ||
+                matchesConfiguredPath(literalPath, config.singularPath))
+                continue;
+            errors.push(finiteEnumError(file, `${label} component navigation path "/${literalPath}" does not match route config "${config.singularPath}" or "${config.pluralPath}"`));
+        }
+    }
+}
+function matchesConfiguredPath(literalPath, configuredPath) {
+    return literalPath === configuredPath || literalPath.startsWith(`${configuredPath}/`);
+}
+function collectNavigationPathLiterals(content, file, ignoredPaths, pattern) {
+    const paths = [];
+    for (const literalPath of collectActivePatternCaptures(content, pattern, file)) {
+        if (!ignoredPaths.has(literalPath))
+            paths.push(literalPath);
+    }
+    return paths;
+}

package/dist/finite-enum-ripple/configured-object-mutations.d.mts

@@ -0,0 +1 @@
+export declare function hasPostDeclarationConfiguredObjectMutation(content: string, file: string, name: string, objectEnd: number): boolean;

package/dist/finite-enum-ripple/configured-object-mutations.mjs

@@ -0,0 +1,78 @@
+import ts from '@typescript/typescript6';
+import { resolve } from 'node:path';
+import { unwrapExpression } from './ast.mjs';
+export function hasPostDeclarationConfiguredObjectMutation(content, file, name, objectEnd) {
+    const fileName = resolve(file);
+    const scriptKind = file.endsWith('.tsx') || file.endsWith('.jsx') ? ts.ScriptKind.TSX : ts.ScriptKind.TS;
+    const source = ts.createSourceFile(fileName, content, ts.ScriptTarget.Latest, true, scriptKind);
+    const options = {
+        noLib: true,
+        noResolve: true,
+        target: ts.ScriptTarget.Latest,
+    };
+    const host = ts.createCompilerHost(options);
+    host.getSourceFile = () => source;
+    const program = ts.createProgram([fileName], options, host);
+    const checker = program.getTypeChecker();
+    const findDeclaration = (node) => {
+        if (ts.isVariableDeclaration(node) &&
+            ts.isIdentifier(node.name) &&
+            node.name.text === name &&
+            node.initializer &&
+            ts.isObjectLiteralExpression(unwrapExpression(node.initializer)) &&
+            unwrapExpression(node.initializer).end === objectEnd)
+            return node.name;
+        return ts.forEachChild(node, findDeclaration);
+    };
+    // The public parser has already verified this exact const object declaration.
+    const configuredName = findDeclaration(source);
+    const configuredSymbol = checker.getSymbolAtLocation(configuredName);
+    const targetsConfiguredMap = (target) => {
+        let root = unwrapExpression(target);
+        while (ts.isPropertyAccessExpression(root) || ts.isElementAccessExpression(root))
+            root = unwrapExpression(root.expression);
+        return ts.isIdentifier(root) && checker.getSymbolAtLocation(root) === configuredSymbol;
+    };
+    const destructuringTargetMutatesConfiguredMap = (target) => {
+        const expression = unwrapExpression(target);
+        if (targetsConfiguredMap(expression))
+            return true;
+        if (ts.isObjectLiteralExpression(expression))
+            return expression.properties.some((property) => ts.isPropertyAssignment(property)
+                ? destructuringTargetMutatesConfiguredMap(property.initializer)
+                : ts.isShorthandPropertyAssignment(property)
+                    ? checker.getSymbolAtLocation(property.name) === configuredSymbol
+                    : ts.isSpreadAssignment(property) &&
+                        destructuringTargetMutatesConfiguredMap(property.expression));
+        if (ts.isArrayLiteralExpression(expression))
+            return expression.elements.some((element) => !ts.isOmittedExpression(element) && destructuringTargetMutatesConfiguredMap(element));
+        return false;
+    };
+    let mutated = false;
+    const inspect = (node) => {
+        if (mutated || node.end <= objectEnd)
+            return;
+        if (ts.isBinaryExpression(node) &&
+            (node.operatorToken.kind === ts.SyntaxKind.EqualsToken ||
+                (node.operatorToken.kind >= ts.SyntaxKind.FirstCompoundAssignment &&
+                    node.operatorToken.kind <= ts.SyntaxKind.LastCompoundAssignment)) &&
+            destructuringTargetMutatesConfiguredMap(node.left)) {
+            mutated = true;
+            return;
+        }
+        if (ts.isDeleteExpression(node) && targetsConfiguredMap(node.expression)) {
+            mutated = true;
+            return;
+        }
+        if ((ts.isPrefixUnaryExpression(node) || ts.isPostfixUnaryExpression(node)) &&
+            (node.operator === ts.SyntaxKind.PlusPlusToken ||
+                node.operator === ts.SyntaxKind.MinusMinusToken) &&
+            targetsConfiguredMap(node.operand)) {
+            mutated = true;
+            return;
+        }
+        ts.forEachChild(node, inspect);
+    };
+    inspect(source);
+    return mutated;
+}