@pho9ubenaa/siro 0.6.1 → 0.6.2

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## [0.6.2] — 2026-10-03
+
+- Report oversized custom rule groups as finding-limit errors (CLI exit 2), rather
+  than JavaScript argument-limit failures (exit 70). Larger caller-supplied finding
+  budgets also work without truncating results.
+- Reduce distribution size and repeated configuration work during scans.
+
+Public API, CLI options, decoded JSON schema 3, Node requirements, inspection scope
+and [safety limits](docs/threat-model.md) remain unchanged.
+
 ## [0.6.1] — 2026-10-02
 
 - Add `--no-config` to skip executable repository configuration, and

package/dist/cli.mjs

@@ -1,305 +1,8 @@
 #!/usr/bin/env node
-import { C as isSeverity, D as asAbsPath, E as version, F as SiroError, I as UsageError, M as DEFAULT_SCAN_LIMITS, N as resolveScanLimits, S as isPM, T as SUPPORTED_NODE_RANGE, _ as PROJECT_TYPES, a as DEFAULT_REPORTER_NAME, b as PMS, i as BUILTIN_REPORTER_NAMES, j as isNodeError, k as assertDirectory, l as safeText, m as loadConfig, o as JSON_REPORTER_NAME, r as lintCommand, t as nodeIO, v as isProjectType, w as isSupportedNodeVersion, x as SEVERITIES, y as isStableVersion } from "./node-io-BpAHyeBG.mjs";
-import path from "node:path";
-import { pathToFileURL } from "node:url";
-import { parseArgs } from "node:util";
-//#region src/cli/parsers.ts
-const parsePmFlag = (raw) => {
-	if (typeof raw === "undefined") return;
-	if (raw === true) throw new UsageError(`--pm requires a value (expected one of: ${PMS.join(", ")})`);
-	if (typeof raw !== "string" || !isPM(raw)) throw new UsageError(`Unknown package manager: ${raw} (expected one of: ${PMS.join(", ")})`);
-	return raw;
-};
-const parseProjectTypeFlag = (raw) => {
-	if (typeof raw === "undefined") return;
-	if (raw === true) throw new UsageError(`--project-type requires a value (expected ${PROJECT_TYPES.join("|")})`);
-	if (typeof raw === "string" && isProjectType(raw)) return raw;
-	throw new UsageError(`Unknown project type: ${String(raw)} (expected ${PROJECT_TYPES.join("|")})`);
-};
-const parseSeverityFlag = (raw) => {
-	if (typeof raw === "undefined") return;
-	if (raw === true) throw new UsageError(`--severity requires a value (expected ${SEVERITIES.join("|")})`);
-	if (typeof raw !== "string" || !isSeverity(raw)) throw new UsageError(`Invalid severity: ${String(raw)} (expected ${SEVERITIES.join("|")})`);
-	return raw;
-};
-const ensureNodeVersion = (nodeVersion) => {
-	if (!isSupportedNodeVersion(nodeVersion)) throw new UsageError(`Node ${SUPPORTED_NODE_RANGE} required (you are on ${nodeVersion}). Upgrade your runtime to use siro.`);
-};
-//#endregion
-//#region src/cli/commands.ts
-const COMMANDS = ["lint", "check"];
-const isCommandName = (value) => COMMANDS.some((cmd) => cmd === value);
-//#endregion
-//#region src/cli/parse-args.ts
-const LIMIT_FLAGS = new Map(Object.keys(DEFAULT_SCAN_LIMITS).map((key) => [key.replace(/[A-Z]/gu, (letter) => `-${letter.toLowerCase()}`), key]));
-const REPEATABLE_FLAGS = new Set(["exclude", "installation-root"]);
-const VALUE_FLAGS = new Set([
-	"pm",
-	"pm-version",
-	"project-type",
-	"reporter",
-	"severity",
-	...REPEATABLE_FLAGS,
-	...LIMIT_FLAGS.keys()
-]);
-const BOOLEAN_FLAGS = new Set([
-	"help",
-	"version",
-	"json",
-	"no-config",
-	"strict-filesystem"
-]);
-const parseCommand = (argv) => {
-	const { tokens } = parseArgs({
-		args: [...argv],
-		options: {
-			help: {
-				type: "boolean",
-				short: "h"
-			},
-			version: {
-				type: "boolean",
-				short: "v"
-			}
-		},
-		strict: false,
-		tokens: true
-	});
-	const flags = /* @__PURE__ */ new Map();
-	const repeated = /* @__PURE__ */ new Map();
-	const positionals = [];
-	let error;
-	for (let index = 0; index < tokens.length; index += 1) {
-		const token = tokens[index];
-		if (!token) break;
-		if (token.kind === "option-terminator") {
-			if (index + 1 < tokens.length) error ??= "siro takes no passthrough arguments after `--`.";
-			break;
-		}
-		if (token.kind === "positional") {
-			positionals.push(token.value);
-			continue;
-		}
-		if (BOOLEAN_FLAGS.has(token.name)) if (token.value !== void 0) error ??= `Flag ${token.rawName} does not accept a value.`;
-		else {
-			if ([
-				"json",
-				"no-config",
-				"strict-filesystem"
-			].includes(token.name) && flags.has(token.name)) error ??= `${token.rawName} must be specified only once.`;
-			flags.set(token.name, true);
-		}
-		else if (VALUE_FLAGS.has(token.name)) {
-			let value = token.value;
-			const next = tokens[index + 1];
-			if (value === void 0 && next?.kind === "positional" && next.index === token.index + 1) {
-				value = next.value;
-				index += 1;
-			}
-			if (value === void 0 || value === "") error ??= `${token.rawName} requires a value.`;
-			else if (REPEATABLE_FLAGS.has(token.name)) repeated.set(token.name, [...repeated.get(token.name) ?? [], value]);
-			else {
-				if (flags.has(token.name)) error ??= `${token.rawName} must be specified only once.`;
-				flags.set(token.name, value);
-			}
-		} else error ??= token.name === "workspaces" ? "The --workspaces flag was removed in 0.6.0; discovery is recursive by default. Use --exclude and --installation-root." : `Unknown flag: ${token.rawName}`;
-	}
-	const [command, cwd, ...extra] = positionals;
-	if (flags.has("help")) return {
-		kind: "help",
-		target: command && isCommandName(command) ? command : void 0
-	};
-	if (flags.has("version")) return { kind: "version" };
-	if (error) throw new UsageError(error);
-	if (command === void 0) return { kind: "usage" };
-	if (command === "init") return {
-		kind: "usage",
-		reason: "The 'init' command was removed: siro is lint-only. Run `siro lint --reporter json` and review each finding's remediation."
-	};
-	if (!isCommandName(command)) return {
-		kind: "usage",
-		reason: `Unknown command: ${command}`
-	};
-	if (extra.length > 0) throw new UsageError(`Unexpected extra argument: ${extra.join(" ")}`);
-	if (flags.has("reporter") && flags.has("json")) throw new UsageError("Invalid reporter selection: use either --reporter or --json.");
-	const reporter = flags.get("reporter");
-	const pmVersion = flags.get("pm-version");
-	const pm = parsePmFlag(flags.get("pm"));
-	if (pmVersion !== void 0 && (!pm || !isStableVersion(pmVersion))) throw new UsageError("--pm-version requires --pm and an exact stable version.");
-	const limits = {};
-	for (const [flag, key] of LIMIT_FLAGS) {
-		const value = flags.get(flag);
-		if (value !== void 0) {
-			if (typeof value !== "string" || !/^\d+$/u.test(value)) throw new UsageError(`${flag} must be a positive safe integer.`);
-			limits[key] = Number(value);
-		}
-	}
-	resolveScanLimits(limits);
-	return {
-		kind: "lint",
-		cwd: asAbsPath(path.resolve(cwd ?? process.cwd())),
-		pm,
-		pmVersion: typeof pmVersion === "string" ? pmVersion : void 0,
-		exclude: repeated.get("exclude"),
-		installationRoots: repeated.get("installation-root"),
-		projectType: parseProjectTypeFlag(flags.get("project-type")),
-		severity: parseSeverityFlag(flags.get("severity")),
-		...flags.has("no-config") ? { noConfig: true } : {},
-		...flags.has("strict-filesystem") ? { rejectSymlinks: true } : {},
-		...Object.keys(limits).length ? { limits } : {},
-		reporter: typeof reporter === "string" ? reporter : flags.has("json") ? JSON_REPORTER_NAME : DEFAULT_REPORTER_NAME
-	};
-};
-//#endregion
-//#region src/cli/help.ts
-const PMS_LIST = PMS.join("|");
-const REPORTERS_LIST = BUILTIN_REPORTER_NAMES.join("|");
-const PROJECT_TYPES_LIST = PROJECT_TYPES.join("|");
-const SEVERITIES_LIST = SEVERITIES.join("|");
-const FLAG_LINES = {
-	json: "  --json               Shortcut for --reporter json",
-	safety: "  --no-config          Do not probe or execute repository siro.config.*\n  --strict-filesystem  Reject symlink input paths (not a containment sandbox)",
-	limits: "  --max-file-bytes <n>  Bound each input file (default 8388608)\n  --max-total-bytes <n>  Bound all input reads (default 67108864)\n  --max-entries <n>     Bound native directory entries (default 100000)\n  --max-directories <n> Bound discovered directories (default 10000)\n  --max-directory-depth <n> Bound discovery depth (default 128)\n  --max-config-depth <n> Bound configuration nesting (default 128)\n  --max-findings <n>    Bound unfiltered findings (default 50000)\n  --max-output-bytes <n> Bound report output (default 33554432)",
-	pm: `  --pm <name>          Target a specific package manager (${PMS_LIST})`,
-	pmVersion: "  --pm-version <x.y.z>  Target an exact stable PM version (requires --pm)",
-	inspection: "  --exclude <pattern>  Exclude directories from recursive discovery (repeatable)\n  --installation-root <path>  Inspect local install policy here (repeatable; default .)",
-	projectType: `  --project-type <type>  Project type (${PROJECT_TYPES_LIST}; default auto)`,
-	reporter: `  --reporter <name>    Reporter (${REPORTERS_LIST}; additional reporters can be registered via siro.config.ts)`,
-	severity: `  --severity <level>   Show + fail on findings at or above this level (${SEVERITIES_LIST})`
-};
-const HELP_ROOT = [
-	"siro — security best-practices for the npm ecosystem",
-	"",
-	"USAGE",
-	"  siro <command> [path] [flags]",
-	"",
-	"COMMANDS",
-	"  lint     Report best-practice violations (alias: check)",
-	"",
-	"GLOBAL FLAGS",
-	FLAG_LINES.pm,
-	FLAG_LINES.pmVersion,
-	FLAG_LINES.inspection,
-	FLAG_LINES.projectType,
-	"  --version            Print the siro version",
-	"  --help               Show help for siro or a command",
-	"",
-	"LINT FLAGS",
-	FLAG_LINES.safety,
-	FLAG_LINES.limits,
-	FLAG_LINES.reporter,
-	FLAG_LINES.json,
-	FLAG_LINES.severity,
-	"",
-	"EXAMPLES",
-	"  $ siro lint                         # report violations in cwd",
-	"  $ siro lint --no-config --strict-filesystem  # data-only inspection",
-	"  $ siro lint --reporter github       # GitHub Actions annotations",
-	"  $ siro lint --severity warn         # also fail on warnings",
-	"",
-	"LEARN MORE",
-	"  Quickstart        https://github.com/pHo9UBenaA/siro/blob/main/docs/getting-started.md",
-	"  Rule reference    https://github.com/pHo9UBenaA/siro/blob/main/docs/rules.md",
-	"  Config options    https://github.com/pHo9UBenaA/siro/blob/main/docs/configuration.md"
-].join("\n");
-const HELP_LINT = [
-	"siro lint — report best-practice violations",
-	"",
-	"USAGE",
-	"  siro lint [path] [flags]",
-	"  siro check [path] [flags]        (alias)",
-	"",
-	"FLAGS",
-	FLAG_LINES.safety,
-	FLAG_LINES.limits,
-	FLAG_LINES.pm,
-	FLAG_LINES.pmVersion,
-	FLAG_LINES.inspection,
-	FLAG_LINES.projectType,
-	FLAG_LINES.reporter,
-	FLAG_LINES.json,
-	FLAG_LINES.severity,
-	"",
-	"EXIT CODES",
-	"  0  No findings at or above the active threshold",
-	"  1  Findings at or above the threshold (default: error)",
-	"  2  Usage error (bad flag, broken siro.config.ts, unreadable path, …)",
-	"  70 Output failure/limit, or unexpected exception (including trusted extensions)",
-	"",
-	"EXAMPLES",
-	"  $ siro lint                         # default: pretty reporter, fail on errors",
-	"  $ siro lint --no-config --strict-filesystem  # data-only inspection",
-	"  $ siro lint --reporter github       # GitHub Actions annotations",
-	"  $ siro lint --severity warn         # tighten the gate"
-].join("\n");
-const renderHelp = (target) => {
-	if (typeof target === "undefined") return HELP_ROOT;
-	if (target === "lint" || target === "check") return HELP_LINT;
-	return target;
-};
-//#endregion
-//#region src/cli.ts
-const EXIT_SUCCESS = 0;
-const EXIT_USAGE = 2;
-const EXIT_CRASH = 70;
-const dispatch = async (cmd, io) => {
-	switch (cmd.kind) {
-		case "version":
-			await io.stdout(version);
-			return EXIT_SUCCESS;
-		case "help":
-			await io.stdout(renderHelp(cmd.target));
-			return EXIT_SUCCESS;
-		case "usage":
-			if (cmd.reason) await io.stderr(`${safeText(cmd.reason)}\n`);
-			await io.stderr(renderHelp());
-			return EXIT_USAGE;
-		case "lint": {
-			assertDirectory(cmd.cwd);
-			const { noConfig, ...options } = cmd;
-			if (noConfig) return lintCommand(options, io);
-			const config = await loadConfig(cmd.cwd);
-			return lintCommand({
-				...options,
-				config
-			}, io);
-		}
-		default: throw new Error(`Unhandled command kind: ${String(cmd)}`);
-	}
-};
-const handleError = async (error, io) => {
-	if (error instanceof SiroError) {
-		await io.stderr(safeText(error.message));
-		return error.exitCode;
-	}
-	if (isNodeError(error) && "errno" in error && typeof error.errno === "number") {
-		await io.stderr(safeText(`File system error: ${error.message}`));
-		return EXIT_USAGE;
-	}
-	throw error;
-};
-const run = async (argv, io = nodeIO) => {
-	try {
-		ensureNodeVersion(process.versions.node);
-		return await dispatch(parseCommand(argv), io);
-	} catch (error) {
-		return handleError(error, io);
-	}
-};
-const runMain = async (argv) => {
-	try {
-		process.exitCode = await run(argv);
-	} catch (error) {
-		const errStr = error instanceof Error ? error.stack ?? error.message : String(error);
-		process.exitCode = EXIT_CRASH;
-		try {
-			await nodeIO.stderr(safeText(errStr));
-		} catch {}
-	}
-};
-const [, invokedPath] = process.argv;
-if (invokedPath && import.meta.url === pathToFileURL(invokedPath).href) await runMain(process.argv.slice(2));
-//#endregion
-export { run, runMain };
-
+import{C as isSeverity,D as asAbsPath,E as version,I as SiroError,L as UsageError,M as DEFAULT_SCAN_LIMITS,N as resolveScanLimits,P as isOwnKey,S as isPM,T as SUPPORTED_NODE_RANGE,_ as PROJECT_TYPES,a as DEFAULT_REPORTER_NAME,b as PMS,i as BUILTIN_REPORTER_NAMES,j as isNodeError,k as assertDirectory,l as safeText,m as loadConfig,o as JSON_REPORTER_NAME,r as lintCommand,t as nodeIO,v as isProjectType,w as isSupportedNodeVersion,x as SEVERITIES,y as isStableVersion}from"./node-io-DE7Nzlal.mjs";import path from"node:path";import{pathToFileURL}from"node:url";import{parseArgs}from"node:util";const parsePmFlag=raw=>{if(typeof raw===`undefined`)return;if(typeof raw!==`string`||!isPM(raw))throw new UsageError(`Unknown package manager: ${raw} (expected one of: ${PMS.join(`, `)})`);return raw};const parseProjectTypeFlag=raw=>{if(typeof raw===`undefined`)return;if(typeof raw===`string`&&isProjectType(raw))return raw;throw new UsageError(`Unknown project type: ${String(raw)} (expected ${PROJECT_TYPES.join(`|`)})`)};const parseSeverityFlag=raw=>{if(typeof raw===`undefined`)return;if(typeof raw!==`string`||!isSeverity(raw))throw new UsageError(`Invalid severity: ${String(raw)} (expected ${SEVERITIES.join(`|`)})`);return raw};const ensureNodeVersion=nodeVersion=>{if(!isSupportedNodeVersion(nodeVersion))throw new UsageError(`Node ${SUPPORTED_NODE_RANGE} required (you are on ${nodeVersion}). Upgrade your runtime to use siro.`)};const COMMANDS=[`lint`,`check`];const isCommandName=value=>COMMANDS.some(command=>command===value);const options={maxFileBytes:{flag:`max-file-bytes`,description:`Bound each input file`},maxTotalBytes:{flag:`max-total-bytes`,description:`Bound all input reads`,descriptionColumn:25},maxEntries:{flag:`max-entries`,description:`Bound native directory entries`},maxDirectories:{flag:`max-directories`,description:`Bound discovered directories`},maxDirectoryDepth:{flag:`max-directory-depth`,description:`Bound discovery depth`},maxConfigDepth:{flag:`max-config-depth`,description:`Bound configuration nesting`},maxFindings:{flag:`max-findings`,description:`Bound unfiltered findings`},maxOutputBytes:{flag:`max-output-bytes`,description:`Bound report output`}};const limitOptions=[];for(const key of Object.keys(options)){if(!isOwnKey(options,key))continue;limitOptions.push({key,...options[key]})}const LIMIT_OPTIONS=limitOptions;const limitHelp=LIMIT_OPTIONS.map(({key,flag,description,descriptionColumn=24})=>`${`  --${flag} <n> `.padEnd(descriptionColumn)}${description} (default ${DEFAULT_SCAN_LIMITS[key]})`).join(`
+`);const REPEATABLE_FLAGS=new Set([`exclude`,`installation-root`]);const VALUE_FLAGS=new Set([`pm`,`pm-version`,`project-type`,`reporter`,`severity`,...REPEATABLE_FLAGS,...LIMIT_OPTIONS.map(({flag})=>flag)]);const BOOLEAN_FLAGS=new Set([`help`,`version`,`json`,`no-config`,`strict-filesystem`]);const collectArguments=argv=>{const{tokens}=parseArgs({args:[...argv],options:{help:{type:`boolean`,short:`h`},version:{type:`boolean`,short:`v`}},strict:false,tokens:true});const flags=new Set;const values=new Map;const repeatedFlags=new Map;const positionals=[];let firstError;const remainingTokens=tokens.entries();for(const[index,token]of remainingTokens){if(token.kind===`option-terminator`){if(index+1<tokens.length)firstError??="siro takes no passthrough arguments after `--`.";break}if(token.kind===`positional`){positionals.push(token.value);continue}if(BOOLEAN_FLAGS.has(token.name)){if(token.value!==void 0){firstError??=`Flag ${token.rawName} does not accept a value.`;continue}if([`json`,`no-config`,`strict-filesystem`].includes(token.name)&&flags.has(token.name))firstError??=`${token.rawName} must be specified only once.`;flags.add(token.name);continue}if(!VALUE_FLAGS.has(token.name)){firstError??=token.name===`workspaces`?`The --workspaces flag was removed in 0.6.0; discovery is recursive by default. Use --exclude and --installation-root.`:`Unknown flag: ${token.rawName}`;continue}const next=tokens[index+1];const consumesNext=token.value===void 0&&next?.kind===`positional`&&next.index===token.index+1;const value=consumesNext?next.value:token.value;if(consumesNext)remainingTokens.next();if(value===void 0||value===``){firstError??=`${token.rawName} requires a value.`;continue}if(REPEATABLE_FLAGS.has(token.name)){const occurrences=repeatedFlags.get(token.name)??[];occurrences.push(value);repeatedFlags.set(token.name,occurrences)}else{if(values.has(token.name))firstError??=`${token.rawName} must be specified only once.`;values.set(token.name,value)}}return{flags,values,repeatedFlags,positionals,firstError}};const parseLimitOverrides=values=>{const limits={};for(const{flag,key}of LIMIT_OPTIONS){const value=values.get(flag);if(value===void 0)continue;if(!/^\d+$/u.test(value))throw new UsageError(`${flag} must be a positive safe integer.`);limits[key]=Number(value)}resolveScanLimits(limits);return limits};const parseCommand=argv=>{const{flags,values,repeatedFlags,positionals,firstError}=collectArguments(argv);const[command,cwd,...extra]=positionals;if(flags.has(`help`))return{kind:`help`,target:command&&isCommandName(command)?command:void 0};if(flags.has(`version`))return{kind:`version`};if(firstError)throw new UsageError(firstError);if(command===void 0)return{kind:`usage`};if(command===`init`)return{kind:`usage`,reason:"The 'init' command was removed: siro is lint-only. Run `siro lint --reporter json` and review each finding's remediation."};if(!isCommandName(command))return{kind:`usage`,reason:`Unknown command: ${command}`};if(extra.length>0)throw new UsageError(`Unexpected extra argument: ${extra.join(` `)}`);if(values.has(`reporter`)&&flags.has(`json`))throw new UsageError(`Invalid reporter selection: use either --reporter or --json.`);const reporter=values.get(`reporter`)??(flags.has(`json`)?JSON_REPORTER_NAME:DEFAULT_REPORTER_NAME);const pmVersion=values.get(`pm-version`);const pm=parsePmFlag(values.get(`pm`));if(pmVersion!==void 0&&(!pm||!isStableVersion(pmVersion)))throw new UsageError(`--pm-version requires --pm and an exact stable version.`);const limits=parseLimitOverrides(values);return{kind:`lint`,cwd:asAbsPath(path.resolve(cwd??process.cwd())),pm,pmVersion,exclude:repeatedFlags.get(`exclude`),installationRoots:repeatedFlags.get(`installation-root`),projectType:parseProjectTypeFlag(values.get(`project-type`)),severity:parseSeverityFlag(values.get(`severity`)),...flags.has(`no-config`)?{noConfig:true}:{},...flags.has(`strict-filesystem`)?{rejectSymlinks:true}:{},...Object.keys(limits).length?{limits}:{},reporter}};const PMS_LIST=PMS.join(`|`);const REPORTERS_LIST=BUILTIN_REPORTER_NAMES.join(`|`);const PROJECT_TYPES_LIST=PROJECT_TYPES.join(`|`);const SEVERITIES_LIST=SEVERITIES.join(`|`);const FLAG_LINES={json:`  --json               Shortcut for --reporter json`,safety:`  --no-config          Do not probe or execute repository siro.config.*
+  --strict-filesystem  Reject symlink input paths (not a containment sandbox)`,limits:limitHelp,pm:`  --pm <name>          Target a specific package manager (${PMS_LIST})`,pmVersion:`  --pm-version <x.y.z>  Target an exact stable PM version (requires --pm)`,inspection:`  --exclude <pattern>  Exclude directories from recursive discovery (repeatable)
+  --installation-root <path>  Inspect local install policy here (repeatable; default .)`,projectType:`  --project-type <type>  Project type (${PROJECT_TYPES_LIST}; default auto)`,reporter:`  --reporter <name>    Reporter (${REPORTERS_LIST}; additional reporters can be registered via siro.config.ts)`,severity:`  --severity <level>   Show + fail on findings at or above this level (${SEVERITIES_LIST})`};const HELP_ROOT=[`siro — security best-practices for the npm ecosystem`,``,`USAGE`,`  siro <command> [path] [flags]`,``,`COMMANDS`,`  lint     Report best-practice violations (alias: check)`,``,`GLOBAL FLAGS`,FLAG_LINES.pm,FLAG_LINES.pmVersion,FLAG_LINES.inspection,FLAG_LINES.projectType,`  --version            Print the siro version`,`  --help               Show help for siro or a command`,``,`LINT FLAGS`,FLAG_LINES.safety,FLAG_LINES.limits,FLAG_LINES.reporter,FLAG_LINES.json,FLAG_LINES.severity,``,`EXAMPLES`,`  $ siro lint                         # report violations in cwd`,`  $ siro lint --no-config --strict-filesystem  # data-only inspection`,`  $ siro lint --reporter github       # GitHub Actions annotations`,`  $ siro lint --severity warn         # also fail on warnings`,``,`LEARN MORE`,`  Quickstart        https://github.com/pHo9UBenaA/siro/blob/main/docs/getting-started.md`,`  Rule reference    https://github.com/pHo9UBenaA/siro/blob/main/docs/rules.md`,`  Config options    https://github.com/pHo9UBenaA/siro/blob/main/docs/configuration.md`].join(`
+`);const HELP_LINT=[`siro lint — report best-practice violations`,``,`USAGE`,`  siro lint [path] [flags]`,`  siro check [path] [flags]        (alias)`,``,`FLAGS`,FLAG_LINES.safety,FLAG_LINES.limits,FLAG_LINES.pm,FLAG_LINES.pmVersion,FLAG_LINES.inspection,FLAG_LINES.projectType,FLAG_LINES.reporter,FLAG_LINES.json,FLAG_LINES.severity,``,`EXIT CODES`,`  0  No findings at or above the active threshold`,`  1  Findings at or above the threshold (default: error)`,`  2  Usage error (bad flag, broken siro.config.ts, unreadable path, …)`,`  70 Output failure/limit, or unexpected exception (including trusted extensions)`,``,`EXAMPLES`,`  $ siro lint                         # default: pretty reporter, fail on errors`,`  $ siro lint --no-config --strict-filesystem  # data-only inspection`,`  $ siro lint --reporter github       # GitHub Actions annotations`,`  $ siro lint --severity warn         # tighten the gate`].join(`
+`);const renderHelp=target=>{if(typeof target===`undefined`)return HELP_ROOT;if(target===`lint`||target===`check`)return HELP_LINT;return target};const EXIT_SUCCESS=0;const EXIT_USAGE=2;const EXIT_CRASH=70;const dispatch=async(command,io)=>{switch(command.kind){case`version`:await io.stdout(version);return EXIT_SUCCESS;case`help`:await io.stdout(renderHelp(command.target));return EXIT_SUCCESS;case`usage`:if(command.reason)await io.stderr(`${safeText(command.reason)}\n`);await io.stderr(renderHelp());return EXIT_USAGE;case`lint`:{assertDirectory(command.cwd);const{noConfig,...options}=command;if(noConfig)return lintCommand(options,io);const config=await loadConfig(command.cwd);return lintCommand({...options,config},io)}default:throw new Error(`Unhandled command kind: ${String(command)}`)}};const handleError=async(error,io)=>{if(error instanceof SiroError){await io.stderr(safeText(error.message));return error.exitCode}if(isNodeError(error)&&`errno`in error&&typeof error.errno===`number`){await io.stderr(safeText(`File system error: ${error.message}`));return EXIT_USAGE}throw error};const run=async(argv,io=nodeIO)=>{try{ensureNodeVersion(process.versions.node);return await dispatch(parseCommand(argv),io)}catch(error){return handleError(error,io)}};const runMain=async argv=>{try{process.exitCode=await run(argv)}catch(error){const diagnostic=error instanceof Error?error.stack??error.message:String(error);process.exitCode=EXIT_CRASH;try{await nodeIO.stderr(safeText(diagnostic))}catch{}}};const[,invokedPath]=process.argv;if(invokedPath&&import.meta.url===pathToFileURL(invokedPath).href)await runMain(process.argv.slice(2));export{run,runMain};
 //# sourceMappingURL=cli.mjs.map

