vouchington-tooling 0.32.0 → 0.34.0

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;

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

@@ -0,0 +1,119 @@
+import ts from '../../contract-schema/typescript-api.mjs';
+export function identifierName(node) {
+    node = unparenthesized(node);
+    return ts.isIdentifier(node) ? node.text : undefined;
+}
+export function staticComputedPropertyName(node) {
+    node = unparenthesized(node);
+    return ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)
+        ? node.text
+        : undefined;
+}
+export function unparenthesized(node) {
+    while (ts.isParenthesizedExpression(node))
+        node = node.expression;
+    return node;
+}
+export function staticSqlTemplateText(node, options) {
+    if (!node)
+        return undefined;
+    node = unparenthesized(node);
+    if (ts.isTaggedTemplateExpression(node)) {
+        if (identifierName(node.tag) !== options.templateTag)
+            return undefined;
+        node = node.template;
+    }
+    if (ts.isNoSubstitutionTemplateLiteral(node))
+        return rawQuasi(node);
+    if (!ts.isTemplateExpression(node))
+        return undefined;
+    return [
+        rawQuasi(node.head),
+        ...node.templateSpans.map((span, index) => `${options.placeholderPrefix}${index + 1}${rawQuasi(span.literal)}`),
+    ].join('');
+}
+function rawQuasi(node) {
+    const closingWidth = ts.isTemplateHead(node) || ts.isTemplateMiddle(node) ? 2 : 1;
+    return node.getText().slice(1, -closingWidth);
+}
+export function walk(root, visit) {
+    visit(root);
+    // Retain the existing analyzer's alternate-before-consequent branch order.
+    // Concatenated fragment order is observable even though this is not execution analysis.
+    if (ts.isIfStatement(root)) {
+        if (root.elseStatement)
+            walk(root.elseStatement, visit);
+        walk(root.thenStatement, visit);
+        walk(root.expression, visit);
+        return;
+    }
+    if (ts.isConditionalExpression(root)) {
+        walk(root.whenFalse, visit);
+        walk(root.whenTrue, visit);
+        walk(root.condition, visit);
+        return;
+    }
+    if (ts.isCallExpression(root)) {
+        for (const argument of root.arguments)
+            walk(argument, visit);
+        walk(root.expression, visit);
+        for (const typeArgument of root.typeArguments ?? [])
+            walk(typeArgument, visit);
+        return;
+    }
+    if (ts.isFunctionDeclaration(root) ||
+        ts.isFunctionExpression(root) ||
+        ts.isArrowFunction(root) ||
+        ts.isMethodDeclaration(root) ||
+        ts.isConstructorDeclaration(root) ||
+        ts.isGetAccessorDeclaration(root) ||
+        ts.isSetAccessorDeclaration(root)) {
+        for (const modifier of root.modifiers ?? [])
+            if (ts.isDecorator(modifier))
+                walk(modifier, visit);
+        if (ts.isMethodDeclaration(root) ||
+            ts.isGetAccessorDeclaration(root) ||
+            ts.isSetAccessorDeclaration(root))
+            walk(root.name, visit);
+        if (root.body)
+            walk(root.body, visit);
+        for (const parameter of root.parameters)
+            walk(parameter, visit);
+        return;
+    }
+    if (ts.isForStatement(root)) {
+        walk(root.statement, visit);
+        for (const header of [root.initializer, root.condition, root.incrementor]) {
+            if (header)
+                walk(header, visit);
+        }
+        return;
+    }
+    if (ts.isWhileStatement(root) || ts.isForInStatement(root) || ts.isForOfStatement(root)) {
+        walk(root.statement, visit);
+        if (ts.isForInStatement(root) || ts.isForOfStatement(root))
+            walk(root.initializer, visit);
+        walk(root.expression, visit);
+        return;
+    }
+    if (ts.isTryStatement(root)) {
+        walk(root.tryBlock, visit);
+        if (root.finallyBlock)
+            walk(root.finallyBlock, visit);
+        if (root.catchClause)
+            walk(root.catchClause, visit);
+        return;
+    }
+    if (ts.isSwitchStatement(root)) {
+        walk(root.caseBlock, visit);
+        walk(root.expression, visit);
+        return;
+    }
+    if (ts.isCaseClause(root)) {
+        for (const statement of root.statements)
+            walk(statement, visit);
+        walk(root.expression, visit);
+        return;
+    }
+    ts.forEachChild(root, (node) => walk(node, visit));
+}

