@crvouga/atlas 0.0.0-stage → 0.2.0

package/dist/core/src/lint.js

@@ -0,0 +1,138 @@
+import { ChartGraph } from './graph.js';
+import { composeCharts } from './spec/compose.js';
+import { invokesOf, walkStates } from './spec/types.js';
+const STATE_KEYS = new Set(['id', 'initial', 'type', 'meta', 'states', 'on', 'invoke', 'description']);
+const INVOKE_KEYS = new Set(['src', 'id', 'onDone']);
+const REQUIRED_META = ['description'];
+const FORBIDDEN = ['entry', 'exit', 'actions', 'assign', 'after', 'always', 'context', 'guard', 'cond', 'delay', 'output', 'onError'];
+function checkShape(node, name, requiredMeta, out) {
+    for (const key of Object.keys(node)) {
+        if (FORBIDDEN.includes(key))
+            out.push({ rule: 'pure', message: `${name}: "${key}" is not allowed` });
+        else if (!STATE_KEYS.has(key))
+            out.push({ rule: 'pure', message: `${name}: unknown key "${key}"` });
+    }
+    if (name.includes('.'))
+        out.push({ rule: 'naming', message: `${name}: state names cannot contain dots` });
+    for (const key of requiredMeta) {
+        if (!(key in (node.meta ?? {})))
+            out.push({ rule: 'meta', message: `${name}: meta.${key} is missing` });
+    }
+    for (const [event, t] of Object.entries(node.on ?? {})) {
+        if (typeof t === 'string')
+            continue;
+        if (typeof t !== 'object' || t === null) {
+            out.push({ rule: 'pure', message: `${name} --${event}--> must be a target` });
+            continue;
+        }
+        for (const key of Object.keys(t)) {
+            if (key !== 'target')
+                out.push({ rule: 'pure', message: `${name} --${event}-->: "${key}" is not allowed (no guards, no actions)` });
+        }
+    }
+    for (const invoke of invokesOf(node)) {
+        for (const key of Object.keys(invoke)) {
+            if (!INVOKE_KEYS.has(key))
+                out.push({ rule: 'pure', message: `${name}: invoke "${key}" is not allowed; invoke only names another chart` });
+        }
+        if (typeof invoke.src !== 'string')
+            out.push({ rule: 'pure', message: `${name}: invoke src must name another chart` });
+    }
+}
+/** A copy with forbidden keys removed, so reachability can be analysed after a purity finding. */
+function sanitized(bundle) {
+    const clean = (node) => {
+        const out = {};
+        for (const [key, value] of Object.entries(node))
+            if (STATE_KEYS.has(key))
+                out[key] = value;
+        if (node.on) {
+            out['on'] = Object.fromEntries(Object.entries(node.on).map(([event, t]) => [event, typeof t === 'string' ? t : { target: t.target }]));
+        }
+        if (node.states)
+            out['states'] = Object.fromEntries(Object.entries(node.states).map(([k, v]) => [k, clean(v)]));
+        return out;
+    };
+    return { ...bundle, charts: bundle.charts.map((c) => ({ ...c, machine: clean(c.machine) })) };
+}
+/**
+ * Checks a spec bundle is executable: pure (no guards, actions, context or delays), every state
+ * reachable, no dead ends without `meta.deadEnd`, every journey replays to its `endsIn` states, and
+ * (when implementations are given) every event and state in scope has one.
+ */
+export function lintBundle(bundle, options = {}) {
+    const findings = [];
+    const requiredMeta = options.requiredMeta ?? REQUIRED_META;
+    for (const chart of bundle.charts) {
+        checkShape(chart.machine, chart.machine.id, [], findings);
+        for (const { name, node } of walkStates(chart.machine))
+            checkShape(node, name, requiredMeta, findings);
+    }
+    let composition;
+    let graph;
+    try {
+        composition = composeCharts(sanitized(bundle));
+        graph = new ChartGraph(composition.machine, composition.handOffs);
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        const listed = findings.map((f) => `\n  [${f.rule}] ${f.message}`).join('');
+        throw new Error(`The charts cannot be composed: ${reason}${listed}`);
+    }
+    const reached = new Set();
+    for (const regions of graph.regionSets()) {
+        for (const { config } of graph.explore(graph.initial(), (event) => graph.actsIn(event, regions)).seen.values()) {
+            for (const name of config.active)
+                reached.add(name);
+        }
+    }
+    for (const name of graph.stateNames()) {
+        if (!reached.has(name))
+            findings.push({ rule: 'reachable', message: `${name} is unreachable from the initial state` });
+    }
+    for (const { name, node, trail } of walkStates(composition.machine)) {
+        if (node.states || node.type === 'final')
+            continue;
+        const hasExit = [name, ...trail].some((n) => Object.keys(graph.node(n)?.on ?? {}).length > 0);
+        if (!hasExit && !node.meta?.deadEnd) {
+            findings.push({ rule: 'dead-end', message: `${name} has no way out and no meta.deadEnd reason` });
+        }
+    }
+    const journeys = bundle.journeys.map((journey) => {
+        const replay = graph.replay(graph.initial(), journey.events);
+        if (!replay.ok) {
+            findings.push({ rule: 'journey', message: `${journey.name}: "${replay.failedAt}" does not apply in ${JSON.stringify(replay.config.value)}` });
+        }
+        else {
+            const missing = journey.endsIn.filter((s) => !replay.config.active.includes(s));
+            if (missing.length) {
+                findings.push({ rule: 'journey', message: `${journey.name}: should end in ${missing.join(', ')}, ends in ${replay.config.active.join(' > ')}` });
+            }
+        }
+        return { journey, replay };
+    });
+    const unimplemented = { events: [], states: [] };
+    if (options.implementations) {
+        const { scope, implementations } = options;
+        const events = new Set(walkStates(composition.machine).flatMap(({ node }) => Object.keys(node.on ?? {})));
+        for (const event of events) {
+            if (scope && !scope.events.has(event))
+                continue;
+            if (!implementations.events.has(event))
+                unimplemented.events.push(event);
+        }
+        for (const name of graph.stateNames()) {
+            if (scope && !scope.states.has(name))
+                continue;
+            if (!graph.isLeaf(name))
+                continue;
+            if (!implementations.states.has(name))
+                unimplemented.states.push(name);
+        }
+        for (const e of unimplemented.events)
+            findings.push({ rule: 'implemented', message: `event "${e}" has no implementation` });
+        for (const s of unimplemented.states)
+            findings.push({ rule: 'implemented', message: `state "${s}" has no recognizer` });
+    }
+    return { findings, composition, graph, journeys, unimplemented };
+}

