@shrkcrft/inspector 0.1.0-alpha.30 → 0.1.0-alpha.32

package/dist/contributions-report.js

@@ -0,0 +1,242 @@
+/**
+ * THE contributions report (round 12, ONE-CHANGE) — `shrk packs contributions`'
+ * `By file:` section and MCP `get_pack_contributions`' `report`.
+ *
+ * "Did what I wrote take effect?" has three columns per contributed file:
+ * entries ACCEPTED (the inventory's structural entries — every loader-backed
+ * kind is structural since 12.1e), entries REJECTED with every reason (THE
+ * rejection channel, carried by the inventory), and references that could not
+ * be checked because their kind's registry is empty or undeclarable (the
+ * self-config doctor's own reference probes, `collectUnresolvableReferences`).
+ * Nothing here resolves or loads anything itself.
+ */
+import { existsSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { CONTRIBUTION_FILE_KEYS } from '@shrkcrft/plugin-api';
+import { ContributionKind } from "./contribution-kind.js";
+import { contributionFileLabel, contributionKindOfLoader, formatEntryRejection } from "./contribution-load-failures.js";
+import { buildPackContributionsInventoryAsync, contributionKindForSlot, } from "./pack-contributions-inventory.js";
+import { collectUnresolvableReferences } from "./self-config-doctor-v2.js";
+/** A reference-declaring asset kind → the contribution kind its file is, for a file no other evidence named. */
+const SOURCE_KIND = {
+    'registration-hint': ContributionKind.RegistrationHint,
+    'routing-hint': ContributionKind.TaskRoutingHint,
+    convention: ContributionKind.Convention,
+    template: ContributionKind.Template,
+    knowledge: ContributionKind.Knowledge,
+    rule: ContributionKind.Rule,
+    'path-convention': ContributionKind.Path,
+    construct: ContributionKind.Construct,
+    'boundary-rule': ContributionKind.Boundary,
+    // Round 13: the scan covers search-tuning boost keys, as `search tuning doctor` does.
+    'search-tuning': ContributionKind.SearchTuning,
+};
+/** A load failure's loader `kind` → its contribution kind, through THE table (`contributionKindOfLoader`). */
+function asKind(kind, fallback) {
+    return contributionKindOfLoader(kind) ?? fallback;
+}
+/**
+ * The report from an already-built inventory and reference scan — the pure
+ * half; {@link buildContributionsReport} gathers both.
+ */
+export function contributionsReportOf(inspection, inventory, references) {
+    const rows = new Map();
+    const rel = (abs) => contributionFileLabel(inspection.projectRoot, abs);
+    const posix = (file) => file.split(nodePath.sep).join('/');
+    const rowFor = (file, kind, packageName) => {
+        const key = posix(file);
+        let row = rows.get(key);
+        if (!row) {
+            row = {
+                file: key,
+                kind,
+                ...(packageName ? { packageName } : {}),
+                status: 'loaded',
+                acceptedIds: new Set(),
+                rejected: [],
+                unresolvable: new Map(),
+            };
+            rows.set(key, row);
+        }
+        if (!row.packageName && packageName)
+            row.packageName = packageName;
+        return row;
+    };
+    // 1) Every file a pack manifest declares (a missing one is a `missing` row).
+    for (const pack of inspection.packs.validPacks ?? []) {
+        const contributions = (pack.manifest?.contributions ?? {});
+        for (const slot of CONTRIBUTION_FILE_KEYS) {
+            const kind = contributionKindForSlot(slot);
+            if (!kind)
+                continue;
+            for (const r of contributions[slot] ?? []) {
+                const abs = nodePath.resolve(pack.packageRoot, r);
+                const row = rowFor(rel(abs), kind, pack.packageName);
+                if (!existsSync(abs))
+                    row.status = 'missing';
+            }
+        }
+    }
+    // 2) Accepted entries (structural) — and every file the inventory saw.
+    for (const e of inventory.entries) {
+        if (!e.sourceFile)
+            continue;
+        const row = rowFor(e.sourceFile, e.kind, e.packageName);
+        if (e.extractionMode === 'structural')
+            row.acceptedIds.add(e.id);
+    }
+    // 3) Rejected entries — THE rejection channel.
+    for (const r of inventory.rejections) {
+        rowFor(r.file, r.kind, r.packageName).rejected.push({
+            index: r.index,
+            ...(r.exportName ? { exportName: r.exportName } : {}),
+            ...(r.entryId !== undefined ? { entryId: r.entryId } : {}),
+            reasons: r.reasons,
+            cause: r.cause,
+        });
+    }
+    // 4) Files that failed to load.
+    for (const f of inventory.loadFailures) {
+        const row = rowFor(f.file, asKind(f.kind, ContributionKind.Knowledge), f.packageName);
+        row.status = 'failed';
+        row.loadError = f.message;
+    }
+    // 5) References that could not be checked, grouped per (source, field, kind, reason).
+    let unattributed = 0;
+    for (const u of references.references) {
+        if (!u.file) {
+            unattributed += 1;
+            continue;
+        }
+        const row = rowFor(rel(u.file), SOURCE_KIND[u.sourceKind] ?? ContributionKind.Knowledge, u.packageName);
+        const key = `${u.sourceId}|${u.field}|${u.kind}|${u.reason}`;
+        const g = row.unresolvable.get(key) ?? { sourceId: u.sourceId, field: u.field, kind: u.kind, ids: [], reason: u.reason };
+        g.ids.push(u.id);
+        row.unresolvable.set(key, g);
+    }
+    const files = [...rows.values()]
+        .map((r) => {
+        const accepted = r.acceptedIds.size;
+        return {
+            file: r.file,
+            kind: r.kind,
+            ...(r.packageName ? { packageName: r.packageName } : {}),
+            source: r.packageName ? 'pack' : 'local',
+            status: r.status,
+            declared: accepted + r.rejected.length,
+            accepted,
+            acceptedIds: [...r.acceptedIds].sort(),
+            rejected: [...r.rejected].sort((a, b) => a.index - b.index),
+            ...(r.loadError !== undefined ? { loadError: r.loadError } : {}),
+            unresolvableReferences: [...r.unresolvable.values()].map((g) => ({ ...g, ids: [...g.ids] })),
+        };
+    })
+        .sort((a, b) => a.file.localeCompare(b.file) || a.kind.localeCompare(b.kind));
+    return summarise(files, references.expected, unattributed);
+}
+/** Totals + THE reference coverage over `files` (`probed` = every reference probed in view). */
+function summarise(files, probed, unattributed) {
+    const unresolvable = files.reduce((n, f) => n + f.unresolvableReferences.reduce((m, g) => m + g.ids.length, 0), 0) + unattributed;
+    const labels = files.flatMap((f) => f.unresolvableReferences.flatMap((g) => g.ids.map((id) => `${f.file}: ${g.sourceId} ${g.field} → ${g.kind} ${id}`)));
+    const referenceCoverage = probed > 0
+        ? {
+            subject: 'contributed references',
+            unit: 'references',
+            expected: probed,
+            examined: Math.max(0, probed - unresolvable),
+            ...(unresolvable > 0 ? { unexamined: labels.slice(0, 20), unexaminedTotal: unresolvable } : {}),
+            reason: "could not be checked — their kind's registry is empty in this workspace, or nothing can declare it",
+        }
+        : undefined;
+    return {
+        files,
+        totals: {
+            files: files.length,
+            declared: files.reduce((n, f) => n + f.declared, 0),
+            accepted: files.reduce((n, f) => n + f.accepted, 0),
+            rejected: files.reduce((n, f) => n + f.rejected.length, 0),
+            loadFailed: files.filter((f) => f.status === 'failed').length,
+            missing: files.filter((f) => f.status === 'missing').length,
+            unresolvable,
+        },
+        ...(referenceCoverage ? { referenceCoverage } : {}),
+    };
+}
+/**
+ * The report narrowed to `--pack` / `--kind`. A narrowed view settles on the
+ * references IN VIEW: its coverage is the view's unresolvable references
+ * (examined 0 of them), so a filter can never borrow another file's pass.
+ */
+export function filterContributionsReport(report, filter) {
+    if (!filter.pack && !filter.kind)
+        return report;
+    const files = report.files.filter((f) => (!filter.pack || f.packageName === filter.pack) && (!filter.kind || f.kind === filter.kind));
+    const inView = files.reduce((n, f) => n + f.unresolvableReferences.reduce((m, g) => m + g.ids.length, 0), 0);
+    return summarise(files, inView, 0);
+}
+/** Every contributed file, accepted vs rejected vs unresolvable. */
+export async function buildContributionsReport(inspection, options = {}) {
+    const inventory = options.inventory ?? (await buildPackContributionsInventoryAsync(inspection));
+    const references = options.references ?? (await collectUnresolvableReferences(inspection));
+    return contributionsReportOf(inspection, inventory, references);
+}
+function fileMark(f) {
+    if (f.status !== 'loaded' || f.rejected.length > 0)
+        return '✗';
+    return f.unresolvableReferences.length > 0 ? '~' : '✓';
+}
+function fileSummary(f) {
+    if (f.status === 'failed')
+        return `FAILED TO LOAD — ${f.loadError ?? 'import error'}`;
+    if (f.status === 'missing')
+        return 'MISSING on disk — nothing in it takes effect';
+    const parts = [`${f.declared} declared`, `${f.accepted} accepted`];
+    if (f.rejected.length > 0)
+        parts.push(`${f.rejected.length} rejected`);
+    const u = f.unresolvableReferences.reduce((n, g) => n + g.ids.length, 0);
+    if (u > 0)
+        parts.push(`${u} unresolvable reference(s)`);
+    return parts.join(' · ');
+}
+/** The `By file:` text section (after `By kind:`). */
+export function renderContributionsByFileText(report) {
+    const lines = [];
+    const t = report.totals;
+    lines.push(`By file (${t.files}): ${t.declared} declared · ${t.accepted} accepted · ${t.rejected} rejected${t.loadFailed > 0 ? ` · ${t.loadFailed} failed to load` : ''}${t.missing > 0 ? ` · ${t.missing} missing` : ''}${t.unresolvable > 0 ? ` · ${t.unresolvable} unresolvable reference(s)` : ''}`);
+    for (const f of report.files) {
+        lines.push(`  ${fileMark(f)} ${f.file}  ${f.kind}${f.packageName ? ` [${f.packageName}]` : ''}  ${fileSummary(f)}`);
+        for (const r of f.rejected)
+            lines.push(`      rejected      ${formatEntryRejection({ ...r, file: f.file })}`);
+        for (const g of f.unresolvableReferences) {
+            lines.push(`      unresolvable  ${g.sourceId} ${g.field} → ${g.kind} ${g.ids.map((id) => `'${id}'`).join(', ')} — ${g.reason === 'undeclarable-kind' ? 'no registry can ever hold this kind' : "this kind's registry is empty here"}`);
+        }
+    }
+    return lines.join('\n') + '\n';
+}
+/** The `## By file` markdown section. */
+export function renderContributionsByFileMarkdown(report) {
+    const lines = ['## By file', ''];
+    if (report.files.length === 0) {
+        lines.push('None.');
+        return lines.join('\n') + '\n';
+    }
+    lines.push('| File | Kind | Pack | Status | Declared | Accepted | Rejected | Unresolvable |');
+    lines.push('| --- | --- | --- | --- | --- | --- | --- | --- |');
+    for (const f of report.files) {
+        const u = f.unresolvableReferences.reduce((n, g) => n + g.ids.length, 0);
+        lines.push(`| \`${f.file}\` | ${f.kind} | ${f.packageName ?? ''} | ${f.status} | ${f.declared} | ${f.accepted} | ${f.rejected.length} | ${u} |`);
+    }
+    const detail = report.files.filter((f) => f.rejected.length > 0 || f.unresolvableReferences.length > 0);
+    if (detail.length > 0) {
+        lines.push('');
+        for (const f of detail) {
+            lines.push(`- \`${f.file}\``);
+            for (const r of f.rejected)
+                lines.push(`  - rejected: ${formatEntryRejection({ ...r, file: f.file })}`);
+            for (const g of f.unresolvableReferences) {
+                lines.push(`  - unresolvable: ${g.sourceId} ${g.field} → ${g.kind} ${g.ids.join(', ')} (${g.reason})`);
+            }
+        }
+    }
+    return lines.join('\n') + '\n';
+}

package/dist/convention-applicability.d.ts

@@ -0,0 +1,46 @@
+import { ConventionAppliesToFilter, type IConvention } from '@shrkcrft/plugin-api';
+import { ConventionFilterLevel } from './convention-filter-level.js';
+import type { IConventionApplicability } from './i-convention-applicability.js';
+import type { IConventionScope } from './i-convention-scope.js';
+import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
+/** Where each filter is decided — keyed by the enum, so a new filter without a level is a compile error. */
+export declare const CONVENTION_FILTER_LEVELS: Readonly<Record<ConventionAppliesToFilter, ConventionFilterLevel>>;
+/** The convention's declared values for `filter` — `[]` for an absent filter (or a non-list, which the loader refuses). */
+export declare function declaredAppliesTo(convention: IConvention, filter: ConventionAppliesToFilter): readonly string[];
+/**
+ * A file path as the per-file filters AND a rule's patterns read it:
+ * project-relative, `/`-separated, no leading `./`. `checkConventionsAgainstFiles`
+ * normalizes its file list through this once, so the scope test and every
+ * `filePattern` / `expectMatch` / `forbidMatch` regex see ONE spelling of a file
+ * (round 15 review: `--files ./src/a.ts` was covered by `fileGlobs: ['src/**']`
+ * here and then failed `filePattern: '^src/'` on the raw `./src/a.ts` — a false hit).
+ *
+ * The spelling is REALPATH-canonical (round 15 follow-up, F9): the file and the
+ * project root are both resolved through their symlinks before one is made
+ * relative to the other, so a symlinked absolute path (`/link/src/a.ts` with
+ * `/link → the project`, or macOS `/var/…` for a root at `/private/var/…`)
+ * behaves exactly like its target — it read `../link/src/a.ts`, which no
+ * `fileGlobs` selected, so the convention was silently not applicable. A path
+ * whose target lies OUTSIDE the project (an in-project symlink to a sibling
+ * checkout) keeps its lexical in-project spelling: that is where it is in scope.
+ */
+export declare function conventionFilePath(inspection: ISharkcraftInspection, file: string): string;
+/**
+ * Does `convention` apply here — to the workspace, and (given `file`) to that
+ * file? Without `file` only the workspace filters decide; the per-file ones
+ * are listed as `decided per file`. See the module doc for the table.
+ */
+export declare function conventionApplicability(convention: IConvention, inspection: ISharkcraftInspection, file?: string): IConventionApplicability;
+/**
+ * Which of `files` `convention` covers — per file through
+ * {@link conventionApplicability}, so `conventions check` and the rule-graph
+ * bridge (which both call this) cannot disagree.
+ *
+ * Not applicable when a workspace filter excludes it, or when `files` is
+ * non-empty and no file passes the per-file filters (the per-file reasons
+ * then count what each filter selected across the list). An EMPTY list keeps
+ * a workspace-applicable convention applicable over nothing — the caller's own
+ * empty-scope verdict decides that case.
+ */
+export declare function conventionScope(convention: IConvention, inspection: ISharkcraftInspection, files: readonly string[]): IConventionScope;
+//# sourceMappingURL=convention-applicability.d.ts.map

package/dist/convention-applicability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"convention-applicability.d.ts","sourceRoot":"","sources":["../src/convention-applicability.ts"],"names":[],"mappings":"AA8BA,OAAO,EAAE,yBAAyB,EAAE,KAAK,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnF,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAErE,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,iCAAiC,CAAC;AAEhF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAEvE,4GAA4G;AAC5G,eAAO,MAAM,wBAAwB,EAAE,QAAQ,CAAC,MAAM,CAAC,yBAAyB,EAAE,qBAAqB,CAAC,CAMtG,CAAC;AAWH,2HAA2H;AAC3H,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,WAAW,EAAE,MAAM,EAAE,yBAAyB,GAAG,SAAS,MAAM,EAAE,CAG/G;AAwCD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,qBAAqB,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAc1F;AAiED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,WAAW,EACvB,UAAU,EAAE,qBAAqB,EACjC,IAAI,CAAC,EAAE,MAAM,GACZ,wBAAwB,CAQ1B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,UAAU,EAAE,WAAW,EACvB,UAAU,EAAE,qBAAqB,EACjC,KAAK,EAAE,SAAS,MAAM,EAAE,GACvB,gBAAgB,CAkDlB"}

