@maci0/dsh-cordis-review 0.17.1

package/lib/cli.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+/**
+ * `cordis-review-check [options] [root]`: print closed-form CORDIS tags.
+ *
+ * One engine (ast-grep, auto-detected) for every tag; without the binary each
+ * covered file warns on stderr and yields an LLM-fallback hit.
+ *
+ * @module dsh-cordis-review/cli
+ */
+import { stat } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { parseArgs } from 'node:util';
+import { check } from './check.js';
+const USAGE = `usage: cordis-review-check [options] [root]
+
+Print closed-form CORDIS findings for <root> (default: the current directory).
+  -h, --help               print this message
+Exit status: 0 clean, 1 findings, 2 usage, path, or ast-grep error, or an
+incomplete scan (each unreadable directory is named on stderr; findings from
+the readable part still print).
+`;
+/** Print one error line and exit with the usage-error status. */
+function fail(message) {
+    process.stderr.write(`cordis-check: ${message}\n`);
+    process.exit(2);
+}
+let positionals;
+let help = false;
+try {
+    const parsed = parseArgs({
+        args: process.argv.slice(2),
+        options: { help: { type: 'boolean', short: 'h' } },
+        allowPositionals: true,
+    });
+    help = parsed.values.help === true;
+    positionals = parsed.positionals;
+}
+catch (error) {
+    const option = /'(-[^']+)'/.exec(error instanceof Error ? error.message : '');
+    fail(`unknown flag ${JSON.stringify(option?.[1] ?? '')}; try --help`);
+}
+if (help) {
+    process.stdout.write(USAGE);
+    process.exit(0);
+}
+if (positionals.length > 1)
+    fail(`unexpected extra argument ${JSON.stringify(positionals[1])}; try --help`);
+const rootArg = positionals[0];
+if (rootArg !== undefined && rootArg.startsWith('-'))
+    fail(`unknown flag ${JSON.stringify(rootArg)}; try --help`);
+const target = resolve(rootArg ?? '.');
+let isDirectory = false;
+try {
+    isDirectory = (await stat(target)).isDirectory();
+}
+catch {
+    fail(`no such path: ${target}`);
+}
+if (!isDirectory)
+    fail(`not a directory: ${target}`);
+let result;
+try {
+    result = await check(target);
+}
+catch (error) {
+    fail(error instanceof Error ? error.message : String(error));
+}
+for (const finding of result.findings) {
+    process.stdout.write(`${finding.file}:${finding.line}: ${finding.tag}: ${finding.message}\n`);
+}
+if (result.unreadable.length > 0) {
+    // An incomplete scan is never "clean": exit 2 even when nothing was found.
+    for (const { dir, reason } of result.unreadable)
+        process.stderr.write(`cordis-check: cannot read ${dir}: ${reason}\n`);
+    const count = result.unreadable.length;
+    fail(`incomplete scan: ${count} ${count === 1 ? 'directory' : 'directories'} unreadable`);
+}
+if (result.findings.length === 0)
+    process.stdout.write('cordis-check: clean\n');
+process.exit(result.findings.length === 0 ? 0 : 1);

package/lib/frontmatter.js

