canary-test-cli 7.0.0 → 7.1.0

package/dist/engine/core/reporter.js

@@ -25,6 +25,7 @@
  */
 import { mkdirSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
+import { ensureAscii } from '../util/ensure-ascii.js';
 const SARIF_SCHEMA = 'https://json.schemastore.org/sarif-2.1.0.json';
 const TOOL_NAME = 'Canary';
 const TOOL_VERSION = '0.1.0';
@@ -70,15 +71,6 @@ function pyOr(value, fallback) {
 function pyGet(obj, key, fallback) {
     return Object.prototype.hasOwnProperty.call(obj, key) ? obj[key] : fallback;
 }
-/**
- * Reproduce Python's `json.dumps(..., ensure_ascii=True)` (the library default)
- * on `JSON.stringify` output: escape every code point >= 0x80 as `\uXXXX`. Only
- * touches the >= 0x80 range, so the ASCII escapes `JSON.stringify` already
- * produced are left intact. (Same helper as `guardian/pr-check.ts`.)
- */
-function ensureAscii(json) {
-    return json.replace(/[€-￿]/g, (ch) => '\\u' + ch.charCodeAt(0).toString(16).padStart(4, '0'));
-}
 /**
  * `json.dumps(default=str)` replacer. Values the encoder can't natively handle
  * are coerced via `str()`; in JS the only common such value that would

package/dist/engine/core/skill-examples.js

@@ -0,0 +1,292 @@
+/**
+ * Execute the commands the docs promise (#487).
+ *
+ * #472 added `canary skills run canary-blackhawk -- --help` to a SKILL.md in
+ * the same PR that left the command broken: the CLI landed at mode 644, the
+ * spawn hit `EACCES`, and that became a bare exit 1 with no output. Nobody had
+ * ever run the command the doc documented. #480 answered part of it with a
+ * hand-written `spawnSync(cli, ['--help'])` per skill — real execution, which
+ * is why the exec-bit bug surfaced at all — but the block is duplicated across
+ * five test files, so a seventh skill is covered only when somebody remembers
+ * to add a sixth copy (#479).
+ *
+ * This module is the discovery-driven form. It consumes the surface inventory
+ * from {@link ./skill-surfaces.js} — deliberately, rather than walking the skill
+ * tree a second time: two walkers with two notions of what a skill is would
+ * disagree eventually, and that disagreement is the very bug class both checks
+ * exist to catch.
+ *
+ * ## Which examples are executable
+ *
+ * #487 left this as an open scope decision. The answer taken here is
+ * conservative and mechanical, because the alternative — a fenced-block
+ * annotation — asks every SKILL.md author to opt in, and an opt-in that is
+ * forgotten reads exactly like a skill with no examples:
+ *
+ *   - The command must live in a **shell-info fenced block** (` ```bash `,
+ *     `sh`, `shell`, `zsh`, `console`). Prose backticks are illustrative.
+ *   - It must be a **`canary` invocation**. Running arbitrary `npm`/`git` lines
+ *     out of a doc is a different and much larger blast radius.
+ *   - It must carry **no placeholder or shell metacharacter** (`<path>`, `$VAR`,
+ *     a pipe, a glob). A placeholder command was never meant to run verbatim.
+ *   - It must be **help-shaped** (`--help` / `-h` / `--version`, or a pure
+ *     listing command). This is what keeps a documented `katana scan` from
+ *     writing a ledger into whatever directory CI happens to be sitting in.
+ *
+ * Everything else is {@link ExampleVerdict.Unverifiable}, **with its reason
+ * recorded**. That is the load-bearing half of the design, and it is the same
+ * distinction `reachability.ts` draws between a dead link and a slow one: an
+ * outcome the checker is not entitled to assert on gets its own status instead
+ * of being folded into either pass or fail.
+ *
+ * ## Denominator
+ *
+ * `checked` counts the examples **actually executed** — never the examples
+ * found. Unverifiable examples travel in `GateResult.skipped`, so `gateOutcome`
+ * renders them in every summary line (D7) and an all-illustrative corpus
+ * ABSTAINS rather than reporting "all 0 examples passed" (#508).
+ */
+import { spawnSync } from 'node:child_process';
+import { SurfaceKind } from './skill-surfaces.js';
+/** Fence info strings whose contents are shell commands. */
+const SHELL_FENCES = new Set(['bash', 'sh', 'shell', 'zsh', 'console']);
+/**
+ * Characters that make a command line unsafe to run verbatim: placeholder
+ * brackets, variable expansion, redirection, pipes, subshells, globs.
+ */
+const PLACEHOLDER = /[<>${}|`*\\]/;
+/** Flags that make an invocation a pure read of the CLI's own surface. */
+const HELP_FLAGS = new Set(['--help', '-h', '--version', '-V']);
+/** Non-mutating subcommands worth executing even without a help flag. */
+const READ_ONLY_COMMANDS = new Set(['canary skills list']);
+/** How an example turned out. */
+export var ExampleVerdict;
+(function (ExampleVerdict) {
+    /** Ran and exited 0 — the doc is proven. */
+    ExampleVerdict["Executed"] = "executed";
+    /** Ran and did not exit 0 — the doc promises something broken. */
+    ExampleVerdict["Failed"] = "failed";
+    /** Could not be run at all; the reason travels with it. */
+    ExampleVerdict["Unverifiable"] = "unverifiable";
+})(ExampleVerdict || (ExampleVerdict = {}));
+export var ExampleFindingKind;
+(function (ExampleFindingKind) {
+    /** A documented command was executed and failed. */
+    ExampleFindingKind["ExampleFailed"] = "example-failed";
+    /** A code-bearing skill's doc offers no command to execute at all. */
+    ExampleFindingKind["NoDocumentedExample"] = "no-documented-example";
+})(ExampleFindingKind || (ExampleFindingKind = {}));
+/**
+ * Whether `line` closes the currently open fence.
+ *
+ * A fence closes only on a BARE delimiter run at least as long as the opener,
+ * so a ```` block may legitimately contain ``` -- the same fence rule
+ * `scripts/check_doc_links.mjs` had to get right for #686.
+ */
+function closesFence(line, delimiter, fence) {
+    if (delimiter === null)
+        return false;
+    const run = delimiter[1];
+    return (run[0] === fence[0] && run.length >= fence.length && line.trim() === run);
+}
+/** Shell-fenced lines with their 1-based source line numbers. */
+function fencedShellLines(text) {
+    const out = [];
+    const lines = text.split('\n');
+    let fence = null;
+    let shell = false;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const delimiter = /^\s*(`{3,}|~{3,})\s*([A-Za-z0-9_+-]*)/.exec(line);
+        if (fence === null) {
+            // A fence opens on a delimiter run; the info string decides whether the
+            // body is shell. Anything else (json, ts, text) is not a command.
+            if (delimiter) {
+                fence = delimiter[1];
+                shell = SHELL_FENCES.has((delimiter[2] ?? '').toLowerCase());
+            }
+            continue;
+        }
+        if (closesFence(line, delimiter, fence)) {
+            fence = null;
+            shell = false;
+            continue;
+        }
+        if (shell)
+            out.push({ line: i + 1, raw: line });
+    }
+    return out;
+}
+/** Classify one command line: executable, or unverifiable with a reason. */
+function classify(command) {
+    if (PLACEHOLDER.test(command)) {
+        return {
+            executable: false,
+            reason: 'contains a placeholder or shell metacharacter, so it was never ' +
+                'meant to run verbatim',
+        };
+    }
+    if (READ_ONLY_COMMANDS.has(command))
+        return { executable: true, reason: null };
+    const tokens = command.split(/\s+/);
+    if (tokens.some((t) => HELP_FLAGS.has(t))) {
+        return { executable: true, reason: null };
+    }
+    return {
+        executable: false,
+        reason: 'not help-shaped, so running it could write files, need credentials, ' +
+            'or reach the network',
+    };
+}
+/**
+ * Extract the documented `canary` commands from one document.
+ *
+ * `text` is the raw file body (the inventory already read it), `skill` and
+ * `path` are carried through onto each example so a finding is attributable.
+ */
+export function extractExamples(text, skill, path) {
+    const out = [];
+    for (const { line, raw } of fencedShellLines(text)) {
+        // Strip a `$ ` or `> ` shell prompt; a doc that shows a prompt is still
+        // documenting the command after it.
+        const command = raw
+            .trim()
+            .replace(/^[$>]\s+/, '')
+            .trim();
+        if (command === '' || command.startsWith('#'))
+            continue;
+        if (command !== 'canary' && !command.startsWith('canary '))
+            continue;
+        const { executable, reason } = classify(command);
+        out.push({ skill, path, command, line, executable, reason });
+    }
+    return out;
+}
+/** Execute the executable examples; report a verdict for every example. */
+export function runExamples(examples, run, cwd) {
+    return examples.map((example) => {
+        if (!example.executable) {
+            return {
+                example,
+                verdict: ExampleVerdict.Unverifiable,
+                detail: example.reason ?? 'unverifiable',
+            };
+        }
+        const { status, output } = run(example.command, cwd);
+        if (status === 0) {
+            return { example, verdict: ExampleVerdict.Executed, detail: 'exit 0' };
+        }
+        return {
+            example,
+            verdict: ExampleVerdict.Failed,
+            detail: status === null
+                ? `the process never started: ${output.trim() || '(no output)'}`
+                : `exit ${status}: ${output.trim() || '(no output)'}`,
+        };
+    });
+}
+/** A skill declaration that ships code, and can therefore ship broken code. */
+function codeBearing(decl) {
+    return ((decl.kind === SurfaceKind.Skill || decl.kind === SurfaceKind.FlatSkill) &&
+        decl.cli !== null);
+}
+/** Fold one skill declaration's results into `tally`. */
+function tallyDeclaration(decl, results, tally) {
+    for (const result of results) {
+        // `<skill>:<line>` rather than the absolute path: a skill's SKILL.md is
+        // unambiguous from its name, and 29 absolute paths turned the D7 skip
+        // suffix into a summary line no reader would finish. Still fully
+        // attributable; `--json` carries the paths.
+        const where = `${decl.name}:${result.example.line}`;
+        if (result.verdict === ExampleVerdict.Unverifiable) {
+            // Never silently dropped: a skip renders in the summary line, so an
+            // example nobody can run stays visible instead of leaving the corpus.
+            tally.skipped.push({ name: where, reason: result.detail });
+            continue;
+        }
+        tally.checked += 1;
+        if (result.verdict === ExampleVerdict.Failed) {
+            tally.findings.push({
+                kind: ExampleFindingKind.ExampleFailed,
+                skill: decl.name,
+                path: decl.path,
+                detail: `\`${result.example.command}\` (line ${result.example.line}) ${result.detail}`,
+            });
+        }
+    }
+}
+export function checkExamples(surfaces, run, cwd) {
+    const tally = { checked: 0, findings: [], skipped: [] };
+    for (const decl of surfaces) {
+        if (decl.kind !== SurfaceKind.Skill &&
+            decl.kind !== SurfaceKind.FlatSkill) {
+            continue;
+        }
+        const examples = extractExamples(decl.text, decl.name, decl.path);
+        // #487 acceptance: a code-bearing skill with no runnable command in its
+        // doc is UNPROVEN, not clean. A markdown-only skill has no command that a
+        // mode bit could break, so it is not held to this.
+        if (examples.length === 0) {
+            if (codeBearing(decl)) {
+                tally.findings.push({
+                    kind: ExampleFindingKind.NoDocumentedExample,
+                    skill: decl.name,
+                    path: decl.path,
+                    detail: 'declares a `cli:` but its SKILL.md documents no command in a ' +
+                        'shell fence, so nothing about it has ever been executed from ' +
+                        'the doc',
+                });
+            }
+            continue;
+        }
+        tallyDeclaration(decl, runExamples(examples, run, cwd), tally);
+    }
+    return tally;
+}
+/**
+ * The production runner: spawn the documented command against the repo's own
+ * built CLI, in `cwd`.
+ *
+ * Two deliberate substitutions, both narrow:
+ *
+ *   - The leading `canary` token becomes `node <canaryBin>`, because a doc
+ *     writes the installed name and CI has a checkout.
+ *   - `--allow-executable-skills` is inserted into a `skills run` invocation,
+ *     ahead of any `--` separator. `isExecutableSkillAllowed` refuses `cli:`
+ *     skills without a TTY, which a spawned process never has, so without the
+ *     flag every example would exit 3 and the check would measure the sandbox
+ *     rather than the doc. The flag is an execution-context opt-in and changes
+ *     nothing about the command's behaviour once it runs. See
+ *     {@link exampleArgv} for why the position matters.
+ */
+export function exampleArgv(command, canaryBin) {
+    const [, ...rest] = command.split(/\s+/);
+    if (rest[0] !== 'skills' || rest[1] !== 'run')
+        return [canaryBin, ...rest];
+    // The flag must land BEFORE `--`, or canary forwards it to the skill and the
+    // executable-skill guard still refuses. Appending it was the first bug this
+    // checker found, in itself: all four documented `skills run ... -- --help`
+    // examples reported exit 3, which measured the sandbox rather than the doc.
+    const sep = rest.indexOf('--');
+    const at = sep === -1 ? rest.length : sep;
+    return [
+        canaryBin,
+        ...rest.slice(0, at),
+        '--allow-executable-skills',
+        ...rest.slice(at),
+    ];
+}
+export function spawnRunner(canaryBin) {
+    return (command, cwd) => {
+        const res = spawnSync(process.execPath, exampleArgv(command, canaryBin), {
+            cwd,
+            encoding: 'utf-8',
+            timeout: 60_000,
+        });
+        return {
+            status: res.status,
+            output: `${res.stdout ?? ''}${res.stderr ?? ''}`,
+        };
+    };
+}
+//# sourceMappingURL=skill-examples.js.map