package/dist/convention-applicability.js

@@ -0,0 +1,247 @@
+/**
+ * THE convention applicability authority (round 15, 15.1).
+ *
+ * `IConventionAppliesTo` declares five filters; before this only `fileGlobs`
+ * was read — by two different matchers that disagreed (`conventions check`
+ * compiled `src/**\/*.ts` so it missed `src/a.ts` and ignored `!`; the
+ * rule-graph bridge dropped a convention with no `fileGlobs` that check
+ * enforced on every file). `profileIds`, `frameworks` and `languages` were
+ * validated, resolved by the doctor, and inert.
+ *
+ * Every surface now asks THIS module: `conventions check`, the rule-graph
+ * bridge, MCP `prepare_agent_task`, and the `conventions list / get / explain`
+ * display (which shows the answer and never hides an entry).
+ *
+ * Semantics — the pack-compatibility precedent (`pack-compatibility.ts`):
+ *   - within a filter, ANY listed value matches;
+ *   - EVERY declared filter must match;
+ *   - an absent or empty filter imposes no constraint.
+ *
+ *   | filter           | level     | matches when                                              |
+ *   |------------------|-----------|-----------------------------------------------------------|
+ *   | `profileIds`     | workspace | a listed id is in `inspection.workspace.profiles`         |
+ *   | `frameworks`     | workspace | a listed id is in `inspection.workspace.frameworks[].id`  |
+ *   | `languages`      | file      | the file's language (`fileLanguageOf`) is listed          |
+ *   | `fileGlobs`      | file      | `globListSelects(file, globs)` — `**` spans zero+ segments, `!` subtracts |
+ *   | `constructKinds` | reserved  | always (not evaluated; the loader warns)                  |
+ */
+import { realpathSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { globListSelects } from '@shrkcrft/boundaries';
+import { ConventionAppliesToFilter } from '@shrkcrft/plugin-api';
+import { ConventionFilterLevel } from "./convention-filter-level.js";
+import { fileLanguageOf } from "./file-languages.js";
+/** Where each filter is decided — keyed by the enum, so a new filter without a level is a compile error. */
+export const CONVENTION_FILTER_LEVELS = Object.freeze({
+    [ConventionAppliesToFilter.ProfileIds]: ConventionFilterLevel.Workspace,
+    [ConventionAppliesToFilter.Frameworks]: ConventionFilterLevel.Workspace,
+    [ConventionAppliesToFilter.Languages]: ConventionFilterLevel.File,
+    [ConventionAppliesToFilter.FileGlobs]: ConventionFilterLevel.File,
+    [ConventionAppliesToFilter.ConstructKinds]: ConventionFilterLevel.Reserved,
+});
+/** Reasons are listed workspace filters first, then per-file, then reserved. */
+const FILTER_ORDER = [
+    ConventionAppliesToFilter.ProfileIds,
+    ConventionAppliesToFilter.Frameworks,
+    ConventionAppliesToFilter.Languages,
+    ConventionAppliesToFilter.FileGlobs,
+    ConventionAppliesToFilter.ConstructKinds,
+];
+/** The convention's declared values for `filter` — `[]` for an absent filter (or a non-list, which the loader refuses). */
+export function declaredAppliesTo(convention, filter) {
+    const value = convention.appliesTo?.[filter];
+    return Array.isArray(value) ? value.filter((v) => typeof v === 'string') : [];
+}
+/** One realpath per distinct file per inspection — `conventionScope` judges every file once per per-file filter. */
+const SPELLINGS = new WeakMap();
+/**
+ * `abs` with every symlink resolved. A path that does not exist (a file a diff
+ * deleted, a path a test names) resolves through its nearest existing ancestor,
+ * so `/var/…/gone.ts` and `/private/var/…/gone.ts` still agree.
+ */
+function canonicalPath(abs) {
+    let head = abs;
+    const tail = [];
+    for (;;) {
+        try {
+            const real = realpathSync(head);
+            return tail.length > 0 ? nodePath.join(real, ...tail.reverse()) : real;
+        }
+        catch {
+            const parent = nodePath.dirname(head);
+            if (parent === head)
+                return abs;
+            tail.push(nodePath.basename(head));
+            head = parent;
+        }
+    }
+}
+/** The lexical spelling: project-relative for an absolute path, `/`-separated, no leading `./`. */
+function lexicalFilePath(projectRoot, file) {
+    let f = nodePath.isAbsolute(file) ? nodePath.relative(projectRoot, file) : file;
+    f = f.replace(/\\/g, '/');
+    while (f.startsWith('./'))
+        f = f.slice(2);
+    return f;
+}
+/**
+ * A file path as the per-file filters AND a rule's patterns read it:
+ * project-relative, `/`-separated, no leading `./`. `checkConventionsAgainstFiles`
+ * normalizes its file list through this once, so the scope test and every
+ * `filePattern` / `expectMatch` / `forbidMatch` regex see ONE spelling of a file
+ * (round 15 review: `--files ./src/a.ts` was covered by `fileGlobs: ['src/**']`
+ * here and then failed `filePattern: '^src/'` on the raw `./src/a.ts` — a false hit).
+ *
+ * The spelling is REALPATH-canonical (round 15 follow-up, F9): the file and the
+ * project root are both resolved through their symlinks before one is made
+ * relative to the other, so a symlinked absolute path (`/link/src/a.ts` with
+ * `/link → the project`, or macOS `/var/…` for a root at `/private/var/…`)
+ * behaves exactly like its target — it read `../link/src/a.ts`, which no
+ * `fileGlobs` selected, so the convention was silently not applicable. A path
+ * whose target lies OUTSIDE the project (an in-project symlink to a sibling
+ * checkout) keeps its lexical in-project spelling: that is where it is in scope.
+ */
+export function conventionFilePath(inspection, file) {
+    let cache = SPELLINGS.get(inspection);
+    if (!cache) {
+        cache = { realRoot: canonicalPath(nodePath.resolve(inspection.projectRoot)), files: new Map() };
+        SPELLINGS.set(inspection, cache);
+    }
+    const known = cache.files.get(file);
+    if (known !== undefined)
+        return known;
+    const real = canonicalPath(nodePath.resolve(inspection.projectRoot, file));
+    const rel = nodePath.relative(cache.realRoot, real);
+    const inside = rel.length > 0 && rel !== '..' && !rel.startsWith(`..${nodePath.sep}`) && !nodePath.isAbsolute(rel);
+    const spelled = inside ? rel.split(nodePath.sep).join('/') : lexicalFilePath(inspection.projectRoot, file);
+    cache.files.set(file, spelled);
+    return spelled;
+}
+function list(values) {
+    return `[${values.join(', ')}]`;
+}
+function reason(filter, declared, observed, matched, detail) {
+    return {
+        filter,
+        level: CONVENTION_FILTER_LEVELS[filter],
+        declared,
+        observed,
+        matched,
+        message: `appliesTo.${filter} ${list(declared)}: ${detail}`,
+    };
+}
+/** A workspace filter: any declared id among the detected ones. */
+function judgeWorkspace(filter, declared, detected, noun) {
+    const hit = declared.filter((d) => detected.includes(d));
+    if (hit.length > 0)
+        return reason(filter, declared, detected, true, `detected ${hit.join(', ')}`);
+    const seen = detected.length > 0 ? `detected: ${detected.join(', ')}` : `no ${noun} detected`;
+    return reason(filter, declared, detected, false, `none detected (${seen})`);
+}
+function judge(filter, declared, inspection, file) {
+    switch (filter) {
+        case ConventionAppliesToFilter.ProfileIds:
+            return judgeWorkspace(filter, declared, [...(inspection.workspace?.profiles ?? [])], 'profile');
+        case ConventionAppliesToFilter.Frameworks:
+            return judgeWorkspace(filter, declared, (inspection.workspace?.frameworks ?? []).map((f) => f.id), 'framework');
+        case ConventionAppliesToFilter.ConstructKinds:
+            return reason(filter, declared, [], true, 'reserved — not evaluated (the convention applies regardless)');
+        case ConventionAppliesToFilter.Languages: {
+            if (file === undefined)
+                return reason(filter, declared, [], true, 'decided per file');
+            const path = conventionFilePath(inspection, file);
+            const language = fileLanguageOf(path)?.id;
+            if (language === undefined)
+                return reason(filter, declared, [], false, `${path} has no known language`);
+            return reason(filter, declared, [language], declared.includes(language), `${path} is ${language}`);
+        }
+        case ConventionAppliesToFilter.FileGlobs: {
+            if (file === undefined)
+                return reason(filter, declared, [], true, 'decided per file');
+            const path = conventionFilePath(inspection, file);
+            const selected = globListSelects(path, declared);
+            return reason(filter, declared, [path], selected, `${selected ? 'selects' : 'does not select'} ${path}`);
+        }
+    }
+}
+/**
+ * Does `convention` apply here — to the workspace, and (given `file`) to that
+ * file? Without `file` only the workspace filters decide; the per-file ones
+ * are listed as `decided per file`. See the module doc for the table.
+ */
+export function conventionApplicability(convention, inspection, file) {
+    const reasons = [];
+    for (const filter of FILTER_ORDER) {
+        const declared = declaredAppliesTo(convention, filter);
+        if (declared.length === 0)
+            continue;
+        reasons.push(judge(filter, declared, inspection, file));
+    }
+    return { applicable: reasons.every((r) => r.matched), reasons };
+}
+/**
+ * Which of `files` `convention` covers — per file through
+ * {@link conventionApplicability}, so `conventions check` and the rule-graph
+ * bridge (which both call this) cannot disagree.
+ *
+ * Not applicable when a workspace filter excludes it, or when `files` is
+ * non-empty and no file passes the per-file filters (the per-file reasons
+ * then count what each filter selected across the list). An EMPTY list keeps
+ * a workspace-applicable convention applicable over nothing — the caller's own
+ * empty-scope verdict decides that case.
+ */
+export function conventionScope(convention, inspection, files) {
+    const conventionId = convention.id;
+    const workspace = conventionApplicability(convention, inspection);
+    if (!workspace.applicable)
+        return { conventionId, applicable: false, files: [], reasons: workspace.reasons };
+    const perFile = FILTER_ORDER.filter((f) => CONVENTION_FILTER_LEVELS[f] === ConventionFilterLevel.File && declaredAppliesTo(convention, f).length > 0);
+    if (perFile.length === 0 || files.length === 0) {
+        return { conventionId, applicable: true, files: [...files], reasons: workspace.reasons };
+    }
+    const covered = [];
+    const admitted = new Map();
+    const seen = new Map();
+    for (const file of files) {
+        const verdict = conventionApplicability(convention, inspection, file);
+        if (verdict.applicable)
+            covered.push(file);
+        for (const r of verdict.reasons) {
+            if (r.level !== ConventionFilterLevel.File)
+                continue;
+            if (r.matched)
+                admitted.set(r.filter, (admitted.get(r.filter) ?? 0) + 1);
+            if (r.filter === ConventionAppliesToFilter.Languages) {
+                const s = seen.get(r.filter) ?? new Set();
+                for (const o of r.observed)
+                    s.add(o);
+                seen.set(r.filter, s);
+            }
+        }
+    }
+    if (covered.length > 0)
+        return { conventionId, applicable: true, files: covered, reasons: workspace.reasons };
+    // No file passed: say, per declared per-file filter, what it selected across
+    // the list. A filter that admitted NO file excluded the convention (matched:
+    // false); one that admitted some did not (matched: true) — unless EVERY
+    // per-file filter admitted some file and none passed them all: then the
+    // intersection excluded it, and each filter says so. So the excluding reasons
+    // are never empty and never name a filter that excluded nothing (round 15
+    // review: `fileGlobs` read "selects 1 of 1 file(s)" as an excluding reason).
+    const n = files.length;
+    const intersectionOnly = perFile.every((filter) => (admitted.get(filter) ?? 0) > 0);
+    const together = intersectionOnly ? ' — but no file in scope passes every per-file filter together' : '';
+    const aggregated = perFile.map((filter) => {
+        const declared = declaredAppliesTo(convention, filter);
+        const count = admitted.get(filter) ?? 0;
+        const matched = count > 0 && !intersectionOnly;
+        if (filter === ConventionAppliesToFilter.Languages) {
+            const langs = [...(seen.get(filter) ?? new Set())].sort();
+            const detail = `${count} of ${n} file(s) in scope ${count === 1 ? 'is' : 'are'} a listed language (seen: ${langs.length > 0 ? langs.join(', ') : 'none known'})${together}`;
+            return reason(filter, declared, langs, matched, detail);
+        }
+        return reason(filter, declared, [], matched, `selects ${count} of ${n} file(s) in scope${together}`);
+    });
+    const workspaceReasons = workspace.reasons.filter((r) => r.level !== ConventionFilterLevel.File);
+    return { conventionId, applicable: false, files: [], reasons: [...workspaceReasons, ...aggregated] };
+}

package/dist/convention-filter-level.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Where an `appliesTo` filter is decided (round 15, 15.1) — see
+ * `conventionApplicability`.
+ */
+export declare enum ConventionFilterLevel {
+    /** Decided once per workspace, from what the workspace detectors saw (`profileIds`, `frameworks`). */
+    Workspace = "workspace",
+    /** Decided per file (`fileGlobs`, `languages`). */
+    File = "file",
+    /** Loaded and never evaluated — the convention applies regardless (`constructKinds`). */
+    Reserved = "reserved"
+}
+//# sourceMappingURL=convention-filter-level.d.ts.map

package/dist/convention-filter-level.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"convention-filter-level.d.ts","sourceRoot":"","sources":["../src/convention-filter-level.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,oBAAY,qBAAqB;IAC/B,sGAAsG;IACtG,SAAS,cAAc;IACvB,mDAAmD;IACnD,IAAI,SAAS;IACb,yFAAyF;IACzF,QAAQ,aAAa;CACtB"}

package/dist/convention-filter-level.js

@@ -0,0 +1,13 @@
+/**
+ * Where an `appliesTo` filter is decided (round 15, 15.1) — see
+ * `conventionApplicability`.
+ */
+export var ConventionFilterLevel;
+(function (ConventionFilterLevel) {
+    /** Decided once per workspace, from what the workspace detectors saw (`profileIds`, `frameworks`). */
+    ConventionFilterLevel["Workspace"] = "workspace";
+    /** Decided per file (`fileGlobs`, `languages`). */
+    ConventionFilterLevel["File"] = "file";
+    /** Loaded and never evaluated — the convention applies regardless (`constructKinds`). */
+    ConventionFilterLevel["Reserved"] = "reserved";
+})(ConventionFilterLevel || (ConventionFilterLevel = {}));

package/dist/convention-registry.d.ts

@@ -1,5 +1,7 @@
-import { type IConvention } from '@shrkcrft/plugin-api';
+import { ConventionSeverity, type IConvention } from '@shrkcrft/plugin-api';
 import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
+import type { INotApplicableConvention } from './i-not-applicable-convention.js';
+import { type IRejectedEntry } from '@shrkcrft/core';
 export declare const CONVENTION_REGISTRY_SCHEMA = "sharkcraft.convention-registry/v1";
 export declare enum ConventionSource {
     Local = "local",
@@ -13,15 +15,36 @@ export interface IConventionEntry {
     readonly sourceFile: string;
 }
 export interface IConventionDoctorIssue {
-    readonly severity: 'info' | 'warning' | 'error';
+    readonly severity: ConventionSeverity;
     readonly code: string;
     readonly message: string;
     readonly conventionId?: string;
     readonly source?: string;
 }
+/** The convention FILES a load discovered, and the ones it could not read — the doctor's coverage. */
+export interface IConventionFileScan {
+    /** Every convention file the load tried (local defaults, `conventionFiles`, pack `conventionFiles`). */
+    readonly discovered: number;
+    /** Discovered but never read (missing, or failed to import) — `file — reason`, project-relative. */
+    readonly unread: readonly string[];
+}
+/**
+ * THE convention acceptance predicate (round 12, 12.1): every error of
+ * `validateConvention`, `<field>: <message>` — `[]` means accepted. The
+ * loader and `packs test --load` refuse exactly the same entries.
+ */
+export declare function conventionRejectionReasons(raw: unknown): readonly string[];
 export declare function loadConventions(inspection: ISharkcraftInspection): Promise<{
     entries: readonly IConventionEntry[];
     issues: readonly IConventionDoctorIssue[];
+    files: IConventionFileScan;
+    /**
+     * Every declared convention the loader refused (round 12, 12.1) — invalid
+     * or a duplicate id — with its position and every reason. The `issues`
+     * above still carry the per-field `invalid-convention` lines `conventions
+     * doctor` prints; this is the record THE rejection channel lifts.
+     */
+    rejected: readonly IRejectedEntry[];
 }>;
 export declare function listConventions(inspection: ISharkcraftInspection): Promise<readonly IConventionEntry[]>;
 export declare function findConvention(inspection: ISharkcraftInspection, id: string): Promise<IConventionEntry | null>;
@@ -31,7 +54,7 @@ export interface IConventionCheckHit {
     readonly ruleId: string;
     readonly file: string;
     readonly line?: number;
-    readonly severity: 'info' | 'warning' | 'error';
+    readonly severity: ConventionSeverity;
     readonly message: string;
 }
 export interface IConventionCheckReport {
@@ -39,6 +62,30 @@ export interface IConventionCheckReport {
     readonly filesScanned: number;
     readonly hits: readonly IConventionCheckHit[];
     readonly verdict: 'clean' | 'has-violations';
+    /**
+     * Conventions that do not apply here (round 15, 15.1) — never evaluated, each
+     * with the `appliesTo` filters that excluded it. `conventions check` prints
+     * every one and accepts it explicitly (`acceptedBy: 'appliesTo'`).
+     */
+    readonly notApplicable: readonly INotApplicableConvention[];
+    /** How many files in scope each APPLICABLE convention covers, by id (round 15). */
+    readonly filesInScope: Readonly<Record<string, number>>;
 }
-export declare function checkConventionsAgainstFiles(inspection: ISharkcraftInspection, files: readonly string[]): Promise<IConventionCheckReport>;
+/**
+ * Run the loaded conventions against `files`. Which files a convention covers
+ * is `conventionScope` — THE applicability authority (round 15), the same one
+ * the rule-graph bridge reads — so every `appliesTo` filter scopes, `**`
+ * spans zero or more segments, and a `!` glob subtracts (a private matcher
+ * here missed `src/a.ts` under `src/**\/*.ts` and ignored `!`). A convention
+ * that does not apply is never evaluated and is reported in `notApplicable`.
+ *
+ * Per covered file, each rule: `filePattern` and `expectMatch` must match the
+ * path (a miss is a hit), `forbidMatch` must not (a match is a hit).
+ *
+ * Every file is read in ONE spelling — `conventionFilePath` (project-relative,
+ * `/`-separated, no `./`), the one the scope test reads — so a rule pattern
+ * never tests a spelling the glob did not, and a hit names that path (round 15
+ * review: `./src/a.ts` was covered by `src/**` and then failed `^src/`).
+ */
+export declare function checkConventionsAgainstFiles(inspection: ISharkcraftInspection, inputFiles: readonly string[]): Promise<IConventionCheckReport>;
 //# sourceMappingURL=convention-registry.d.ts.map