@@ -0,0 +1,308 @@
+/**
+ * Frontmatter reader for the bundled `SKILL.md` files.
+ *
+ * Almost every skill header is flat: `key: value`, a quoted scalar, or a
+ * `|`/`>` block of same-indent lines. A local reader handles that subset and
+ * changes nothing; it returns `undefined` the moment the block contains
+ * anything it cannot prove it understood (a nested map, a list, a quoted
+ * scalar with an escape, a more-indented or empty line inside a block scalar,
+ * a flow collection, a YAML-tag indicator). The caller then loads `yaml`
+ * dynamically and re-parses that one file, so the fallback stays the contract
+ * and a static `import('yaml')` no longer costs every boot ~11ms of CPU for a
+ * mapping it never needed.
+ *
+ * The fast path may only claim a block whose value is *provably* what `yaml`
+ * produces. Anything it cannot prove (a `\r` anywhere in the source, a quoted
+ * key, a duplicate key, a `#` in a value, a scalar that has a typed YAML form
+ * (`0x10`, `0o17`, `.inf`, `.nan`, `1_000`, `+5`, `-0`, leading zeros), a
+ * `+` keep-chomped block scalar) is refused and re-parsed by `yaml`. A false
+ * refusal costs one dynamic import; a false claim silently diverges.
+ *
+ * The delimiter scan stays local: frontmatter with no closing `---` is not
+ * frontmatter, and the body is then the whole source.
+ *
+ * @module dsh-cordis-review/frontmatter
+ */
+/** `key: value` at column zero, with nothing but horizontal space around the colon. */
+const ENTRY = /^([^\s:#][^\s:#]*?)[ \t]*:([ \t]+[^\r\n]*|)$/;
+/** A plain scalar with no leading indicator, no `#`, no `: ` mapping, no reserved start. */
+const PLAIN = /^[^\s!&*\-?{}[\],#|>@`"'%:][^#:]*$/;
+/** A double-quoted scalar with no backslash escape in it. */
+const SIMPLE_DOUBLE = /^[^\\]*$/;
+/** A single-quoted scalar with no `''` escape in it. */
+const SIMPLE_SINGLE = /^[^']*$/;
+/** The block scalar header this reader reads: style plus an optional strip flag. */
+const BLOCK_HEADER = /^([|>])(-)?$/;
+/** A plain scalar YAML types as an integer: `0x10`, `0o17`, `+5`, `-0`, `007`, `1_000`. */
+const TYPED_INT = /^[-+]?(?:0[xX][0-9a-fA-F_]+|0[oO][0-7_]+|0[bB][01_]+|[0-9][0-9_]*)$/;
+/** A plain scalar YAML types as a special float: `.inf`, `.nan`, either sign, any case. */
+const TYPED_SPECIAL = /^[-+]?\.(?:inf|nan)$/i;
+/** A plain scalar YAML types as a float: a leading `+`, leading zeros, a `.5`/`1.` body. */
+const TYPED_FLOAT = /^(?:[-+]?[0-9][0-9_]*\.[0-9_]*|[-+]?\.[0-9][0-9_]*)$/i;
+/** The decimal scalars this reader converts itself, with no YAML-only spelling. */
+const SAFE_INT = /^-?(?:0|[1-9]\d*)$/;
+const SAFE_FLOAT = /^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][-+]?\d+)?$/;
+/** A key this reader can prove `yaml` resolves to the same string. */
+const SAFE_KEY = /^[A-Za-z_][A-Za-z0-9_.-]*$/;
+/** Code points JS `trim` strips but YAML counts as content: indentation is unprovable. */
+const JS_ONLY_SPACE = /[\u000B\u000C\u00A0\u1680\u2000-\u200A\u2028\u2029\u202F\u205F\u3000\uFEFF]/;
+/** Keys YAML resolves to a non-string: `null` becomes `''` and `True` becomes `'true'`. */
+const RESOLVED_KEY = /^(?:~|null|Null|NULL|true|True|TRUE|false|False|FALSE)$/;
+/** Keys that would not survive `data[key] = value` on an object literal. */
+const UNSAFE_KEY = new Set(['__proto__']);
+/**
+ * Count the spaces a line starts with. YAML indentation is spaces; a tab or a
+ * code point JS treats as blank is not this reader's to interpret.
+ * @param line - one line of the block.
+ * @returns the number of leading spaces.
+ */
+function leadingSpaces(line) {
+    let count = 0;
+    while (count < line.length && line.charCodeAt(count) === 32)
+        count += 1;
+    return count;
+}
+/**
+ * Split a data block into lines.
+ * @param text - the data block, already newline-normalized.
+ * @returns the lines, `\n`-separated.
+ */
+function toLines(text) {
+    return text.split('\n');
+}
+/** The closing (and opening) delimiter line, exactly as the pre-change reader tested it. */
+const DELIMITER = /^---[ \t]*$/;
+/**
+ * Split one document into its leading frontmatter block and the body, the way
+ * the pre-change reader did: line by line, so the string handed to `yaml` is
+ * byte-identical to what it parsed before the fast path existed.
+ * @param source - the file's contents.
+ * @returns the block, the body, and whether a delimited block was present.
+ */
+function splitDocument(source) {
+    const text = source.replace(/^\uFEFF/, '');
+    const lines = text.split(/\r?\n/);
+    if (lines[0] === undefined || !DELIMITER.test(lines[0]))
+        return { block: '', body: text, present: false };
+    let closing = -1;
+    for (let index = 1; index < lines.length; index += 1) {
+        if (DELIMITER.test(lines[index] ?? '')) {
+            closing = index;
+            break;
+        }
+    }
+    if (closing === -1)
+        return { block: '', body: text, present: false };
+    return { block: lines.slice(1, closing).join('\n'), body: lines.slice(closing + 1).join('\n'), present: true };
+}
+/**
+ * Read one block scalar: same-indent lines only, chomping as YAML defines it.
+ * @param lines - the block's lines.
+ * @param header - index of the `key: >` line.
+ * @param headerValue - the `>` or `|` indicator, optionally followed by `-`.
+ * @returns the scalar and the index one past the block, or `undefined` when the
+ *   block has a deeper-indented line, an interior blank line, or no content.
+ */
+function readBlockScalar(lines, header, headerValue) {
+    const style = headerValue[0];
+    const modifier = headerValue.slice(1);
+    const first = lines[header + 1];
+    if (first === undefined)
+        return undefined;
+    // Indentation is spaces only: a tab is a YAML parse error there, so a
+    // tab-led or unindented first line leaves the block to `yaml`.
+    const indent = leadingSpaces(first);
+    if (indent === 0)
+        return undefined;
+    const content = [];
+    let index = header + 1;
+    let closed = false;
+    for (; index < lines.length; index += 1) {
+        const line = lines[index];
+        if (leadingSpaces(line) < indent) {
+            closed = true;
+            break;
+        }
+        if (line.length === indent) {
+            // An interior blank line folds differently; only a trailing run may stay.
+            if (index + 1 < lines.length && lines[index + 1].length >= indent)
+                return undefined;
+            content.push('');
+            continue;
+        }
+        if (leadingSpaces(line) > indent)
+            return undefined;
+        if (line.charCodeAt(indent) === 9)
+            return undefined;
+        content.push(line.slice(indent, line.length));
+    }
+    // A block that runs to the end of the document is closed there.
+    if (!closed && index >= lines.length)
+        closed = true;
+    if (!closed)
+        return undefined;
+    if (content.length === 0)
+        return undefined;
+    let last = content.length;
+    while (last > 0 && content[last - 1] === '')
+        last -= 1;
+    const kept = content.slice(0, last);
+    if (kept.length === 0)
+        return undefined;
+    const body = style === '|' ? kept.join('\n') : kept.join(' ');
+    if (modifier.includes('-'))
+        return { value: body, next: index };
+    return { value: `${body}\n`, next: index };
+}
+/**
+ * Read one scalar value.
+ * @param raw - the value text, right-trimmed.
+ * @returns the value, or `undefined` when it needs the real YAML parser.
+ */
+function readScalar(raw) {
+    // A `#` needs YAML's comment rules (one only after whitespace) to read: refuse.
+    if (raw.includes('#'))
+        return undefined;
+    // `.inf` / `.nan` are YAML's special floats, in any case and either sign.
+    if (TYPED_SPECIAL.test(raw))
+        return undefined;
+    if (raw === '' || raw === '~' || raw === 'null' || raw === 'Null' || raw === 'NULL')
+        return { value: null };
+    if (raw === 'true' || raw === 'True' || raw === 'TRUE')
+        return { value: true };
+    if (raw === 'false' || raw === 'False' || raw === 'FALSE')
+        return { value: false };
+    if (/[0-9]/.test(raw)) {
+        // A digit anywhere means YAML may type this scalar; only the spellings this
+        // reader converts identically may pass, every other form goes to `yaml`.
+        if (SAFE_INT.test(raw) || SAFE_FLOAT.test(raw))
+            return { value: Number(raw) };
+        // Any other exponent spelling is YAML's floatExp, whose mantissa may be
+        // `.5`, `1.`, or zero-padded (`01e9`, `00e0`), none of which this reader
+        // converts, so it must not claim the block.
+        if (/[eE]/.test(raw))
+            return undefined;
+        if (TYPED_INT.test(raw) || TYPED_FLOAT.test(raw) || /^[-+]/.test(raw) || raw.includes('_'))
+            return undefined;
+    }
+    const first = raw.charCodeAt(0);
+    if (first === 34) {
+        if (!SIMPLE_DOUBLE.test(raw.slice(1)))
+            return undefined;
+        const closing = raw.indexOf('"', 1);
+        if (closing === -1 || raw.slice(closing + 1).trim() !== '')
+            return undefined;
+        return { value: raw.slice(1, closing) };
+    }
+    if (first === 39) {
+        if (!SIMPLE_SINGLE.test(raw.slice(1)))
+            return undefined;
+        const closing = raw.indexOf("'", 1);
+        if (closing === -1 || raw.slice(closing + 1).trim() !== '')
+            return undefined;
+        return { value: raw.slice(1, closing) };
+    }
+    if (!PLAIN.test(raw))
+        return undefined;
+    return { value: raw };
+}
+/**
+ * Read a flat block of `key: value` entries.
+ * @param block - the block's own text, `\n`-separated.
+ * @returns the mapping, or `undefined` when any line needs the real YAML parser.
+ */
+function parseFlatBlock(block) {
+    // `trim`/`trimStart` in this reader would measure indentation through these
+    // and YAML would not: the real parser has to decide.
+    if (JS_ONLY_SPACE.test(block))
+        return undefined;
+    const lines = toLines(block);
+    const data = {};
+    const seen = new Set();
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index];
+        if (line === '' || line.charCodeAt(0) === 35)
+            continue;
+        const entry = ENTRY.exec(line);
+        if (entry === null)
+            return undefined;
+        const key = entry[1].trimEnd();
+        if (key !== entry[1])
+            return undefined;
+        // Only a key that is provably its own string: that excludes quoted keys,
+        // flow keys, keys starting with an indicator (`@a`, `|a`, `[a]`), typed
+        // keys (`0x10`), and the words YAML resolves to `null`/`true`/`false`.
+        if (!SAFE_KEY.test(key))
+            return undefined;
+        if (RESOLVED_KEY.test(key))
+            return undefined;
+        // `yaml` rejects a duplicate key and a `__proto__` key does not survive a
+        // plain object assignment; both need the real parser.
+        if (seen.has(key) || UNSAFE_KEY.has(key))
+            return undefined;
+        seen.add(key);
+        const raw = entry[2].replace(/^[ \t]+/, '').replace(/[ \t]+$/, '');
+        if (raw === '') {
+            // A value on following lines is a nested map or a sequence.
+            const next = lines[index + 1];
+            if (next !== undefined && next.trimStart() !== '' && next.charCodeAt(0) !== 35)
+                return undefined;
+            data[key] = null;
+            continue;
+        }
+        if (raw.charCodeAt(0) === 124 || raw.charCodeAt(0) === 62) {
+            // Only clip and strip chomping are read here; `+` keeps every trailing
+            // line break, which this line-based reader does not count.
+            if (BLOCK_HEADER.exec(raw) === null)
+                return undefined;
+            const scalar = readBlockScalar(lines, index, raw);
+            if (scalar === undefined)
+                return undefined;
+            data[key] = scalar.value;
+            index = scalar.next - 1;
+            continue;
+        }
+        const scalar = readScalar(raw);
+        if (scalar === undefined)
+            return undefined;
+        data[key] = scalar.value;
+    }
+    return data;
+}
+/**
+ * Parse leading frontmatter from a markdown document, for the flat subset only.
+ * @param source - full file contents.
+ * @returns the mapping and body, or `undefined` when this file's block needs
+ *   the real YAML parser ({@link parseFrontmatterWithYaml}).
+ */
+export function parseFrontmatter(source) {
+    // `\r` is a line break to YAML and not to this reader: hand the whole file,
+    // CRLF included, to the real parser instead of claiming the block.
+    if (source.includes('\r'))
+        return undefined;
+    const { block, body, present } = splitDocument(source);
+    if (!present)
+        return { data: {}, body };
+    const data = parseFlatBlock(block);
+    if (data === undefined)
+        return undefined;
+    return { data, body };
+}
+/**
+ * Parse leading frontmatter with the `yaml` parser the harness's own filesystem
+ * skill provider uses. Loaded dynamically, so a flat header never pays for it.
+ * @param source - full file contents.
+ * @returns the parsed mapping and the remaining body.
+ */
+export async function parseFrontmatterWithYaml(source) {
+    const { block, body, present } = splitDocument(source);
+    if (!present)
+        return { data: {}, body };
+    const { parse } = await import('yaml');
+    const parsed = parse(block);
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        // Empty or non-mapping frontmatter: no keys, but the body still loads.
+        return { data: {}, body };
+    }
+    return { data: parsed, body };
+}

