vouchington-tooling 0.13.1 → 0.13.3

package/dist/scc-complexity/index.mjs

@@ -3,8 +3,15 @@ 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 { SCC_COMPLEXITY_LIMIT } from './constants.mjs';
+import { canonicalRepoPath } from './paths.mjs';
+import { parseSccComplexityValues } from './parser.mjs';
+import { normalizeScopes, scopesFor } from './scope-config.mjs';
+import { escapeWorkflowCommandMessage, escapeWorkflowCommandProperty } from './workflow-command.mjs';
 const execFileAsync = promisify(execFile);
-export const SCC_COMPLEXITY_LIMIT = 50;
+export { parseSccComplexityBaseline, SCC_COMPLEXITY_BASELINE_VERSION } from './baseline.mjs';
+export { SCC_COMPLEXITY_LIMIT } from './constants.mjs';
 const DEFAULT_INCLUDE_EXT = 'js,mts,jsx,ts,tsx';
 const DEFAULT_EXCLUDE_DIR = '.git,fixtures,__tests__,test-helpers';
 const DEFAULT_NOT_MATCH = String.raw `\.(test|spec)\.`;
@@ -26,65 +33,83 @@ export function buildSccArgs(options = {}) {
     ];
 }
 export async function checkSccComplexity(ctx, options = {}, runScc) {
-    if (!ctx.isInsideGitRepo) {
-        return { errors: [`::error::${ctx.repoRoot} is not inside a git repository`] };
-    }
+    if (!ctx.isInsideGitRepo)
+        return {
+            errors: [
+                `::error::${escapeWorkflowCommandMessage(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 = await normalizeScopes(scopesFor(options), ctx.repoRoot, options.limit);
+        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);
-        return { errors: [`::error::scc-complexity failed: ${message}`] };
+        return { errors: [`::error::scc-complexity failed: ${escapeWorkflowCommandMessage(message)}`] };
     }
     finally {
         await rm(dir, { force: true, recursive: true });
     }
 }
 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);
+}
+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));
+        const values = parseSccComplexityValues(await resolve(outputPath, scope), trackedFileSet, ctx.repoRoot);
+        const outside = values.find((value) => !isInScopeResult(scope, value.file));
+        if (outside)
+            throw new Error(`scope ${scope.name} received result outside its paths: ${outside.file}`);
+        results.push({ scope, values });
     }
-    return violations.toSorted((a, b) => b.complexity - a.complexity || a.file.localeCompare(b.file));
+    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=${escapeWorkflowCommandProperty(value.file)}::${escapeWorkflowCommandMessage(`${prefix}${value.file}: ${detail}`)}`,
+        ];
+    }));
+}
+function isInScopeResult(scope, file) {
+    return (scope.includePaths.length === 0 ||
+        scope.includePaths.some((path) => file === path || file.startsWith(`${path}/`) || path === '.'));
 }
