@pho9ubenaa/siro 0.1.3 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## [0.3.0]
+
+### Features
+
+- **Project policy selection**: `--project-type application|package`, `SiroConfig.projectType`, and `LintOptions.projectType` distinguish dependency-consuming applications from published packages. Omit the selection to infer policy per package-manager binding.
+- **Scoped custom rules**: `Rule.projectTypes` follows explicit or inferred policy for npm-family and Deno bindings.
+
+### Fixes
+
+- Programmatic `lintCommand` calls reject unsupported project type, package manager, and severity values instead of returning misleading results.
+- Malformed custom rules from config files or untyped programmatic callers are rejected before rule merging and evaluation.
+- Empty and whitespace-only package names no longer activate published-package policy.
+- Unscoped Deno rules no longer read `deno.json` solely for project-type inference.
+- The published `package.json#bin` preserves exit code 70 when a reporter or custom rule crashes, and subprocess tests now execute that declared bin directly.
+- Malformed or cyclic YAML configurations are rejected, while TOML configurations with a leading UTF-8 BOM are accepted.
+- Deno release-age validation accepts documented default forms and rejects invalid, partial, or zero ages.
+- Repeated reporter selectors and non-boolean Yarn strict SSL values are rejected as invalid input.
+- Findings without automatic remediation operations no longer report themselves as fixable.
+
+## [0.2.0]
+
+### Breaking Changes
+
+- **Node.js `^22.18.0 || ^23.6.0 || >=24.0.0` required** (was `>=20`): `siro.config.ts` now loads via Node's native type stripping.
+
+### Features
+
+- **OSS benchmarks module**: coverage validation against 47 leading OSS projects across all 6 package managers. Includes sparse-checkout clone script, snapshot-based CI mode, and local clone-based checking.
+- **jiti dependency removed**: runtime dependencies drop from 7 to 6. `.ts` configs load via native type stripping, and every `loadConfig` call now truly re-reads the config from disk (jiti's transform cache could replay a same-second rewrite).
+- **Unminified dist**: the published bundle ships as readable JavaScript for supply-chain transparency.
+
+### Fixes
+
+- A `.ts` config on a runtime without type stripping fails with an actionable `ConfigError` instead of a raw `ERR_UNKNOWN_FILE_EXTENSION`.
+- `pnpm gen:rule` works again — the scaffolder's marker had drifted from `rule-id.ts`.
+
 ## [0.1.3]
 
 Initial public release. 27 rules across 6 package managers (npm, pnpm, yarn, bun, deno, aube).

package/README.md

@@ -31,7 +31,7 @@ npx @pho9ubenaa/siro lint --reporter json # machine-readable output with fix ops
 - **PM-aware severities.** When a manager's documented default already satisfies a rule (e.g.
   Yarn's `enableScripts: false`, aube's `preferFrozenLockfile: true`), the finding is demoted
   to `info` so CI noise stays proportional to real risk.
-- **Machine-readable remediation.** Every finding carries `fix` operations and `manualSteps` in the
+- **Machine-readable remediation.** Every finding carries `fix` operations or `manualSteps` in the
   JSON output — hand it to an agent skill or editor plugin that edits the files and re-runs
   `siro lint` until it exits `0`. See [JSON output](docs/json-output.md).
 - **Lint with severities.** `error` fails CI by default; `--severity warn` tightens the gate.
@@ -62,6 +62,7 @@ that backs those suffixes.
 siro <lint|check> [path] [options]
 
  --pm <npm|pnpm|yarn|bun|deno|aube> Target a specific package manager (auto-detected; required if detection finds nothing)
+ --project-type <application|package> Select application or published-package policy (default auto)
  --reporter <pretty|json|github> Output format (default pretty)
  --severity <error|warn|info> Show and fail on findings at or above this level
  --json Shortcut for --reporter json
@@ -70,7 +71,7 @@ siro <lint|check> [path] [options]
 
 `check` is an alias of `lint` (same flags, same exit codes) — provided so `siro check` reads naturally in CI scripts.
 