package/dist/post-publication-inventory/writers/source.d.mts

@@ -0,0 +1,9 @@
+import type { PostPublicationWriterSourceOptions } from './types.mts';
+export type PostPublicationWriterSourceAnalysis = {
+    readonly callsApprovedCaptureHelper: boolean;
+    readonly optsOutOfPublicationCapture: boolean;
+    readonly writesConfigEntityTable: boolean;
+    readonly writesGeneratedRelationTable: boolean;
+    readonly writesEligibilityTable: boolean;
+};
+export declare function analyzePostPublicationWriterSource(source: string, path: string, options: PostPublicationWriterSourceOptions): PostPublicationWriterSourceAnalysis;

package/dist/post-publication-inventory/writers/source.mjs

@@ -0,0 +1,128 @@
+import ts from '../../contract-schema/typescript-api.mjs';
+const DML = /\b(?:INSERT\s+INTO|UPDATE(?:\s+ONLY)?|DELETE\s+FROM)\b/i;
+const DML_PREFIX = /\b(?:INSERT\s+INTO|UPDATE(?:\s+ONLY)?|DELETE\s+FROM)\s*$/i;
+export function analyzePostPublicationWriterSource(source, path, options) {
+    const captureBindings = new Set();
+    const invokedIdentifiers = new Set();
+    const relationTableBindings = new Set();
+    let optsOutOfPublicationCapture = false;
+    let hasConfigEntityTable = false;
+    let hasDmlPrefix = false;
+    let buildsRelationInsert = false;
+    let appendsRelationTable = false;
+    let writesEligibilityTable = false;
+    const ast = ts.createSourceFile(path, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    function visit(node) {
+        if (ts.isImportDeclaration(node))
+            collectCaptureBindings(node, captureBindings, options);
+        if (ts.isCallExpression(node) && ts.isIdentifier(node.expression)) {
+            invokedIdentifiers.add(node.expression.text);
+            buildsRelationInsert ||= node.expression.text === options.insertBuilder;
+            hasConfigEntityTable ||= isConfigEntityTableAssertion(node, options);
+        }
+        if (ts.isPropertyAssignment(node) &&
+            (ts.isIdentifier(node.name) || ts.isStringLiteral(node.name)) &&
+            node.name.text === options.captureOption &&
+            node.initializer.kind === ts.SyntaxKind.FalseKeyword)
+            optsOutOfPublicationCapture = true;
+        if (ts.isVariableDeclaration(node) &&
+            ts.isIdentifier(node.name) &&
+            isEntityRelationElectionTableIdentifier(node.initializer, options))
+            relationTableBindings.add(node.name.text);
+        if (ts.isCallExpression(node) && isRelationTableAppend(node, relationTableBindings, options))
+            appendsRelationTable = true;
+        if (isSqlTextNode(node)) {
+            const text = sqlText(node);
+            if (!ts.isStringLiteral(node))
+                hasDmlPrefix ||= DML_PREFIX.test(text);
+            if (DML.test(text)) {
+                const table = writtenTableName(text);
+                writesEligibilityTable ||=
+                    options.eligibilityTables.has(table ?? '') ||
+                        (ts.isTemplateExpression(node) && dynamicEligibilityTable(node, options));
+            }
+        }
+        ts.forEachChild(node, visit);
+    }
+    visit(ast);
+    return {
+        callsApprovedCaptureHelper: [...captureBindings].some((binding) => invokedIdentifiers.has(binding)),
+        optsOutOfPublicationCapture,
+        writesConfigEntityTable: hasConfigEntityTable && hasDmlPrefix,
+        writesGeneratedRelationTable: buildsRelationInsert || (appendsRelationTable && hasDmlPrefix),
+        writesEligibilityTable,
+    };
+}
+function collectCaptureBindings(node, bindings, options) {
+    if (!ts.isStringLiteral(node.moduleSpecifier) ||
+        !options.captureModules.has(node.moduleSpecifier.text))
+        return;
+    const namedBindings = node.importClause?.namedBindings;
+    if (!namedBindings || !ts.isNamedImports(namedBindings))
+        return;
+    for (const binding of namedBindings.elements) {
+        const importedName = binding.propertyName?.text ?? binding.name.text;
+        if (options.captureSymbols.has(importedName))
+            bindings.add(binding.name.text);
+    }
+}
+function isConfigEntityTableAssertion(node, options) {
+    return (ts.isIdentifier(node.expression) &&
+        node.expression.text === options.identifierAssertion &&
+        isConfigEntityTable(node.arguments[0], options));
+}
+function isRelationTableAppend(node, bindings, options) {
+    if (!ts.isPropertyAccessExpression(node.expression) ||
+        node.expression.name.text !== options.appendMethod)
+        return false;
+    const argument = node.arguments[0];
+    return (!!argument &&
+        (isRelationTableName(argument, options) ||
+            (ts.isIdentifier(argument) && bindings.has(argument.text))));
+}
+function isEntityRelationElectionTableIdentifier(initializer, options) {
+    return Boolean(initializer &&
+        ts.isCallExpression(initializer) &&
+        ts.isIdentifier(initializer.expression) &&
+        initializer.expression.text === options.identifierAssertion &&
+        initializer.arguments.some((argument) => ts.isIdentifier(argument) && argument.text === options.relationElectionAllowlist));
+}
+function isConfigEntityTable(node, options) {
+    return Boolean(node &&
+        ts.isPropertyAccessExpression(node) &&
+        node.name.text === options.entityTable.property &&
+        ts.isIdentifier(node.expression) &&
+        node.expression.text === options.entityTable.receiver);
+}
+function isRelationTableName(node, options) {
+    return Boolean(node &&
+        ts.isPropertyAccessExpression(node) &&
+        node.name.text === options.relationTable.property &&
+        ts.isIdentifier(node.expression) &&
+        node.expression.text === options.relationTable.receiver);
+}
+function isSqlTextNode(node) {
+    return (ts.isNoSubstitutionTemplateLiteral(node) ||
+        ts.isTemplateExpression(node) ||
+        ts.isStringLiteral(node));
+}
+function sqlText(node) {
+    if (ts.isStringLiteral(node))
+        return node.text;
+    return ts.isNoSubstitutionTemplateLiteral(node)
+        ? node.text
+        : [node.head.text, ...node.templateSpans.map((span) => span.literal.text)].join('');
+}
+function writtenTableName(text) {
+    return /\b(?:INSERT\s+INTO|UPDATE(?:\s+ONLY)?|DELETE\s+FROM)\s+(?:(?:"?[\w$]+"?\.)?"?)([\w$]+)"?/i
+        .exec(text)?.[1]
+        ?.toLowerCase();
+}
+function dynamicEligibilityTable(node, options) {
+    if (!/\b(?:INSERT\s+INTO|UPDATE(?:\s+ONLY)?|DELETE\s+FROM)\s+(?:(?:"?[\w$]+"?\.)?)$/i.test(node.head.text))
+        return false;
+    const expression = node.templateSpans[0]?.expression;
+    return (expression !== undefined &&
+        ts.isStringLiteral(expression) &&
+        options.eligibilityTables.has(expression.text));
+}

package/dist/post-publication-inventory/writers/types.d.mts

@@ -0,0 +1,19 @@
+/** All repository-specific names are explicit; SQL recognition preserves the inventory heuristic. */
+export interface PostPublicationWriterSourceOptions {
+    captureModules: ReadonlySet<string>;
+    captureSymbols: ReadonlySet<string>;
+    eligibilityTables: ReadonlySet<string>;
+    captureOption: string;
+    insertBuilder: string;
+    identifierAssertion: string;
+    entityTable: {
+        receiver: string;
+        property: string;
+    };
+    relationTable: {
+        receiver: string;
+        property: string;
+    };
+    relationElectionAllowlist: string;
+    appendMethod: string;
+}

package/dist/post-publication-inventory/writers/types.mjs

@@ -0,0 +1 @@
+export {};

package/docs/basic-auth-doc-sync.md

@@ -0,0 +1,37 @@
+# Basic Auth exemption facts
+
+Import from `vouchington-tooling/basic-auth-doc-sync`. TypeScript source parsing uses
+the optional `@typescript/typescript6` dependency. Markdown-only callers can import
+`findRunbookExemptRoutes` from `vouchington-tooling/basic-auth-doc-sync/runbook`
+without installing that optional compiler.
+
+- `findBasicAuthExemptPaths(source, variableName)` returns the literal strings in a
+  top-level `const` initialized with `new Set([...])`.
+- `findBasicAuthExemptMethodsByPath(source, variableName)` returns a map of literal
+  paths to literal uppercase HTTP method tokens from `new Map([[path, new Set([...])]])`.
+- `findRunbookExemptRoutes(markdown, heading)` reads the first GFM table following
+  the configured real GFM level-three heading (case insensitive), stopping at the
+  next same-or-higher-level heading. Duplicate `Path` or `Methods` columns are rejected. Columns are named `Path`
+  and `Methods`; paths and comma-separated method tokens must be inline code.
+
+All functions return `null` for absent or unsupported declarations/tables. Source
+collections must be nonempty and contain only nonempty string literals or static
+templates; dynamic expressions are rejected. Literal order and duplicate methods
+or documentation rows are preserved for caller validation; repeated map keys follow
+Map replacement semantics. The runbook reader accepts short table separators and CRLF.
+
+Callers own symbol names, route inventory, document locations, comparisons, and
+diagnostics. These functions return data without exposing AST nodes.
+
+## Source provenance
+
+The fact readers were extracted from `vouchington/vouchington` at
+`99a0948e4e3cc0c5b9791062df6e9de37e4cf3f1`:
+
+- `static-code-analysis/targeted-guardrails/basic-auth-doc-sync-parsers.mts`
+- `static-code-analysis/targeted-guardrails/basic-auth-doc-sync.test.mts`
+- `static-code-analysis/targeted-guardrails/basic-auth-doc-sync-parser-edge.test.mts`
+
+The original parser and its characterization tests informed the extraction. The
+first extraction commit misspelled the edge-test basename in its provenance body;
+the paths above are the authoritative source list.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vouchington-tooling",
-  "version": "0.32.0",
+  "version": "0.34.0",
   "description": "Vouchington CLI and extractable tooling libraries.",
   "homepage": "https://github.com/vouchington/vouchington-tooling/tree/main/packages/vouchington-tooling#readme",
   "bugs": {
@@ -331,7 +331,27 @@
       "import": "./dist/gh-api-shell-quoting/index.mjs",
       "default": "./dist/gh-api-shell-quoting/index.mjs"
     },
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./basic-auth-doc-sync": {
+      "types": "./dist/basic-auth-doc-sync/index.d.mts",
+      "import": "./dist/basic-auth-doc-sync/index.mjs",
+      "default": "./dist/basic-auth-doc-sync/index.mjs"
+    },
+    "./basic-auth-doc-sync/runbook": {
+      "types": "./dist/basic-auth-doc-sync/runbook.d.mts",
+      "import": "./dist/basic-auth-doc-sync/runbook.mjs",
+      "default": "./dist/basic-auth-doc-sync/runbook.mjs"
+    },
+    "./finite-enum-ripple": {
+      "types": "./dist/finite-enum-ripple/index.d.mts",
+      "import": "./dist/finite-enum-ripple/index.mjs",
+      "default": "./dist/finite-enum-ripple/index.mjs"
+    },
+    "./post-publication-inventory": {
+      "types": "./dist/post-publication-inventory/index.d.mts",
+      "import": "./dist/post-publication-inventory/index.mjs",
+      "default": "./dist/post-publication-inventory/index.mjs"
+    }
   },
   "publishConfig": {
     "access": "public"
@@ -359,7 +379,8 @@
     "@types/picomatch": "^4.0.3",
     "@types/spdx-expression-parse": "4.0.0",
     "agent-blackboard": "^0.6.0",
-    "smol-toml": "1.9.0"
+    "smol-toml": "1.9.0",
+    "typescript5": "npm:typescript@5.9.3"
   },
   "peerDependencies": {
     "@modelcontextprotocol/sdk": "^1.31.0",