-async function runSccJson(repoRoot, outputPath, options) {
+async function runSccJson(repoRoot, outputPath, options, scope) {
     try {
-        await execFileAsync(options.command ?? 'scc', [...buildSccArgs(options), '--output', outputPath], {
-            cwd: repoRoot,
-            maxBuffer: 1024 * 1024,
-        });
+        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,4 @@
+export declare function canonicalRepoPath(repoRoot: string, path: string): string;
+export declare function isInScope(file: string, includePaths: readonly string[]): boolean;
+export declare function canonicalScopePath(repoRoot: string, path: string): Promise<string>;
+export declare function assertWorkflowCommandData(value: string, label: string): void;

package/dist/scc-complexity/paths.mjs

@@ -0,0 +1,44 @@
+import { lstat, realpath } from 'node:fs/promises';
+import { dirname, isAbsolute, relative, resolve, win32 } from 'node:path';
+export function canonicalRepoPath(repoRoot, path) {
+    const relativePath = relative(repoRoot, resolve(repoRoot, path.replaceAll('\\', '/'))).replaceAll('\\', '/');
+    return relativePath || '.';
+}
+function isInsideRepo(path) {
+    return path !== '..' && !path.startsWith('../');
+}
+export function isInScope(file, includePaths) {
+    return includePaths.some((includePath) => includePath === '.' || file === includePath || file.startsWith(`${includePath}/`));
+}
+export async function canonicalScopePath(repoRoot, path) {
+    if (isAbsolute(path) || win32.parse(path).root)
+        throw new Error('path is outside the repository');
+    const physicalRoot = await realpath(repoRoot);
+    const candidatePath = resolve(repoRoot, path.replaceAll('\\', '/'));
+    if (!isInsideRepo(canonicalRepoPath(repoRoot, candidatePath)))
+        throw new Error('path is outside the repository');
+    const physicalPath = await physicalPathFor(candidatePath, repoRoot, physicalRoot);
+    const canonicalPath = canonicalRepoPath(physicalRoot, physicalPath);
+    if (!isInsideRepo(canonicalPath))
+        throw new Error('path is outside the repository');
+    return canonicalPath;
+}
+export function assertWorkflowCommandData(value, label) {
+    if (/[\r\n]/.test(value))
+        throw new Error(`${label} contains a workflow command control character`);
+}
+async function physicalPathFor(path, repoRoot, physicalRoot) {
+    let existingPath = path;
+    while (existingPath !== repoRoot) {
+        try {
+            const physicalPath = await realpath(existingPath);
+            return resolve(physicalPath, relative(existingPath, path));
+        }
+        catch (error) {
+            if ((await lstat(existingPath).catch(() => undefined))?.isSymbolicLink())
+                throw error;
+            existingPath = dirname(existingPath);
+        }
+    }
+    return resolve(physicalRoot, relative(repoRoot, path));
+}

package/dist/scc-complexity/scope-config.d.mts

@@ -0,0 +1,3 @@
+import type { SccComplexityOptions, SccComplexityScope } from './types.mts';
+export declare function scopesFor(options: SccComplexityOptions): readonly SccComplexityScope[];
+export declare function normalizeScopes(scopes: readonly SccComplexityScope[], repoRoot: string, topLevelLimit: number | undefined): Promise<readonly SccComplexityScope[]>;

package/dist/scc-complexity/scope-config.mjs

@@ -0,0 +1,35 @@
+import { assertWorkflowCommandData, canonicalScopePath } from './paths.mjs';
+export 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`);
+        assertWorkflowCommandData(scope.name, 'scope name');
+        if (scope.includePaths.length === 0 || scope.includePaths.some((path) => !path))
+            throw new Error(`scope ${scope.name} must include at least one path`);
+        for (const path of scope.includePaths)
+            assertWorkflowCommandData(path, `scope ${scope.name} path`);
+        names.add(scope.name);
+    }
+    return options.scopes;
+}
+export async function normalizeScopes(scopes, repoRoot, topLevelLimit) {
+    return Promise.all(scopes.map(async (scope) => {
+        let includePaths;
+        try {
+            includePaths = await Promise.all(scope.includePaths.map((path) => canonicalScopePath(repoRoot, path)));
+        }
+        catch {
+            throw new Error(`scope ${scope.name} includes a path outside the repository`);
+        }
+        const limit = scope.limit ?? topLevelLimit;
+        return limit === undefined ? { ...scope, includePaths } : { ...scope, includePaths, limit };
+    }));
+}

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/dist/scc-complexity/workflow-command.d.mts

@@ -0,0 +1,2 @@
+export declare function escapeWorkflowCommandMessage(value: string): string;
+export declare function escapeWorkflowCommandProperty(value: string): string;

package/dist/scc-complexity/workflow-command.mjs

@@ -0,0 +1,6 @@
+export function escapeWorkflowCommandMessage(value) {
+    return value.replaceAll('%', '%25').replaceAll('\r', '%0D').replaceAll('\n', '%0A');
+}
+export function escapeWorkflowCommandProperty(value) {
+    return escapeWorkflowCommandMessage(value).replaceAll(':', '%3A').replaceAll(',', '%2C');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vouchington-tooling",
-  "version": "0.13.1",
+  "version": "0.13.3",
   "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",
@@ -203,6 +208,11 @@
       "import": "./dist/gha-claude-post-review/index.mjs",
       "default": "./dist/gha-claude-post-review/index.mjs"
     },
+    "./gha-check-run": {
+      "types": "./dist/gha-check-run/index.d.mts",
+      "import": "./dist/gha-check-run/index.mjs",
+      "default": "./dist/gha-check-run/index.mjs"
+    },
     "./http-link-pagination": {
       "types": "./dist/http-link-pagination/index.d.mts",
       "import": "./dist/http-link-pagination/index.mjs",
@@ -294,10 +304,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"
   },