@mcptoolshop/housekeeping 1.3.1 → 1.4.0

package/src/collect.mjs

@@ -14,11 +14,12 @@ import { priceRun, ratesFromUsage, withFallback, runnerClass } from './cost.mjs'
 import { pagesDeployJobs, jobEnvironment } from './workflow-risks.mjs';
 import { DATA_DIR } from './paths.mjs';
 
-export const COLLECTOR_VERSION = '1.4.0';
+export const COLLECTOR_VERSION = '1.5.0';
 
 const REPO_FIELDS = `
   id name description url homepageUrl
   isPrivate isArchived isFork isTemplate isEmpty
+  parent { owner { login } }
   createdAt updatedAt pushedAt diskUsage
   stargazerCount forkCount
   watchers { totalCount }
@@ -680,7 +681,9 @@ export async function collectAtlasMaps(org, repos, { get = rest, fetchImpl = fet
   }
   const fleet = await atlasFleetVersion(fetchImpl);
   log(`atlas maps: ${targets.length} committed (${fetched} fetched, ${cached} from cache, ${errored} errors); ` +
-      `fleet engine ${fleet.version ?? `unknown (${fleet.error})`}`);
+      // npm's newest, not the fleet's version: the fleet carries what the repos
+      // pin (analyze.mjs fleetPin), which moves by a pin-bump wave.
+      `npm latest ${fleet.version ?? `unknown (${fleet.error})`}`);
   return { ok: true, fleet_version: fleet, fetched, cached, repos: out };
 }
 

package/src/config.mjs

@@ -7,7 +7,12 @@
 // treated as a non-product.
 //
 //   housekeeping.config.json
-//   { "org": "your-org", "metaRepos": [".github", "design-assets"] }
+//   { "org": "your-org", "metaRepos": [".github", "design-assets"],
+//     "homeOrgs": ["your-org", "your-other-org"] }
+//
+// `homeOrgs` names the organizations whose projects count as the org's own.
+// A fork of a project outside them is exempt from the map rule. Unset, it is
+// the swept org alone.
 //
 // No network and no database here, so every branch is unit-testable.
 import { readFileSync } from 'node:fs';
@@ -17,7 +22,7 @@ import { WORK_DIR } from './paths.mjs';
 
 export const CONFIG_PATH = process.env.HK_CONFIG ?? join(WORK_DIR, 'housekeeping.config.json');
 
-const KEYS = ['org', 'metaRepos'];
+const KEYS = ['org', 'metaRepos', 'homeOrgs'];
 const invalid = message => userError('CONFIG_INVALID', message,
   'fix housekeeping.config.json; housekeeping.config.example.json shows the shape');
 const DEFAULT_META = ['.github'];
@@ -47,7 +52,11 @@ export function parseConfig(text) {
   if (!Array.isArray(meta) || meta.some(m => typeof m !== 'string' || !m.trim())) {
     throw invalid('housekeeping config: "metaRepos" must be an array of repo names');
   }
-  return { org, metaRepos: [...meta] };
+  const home = raw.homeOrgs ?? null;
+  if (home !== null && (!Array.isArray(home) || !home.length || home.some(o => typeof o !== 'string' || !o.trim()))) {
+    throw invalid('housekeeping config: "homeOrgs" must be a non-empty array of organization names');
+  }
+  return { org, metaRepos: [...meta], homeOrgs: home ? [...home] : null };
 }
 
 /** Read the config file. A missing file is the defaults; an unreadable or malformed one throws. */
@@ -55,7 +64,7 @@ export function loadConfig(path = CONFIG_PATH) {
   let text;
   try { text = readFileSync(path, 'utf8'); }
   catch (e) {
-    if (e.code === 'ENOENT') return { org: null, metaRepos: [...DEFAULT_META] };
+    if (e.code === 'ENOENT') return { org: null, metaRepos: [...DEFAULT_META], homeOrgs: null };
     throw e;
   }
   return parseConfig(text);

package/src/load.mjs

@@ -9,7 +9,7 @@ import { parse as parseYaml } from 'yaml';
 import {
   editsWorkflowFiles, prCreateWithDefaultToken, auditSteps,
   pagesDeployJobs, jobEnvironment, jobRunsOnDefaultBranch, atlasCheckPins,
-  resolveFailedStep,
+  resolveFailedStep, scheduleGaps,
 } from './workflow-risks.mjs';
 import { safeJson } from './collect.mjs';
 import { reconcileRepos } from './cost.mjs';
@@ -112,7 +112,7 @@ export function inspectWorkflow(text, path, defaultBranch = null, atlasEnv = nul
     on_triggers: '', job_count: 0, has_matrix: 0, size_bytes: text.length, job_names: '',
     edits_workflow_files: 0, pr_create_default_token: 0,
     audit_steps_enforcing: 0, audit_steps_defanged: '',
-    pages_deploy_jobs: '', environments: [], atlas_check: '',
+    pages_deploy_jobs: '', environments: [], atlas_check: '', schedule_gaps: null,
   };
   let doc;
   try { doc = parseYaml(text, { logLevel: 'silent' }); } catch { out.state = 'parse_error'; return out; }
@@ -193,6 +193,9 @@ export function inspectWorkflow(text, path, defaultBranch = null, atlasEnv = nul
 
   out.atlas_check = atlasCheckPins(doc, jobs).join('\n');
 
+  const gaps = scheduleGaps(doc, jobEntries);
+  out.schedule_gaps = gaps ? gaps.join('\n') : null;
+
   // The deploy doors, joined in analyze.mjs to the settings they depend on.
   out.pages_deploy_jobs = pagesDeployJobs(jobEntries).join('\n');
   // The environment a job deploys to is a fact Atlas also records, so where
@@ -598,6 +601,7 @@ function loadSnapshotInner(db, snap) {
       sidebarShape(r.siteAstroCfg?.text),
       starlightRange(r.sitePkg?.text),
       hasAtlasMap(r),
+      r.isFork ? (r.parent?.owner?.login ?? null) : null,
     );
 
     // The trimmed map record, when the atlas pass read one for this repo.
@@ -695,7 +699,7 @@ function loadSnapshotInner(db, snap) {
         w.on_triggers, w.job_count, w.has_matrix, f.byteSize || w.size_bytes,
         w.edits_workflow_files, w.pr_create_default_token, w.job_names ?? '',
         w.audit_steps_enforcing ?? 0, w.audit_steps_defanged ?? '',
-        w.pages_deploy_jobs ?? '', w.atlas_check ?? '');
+        w.pages_deploy_jobs ?? '', w.atlas_check ?? '', w.schedule_gaps ?? null);
       for (const e of w.environments ?? []) {
         stmts.wfEnv.run(sid, r.name, w.path, e.job, e.environment, e.runs_on_default,
           e.source ?? 'workflow', e.parsed ?? null);

package/src/report.mjs

@@ -4,7 +4,7 @@
 import { writeFileSync, mkdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { openDb } from './load.mjs';
-import { healthScores, RUN_IS_LIVE_MAINLINE_SIGNAL, HEAD_CHECKS_RED, doorFindingRows, ATLAS_DOOR_CHECKS_SINCE, engineBehindCounts } from './analyze.mjs';
+import { healthScores, RUN_IS_LIVE_MAINLINE_SIGNAL, HEAD_CHECKS_RED, doorFindingRows, ATLAS_DOOR_CHECKS_SINCE, fleetEngineFor } from './analyze.mjs';
 import { exitCodeFor, formatError, userError } from './errors.mjs';
 import { REPORTS_DIR } from './paths.mjs';
 
@@ -287,7 +287,7 @@ export function buildReport(db, sid) {
   push(md.table(relMissing));
 
   const unpub = q(`SELECT repo, message FROM finding