package/lib/index.js

@@ -0,0 +1,29 @@
+/**
+ * dsh-cordis-review: CORDIS review skills as a DeepSeek Harness plugin.
+ *
+ * One capability: every bundled `skills/<name>/SKILL.md` becomes a
+ * `ctx.skills` provider entry, so each appears as `/<name>` in the composer
+ * (DSH's command surface for user-invocable skills). `cordis-review` reviews
+ * a codebase against the CORDIS context paradigm (arXiv:2608.25512) and
+ * applies the fixes; `cordis-doc-review` writes and repairs the docs.
+ *
+ * @module dsh-cordis-review
+ */
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createSkillProvider } from './skills.js';
+/** Plugin name as it appears in the loader. */
+export const name = 'cordis-review';
+/**
+ * Mount the plugin.
+ * @param ctx - the host context.
+ */
+export function apply(ctx) {
+    const skillsDir = join(dirname(fileURLToPath(import.meta.url)), '..', 'skills');
+    ctx.inject(['skills'], (scope) => {
+        const warn = (message) => {
+            scope.logger.warn(`[cordis-review] ${message}`);
+        };
+        scope.skills.registerProvider(() => createSkillProvider({ skillsDir, onWarn: warn }));
+    });
+}

package/lib/skills.js

@@ -0,0 +1,226 @@
+/**
+ * The bundled cordis-review skill as a `ctx.skills` provider.
+ *
+ * Skills are read from this package's `skills/<name>/SKILL.md`, so that file
+ * stays the single source of truth for `/cordis-review`.
+ *
+ * @module dsh-cordis-review/skills
+ */
+import { readdir, readFile } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
+import { BUNDLED_SKILL_RANK, isSkillName } from '@deepseek-ai/dsh-skill';
+import { parseFrontmatter, parseFrontmatterWithYaml } from './frontmatter.js';
+/**
+ * Rank matching a harness bundled skill, re-exported from the registry so a
+ * project-level or user-level skill of the same name still wins the duplicate.
+ */
+export { BUNDLED_SKILL_RANK };
+/** Provider name inside the skill registry. */
+const PROVIDER_NAME = 'cordis-review';
+/** Instruction file every skill directory must carry. */
+const INSTRUCTION_FILE = 'SKILL.md';
+/** Frontmatter keys the harness defines; they project into named summary fields, never into `metadata`. */
+const SUMMARY_KEYS = new Set(['name', 'description', 'whenToUse', 'disable-model-invocation', 'user-invocable']);
+/** Pre-hyphenated invocation keys the harness refuses, with the key that replaced each. */
+const LEGACY_INVOCATION_KEYS = {
+    disableModelInvocation: 'disable-model-invocation',
+    modelInvocable: 'disable-model-invocation',
+    userInvocable: 'user-invocable',
+};
+/**
+ * Read one invocation flag with the spellings the harness filesystem provider
+ * accepts: a YAML boolean, `1`/`0`, or `true`/`yes`/`on`/`false`/`no`/`off`
+ * in any case.
+ * @param data - the frontmatter mapping.
+ * @param key - the invocation key.
+ * @returns the flag, or `undefined` when the key is absent.
+ * @throws TypeError when the value is none of those spellings.
+ */
+function frontmatterBoolean(data, key) {
+    if (!Object.hasOwn(data, key))
+        return undefined;
+    const value = data[key];
+    if (typeof value === 'boolean')
+        return value;
+    if (value === 1 || value === '1')
+        return true;
+    if (value === 0 || value === '0')
+        return false;
+    if (typeof value === 'string') {
+        const word = value.toLowerCase();
+        if (word === 'true' || word === 'yes' || word === 'on')
+            return true;
+        if (word === 'false' || word === 'no' || word === 'off')
+            return false;
+    }
+    throw new TypeError(`frontmatter field "${key}" must be a boolean`);
+}
+/**
+ * Resolve the invocation policy the way the harness filesystem provider does.
+ * @param data - the frontmatter mapping.
+ * @returns the policy; both surfaces default to on.
+ * @throws Error for a legacy camelCase key or a non-boolean value.
+ */
+function parseInvocationPolicy(data) {
+    for (const [legacy, canonical] of Object.entries(LEGACY_INVOCATION_KEYS)) {
+        if (Object.hasOwn(data, legacy))
+            throw new Error(`frontmatter field "${legacy}" is unsupported; use "${canonical}"`);
+    }
+    return {
+        modelInvocable: frontmatterBoolean(data, 'disable-model-invocation') !== true,
+        userInvocable: frontmatterBoolean(data, 'user-invocable') !== false,
+    };
+}
+/**
+ * Read and parse one skill file. Shared by discovery and direct loads so a
+ * single file enforces the name/description/frontmatter rules everywhere.
+ * @param path - absolute path of the `SKILL.md` file.
+ * @param onWarn - optional non-fatal problem sink.
+ * @param entryName - directory name fallback when frontmatter omits `name`.
+ * @param signal - aborts the read for a caller that no longer wants the result.
+ * @returns the parsed skill, or `undefined` with a warning when invalid.
+ */
+async function readSkillFile(path, onWarn, entryName, signal) {
+    if (signal?.aborted)
+        return undefined;
+    let source;
+    try {
+        source = await readFile(path, { encoding: 'utf8', signal });
+    }
+    catch (error) {
+        if (!signal?.aborted)
+            onWarn?.(`cannot read ${path}: ${error instanceof Error ? error.message : String(error)}`);
+        return undefined;
+    }
+    let parsed;
+    try {
+        // The flat reader covers every header this package ships. Its refusal is
+        // what selects the real YAML parser, so the fallback stays the contract.
+        parsed = parseFrontmatter(source) ?? await parseFrontmatterWithYaml(source);
+    }
+    catch (error) {
+        onWarn?.(`skipping ${path}: ${error instanceof Error ? error.message : String(error)}`);
+        return undefined;
+    }
+    const fallback = entryName ?? basename(path);
+    const name = String(parsed.data['name'] ?? fallback).trim();
+    const description = String(parsed.data['description'] ?? '').trim();
+    if (!isSkillName(name)) {
+        onWarn?.(`skipping ${path}: "${name}" is not a valid kebab-case skill name`);
+        return undefined;
+    }
+    if (description === '') {
+        onWarn?.(`skipping ${path}: frontmatter has no description`);
+        return undefined;
+    }
+    let invocation;
+    try {
+        invocation = parseInvocationPolicy(parsed.data);
+    }
+    catch (error) {
+        onWarn?.(`skipping ${path}: ${error instanceof Error ? error.message : String(error)}`);
+        return undefined;
+    }
+    const metadata = {};
+    for (const [key, value] of Object.entries(parsed.data)) {
+        if (SUMMARY_KEYS.has(key))
+            continue;
+        metadata[key] = value;
+    }
+    const whenToUse = String(parsed.data['whenToUse'] ?? '').trim();
+    return {
+        name,
+        description,
+        ...whenToUse === '' ? {} : { whenToUse },
+        invocation,
+        content: parsed.body.trim(),
+        metadata,
+        path,
+        directory: dirname(path),
+    };
+}
+/**
+ * Read every valid skill directory under `skillsDir`.
+ *
+ * A missing directory, a directory without `SKILL.md`, a file whose frontmatter
+ * the reader refuses, and a file with a missing description or an invalid
+ * invocation key are reported through `onWarn` and skipped: one broken file
+ * must not cost the catalog its other skills.
+ * @param skillsDir - directory holding one subdirectory per skill.
+ * @param onWarn - optional non-fatal problem sink.
+ * @param signal - aborts discovery for a caller that no longer wants the result.
+ * @returns the parsed skills, sorted by name.
+ */
+export async function discoverSkills(skillsDir, onWarn, signal) {
+    if (signal?.aborted)
+        return [];
+    let entries;
+    try {
+        entries = await readdir(skillsDir, { withFileTypes: true });
+    }
+    catch (error) {
+        if (signal?.aborted)
+            return [];
+        onWarn?.(`cannot read skills directory ${skillsDir}: ${error instanceof Error ? error.message : String(error)}`);
+        return [];
+    }
+    const skills = [];
+    for (const entry of entries) {
+        if (signal?.aborted)
+            break;
+        if (!entry.isDirectory())
+            continue;
+        const path = join(skillsDir, entry.name, INSTRUCTION_FILE);
+        const skill = await readSkillFile(path, onWarn, entry.name, signal);
+        if (skill !== undefined)
+            skills.push(skill);
+    }
+    return skills.sort((left, right) => left.name.localeCompare(right.name));
+}
+/**
+ * Build the provider the skill registry mounts.
+ * @param options - skills directory and the non-fatal problem sink.
+ * @returns a provider whose candidates are summaries and whose bodies come from disk.
+ */
+export function createSkillProvider(options) {
+    const summaryOf = (skill) => ({
+        path: skill.path,
+        name: skill.name,
+        description: skill.description,
+        ...skill.whenToUse === undefined ? {} : { whenToUse: skill.whenToUse },
+        invocation: skill.invocation,
+        source: 'bundled',
+        provider: PROVIDER_NAME,
+        resourceBase: { kind: 'directory', path: skill.directory },
+    });
+    return {
+        name: PROVIDER_NAME,
+        async list(lookup) {
+            let complete = true;
+            const skills = await discoverSkills(options.skillsDir, (message) => {
+                complete = false;
+                options.onWarn?.(message);
+            }, lookup?.signal);
+            const candidates = skills.map((skill) => ({
+                ...summaryOf(skill),
+                rank: BUNDLED_SKILL_RANK,
+                locator: skill.path,
+                metadata: skill.metadata,
+            }));
+            return complete ? candidates : { candidates, complete: false };
+        },
+        async get(candidate, lookup) {
+            if (typeof candidate.locator !== 'string')
+                return undefined;
+            // Read the locator directly: one file instead of a full re-discovery.
+            // The name check keeps a stale candidate (path reused by another skill)
+            // from loading under the wrong identity.
+            // Same directory-name fallback `list` applies, so a skill that omits
+            // `name` in frontmatter is not listed under an identity `get` refuses.
+            const skill = await readSkillFile(candidate.locator, options.onWarn, basename(dirname(candidate.locator)), lookup?.signal);
+            if (skill === undefined || skill.name !== candidate.name)
+                return undefined;
+            return { ...summaryOf(skill), content: skill.content, metadata: skill.metadata };
+        },
+    };
+}

