Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

4.6 KB
Raw Blame
/**
 * Parity guard for docs/DEPS.md.
 *
 * DEPS.md calls itself a "living reference of every third-party dependency in
 * PortOS" and is the artifact a reviewer consults to answer "why is this package
 * here, and is it still justified?". Nothing enforced that claim, and it drifted:
 * `playwright-core` landed as a server runtime dependency 27 days after the
 * document's stated last-audit date and had no row at all, so the newest
 * dependency in the tree was the one with no recorded justification.
 *
 * These assertions move that failure from "the next audit, months later" to the
 * commit that introduces it. They deliberately check *names*, not versions —
 * DEPS.md carries no version for most rows, and asserting on the few that do
 * would turn every Dependabot bump into a doc-edit chore.
 *
 * The test is colocated with the document it guards; `server/vitest.config.js`
 * globs `../docs/**` so `cd server && npm test` picks it up.
 */
import { readFileSync } from 'fs';
import { dirname, join } from 'path';
import { fileURLToPath } from 'url';
import { describe, expect, it } from 'vitest';
import { discoverWorkspaces, workspaceDir } from '../scripts/trusted-rebuilds.js';

const DOC = readFileSync(join(dirname(fileURLToPath(import.meta.url)), 'DEPS.md'), 'utf8');

/**
 * Every direct dependency name in every workspace manifest, mapped to the
 * workspaces declaring it. Workspaces are discovered rather than hardcoded
 * (`discoverWorkspaces()` is the repo's existing single source for "what is a
 * workspace"), so a fifth workspace is covered without editing a list here.
 *
 * `optionalDependencies` counts too — an optional package is still installed
 * third-party code with a supply-chain surface. `peerDependencies` does not: a
 * peer is declared for a consumer to install, and no PortOS workspace is a
 * published library.
 *
 * Manifests are read and JSON-parsed as files rather than resolved as modules:
 * CI never installs root `node_modules`, so anything reached through an
 * installed package would be green locally and red in CI.
 */
const WORKSPACES = discoverWorkspaces();
const DECLARED = new Map();
for (const label of WORKSPACES) {
  const pkg = JSON.parse(readFileSync(join(workspaceDir(label), 'package.json'), 'utf8'));
  const declared = [pkg.dependencies, pkg.devDependencies, pkg.optionalDependencies];
  for (const name of declared.flatMap((group) => Object.keys(group ?? {}))) {
    DECLARED.set(name, [...(DECLARED.get(name) ?? []), label]);
  }
}

/**
 * Rows of the Quick Reference table, as `{ name, verdict }`. Scoped to that one
 * section so a table added to the prose below can't be mistaken for the roster.
 * Cells are split rather than pattern-matched so padding and any decoration
 * around the name (a link, a footnote marker) leave the row readable;
 * section headings (`**Server deps**`) and the browser workspace's `_(none)_`
 * placeholder carry no backticked package and drop out.
 */
function quickReferenceRows() {
  const afterHeading = DOC.slice(DOC.indexOf('## Quick Reference Table') + 1);
  const end = afterHeading.indexOf('\n## ');
  const section = end === -1 ? afterHeading : afterHeading.slice(0, end);
  return section
    .split('\n')
    .map((line) => line.split('|').map((cell) => cell.trim()))
    .map(([, name, , verdict]) => ({ name: /`([^`]+)`/.exec(name ?? '')?.[1], verdict: verdict ?? '' }))
    .filter(({ name }) => name);
}

describe('docs/DEPS.md', () => {
  it('documents every dependency declared in every workspace manifest', () => {
    // A Quick Reference row, not merely a backticked mention anywhere in the
    // file: prose elsewhere (a "Last audited" note, a detailed finding) names
    // packages in passing, and accepting that would let a deleted row pass.
    const documented = new Set(quickReferenceRows().map(({ name }) => name));
    const undocumented = [...DECLARED.entries()]
      .filter(([name]) => !documented.has(name))
      .map(([name, labels]) => `${name} (${labels.join(', ')})`);
    expect(undocumented).toEqual([]);
  });

  it('names no package that no manifest declares, unless the row records a removal', () => {
    const stale = quickReferenceRows()
      .filter(({ name, verdict }) => !DECLARED.has(name) && !/REMOVED|REPLACED/.test(verdict))
      .map(({ name }) => name);
    expect(stale).toEqual([]);
  });

  it('scans a non-empty set of manifests and table rows', () => {
    // Without this, a broken discovery path or a table-format change lets both
    // assertions above pass over nothing at all.
    expect(WORKSPACES.length).toBeGreaterThanOrEqual(4);
    expect(quickReferenceRows().length).toBeGreaterThanOrEqual(40);
  });
});