-    WHERE snapshot_id=? AND code IN ('NPM_UNPUBLISHED','PRE_1_0','MONOREPO_ROOT') ORDER BY code, repo`);
+    WHERE snapshot_id=? AND code IN ('NPM_UNPUBLISHED','MONOREPO_ROOT') ORDER BY code, repo`);
   push(md.h3('Other version observations'));
   push(md.table(unpub));
 
@@ -460,7 +460,7 @@ export function buildReport(db, sid) {
       SUM(CASE WHEN r.has_atlas_map IS NULL THEN 1 ELSE 0 END) unknown
     FROM repo r WHERE r.snapshot_id=?1 AND r.is_archived=0 AND r.is_empty=0
       AND EXISTS (SELECT 1 FROM workflow w WHERE w.snapshot_id=r.snapshot_id AND w.repo=r.name)`);
-  const fleet = one('SELECT version, error FROM atlas_fleet WHERE snapshot_id=?');
+  const fleet = fleetEngineFor(db, sid);
   if (!atlas?.running || atlas.unknown === atlas.running) {
     push(md.p('_Not measured — this snapshot predates the Atlas map pass (collector 1.3.0). Run `npm run refresh`._'));
   } else {
@@ -468,12 +468,16 @@ export function buildReport(db, sid) {
       '`atlas check` in CI (`rules/atlas-map.md`). ' +
       `${atlas.mapped} of ${atlas.running} such repos have \`atlas/structure.json\` on their default branch; ` +
       `${atlas.unmapped} do not` + (atlas.unknown ? `; ${atlas.unknown} could not be read` : '') + '. ' +
-      (fleet?.version
-        ? `The fleet engine is **${fleet.version}** (latest \`@dogfood-lab/atlas\` on npm). ` +
-          (engineBehindCounts(snap.taken_at)
-            ? 'An engine behind it counts as a defect (`low`): the first pin-bump wave ended on 2026-09-30.'
-            : 'This snapshot predates the end of the first pin-bump wave, so an older engine is reported here and not counted in the health score.')
-        : `The fleet engine version could not be read${fleet?.error ? ` (${fleet.error})` : ''}, so no engine is judged behind.`)));
+      (fleet.version
+        ? (fleet.source === 'fleet-pin'
+          ? `The fleet engine is **${fleet.version}**, the \`atlas check\` pin ${fleet.repos} of ${fleet.pinned} pinning repos carry` +
+            (fleet.npmLatest && fleet.npmLatest !== fleet.version ? ` (npm's newest is ${fleet.npmLatest}; the fleet moves to it by a pin-bump wave)` : '') + '. ' +
+            'An engine behind the fleet\'s counts as a defect (`low`): the first pin-bump wave ended on 2026-09-30.'
+          : `The fleet engine is **${fleet.version}** (latest \`@dogfood-lab/atlas\` on npm). ` +
+            'This snapshot predates the end of the first pin-bump wave, so an older engine is reported here and not counted in the health score.')
+        : (fleet.source === 'fleet-pin'
+          ? 'No repository pins an `atlas check` version, so no engine is judged behind.'
+          : `The fleet engine version could not be read${fleet.npmError ? ` (${fleet.npmError})` : ''}, so no engine is judged behind.`))));
     push(md.table(q(`SELECT repo, code, message FROM finding
       WHERE snapshot_id=? AND code IN ('ATLAS_MAP_MISSING','ATLAS_CHECK_NOT_IN_CI')
       ORDER BY code, repo`)));

