vouchington-tooling 0.13.1 → 0.13.2

package/README.md

@@ -186,6 +186,13 @@ import {
 import { buildOpenApiDocument, writeOpenApi } from 'vouchington-tooling/openapi-document'
 import { decide, deriveRetryAttempt } from 'vouchington-tooling/transient-retry'
 import { parseCsvRows, streamCsvRows } from 'vouchington-tooling/csv'
+import {
+  extractLooseMarkdownTableRows,
+  extractMarkdownTables,
+  markdownSectionBetweenHeadings,
+  parseGfmMarkdown,
+  parseMarkdownTables,
+} from 'vouchington-tooling/markdown'
 import { readResponseBody } from 'vouchington-tooling/http-body'
 import { runAstGrepRule } from 'vouchington-tooling/ast-grep-rule'
 import { parseReviewPayload, remapReviewComments } from 'vouchington-tooling/gha-review-payload'
@@ -228,6 +235,13 @@ import {
 } from 'vouchington-tooling/gh-api-shell-quoting'
 ```
 
+`checkSccComplexity` keeps its single repository-wide scan when `scopes` is omitted. Consumers
+that need separately ratcheted areas may provide named scopes with positional `includePaths`; SCC
+runs once per scope and reports the scope in each diagnostic. Parse a consumer-owned JSON baseline
+with `parseSccComplexityBaseline` and pass it as `baseline`. Baselines are versioned, record the
+maximum permitted complexity for each `{ scope, file }`, suppress only values at or below that
+ceiling, and reject malformed, duplicate, untracked, stale, or out-of-scope entries.
+
 `shellScriptViolations`/`workflowYamlViolations` flag a `gh api` call whose argument carries an
 unquoted `?` or `&`: an unquoted `&` silently backgrounds the command and truncates the query
 (the call still exits 0), and an unquoted `?` fails loudly under zsh glob-nomatch but passes
@@ -241,6 +255,13 @@ shell script or a workflow/action YAML file is left to the caller.
 code-point limit without altering it. Its result includes the UTF-8 byte count for diagnostics; that
 byte count is not a validation limit.
 
+`vouchington-tooling/markdown` parses GFM into standard mdast/unist nodes, provides pre-order
+walking and typed searches, normalizes node text, and extracts positioned tables or heading-bounded
+source sections. `parseMarkdownTables` preserves its compact `{ cells, line }[][]` compatibility
+shape, including short table delimiters. `extractLooseMarkdownTableRows` is intentionally literal
+recovery for malformed pipe rows; callers supply table positions to exclude and retain ownership of
+their policy interpretation.
+
 `agent-harness-config` merges classifier-auto and sandbox keys into Claude, Codex, Grok, and Cursor
 config files. See [docs/agent-harness-config.md](./docs/agent-harness-config.md). `--global` updates
 home-directory configs; `--repo` updates a checkout. It does not copy allowlists, hooks, or plugins.

package/dist/index.d.mts

@@ -72,8 +72,8 @@ export { EPOCH_PRUNED_AT, normalizeDeployedLayer, pruneDeployedRuntimeDeps, rest
 export type { NormalizeDeployedLayerResult, PruneResult, RestoreWorkspacePackagesOptions, } from './pnpm-deploy/index.mts';
 export { parseDockerfilePrewarmStages, parseDockerfileRuntimeImages, } from './dockerfile-parse/index.mts';
 export type { DockerfilePrewarmStage, DockerfileRuntimeImage, ParseDockerfilePrewarmOptions, ParseDockerfileRuntimeImagesOptions, } from './dockerfile-parse/index.mts';
-export { buildSccArgs, checkSccComplexity, parseSccComplexityViolations, SCC_COMPLEXITY_LIMIT, } from './scc-complexity/index.mts';
-export type { SccComplexityOptions, SccComplexityViolation } from './scc-complexity/index.mts';
+export { buildSccArgs, checkSccComplexity, parseSccComplexityBaseline, parseSccComplexityViolations, SCC_COMPLEXITY_BASELINE_VERSION, SCC_COMPLEXITY_LIMIT, } from './scc-complexity/index.mts';
+export type { SccComplexityBaseline, SccComplexityBaselineEntry, SccComplexityOptions, SccComplexityScope, SccComplexityViolation, } from './scc-complexity/index.mts';
 export { assertWorkflowCommandDrift, parseCiLocalArgs, runCiLocal } from './ci-local/index.mts';
 export type { CiLocalCommand, CiLocalSpawn, CiLocalSpawnOptions, CiLocalSpawnResult, CiLocalTarget, RunCiLocalOptions, } from './ci-local/index.mts';
 export { GitHubRateLimitError, isRateLimited, isRetryableCancellationError, MAX_RATE_LIMIT_WAIT_MS, rateLimitDelay, reserveRateLimitDelay, } from './gha-rate-limit/index.mts';

package/dist/index.mjs

@@ -39,7 +39,7 @@ export { nextPageCursorFromLinkHeader, nextPageUrlFromLinkHeader, validatePagina
 export { cmdDownloadCoverage, cmdDownloadVitestBlobs, cmdUpload, mintPresignedControl, transportObjectKeys, } from './coverage-transport/index.mjs';
 export { EPOCH_PRUNED_AT, normalizeDeployedLayer, pruneDeployedRuntimeDeps, restoreDeployedWorkspacePackages, } from './pnpm-deploy/index.mjs';
 export { parseDockerfilePrewarmStages, parseDockerfileRuntimeImages, } from './dockerfile-parse/index.mjs';
-export { buildSccArgs, checkSccComplexity, parseSccComplexityViolations, SCC_COMPLEXITY_LIMIT, } from './scc-complexity/index.mjs';
+export { buildSccArgs, checkSccComplexity, parseSccComplexityBaseline, parseSccComplexityViolations, SCC_COMPLEXITY_BASELINE_VERSION, SCC_COMPLEXITY_LIMIT, } from './scc-complexity/index.mjs';
 export { assertWorkflowCommandDrift, parseCiLocalArgs, runCiLocal } from './ci-local/index.mjs';
 export { GitHubRateLimitError, isRateLimited, isRetryableCancellationError, MAX_RATE_LIMIT_WAIT_MS, rateLimitDelay, reserveRateLimitDelay, } from './gha-rate-limit/index.mjs';
 export { CHECKPOINT_MARKER, isTrustedCheckpointComment, parseCheckpoint, renderCheckpoint, sortedCheckpointCandidates, validateCheckpoint, } from './gha-pr-checkpoint/index.mjs';

package/dist/markdown/ast.d.mts

@@ -0,0 +1,8 @@
+import type { Root } from 'mdast';
+import type { MarkdownNode } from './types.mts';
+export declare function parseGfmMarkdown(markdown: string): Root;
+export declare function walkMarkdown(node: MarkdownNode, visitor: (node: MarkdownNode) => void): void;
+export declare function findMarkdownNode<T extends MarkdownNode>(node: MarkdownNode, predicate: (node: MarkdownNode) => node is T): T | null;
+export declare function findMarkdownNode(node: MarkdownNode, predicate: (node: MarkdownNode) => boolean): MarkdownNode | null;
+export declare function findMarkdownNodes<T extends MarkdownNode>(node: MarkdownNode, predicate: (node: MarkdownNode) => node is T): T[];
+export declare function findMarkdownNodes(node: MarkdownNode, predicate: (node: MarkdownNode) => boolean): MarkdownNode[];

package/dist/markdown/ast.mjs

@@ -0,0 +1,29 @@
+import { remark } from 'remark';
+import remarkGfm from 'remark-gfm';
+const processor = remark().use(remarkGfm);
+export function parseGfmMarkdown(markdown) {
+    return processor.parse(markdown);
+}
+export function walkMarkdown(node, visitor) {
+    visitor(node);
+    if (!('children' in node))
+        return;
+    for (const child of node.children)
+        walkMarkdown(child, visitor);
+}
+export function findMarkdownNode(node, predicate) {
+    let match = null;
+    walkMarkdown(node, (candidate) => {
+        if (!match && predicate(candidate))
+            match = candidate;
+    });
+    return match;
+}
+export function findMarkdownNodes(node, predicate) {
+    const matches = [];
+    walkMarkdown(node, (candidate) => {
+        if (predicate(candidate))
+            matches.push(candidate);
+    });
+    return matches;
+}

package/dist/markdown/index.d.mts

@@ -0,0 +1,6 @@
+export { findMarkdownNode, findMarkdownNodes, parseGfmMarkdown, walkMarkdown } from './ast.mts';
+export { extractLooseMarkdownTableRows } from './loose-pipe-rows.mts';
+export { markdownSectionBetweenHeadings } from './sections.mts';
+export { extractMarkdownTables, parseMarkdownTables } from './tables.mts';
+export { markdownNodeText } from './text.mts';
+export type { LooseMarkdownTableRow, LooseMarkdownTableRowsOptions, MarkdownNode, MarkdownSection, MarkdownSectionOptions, MarkdownTableRow, MarkdownTextOptions, ParseMarkdownTablesOptions, PositionedMarkdownTable, } from './types.mts';

package/dist/markdown/index.mjs

@@ -0,0 +1,5 @@
+export { findMarkdownNode, findMarkdownNodes, parseGfmMarkdown, walkMarkdown } from './ast.mjs';
+export { extractLooseMarkdownTableRows } from './loose-pipe-rows.mjs';
+export { markdownSectionBetweenHeadings } from './sections.mjs';
+export { extractMarkdownTables, parseMarkdownTables } from './tables.mjs';
+export { markdownNodeText } from './text.mjs';

package/dist/markdown/loose-pipe-rows.d.mts

@@ -0,0 +1,2 @@
+import type { LooseMarkdownTableRow, LooseMarkdownTableRowsOptions } from './types.mts';
+export declare function extractLooseMarkdownTableRows(markdown: string, options?: LooseMarkdownTableRowsOptions): LooseMarkdownTableRow[];

package/dist/markdown/loose-pipe-rows.mjs

@@ -0,0 +1,31 @@
+export function extractLooseMarkdownTableRows(markdown, options = {}) {
+    const rows = [];
+    let offset = 0;
+    for (const [index, line] of markdown.split('\n').entries()) {
+        if (!isExcluded(offset, offset + line.length, options.excludePositions)) {
+            const cells = parseLoosePipeRow(line);
+            if (cells.length > 0)
+                rows.push({ cells, line: index + 1, offset });
+        }
+        offset += line.length + 1;
+    }
+    return rows;
+}
+function isExcluded(lineStart, lineEnd, positions) {
+    return (positions?.some((position) => {
+        const start = position.start.offset;
+        const end = position.end.offset;
+        return start !== undefined && end !== undefined && lineStart < end && lineEnd > start;
+    }) ?? false);
+}
+function parseLoosePipeRow(line) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith('|'))
+        return [];
+    const row = trimmed.endsWith('|') ? trimmed.slice(1, -1) : trimmed.slice(1);
+    const cells = row
+        .split('|')
+        .map((cell) => cell.trim())
+        .filter(Boolean);
+    return cells.every((cell) => /^:?-{3,}:?$/u.test(cell)) ? [] : cells;
+}

package/dist/markdown/sections.d.mts

@@ -0,0 +1,2 @@
+import type { MarkdownSection, MarkdownSectionOptions } from './types.mts';
+export declare function markdownSectionBetweenHeadings(markdown: string, start: string, end: string, options?: MarkdownSectionOptions): MarkdownSection | null;

package/dist/markdown/sections.mjs

@@ -0,0 +1,25 @@
+import { parseGfmMarkdown } from './ast.mjs';
+import { markdownNodeText } from './text.mjs';
+export function markdownSectionBetweenHeadings(markdown, start, end, options = {}) {
+    const children = parseGfmMarkdown(markdown).children;
+    const startIndex = children.findIndex((node) => isNamedHeading(node, start));
+    if (startIndex < 0)
+        return null;
+    const startHeading = children[startIndex];
+    const endIndex = children.findIndex((node, index) => index > startIndex &&
+        isNamedHeading(node, end) &&
+        (options.endBoundary === 'any' || node.depth <= startHeading.depth));
+    const endHeading = endIndex < 0 ? null : children[endIndex];
+    const startOffset = startHeading.position.end.offset;
+    const endOffset = endHeading ? endHeading.position.start.offset : markdown.length;
+    return {
+        content: markdown.slice(startOffset, endOffset),
+        endHeading,
+        endOffset,
+        startHeading,
+        startOffset,
+    };
+}
+function isNamedHeading(node, expected) {
+    return node.type === 'heading' && markdownNodeText(node, { whitespace: 'collapse' }) === expected;
+}

package/dist/markdown/tables.d.mts

@@ -0,0 +1,3 @@
+import type { MarkdownNode, MarkdownTableRow, ParseMarkdownTablesOptions, PositionedMarkdownTable } from './types.mts';
+export declare function extractMarkdownTables(root: MarkdownNode): PositionedMarkdownTable[];
+export declare function parseMarkdownTables(markdown: string, options?: ParseMarkdownTablesOptions): MarkdownTableRow[][];

package/dist/markdown/tables.mjs

@@ -0,0 +1,43 @@
+import { findMarkdownNodes, parseGfmMarkdown } from './ast.mjs';
+import { markdownNodeText } from './text.mjs';
+export function extractMarkdownTables(root) {
+    return findMarkdownNodes(root, (node) => node.type === 'table').map((table) => {
+        const result = {
+            rows: normalizeTableRows(table),
+        };
+        if (table.position)
+            result.position = table.position;
+        return result;
+    });
+}
+export function parseMarkdownTables(markdown, options = {}) {
+    const root = parseGfmMarkdown(normalizeTableDelimiterRows(markdown));
+    return findMarkdownNodes(root, (node) => node.type === 'table').map((table) => normalizeTableRows(table, {
+        inlineCode: options.preserveInlineCodeMarkers ? 'markers' : 'content',
+        issueReferences: 'brackets',
+    }));
+}
+function normalizeTableRows(table, textOptions = {}) {
+    return table.children.map((row) => ({
+        cells: row.children.map((cell) => markdownNodeText(cell, textOptions).trim()),
+        line: row.position?.start.line ?? 1,
+    }));
+}
+function normalizeTableDelimiterRows(markdown) {
+    return markdown
+        .split('\n')
+        .map((line) => {
+        const trimmed = line.trim();
+        if (!trimmed.startsWith('|'))
+            return line;
+        const cells = trimmed
+            .replace(/^\|/u, '')
+            .replace(/\|$/u, '')
+            .split('|')
+            .map((cell) => cell.trim());
+        if (!cells.every((cell) => /^:?-+:?$/u.test(cell)))
+            return line;
+        return `| ${cells.map((cell) => cell.replace(/-+/u, '---')).join(' | ')} |`;
+    })
+        .join('\n');
+}

package/dist/markdown/text.d.mts

@@ -0,0 +1,2 @@
+import type { MarkdownNode, MarkdownTextOptions } from './types.mts';
+export declare function markdownNodeText(node: MarkdownNode, options?: MarkdownTextOptions): string;

package/dist/markdown/text.mjs

@@ -0,0 +1,22 @@
+export function markdownNodeText(node, options = {}) {
+    const text = textFor(node, options);
+    return options.whitespace === 'collapse' ? text.replace(/\s+/gu, ' ').trim() : text;
+}
+function textFor(node, options) {
+    if (node.type === 'break')
+        return ' ';
+    if ('value' in node && typeof node.value === 'string') {
+        if (node.type === 'inlineCode' && options.inlineCode === 'markers')
+            return `\`${node.value}\``;
+        return node.value;
+    }
+    if (!('children' in node))
+        return '';
+    const text = node.children.map((child) => textFor(child, options)).join('');
+    if (options.issueReferences === 'brackets' &&
+        (node.type === 'link' || node.type === 'linkReference') &&
+        /^#\d+$/u.test(text.trim())) {
+        return `[${text.trim()}]`;
+    }
+    return text;
+}

