@pho9ubenaa/siro 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## [0.4.0]
+
+### Breaking Changes
+
+- **One remediation per check**: replace binding `fix`/`fixKind` and finding `fix`/`fixable`/`manualSteps` with automatic operations or manual instructions in `remediation`. JSON output uses schema 2.
+- **Explicit library configuration**: `lint` evaluates without executing repository configuration. Pass extensions inside `config`; use `loadConfig` to opt into trusted code execution. `LintCommandOptions` adds reporting to `LintOptions`.
+- **Validated extension boundaries**: parsed values and `getByPath()` results are `unknown`. Rules, bindings, reporters, and configuration maps require ordinary or null-prototype objects. Path constructors reject invalid roots and parent traversal.
+- **Simpler bindings and exports**: remove `fileGlob`, separate automatic/advisory binding types, `requireConfigKey.extraFix`, `KeyAssignment`, and internal implementation exports. `RuleContext.readConfig` shares parsed inputs across checks; a violation can identify an additional input file.
+
+### Fixes
+
+- Keep version- and environment-dependent defaults at the configured severity until their conditions can be established.
+- Align npm 12 script-policy precedence, URL restrictions, release-age values, and lockfile guidance with the cited upstream policy.
+- Read Aube `strictDepBuilds` from `.npmrc`, combine it with workspace `jailBuilds`, and report and propose changes in the correct files. Correct advisory/trust defaults, paranoid overrides, and supported lockfiles.
+- Honor pnpm `ignoreScripts` and Bun's boolean auto-install disable. Keep store, provenance, and frozen-install guidance within what configuration alone establishes.
+- Correct npm/Aube exact-save precedence and Deno registry import checks, including tags, missing versions, partial versions, and subpaths.
+- Match supported Deno and Yarn release-age formats; reject malformed ages and exclusions while preserving valid exclusions in remediation.
+- Honor Deno's configured lockfile path and flag disabled or malformed lock settings. Report unsupported `deno.jsonc` explicitly.
+- Reject invalid consumed manifest fields, non-mapping JSON/YAML roots, empty JSON, invalid extension results, and inaccessible or non-directory targets with actionable errors.
+- Preserve severity overrides for prototype-named rules and compute exit decisions before custom reporters run. Require manual review when remediation would overwrite a settings container or leave a security bypass active.
+- Validate repeated, missing, unknown, and non-boolean CLI options consistently. Match Node support against the package engine range.
+- Limit the declared Node.js support range to the maintained majors exercised by CI.
+- Reject cyclic YAML aliases and excessive alias expansion without repeatedly traversing unused nested anchors.
+
+### Refactoring
+
+- Consolidate CLI parsing on Node's argument tokenizer and remove the direct `cac` dependency. Keep configuration validation and parsed-file caching at their input boundaries.
+- Replace custom script loaders, rule scaffolding, layer restrictions, and selective hook machinery with native Node scripts and direct verification commands.
+- Generate rule inputs, default severities, and version notes from live bindings. Replace the duplicated version matrix with concise policy sources and interpretation limits.
+- Remove private OSS research from the public repository and replace the single-package dependency catalog with exact versions in `package.json`.
+- Build before every test command so executable CLI and public API cases cannot silently skip. Run full verification in CI and before release staging; require the tag to match the package version and stage exactly one packed artifact.
+
+### Security and documentation
+
+- Pin GitHub Actions to full commit SHAs, disable persisted checkout credentials, and configure Dependabot updates.
+- Add security reporting guidance, a threat model, and a concrete configuration example. Clarify executable configuration, static-analysis limits, migration, and package verification.
+
 ## [0.3.0]
 
 ### Features
