@aqian0/dsh-unity 0.0.0-stage → 0.1.0

package/lib/project.js

@@ -0,0 +1,210 @@
+/**
+ * Unity project detection.
+ *
+ * A session's working directory may sit anywhere inside a Unity project, so the
+ * plugin walks up to the nearest ancestor that carries
+ * `ProjectSettings/ProjectVersion.txt` — the marker Unity itself writes and the
+ * same file that names the editor version. From there it reads the facts that
+ * decide whether a skill applies: the editor version, the UPM packages in
+ * `Packages/manifest.json`, the inferred render pipeline, whether an Editor holds
+ * the project lock, and whether the `unity` CLI is on `PATH`.
+ *
+ * Everything here is read-only and best-effort. A partially readable project is
+ * reported with the fields it does have; a directory that is not a Unity project
+ * reports `undefined` rather than throwing.
+ *
+ * @module dsh-unity/lib/project
+ */
+import { readFile, readdir, stat } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+/** Relative path of the file that identifies a Unity project root. */
+export const PROJECT_MARKER = join('ProjectSettings', 'ProjectVersion.txt');
+/** Render-pipeline package ids, in the order that decides the answer. */
+const PIPELINE_PACKAGES = [
+    ['com.unity.render-pipelines.high-definition', 'hdrp'],
+    ['com.unity.render-pipelines.universal', 'urp'],
+];
+/** Project-relative skill roots that a project may use to override a skill. */
+const PROJECT_SKILL_ROOTS = [join('.dsh', 'skills'), join('.agents', 'skills')];
+/** How many ancestor directories detection walks before giving up. */
+const DEFAULT_MAX_DEPTH = 8;
+/**
+ * Find the nearest ancestor containing the Unity project marker.
+ *
+ * @param cwd - directory to start from.
+ * @param options - injectable filesystem and walk depth.
+ * @returns the absolute project root, or `undefined` when there is none.
+ */
+export async function findProjectRoot(cwd, options = {}) {
+    const statFile = options.stat ?? stat;
+    const maxDepth = options.maxDepth ?? DEFAULT_MAX_DEPTH;
+    let current = resolve(cwd);
+    for (let depth = 0; depth <= maxDepth; depth += 1) {
+        try {
+            const info = await statFile(join(current, PROJECT_MARKER));
+            if (info.isFile())
+                return current;
+        }
+        catch {
+            // Not a project at this level; keep walking up.
+        }
+        const parent = dirname(current);
+        if (parent === current)
+            return undefined;
+        current = parent;
+    }
+    return undefined;
+}
+/**
+ * Read the editor version from `ProjectVersion.txt`.
+ *
+ * @param text - file contents.
+ * @returns the version such as `6000.3.14f1`, or `undefined` when absent.
+ */
+export function parseProjectVersion(text) {
+    const match = /^\s*m_EditorVersion:\s*(\S+)\s*$/m.exec(text);
+    return match?.[1];
+}
+/**
+ * Read installed UPM packages from a manifest.
+ *
+ * @param text - `Packages/manifest.json` contents.
+ * @returns package id to version, or `undefined` when the manifest is not a mapping.
+ */
+export function parsePackages(text) {
+    try {
+        const manifest = JSON.parse(text);
+        const dependencies = manifest?.dependencies;
+        if (typeof dependencies !== 'object' || dependencies === null || Array.isArray(dependencies))
+            return undefined;
+        const packages = new Map();
+        for (const [name, version] of Object.entries(dependencies)) {
+            if (typeof version === 'string')
+                packages.set(name, version.trim());
+        }
+        return packages;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Infer the render pipeline from installed packages.
+ *
+ * @param packages - installed packages, or `undefined` when unknown.
+ * @returns the pipeline name, or `undefined` when the package list is unknown.
+ */
+export function inferRenderPipeline(packages) {
+    if (packages === undefined)
+        return undefined;
+    for (const [id, pipeline] of PIPELINE_PACKAGES) {
+        if (packages.has(id))
+            return pipeline;
+    }
+    return 'builtin';
+}
+/**
+ * Detect the Unity project that contains a directory.
+ *
+ * @param cwd - session working directory.
+ * @param options - injectable collaborators and walk depth.
+ * @returns project facts, or `undefined` outside a project.
+ */
+export async function detectProject(cwd, options = {}) {
+    if (typeof cwd !== 'string' || cwd === '')
+        return undefined;
+    const statFile = options.stat ?? stat;
+    const readText = options.readFile ?? ((path) => readFile(path, 'utf8'));
+    const root = await findProjectRoot(cwd, { ...options, stat: statFile });
+    if (root === undefined)
+        return undefined;
+    let editorVersion;
+    try {
+        editorVersion = parseProjectVersion(await readText(join(root, PROJECT_MARKER)));
+    }
+    catch {
+        editorVersion = undefined;
+    }
+    let packages;
+    try {
+        packages = parsePackages(await readText(join(root, 'Packages', 'manifest.json')));
+    }
+    catch {
+        packages = undefined;
+    }
+    let editorOpen = false;
+    try {
+        editorOpen = (await statFile(join(root, 'Temp', 'UnityLockfile'))).isFile();
+    }
+    catch {
+        editorOpen = false;
+    }
+    let cliAvailable = false;
+    if (typeof options.resolveExecutable === 'function') {
+        try {
+            cliAvailable = (await options.resolveExecutable('unity')) !== undefined;
+        }
+        catch {
+            cliAvailable = false;
+        }
+    }
+    return {
+        root,
+        ...(editorVersion === undefined ? {} : { editorVersion }),
+        ...(packages === undefined ? {} : { packages }),
+        renderPipeline: inferRenderPipeline(packages),
+        editorOpen,
+        cliAvailable,
+    };
+}
+/**
+ * Skill names a project provides itself, which this plugin must not shadow.
+ *
+ * @param root - project root.
+ * @param options - injectable filesystem.
+ * @returns skill names found under the project skill roots.
+ */
+export async function readProjectSkillNames(root, options = {}) {
+    const listDir = options.readdir ?? readdir;
+    const statFile = options.stat ?? stat;
+    const names = new Set();
+    for (const relative of PROJECT_SKILL_ROOTS) {
+        let entries;
+        try {
+            entries = await listDir(join(root, relative), { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory() && !entry.isSymbolicLink())
+                continue;
+            try {
+                const info = await statFile(join(root, relative, entry.name, 'SKILL.md'));
+                if (info.isFile())
+                    names.add(entry.name);
+            }
+            catch {
+                // A directory without SKILL.md is not a skill override.
+            }
+        }
+    }
+    return names;
+}
+/**
+ * A short, stable identity for a fact set, used to notice project changes.
+ *
+ * @param facts - detected facts.
+ * @returns a cache and comparison key.
+ */
+export function factsKey(facts) {
+    if (facts === undefined)
+        return 'none';
+    const packages = facts.packages === undefined
+        ? '?'
+        : [...facts.packages.entries()]
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([id, version]) => `${id}@${version}`)
+            .join(',');
+    return [facts.root, facts.editorVersion ?? '?', facts.renderPipeline ?? '?', facts.editorOpen ? 'open' : 'closed', packages].join('|');
+}

package/lib/registry.js

@@ -0,0 +1,268 @@
+/**
+ * Per-agent skill provider registry.
+ *
+ * A bundle row lands in the harness's global scope layer, while an agent preset
+ * mounts its own skill provider in the agent's layer — and the nearest layer wins
+ * a duplicate name outright, regardless of rank. Registering from a bundle row
+ * alone therefore loses to whatever the preset already sees, and cannot vary by
+ * project. Registering through `agent.ctx` instead places this provider in that
+ * agent's layer: it wins the names it owns, and its catalog can depend on the
+ * project the agent is actually working in.
+ *
+ * This module keeps that bookkeeping: one shared reader and parse cache, one fact
+ * cache per working directory, and one registration per live agent. It also
+ * implements the provider itself, which re-reads the project facts whenever the
+ * harness asks for the catalog, so a changed editor version or package list
+ * invalidates the catalog instead of waiting for a restart.
+ *
+ * @module dsh-unity/lib/registry
+ */
+import { detectProject, factsKey, readProjectSkillNames } from './project.js';
+import { gateCatalog, renderContext } from './gating.js';
+import { createUnitySkillReader } from './skills.js';
+/** How long detected project facts stay fresh before they are read again. */
+export const FACTS_TTL_MS = 2000;
+/** Prompt order for the contributed Unity context: after policies, before harness source. */
+const CONTEXT_ORDER = 180;
+/**
+ * Create the registry that owns every per-agent registration.
+ *
+ * @param options - registry settings and injectable collaborators.
+ * @returns the registry.
+ */
+export function createAgentRegistry(options) {
+    const { ctx, settings } = options;
+    const skillReader = options.reader ??
+        createUnitySkillReader({
+            skillDir: settings.skillDir,
+            providerName: settings.providerName,
+            source: settings.source,
+            rank: settings.rank,
+            exclude: settings.exclude,
+            parseCache: settings.parseCache,
+            logger: ctx.logger,
+        });
+    const detectProjectFacts = options.detect ?? ((cwd) => detectProject(cwd, resolveDetectOptions(ctx)));
+    const readOverrides = options.readProjectSkills ?? ((root) => readProjectSkillNames(root));
+    const factsByCwd = new Map();
+    const overridesByRoot = new Map();
+    const states = new Map();
+    async function factsFor(cwd) {
+        if (typeof cwd !== 'string' || cwd === '')
+            return undefined;
+        const cached = factsByCwd.get(cwd);
+        const now = Date.now();
+        if (cached !== undefined && now - cached.at < FACTS_TTL_MS)
+            return cached.facts;
+        let facts;
+        try {
+            facts = await detectProjectFacts(cwd);
+        }
+        catch (error) {
+            ctx.logger.warn(`unity skills: project detection failed for ${cwd}: ${String(error)}`);
+            facts = undefined;
+        }
+        factsByCwd.set(cwd, { facts, at: now });
+        return facts;
+    }
+    async function overridesFor(facts) {
+        if (facts === undefined || !settings.respectProjectRoots)
+            return new Set();
+        const now = Date.now();
+        const cached = overridesByRoot.get(facts.root);
+        if (cached !== undefined && now - cached.at < FACTS_TTL_MS)
+            return cached.names;
+        let names;
+        try {
+            names = await readOverrides(facts.root);
+        }
+        catch {
+            names = new Set();
+        }
+        overridesByRoot.set(facts.root, { names, at: now });
+        return names;
+    }
+    /** Compute the gated catalog for one working directory. */
+    async function view(cwd, lookup) {
+        const facts = await factsFor(cwd);
+        const projectSkills = await overridesFor(facts);
+        const candidates = await skillReader.list(lookup);
+        const gated = gateCatalog(candidates, facts, settings, projectSkills);
+        return { ...gated, facts, key: factsKey(facts) };
+    }
+    /** The provider one agent sees. */
+    class UnitySkillProvider {
+        name;
+        resolveView;
+        constructor(providerName, resolveView) {
+            this.name = providerName;
+            this.resolveView = resolveView;
+        }
+        async list(lookup = {}) {
+            const result = await this.resolveView(lookup);
+            return result.candidates;
+        }
+        get(candidate, lookup = {}) {
+            return skillReader.load(candidate, lookup);
+        }
+    }
+    function cwdOf(agent) {
+        const session = agent?.session;
+        let directory;
+        try {
+            directory = serviceOf(ctx, 'workingDirectory')?.get(session);
+        }
+        catch {
+            directory = undefined;
+        }
+        return directory ?? session?.header?.cwd ?? session?.cwd;
+    }
+    async function add(agent) {
+        const id = agent?.session?.id ?? agent?.id;
+        if (id === undefined || states.has(id))
+            return 'skipped';
+        const agentSkills = serviceOf(agent?.ctx, 'skills');
+        if (agentSkills === undefined)
+            return 'unavailable';
+        const cwd = cwdOf(agent);
+        const state = {
+            id,
+            agent: agent,
+            control: undefined,
+            facts: undefined,
+            hidden: [],
+            lastKey: 'unset',
+            disposers: [],
+        };
+        states.set(id, state);
+        const provider = new UnitySkillProvider(settings.providerName, async (lookup) => {
+            const current = cwdOf(agent) ?? cwd;
+            const result = await view(current, lookup);
+            state.facts = result.facts;
+            state.hidden = result.hidden;
+            if (result.key !== state.lastKey) {
+                state.lastKey = result.key;
+                // Facts moved (editor version, packages, project root): refresh the cached
+                // catalog so the next snapshot reflects the new gating.
+                const control = state.control;
+                if (control !== undefined)
+                    queueMicrotask(() => control.invalidate());
+            }
+            return result;
+        });
+        state.disposers.push(agentSkills.registerProvider((control) => {
+            state.control = control;
+            return provider;
+        }));
+        const agentPrompt = serviceOf(agent?.ctx, 'systemPrompt');
+        if (settings.injectContext && agentPrompt !== undefined) {
+            state.disposers.push(agentPrompt.context({
+                name: 'unity:project',
+                order: CONTEXT_ORDER,
+                text: () => renderContext(state.facts, state.hidden) ?? '',
+            }));
+        }
+        // Prime the facts so the first prompt assembly already carries the context.
+        await factsFor(cwd);
+        return 'registered';
+    }
+    function remove(agent) {
+        const id = typeof agent?.session?.id === 'string' ? agent.session.id : typeof agent?.id === 'string' ? agent.id : undefined;
+        if (id === undefined)
+            return;
+        const state = states.get(id);
+        if (state === undefined)
+            return;
+        states.delete(id);
+        for (const dispose of state.disposers.splice(0)) {
+            try {
+                dispose();
+            }
+            catch (error) {
+                ctx.logger.warn(`unity skills: registration cleanup failed: ${String(error)}`);
+            }
+        }
+    }
+    return {
+        reader: skillReader,
+        size: () => states.size,
+        add,
+        remove,
+        factsFor,
+        projectSkillsFor: overridesFor,
+        invalidateAll() {
+            for (const state of states.values())
+                state.control?.invalidate();
+        },
+        disposeAll() {
+            for (const state of [...states.values()])
+                remove(state.agent);
+            states.clear();
+            factsByCwd.clear();
+            overridesByRoot.clear();
+        },
+    };
+}
+/**
+ * Resolve an optional service from a context without requiring an injection.
+ *
+ * @param context - the context to read from, possibly an agent scope.
+ * @param name - service name.
+ * @returns the service, or `undefined` when unavailable.
+ */
+export function serviceOf(context, name) {
+    if (context === undefined)
+        return undefined;
+    try {
+        return context.get(name);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Options passed to the real project detector. */
+export function resolveDetectOptions(ctx) {
+    const subprocess = serviceOf(ctx, 'subprocess');
+    return {
+        maxDepth: 8,
+        ...(subprocess === undefined
+            ? {}
+            : {
+                resolveExecutable: async (command) => {
+                    try {
+                        return await subprocess.resolveExecutable(command);
+                    }
+                    catch {
+                        return undefined;
+                    }
+                },
+            }),
+    };
+}
+/**
+ * Build a single provider that resolves project facts from each lookup's `cwd`.
+ *
+ * Used as the fallback when a plugin context cannot reach `agent.ctx.skills`: the
+ * catalog still follows each lookup's working directory, but it registers in the
+ * global layer, where the nearest layer (the agent preset) wins a duplicate name.
+ * Context contribution stays agent-scoped, so a deployment on this path gets
+ * gating without the runtime-context line.
+ *
+ * @param options - settings and the registry whose caches are reused.
+ * @returns the provider to register globally.
+ */
+export function createGlobalProvider(options) {
+    const { settings, registry } = options;
+    return {
+        name: settings.providerName,
+        async list(lookup = {}) {
+            const candidates = await registry.reader.list(lookup);
+            const facts = await registry.factsFor(lookup.cwd);
+            const projectSkills = await registry.projectSkillsFor(facts);
+            return gateCatalog(candidates, facts, settings, projectSkills).candidates;
+        },
+        get(candidate, lookup = {}) {
+            return registry.reader.load(candidate, lookup);
+        },
+    };
+}

package/lib/requirements.js

@@ -0,0 +1,214 @@
+/**
+ * Unity version and UPM package requirement arithmetic.
+ *
+ * Skill frontmatter can state what the skill needs: `required_editor_version`
+ * (a range such as `>=6000.6`) and `required_packages` (a map of package id to
+ * range). The harness has no equivalent mechanism, so this module turns those
+ * declarations into a decision the plugin can act on: is the skill applicable to
+ * the project this agent is working in?
+ *
+ * Parsing is deliberately tolerant. A Unity editor version like `6000.3.14f1`
+ * becomes `[6000, 3, 14]` — the `f1` build suffix is information about the build
+ * channel, not ordering — while a package version keeps its prerelease tag.
+ * Anything unparseable is "unknown", and the caller treats unknown as *do not
+ * hide*: a declaration nobody can evaluate must not silently remove a skill.
+ *
+ * @module dsh-unity/lib/requirements
+ */
+/** Range operators this reader understands, longest match first. */
+const OPERATORS = ['>=', '<=', '>', '<', '=', '^', '~'];
+/**
+ * Parse a version string into comparable numeric segments.
+ *
+ * @param value - raw version such as `6000.3.14f1`, `17.5.0`, `1.2`.
+ * @returns the parsed version, or `undefined` when it is not a version.
+ */
+export function parseVersion(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const text = value.trim();
+    if (text === '')
+        return undefined;
+    // Unity editor versions carry a build channel suffix: 6000.3.14f1, 2022.3.10b5.
+    const match = /^v?(\d+(?:\.\d+)*)(?:[-+]([0-9A-Za-z.-]+))?$/.exec(text.replace(/[fabp]\d+$/, ''));
+    if (match === null)
+        return undefined;
+    const segments = (match[1] ?? '').split('.').map((part) => Number(part));
+    if (segments.some((segment) => !Number.isInteger(segment) || segment < 0))
+        return undefined;
+    return { segments, prerelease: match[2] };
+}
+/** Compare two parsed versions, padding the shorter one with zeros. */
+export function compareVersions(left, right) {
+    const length = Math.max(left.segments.length, right.segments.length);
+    for (let index = 0; index < length; index += 1) {
+        const a = left.segments[index] ?? 0;
+        const b = right.segments[index] ?? 0;
+        if (a !== b)
+            return a < b ? -1 : 1;
+    }
+    if (left.prerelease === right.prerelease)
+        return 0;
+    if (left.prerelease === undefined)
+        return 1;
+    if (right.prerelease === undefined)
+        return -1;
+    return left.prerelease < right.prerelease ? -1 : 1;
+}
+/** Resolve one comparator such as `>=6000.6` against a version. */
+function satisfiesToken(token, version) {
+    const operator = OPERATORS.find((candidate) => token.startsWith(candidate)) ?? '';
+    const body = (operator === '' ? token : token.slice(operator.length)).trim();
+    if (body === '' || body === '*' || body === 'x')
+        return true;
+    const wanted = parseVersion(body);
+    if (wanted === undefined)
+        return undefined;
+    // A bare `6000.6` means "this release line", i.e. >=6000.6 <6000.7; a full
+    // three-part version is an exact release.
+    if (operator === '' || operator === '=') {
+        if (wanted.segments.length < 3)
+            return isWithinLine(version, wanted);
+        return compareVersions(version, wanted) === 0;
+    }
+    switch (operator) {
+        case '>=':
+            return compareVersions(version, wanted) >= 0;
+        case '>':
+            return compareVersions(version, wanted) > 0;
+        case '<=':
+            return compareVersions(version, wanted) <= 0;
+        case '<':
+            return compareVersions(version, wanted) < 0;
+        case '^':
+            return compareVersions(version, wanted) >= 0 && compareVersions(version, caretUpperBound(wanted)) < 0;
+        case '~':
+            return compareVersions(version, wanted) >= 0 && compareVersions(version, tildeUpperBound(wanted)) < 0;
+        default:
+            return undefined;
+    }
+}
+/** Whether a version sits inside the release line the wanted prefix names. */
+function isWithinLine(version, wanted) {
+    for (let index = 0; index < wanted.segments.length; index += 1) {
+        if ((version.segments[index] ?? 0) !== wanted.segments[index])
+            return false;
+    }
+    return true;
+}
+/** `^1.2.3` allows `<2.0.0`; `^0.2.3` allows `<0.3.0`. */
+function caretUpperBound(wanted) {
+    const major = wanted.segments[0] ?? 0;
+    const minor = wanted.segments[1] ?? 0;
+    return (major > 0 ? parseVersion(`${major + 1}.0.0`) : parseVersion(`0.${minor + 1}.0`));
+}
+/** `~1.2.3` allows `<1.3.0`. */
+function tildeUpperBound(wanted) {
+    const major = wanted.segments[0] ?? 0;
+    const minor = wanted.segments[1] ?? 0;
+    return parseVersion(`${major}.${minor + 1}.0`);
+}
+/**
+ * Check a range against a version.
+ *
+ * @param rawRange - range text, for example `>=6000.6`.
+ * @param rawVersion - version text, for example `6000.3.14f1`.
+ * @returns `undefined` when either side cannot be parsed, so the caller can treat
+ *   the answer as unknown instead of hiding a skill.
+ */
+export function satisfiesRange(rawRange, rawVersion) {
+    if (typeof rawRange !== 'string' || rawRange.trim() === '')
+        return true;
+    if (rawVersion === undefined || rawVersion === null)
+        return undefined;
+    const version = parseVersion(rawVersion);
+    if (version === undefined)
+        return undefined;
+    // Comparators may be comma- or space-separated, and the operator may be
+    // separated from its version (`>= 6000.6`), so normalise before splitting.
+    const normalized = rawRange.replace(/(>=|<=|>|<|=|\^|~)\s+/g, '$1');
+    const tokens = normalized.split(/[,\s]+/).filter((token) => token !== '');
+    if (tokens.length === 0)
+        return true;
+    let unknown = false;
+    for (const token of tokens) {
+        const verdict = satisfiesToken(token, version);
+        if (verdict === undefined)
+            unknown = true;
+        else if (verdict === false)
+            return false;
+    }
+    return unknown ? undefined : true;
+}
+/**
+ * Read the requirement declarations out of parsed skill frontmatter.
+ *
+ * @param data - parsed SKILL.md frontmatter.
+ * @returns the declared editor range and package ranges.
+ */
+export function readRequirements(data) {
+    const rawEditor = data.required_editor_version;
+    const editor = typeof rawEditor === 'string' ? rawEditor : typeof rawEditor === 'number' ? String(rawEditor) : undefined;
+    const packages = [];
+    const declared = data.required_packages;
+    if (typeof declared === 'object' && declared !== null && !Array.isArray(declared)) {
+        for (const [name, range] of Object.entries(declared)) {
+            if (typeof range === 'string' || typeof range === 'number')
+                packages.push({ name, range: String(range) });
+            else if (range === null || range === '')
+                packages.push({ name, range: '' });
+        }
+    }
+    return { ...(editor === undefined ? {} : { editor }), packages };
+}
+/**
+ * Evaluate requirements against project facts.
+ *
+ * @param requirements - declarations from {@link readRequirements}.
+ * @param facts - detected project facts; `undefined` means no project was detected.
+ * @returns the decision; `applicable` stays true when the answer is only unknown.
+ */
+export function evaluateRequirements(requirements, facts) {
+    const reasons = [];
+    let unknown = false;
+    if (requirements.editor !== undefined) {
+        if (facts?.editorVersion === undefined) {
+            unknown = true;
+            reasons.push(`cannot check Unity ${requirements.editor}: editor version unknown`);
+        }
+        else {
+            const verdict = satisfiesRange(requirements.editor, facts.editorVersion);
+            if (verdict === false) {
+                return { applicable: false, unknown, reasons: [`needs Unity ${requirements.editor} (project ${facts.editorVersion})`] };
+            }
+            if (verdict === undefined) {
+                unknown = true;
+                reasons.push(`cannot check Unity ${requirements.editor} against ${facts.editorVersion}`);
+            }
+        }
+    }
+    for (const requirement of requirements.packages) {
+        if (facts?.packages === undefined) {
+            unknown = true;
+            reasons.push(`cannot check ${requirement.name}: installed packages unknown`);
+            continue;
+        }
+        const installed = facts.packages.get(requirement.name);
+        if (installed === undefined) {
+            return {
+                applicable: false,
+                unknown,
+                reasons: [`missing package ${requirement.name}${requirement.range === '' ? '' : ` ${requirement.range}`}`],
+            };
+        }
+        const verdict = satisfiesRange(requirement.range, installed);
+        if (verdict === false) {
+            return { applicable: false, unknown, reasons: [`needs ${requirement.name} ${requirement.range} (project ${installed})`] };
+        }
+        if (verdict === undefined) {
+            unknown = true;
+            reasons.push(`cannot check ${requirement.name} ${requirement.range} against ${installed}`);
+        }
+    }
+    return { applicable: true, unknown, reasons };
+}