@1aboveio/skills 0.10.0

package/skills/engineering/ensure-coverage/scripts/mock-policy-config.mjs

@@ -0,0 +1,176 @@
+// mock-policy-config — project-agnostic classifier for the `mock-internal-seam`
+// lint rule. The engine is invariant; the project's topology is *declared*, not
+// hardcoded. This is the "externals-allowlist inversion": you cannot enumerate
+// every internal seam (unbounded, per-project), but the set of things that may
+// LEGITIMATELY be faked is small, stable, and known — third-party HTTP, the
+// clock, randomness, the runtime/stdlib. So we flip the question: a mock whose
+// target resolves to *first-party* code is a candidate gap; anything on the
+// declared externals allowlist (or the stdlib) is exempt. This makes the
+// "real internals, faked externals, nothing between" policy (mock-policy.md)
+// decidable from config rather than from a baked-in path regex.
+//
+// Per-project facts come from a `coverage.config.json` (or `.coverage.config.json`)
+// at the repo root, under a `mockPolicy` key. The config only *declares topology*
+// (a monorepo's own package scope, generated dirs to exempt) — it does NOT gate
+// whether the rule runs. Over-mock is ZERO-TOLERANCE: the gate is default-on and
+// works with zero config on a conventional `@/`-aliased repo. There is no
+// `enabled:false` off switch and no inline waiver.
+
+import fs from 'node:fs'
+import path from 'node:path'
+
+/** Generic defaults — safe for any repo; tune topology via coverage.config.json. */
+export const DEFAULT_MOCK_POLICY = {
+  // Default-ON. Zero-tolerance: a project cannot turn the over-mock gate off via
+  // config; `enabled` is retained only so a config that sets it is accepted, but
+  // the rule is default-on (defaultOn:true) regardless. There is no opt-out.
+  enabled: true,
+  // Import-specifier prefixes that denote first-party app source. `@/` and `~/`
+  // are near-universal TS path aliases for "this app's src".
+  firstPartyAliasPrefixes: ['@/', '~/'],
+  // Bare package names (exact or prefix) that are actually first-party workspace
+  // packages — e.g. a monorepo's own scope `@acme/`. Declared per project.
+  firstPartyPackages: [],
+  // Regex sources (strings) for specifiers that ARE legitimately external and so
+  // exempt — third-party APIs/SDKs a project wants to name explicitly. Bare npm
+  // packages are already treated as external by default; this is for the rare
+  // case you must override (or to exempt a first-party-looking alias).
+  externals: [],
+  // Path segments that mark a relative import as a test util / fixture / mock,
+  // NOT an internal seam — mocking those is not over-mocking.
+  testUtilHints: [
+    '__mocks__', '__fixtures__', 'fixtures', 'mocks', 'helpers',
+    'test-utils', 'testing', 'support', 'stubs', 'factories',
+  ],
+}
+
+/**
+ * Compile externals regex sources once and attach them as a genuinely
+ * non-enumerable cache, so the compiled RegExp[] never leaks into a
+ * `JSON.stringify(policy)` (where it would serialize to a useless `{}`) or a
+ * `deepEqual` over the policy's declared fields.
+ */
+function compile(policy) {
+  const externalsRe = (policy.externals || []).map((src) => {
+    try { return new RegExp(src) } catch { return null }
+  }).filter(Boolean)
+  const compiled = { ...policy }
+  Object.defineProperty(compiled, '_externalsRe', { value: externalsRe, enumerable: false })
+  return compiled
+}
+
+/**
+ * Merge a project's `mockPolicy` over the defaults and compile it. Pure given
+ * the override object (no fs); use loadMockPolicy() to read from disk.
+ */
+export function resolveMockPolicy(override = {}) {
+  const merged = {
+    ...DEFAULT_MOCK_POLICY,
+    ...override,
+    // arrays replace wholesale when provided, else inherit the default
+    firstPartyAliasPrefixes: override.firstPartyAliasPrefixes ?? DEFAULT_MOCK_POLICY.firstPartyAliasPrefixes,
+    firstPartyPackages: override.firstPartyPackages ?? DEFAULT_MOCK_POLICY.firstPartyPackages,
+    externals: override.externals ?? DEFAULT_MOCK_POLICY.externals,
+    testUtilHints: override.testUtilHints ?? DEFAULT_MOCK_POLICY.testUtilHints,
+  }
+  return compile(merged)
+}
+
+/** Non-fatal warning sink (stderr). Kept here so both loaders warn identically. */
+function warn(msg) {
+  process.stderr.write(`lint-tests: ${msg}\n`)
+}
+
+/**
+ * Read+resolve `mockPolicy` from one config file. Returns the resolved policy,
+ * or `null` when the file does not exist (so the dir-search can fall through).
+ * A *malformed* file resolves to defaults AND warns — a silent fallback would let
+ * a typo'd config that meant `enabled:true` masquerade as a clean run (finding #2).
+ */
+function readConfigFile(p) {
+  if (!fs.existsSync(p)) return null
+  try {
+    const cfg = JSON.parse(fs.readFileSync(p, 'utf8'))
+    return resolveMockPolicy(cfg.mockPolicy ?? {})
+  } catch (e) {
+    warn(`ignoring malformed ${p} (${e.message}); mock-policy running on defaults`)
+    return resolveMockPolicy({})
+  }
+}
+
+/**
+ * Discover `coverage.config.json` / `.coverage.config.json` in rootDir and resolve
+ * its `mockPolicy`. Returns the compiled default policy when absent/unparsable
+ * (never throws — a missing config must not break the gate).
+ */
+export function loadMockPolicy(rootDir = process.cwd()) {
+  for (const name of ['coverage.config.json', '.coverage.config.json']) {
+    const got = readConfigFile(path.join(rootDir, name))
+    if (got) return got
+  }
+  return resolveMockPolicy({})
+}
+
+/**
+ * Resolve the policy for an explicit `--config <file>`. Reads THAT file (finding
+ * #1: the old caller passed only its dirname, so a non-standard filename was
+ * silently discarded and the gate ran on defaults). Falls back to dir-discovery
+ * when no file is given, and WARNS (non-fatal) when the named file is missing —
+ * a declared config that doesn't apply must never look like a clean pass.
+ */
+export function loadMockPolicyFromFile(configFile, rootDir = process.cwd()) {
+  if (!configFile) return loadMockPolicy(rootDir)
+  const got = readConfigFile(configFile)
+  if (got) return got
+  warn(`--config ${configFile} not found; mock-policy running on defaults`)
+  return resolveMockPolicy({})
+}
+
+/**
+ * Extract the mocked module specifier from a (comment-stripped) line of test
+ * code, or null. Covers the JS/TS module-mock front-ends: `vi.mock`/`vi.doMock`,
+ * `jest.mock`/`jest.doMock`, `vitest.mock`. Other ecosystems (e.g. Python
+ * `patch('a.b.c')`) are a future adapter — keep one matcher per ecosystem so the
+ * core classify logic stays shared. Returns the FIRST string argument only.
+ */
+export function extractMockTarget(codeLine) {
+  const m = /\b(?:vi|jest|vitest)\s*\.\s*(?:mock|doMock)\s*\(\s*(['"`])([^'"`]+)\1/.exec(codeLine || '')
+  return m ? m[2] : null
+}
+
+/**
+ * Classify a mock target as an internal seam (a gap) or an allowed external.
+ * Decidable given the policy — no fs, no module resolution at runtime; the
+ * project's declared topology supplies the facts.
+ *
+ * Precedence: declared externals > stdlib > relative(util vs source) >
+ * first-party alias > first-party package > bare package (external default).
+ */
+export function classifyMockTarget(target, policy = DEFAULT_MOCK_POLICY) {
+  const p = policy._externalsRe ? policy : compile(policy)
+  if (!target) return { internal: false, reason: 'no target' }
+
+  for (const re of p._externalsRe) {
+    if (re.test(target)) return { internal: false, reason: 'declared external' }
+  }
+  if (target.startsWith('node:')) return { internal: false, reason: 'node builtin' }
+
+  if (target.startsWith('.')) {
+    const segs = target.split('/')
+    if (segs.some((s) => p.testUtilHints.includes(s))) {
+      return { internal: false, reason: 'relative test util/fixture/mock' }
+    }
+    return { internal: true, reason: 'relative import into first-party source' }
+  }
+
+  for (const pre of p.firstPartyAliasPrefixes) {
+    if (target.startsWith(pre)) return { internal: true, reason: `first-party alias "${pre}"` }
+  }
+  for (const fp of p.firstPartyPackages) {
+    const base = fp.endsWith('/') ? fp.slice(0, -1) : fp
+    if (target === base || target.startsWith(`${base}/`)) {
+      return { internal: true, reason: `first-party package "${fp}"` }
+    }
+  }
+  return { internal: false, reason: 'external package' }
+}

package/skills/engineering/ensure-coverage/scripts/package-lock.json

@@ -0,0 +1,76 @@
+{
+  "name": "ensure-coverage-ledger",
+  "version": "file:../../../../projects/ai/skills/engineering/ensure-coverage/scripts",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "ensure-coverage-ledger",
+      "version": "0.1.0",
+      "dependencies": {
+        "js-yaml": "^4.2.0"
+      },
+      "bin": {
+        "coverage-ledger": "coverage-ledger.mjs"
+      }
+    },
+    "../../../../projects/ai/projects/ai/skills/engineering/ensure-coverage/scripts/node_modules/argparse": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmmirror.com/argparse/-/argparse-2.0.1.tgz",
+      "integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==",
+      "extraneous": true,
+      "license": "Python-2.0"
+    },
+    "../../../../projects/ai/projects/ai/skills/engineering/ensure-coverage/scripts/node_modules/js-yaml": {
+      "version": "4.3.1",
+      "resolved": "https://registry.npmmirror.com/js-yaml/-/js-yaml-4.3.1.tgz",
+      "integrity": "sha512-CY6crGq313MX8GkwvB7tzgp99vjQxY1++5y10/BKN/GUfHqWaOGQMNZkBvqSzsZKWk/ijwHlWzzkLulsGHhjWQ==",
+      "extraneous": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/puzrin"
+        },
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/nodeca"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "argparse": "^2.0.1"
+      },
+      "bin": {
+        "js-yaml": "bin/js-yaml.js"
+      }
+    },
+    "../../../../projects/ai/skills/engineering/ensure-coverage/scripts/node_modules/argparse": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmmirror.com/argparse/-/argparse-2.0.1.tgz",
+      "integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==",
+      "license": "Python-2.0"
+    },
+    "../../../../projects/ai/skills/engineering/ensure-coverage/scripts/node_modules/js-yaml": {
+      "version": "4.3.1",
+      "resolved": "https://registry.npmmirror.com/js-yaml/-/js-yaml-4.3.1.tgz",
+      "integrity": "sha512-CY6crGq313MX8GkwvB7tzgp99vjQxY1++5y10/BKN/GUfHqWaOGQMNZkBvqSzsZKWk/ijwHlWzzkLulsGHhjWQ==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/puzrin"
+        },
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/nodeca"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "argparse": "^2.0.1"
+      },
+      "bin": {
+        "js-yaml": "bin/js-yaml.js"
+      }
+    }
+  }
+}

package/skills/engineering/ensure-coverage/scripts/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "ensure-coverage-ledger",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "Reference validator + aggregator for the ensure-coverage Coverage Ledger convention.",
+  "bin": {
+    "coverage-ledger": "./coverage-ledger.mjs"
+  },
+  "scripts": {
+    "aggregate": "node coverage-ledger.mjs aggregate",
+    "validate": "node coverage-ledger.mjs validate",
+    "report": "node coverage-ledger.mjs report",
+    "test": "node --test"
+  },
+  "dependencies": {
+    "js-yaml": "^4.2.0"
+  }
+}