vouchington-tooling 0.20.0 → 0.22.0

package/dist/compiler-build/settlement.d.mts

@@ -0,0 +1,10 @@
+export type SettlementConfirmation<Configuration> = {
+    configuration: Configuration;
+    settled: boolean;
+};
+export type SettlementCallbacks<Configuration, Value> = {
+    buildAttempt(configuration: Configuration): Value;
+    confirmAttempt(configuration: Configuration, value: Value): SettlementConfirmation<Configuration>;
+};
+/** Rebuilds against the configuration returned by each failed confirmation. */
+export declare function settleBuild<Configuration, Value>(initialConfiguration: Configuration, maximumAttempts: number, callbacks: SettlementCallbacks<Configuration, Value>): Value;

package/dist/compiler-build/settlement.mjs

@@ -0,0 +1,14 @@
+/** Rebuilds against the configuration returned by each failed confirmation. */
+export function settleBuild(initialConfiguration, maximumAttempts, callbacks) {
+    if (!Number.isSafeInteger(maximumAttempts) || maximumAttempts < 1)
+        throw new RangeError('maximumAttempts must be a positive safe integer');
+    let configuration = initialConfiguration;
+    for (let attempts = 1; attempts <= maximumAttempts; attempts += 1) {
+        const value = callbacks.buildAttempt(configuration);
+        const confirmation = callbacks.confirmAttempt(configuration, value);
+        if (confirmation.settled)
+            return value;
+        configuration = confirmation.configuration;
+    }
+    throw new Error(`Inputs changed during ${maximumAttempts} consecutive build attempts`);
+}

package/dist/config-inventory/call-arguments.d.mts

@@ -0,0 +1 @@
+export declare function splitCallArguments(args: string): string[];

package/dist/config-inventory/call-arguments.mjs

@@ -0,0 +1,30 @@
+export function splitCallArguments(args) {
+    const parts = [];
+    let start = 0;
+    let depth = 0;
+    let quote = '';
+    for (let index = 0; index < args.length; index += 1) {
+        const char = args[index];
+        if (quote) {
+            if (char === '\\')
+                index += 1;
+            else if (char === quote)
+                quote = '';
+        }
+        else if (char === '"' || char === "'" || char === '`') {
+            quote = char;
+        }
+        else if ('<[{('.includes(char)) {
+            depth += 1;
+        }
+        else if ('>]})'.includes(char)) {
+            depth = Math.max(0, depth - 1);
+        }
+        else if (char === ',' && depth === 0) {
+            parts.push(args.slice(start, index).trim());
+            start = index + 1;
+        }
+    }
+    parts.push(args.slice(start).trim());
+    return parts;
+}

package/dist/config-inventory/collect.d.mts

@@ -0,0 +1,3 @@
+import type { ConfigInventory, ConfigInventoryContext, ConfigInventoryOptions } from './types.mts';
+/** Collects syntax-level evidence without executing any consumer module. */
+export declare function collectConfigInventory(context: ConfigInventoryContext, options: ConfigInventoryOptions): ConfigInventory;

package/dist/config-inventory/collect.mjs