package/dist/markdown/types.d.mts

@@ -0,0 +1,35 @@
+import type { Heading, Root, RootContent } from 'mdast';
+import type { Position } from 'unist';
+export type MarkdownNode = Root | RootContent;
+export type MarkdownTableRow = {
+    cells: string[];
+    line: number;
+};
+export type PositionedMarkdownTable = {
+    position?: Position;
+    rows: MarkdownTableRow[];
+};
+export type MarkdownTextOptions = {
+    inlineCode?: 'content' | 'markers';
+    issueReferences?: 'text' | 'brackets';
+    whitespace?: 'preserve' | 'collapse';
+};
+export type ParseMarkdownTablesOptions = {
+    preserveInlineCodeMarkers?: boolean;
+};
+export type MarkdownSectionOptions = {
+    endBoundary?: 'same-or-higher' | 'any';
+};
+export type LooseMarkdownTableRowsOptions = {
+    excludePositions?: readonly Position[];
+};
+export type MarkdownSection = {
+    content: string;
+    endHeading: Heading | null;
+    endOffset: number;
+    startHeading: Heading;
+    startOffset: number;
+};
+export type LooseMarkdownTableRow = MarkdownTableRow & {
+    offset: number;
+};

package/dist/markdown/types.mjs

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

package/dist/scc-complexity/baseline.d.mts