package/lib/types/check.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Deterministic CORDIS tags, converged on one engine: ast-grep.
+ *
+ * Every tag (`mix-export`, `inject`, `toplevel`, `id`) is an ast-grep query.
+ * The engine is auto-detected: when the binary is missing, every covered file
+ * warns on stderr and yields an LLM-fallback handoff in the message (the
+ * review agent reads the message and judges the file).
+ *
+ * @module dsh-cordis-review/check
+ */
+/** One closed-form hit. */
+export interface Finding {
+    /** Checklist tag. */
+    readonly tag: 'mix-export' | 'inject' | 'toplevel' | 'id';
+    /** Path relative to the scan root. */
+    readonly file: string;
+    /** 1-based line. */
+    readonly line: number;
+    /** What to change. */
+    readonly message: string;
+}
+/** A directory the walk could not list; nothing under it was scanned. */
+export interface Unreadable {
+    /** Path relative to the scan root (`.` for the root itself). */
+    readonly dir: string;
+    /** The listing error's message. */
+    readonly reason: string;
+}
+/** One scan: its findings, and the directories it could not read. */
+export interface CheckResult {
+    readonly findings: readonly Finding[];
+    /** Non-empty means the scan is incomplete. */
+    readonly unreadable: readonly Unreadable[];
+}
+/**
+ * Scan `root` for the closed-form tags.
+ * @param root - workspace (or subdirectory) to walk.
+ */
+export declare function check(root: string): Promise<CheckResult>;