-Exit codes: `0` clean · `1` findings at/above threshold · `2` usage error.
+Exit codes: `0` clean · `1` findings at/above threshold · `2` usage error · `70` uncaught exception (a siro bug or a throwing reporter/custom rule).
 
 ## How is this different from `npm audit` / `osv-scanner`?
 

package/dist/cli.js

@@ -1,5 +1,4 @@
 #!/usr/bin/env node
-import { run } from './cli.mjs';
+import { runMain } from './cli.mjs';
 
-const code = await run(process.argv.slice(2));
-process.exitCode = code;
+await runMain(process.argv.slice(2));

package/dist/cli.mjs

@@ -1,5 +1,430 @@
 #!/usr/bin/env node
-import{C as e,E as t,O as n,S as r,k as i,m as a,n as o,p as s,t as c,v as l,w as u,x as d}from"./node-io-BLwef7p6.mjs";import ee from"node:path";import{cac as f}from"cac";import{pathToFileURL as p}from"node:url";const m=[`lint`,`check`],h=e=>m.some(t=>t===e),g=new Set(Object.entries({json:{takesValue:!1},pm:{takesValue:!0},reporter:{takesValue:!0},severity:{takesValue:!0}}).filter(([,e])=>e.takesValue).map(([e])=>e)),_=[`pm`,`reporter`,`json`,`severity`],te={check:_,lint:_},ne=[`version`,`help`],v=[`v`,`h`,`--`],y=e=>new Set([...te[e],...ne,...v]),b=(()=>{let e=[];for(let t of m)for(let n of y(t))e.push(n);return new Set(e)})(),x=(e,t)=>e.startsWith(`--`)&&!e.includes(`=`)&&g.has(e.slice(2))&&t!==void 0&&!t.startsWith(`-`),S=e=>e===`--help`||e===`-h`,C=(e,t,n)=>e===`--`?`break`:(S(e)?n.asksHelp=!0:x(e,t)?n.index+=1:!e.startsWith(`-`)&&n.first===``&&(n.first=e),`continue`),w=e=>{let t={asksHelp:!1,first:``,index:0};for(;t.index<e.length;t.index+=1){let n=e[t.index];if(typeof n==`string`&&C(n,e[t.index+1],t)===`break`)break}return{asksHelp:t.asksHelp,first:t.first||[].pop()}},T=e=>{if(e!==void 0&&h(e))return e},E=e=>{let{asksHelp:t,first:n}=w(e);return t?{target:T(n)}:[].pop()},D=e=>{for(let t=0;t<e.length;t+=1){let n=e[t];if(typeof n==`string`){if(n===`--`)return!1;if(n===`--version`||n===`-v`)return!0;x(n,e[t+1])&&(t+=1)}}return!1},O=(e,n,r)=>{for(let i of Object.keys(e))if(!n.has(i)){let e=``;throw r&&(e=` for '${r}'`),new t(`Unknown flag${e}: --${i}`)}},k=n=>{if(n!==void 0){if(n===!0)throw new t(`--pm requires a value (expected one of: ${d.join(`, `)})`);if(typeof n!=`string`||!e(n))throw new t(`Unknown package manager: ${n} (expected one of: ${d.join(`, `)})`);return n}},A=e=>{if(e!==void 0){if(e===!0)throw new t(`--severity requires a value (expected ${r.join(`|`)})`);if(typeof e!=`string`||!u(e))throw new t(`Invalid severity: ${String(e)} (expected ${r.join(`|`)})`);return e}},j=e=>{if(e.reporter===!0)throw new t(`--reporter requires a value (expected one of: ${a.join(`, `)}, or a reporter registered via siro.config.ts)`);if(typeof e.reporter==`string`){if(e.json===!0)throw new t(`Use either --reporter or --json, not both.`);return e.reporter}return e.json===!0?`json`:`pretty`},M=e=>{let n=Number(e.replace(/^v/u,``).split(`.`)[0]);if(Number.isFinite(n)&&n<20)throw new t(`Node 20+ required (you are on ${e}). Upgrade your runtime to use siro.`)},N=()=>{let e=f(`siro`);e.option(`--pm <name>`,`Target a specific package manager`).option(`--reporter <name>`,`Reporter (${a.join(`|`)})`).option(`--json`,`Shortcut for --reporter json`).option(`--severity <level>`,`Display/fail threshold (${r.join(`|`)})`).help().version(l);for(let t of m){let n=`${t} a repository`;t===`check`&&(n=`Alias of lint`),e.command(`${t} [cwd]`,n)}return e},P=(e,t)=>e?t[0]:t[1],F=(e,t)=>e||t[0],I=(e,t)=>e?t.slice(1):t.slice(2),L=e=>{let t=N(),n=t.parse([`node`,`siro`,...e],{run:!1}),r=n.options,i=t.matchedCommandName,a=P(i,n.args);return{commandCandidate:F(i,n.args),extraPositionals:I(i,n.args),flags:r,matchedCommand:i,positionalCwd:a}},re=d.join(`|`),R=a.join(`|`),z=r.join(`|`),B={json:`  --json               Shortcut for --reporter json`,pm:`  --pm <name>          Target a specific package manager (${re})`,reporter:`  --reporter <name>    Reporter (${R}; additional reporters can be registered via siro.config.ts)`,severity:`  --severity <level>   Show + fail on findings at or above this level (${z})`},V=[`siro — security best-practices for the npm ecosystem`,``,`USAGE`,`  siro <command> [path] [flags]`,``,`COMMANDS`,`  lint     Report best-practice violations (alias: check)`,``,`GLOBAL FLAGS`,B.pm,`  --version            Print the siro version`,`  --help               Show help for siro or a command`,``,`LINT FLAGS`,B.reporter,B.json,B.severity,``,`EXAMPLES`,`  $ siro lint                         # report violations in cwd`,`  $ 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(`
-`),H=[`siro lint — report best-practice violations`,``,`USAGE`,`  siro lint [path] [flags]`,`  siro check [path] [flags]        (alias)`,``,`FLAGS`,B.pm,B.reporter,B.json,B.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 Uncaught exception (a siro bug, or a reporter / custom rule that threw)`,``,`EXAMPLES`,`  $ siro lint                         # default: pretty reporter, fail on errors`,`  $ siro lint --reporter github       # GitHub Actions annotations`,`  $ siro lint --severity warn         # tighten the gate`].join(`
-`),U=e=>e===void 0?V:e===`lint`||e===`check`?H:e,W=e=>{let n=e[`--`];if(Array.isArray(n)&&n.length>0)throw new t("siro takes no passthrough arguments after `--`.")},G=e=>e===void 0?{kind:`usage`}:e===`init`?{kind:`usage`,reason:"The 'init' command was removed: siro is lint-only. Run `siro lint --reporter json` and apply each finding's `fix` operations with your editor or an agent skill."}:typeof e!=`string`||!h(e)?{kind:`usage`,reason:`Unknown command: ${String(e)}`}:{kind:`command`,name:e},K=e=>{if(e.length>0){let n=``;throw e.length>1&&(n=`s`),new t(`Unexpected extra argument${n}: ${e.join(` `)}`)}},q=e=>{let t=process.cwd();return typeof e==`string`&&(t=e),i(ee.resolve(t))},J=e=>{let t=E(e);if(t!==void 0)return{kind:`help`,target:t.target};if(D(e))return{kind:`version`}},Y=(e,t,n)=>(O(e,y(n),n),{cwd:q(t),kind:`lint`,pm:k(e.pm),reporter:j(e),severity:A(e.severity)}),X=e=>{O(e,b),W(e)},ie=e=>{let t=J(e);if(t!==void 0)return t;let{commandCandidate:n,extraPositionals:r,flags:i,positionalCwd:a}=L(e);X(i);let o=G(n);return o.kind===`usage`?o:(K(r),Y(i,a,o.name))},ae=e=>(e.stdout(l),Promise.resolve(0)),oe=(e,t)=>(t.stdout(U(e)),Promise.resolve(0)),se=(e,t)=>(e!==void 0&&t.stderr(`${e}\n`),t.stderr(U()),Promise.resolve(2)),ce=(e,t)=>{switch(e.kind){case`version`:return ae(t);case`help`:return oe(e.target,t);case`usage`:return se(e.reason,t);case`lint`:return o(e,t);default:throw Error(`Unhandled command kind: ${String(e)}`)}},Z=(e,t)=>{if(e instanceof n)return t.stderr(e.message),e.exitCode;if(s(e)&&typeof e.errno==`number`)return t.stderr(`File system error: ${e.message}`),2;throw e},le=(e,t)=>e instanceof n?(t.stderr(e.message),Promise.resolve(e.exitCode)):s(e)&&typeof e.errno==`number`?(t.stderr(`File system error: ${e.message}`),Promise.resolve(2)):Promise.reject(e),Q=(e,t=c)=>{try{return M(process.versions.node),ce(ie(e),t).catch(e=>Z(e,t))}catch(e){return le(e,t)}},ue=e=>{process.exitCode=e},de=e=>{let t=String(e);e instanceof Error&&(t=e.stack??e.message),process.stderr.write(`${t}\n`),process.exitCode=70},[,$]=process.argv;if($&&import.meta.url===p($).href)try{ue(await Q(process.argv.slice(2)))}catch(e){de(e)}export{Q as run};
+import { A as isSeverity, D as PMS, F as asAbsPath, M as UsageError, O as SEVERITIES, P as SiroError, _ as isSupportedNodeVersion, b as JSON_REPORTER_NAME, g as SUPPORTED_NODE_RANGE, h as isProjectType, k as isPM, m as PROJECT_TYPES, n as lintCommand, p as isNodeError, t as nodeIO, v as BUILTIN_REPORTER_NAMES, w as version, y as DEFAULT_REPORTER_NAME } from "./node-io-CUcMwlGH.mjs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { cac } from "cac";
+
+//#region src/cli/commands.ts
+/**
+* Canonical list of siro CLI sub-commands. Shared between `cli.ts` (the
+* dispatcher / arg parser) and `cli/help.ts` (the help-text renderer) so a
+* new command added here propagates to both via the derived `CommandName`
+* union — there is no second place to remember to update.
+*/
+const COMMANDS = ["lint", "check"];
+const isCommandName = (value) => COMMANDS.some((cmd) => cmd === value);
+
+//#endregion
+//#region src/cli/flags.ts
+const ARGS_OFFSET$1 = 2;
+const FLAGS = {
+	json: { takesValue: false },
+	pm: { takesValue: true },
+	projectType: {
+		cliName: "project-type",
+		takesValue: true
+	},
+	reporter: { takesValue: true },
+	severity: { takesValue: true }
+};
+const flagCliName = (name, meta) => {
+	if (typeof meta.cliName !== "undefined") return meta.cliName;
+	return name;
+};
+/** Flags that consume the following argv token; pre-cac scanners skip that token. */
+const VALUE_FLAGS = new Set(Object.entries(FLAGS).filter(([, meta]) => meta.takesValue).flatMap(([name, meta]) => [name, flagCliName(name, meta)]));
+const LINT_FLAGS = [
+	"pm",
+	"projectType",
+	"reporter",
+	"json",
+	"severity"
+];
+const FLAG_SCOPES = {
+	check: LINT_FLAGS,
+	lint: LINT_FLAGS
+};
+const GLOBAL_FLAGS = ["version", "help"];
+const CAC_KEYS = [
+	"v",
+	"h",
+	"--"
+];
+const flagsFor = (command) => new Set([
+	...FLAG_SCOPES[command],
+	...GLOBAL_FLAGS,
+	...CAC_KEYS
+]);
+const collectAllFlags = () => {
+	const all = [];
+	for (const command of COMMANDS) for (const flag of flagsFor(command)) all.push(flag);
+	return new Set(all);
+};
+const KNOWN_FLAGS = collectAllFlags();
+/**
+* Whether a `--name value` flag consumes the following argv token. Only the
+* separate-token form of a value-taking flag does (`--name=value` carries its
+* own value), AND only when the next token isn't itself a `-`-prefixed flag —
+* so `--reporter --help` leaves `--help` for the help/version detectors rather
+* than eating it as the reporter value. Shared by both pre-cac scanners so the
+* skip predicate stays in one place.
+*/
+const consumesNext = (token, next) => token.startsWith("--") && !token.includes("=") && VALUE_FLAGS.has(token.slice(ARGS_OFFSET$1)) && typeof next !== "undefined" && !next.startsWith("-");
+
+//#endregion
+//#region src/cli/scanners.ts
+const STEP$1 = 1;
+const isHelpFlag = (token) => token === "--help" || token === "-h";
+const processHelpToken = (token, next, state) => {
+	if (token === "--") return "break";
+	if (isHelpFlag(token)) state.asksHelp = true;
+	else if (consumesNext(token, next)) state.index += STEP$1;
+	else if (!token.startsWith("-") && state.first === "") state.first = token;
+	return "continue";
+};
+const scanHelpTokens = (argv) => {
+	const state = {
+		asksHelp: false,
+		first: "",
+		index: 0
+	};
+	for (; state.index < argv.length; state.index += STEP$1) {
+		const token = argv[state.index];
+		if (typeof token === "string" && processHelpToken(token, argv[state.index + STEP$1], state) === "break") break;
+	}
+	return {
+		asksHelp: state.asksHelp,
+		first: state.first || void 0
+	};
+};
+const resolveTarget = (first) => {
+	if (typeof first !== "undefined" && isCommandName(first)) return first;
+};
+/**
+* Detect a --help / -h flag in argv before cac sees it (cac would otherwise
+* write to console.log itself). Returns the target command (when the first
+* positional names one) or 'root' for the top-level help.
+*/
+const detectHelpFlag = (argv) => {
+	const { asksHelp, first } = scanHelpTokens(argv);
+	if (!asksHelp) return;
+	return { target: resolveTarget(first) };
+};
+/**
+* Detect `--version` / `-v` ahead of cac for the same reason `detectHelpFlag`
+* exists. The `--` separator stops the scan so a trailing `--version` is left
+* for the (rejected) passthrough handler rather than flipping to the version
+* branch — siro forwards to no wrapped tool, so non-empty passthrough is a
+* usage error (see parseArgs).
+*/
+const detectVersionFlag = (argv) => {
+	for (let index = 0; index < argv.length; index += STEP$1) {
+		const token = argv[index];
+		if (typeof token === "string") {
+			if (token === "--") return false;
+			if (token === "--version" || token === "-v") return true;
+			if (consumesNext(token, argv[index + STEP$1])) index += STEP$1;
+		}
+	}
+	return false;
+};
+
+//#endregion
+//#region src/cli/parsers.ts
+const rejectUnknownFlags = (flags, allowed, scope) => {
+	for (const key of Object.keys(flags)) if (!allowed.has(key)) {
+		let where = "";
+		if (scope) where = ` for '${scope}'`;
+		throw new UsageError(`Unknown flag${where}: --${key}`);
+	}
+};
+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 resolveReporter = (flags) => {
+	if (flags.reporter === true) throw new UsageError(`--reporter requires a value (expected one of: ${BUILTIN_REPORTER_NAMES.join(", ")}, or a reporter registered via siro.config.ts)`);
+	if (Array.isArray(flags.reporter) || Array.isArray(flags.json) || typeof flags.reporter === "string" && flags.json === true) throw new UsageError("Invalid reporter selection: use either --reporter or --json, and specify it only once.");
+	if (typeof flags.reporter === "string") return flags.reporter;
+	if (flags.json === true) return JSON_REPORTER_NAME;
+	return DEFAULT_REPORTER_NAME;
+};
+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/cac-bridge.ts
+const STEP = 1;
+const ARGS_OFFSET = 2;
+const buildCli = () => {
+	const cli = cac("siro");
+	cli.option("--pm <name>", "Target a specific package manager").option("--project-type <type>", "Project type (application|package)").option("--reporter <name>", `Reporter (${BUILTIN_REPORTER_NAMES.join("|")})`).option("--json", "Shortcut for --reporter json").option("--severity <level>", `Display/fail threshold (${SEVERITIES.join("|")})`).help().version(version);
+	for (const name of COMMANDS) {
+		let desc = `${name} a repository`;
+		if (name === "check") desc = "Alias of lint";
+		cli.command(`${name} [cwd]`, desc);
+	}
+	return cli;
+};
+const extractPositionalCwd = (matchedCommand, args) => {
+	if (matchedCommand) {
+		const [cwd] = args;
+		return cwd;
+	}
+	return args[STEP];
+};
+const extractCommandCandidate = (matchedCommand, args) => {
+	if (matchedCommand) return matchedCommand;
+	const [candidate] = args;
+	return candidate;
+};
+const extractExtraPositionals = (matchedCommand, args) => {
+	if (matchedCommand) return args.slice(STEP);
+	return args.slice(ARGS_OFFSET);
+};
+const parseCacOutput = (argv) => {
+	const cli = buildCli();
+	const parsed = cli.parse([
+		"node",
+		"siro",
+		...argv
+	], { run: false });
+	const flags = parsed.options;
+	const matchedCommand = cli.matchedCommandName;
+	const positionalCwd = extractPositionalCwd(matchedCommand, parsed.args);
+	return {
+		commandCandidate: extractCommandCandidate(matchedCommand, parsed.args),
+		extraPositionals: extractExtraPositionals(matchedCommand, parsed.args),
+		flags,
+		positionalCwd
+	};
+};
+
+//#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",
+	pm: `  --pm <name>          Target a specific package manager (${PMS_LIST})`,
+	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.projectType,
+	"  --version            Print the siro version",
+	"  --help               Show help for siro or a command",
+	"",
+	"LINT FLAGS",
+	FLAG_LINES.reporter,
+	FLAG_LINES.json,
+	FLAG_LINES.severity,
+	"",
+	"EXAMPLES",
+	"  $ siro lint                         # report violations in cwd",
+	"  $ 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.pm,
+	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 Uncaught exception (a siro bug, or a reporter / custom rule that threw)",
+	"",
+	"EXAMPLES",
+	"  $ siro lint                         # default: pretty reporter, fail on errors",
+	"  $ 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 rejectPassthrough = (flags) => {
+	const passthrough = flags["--"];
+	if (Array.isArray(passthrough) && passthrough.length > 0) throw new UsageError("siro takes no passthrough arguments after `--`.");
+};
+const resolveCommandCandidate = (commandCandidate) => {
+	if (typeof commandCandidate === "undefined") return { kind: "usage" };
+	if (commandCandidate === "init") return {
+		kind: "usage",
+		reason: "The 'init' command was removed: siro is lint-only. Run `siro lint --reporter json` and apply each finding's `fix` operations with your editor or an agent skill."
+	};
+	if (typeof commandCandidate !== "string" || !isCommandName(commandCandidate)) return {
+		kind: "usage",
+		reason: `Unknown command: ${String(commandCandidate)}`
+	};
+	return {
+		kind: "command",
+		name: commandCandidate
+	};
+};
+const SINGLE = 1;
+const rejectExtraPositionals = (extraPositionals) => {
+	if (extraPositionals.length > 0) {
+		let plural = "";
+		if (extraPositionals.length > SINGLE) plural = "s";
+		throw new UsageError(`Unexpected extra argument${plural}: ${extraPositionals.join(" ")}`);
+	}
+};
+const resolveCwd = (positionalCwd) => {
+	let raw = process.cwd();
+	if (typeof positionalCwd === "string") raw = positionalCwd;
+	return asAbsPath(path.resolve(raw));
+};
+const checkPreScanFlags = (argv) => {
+	const preHelp = detectHelpFlag(argv);
+	if (typeof preHelp !== "undefined") return {
+		kind: "help",
+		target: preHelp.target
+	};
+	if (detectVersionFlag(argv)) return { kind: "version" };
+};
+const buildLintCommand = (flags, positionalCwd, commandCandidate) => {
+	rejectUnknownFlags(flags, flagsFor(commandCandidate), commandCandidate);
+	return {
+		cwd: resolveCwd(positionalCwd),
+		kind: "lint",
+		pm: parsePmFlag(flags.pm),
+		projectType: parseProjectTypeFlag(flags.projectType),
+		reporter: resolveReporter(flags),
+		severity: parseSeverityFlag(flags.severity)
+	};
+};
+const validateFlags = (flags) => {
+	rejectUnknownFlags(flags, KNOWN_FLAGS);
+	rejectPassthrough(flags);
+};
+const parseArgs = (argv) => {
+	const preScan = checkPreScanFlags(argv);
+	if (typeof preScan !== "undefined") return preScan;
+	const { commandCandidate, extraPositionals, flags, positionalCwd } = parseCacOutput(argv);
+	validateFlags(flags);
+	const resolved = resolveCommandCandidate(commandCandidate);
+	if (resolved.kind === "usage") return resolved;
+	rejectExtraPositionals(extraPositionals);
+	return buildLintCommand(flags, positionalCwd, resolved.name);
+};
+const handleVersion = (io) => {
+	io.stdout(version);
+	return Promise.resolve(EXIT_SUCCESS);
+};
+const handleHelp = (target, io) => {
+	io.stdout(renderHelp(target));
+	return Promise.resolve(EXIT_SUCCESS);
+};
+const handleUsage = (reason, io) => {
+	if (typeof reason !== "undefined") io.stderr(`${reason}\n`);
+	io.stderr(renderHelp());
+	return Promise.resolve(EXIT_USAGE);
+};
+const dispatch = (cmd, io) => {
+	switch (cmd.kind) {
+		case "version": return handleVersion(io);
+		case "help": return handleHelp(cmd.target, io);
+		case "usage": return handleUsage(cmd.reason, io);
+		case "lint": return lintCommand(cmd, io);
+		default: throw new Error(`Unhandled command kind: ${String(cmd)}`);
+	}
+};
+const handleAsyncError = (error, io) => {
+	if (error instanceof SiroError) {
+		io.stderr(error.message);
+		return error.exitCode;
+	}
+	if (isNodeError(error) && typeof error.errno === "number") {
+		io.stderr(`File system error: ${error.message}`);
+		return EXIT_USAGE;
+	}
+	throw error;
+};
+const handleSyncError = (error, io) => {
+	if (error instanceof SiroError) {
+		io.stderr(error.message);
+		return Promise.resolve(error.exitCode);
+	}
+	if (isNodeError(error) && typeof error.errno === "number") {
+		io.stderr(`File system error: ${error.message}`);
+		return Promise.resolve(EXIT_USAGE);
+	}
+	return Promise.reject(error);
+};
+const run = (argv, io = nodeIO) => {
+	try {
+		ensureNodeVersion(process.versions.node);
+		return dispatch(parseArgs(argv), io).catch((error) => handleAsyncError(error, io));
+	} catch (error) {
+		return handleSyncError(error, io);
+	}
+};
+const onRunFulfilled = (code) => {
+	process.exitCode = code;
+};
+const onRunRejected = (error) => {
+	let errStr = String(error);
+	if (error instanceof Error) errStr = error.stack ?? error.message;
+	process.stderr.write(`${errStr}\n`);
+	process.exitCode = EXIT_CRASH;
+};
+const runMain = (argv) => run(argv).then(onRunFulfilled, onRunRejected);
+const ARGV_SKIP = 2;
+const [, invokedPath] = process.argv;
+if (invokedPath && import.meta.url === pathToFileURL(invokedPath).href) await runMain(process.argv.slice(ARGV_SKIP));
+
+//#endregion
+export { run, runMain };
 //# sourceMappingURL=cli.mjs.map