@@ -0,0 +1,43 @@
+import { addDynamicConfigReferences } from './dynamic-configs.mjs';
+import { collectEnvVarPrefixReadersFromFile } from './env-prefix-readers.mjs';
+import { compileEnvVarReferenceMatchers } from './env-reference-matchers.mjs';
+import { collectEnvVarReferencesFromFile, collectEnvVarsFromFile, seedTypedEnvContractEntries, toEnvVarRow, } from './env-vars.mjs';
+import { collectPackageGatesFromFile } from './package-gates.mjs';
+/** Collects syntax-level evidence without executing any consumer module. */
+export function collectConfigInventory(context, options) {
+    const envVars = new Map();
+    const dynamicConfigs = new Map();
+    const packageGates = new Map();
+    const sources = [];
+    const constants = options.envConstants ?? new Map();
+    seedTypedEnvContractEntries(envVars, options.envContract ?? [], options.sensitivityOrder);
+    for (const file of [...new Set(context.trackedFiles)].sort()) {
+        const rules = options.describeFile(file);
+        if (!rules)
+            continue;
+        const source = context.readTrackedFile(file);
+        if (source === null)
+            continue;
+        sources.push({ file, source, rules });
+        collectEnvVarsFromFile(file, source, envVars, constants, rules, options.envHelperNames ?? []);
+        if (rules.packageManagerConfig)
+            collectPackageGatesFromFile(file, source, packageGates);
+        addDynamicConfigReferences(dynamicConfigs, file, options.collectDynamicConfigs?.(file, source) ?? []);
+    }
+    const matchers = compileEnvVarReferenceMatchers(envVars);
+    for (const { file, source, rules } of sources) {
+        if (!rules.markdown)
+            collectEnvVarPrefixReadersFromFile(file, source, envVars, constants);
+        collectEnvVarReferencesFromFile(file, source, envVars, matchers, rules.referenceBuckets ?? []);
+    }
+    return {
+        envVars: [...envVars.values()]
+            .map((accumulator) => {
+            const row = toEnvVarRow(accumulator);
+            return { ...row, ...options.annotateEnv?.(row) };
+        })
+            .toSorted((a, b) => a.name.localeCompare(b.name)),
+        dynamicConfigs: [...dynamicConfigs.values()].toSorted((a, b) => a.namespace.localeCompare(b.namespace)),
+        packageGates: [...packageGates.values()].toSorted((a, b) => a.name.localeCompare(b.name)),
+    };
+}

package/dist/config-inventory/dynamic-configs.d.mts

@@ -0,0 +1,2 @@
+import type { DynamicConfigInventoryRow, DynamicConfigReference } from './types.mts';
+export declare function addDynamicConfigReferences(rows: Map<string, DynamicConfigInventoryRow>, file: string, references: readonly DynamicConfigReference[]): void;

package/dist/config-inventory/dynamic-configs.mjs

@@ -0,0 +1,9 @@
+import { sorted } from './shared.mjs';
+export function addDynamicConfigReferences(rows, file, references) {
+    for (const { namespace, kind } of references) {
+        const row = rows.get(namespace) ?? { namespace, definitionFiles: [], registryFiles: [] };
+        const key = kind === 'definition' ? 'definitionFiles' : 'registryFiles';
+        row[key] = sorted(new Set([...row[key], file]));
+        rows.set(namespace, row);
+    }
+}

package/dist/config-inventory/env-expression-readers.d.mts

@@ -0,0 +1,3 @@
+export declare function matchLocalEnvWrapperCallNames(source: string, envConstants: ReadonlyMap<string, string>): string[];
+export declare function matchLocalEnvWrapperCallPrefixes(source: string, envConstants: ReadonlyMap<string, string>): string[];
+export declare function matchWorkflowEnvMapNames(source: string): string[];

package/dist/config-inventory/env-expression-readers.mjs