package/dist/core/src/plan.d.ts

@@ -0,0 +1,109 @@
+import type { Config, StateValue } from './graph.js';
+import type { ChartGraph } from './graph.js';
+import type { Composition } from './spec/compose.js';
+import type { SpecBundle } from './spec/types.js';
+export type ChartScope = {
+    chart: string;
+    /** Set when the run covers one state of the chart and what is inside it. */
+    state?: string;
+    /** The configuration each generated path starts from. */
+    start: StateValue;
+    startLabel: string;
+    states: Set<string>;
+    transitions: Set<string>;
+    events: Set<string>;
+    /** Transitions that enter the chart from outside it. */
+    entries: Set<string>;
+};
+export type PlannedStep = {
+    event: string;
+    transitions: string[];
+    handOff: boolean;
+    from: string[];
+    to: string[];
+};
+export type PlannedPath = {
+    id: string;
+    /** The same start and events give the same key on any machine and in any run. */
+    key: string;
+    name: string;
+    kind: 'journey' | 'generated';
+    description: string;
+    steps: PlannedStep[];
+    /** Active states the path starts in, for the implementation's setup. */
+    start: string[];
+    /** The seed that puts the system in the start configuration; `setup` does it when absent. */
+    seed?: string;
+    /** The journeys this stretch belongs to: a stretch several journeys share is run once. */
+    journeys?: string[];
+    blockedBy: string[];
+    /** A blocked path whose runnable part other paths already cover: reported, not run. */
+    skipRun?: boolean;
+};
+export type ScopeOptions = {
+    /** The chart to run; the root chart (the whole product) when omitted. */
+    chart?: string;
+    /** Where generated paths start; the root's initial configuration when omitted. */
+    start?: StateValue;
+    startLabel?: string;
+    /** Only these events enter the chart from outside it; every entering transition when omitted. */
+    entryEvents?: string[];
+    /**
+     * Cover only this state and what is inside it, with the transitions into and out of it: one
+     * area of a chart that holds the whole product.
+     */
+    state?: string;
+};
+/**
+ * The part of the composed product a run covers: every state of `chart`, the transitions that
+ * enter it from outside, and the hand-offs back to its parent.
+ */
+export declare function chartScope(bundle: SpecBundle, composition: Composition, graph: ChartGraph, options?: ScopeOptions): ChartScope;
+/** A named seed: a configuration the implementation can put the system in directly. */
+export type SeedPoint = {
+    name: string;
+    at: StateValue;
+    blocked?: string;
+    for?: string[];
+    shows?: string;
+};
+/** A journey as the paths it is cut into, one per seeded stretch, in order. */
+export type PlannedJourney = {
+    name: string;
+    description: string;
+    paths: string[];
+};
+export type PlanOptions = {
+    /** Events that cannot run yet; paths stop before them. */
+    isBlocked?: (event: string) => boolean;
+    /** Whether the implementation can set a path up in this starting configuration. */
+    canStart?: (active: string[]) => true | string;
+    /**
+     * Configurations the implementation can seed directly. Paths start from the nearest one, and
+     * journeys are cut wherever they pass through one, so every stretch runs on its own.
+     */
+    seeds?: SeedPoint[];
+    /** Whether `setup` can start a path at the scope's start; true when omitted. */
+    hasSetup?: boolean;
+};
+/** The steps a path can actually run: everything before its first blocked event. */
+export declare function runnableSteps(steps: PlannedStep[], isBlocked: (event: string) => boolean): PlannedStep[];
+export declare function pathKey(seed: string | undefined, start: Config, events: string[]): string;
+/**
+ * Paths for one chart. Every path starts at a start point: the scope's start (through `setup`)
+ * or a seed. Each curated journey is replayed from the chart's initial state and cut into
+ * stretches wherever it passes through a seeded configuration; identical stretches of different
+ * journeys become one path. Then the shortest extra path from the nearest start point is added
+ * for every transition still uncovered, and extra paths that are a prefix of another path are
+ * dropped. Everything is ordered by the chart and the journeys, so the plan is deterministic.
+ */
+export declare function planChart(bundle: SpecBundle, graph: ChartGraph, scope: ChartScope, options?: PlanOptions): {
+    paths: PlannedPath[];
+    unreachable: string[];
+    journeys: PlannedJourney[];
+    seeds: {
+        blocked?: string | undefined;
+        name: string;
+        active: string[];
+    }[];
+};

