@blamejs/exceptd-skills 0.13.125 → 0.14.0

package/lib/collectors/library-author.js

@@ -31,15 +31,16 @@
 
 const fs = require("node:fs");
 const path = require("node:path");
+const { codeExcludeSet, isLinkedWorktreeDir } = require("./scan-excludes");
 
 const COLLECTOR_ID = "library-author";
 
 const DEFAULT_MAX_DEPTH = 6;
-const DEFAULT_EXCLUDES = new Set([
-  "node_modules", ".git", "dist", "build", "out",
-  ".venv", "venv", "__pycache__", ".pytest_cache",
-  "target", ".idea", ".vscode",
-]);
+// Shared code-scope exclusions (dependency caches, build output, VCS +
+// agent/editor scratch including `.claude/`). Applied to the vendor-tree
+// walk so a linked worktree or dependency cache nested under `vendor/`
+// isn't mistaken for vendored provenance state.
+const DEFAULT_EXCLUDES = codeExcludeSet();
 
 function readSafe(full, max = 512 * 1024) {
   try {
@@ -112,6 +113,18 @@ function looksLikePublishWorkflow(name, content) {
   return false;
 }
 
+// `id-token: write` grants the OIDC token used for npm provenance and
+// sigstore keyless signing. It is valid at workflow-level permissions or at
+// a specific job's `permissions:` block, so any occurrence of the
+// `id-token: write` token within the publish workflow file counts as the
+// capability being present — this is what lets a job-scoped declaration
+// (not just a workflow-level one) satisfy the check. The match is
+// deliberately scoped to the file being scanned, not repo-wide: a sibling
+// workflow's OIDC does not grant it to the publish job.
+function hasIdTokenWriteAnyScope(content) {
+  return /\bid-token:\s*write\b/.test(content);
+}
+
 function scanPublishWorkflow(content, rel) {
   const hits = {
     "publish-workflow-uses-static-token": [],
@@ -122,18 +135,21 @@ function scanPublishWorkflow(content, rel) {
   };
 
   // static-token: workflow references a publish-credential secret
-  // without a corresponding `permissions: id-token: write`. The
-  // predicate (per data/playbooks/library-author.json) lists
+  // without a corresponding `id-token: write` permission (at any scope).
+  // The predicate (per data/playbooks/library-author.json) lists
   // NPM_TOKEN / PYPI_TOKEN / CARGO_TOKEN / RUBYGEMS_API_KEY /
   // GEM_HOST_API_KEY; expand to cover the common variants for each
   // ecosystem.
   const usesStaticToken = /\bsecrets\.(NPM_TOKEN|PYPI_TOKEN|PYPI_API_TOKEN|CARGO_TOKEN|CARGO_REGISTRY_TOKEN|RUBYGEMS_API_KEY|GEM_HOST_API_KEY|MAVEN_TOKEN|MAVEN_CENTRAL_TOKEN|GH_TOKEN)\b/.test(content);
-  const hasIdTokenWrite = /\bid-token:\s*write\b/.test(content);
+  // OIDC is available when THIS publish file declares `id-token: write` at
+  // any scope (workflow or job). Scoped to the file by design — a sibling
+  // workflow's OIDC does not authenticate this publish job.
+  const hasIdTokenWrite = hasIdTokenWriteAnyScope(content);
   if (usesStaticToken && !hasIdTokenWrite) {
     hits["publish-workflow-uses-static-token"].push({ file: rel, line: 0, snippet: "publish workflow uses a static long-lived token (NPM_TOKEN / PYPI / Cargo / Maven) without id-token: write for OIDC" });
   }
   if (!hasIdTokenWrite) {
-    hits["publish-workflow-no-id-token-write"].push({ file: rel, line: 0, snippet: "permissions block lacks id-token: write — npm provenance / sigstore signing unavailable" });
+    hits["publish-workflow-no-id-token-write"].push({ file: rel, line: 0, snippet: "no id-token: write at any scope (workflow or job) — npm provenance / sigstore signing unavailable" });
   }
 
   // action-refs-mutable: any `uses: <action>@<ref>` where ref is NOT
@@ -212,6 +228,13 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
     "release-workflow-non-frozen-install": [],
     "publish-workflow-runs-on-self-hosted": [],
   };
+  // OIDC capability is evaluated per publish workflow, NOT repo-wide: a
+  // sibling docs/deploy workflow declaring `id-token: write` does not give
+  // OIDC to a release job that still publishes with a long-lived
+  // `secrets.NPM_TOKEN`. Treating it repo-wide would mask exactly the
+  // static-token publisher-takeover case this indicator exists to catch.
+  // Job-scoped `id-token: write` inside the publish file still counts —
+  // hasIdTokenWriteAnyScope matches any scope within the scanned file.
   for (const w of publishWorkflows) {
     const h = scanPublishWorkflow(w.content, w.rel);
     for (const [id, list] of Object.entries(h)) workflowHits[id].push(...list);
@@ -367,10 +390,50 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
   for (const f of ["sbom.cdx.json", "sbom.json", "bom.json", "sbom.spdx.json", "sbom.cdx.xml"]) {
     if (fs.existsSync(path.join(root, f))) { sbomFile = f; break; }
   }
+  // Many publishers don't commit a static SBOM; they generate a
+  // cosign-signed CycloneDX/SPDX SBOM (and provenance attestation) at
+  // release time inside the publish workflow. Those assets never land in
+  // the committed tree, so a repo-state-only check can't see them. Detect
+  // the *capability* in the publish workflows: an SBOM-generation step
+  // (cyclonedx / syft / anchore-sbom-action / trivy / `npm sbom`), npm
+  // provenance (`--provenance` flag or `publishConfig.provenance: true`),
+  // or a sigstore/cosign signing step. If any is present, the SBOM /
+  // signed-attestation capability exists at release and the indicator
+  // should not fire on the absence of a committed artifact.
+  const releaseSbomCapable = publishWorkflows.some(w => {
+    const c = w.content;
+    return (
+      // SBOM-generation tooling invoked in the workflow.
+      /cyclonedx/i.test(c) ||
+      /\bsyft\b/i.test(c) ||
+      /anchore\/sbom-action/i.test(c) ||
+      /\btrivy\b[^\n]*\bsbom\b/i.test(c) ||
+      /\bnpm\s+sbom\b/.test(c) ||
+      /spdx-sbom-generator/i.test(c) ||
+      // npm provenance (signed build provenance attestation at publish).
+      /npm\s+publish[^\n]*--provenance\b/.test(c) ||
+      // sigstore / cosign signing of release artifacts.
+      /\bcosign\s+(?:sign|attest)\b/.test(c) ||
+      /sigstore\//i.test(c) ||
+      /gh-action-sigstore-python/i.test(c)
+    );
+  });
+  // package.json publishConfig.provenance opt-in also signals a signed
+  // provenance attestation is produced at publish time.
+  const manifestProvenanceOptIn = (() => {
+    if (!pkgManifest || !pkgManifest.content) return false;
+    try { return JSON.parse(pkgManifest.content)?.publishConfig?.provenance === true; }
+    catch { return false; }
+  })();
   let sbomAbsentOrUnsigned = "hit";
   if (sbomFile) {
     const sigPath = path.join(root, `${sbomFile}.sig`);
     sbomAbsentOrUnsigned = fs.existsSync(sigPath) ? "miss" : "hit";
+  } else if (releaseSbomCapable || manifestProvenanceOptIn) {
+    // No committed SBOM, but the release pipeline generates / signs one
+    // (or emits a signed provenance attestation). Treat the capability
+    // as present-at-release rather than reporting it absent.
+    sbomAbsentOrUnsigned = "miss";
   }
 
   // vendored-no-provenance: vendor/ directory exists without a
@@ -385,7 +448,16 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
       try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
       for (const e of entries) {
         if (e.name === "_PROVENANCE.json") { foundProvenance = true; return; }
-        if (e.isDirectory()) walkVendor(path.join(dir, e.name), depth + 1);
+        if (e.isDirectory()) {
+          if (DEFAULT_EXCLUDES.has(e.name)) continue;
+          const sub = path.join(dir, e.name);
+          // Don't descend into a linked git worktree nested under
+          // vendor/ — its `.git` is a gitdir pointer file, and a repo
+          // copy stamped by agent tooling carries unrelated provenance
+          // state that shouldn't count toward this tree's vendoring.
+          if (isLinkedWorktreeDir(sub)) continue;
+          walkVendor(sub, depth + 1);
+        }
       }
     };
     walkVendor(vendorDir, 0);

package/lib/collectors/scan-excludes.js

@@ -0,0 +1,85 @@
+"use strict";
+
+/**
+ * lib/collectors/scan-excludes.js
+ *
+ * Shared directory-walk exclusion policy for every code-scope collector.
+ *
+ * Before this existed, each collector hard-coded its own exclude Set. None
+ * skipped agent/editor worktree copies (`.claude/worktrees/`), so a tree
+ * holding N detached worktrees scanned each one as a full repo — inflating
+ * hit counts to N+1 duplicates of the same source and forcing manual dedup.
+ *
+ * Two layers:
+ *   1. NAME exclusions — directory basenames never worth descending into
+ *      (dependency caches, build output, VCS metadata, agent scratch).
+ *   2. A LINKED-WORKTREE predicate — a directory that is itself a git
+ *      worktree distinct from the scan root. A `git worktree add` target
+ *      carries a `.git` *file* (a gitdir pointer) rather than a `.git`
+ *      directory; agent tools frequently stamp full repo copies under
+ *      `.claude/worktrees/`. Skipping these keeps a scan to the one tree
+ *      the operator actually pointed at.
+ *
+ * Collectors apply both: spread DEFAULT_CODE_EXCLUDES into their exclude
+ * Set, and call isLinkedWorktreeDir(fullPath) before descending into a
+ * subdirectory.
+ */
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+// Directory basenames excluded from every code-scope walk. Superset of the
+// per-collector lists that predated this module, plus agent/editor scratch
+// (`.claude`) and additional dependency/build caches that only ever hold
+// generated or third-party content.
+const DEFAULT_CODE_EXCLUDES = Object.freeze([
+  // VCS + agent/editor scratch
+  ".git", ".hg", ".svn", ".claude", ".idea", ".vscode",
+  // dependency trees / package caches
+  "node_modules", ".pnpm-store", "bower_components",
+  ".venv", "venv", "__pycache__", ".pytest_cache", ".mypy_cache",
+  ".tox", ".gradle", ".m2",
+  // build output
+  "dist", "build", "out", "target", "coverage",
+  ".next", ".nuxt", ".svelte-kit", ".turbo", ".cache",
+]);
+
+/**
+ * Build an exclude Set for a collector. Pass any collector-specific extra
+ * basenames; they are merged with the shared defaults.
+ *
+ * @param {Iterable<string>} [extra] additional basenames to exclude
+ * @returns {Set<string>}
+ */
+function codeExcludeSet(extra = []) {
+  return new Set([...DEFAULT_CODE_EXCLUDES, ...extra]);
+}
+
+/**
+ * True when `dir` is a git worktree linked to a repository elsewhere — i.e.
+ * its `.git` entry is a file (a `gitdir: …` pointer) rather than a directory.
+ * These are detached copies created by `git worktree add` (commonly under
+ * `.claude/worktrees/<id>/`); descending into them rescans unrelated repo
+ * state. A normal repo root has a `.git` *directory* and is NOT skipped.
+ *
+ * Cheap and synchronous: one lstat. Returns false on any error so a walk
+ * never aborts on a permission/race issue.
+ *
+ * @param {string} dir absolute path to a candidate directory
+ * @returns {boolean}
+ */
+function isLinkedWorktreeDir(dir) {
+  try {
+    const gitPath = path.join(dir, ".git");
+    const st = fs.lstatSync(gitPath);
+    return st.isFile();
+  } catch {
+    return false;
+  }
+}
+
+module.exports = {
+  DEFAULT_CODE_EXCLUDES,
+  codeExcludeSet,
+  isLinkedWorktreeDir,
+};

package/lib/collectors/secrets.js

@@ -18,17 +18,16 @@
 
 const fs = require("node:fs");
 const path = require("node:path");
+const { codeExcludeSet, isLinkedWorktreeDir } = require("./scan-excludes");
 
 const COLLECTOR_ID = "secrets";
 
 // Walk depth + exclusion list mirrors the secrets playbook's
-// `look.artifacts[repo-tree].source` declaration.
+// `look.artifacts[repo-tree].source` declaration. Exclusions come from
+// the shared code-scope policy (dependency caches, build output, VCS +
+// agent/editor scratch including `.claude/`); no secrets-specific extras.
 const DEFAULT_MAX_DEPTH = 6;
-const DEFAULT_EXCLUDES = new Set([
-  "node_modules", ".git", "dist", "build", "out",
-  ".venv", "venv", "__pycache__", ".pytest_cache",
-  "target", ".idea", ".vscode",
-]);
+const DEFAULT_EXCLUDES = codeExcludeSet();
 
 // Path segments that denote test / fixture / example material. Hits
 // scoped exclusively to these paths are downgraded — a private-key
@@ -127,6 +126,11 @@ function walkTree(root, opts = {}) {
       if (seen.has(real)) continue;
       seen.add(real);
       if (entry.isDirectory()) {
+        // Skip linked git worktrees (their `.git` is a gitdir pointer
+        // file). Agent tooling stamps full repo copies under
+        // `.claude/worktrees/<id>/`; descending into them rescans the
+        // same files and inflates secret-carrier hit counts.
+        if (isLinkedWorktreeDir(full)) continue;
         walk(full, depth + 1);
       } else if (entry.isFile()) {
         out.push({ full, rel: path.relative(root, full), name: entry.name });

package/lib/flag-suggest.js

@@ -107,7 +107,7 @@ const VERB_FLAG_ALLOWLIST = Object.freeze({
   ask: [],
   attest: [
     'against', 'playbook', 'since', 'latest', 'format', 'force', 'dry-run',
-    'all-older-than',
+    'all-older-than', 'limit',
   ],
   reattest: [
     'playbook', 'since', 'latest', 'force-replay', 'attestation-root',
@@ -117,7 +117,7 @@ const VERB_FLAG_ALLOWLIST = Object.freeze({
   collect: ['cwd', 'attest-ownership'],
   refresh: [
     'apply', 'dry-run', 'from-cache', 'from-fixture', 'network', 'source',
-    'advisory', 'force-stale', 'force-stale-acked', 'air-gap', 'swarm',
+    'advisory', 'check-advisories', 'force-stale', 'force-stale-acked', 'air-gap', 'swarm',
   ],
   prefetch: ['source', 'cache-dir', 'max-age', 'force', 'no-network', 'quiet'],
 });

package/lib/refresh-external.js

@@ -79,6 +79,12 @@ function parseArgs(argv) {
     else if (a === "--help" || a === "-h") out.help = true;
     else if (a === "--advisory") { out.advisory = argv[++i]; }
     else if (a.startsWith("--advisory=")) { out.advisory = a.slice("--advisory=".length); }
+    // --check-advisories polls the primary-source advisory feeds (Qualys TRU,
+    // RHSA, USN, ZDI, kernel.org, oss-security, vendor research blogs) and
+    // reports newly-seen CVE IDs ahead of NVD enrichment. Report-only: it
+    // selects the `advisories` source and never applies — operators triage the
+    // diffs[] and seed promising IDs via `refresh --advisory <id> --apply`.
+    else if (a === "--check-advisories") { out.source = "advisories"; out.apply = false; out.checkAdvisories = true; }
     else if (a === "--catalog") { out.catalog = argv[++i]; }
     else if (a.startsWith("--catalog=")) { out.catalog = a.slice("--catalog=".length); }
     else if (a === "--from-cache") {
@@ -105,6 +111,9 @@ function parseArgs(argv) {
     else if (a === "--force-stale") out.forceStale = true;
   }
   if (process.env.EXCEPTD_FORCE_STALE === "1") out.forceStale = true;
+  // Report-only is intrinsic to the advisory poll regardless of flag order —
+  // a trailing --apply must not turn it into a catalog mutation.
+  if (out.checkAdvisories) out.apply = false;
   return out;
 }
 
@@ -129,6 +138,12 @@ Modes:
                      Combine with --apply to upsert against cached data
                      entirely offline. Cache must be pre-populated via --prefetch.
   --source kev,epss  scope to a comma-separated list (kev|epss|nvd|rfc|pins|ghsa|osv)
+  --check-advisories poll primary-source advisory feeds (Qualys TRU, RHSA, USN,
+                     ZDI, kernel.org, oss-security, vendor research blogs) and
+                     report newly-seen CVE IDs ahead of NVD enrichment.
+                     Report-only — emits diffs[]; never mutates the catalog.
+                     Triage the output and seed promising IDs with
+                     \`exceptd refresh --advisory <id> --apply\`.
   --from-fixture <p> use frozen fixture payloads (tests use this path)
   --indexes-only     rebuild data/_indexes/ only; no network. Equivalent to
                      \`exceptd refresh --indexes-only\`.