@@ -0,0 +1,6 @@
+import type { SccComplexityBaseline, SccComplexityBaselineEntry, SccComplexityScope, SccComplexityValue } from './types.mts';
+export declare const SCC_COMPLEXITY_BASELINE_VERSION: 1;
+export declare function parseSccComplexityBaseline(json: string): SccComplexityBaseline;
+export declare function validateSccComplexityBaseline(baseline: SccComplexityBaseline, scopes: readonly SccComplexityScope[], trackedFileSet: ReadonlySet<string>, valuesByScope: ReadonlyMap<string, readonly SccComplexityValue[]>): void;
+export declare function normalizeSccComplexityBaseline(baseline: SccComplexityBaseline, repoRoot: string): SccComplexityBaseline;
+export declare function baselineEntryByScopeAndFile(baseline: SccComplexityBaseline | undefined): ReadonlyMap<string, ReadonlyMap<string, SccComplexityBaselineEntry>>;

package/dist/scc-complexity/baseline.mjs

@@ -0,0 +1,87 @@
+import { canonicalRepoPath, isInScope } from './paths.mjs';
+export const SCC_COMPLEXITY_BASELINE_VERSION = 1;
+export function parseSccComplexityBaseline(json) {
+    const parsed = JSON.parse(json);
+    if (!isRecord(parsed))
+        throw new Error('baseline must be an object');
+    if (parsed.version !== SCC_COMPLEXITY_BASELINE_VERSION)
+        throw new Error(`baseline version must be ${SCC_COMPLEXITY_BASELINE_VERSION}`);
+    if (!Array.isArray(parsed.entries))
+        throw new Error('baseline entries must be an array');
+    const entries = parsed.entries.map(parseEntry);
+    const seen = new Map();
+    for (const entry of entries) {
+        if (seen.get(entry.scope)?.has(entry.file))
+            throw new Error(`baseline entry ${entry.scope}:${entry.file} is duplicated`);
+        const files = seen.get(entry.scope) ?? new Set();
+        files.add(entry.file);
+        seen.set(entry.scope, files);
+    }
+    return { entries, version: SCC_COMPLEXITY_BASELINE_VERSION };
+}
+export function validateSccComplexityBaseline(baseline, scopes, trackedFileSet, valuesByScope) {
+    const scopeByName = new Map(scopes.map((scope) => [scope.name, scope]));
+    const allFiles = new Set();
+    for (const values of valuesByScope.values()) {
+        for (const value of values)
+            allFiles.add(value.file);
+    }
+    for (const entry of baseline.entries) {
+        const key = `${entry.scope}:${entry.file}`;
+        const scope = scopeByName.get(entry.scope);
+        if (!scope)
+            throw new Error(`baseline entry ${key} is out of scope`);
+        if (!trackedFileSet.has(entry.file))
+            throw new Error(`baseline entry ${key} is untracked`);
+        if (!isInScope(entry.file, scope.includePaths))
+            throw new Error(`baseline entry ${key} is out of scope`);
+        const value = valuesByScope.get(scope.name)?.find((item) => item.file === entry.file);
+        if (!value) {
+            if (allFiles.has(entry.file))
+                throw new Error(`baseline entry ${key} is out of scope`);
+            throw new Error(`baseline entry ${key} is stale`);
+        }
+        if (value.complexity <= (scope.limit ?? 50))
+            throw new Error(`baseline entry ${key} is stale`);
+    }
+}
+export function normalizeSccComplexityBaseline(baseline, repoRoot) {
+    const entries = baseline.entries.map((entry) => ({
+        ...entry,
+        file: canonicalRepoPath(repoRoot, entry.file),
+    }));
+    const seen = new Map();
+    for (const entry of entries) {
+        if (seen.get(entry.scope)?.has(entry.file))
+            throw new Error(`baseline entry ${entry.scope}:${entry.file} is duplicated`);
+        const files = seen.get(entry.scope) ?? new Set();
+        files.add(entry.file);
+        seen.set(entry.scope, files);
+    }
+    return { entries, version: baseline.version };
+}
+export function baselineEntryByScopeAndFile(baseline) {
+    const scopes = new Map();
+    for (const entry of baseline?.entries ?? []) {
+        const files = scopes.get(entry.scope) ?? new Map();
+        files.set(entry.file, entry);
+        scopes.set(entry.scope, files);
+    }
+    return scopes;
+}
+function parseEntry(value, index) {
+    if (!isRecord(value))
+        throw new Error(`baseline entry ${index} must be an object`);
+    if (typeof value.scope !== 'string' || value.scope.length === 0)
+        throw new Error(`baseline entry ${index} has an invalid scope`);
+    if (typeof value.file !== 'string' || value.file.length === 0)
+        throw new Error(`baseline entry ${index} has an invalid file`);
+    if (typeof value.complexity !== 'number' ||
+        !Number.isSafeInteger(value.complexity) ||
+        value.complexity < 0)
+        throw new Error(`baseline entry ${index} has an invalid complexity`);
+    return { complexity: value.complexity, file: value.file, scope: value.scope };
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/dist/scc-complexity/index.d.mts

@@ -1,19 +1,11 @@
 import type { SharedContext } from '../shared-context/index.mts';
+import type { SccComplexityOptions, SccComplexityScope, SccComplexityViolation } from './types.mts';
+export { parseSccComplexityBaseline, SCC_COMPLEXITY_BASELINE_VERSION } from './baseline.mts';
+export type { SccComplexityBaseline, SccComplexityBaselineEntry, SccComplexityOptions, SccComplexityScope, SccComplexityViolation, } from './types.mts';
 export declare const SCC_COMPLEXITY_LIMIT = 50;
-export interface SccComplexityOptions {
-    limit?: number;
-    includeExt?: string;
-    excludeDir?: string;
-    notMatch?: string;
-    tmpdirPrefix?: string;
-    command?: string;
-}
-export interface SccComplexityViolation {
-    file: string;
-    complexity: number;
-}
+type RunScc = (outputPath: string, scope?: SccComplexityScope) => Promise<string>;
 export declare function buildSccArgs(options?: SccComplexityOptions): string[];
-export declare function checkSccComplexity(ctx: SharedContext, options?: SccComplexityOptions, runScc?: (outputPath: string) => Promise<string>): Promise<{
+export declare function checkSccComplexity(ctx: SharedContext, options?: SccComplexityOptions, runScc?: RunScc): Promise<{
     errors: string[];
 }>;
 export declare function parseSccComplexityViolations(json: string, trackedFileSet: ReadonlySet<string>, limit?: number): SccComplexityViolation[];

package/dist/scc-complexity/index.mjs

@@ -3,7 +3,11 @@ import { mkdtemp, readFile, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { promisify } from 'node:util';
+import { baselineEntryByScopeAndFile, normalizeSccComplexityBaseline, validateSccComplexityBaseline, } from './baseline.mjs';
+import { canonicalRepoPath, isInsideRepo } from './paths.mjs';
+import { parseSccComplexityValues } from './parser.mjs';
 const execFileAsync = promisify(execFile);
+export { parseSccComplexityBaseline, SCC_COMPLEXITY_BASELINE_VERSION } from './baseline.mjs';
 export const SCC_COMPLEXITY_LIMIT = 50;
 const DEFAULT_INCLUDE_EXT = 'js,mts,jsx,ts,tsx';
 const DEFAULT_EXCLUDE_DIR = '.git,fixtures,__tests__,test-helpers';
@@ -26,17 +30,17 @@ export function buildSccArgs(options = {}) {
     ];
 }
 export async function checkSccComplexity(ctx, options = {}, runScc) {
-    if (!ctx.isInsideGitRepo) {
+    if (!ctx.isInsideGitRepo)
         return { errors: [`::error::${ctx.repoRoot} is not inside a git repository`] };
-    }
     const dir = await mkdtemp(join(tmpdir(), options.tmpdirPrefix ?? DEFAULT_TMPDIR_PREFIX));
-    const outputPath = join(dir, 'scc.json');
-    const limit = options.limit ?? SCC_COMPLEXITY_LIMIT;
     try {
-        const resolve = runScc ?? ((path) => runSccJson(ctx.repoRoot, path, options));
-        const json = await resolve(outputPath);
-        const violations = parseSccComplexityViolations(json, ctx.trackedFileSet, limit);
-        return { errors: violations.map((violation) => formatViolation(violation, limit)) };
+        const scopes = normalizeScopes(scopesFor(options), ctx.repoRoot);
+        const trackedFileSet = new Set([...ctx.trackedFileSet].map((file) => canonicalRepoPath(ctx.repoRoot, file)));
+        const baseline = options.baseline && normalizeSccComplexityBaseline(options.baseline, ctx.repoRoot);
+        const results = await runScopes(ctx, options, scopes, dir, trackedFileSet, runScc);
+        if (baseline)
+            validateSccComplexityBaseline(baseline, scopes, trackedFileSet, new Map(results.map(({ scope, values }) => [scope.name, values])));
+        return { errors: formatViolations(results, baseline) };
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
@@ -47,44 +51,77 @@ export async function checkSccComplexity(ctx, options = {}, runScc) {
     }
 }
 export function parseSccComplexityViolations(json, trackedFileSet, limit = SCC_COMPLEXITY_LIMIT) {
-    const parsed = JSON.parse(json);
-    if (!Array.isArray(parsed))
-        throw new Error('scc JSON output must be an array');
-    const violations = [];
-    for (const language of parsed) {
-        if (!Array.isArray(language.Files))
-            continue;
-        for (const file of language.Files) {
-            if (typeof file.Location !== 'string')
-                continue;
-            if (!trackedFileSet.has(file.Location))
-                continue;
-            if (typeof file.Complexity !== 'number')
-                continue;
-            if (file.Complexity <= limit)
-                continue;
-            violations.push({ file: file.Location, complexity: file.Complexity });
-        }
+    return parseSccComplexityValues(json, trackedFileSet)
+        .filter((value) => value.complexity > limit)
+        .toSorted(compare);
+}
+function scopesFor(options) {
+    if (!options.scopes) {
+        if (options.baseline)
+            throw new Error('baseline requires named scopes');
+        return [{ includePaths: [], name: '', ...options }];
+    }
+    if (options.scopes.length === 0)
+        throw new Error('scopes must not be empty');
+    const names = new Set();
+    for (const scope of options.scopes) {
+        if (!scope.name || names.has(scope.name))
+            throw new Error(`scope name ${scope.name || '(empty)'} is invalid`);
+        if (scope.includePaths.length === 0 || scope.includePaths.some((path) => !path))
+            throw new Error(`scope ${scope.name} must include at least one path`);
+        names.add(scope.name);
     }
-    return violations.toSorted((a, b) => b.complexity - a.complexity || a.file.localeCompare(b.file));
+    return options.scopes;
 }
-async function runSccJson(repoRoot, outputPath, options) {
-    try {
-        await execFileAsync(options.command ?? 'scc', [...buildSccArgs(options), '--output', outputPath], {
-            cwd: repoRoot,
-            maxBuffer: 1024 * 1024,
+function normalizeScopes(scopes, repoRoot) {
+    return scopes.map((scope) => {
+        const includePaths = scope.includePaths.map((path) => canonicalRepoPath(repoRoot, path));
+        if (includePaths.some((path) => !isInsideRepo(path)))
+            throw new Error(`scope ${scope.name} includes a path outside the repository`);
+        return { ...scope, includePaths };
+    });
+}
+async function runScopes(ctx, options, scopes, dir, trackedFileSet, runScc) {
+    const results = [];
+    for (const [index, scope] of scopes.entries()) {
+        const outputPath = join(dir, `scope-${index}.json`);
+        const resolve = runScc ?? ((path) => runSccJson(ctx.repoRoot, path, options, scope));
+        results.push({
+            scope,
+            values: parseSccComplexityValues(await resolve(outputPath, scope), trackedFileSet, ctx.repoRoot),
         });
     }
+    return results;
+}
+function formatViolations(results, baseline) {
+    const entries = baselineEntryByScopeAndFile(baseline);
+    return results.flatMap(({ scope, values }) => values.flatMap((value) => {
+        const limit = scope.limit ?? SCC_COMPLEXITY_LIMIT;
+        if (value.complexity <= limit)
+            return [];
+        const entry = entries.get(scope.name)?.get(value.file);
+        if (entry && value.complexity <= entry.complexity)
+            return [];
+        const prefix = scope.name ? `[${scope.name}] ` : '';
+        const detail = entry
+            ? `scc complexity ${value.complexity} exceeds baseline ceiling ${entry.complexity}`
+            : `scc complexity ${value.complexity} exceeds ${limit}; simplify or split this file`;
+        return [`::error file=${value.file}::${prefix}${value.file}: ${detail}`];
+    }));
+}
+async function runSccJson(repoRoot, outputPath, options, scope) {
+    try {
+        await execFileAsync(options.command ?? 'scc', [...buildSccArgs({ ...options, ...scope }), ...scope.includePaths, '--output', outputPath], { cwd: repoRoot, maxBuffer: 1024 * 1024 });
+    }
     catch (error) {
-        if (isNodeSystemError(error) && error.code === 'ENOENT') {
+        if (isNodeSystemError(error) && error.code === 'ENOENT')
             throw new Error('scc executable not found; install with mise install', { cause: error });
-        }
         throw error;
     }
     return readFile(outputPath, 'utf8');
 }
-function formatViolation({ file, complexity }, limit) {
-    return `::error file=${file}::${file}: scc complexity ${complexity} exceeds ${limit}; simplify or split this file`;
+function compare(a, b) {
+    return b.complexity - a.complexity || a.file.localeCompare(b.file);
 }
 function isNodeSystemError(error) {
     return error instanceof Error && 'code' in error;

package/dist/scc-complexity/parser.d.mts

@@ -0,0 +1,2 @@
+import type { SccComplexityValue } from './types.mts';
+export declare function parseSccComplexityValues(json: string, trackedFileSet: ReadonlySet<string>, repoRoot?: string): SccComplexityValue[];

package/dist/scc-complexity/parser.mjs

@@ -0,0 +1,21 @@
+import { canonicalRepoPath } from './paths.mjs';
+export function parseSccComplexityValues(json, trackedFileSet, repoRoot) {
+    const parsed = JSON.parse(json);
+    if (!Array.isArray(parsed))
+        throw new Error('scc JSON output must be an array');
+    const values = [];
+    for (const language of parsed) {
+        if (!Array.isArray(language.Files))
+            continue;
+        for (const file of language.Files) {
+            if (typeof file.Location !== 'string')
+                continue;
+            const location = repoRoot ? canonicalRepoPath(repoRoot, file.Location) : file.Location;
+            if (!trackedFileSet.has(location))
+                continue;
+            if (typeof file.Complexity === 'number')
+                values.push({ complexity: file.Complexity, file: location });
+        }
+    }
+    return values.toSorted((a, b) => b.complexity - a.complexity || a.file.localeCompare(b.file));
+}

package/dist/scc-complexity/paths.d.mts

@@ -0,0 +1,3 @@
+export declare function canonicalRepoPath(repoRoot: string, path: string): string;
+export declare function isInsideRepo(path: string): boolean;
+export declare function isInScope(file: string, includePaths: readonly string[]): boolean;

package/dist/scc-complexity/paths.mjs

@@ -0,0 +1,11 @@
+import { relative, resolve } from 'node:path';
+export function canonicalRepoPath(repoRoot, path) {
+    const relativePath = relative(repoRoot, resolve(repoRoot, path.replaceAll('\\', '/'))).replaceAll('\\', '/');
+    return relativePath || '.';
+}
+export function isInsideRepo(path) {
+    return path !== '..' && !path.startsWith('../');
+}
+export function isInScope(file, includePaths) {
+    return includePaths.some((includePath) => includePath === '.' || file === includePath || file.startsWith(`${includePath}/`));
+}

package/dist/scc-complexity/types.d.mts

@@ -0,0 +1,32 @@
+interface SccComplexitySettings {
+    limit?: number;
+    includeExt?: string;
+    excludeDir?: string;
+    notMatch?: string;
+}
+export interface SccComplexityScope extends SccComplexitySettings {
+    name: string;
+    includePaths: readonly string[];
+}
+export interface SccComplexityBaselineEntry {
+    scope: string;
+    file: string;
+    complexity: number;
+}
+export interface SccComplexityBaseline {
+    version: 1;
+    entries: readonly SccComplexityBaselineEntry[];
+}
+export interface SccComplexityOptions extends SccComplexitySettings {
+    tmpdirPrefix?: string;
+    command?: string;
+    scopes?: readonly SccComplexityScope[];
+    baseline?: SccComplexityBaseline;
+}
+export interface SccComplexityViolation {
+    file: string;
+    complexity: number;
+}
+export interface SccComplexityValue extends SccComplexityViolation {
+}
+export {};

package/dist/scc-complexity/types.mjs

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vouchington-tooling",
-  "version": "0.13.1",
+  "version": "0.13.2",
   "description": "Vouchington CLI and extractable tooling libraries.",
   "homepage": "https://github.com/vouchington/vouchington-tooling/tree/main/packages/vouchington-tooling#readme",
   "bugs": {
@@ -178,6 +178,11 @@
       "import": "./dist/csv/index.mjs",
       "default": "./dist/csv/index.mjs"
     },
+    "./markdown": {
+      "types": "./dist/markdown/index.d.mts",
+      "import": "./dist/markdown/index.mjs",
+      "default": "./dist/markdown/index.mjs"
+    },
     "./http-body": {
       "types": "./dist/http-body/index.d.mts",
       "import": "./dist/http-body/index.mjs",
@@ -294,10 +299,14 @@
     "typecheck": "tsc --noEmit --project tsconfig.json"
   },
   "dependencies": {
+    "@types/mdast": "4.0.4",
+    "@types/unist": "3.0.3",
     "csv-parse": "7.0.2",
     "csv-stringify": "6.8.3",
     "dockerfile-ast": "0.7.1",
     "picomatch": "4.0.7",
+    "remark": "15.0.1",
+    "remark-gfm": "4.0.1",
     "smol-toml": "1.8.0",
     "yaml": "2.9.0"
   },