package/dist/core/src/plan.js

@@ -0,0 +1,324 @@
+import { createHash } from 'node:crypto';
+import { configKey } from './graph.js';
+import { splitTransitionId, transitionId, walkStates } from './spec/types.js';
+/**
+ * The part of the composed product a run covers: every state of `chart`, the transitions that
+ * enter it from outside, and the hand-offs back to its parent.
+ */
+export function chartScope(bundle, composition, graph, options = {}) {
+    const chart = options.chart ?? bundle.root;
+    const states = new Set();
+    const area = options.state;
+    if (area) {
+        if (!graph.stateNames().includes(area))
+            throw new Error(`There is no state "${area}" to scope the run to`);
+        const within = (name) => {
+            for (let n = name; n; n = graph.parent(n))
+                if (n === area)
+                    return true;
+            return false;
+        };
+        for (const name of graph.stateNames())
+            if (within(name))
+                states.add(name);
+    }
+    else {
+        for (const [state, owner] of composition.chartOf)
+            if (owner === chart)
+                states.add(state);
+        if (chart === bundle.root)
+            for (const name of graph.stateNames())
+                states.add(name);
+        const host = composition.hosts.get(chart);
+        if (host)
+            states.add(host);
+    }
+    const transitions = new Set();
+    const entries = new Set();
+    for (const { name, node } of walkStates(composition.machine)) {
+        for (const event of Object.keys(node.on ?? {})) {
+            const id = transitionId(name, event);
+            const target = graph.target(name, event);
+            if (states.has(name))
+                transitions.add(id);
+            else if (target && states.has(target) && (!options.entryEvents || options.entryEvents.includes(event))) {
+                transitions.add(id);
+                entries.add(id);
+            }
+        }
+    }
+    for (const h of composition.handOffs) {
+        if (!states.has(h.finalState))
+            continue;
+        const target = graph.target(h.finalState, h.event);
+        if (target)
+            states.add(target);
+    }
+    if (area) {
+        for (const id of transitions) {
+            const { source, event } = splitTransitionId(id);
+            const target = graph.target(source, event);
+            if (target && !entries.has(id))
+                states.add(target);
+        }
+    }
+    for (const id of entries)
+        states.add(splitTransitionId(id).source);
+    const start = options.start ?? graph.initial().value;
+    return {
+        chart,
+        ...(area ? { state: area } : {}),
+        start,
+        startLabel: options.startLabel ?? 'The start of the chart',
+        states,
+        transitions,
+        events: new Set([...transitions].map((id) => splitTransitionId(id).event)),
+        entries
+    };
+}
+function inScope(scope, fired) {
+    return fired.length > 0 && fired.every((t) => scope.transitions.has(t));
+}
+function toSteps(replaySteps) {
+    return replaySteps.map((s) => ({ event: s.event, transitions: s.transitions, handOff: s.handOff, from: s.from.active, to: s.to.active }));
+}
+/**
+ * `explore` takes hand-off events as ordinary moves, but `replay` inserts them by itself as soon as
+ * a hand-off state is active. Drop the ones `replay` will insert, so it does not see them twice.
+ */
+function withoutAutomaticHandOffs(graph, start, events) {
+    const out = [];
+    let config = start;
+    for (const event of events) {
+        const automatic = graph.pendingHandOffs(config).some((h) => h.event === event);
+        const next = graph.step(config, event);
+        if (!automatic)
+            out.push(event);
+        if (!next)
+            break;
+        config = next.config;
+    }
+    return out;
+}
+/** The steps a path can actually run: everything before its first blocked event. */
+export function runnableSteps(steps, isBlocked) {
+    const stop = steps.findIndex((s) => isBlocked(s.event));
+    return stop < 0 ? steps : steps.slice(0, stop);
+}
+export function pathKey(seed, start, events) {
+    return createHash('sha256')
+        .update(JSON.stringify([seed ?? null, configKey(start.value), events]))
+        .digest('hex')
+        .slice(0, 16);
+}
+const leaves = (graph, active) => active.filter((n) => graph.isLeaf(n));
+/**
+ * Paths for one chart. Every path starts at a start point: the scope's start (through `setup`)
+ * or a seed. Each curated journey is replayed from the chart's initial state and cut into
+ * stretches wherever it passes through a seeded configuration; identical stretches of different
+ * journeys become one path. Then the shortest extra path from the nearest start point is added
+ * for every transition still uncovered, and extra paths that are a prefix of another path are
+ * dropped. Everything is ordered by the chart and the journeys, so the plan is deterministic.
+ */
+export function planChart(bundle, graph, scope, options = {}) {
+    const isBlocked = options.isBlocked ?? (() => false);
+    const canStart = options.canStart ?? (() => true);
+    const hasSetup = options.hasSetup !== false;
+    const blockedEvents = (steps) => [...new Set(steps.map((s) => s.event).filter(isBlocked))];
+    const isRoot = scope.chart === bundle.root && !scope.state;
+    const seeds = (options.seeds ?? []).map((seed) => ({ ...seed, config: graph.resolve(seed.at) }));
+    const startPoints = [
+        ...seeds.filter((s) => !s.blocked).map((s) => ({ seed: s.name, config: s.config, ...(s.for ? { for: s.for } : {}), ...(s.shows ? { shows: s.shows } : {}) })),
+        ...(hasSetup ? [{ config: graph.resolve(scope.start) }] : [])
+    ];
+    const variantEvents = new Set(startPoints.flatMap((p) => p.for ?? []));
+    /** A variant seed starts only paths that take one of its events; those events start only from it. */
+    const suits = (point, events) => {
+        const needed = events.filter((e) => variantEvents.has(e));
+        return point.for ? needed.length > 0 && needed.every((e) => point.for.includes(e)) : needed.length === 0;
+    };
+    /** The region of a parallel state a state sits in: the child of its nearest parallel ancestor. */
+    const regionOf = (state) => {
+        for (let n = state, p = graph.parent(state); p; n = p, p = graph.parent(p))
+            if (graph.node(p)?.type === 'parallel')
+                return n;
+        return null;
+    };
+    /** Whether the first event acts in the region whose screen the seed leaves open. */
+    const sameRegion = (config, event, shows) => {
+        const sources = graph.firedBy(config, event).map((t) => splitTransitionId(t).source);
+        return sources.some((source) => regionOf(source) === regionOf(shows));
+    };
+    const startsAt = (config) => startPoints.filter((p) => configKey(p.config.value) === configKey(config.value));
+    const startVerdict = (config, events) => {
+        const candidates = startsAt(config);
+        const point = candidates.find((p) => suits(p, events));
+        if (point?.seed)
+            return { point, supported: true };
+        const needed = events.filter((e) => variantEvents.has(e));
+        if (!point && needed.length && candidates.length)
+            return { point, supported: `no seed at ${leaves(graph, config.active).join(' + ')} is for ${needed.map((e) => `"${e}"`).join(', ')}` };
+        if (!hasSetup)
+            return { point, supported: `no seed puts the system in ${leaves(graph, config.active).join(' + ')}` };
+        return { point, supported: canStart(config.active) };
+    };
+    const journeyPaths = [];
+    const byKey = new Map();
+    const journeys = [];
+    for (const journey of bundle.journeys) {
+        const replay = graph.replay(graph.initial(), journey.events);
+        const ids = [];
+        let current = null;
+        const flush = () => {
+            if (!current?.length) {
+                current = null;
+                return;
+            }
+            const startConfig = current[0].from;
+            const steps = toSteps(current);
+            current = null;
+            const { point, supported } = startVerdict(startConfig, steps.map((s) => s.event));
+            const key = pathKey(point?.seed, startConfig, steps.map((s) => s.event));
+            const existing = byKey.get(key);
+            if (existing) {
+                if (!existing.journeys.includes(journey.name))
+                    existing.journeys.push(journey.name);
+                if (!ids.includes(existing.id))
+                    ids.push(existing.id);
+                return;
+            }
+            const path = {
+                id: `journey-${journeyPaths.length + 1}`,
+                key,
+                name: journey.name,
+                kind: 'journey',
+                description: journey.description,
+                steps,
+                start: startConfig.active,
+                ...(point?.seed ? { seed: point.seed } : {}),
+                journeys: [journey.name],
+                blockedBy: [...(supported === true ? [] : [`Start: ${supported}`]), ...blockedEvents(steps)]
+            };
+            byKey.set(key, path);
+            journeyPaths.push(path);
+            ids.push(path.id);
+        };
+        /** The events of the stretch that would start at step `from`: up to the next seeded configuration. */
+        const stretchFrom = (from) => {
+            const events = [];
+            for (let i = from; i < replay.steps.length; i++) {
+                const next = replay.steps[i];
+                if (!inScope(scope, next.transitions) || (i > from && startsAt(next.from).length > 0))
+                    break;
+                events.push(next.event);
+            }
+            return events;
+        };
+        for (const [index, step] of replay.steps.entries()) {
+            if (!inScope(scope, step.transitions)) {
+                flush();
+                continue;
+            }
+            // Cut only where a start point suits what follows: a variant seed for other events is no place to cut.
+            const candidates = startsAt(step.from);
+            const seeded = candidates.length > 0 && candidates.some((p) => suits(p, stretchFrom(index)));
+            if (current && seeded)
+                flush();
+            if (!current) {
+                const entering = isRoot || seeded || step.transitions.some((t) => scope.entries.has(t));
+                if (!entering)
+                    continue;
+                current = [];
+            }
+            current.push(step);
+        }
+        flush();
+        if (ids.length)
+            journeys.push({ name: journey.name, description: journey.description, paths: ids });
+    }
+    const startable = (p) => !p.blockedBy.some((b) => b.startsWith('Start:'));
+    const covered = new Set(journeyPaths.filter(startable).flatMap((p) => runnableSteps(p.steps, isBlocked).flatMap((s) => s.transitions)));
+    const planned = new Set();
+    let generated = [];
+    if (startPoints.length) {
+        for (const avoidBlocked of [true, false]) {
+            const explorations = new Map();
+            const exploredFor = (source) => {
+                const regions = graph.regionsOf(source);
+                const key = regions.join('\u0000');
+                if (!explorations.has(key)) {
+                    explorations.set(key, startPoints.map((point) => graph.explore(point.config, (event) => scope.events.has(event) &&
+                        (!avoidBlocked || !isBlocked(event)) &&
+                        (!variantEvents.has(event) || Boolean(point.for?.includes(event))) &&
+                        graph.actsIn(event, regions))));
+                }
+                return explorations.get(key);
+            };
+            for (const target of scope.transitions) {
+                if (covered.has(target) || planned.has(target))
+                    continue;
+                const { source, event } = splitTransitionId(target);
+                if (avoidBlocked && isBlocked(event))
+                    continue;
+                let best = null;
+                const explored = exploredFor(source);
+                startPoints.forEach((point, i) => {
+                    const first = explored[i].firstFired.get(target);
+                    if (!first)
+                        return;
+                    const path = [...first.from.path, first.event];
+                    if (point.for && !path.some((e) => point.for.includes(e)))
+                        return;
+                    if (point.shows && !sameRegion(point.config, path[0], point.shows))
+                        return;
+                    if (!best || path.length < best.path.length)
+                        best = { origin: point, path };
+                });
+                if (!best)
+                    continue;
+                const { origin, path: events } = best;
+                const replay = graph.replay(origin.config, withoutAutomaticHandOffs(graph, origin.config, events));
+                const steps = toSteps(replay.steps).filter((s) => inScope(scope, s.transitions));
+                for (const s of runnableSteps(steps, isBlocked))
+                    for (const t of s.transitions)
+                        covered.add(t);
+                if (!avoidBlocked)
+                    for (const s of steps)
+                        for (const t of s.transitions)
+                            planned.add(t);
+                generated.push({
+                    id: '',
+                    key: pathKey(origin.seed, origin.config, steps.map((s) => s.event)),
+                    name: `Covers: ${source} → ${event}`,
+                    kind: 'generated',
+                    description: `Shortest path from ${origin.seed ? `the seed "${origin.seed}"` : 'the start'} that reaches "${source}" and takes "${event}".`,
+                    steps,
+                    start: origin.config.active,
+                    ...(origin.seed ? { seed: origin.seed } : {}),
+                    blockedBy: blockedEvents(steps)
+                });
+            }
+        }
+    }
+    const all = [...journeyPaths, ...generated];
+    const startKey = (p) => `${p.seed ?? ''}|${p.start.join('|')}`;
+    const isPrefix = (short, long) => short !== long && startable(long) && startKey(short) === startKey(long) && short.steps.length <= long.steps.length && short.steps.every((s, i) => s.event === long.steps[i].event);
+    generated = generated.filter((p, i) => !all.some((q) => isPrefix(p, q) && (q.steps.length > p.steps.length || q.kind === 'journey' || generated.indexOf(q) < i)));
+    generated.forEach((p, i) => (p.id = `generated-${i + 1}`));
+    const everPlanned = new Set([...journeyPaths, ...generated].filter(startable).flatMap((p) => p.steps.flatMap((s) => s.transitions)));
+    const unreachable = [...scope.transitions].filter((t) => !everPlanned.has(t));
+    const runCovered = new Set();
+    const paths = [...journeyPaths, ...generated].map((p) => {
+        const prefix = startable(p) ? runnableSteps(p.steps, isBlocked).flatMap((s) => s.transitions) : [];
+        const adds = prefix.some((t) => !runCovered.has(t));
+        for (const t of prefix)
+            runCovered.add(t);
+        return p.blockedBy.length && !adds ? { ...p, skipRun: true } : p;
+    });
+    return {
+        paths,
+        unreachable,
+        journeys,
+        seeds: seeds.map((s) => ({ name: s.name, active: s.config.active, ...(s.blocked ? { blocked: s.blocked } : {}) }))
+    };
+}