@@ -0,0 +1,117 @@
+import { splitCallArguments } from './call-arguments.mjs';
+const FUNCTION_DECLARATION_PATTERN = /\bfunction\s+([a-zA-Z_$][\w$]*)\s*\(([^)]*)\)\s*(?::[^{]+)?\{([\s\S]*?)\n\s*\}/g;
+const CALL_EXPRESSION_PATTERN = /\b([a-zA-Z_$][\w$]*)\s*\(([^)]*)\)/g;
+const ENV_MAP_DECLARATION_PATTERN = /^(\s*)(?:-\s*)?env\s*:\s*(?:#.*)?$/;
+const BLANK_OR_COMMENT_PATTERN = /^\s*(?:#.*)?$/;
+const UPPERCASE_YAML_KEY_PATTERN = /^\s*([A-Z][A-Z0-9_]*)\s*:/;
+const PROCESS_ENV_PARAM_PATTERN = /\bprocess\.env\[([a-zA-Z_$][\w$]*)\]/g;
+const IDENTIFIER_INDEXED_ACCESS_PATTERN = /\b([a-zA-Z_$][\w$]*)\[([a-zA-Z_$][\w$]*)\]/g;
+export function matchLocalEnvWrapperCallNames(source, envConstants) {
+    const envNameArgumentIndexes = findLocalEnvWrapperArgumentIndexes(source);
+    if (envNameArgumentIndexes.size === 0)
+        return [];
+    const names = new Set();
+    for (const match of source.matchAll(CALL_EXPRESSION_PATTERN)) {
+        const functionName = match[1];
+        const envNameArgumentIndex = envNameArgumentIndexes.get(functionName);
+        if (envNameArgumentIndex === undefined)
+            continue;
+        const args = splitCallArguments(match[2]);
+        const name = envNameFromArgument(args[envNameArgumentIndex], envConstants);
+        if (name)
+            names.add(name);
+    }
+    return [...names];
+}
+export function matchLocalEnvWrapperCallPrefixes(source, envConstants) {
+    const envNameArgumentIndexes = findLocalEnvWrapperArgumentIndexes(source);
+    if (envNameArgumentIndexes.size === 0)
+        return [];
+    const prefixes = new Set();
+    for (const match of source.matchAll(CALL_EXPRESSION_PATTERN)) {
+        const functionName = match[1];
+        const envNameArgumentIndex = envNameArgumentIndexes.get(functionName);
+        if (envNameArgumentIndex === undefined)
+            continue;
+        const args = splitCallArguments(match[2]);
+        const prefix = envNamePrefixFromArgument(args[envNameArgumentIndex], envConstants);
+        if (prefix)
+            prefixes.add(prefix);
+    }
+    return [...prefixes];
+}
+export function matchWorkflowEnvMapNames(source) {
+    const names = new Set();
+    const lines = source.split('\n');
+    for (let index = 0; index < lines.length; index += 1) {
+        const envIndent = lines[index].match(ENV_MAP_DECLARATION_PATTERN)?.[1]?.length;
+        if (envIndent === undefined)
+            continue;
+        collectEnvMapChildNames(lines, index, envIndent, names);
+    }
+    return [...names];
+}
+function findLocalEnvWrapperArgumentIndexes(source) {
+    const indexes = new Map();
+    for (const match of source.matchAll(FUNCTION_DECLARATION_PATTERN)) {
+        const functionName = match[1];
+        const params = parseParameterNames(match[2]);
+        const body = match[3];
+        const processEnvParams = new Set([...body.matchAll(PROCESS_ENV_PARAM_PATTERN)].map((item) => item[1]));
+        const indexedAccesses = new Set([...body.matchAll(IDENTIFIER_INDEXED_ACCESS_PATTERN)].map((item) => `${item[1]}:${item[2]}`));
+        addProcessEnvWrapperIndexes(indexes, functionName, params, processEnvParams);
+        addEnvObjectWrapperIndexes(indexes, functionName, params, indexedAccesses);
+    }
+    return indexes;
+}
+function addProcessEnvWrapperIndexes(indexes, functionName, params, processEnvParams) {
+    for (const [index, param] of params.entries()) {
+        if (processEnvParams.has(param))
+            indexes.set(functionName, index);
+    }
+}
+function addEnvObjectWrapperIndexes(indexes, functionName, params, indexedAccesses) {
+    for (const [envIndex, envParam] of params.entries()) {
+        for (const [nameIndex, nameParam] of params.entries()) {
+            if (envIndex === nameIndex)
+                continue;
+            if (indexedAccesses.has(`${envParam}:${nameParam}`))
+                indexes.set(functionName, nameIndex);
+        }
+    }
+}
+function parseParameterNames(parameters) {
+    return splitCallArguments(parameters).map((parameter) => {
+        const name = parameter.trim().match(/^([a-zA-Z_$][\w$]*)\b/)?.[1];
+        return name ?? '';
+    });
+}
+function envNameFromArgument(arg, envConstants) {
+    if (!arg)
+        return null;
+    const literal = arg.match(/^['"]([A-Z][A-Z0-9_]*)['"]$/)?.[1];
+    if (literal)
+        return literal;
+    return envConstants.get(arg) ?? null;
+}
+function envNamePrefixFromArgument(arg, envConstants) {
+    const prefixConstant = arg?.match(/^`\$\{([A-Z0-9_]+)\}/)?.[1];
+    return prefixConstant ? (envConstants.get(prefixConstant) ?? null) : null;
+}
+function collectEnvMapChildNames(lines, envLineIndex, envIndent, names) {
+    let keyIndent = null;
+    for (let childIndex = envLineIndex + 1; childIndex < lines.length; childIndex += 1) {
+        const line = lines[childIndex];
+        if (BLANK_OR_COMMENT_PATTERN.test(line))
+            continue;
+        const indent = line.match(/^\s*/)[0].length;
+        if (indent <= envIndent)
+            break;
+        keyIndent ??= indent;
+        if (indent !== keyIndent)
+            continue;
+        const name = line.match(UPPERCASE_YAML_KEY_PATTERN)?.[1];
+        if (name)
+            names.add(name);
+    }
+}

package/dist/config-inventory/env-prefix-readers.d.mts

@@ -0,0 +1,2 @@
+import type { EnvVarAccumulator } from './types.mts';
+export declare function collectEnvVarPrefixReadersFromFile(file: string, source: string, envVars: Map<string, EnvVarAccumulator>, envConstants: ReadonlyMap<string, string>): void;

package/dist/config-inventory/env-prefix-readers.mjs

@@ -0,0 +1,14 @@
+import { matchLocalEnvWrapperCallPrefixes } from './env-expression-readers.mjs';
+import { ENV_NAME_PATTERN, sorted } from './shared.mjs';
+export function collectEnvVarPrefixReadersFromFile(file, source, envVars, envConstants) {
+    const prefixes = matchLocalEnvWrapperCallPrefixes(source, envConstants);
+    if (prefixes.length === 0)
+        return;
+    for (const prefix of prefixes) {
+        for (const name of sorted(envVars.keys())) {
+            if (name.startsWith(prefix) && ENV_NAME_PATTERN.test(name)) {
+                envVars.get(name)?.readers.add(file);
+            }
+        }
+    }
+}

package/dist/config-inventory/env-reference-matchers.d.mts

@@ -0,0 +1,3 @@
+import type { EnvVarAccumulator, EnvVarReferenceMatcher } from './types.mts';
+export declare function compileEnvVarReferenceMatchers(envVars: Map<string, EnvVarAccumulator>): EnvVarReferenceMatcher[];
+export declare function namesAlreadySeen(source: string, referenceMatchers: EnvVarReferenceMatcher[]): string[];

package/dist/config-inventory/env-reference-matchers.mjs

@@ -0,0 +1,9 @@
+export function compileEnvVarReferenceMatchers(envVars) {
+    return [...envVars.keys()].map((name) => ({
+        name,
+        pattern: new RegExp(`(?<![A-Za-z0-9_/-])${name}(?![A-Za-z0-9_/-])`),
+    }));
+}
+export function namesAlreadySeen(source, referenceMatchers) {
+    return referenceMatchers.flatMap(({ name, pattern }) => (pattern.test(source) ? [name] : []));
+}

package/dist/config-inventory/env-var-accumulator.d.mts

@@ -0,0 +1,6 @@
+import type { EnvVarAccumulator, EnvVarInventoryRow, SourceBucket, TypedEnvContractEntry } from './types.mts';
+type EnvVarMetadata = Pick<TypedEnvContractEntry, 'contractKey' | 'sourceOfTruth' | 'runtimeSurfaces' | 'sensitivity'>;
+export declare function seedTypedEnvContractEntries(envVars: Map<string, EnvVarAccumulator>, entries: readonly TypedEnvContractEntry[], sensitivityOrder?: readonly string[]): void;
+export declare function toEnvVarRow(acc: EnvVarAccumulator): EnvVarInventoryRow;
+export declare function addEnvVar(envVars: Map<string, EnvVarAccumulator>, name: string, file: string, bucket: SourceBucket, metadata?: EnvVarMetadata): void;
+export {};

package/dist/config-inventory/env-var-accumulator.mjs

@@ -0,0 +1,82 @@
+import { ENV_NAME_PATTERN, sorted } from './shared.mjs';
+const DEFAULT_SENSITIVITY_ORDER = ['internal', 'public', 'secret'];
+export function seedTypedEnvContractEntries(envVars, entries, sensitivityOrder = DEFAULT_SENSITIVITY_ORDER) {
+    const sensitivityRank = new Map(sensitivityOrder.map((value, index) => [value, index + 1]));
+    for (const entry of entries)
+        addTypedEnvContractEntry(envVars, entry, sensitivityRank);
+}
+export function toEnvVarRow(acc) {
+    const sourceSets = {
+        runtimeSurfaces: sorted(acc.runtimeSurfaces),
+        contractKeys: sorted(acc.contractKeys),
+        readers: sorted(acc.readers),
+        localSetup: sorted(acc.localSetup),
+        docs: sorted(acc.docs),
+        deployment: sorted(acc.deployment),
+        dockerBuildArgs: sorted(acc.dockerBuildArgs),
+        workflows: sorted(acc.workflows),
+        packageGates: sorted(acc.packageGates),
+    };
+    return {
+        name: acc.name,
+        classifications: [],
+        reviewReason: null,
+        contractKey: acc.contractKey,
+        sourceOfTruth: acc.sourceOfTruth,
+        sensitivity: acc.sensitivity,
+        ...sourceSets,
+    };
+}
+export function addEnvVar(envVars, name, file, bucket, metadata = {}) {
+    if (!ENV_NAME_PATTERN.test(name))
+        return;
+    const acc = envVars.get(name) ?? createEnvVarAccumulator(name);
+    acc[bucket].add(file);
+    mergeEnvVarMetadata(acc, metadata);
+    envVars.set(name, acc);
+}
+function addTypedEnvContractEntry(envVars, entry, sensitivityRank) {
+    if (!ENV_NAME_PATTERN.test(entry.name))
+        return;
+    const acc = envVars.get(entry.name) ?? createEnvVarAccumulator(entry.name);
+    mergeEnvVarMetadata(acc, entry, sensitivityRank);
+    envVars.set(entry.name, acc);
+}
+function createEnvVarAccumulator(name) {
+    return {
+        name,
+        contractKey: null,
+        contractKeys: new Set(),
+        sourceOfTruth: null,
+        sensitivity: null,
+        runtimeSurfaces: new Set(),
+        readers: new Set(),
+        localSetup: new Set(),
+        docs: new Set(),
+        deployment: new Set(),
+        dockerBuildArgs: new Set(),
+        workflows: new Set(),
+        packageGates: new Set(),
+    };
+}
+function mergeEnvVarMetadata(acc, metadata, sensitivityRank = new Map()) {
+    if (metadata.contractKey) {
+        acc.contractKeys.add(metadata.contractKey);
+        if (acc.contractKey === null)
+            acc.contractKey = metadata.contractKey;
+    }
+    if (acc.sourceOfTruth === null && metadata.sourceOfTruth)
+        acc.sourceOfTruth = metadata.sourceOfTruth;
+    acc.sensitivity = highestSensitivity(acc.sensitivity, metadata.sensitivity, sensitivityRank);
+    for (const surface of metadata.runtimeSurfaces ?? [])
+        acc.runtimeSurfaces.add(surface);
+}
+function highestSensitivity(current, incoming, sensitivityRank) {
+    if (!incoming)
+        return current;
+    if (current === null)
+        return incoming;
+    return (sensitivityRank.get(incoming) ?? 0) > (sensitivityRank.get(current) ?? 0)
+        ? incoming
+        : current;
+}

package/dist/config-inventory/env-vars.d.mts

@@ -0,0 +1,4 @@
+import type { EnvVarAccumulator, EnvVarReferenceMatcher, ConfigSourceRules } from './types.mts';
+export { seedTypedEnvContractEntries, toEnvVarRow } from './env-var-accumulator.mts';
+export declare function collectEnvVarsFromFile(file: string, source: string, envVars: Map<string, EnvVarAccumulator>, envConstants: ReadonlyMap<string, string>, rules: ConfigSourceRules, helperNames: readonly string[]): void;
+export declare function collectEnvVarReferencesFromFile(file: string, source: string, envVars: Map<string, EnvVarAccumulator>, referenceMatchers: EnvVarReferenceMatcher[], buckets: readonly import('./types.mts').SourceBucket[]): void;

package/dist/config-inventory/env-vars.mjs

@@ -0,0 +1,108 @@
+import { matchLocalEnvWrapperCallNames, matchWorkflowEnvMapNames, } from './env-expression-readers.mjs';
+import { namesAlreadySeen } from './env-reference-matchers.mjs';
+import { addEnvVar } from './env-var-accumulator.mjs';
+import { matchNames } from './shared.mjs';
+export { seedTypedEnvContractEntries, toEnvVarRow } from './env-var-accumulator.mjs';
+const PROCESS_ENV_PATTERNS = [
+    /\bprocess\.env\.([A-Z][A-Z0-9_]*)\b/g,
+    /\bprocess\.env\[['"]([A-Z][A-Z0-9_]*)['"]\]/g,
+    /\b(?:const|let|var)\s*\{\s*([^}]+?)\s*\}\s*=\s*process\.env\b/g,
+];
+const WORKER_ENV_BINDING_PATTERN = /\benv\.([A-Z][A-Z0-9_]*)\b/g;
+const PROCESS_ENV_IDENTIFIER_PATTERN = /\bprocess\.env\[([A-Z0-9_]+)\]/g;
+const ENV_ASSIGNMENT_PATTERN = /(?:^|[\s"'(])([A-Z][A-Z0-9_]*)=/g;
+const EXPORT_ENV_PATTERN = /(?:^|\n)\s*(?:export\s+)?([A-Z][A-Z0-9_]*)=/g;
+const DEV_INITIALIZE_EXPORT_PATTERN = /(?:^|\n)\s*(?:export\s+|printf\s+'export\s+)([A-Z][A-Z0-9_]*)=/g;
+const DOCKER_ARG_NAME_PATTERN = /(?:^|\n)\s*ARG\s+([A-Z][A-Z0-9_]*)(?:[=\s]|$)/g;
+const DOCKER_ENV_NAME_PATTERN = /(?:^|\n)\s*ENV\s+([A-Z][A-Z0-9_]*)(?:[=\s]|$)/g;
+const WRANGLER_JSONC_ENV_NAME_PATTERN = /"([A-Z][A-Z0-9_]*)"\s*:/g;
+const MARKDOWN_CODE_ENV_PATTERN = /`([A-Z][A-Z0-9_]{2,})`/g;
+export function collectEnvVarsFromFile(file, source, envVars, envConstants, rules, helperNames) {
+    const isMarkdown = rules.markdown === true;
+    if (!isMarkdown) {
+        for (const pattern of PROCESS_ENV_PATTERNS) {
+            for (const name of matchEnvNames(source, pattern))
+                addEnvVar(envVars, name, file, 'readers');
+        }
+        for (const name of matchConstantIndexedEnvNames(source, envConstants))
+            addEnvVar(envVars, name, file, 'readers');
+        for (const name of matchHelperNames(source, helperNames))
+            addEnvVar(envVars, name, file, 'readers');
+        for (const name of matchLocalEnvWrapperCallNames(source, envConstants))
+            addEnvVar(envVars, name, file, 'readers');
+        if (rules.workerBindings) {
+            for (const name of matchEnvNames(source, WORKER_ENV_BINDING_PATTERN))
+                addEnvVar(envVars, name, file, 'readers');
+        }
+    }
+    if (rules.localAssignments) {
+        for (const name of matchEnvNames(source, EXPORT_ENV_PATTERN)) {
+            addEnvVar(envVars, name, file, 'localSetup');
+        }
+    }
+    if (rules.shellExports) {
+        for (const name of matchEnvNames(source, DEV_INITIALIZE_EXPORT_PATTERN)) {
+            addEnvVar(envVars, name, file, 'localSetup');
+        }
+    }
+    if (rules.jsonBindings) {
+        for (const name of matchEnvNames(source, WRANGLER_JSONC_ENV_NAME_PATTERN)) {
+            addEnvVar(envVars, name, file, 'localSetup');
+        }
+    }
+    if (rules.docker) {
+        for (const name of matchEnvNames(source, DOCKER_ARG_NAME_PATTERN)) {
+            addEnvVar(envVars, name, file, 'deployment');
+            addEnvVar(envVars, name, file, 'dockerBuildArgs');
+        }
+        for (const name of matchEnvNames(source, DOCKER_ENV_NAME_PATTERN)) {
+            addEnvVar(envVars, name, file, 'deployment');
+        }
+    }
+    if (rules.workflow) {
+        for (const name of matchWorkflowEnvMapNames(source)) {
+            addEnvVar(envVars, name, file, 'workflows');
+        }
+    }
+    if (rules.markdown) {
+        for (const name of matchEnvNames(source, MARKDOWN_CODE_ENV_PATTERN))
+            addEnvVar(envVars, name, file, 'docs');
+    }
+    if (rules.packageManifest) {
+        for (const name of matchEnvNames(source, ENV_ASSIGNMENT_PATTERN))
+            addEnvVar(envVars, name, file, 'packageGates');
+    }
+}
+export function collectEnvVarReferencesFromFile(file, source, envVars, referenceMatchers, buckets) {
+    if (buckets.length === 0)
+        return;
+    const names = namesAlreadySeen(source, referenceMatchers);
+    for (const bucket of buckets) {
+        for (const name of names)
+            addEnvVar(envVars, name, file, bucket);
+    }
+}
+function matchEnvNames(source, pattern) {
+    if (pattern === PROCESS_ENV_PATTERNS[2]) {
+        return [...source.matchAll(pattern)].flatMap((match) => parseDestructuredEnvNames(match[1]));
+    }
+    return matchNames(source, pattern);
+}
+function parseDestructuredEnvNames(bindingList) {
+    return bindingList.split(',').flatMap((binding) => {
+        const name = binding.trim().match(/^([A-Z][A-Z0-9_]*)\b/)?.[1];
+        return name ? [name] : [];
+    });
+}
+function matchConstantIndexedEnvNames(source, envConstants) {
+    return [...source.matchAll(PROCESS_ENV_IDENTIFIER_PATTERN)].flatMap((match) => {
+        const name = envConstants.get(match[1]);
+        return name ? [name] : [];
+    });
+}
+function matchHelperNames(source, names) {
+    if (names.length === 0)
+        return [];
+    const pattern = new RegExp(String.raw `(?<![\w$])(?:${names.map((name) => name.replace(/[.*+?^${}()|[\]\\]/g, (character) => `\\${character}`)).join('|')})\(\s*['"]([A-Z][A-Z0-9_]*)['"]`, 'g');
+    return matchNames(source, pattern);
+}

package/dist/config-inventory/format.d.mts

@@ -0,0 +1,2 @@
+import type { ConfigInventory } from './types.mts';
+export declare function formatConfigInventoryMarkdown(inventory: ConfigInventory): string;

package/dist/config-inventory/format.mjs

@@ -0,0 +1,69 @@
+export function formatConfigInventoryMarkdown(inventory) {
+    return [
+        '# Configuration Inventory',
+        '',
+        'Generated from caller-selected repository files.',
+        '',
+        '## Environment Variables',
+        '',
+        '| Name | Classifications | Contract | Source of truth | Sensitivity | Surfaces | Readers | Local setup | Deployment | Docker build args | Workflows | Docs | Package gates | Review |',
+        '| ---- | --------------- | -------- | --------------- | ----------- | -------- | ------- | ----------- | ---------- | ----------------- | --------- | ---- | ------------- | ------ |',
+        ...inventory.envVars.map((row) => tableRow([
+            code(row.name),
+            row.classifications.map(code).join(', '),
+            row.contractKeys.map(code).join('<br>'),
+            row.sourceOfTruth ? code(row.sourceOfTruth) : '',
+            row.sensitivity ? code(row.sensitivity) : '',
+            row.runtimeSurfaces.map(code).join('<br>'),
+            formatFiles(row.readers),
+            formatFiles(row.localSetup),
+            formatFiles(row.deployment),
+            formatFiles(row.dockerBuildArgs),
+            formatFiles(row.workflows),
+            formatFiles(row.docs),
+            formatFiles(row.packageGates),
+            escapeTextCell(row.reviewReason ?? ''),
+        ])),
+        '',
+        '## Dynamic Configuration Namespaces',
+        '',
+        '| Namespace | Definitions | Registry |',
+        '| --------- | ----------- | -------------- |',
+        ...inventory.dynamicConfigs.map((row) => tableRow([
+            code(row.namespace),
+            formatFiles(row.definitionFiles),
+            formatFiles(row.registryFiles),
+        ])),
+        '',
+        '## Package-Manager Gates',
+        '',
+        '| Gate | Values | Files |',
+        '| ---- | ------ | ----- |',
+        ...inventory.packageGates.map((row) => tableRow([code(row.name), row.values.map(code).join(', '), formatFiles(row.files)])),
+        '',
+    ].join('\n');
+}
+function formatFiles(files) {
+    return files.length === 0 ? '' : files.map((file) => code(file)).join('<br>');
+}
+function tableRow(cells) {
+    return `| ${cells.join(' | ')} |`;
+}
+function code(value) {
+    const delimiter = '`'.repeat(Math.max(0, ...[...value.matchAll(/`+/g)].map((match) => match[0].length)) + 1);
+    const content = escapeCodeCell(value);
+    const padding = content.includes('`') || content.startsWith(' ') || content.endsWith(' ') ? ' ' : '';
+    return `${delimiter}${padding}${content}${padding}${delimiter}`;
+}
+function escapeCodeCell(value) {
+    return value.replaceAll('|', String.raw `\|`).replaceAll(/\r\n|\r|\n/g, ' ');
+}
+function escapeTextCell(value) {
+    return value
+        .replaceAll('&', '&amp;')
+        .replaceAll('|', '&#124;')
+        .replaceAll('<', '&lt;')
+        .replaceAll('>', '&gt;')
+        .replaceAll('`', '&#96;')
+        .replaceAll(/\r\n|\r|\n/g, ' ');
+}

package/dist/config-inventory/index.d.mts

@@ -0,0 +1,3 @@
+export { collectConfigInventory } from './collect.mts';
+export { formatConfigInventoryMarkdown } from './format.mts';
+export type { ConfigInventory, ConfigInventoryContext, ConfigInventoryOptions, ConfigSourceRules, DynamicConfigInventoryRow, DynamicConfigReference, EnvClassification, EnvVarInventoryRow, PackageGateInventoryRow, SourceBucket, TypedEnvContractEntry, } from './types.mts';

package/dist/config-inventory/index.mjs

@@ -0,0 +1,2 @@
+export { collectConfigInventory } from './collect.mjs';
+export { formatConfigInventoryMarkdown } from './format.mjs';

package/dist/config-inventory/package-gates.d.mts

@@ -0,0 +1,2 @@
+import type { PackageGateInventoryRow } from './types.mts';
+export declare function collectPackageGatesFromFile(file: string, source: string, packageGates: Map<string, PackageGateInventoryRow>): void;

package/dist/config-inventory/package-gates.mjs

@@ -0,0 +1,54 @@
+import { parse as load } from 'yaml';
+const PACKAGE_GATE_KEYS = [
+    'allowBuilds',
+    'dangerouslyAllowAllBuilds',
+    'ignoredOptionalDependencies',
+    'minimumReleaseAge',
+    'minimumReleaseAgeExclude',
+    'overrides',
+    'packageExtensions',
+    'strictDepBuilds',
+];
+export function collectPackageGatesFromFile(file, source, packageGates) {
+    let parsed;
+    try {
+        parsed = load(source);
+    }
+    catch {
+        return;
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+        return;
+    for (const key of PACKAGE_GATE_KEYS) {
+        const values = extractPackageGateValues(parsed[key]);
+        if (values.length === 0)
+            continue;
+        const existing = packageGates.get(key);
+        packageGates.set(key, {
+            name: key,
+            values: [...new Set([...(existing?.values ?? []), ...values])].sort(),
+            files: [...new Set([...(existing?.files ?? []), file])].sort(),
+        });
+    }
+}
+function extractPackageGateValues(value) {
+    if (Array.isArray(value)) {
+        return value.flatMap((entry) => (isScalarValue(entry) ? [String(entry)] : []));
+    }
+    if (isPlainObject(value)) {
+        return Object.keys(value);
+    }
+    return isScalarValue(value) ? [String(value)] : [];
+}
+function isPlainObject(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype;
+}
+function isScalarValue(value) {
+    return (typeof value === 'string' ||
+        typeof value === 'number' ||
+        typeof value === 'boolean' ||
+        value instanceof Date);
+}

package/dist/config-inventory/shared.d.mts

@@ -0,0 +1,3 @@
+export declare const ENV_NAME_PATTERN: RegExp;
+export declare function matchNames(source: string, pattern: RegExp): string[];
+export declare function sorted(values: Iterable<string>): string[];

package/dist/config-inventory/shared.mjs

@@ -0,0 +1,7 @@
+export const ENV_NAME_PATTERN = /^[A-Z][A-Z0-9_]*$/;
+export function matchNames(source, pattern) {
+    return [...source.matchAll(pattern)].flatMap((match) => (match[1] ? [match[1]] : []));
+}
+export function sorted(values) {
+    return [...values].toSorted((a, b) => a.localeCompare(b));
+}