@@ -52,36 +89,7 @@ Initial public release. 27 rules across 6 package managers (npm, pnpm, yarn, bun
 - **`--pm` flag**: target a specific package manager.
 - **`--json` flag**: shortcut for `--reporter json`.
 
-### Rules added
-
-- `advisory-check` — aube `security.advisoryCheck`
-- `approved-git-repos` — yarn `npmScopes.*.approvedGitRepos`
-- `audit-suppression` — yarn `npmAuditExclude`
-- `block-auto-install` — pnpm `autoInstallPeers`, aube `peerDependencies.autoInstall`
-- `block-exotic-subdeps` — aube `blockExoticSubdeps`
-- `bun-security-scanner` — bun `install.security`
-- `checksum-verification` — pnpm `verifyStoreIntegrity`, aube `checksumVerification`
-- `commit-lockfile` — npm `lockfileVersion` (lockfile committed to git)
-- `dependency-overrides` — pnpm `pnpm.overrides`, aube `overrides`
-- `disable-lifecycle-scripts` — npm `ignore-scripts`, pnpm `strictDepBuilds`, yarn `enableScripts`, bun `install.ignoreScripts`, deno `deno.json#/tasks`, aube `jailBuilds`
-- `enforce-strict-ssl` — npm/yarn/pnpm/bun/aube `strict-ssl`
-- `files-field` — npm `files` in package.json
-- `frozen-lockfile` — npm `ci` enforcement, pnpm `frozen-lockfile`, yarn `freezeLockfile`, aube `preferFrozenLockfile`
-- `frozen-store` — pnpm `store.frozen`
-- `hardened-mode` — yarn `enableHardenedMode`
-- `minimum-release-age` — pnpm `fetchRetries`, aube `minimumReleaseAge`
-- `named-registries` — pnpm `registries.*.registry`
-- `paranoid-mode` — aube `paranoid`
-- `patched-dependencies` — pnpm `patchedDependencies`
-- `pin-exact-versions` — npm `save-exact`, pnpm `save-exact`, deno `deno.json#/imports`
-- `provenance` — npm/pnpm `publishConfig.provenance`
-- `publish-access` — npm/pnpm `publishConfig.access`
-- `publishable` — package.json `private`
-- `store-server` — pnpm `store.server`
-- `strict-allow-scripts` — aube `strictAllowScripts`
-- `strict-release-age` — aube `strictReleaseAge`
-- `strict-store-integrity` — pnpm `store.integrity`
-- `trust-policy` — aube `trustPolicy`
+Earlier implementations remain available in the release tags. See the [rule reference](docs/rules.md) for current policies.
 
 ### Tooling
 

package/README.md

@@ -4,36 +4,52 @@
 [![npm](https://img.shields.io/npm/v/@pho9ubenaa/siro)](https://www.npmjs.com/package/@pho9ubenaa/siro)
 [![license](https://img.shields.io/github/license/pHo9UBenaA/siro)](https://github.com/pHo9UBenaA/siro/blob/main/LICENSE)
 
-> Security best-practices linter for the npm ecosystem — npm, pnpm, yarn, bun, deno, aube.
+> Security best-practices linter for the npm ecosystem — npm, pnpm, yarn, bun, deno, [aube](https://github.com/aubepkg/aube).
 
 [Getting started](docs/getting-started.md) ·
 [Rules](docs/rules.md) ·
 [Comparison](docs/comparison.md) ·
 [Configuration](docs/configuration.md)
 
-`siro` **lints** repos for supply-chain risks, graded `error` / `warn` / `info`,
-and emits machine-readable remediation so an editor or agent skill
-can apply the fixes.
+`siro` is **inspired by** the community-maintained [npm security best practices](https://github.com/bodadotsh/npm-security-best-practices)
+and turns those recommendations into something you can run: it **lints** repos for supply-chain risks,
+graded `error` / `warn` / `info`, and emits machine-readable remediation so an editor or agent skill
+can apply the fixes. The rule selection and severities reflect siro's own opinions; it is not
+affiliated with the upstream doc.
 
 ```sh
-npx @pho9ubenaa/siro lint
-npx @pho9ubenaa/siro lint --reporter json # machine-readable output with fix ops (see docs/json-output.md)
+npx @pho9ubenaa/siro lint                 # report best-practice violations in the current repo
+npx @pho9ubenaa/siro lint --reporter json # machine-readable remediation (see docs/json-output.md)
 ```
 
+## A concrete example
+
+For maintainers and CI owners, siro makes package-manager policy gaps visible during review. For example, change an unsafe npm script setting:
+
+```diff
+# .npmrc
+-ignore-scripts=false
++ignore-scripts=true
+```
+
+Run `siro lint --pm npm --project-type application` before and after the edit. The `disable-lifecycle-scripts` error clears when this setting is enabled; other findings remain until addressed. Review required build scripts before changing their execution policy.
+
+The CLI reads `siro.config.*` as executable code. Review repository configuration before running it, particularly in CI. See the [threat model](docs/threat-model.md) and [security reporting policy](SECURITY.md).
+
 ## Features
 
-- **27 rules across 6 managers.** Covering lifecycle scripts, version pinning, lockfiles
+- **Rules across six managers.** 27 rules covering lifecycle scripts, version pinning, lockfiles
   (`commit`/`frozen`), release age, publish provenance, `files`/`publishConfig`, SSL enforcement,
   checksum verification, exotic subdependency blocking, audit suppression review, store integrity,
   Bun's security scanner API, and Yarn 4's hardened-mode — each mapped to the right setting per
   package manager (`.npmrc`, `pnpm-workspace.yaml`, `.yarnrc.yml`, `bunfig.toml`, `deno.json`,
   `aube-workspace.yaml`, `package.json`).
-- **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 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).
+- **PM-aware severities.** When a manager's documented default satisfies a rule across every
+  supported version and target environment, the finding is demoted to `info`. Installed versions
+  and CI conditions are not checked, so defaults that depend on either retain the rule's severity.
+- **Machine-readable remediation.** A finding can carry automatic key operations or manual
+  instructions. Review proposed changes and rerun the linter after editing.
+  See [docs/json-output.md](docs/json-output.md).
 - **Lint with severities.** `error` fails CI by default; `--severity warn` tightens the gate.
 - **Reporters.** `pretty` (default), `json` for CI, `github` for PR annotations; register your own.
 - **Configurable.** Drop a `siro.config.ts` to disable rules, override severities, restrict PMs,
@@ -44,50 +60,44 @@ See the [rule reference](docs/rules.md) for what each check does and why, and th
 
 ## Versioning policy
 
-`siro` is **version-agnostic**: it never inspects the actual version of npm / pnpm / yarn / bun /
-deno your project is running. Every rule is written against the **latest stable major** of each
-manager — that's the configuration surface we lint and the defaults we trust.
-
-When a rule's binding knows that a key was introduced or had its default tightened in a specific
-version, the finding's message carries a `(available since pnpm 10.16.0; default safe since pnpm 11.0.0 (1440 minutes))`
-suffix as documentation — but siro does not branch on it. If your project pins an older PM, the
-right move is usually to upgrade; the lint output stays the same either way.
-
-See [version matrix](docs/version-matrix.md) for the per-rule × per-PM version table
-that backs those suffixes.
+siro evaluates the recorded policy snapshot in [docs/policy-sources.md](docs/policy-sources.md).
+It detects package-manager names, not effective runtime versions. Version annotations describe
+verified upstream facts. A version-dependent safe-default annotation prevents an unverified
+severity downgrade; it does not prove that the current version satisfies the rule. See
+[configuration](docs/configuration.md) for defaults, applicability, and limits.
 
 ## Usage
 
 ```
 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
- --version, --help
+  --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
+  --version, --help
 ```
 
 `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 · `70` uncaught exception (a siro bug or a throwing reporter/custom rule).
+Exit codes: `0` no findings at/above threshold · `1` findings at/above threshold · `2` usage or configuration error · `70` uncaught exception (a siro bug or a throwing reporter/custom rule).
 
 ## How is this different from `npm audit` / `osv-scanner`?
 
 Different layer of the supply-chain pipeline; you want both.
 
-| Tool                                          | What it checks                                                                                                                               | Where the data comes from                                                                                                            |
-| --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
-| `npm audit` · osv-scanner · Snyk · Dependabot | **Known CVEs** in your installed dependency tree                                                                                             | GHSA / OSV.dev / vendor feeds                                                                                                        |
-| `siro`                                        | **Your install pipeline's configuration** — postinstall scripts, version ranges, lockfile policy, publish provenance, files allow-list, etc. | Static analysis of `.npmrc`, `pnpm-workspace.yaml`, `.yarnrc.yml`, `bunfig.toml`, `deno.json`, `aube-workspace.yaml`, `package.json` |
+| Tool                                                                                   | What it checks                                                                                                                               | Where the data comes from                                                                                                            |
+| -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `npm audit` · [osv-scanner](https://github.com/google/osv-scanner) · Snyk · Dependabot | **Known CVEs** in your installed dependency tree                                                                                             | GHSA / OSV.dev / vendor feeds                                                                                                        |
+| `siro`                                                                                 | **Your install pipeline's configuration** — postinstall scripts, version ranges, lockfile policy, publish provenance, files allow-list, etc. | Static analysis of `.npmrc`, `pnpm-workspace.yaml`, `.yarnrc.yml`, `bunfig.toml`, `deno.json`, `aube-workspace.yaml`, `package.json` |
 
-`npm audit` tells you "this dependency has a known vulnerability". `siro` tells you "even if a brand-new vulnerability lands tomorrow, your install settings can't trust it without review". Run both in CI.
+`npm audit` reports known vulnerabilities. `siro` reports supported configuration gaps that can increase exposure to malicious dependencies. Neither a clean result nor a cooldown window guarantees safety. Run both in CI.
 
 ## Contributing
 
 Adding a rule or a package manager is a localized change — see
-[contributing guide](docs/contributing.md).
+[docs/contributing.md](docs/contributing.md).
 
 ## License