package/dist/engine/core/skill-surfaces.js

@@ -0,0 +1,307 @@
+/**
+ * Cross-surface skill-declaration inventory and integrity check (#452).
+ *
+ * A canary skill is not declared in one place. The same name appears in the
+ * `SKILL.md` under `agents/skills/`, in the plugin slash command under
+ * `commands/`, in the agent definition under `agents/`, and again in the
+ * per-host `agents/commands/<host>/` and `agents/agents/<host>/` trees. Each of
+ * those files is internally consistent, so every per-file assertion passes even
+ * when they disagree with each other or point at something that no longer
+ * exists.
+ *
+ * That is the bug class #452 describes: grading a value against a hardcoded
+ * literal is blind to a fact that is right on one surface and stale on another.
+ * The remedy is to grade against **agreement** and **resolvability** instead:
+ * enumerate the surfaces that declare a name, then verify the declaration
+ * against reality.
+ *
+ * ## The two rules it enforces
+ *
+ * 1. **A declared name is the name the invocation path uses.** Skill discovery
+ *    ({@link ../core/skill-registry.js}) keys off the frontmatter `name:`, while
+ *    every doc invokes the skill by its directory. When those diverge the
+ *    documented command misses and nothing says so.
+ * 2. **A documented invocation reaches something that exists and can run.** A
+ *    `cli:` path that is absent, or present at mode 0644, installs cleanly,
+ *    lists cleanly, documents cleanly — and cannot run (#478). A
+ *    `canary skills run <name>` in prose whose target has been renamed away is
+ *    the same defect one layer up.
+ *
+ * ## What it deliberately refuses to do
+ *
+ * It does not adjudicate prose. When two surfaces carry different descriptions
+ * there is no principled culprit: #452's triage settled that majority-wins is
+ * wrong at N=2 and wrong in general when one surface is the write path and the
+ * others are read models, and that only a fixture-intent floor may name a
+ * culprit. No such floor exists for skill prose, so divergent descriptions are
+ * not reported at all rather than reported against an invented winner. Adding
+ * that arbitration is the remaining half of #452 and is out of scope here.
+ *
+ * ## Denominator
+ *
+ * {@link checkSurfaces} returns a {@link GateResult} whose `checked` is the
+ * number of surface declarations actually inspected. Zero means the layout was
+ * renamed underneath the check, and `gateOutcome` turns that into a loud
+ * abstention rather than "all surfaces agree" (#508).
+ */
+import { accessSync, constants, readFileSync, readdirSync } from 'node:fs';
+import { basename, extname, join } from 'node:path';
+import { SkillRegistry } from './skill-registry.js';
+/** Where a skill name was declared. */
+export var SurfaceKind;
+(function (SurfaceKind) {
+    /** `agents/skills/<host>/<dir>/SKILL.md` — the skill itself. */
+    SurfaceKind["Skill"] = "skill";
+    /** `agents/skills/*.md` — a flat slash-command skill. */
+    SurfaceKind["FlatSkill"] = "flat-skill";
+    /** `commands/*.md` — the plugin slash command fronting a skill. */
+    SurfaceKind["PluginCommand"] = "plugin-command";
+    /** `agents/*.md` — the plugin agent definition. */
+    SurfaceKind["PluginAgent"] = "plugin-agent";
+    /** `agents/commands/<host>/**` — the per-host command definition. */
+    SurfaceKind["HarnessCommand"] = "harness-command";
+    /** `agents/agents/<host>/**` — the per-host agent definition. */
+    SurfaceKind["HarnessAgent"] = "harness-agent";
+})(SurfaceKind || (SurfaceKind = {}));
+/** What a cross-surface check found. */
+export var SurfaceFindingKind;
+(function (SurfaceFindingKind) {
+    /** Frontmatter `name:` disagrees with the directory docs invoke it by. */
+    SurfaceFindingKind["NameMismatch"] = "name-mismatch";
+    /** A declared `cli:` target does not exist. */
+    SurfaceFindingKind["CliMissing"] = "cli-missing";
+    /** A declared `cli:` target exists but is not executable (#478). */
+    SurfaceFindingKind["CliNotExecutable"] = "cli-not-executable";
+    /** A documented `canary skills run <name>` names no discoverable skill. */
+    SurfaceFindingKind["UnreachableReference"] = "unreachable-reference";
+})(SurfaceFindingKind || (SurfaceFindingKind = {}));
+/** Vendored trees are not first-party skill surfaces. */
+const IGNORED_DIRS = new Set(['node_modules', '.git', 'dist', 'coverage']);
+/**
+ * A literal canary skill name. Anchored on the `canary-`/`canary:` prefix every
+ * first-party skill carries, which keeps a hypothetical `canary skills run
+ * my-skill` in prose from being reported as a dead reference.
+ */
+const SKILL_NAME = /^canary[-:][a-z0-9:_-]*$/;
+/** Every `canary skills run <name>` in the document, placeholders excluded. */
+function referencedSkills(text) {
+    const found = new Set();
+    const pattern = /canary\s+skills\s+run\s+(\S+)/g;
+    for (const match of text.matchAll(pattern)) {
+        const token = match[1].replace(/[`'"]/g, '');
+        if (SKILL_NAME.test(token))
+            found.add(token);
+    }
+    return [...found].sort();
+}
+/** Read a file, returning null when it cannot be read. */
+function readOrNull(path) {
+    try {
+        return readFileSync(path, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+}
+function listDirs(path) {
+    try {
+        return readdirSync(path, { withFileTypes: true })
+            .filter((e) => e.isDirectory() && !IGNORED_DIRS.has(e.name))
+            .map((e) => e.name)
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+function listMarkdown(path) {
+    try {
+        return readdirSync(path, { withFileTypes: true })
+            .filter((e) => e.isFile() && e.name.endsWith('.md') && e.name !== 'README.md')
+            .map((e) => e.name)
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+/** Parse one declaring file into a {@link SurfaceDeclaration}. */
+function declare(kind, path, fallbackName, dirName) {
+    const text = readOrNull(path);
+    if (text === null)
+        return null;
+    // The SAME frontmatter parser discovery uses, deliberately: a checker with
+    // its own YAML subset would disagree with the runtime it is auditing, and
+    // that disagreement is the bug class rather than a detail (#501).
+    const fm = SkillRegistry.parseFrontmatter(text);
+    const name = typeof fm['name'] === 'string' && fm['name'] ? fm['name'] : fallbackName;
+    const description = typeof fm['description'] === 'string' ? fm['description'] : '';
+    const cli = typeof fm['cli'] === 'string' && fm['cli'] ? fm['cli'] : null;
+    return {
+        kind,
+        name,
+        dirName,
+        path,
+        description,
+        cli,
+        references: referencedSkills(text),
+        text,
+    };
+}
+/** Nested `agents/skills/<host>/<dir>/SKILL.md` declarations. */
+function nestedSkills(root) {
+    const out = [];
+    const skillsRoot = join(root, 'agents', 'skills');
+    for (const host of listDirs(skillsRoot)) {
+        for (const dir of listDirs(join(skillsRoot, host))) {
+            const path = join(skillsRoot, host, dir, 'SKILL.md');
+            const decl = declare(SurfaceKind.Skill, path, dir, dir);
+            if (decl)
+                out.push(decl);
+        }
+    }
+    return out;
+}
+/** Flat `*.md` surfaces directly inside `dir`. */
+function flatSurfaces(dir, kind) {
+    const out = [];
+    for (const file of listMarkdown(dir)) {
+        const path = join(dir, file);
+        const decl = declare(kind, path, basename(file, extname(file)), null);
+        if (decl)
+            out.push(decl);
+    }
+    return out;
+}
+/** Per-host `agents/<commands|agents>/<host>/**\/*.md` surfaces. */
+function hostSurfaces(root, segment, kind) {
+    const out = [];
+    const base = join(root, 'agents', segment);
+    for (const host of listDirs(base)) {
+        const hostDir = join(base, host);
+        out.push(...flatSurfaces(hostDir, kind));
+        // Host trees nest one more level (`harness/harness/<name>.md`).
+        for (const sub of listDirs(hostDir)) {
+            out.push(...flatSurfaces(join(hostDir, sub), kind));
+        }
+    }
+    return out;
+}
+/**
+ * Enumerate every surface that declares a skill name, in a stable order.
+ *
+ * Purely a read: no network, no subprocess, no writes. `root` is the repository
+ * root, injectable so tests build small fixture trees instead of asserting
+ * against the live checkout.
+ */
+export function collectSurfaces(root) {
+    return [
+        ...nestedSkills(root),
+        ...flatSurfaces(join(root, 'agents', 'skills'), SurfaceKind.FlatSkill),
+        ...flatSurfaces(join(root, 'commands'), SurfaceKind.PluginCommand),
+        ...flatSurfaces(join(root, 'agents'), SurfaceKind.PluginAgent),
+        ...hostSurfaces(root, 'commands', SurfaceKind.HarnessCommand),
+        ...hostSurfaces(root, 'agents', SurfaceKind.HarnessAgent),
+    ];
+}
+/** Process-backed defaults. */
+function defaultSurfaceDeps() {
+    return {
+        isExecutable: (path) => {
+            try {
+                // X_OK is exactly what `canary skills run` needs; R_OK alone is #478.
+                accessSync(path, constants.X_OK);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+        exists: (path) => {
+            try {
+                accessSync(path, constants.F_OK);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+    };
+}
+/** Findings for one declaration's `cli:` target. */
+function cliFindings(decl, deps) {
+    if (decl.cli === null)
+        return [];
+    const target = join(decl.path, '..', decl.cli);
+    if (!deps.exists(target)) {
+        return [
+            {
+                kind: SurfaceFindingKind.CliMissing,
+                surface: decl.kind,
+                name: decl.name,
+                path: decl.path,
+                detail: `declares \`cli: ${decl.cli}\` but the target does not exist, so ` +
+                    '`canary skills run` cannot invoke it',
+            },
+        ];
+    }
+    if (!deps.isExecutable(target)) {
+        return [
+            {
+                kind: SurfaceFindingKind.CliNotExecutable,
+                surface: decl.kind,
+                name: decl.name,
+                path: decl.path,
+                detail: `declares \`cli: ${decl.cli}\` but the target is not executable ` +
+                    '(#478: mode 0644 installs, lists, and documents cleanly, then fails ' +
+                    'with EACCES mapped to a bare exit 1)',
+            },
+        ];
+    }
+    return [];
+}
+/**
+ * Verify every declaration against reality.
+ *
+ * Classified **advisory**: it is landing on a repository whose surfaces have
+ * never been checked before, so its precision is not yet known and promoting it
+ * to a blocking gate would teach people to ignore it (ADR 0010). The
+ * zero-denominator abstention is not advisory — that path is loud either way.
+ */
+export function checkSurfaces(root, deps = defaultSurfaceDeps()) {
+    const surfaces = collectSurfaces(root);
+    const known = new Set(surfaces
+        .filter((s) => s.kind === SurfaceKind.Skill || s.kind === SurfaceKind.FlatSkill)
+        .flatMap((s) => (s.dirName ? [s.name, s.dirName] : [s.name])));
+    const findings = [];
+    for (const decl of surfaces) {
+        if (decl.kind === SurfaceKind.Skill &&
+            decl.dirName !== null &&
+            decl.name !== decl.dirName) {
+            findings.push({
+                kind: SurfaceFindingKind.NameMismatch,
+                surface: decl.kind,
+                name: decl.name,
+                path: decl.path,
+                detail: `frontmatter declares \`name: ${decl.name}\` but the directory is ` +
+                    `\`${decl.dirName}\`; discovery keys off the frontmatter, docs invoke ` +
+                    'the directory, so one of the two paths misses',
+            });
+        }
+        findings.push(...cliFindings(decl, deps));
+        for (const ref of decl.references) {
+            if (!known.has(ref)) {
+                findings.push({
+                    kind: SurfaceFindingKind.UnreachableReference,
+                    surface: decl.kind,
+                    name: decl.name,
+                    path: decl.path,
+                    detail: `documents \`canary skills run ${ref}\`, and no discoverable skill ` +
+                        'answers to that name',
+                });
+            }
+        }
+    }
+    return { checked: surfaces.length, findings };
+}
+//# sourceMappingURL=skill-surfaces.js.map