package/src/schema.sql

@@ -46,6 +46,10 @@ CREATE TABLE IF NOT EXISTS repo (
   -- 1 = atlas/structure.json is on the default branch, 0 = it is not, NULL =
   -- not collected (a snapshot before collector 1.3.0). See rules/atlas-map.md.
   has_atlas_map INTEGER,
+  -- The owner of the repository a fork was made from. NULL for a repo that is
+  -- not a fork, and for any repo in a snapshot before collector 1.5.0, which
+  -- did not read it: an unknown parent is never read as "someone else's".
+  fork_parent_owner TEXT,
   PRIMARY KEY (snapshot_id, name)
 );
 
@@ -147,7 +151,11 @@ CREATE TABLE IF NOT EXISTS workflow (
   pages_deploy_jobs TEXT,
   -- The pin of each `@dogfood-lab/atlas@<version> check` a run step issues,
   -- newline-joined; `unpinned` for a call without a version. Empty: none.
-  atlas_check TEXT
+  atlas_check TEXT,
+  -- For a scheduled workflow, the conditions of rules/github-actions.md
+  -- ("Scheduled workflows") it is shown to fail, newline-joined (scheduleGaps).
+  -- Empty: none shown to fail. NULL: the workflow has no schedule.
+  schedule_gaps TEXT
 );
 
 -- One row per job that names a deployment environment, read from the YAML at