package/dist/index.d.mts

@@ -35,12 +35,7 @@ interface ConfigFileRef {
 }
 //#endregion
 //#region src/core/contracts/pms.d.ts
-/**
- * Single source of truth for package managers and severities.
- * Types, runtime sets, and ordering derive from these tuples. Adding a manager
- * still requires local detection signals, applicable rule bindings and verified
- * policy/availability evidence; the tuple alone does not implement support.
- */
+/** Supported identifiers in stable evaluation/display order. */
 declare const PMS: readonly ["npm", "pnpm", "yarn", "bun", "deno", "aube"];
 type PM = (typeof PMS)[number];
 declare const SEVERITIES: readonly ["error", "warn", "info"];
@@ -146,7 +141,7 @@ interface Rule<Id extends string = string> {
 declare const defineRule: <const Id extends string>(rule: Rule<Id>) => Rule<Id>;
 //#endregion
 //#region src/core/contracts/file-system.d.ts
-/** IO boundary: swap in memfs (or any other backend) for tests. */
+/** Read-only filesystem boundary for repository inspection. */
 interface FileSystem {
   /** Ordinary native child directory names, excluding symlinks. Required for recursive discovery. Errors must propagate. */
   readDirectories: (path: AbsPath) => readonly string[];
@@ -235,7 +230,9 @@ type InstallationRootInput = string | {
 //#region src/core/contracts/date-time.d.ts
 /** Host time and native date parsing, including the host timezone for offsetless input. */
 interface DateTime {
+  /** Current epoch milliseconds. */
   now: () => number;
+  /** Epoch milliseconds, or NaN for invalid input; offsetless dates use host semantics. */
   parse: (value: string) => number;
 }
 //#endregion
@@ -301,32 +298,13 @@ interface LintCommandOptions extends LintOptions {
 declare const lint: (options: LintOptions) => LintResult;
 declare const lintCommand: (options: LintCommandOptions, io: IO) => Promise<number>;
 //#endregion
+//#region src/version.d.ts
+declare const version: string;
+//#endregion
 //#region src/load-config.d.ts
 /** Load the first matching config; executable imports always use the real filesystem. */
 declare const loadConfig: (cwd: AbsPath, nodeVersion?: string) => Promise<SiroConfig | undefined>;
 //#endregion
-//#region src/adapters/node-file-system.d.ts
-declare const nodeFileSystem: FileSystem;
-//#endregion
-//#region src/adapters/node-io.d.ts
-declare const nodeIO: IO;
-//#endregion
-//#region src/adapters/reporters/github.d.ts
-/** Emit GitHub Actions workflow commands (annotations on PRs). */
-declare const githubReporter: Reporter<'github'>;
-//#endregion
-//#region src/adapters/reporters/json.d.ts
-declare const jsonReporter: Reporter<'json'>;
-//#endregion
-//#region src/adapters/reporters/pretty.d.ts
-declare const prettyReporter: Reporter<'pretty'>;
-//#endregion
-//#region src/adapters/reporters/registry.d.ts
-/** Names of every built-in reporter, in stable display order. */
-declare const BUILTIN_REPORTER_NAMES: readonly BuiltinReporterName[];
-/** Literal union of every built-in reporter name. */
-type BuiltinReporterName = (typeof prettyReporter | typeof jsonReporter | typeof githubReporter)['name'];
-//#endregion
 //#region src/core/config-files.d.ts
 /** Known configuration locations and their parsers. */
 declare const CONFIG_FILES: {
@@ -376,7 +354,7 @@ interface RequireConfigKeySpec {
   /** Only unconditional defaults may reduce severity; omitted means conditional. */
   readonly defaultSafety?: 'unconditional' | 'conditional';
   /**
-   * Severity used when `documentedDefault` satisfies the requirement. Defaults
+   * Severity when an unconditional `documentedDefault` satisfies the requirement. Defaults
    * to `'info'` (advisory). Set `'off'` to silence the finding entirely.
    */
   readonly defaultSatisfiedSeverity?: Severity | 'off';
@@ -398,6 +376,28 @@ declare const overrideBindings: <Id extends string>(rule: Rule<Id>, overrides: P
 /** Build a Rule from a per-PM table of {file, keyPath, value, message}. */
 declare const requireConfigKey: <const Id extends string>(options: RequireConfigKeyOptions<Id>) => Rule<Id>;
 //#endregion
+//#region src/adapters/node-file-system.d.ts
+declare const nodeFileSystem: FileSystem;
+//#endregion
+//#region src/adapters/node-io.d.ts
+declare const nodeIO: IO;
+//#endregion
+//#region src/adapters/reporters/github.d.ts
+/** Emit GitHub Actions workflow commands (annotations on PRs). */
+declare const githubReporter: Reporter<'github'>;
+//#endregion
+//#region src/adapters/reporters/json.d.ts
+declare const jsonReporter: Reporter<'json'>;
+//#endregion
+//#region src/adapters/reporters/pretty.d.ts
+declare const prettyReporter: Reporter<'pretty'>;
+//#endregion
+//#region src/adapters/reporters/registry.d.ts
+/** Names of every built-in reporter, in stable display order. */
+declare const BUILTIN_REPORTER_NAMES: readonly BuiltinReporterName[];
+/** Literal union of every built-in reporter name. */
+type BuiltinReporterName = (typeof prettyReporter | typeof jsonReporter | typeof githubReporter)['name'];
+//#endregion
 //#region src/core/contracts/errors.d.ts
 declare class SiroError extends Error {
   readonly exitCode: number;
@@ -410,9 +410,6 @@ declare class UsageError extends SiroError {
   constructor(message: string);
 }
 //#endregion
-//#region src/version.d.ts
-declare const version: string;
-//#endregion
 //#region src/adapters/node-paths.d.ts
 declare const asAbsPath: (value: string) => AbsPath;
 //#endregion

package/dist/index.mjs

@@ -1,8 +1,2 @@
-import { A as nodeFileSystem, C as isSeverity, D as asAbsPath, E as version, F as SiroError, I as UsageError, M as DEFAULT_SCAN_LIMITS, O as asRelPath, P as ConfigError, S as isPM, _ as PROJECT_TYPES, b as PMS, c as jsonReporter, d as overrideBindings, f as requireConfigKey, g as getByPath, h as defineRule, i as BUILTIN_REPORTER_NAMES, m as loadConfig, n as lint, p as CONFIG_FILES, r as lintCommand, s as prettyReporter, t as nodeIO, u as githubReporter, x as SEVERITIES } from "./node-io-BpAHyeBG.mjs";
-//#region src/core/siro-config.ts
-/** Identity helper for type-checked config files. */
-const defineConfig = (config) => config;
-//#endregion
-export { BUILTIN_REPORTER_NAMES, CONFIG_FILES, ConfigError, DEFAULT_SCAN_LIMITS, PMS, PROJECT_TYPES, SEVERITIES, SiroError, UsageError, asAbsPath, asRelPath, defineConfig, defineRule, getByPath, githubReporter, isPM, isSeverity, jsonReporter, lint, lintCommand, loadConfig, nodeFileSystem, nodeIO, overrideBindings, prettyReporter, requireConfigKey, version };
-
+import{A as nodeFileSystem,C as isSeverity,D as asAbsPath,E as version,F as ConfigError,I as SiroError,L as UsageError,M as DEFAULT_SCAN_LIMITS,O as asRelPath,S as isPM,_ as PROJECT_TYPES,b as PMS,c as jsonReporter,d as overrideBindings,f as requireConfigKey,g as getByPath,h as defineRule,i as BUILTIN_REPORTER_NAMES,m as loadConfig,n as lint,p as CONFIG_FILES,r as lintCommand,s as prettyReporter,t as nodeIO,u as githubReporter,x as SEVERITIES}from"./node-io-DE7Nzlal.mjs";const defineConfig=config=>config;export{BUILTIN_REPORTER_NAMES,CONFIG_FILES,ConfigError,DEFAULT_SCAN_LIMITS,PMS,PROJECT_TYPES,SEVERITIES,SiroError,UsageError,asAbsPath,asRelPath,defineConfig,defineRule,getByPath,githubReporter,isPM,isSeverity,jsonReporter,lint,lintCommand,loadConfig,nodeFileSystem,nodeIO,overrideBindings,prettyReporter,requireConfigKey,version};
 //# sourceMappingURL=index.mjs.map