@dogfood-lab/atlas 0.0.0 → 1.13.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mcp-tool-shop
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,56 @@
 # @dogfood-lab/atlas
 
-Placeholder so the name exists for trusted publishing. The real package ships from https://github.com/dogfood-lab/testing-os.
+Atlas reads a git repository and writes a page that says how it works: what comes in, what runs, where it lands, who reads it, what breaks what, and where to start reading. Nothing in the page is written by a person. It is derived from the workflows, the manifests, the imports, the writes and reads in the code, and the git history, and it is regenerated whenever the repository changes.
+
+The page is for anyone who has to understand a repository they did not write: a new contributor, a reviewer, an operator, or a model.
+
+## Use
+
+```bash
+npx --yes @dogfood-lab/atlas init
+npx --yes @dogfood-lab/atlas map
+npx --yes @dogfood-lab/atlas check
+```
+
+`init` proposes `atlas/boundaries.yaml`: the named parts of the repository and the globs that own them. Edit the names and globs if the proposal is wrong. The one line a person may add is `summary`.
+
+`map` writes four files under `atlas/`:
+
+| File | What it is |
+|------|------------|
+| `README.md` | The page. GitHub renders it when anyone opens the folder. |
+| `page.json` | The same sections as data, for sites and tools. |
+| `structure.json` | Every tracked file in its part, the import edges between parts, the doors, the landing places and their readers. Byte-deterministic. |
+| `statistics.json` | What changes together over the last 180 days, dated. |
+
+`check` compares the committed map with the working tree and fails when a part gains or loses a dependency, a file changes part, a new file belongs to no part, a named part matches nothing, or a file belongs to two parts. Run it in the test job so the map moves with the code. A repository with no `atlas/` directory is a notice and exit 0, so adopting Atlas reddens nothing.
+
+## What it reads
+
+- **Doors.** Every workflow under `.github/workflows/`: its triggers, the files its steps execute (following `npm run` through root and workspace scripts), what it stages and pushes, what it dispatches, publishes, releases or deploys.
+- **Parts and imports.** JavaScript, TypeScript, TSX and Python, parsed with tree-sitter; imports resolved with the same rules the runtime uses, including workspace package exports without `node_modules`.
+- **Landing places and readers.** The tracked paths that code writes to and reads from, found in call expressions and followed through joins and helpers; raw GitHub URLs and quoted paths in files it does not parse, marked as found by text.
+- **History.** Files that change together, with a floor that falls when the history is thin, and the confidence stated on the page.
+
+## What it cannot see
+
+Paths built at run time are counted, not named. Imports that do not resolve are counted. The page ends with the list of what the map could not see for that repository, so a reader knows the edges of the picture.
+
+## Errors
+
+Every failure prints one shape: the code, one sentence, what changed, what to do, and the exit code. Exit 2 means the input was unusable and nothing was checked; exit 1 means the check ran and the tree disagrees with the committed map.
+
+```text
+ATLAS_OVERLAP  A file belongs to more than one boundary.
+  what changed:   shared/util.js: alpha, shared
+  what to do:     narrow one boundary's globs, then atlas map
+exit 1
+```
+
+## Private repositories
+
+`templates/atlas-refresh.yml` is a workflow that maps a private repository inside its own CI and commits the page there. Nothing leaves the repository.
+
+## Part of testing-os
+
+Atlas is one package of [dogfood-lab/testing-os](https://github.com/dogfood-lab/testing-os). The specification of the page, and the reasoning behind it, is `docs/atlas-page.spec.md` there. Licence: MIT.

package/adapter/artifact.js

@@ -0,0 +1,157 @@
+import { isTestMaterial } from '../core/landings.js';
+import { roleFor } from './templates.js';
+
+const byPath = (a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+
+// The artifact describes the tree minus atlas/. Every list below, and every
+// count, is over that set. The directory cannot record a stable hash of
+// itself, and a count that includes it changes on the commit that lands it.
+function inAtlas(path) {
+  return path === 'atlas' || path.startsWith('atlas/');
+}
+
+function keep(items) {
+  return items.filter((item) => !inAtlas(item.path));
+}
+
+function siteCounts(files) {
+  let unresolved = 0;
+  let resolved = 0;
+  for (const file of files) {
+    if (!Array.isArray(file.imports)) continue;
+    for (const site of file.imports) {
+      const outcome = site.resolved?.outcome;
+      if (outcome === 'file' || outcome === 'boundary' || outcome === 'external') resolved += 1;
+      else unresolved += 1;
+    }
+  }
+  return { unresolved, resolved };
+}
+
+// Reads and writes whose path is built at run time name no place, so the map
+// can only count them. Test material is left out for the reason landings leave
+// it out: what it names is a temporary copy, not the repository.
+function dynamicCounts(files) {
+  let reads = 0;
+  let writes = 0;
+  for (const file of files) {
+    if (isTestMaterial(file.path)) continue;
+    reads += file.dynamicReads ?? 0;
+    writes += file.dynamicWrites ?? 0;
+  }
+  return { reads, writes };
+}
+
+// A boundary file may leave a role out; the role is then derived from the
+// files, the same way init derives the one it writes.
+export function buildArtifact(mapped, commit) {
+  const boundaries = mapped.boundaries.map((boundary) => {
+    const files = keep(boundary.files);
+    const sites = siteCounts(files);
+    const dynamic = dynamicCounts(files);
+    return {
+      dynamicReads: dynamic.reads,
+      dynamicWrites: dynamic.writes,
+      entryPoints: [...boundary.entryPoints].filter((path) => !inAtlas(path)).sort(),
+      files: files.map((file) => ({ hash: file.hash, path: file.path })).sort(byPath),
+      globs: [...boundary.globs].sort(),
+      importConfidence: sites.unresolved > sites.resolved ? 'low' : 'full',
+      name: boundary.name,
+      origin: boundary.origin,
+      role: boundary.role ?? roleFor(files.map((file) => file.path)),
+      unresolvedSites: sites.unresolved,
+    };
+  });
+  const overlaps = keep(mapped.overlaps)
+    .map((overlap) => ({
+      boundaries: [...overlap.boundaries].sort(),
+      hash: overlap.hash,
+      path: overlap.path,
+    }))
+    .sort(byPath);
+  const unassigned = keep(mapped.unassigned).map((file) => ({ hash: file.hash, path: file.path })).sort(byPath);
+  const tracked = boundaries.reduce((sum, boundary) => sum + boundary.files.length, 0) + overlaps.length + unassigned.length;
+  return {
+    boundaries,
+    doors: (mapped.doors ?? []).map(carryDoor).sort((a, b) => (a.file < b.file ? -1 : a.file > b.file ? 1 : 0)),
+    edges: mapped.edges.map((edge) => ({ from: edge.from, kind: edge.kind, to: edge.to })),
+    generatedFrom: { commit, tracked },
+    landings: carryLandings(mapped.landings ?? []),
+    overlaps,
+    submodules: [...mapped.submodules].sort(),
+    symlinks: mapped.symlinks.filter((link) => !inAtlas(link.path)).map((link) => ({ path: link.path, target: link.target })).sort(byPath),
+    unassigned,
+  };
+}
+
+// A landing on atlas/ is the map describing itself, and a reader or writer in
+// atlas/ is the map's own files; both are left out for the reason the file
+// lists leave atlas/ out.
+function carryLandings(landings) {
+  return landings
+    .filter((landing) => !inAtlas(landing.target))
+    .map((landing) => ({
+      readers: landing.readers.filter((entry) => !inAtlas(entry.by)).map(carryReader),
+      target: landing.target,
+      writers: landing.writers.filter((entry) => !inAtlas(entry.by)).map(carryWriter),
+    }))
+    .filter((landing) => landing.readers.length > 0 || landing.writers.length > 0);
+}
+
+function carryWriter(entry) {
+  const out = { by: entry.by };
+  if (entry.confidence != null) out.confidence = entry.confidence;
+  return out;
+}
+
+function carryReader(entry) {
+  const out = { by: entry.by };
+  for (const field of ['call', 'confidence', 'ref', 'repo', 'target']) {
+    if (entry[field] != null) out[field] = entry[field];
+  }
+  return out;
+}
+
+// Every list a door carries arrives sorted from the core, except commands,
+// whose order is the workflow's own. Copying field by field keeps the
+// artifact's shape the one written here rather than whatever the core adds.
+function carryDoor(door) {
+  if (door.parseError) return { file: door.file, name: door.name, parseError: true };
+  return {
+    commands: door.commands.map((command) => ({ job: command.job, step: command.step, text: command.text })),
+    file: door.file,
+    landings: door.landings.filter((target) => !inAtlas(target)),
+    mentions: door.mentions.map((mention) => ({ job: mention.job, path: mention.path })),
+    name: door.name,
+    permissions: [...door.permissions],
+    pushes: door.pushes,
+    reach: door.reach.map((entry) => ({ boundary: entry.boundary, depth: entry.depth, files: entry.files })),
+    readers: door.readers.filter((entry) => !inAtlas(entry.target) && !inAtlas(entry.by)).map(carryReader),
+    runs: door.runs.map((run) => ({ job: run.job, path: run.path })),
+    secrets: [...door.secrets],
+    sends: {
+      deploysPages: door.sends.deploysPages,
+      dispatchesTo: [...door.sends.dispatchesTo],
+      publishes: door.sends.publishes,
+      releases: door.sends.releases,
+    },
+    stages: [...door.stages],
+    triggers: door.triggers.map((trigger) => ({ ...trigger })),
+    uses: [...door.uses],
+    usesWorkflowToken: door.usesWorkflowToken,
+  };
+}
+
+export function serializeArtifact(artifact) {
+  return `${JSON.stringify(sortKeys(artifact), null, 2)}\n`;
+}
+
+function sortKeys(value) {
+  if (Array.isArray(value)) return value.map(sortKeys);
+  if (value && typeof value === 'object') {
+    const out = {};
+    for (const key of Object.keys(value).sort()) out[key] = sortKeys(value[key]);
+    return out;
+  }
+  return value;
+}

package/adapter/boundary-file.js

@@ -0,0 +1,99 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parse } from 'yaml';
+
+const TOP_LEVEL = new Set(['summary', 'window', 'thresholds', 'boundaries']);
+const BOUNDARY_FIELDS = new Set(['name', 'globs', 'role', 'rebaseline']);
+const ROLES = new Set(['code', 'test', 'docs', 'config']);
+
+// Fields an older boundary file carried for the acceptance ladder. The page is
+// written from the recorded facts now, so these are read past, not rejected:
+// a file written before the change still maps.
+const RETIRED_TOP_LEVEL = new Set(['machine_budget']);
+const RETIRED_BOUNDARY = new Set(['status', 'reason', 'why_from', 'will_break', 'will_break_from', 'start_here']);
+
+export function readBoundaryFile(repoPath) {
+  const path = join(repoPath, 'atlas', 'boundaries.yaml');
+  let text;
+  try {
+    text = readFileSync(path, 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') return { ok: false, code: 'ATLAS_NO_BOUNDARY_FILE', details: ['atlas/boundaries.yaml is absent'] };
+    return { ok: false, code: 'ATLAS_BOUNDARY_FILE_INVALID', details: [`atlas/boundaries.yaml could not be read`] };
+  }
+  let doc;
+  try {
+    doc = parse(text);
+  } catch {
+    return { ok: false, code: 'ATLAS_BOUNDARY_FILE_INVALID', details: ['atlas/boundaries.yaml is not valid YAML'] };
+  }
+  const problem = validate(doc);
+  if (problem) return { ok: false, code: 'ATLAS_BOUNDARY_FILE_INVALID', details: [problem] };
+  return {
+    ok: true,
+    summary: typeof doc.summary === 'string' ? doc.summary : null,
+    window: doc.window ?? null,
+    thresholds: doc.thresholds ?? null,
+    boundaries: doc.boundaries.map(carryBoundary),
+    ignored: ignoredKeys(doc),
+    personMarked: personMarked(doc),
+  };
+}
+
+/** The one line a command prints when an older file's retired fields were read past. */
+export function ignoredNotice(boundary) {
+  if (!boundary.ok || boundary.ignored.length === 0) return '';
+  return `atlas: ignored fields no longer read from atlas/boundaries.yaml: ${boundary.ignored.join(', ')}\n`;
+}
+
+function carryBoundary(boundary) {
+  const carried = { name: boundary.name, globs: boundary.globs };
+  if (boundary.role != null) carried.role = boundary.role;
+  if (boundary.rebaseline != null) carried.rebaseline = boundary.rebaseline;
+  return carried;
+}
+
+function ignoredKeys(doc) {
+  const keys = new Set(Object.keys(doc).filter((key) => RETIRED_TOP_LEVEL.has(key)));
+  for (const boundary of doc.boundaries) {
+    for (const key of Object.keys(boundary)) if (RETIRED_BOUNDARY.has(key)) keys.add(key);
+  }
+  return [...keys].sort();
+}
+
+// An older file records a person's hand as a status past proposed or a field
+// marked human. Init keeps its refusal to overwrite either.
+function personMarked(doc) {
+  return doc.boundaries.some((boundary) => (
+    (boundary.status != null && boundary.status !== 'proposed')
+    || boundary.why_from === 'human'
+    || boundary.will_break_from === 'human'
+  ));
+}
+
+function validate(doc) {
+  if (doc == null || typeof doc !== 'object' || Array.isArray(doc)) return 'the boundary file must be a mapping';
+  for (const key of Object.keys(doc)) {
+    if (!TOP_LEVEL.has(key) && !RETIRED_TOP_LEVEL.has(key)) return `unknown field ${key}`;
+  }
+  if (doc.summary != null && typeof doc.summary !== 'string') return 'summary must be a string';
+  if (!Array.isArray(doc.boundaries)) return 'boundaries must be an array';
+  const names = new Set();
+  for (let i = 0; i < doc.boundaries.length; i += 1) {
+    const boundary = doc.boundaries[i];
+    const where = `boundaries[${i}]`;
+    if (boundary == null || typeof boundary !== 'object' || Array.isArray(boundary)) return `${where} must be a mapping`;
+    for (const key of Object.keys(boundary)) {
+      if (!BOUNDARY_FIELDS.has(key) && !RETIRED_BOUNDARY.has(key)) return `${where}.${key} is not a boundary field`;
+    }
+    if (typeof boundary.name !== 'string' || boundary.name.trim() === '') return `${where}.name is required`;
+    if (names.has(boundary.name)) return `${where}.name duplicates ${boundary.name}`;
+    names.add(boundary.name);
+    if (!Array.isArray(boundary.globs) || boundary.globs.some((glob) => typeof glob !== 'string')) {
+      return `${where}.globs must be an array of strings`;
+    }
+    if (boundary.role != null && !ROLES.has(boundary.role)) return `${where}.role must be code, test, docs, or config`;
+    if (boundary.rebaseline != null && typeof boundary.rebaseline !== 'string') return `${where}.rebaseline must be a string`;
+  }
+  return null;
+}

package/adapter/check.js

@@ -0,0 +1,200 @@
+import { statSync } from 'node:fs';
+import { join } from 'node:path';
+
+const FLOOR = 100;
+
+/**
+ * Compare a committed artifact to the one just derived.
+ * An overlap is reported before a glob mismatch: editing the boundary file
+ * so two globs claim one file is ATLAS_OVERLAP, which a glob-equality check
+ * would hide as a generic drift.
+ */
+export function compareArtifacts(committed, current, repoPath) {
+  committed = {
+    boundaries: committed.boundaries ?? [],
+    edges: committed.edges ?? [],
+    overlaps: committed.overlaps ?? [],
+    submodules: committed.submodules ?? [],
+    unassigned: committed.unassigned ?? [],
+  };
+  const overlap = overlapFailure(current);
+  if (overlap) return overlap;
+  const identity = boundaryIdentity(committed, current);
+  if (identity) return identity;
+  const empty = emptyBoundary(current);
+  if (empty) return empty;
+  const edges = setDrift('edge', edgeKey, committed.edges, current.edges, (edge) => `${edge.from} → ${edge.to} (${edge.kind})`);
+  if (edges) return edges;
+  const entries = entryDrift(committed, current);
+  if (entries) return entries;
+  const unresolved = unresolvedDrift(committed, current);
+  if (unresolved) return unresolved;
+  const unassigned = unassignedDrift(committed, current, repoPath);
+  if (unassigned) return unassigned;
+  const moved = moveDrift(committed, current, repoPath);
+  if (moved) return moved;
+  return setDrift('submodule', (name) => name, committed.submodules, current.submodules, (name) => name, 'submodule');
+}
+
+function overlapFailure(current) {
+  if (current.overlaps.length === 0) return null;
+  return {
+    code: 'ATLAS_OVERLAP',
+    details: current.overlaps.map((overlap) => `${overlap.path} is in ${overlap.boundaries.join(' and ')}`),
+  };
+}
+
+function boundaryIdentity(committed, current) {
+  const details = [];
+  const oldNames = new Set(committed.boundaries.map((boundary) => boundary.name));
+  const newNames = new Set(current.boundaries.map((boundary) => boundary.name));
+  for (const name of [...oldNames].sort()) {
+    if (!newNames.has(name)) details.push(`boundary ${name} vanished`);
+  }
+  for (const name of [...newNames].sort()) {
+    if (!oldNames.has(name)) details.push(`boundary ${name} is new`);
+  }
+  const oldByName = new Map(committed.boundaries.map((boundary) => [boundary.name, boundary]));
+  for (const boundary of current.boundaries) {
+    const old = oldByName.get(boundary.name);
+    if (!old) continue;
+    if (old.role !== boundary.role) {
+      details.push(`${boundary.name} role is ${boundary.role}; the committed map says ${old.role}`);
+    }
+    if (listsDiffer(sorted(old.globs), sorted(boundary.globs))) details.push(`${boundary.name} globs changed`);
+    if (old.importConfidence !== boundary.importConfidence) {
+      details.push(`${boundary.name} import confidence was ${old.importConfidence} and is ${boundary.importConfidence}`);
+    }
+  }
+  if (details.length === 0) return null;
+  return { code: 'ATLAS_STRUCTURE_DRIFT', details };
+}
+
+function emptyBoundary(current) {
+  const names = current.boundaries.filter((boundary) => boundary.files.length === 0).map((boundary) => boundary.name);
+  if (names.length === 0) return null;
+  return { code: 'ATLAS_BOUNDARY_EMPTY', details: names.map((name) => `${name} matches no files`) };
+}
+
+function entryDrift(committed, current) {
+  const details = [];
+  const oldByName = new Map(committed.boundaries.map((boundary) => [boundary.name, boundary]));
+  for (const boundary of current.boundaries) {
+    const old = oldByName.get(boundary.name);
+    if (!old) continue;
+    if (listsDiffer(sorted(old.entryPoints), sorted(boundary.entryPoints))) {
+      details.push(`${boundary.name} entry points were ${showList(old.entryPoints)} and are ${showList(boundary.entryPoints)}`);
+    }
+  }
+  if (details.length === 0) return null;
+  return { code: 'ATLAS_STRUCTURE_DRIFT', details };
+}
+
+function unresolvedDrift(committed, current) {
+  const details = [];
+  const oldByName = new Map(committed.boundaries.map((boundary) => [boundary.name, boundary]));
+  for (const boundary of current.boundaries) {
+    const old = oldByName.get(boundary.name);
+    if (!old) continue;
+    if (old.unresolvedSites !== boundary.unresolvedSites) {
+      details.push(`${boundary.name} unresolved sites were ${old.unresolvedSites} and are ${boundary.unresolvedSites}`);
+    }
+  }
+  if (details.length === 0) return null;
+  return { code: 'ATLAS_STRUCTURE_DRIFT', details };
+}
+
+function unassignedDrift(committed, current, repoPath) {
+  const old = new Map(committed.unassigned.map((file) => [file.path, file.hash]));
+  const pardons = new Map();
+  for (const [path, hash] of old) {
+    if (current.unassigned.some((file) => file.path === path)) continue;
+    pardons.set(hash, (pardons.get(hash) ?? 0) + 1);
+  }
+  const offenders = [];
+  for (const file of current.unassigned) {
+    if (old.has(file.path)) continue;
+    const size = fileSize(repoPath, file.path);
+    if (size >= FLOOR && (pardons.get(file.hash) ?? 0) > 0) {
+      pardons.set(file.hash, pardons.get(file.hash) - 1);
+      continue;
+    }
+    offenders.push(file.path);
+  }
+  if (offenders.length === 0) return null;
+  return { code: 'ATLAS_UNASSIGNED_NEW', details: offenders };
+}
+
+function moveDrift(committed, current, repoPath) {
+  const old = roster(committed);
+  const now = roster(current);
+  const details = [];
+  const disappeared = [];
+  for (const [path, entry] of old) {
+    if (!now.has(path)) disappeared.push({ ...entry, path });
+  }
+  for (const [path, entry] of now) {
+    const same = old.get(path);
+    if (same) {
+      if (same.boundary !== entry.boundary) {
+        details.push(`${path} was in ${same.boundary} and is in ${entry.boundary}`);
+      }
+      continue;
+    }
+    if (fileSize(repoPath, path) < FLOOR) continue;
+    const matches = disappeared.filter((item) => item.hash === entry.hash);
+    const boundaries = new Set(matches.map((item) => item.boundary));
+    if (boundaries.size !== 1) continue;
+    const from = [...boundaries][0];
+    if (from !== entry.boundary) details.push(`${path} was in ${from} and is in ${entry.boundary}`);
+  }
+  if (details.length === 0) return null;
+  return { code: 'ATLAS_FILE_MOVED', details };
+}
+
+function roster(artifact) {
+  const map = new Map();
+  for (const boundary of artifact.boundaries) {
+    for (const file of boundary.files) map.set(file.path, { hash: file.hash, boundary: boundary.name });
+  }
+  return map;
+}
+
+function setDrift(noun, keyOf, oldList, newList, show) {
+  const oldKeys = new Set(oldList.map(keyOf));
+  const newKeys = new Set(newList.map(keyOf));
+  const details = [];
+  for (const item of newList) {
+    if (!oldKeys.has(keyOf(item))) details.push(`new ${show(item)}`);
+  }
+  for (const item of oldList) {
+    if (!newKeys.has(keyOf(item))) details.push(`vanished ${show(item)}`);
+  }
+  if (details.length === 0) return null;
+  return { code: 'ATLAS_STRUCTURE_DRIFT', details };
+}
+
+function edgeKey(edge) {
+  return `${edge.from}\0${edge.to}\0${edge.kind}`;
+}
+
+function sorted(list = []) {
+  return [...list].sort();
+}
+
+function listsDiffer(left = [], right = []) {
+  if (left.length !== right.length) return true;
+  return left.some((item, index) => item !== right[index]);
+}
+
+function showList(list) {
+  return list.length === 0 ? '(none)' : list.join(', ');
+}
+
+function fileSize(repoPath, path) {
+  try {
+    return statSync(join(repoPath, path)).size;
+  } catch {
+    return 0;
+  }
+}