package/src/workflow-risks.mjs

@@ -453,3 +453,128 @@ export function resolveFailedStep(doc, jobName, stepName, stepNumber = null) {
   const st = steps[index];
   return { job: jobId, step: typeof st.name === 'string' && st.name.trim() ? st.name : String(index), index, phase };
 }
+
+// ---------------------------------------------------------------------------
+// A scheduled workflow against rules/github-actions.md, "Scheduled workflows"
+// (the org rule was amended 2026-09-08).
+//
+// The rule permits a schedule in an org repo when ALL of these hold: it does
+// something a push cannot; it runs weekly or slower (daily needs a stated
+// reason); it is bounded (ubuntu-latest, an explicit timeout-minutes, a
+// concurrency block); it opens a PR and never pushes to a protected branch; and
+// it carries workflow_dispatch. The first is judgment and is not checked here.
+// Everything below is read from the file alone, and every unknown reads as
+// "not shown to fail": an expression we cannot resolve is not a violation.
+
+const FIELD_RANGES = [[0, 59], [0, 23], [1, 31], [1, 12], [0, 6]];
+const NAMES = {
+  3: ['jan', 'feb', 'mar', 'apr', 'may', 'jun', 'jul', 'aug', 'sep', 'oct', 'nov', 'dec'],
+  4: ['sun', 'mon', 'tue', 'wed', 'thu', 'fri', 'sat'],
+};
+
+/** Number of values a cron field admits, or null when it cannot be read. */
+function cronFieldSize(text, i) {
+  const [lo, hi] = FIELD_RANGES[i];
+  const values = new Set();
+  const num = s => {
+    const k = NAMES[i]?.indexOf(s.toLowerCase());
+    if (k != null && k >= 0) return i === 3 ? k + 1 : k;
+    return /^\d+$/.test(s) ? +s : NaN;
+  };
+  for (const part of text.split(',')) {
+    const [range, stepText] = part.split('/');
+    const step = stepText == null ? 1 : +stepText;
+    let a, b;
+    if (range === '*') [a, b] = [lo, hi];
+    else if (range.includes('-')) [a, b] = range.split('-').map(num);
+    else { a = num(range); b = stepText == null ? a : hi; }
+    if (![a, b, step].every(Number.isFinite) || step < 1) return null;
+    for (let v = a; v <= b; v += step) values.add(i === 4 ? v % 7 : v);
+  }
+  return values.size;
+}
+
+/**
+ * How many times a year a five-field cron fires, approximately. Day-of-month
+ * and day-of-week are ORed by cron when both are restricted, so both count.
+ */
+export function cronFiresPerYear(expr) {
+  const f = String(expr ?? '').trim().split(/\s+/);
+  if (f.length !== 5) return null;
+  const n = f.map(cronFieldSize);
+  if (n.some(x => x == null)) return null;
+  const domAll = f[2] === '*', dowAll = f[4] === '*';
+  const daysPerYear = domAll && dowAll ? 365
+    : dowAll ? n[2] * 12
+    : domAll ? n[4] * 52
+    : n[2] * 12 + n[4] * 52;
+  return n[0] * n[1] * daysPerYear * (n[3] / 12);
+}
+
+const PUSH = /\bgit\s+push\b/;
+const NEW_BRANCH = /\bgit\s+(?:checkout\s+-[bB]|switch\s+-[cC])\s/;
+const AUTO_COMMIT = /^(?:stefanzweifel\/git-auto-commit-action|EndBug\/add-and-commit|ad-m\/github-push-action)@/;
+
+/** Does this job push to the branch it checked out (the default, on a cron)? */
+function pushesCheckedOutBranch(job) {
+  const steps = Array.isArray(job?.steps) ? job.steps : [];
+  let branched = false;
+  for (const st of steps) {
+    if (!st || typeof st !== 'object') continue;
+    if (typeof st.uses === 'string' && AUTO_COMMIT.test(st.uses)) {
+      const w = st.with ?? {};
+      if (!w.branch && !w.create_branch && !w.new_branch) return true;
+    }
+    if (typeof st.run !== 'string') continue;
+    if (NEW_BRANCH.test(st.run)) branched = true;
+    if (PUSH.test(st.run) && !branched) return true;
+  }
+  return false;
+}
+
+/**
+ * The rule's mechanical conditions that a scheduled workflow fails, as short
+ * phrases. Empty: none shown to fail. null: the workflow has no schedule.
+ */
+export function scheduleGaps(doc, jobEntries) {
+  const on = doc?.on ?? doc?.[true];
+  const schedule = on && typeof on === 'object' && !Array.isArray(on) ? on.schedule : null;
+  if (!Array.isArray(schedule)) return null;
+  const gaps = [];
+
+  const fires = schedule.map(s => cronFiresPerYear(s?.cron)).filter(x => x != null);
+  const perYear = fires.reduce((a, b) => a + b, 0);
+  if (perYear > 53) {
+    const days = 365 / perYear;
+    const every = Math.abs(days - 1) < 0.05 ? 'daily'
+      : days >= 1 ? `every ${+days.toFixed(1)} days` : `${+(perYear / 365).toFixed(1)} times a day`;
+    gaps.push(`runs more often than weekly (${every}, which needs a stated reason)`);
+  }
+
+  const offLinux = new Set();
+  const noTimeout = [], noConcurrency = [], pushers = [];
+  for (const [id, job] of jobEntries) {
+    if (!job || typeof job !== 'object') continue;
+    const reusable = typeof job.uses === 'string';
+    const ro = job['runs-on'];
+    const labels = (Array.isArray(ro) ? ro : [ro]).filter(r => typeof r === 'string');
+    const os = job.strategy?.matrix?.os;
+    for (const r of labels) {
+      if (r.includes('${{')) {
+        if (/matrix\.os/.test(r) && Array.isArray(os)) {
+          os.filter(o => typeof o === 'string' && !/^ubuntu-/.test(o)).forEach(o => offLinux.add(o));
+        }
+      } else if (!/^ubuntu-/.test(r)) offLinux.add(r);
+    }
+    // A job that calls a reusable workflow cannot carry timeout-minutes.
+    if (!reusable && job['timeout-minutes'] == null) noTimeout.push(id);
+    if (!job.concurrency) noConcurrency.push(id);
+    if (pushesCheckedOutBranch(job)) pushers.push(id);
+  }
+  if (offLinux.size) gaps.push(`runs off Linux (${[...offLinux].join(', ')})`);
+  if (noTimeout.length) gaps.push(`no timeout-minutes on ${noTimeout.join(', ')}`);
+  if (!doc.concurrency && noConcurrency.length) gaps.push('no concurrency block');
+  if (pushers.length) gaps.push(`pushes to the branch it checked out instead of opening a PR (${pushers.join(', ')})`);
+  if (!('workflow_dispatch' in on)) gaps.push('no workflow_dispatch');
+  return gaps;
+}