package/dist/core/src/privacy.d.ts

@@ -0,0 +1,8 @@
+import type { PrivacyRules } from './run/types.js';
+/** Defaults that fit any product: no real-looking emails, SSNs or card numbers in media or manifests. */
+export declare const DEFAULT_PRIVACY: Required<PrivacyRules>;
+export declare function mergePrivacy(rules?: PrivacyRules): Required<PrivacyRules>;
+/** What in `text` looks like real personal data, described without repeating it. */
+export declare function privacyFindings(text: string, where: string, rules: Required<PrivacyRules>): string[];
+/** Refuse to run against anything but the allowed hosts (loopback by default). */
+export declare function assertAllowedTarget(urls: string[], rules: Required<PrivacyRules>): void;

package/dist/core/src/privacy.js

@@ -0,0 +1,42 @@
+const EMAIL = /[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/gi;
+/** Defaults that fit any product: no real-looking emails, SSNs or card numbers in media or manifests. */
+export const DEFAULT_PRIVACY = {
+    deny: [
+        { name: 'a US Social Security number', pattern: /\b\d{3}-\d{2}-\d{4}\b/ },
+        {
+            name: 'a payment card number',
+            pattern: /\b(?!4242[ -]?4242[ -]?4242[ -]?4242\b|4000[ -]?0000[ -]?0000[ -]?0002\b|5555[ -]?5555[ -]?5555[ -]?4444\b)(?:4\d{3}|5[1-5]\d{2})[ -]?\d{4}[ -]?\d{4}[ -]?\d{4}\b/
+        }
+    ],
+    allowEmails: [/@example\.(com|org|net)$/i, /\.(test|example|invalid|localhost|local)$/i],
+    allowHosts: ['127.0.0.1', 'localhost', '::1', '[::1]']
+};
+export function mergePrivacy(rules = {}) {
+    return {
+        deny: [...DEFAULT_PRIVACY.deny, ...(rules.deny ?? [])],
+        allowEmails: [...DEFAULT_PRIVACY.allowEmails, ...(rules.allowEmails ?? [])],
+        allowHosts: rules.allowHosts ?? DEFAULT_PRIVACY.allowHosts
+    };
+}
+/** What in `text` looks like real personal data, described without repeating it. */
+export function privacyFindings(text, where, rules) {
+    const findings = [];
+    for (const email of text.match(EMAIL) ?? []) {
+        const lower = email.toLowerCase();
+        if (rules.allowEmails.some((p) => p.test(lower)))
+            continue;
+        findings.push(`${where}: an email address outside the allowed domains (${lower.replace(/^(.).*@/, '$1…@')})`);
+    }
+    for (const { name, pattern } of rules.deny)
+        if (pattern.test(text))
+            findings.push(`${where}: something shaped like ${name}`);
+    return findings;
+}
+/** Refuse to run against anything but the allowed hosts (loopback by default). */
+export function assertAllowedTarget(urls, rules) {
+    for (const url of urls) {
+        const host = new URL(url).hostname;
+        if (!rules.allowHosts.includes(host))
+            throw new Error(`Refusing to run against ${host}: allowed hosts are ${rules.allowHosts.join(', ')}`);
+    }
+}