@shrkcrft/inspector 0.1.0-alpha.2

package/dist/construct-inference.js

@@ -0,0 +1,391 @@
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { scanImports } from '@shrkcrft/boundaries';
+import { listConstructs } from "./construct-registry.js";
+export const CONSTRUCT_INFERENCE_SCHEMA = 'sharkcraft.construct-inference/v1';
+export var InferredConstructConfidence;
+(function (InferredConstructConfidence) {
+    InferredConstructConfidence["High"] = "high";
+    InferredConstructConfidence["Medium"] = "medium";
+    InferredConstructConfidence["Low"] = "low";
+})(InferredConstructConfidence || (InferredConstructConfidence = {}));
+const FOLDER_HINTS = [
+    { match: /(^|\/)services?($|\/)/, type: 'service', title: (_r, n) => `${n} service`, confidence: InferredConstructConfidence.High },
+    { match: /(^|\/)plugins?($|\/)/, type: 'plugin', title: (_r, n) => `${n} plugin`, confidence: InferredConstructConfidence.High },
+    { match: /(^|\/)policies?($|\/)/, type: 'policy', title: (_r, n) => `${n} policy`, confidence: InferredConstructConfidence.High },
+    { match: /(^|\/)capabilities?($|\/)/, type: 'capability', title: (_r, n) => `${n} capability`, confidence: InferredConstructConfidence.High },
+    { match: /(^|\/)adapters?($|\/)/, type: 'adapter', title: (_r, n) => `${n} adapter`, confidence: InferredConstructConfidence.Medium },
+    { match: /(^|\/)(routes?|controllers?)($|\/)/, type: 'route', title: (_r, n) => `${n} route`, confidence: InferredConstructConfidence.Medium },
+    { match: /(^|\/)components?($|\/)/, type: 'component', title: (_r, n) => `${n} component`, confidence: InferredConstructConfidence.Medium },
+    { match: /(^|\/)features?($|\/)/, type: 'feature', title: (_r, n) => `${n} feature`, confidence: InferredConstructConfidence.Medium },
+    { match: /(^|\/)modules?($|\/)/, type: 'module', title: (_r, n) => `${n} module`, confidence: InferredConstructConfidence.Low },
+];
+const FILE_SUFFIX_HINTS = [
+    { suffix: /\.service\.(ts|tsx|js)$/, type: 'service', title: (n) => `${n} service`, confidence: InferredConstructConfidence.High },
+    { suffix: /\.plugin\.(ts|tsx|js)$/, type: 'plugin', title: (n) => `${n} plugin`, confidence: InferredConstructConfidence.High },
+    { suffix: /\.policy\.(ts|tsx|js)$/, type: 'policy', title: (n) => `${n} policy`, confidence: InferredConstructConfidence.High },
+    { suffix: /\.controller\.(ts|tsx|js)$/, type: 'controller', title: (n) => `${n} controller`, confidence: InferredConstructConfidence.Medium },
+    { suffix: /\.adapter\.(ts|tsx|js)$/, type: 'adapter', title: (n) => `${n} adapter`, confidence: InferredConstructConfidence.Medium },
+];
+const IGNORE_DIRS = new Set([
+    'node_modules',
+    '.git',
+    '.sharkcraft',
+    'dist',
+    'build',
+    '.cache',
+    '.turbo',
+    '.nx',
+    '.next',
+    'coverage',
+]);
+function walk(root, current = '') {
+    const out = [];
+    const dir = current ? nodePath.join(root, current) : root;
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return out;
+    }
+    for (const name of entries) {
+        if (name.startsWith('.') && name !== '.github')
+            continue;
+        if (IGNORE_DIRS.has(name))
+            continue;
+        const rel = current ? `${current}/${name}` : name;
+        let stat;
+        try {
+            stat = statSync(nodePath.join(root, rel));
+        }
+        catch {
+            continue;
+        }
+        if (stat.isDirectory())
+            out.push(...walk(root, rel));
+        else if (stat.isFile())
+            out.push(rel);
+    }
+    return out;
+}
+function basenameNoExt(file) {
+    const base = file.split('/').pop() ?? file;
+    const dotIdx = base.indexOf('.');
+    return dotIdx >= 0 ? base.slice(0, dotIdx) : base;
+}
+function kebabize(s) {
+    return s
+        .replace(/([a-z])([A-Z])/g, '$1-$2')
+        .replace(/[_\s]+/g, '-')
+        .toLowerCase();
+}
+function newBuilder(type, baseId, title, confidence) {
+    return {
+        type,
+        baseId,
+        title,
+        files: new Set(),
+        publicApi: new Set(),
+        evidence: new Set(),
+        events: new Set(),
+        tokens: new Set(),
+        confidence,
+    };
+}
+function safeId(s) {
+    return s.replace(/[^a-z0-9-]+/gi, '-').replace(/-+/g, '-').replace(/^-|-$/g, '').toLowerCase();
+}
+/** Extract simple string-constant style events/tokens from a file. */
+function scanFacets(absPath) {
+    const events = [];
+    const tokens = [];
+    let text;
+    try {
+        text = readFileSync(absPath, 'utf8');
+    }
+    catch {
+        return { events, tokens };
+    }
+    // Event-like: 'foo.bar' / "foo.bar" with a dot in the middle.
+    const evRe = /['"`]([a-z0-9_-]+(?:\.[a-z0-9_-]+){1,3})['"`]/gi;
+    let m;
+    while ((m = evRe.exec(text)) !== null) {
+        const val = m[1];
+        if (/^[a-z0-9_-]+\.[a-z0-9_-]+/i.test(val) && val.length < 60) {
+            events.push(val);
+        }
+    }
+    // Token-like: UPPER_SNAKE_CASE identifiers exported or referenced.
+    const tokRe = /\b([A-Z][A-Z0-9_]{3,})\b/g;
+    while ((m = tokRe.exec(text)) !== null) {
+        tokens.push(m[1]);
+    }
+    return {
+        events: [...new Set(events)].slice(0, 6),
+        tokens: [...new Set(tokens)].slice(0, 6),
+    };
+}
+function buildPublicApi(files) {
+    const out = [];
+    for (const f of files) {
+        const base = f.split('/').pop() ?? '';
+        if (base === 'index.ts' || base === 'index.tsx' || base === 'index.js') {
+            out.push(f);
+        }
+        if (/\.public\.(ts|tsx|js)$/.test(base))
+            out.push(f);
+    }
+    return [...new Set(out)];
+}
+function relatedAssets(inspection, files) {
+    const templates = new Set();
+    const pipelines = new Set();
+    const paths = new Set();
+    // Templates with targetPath overlap.
+    for (const t of inspection.templateRegistry.list()) {
+        const tp = t.targetPath;
+        const pathLike = typeof tp === 'string' ? tp : '';
+        if (!pathLike)
+            continue;
+        if (files.some((f) => f.includes(pathLike) || pathLike.includes(f.split('/').pop() ?? ''))) {
+            templates.add(t.id);
+        }
+    }
+    // Pipelines that mention these files (heuristic).
+    for (const p of inspection.pipelineRegistry.list()) {
+        const blob = JSON.stringify(p.steps ?? []).toLowerCase();
+        if (files.some((f) => blob.includes(f.toLowerCase())))
+            pipelines.add(p.id);
+    }
+    // Path conventions covering folders.
+    for (const p of inspection.pathService.list()) {
+        const meta = (p.metadata ?? {});
+        const segment = (meta.path ?? '').replace(/\*+/g, '');
+        if (!segment)
+            continue;
+        if (files.some((f) => f.includes(segment)))
+            paths.add(p.id);
+    }
+    return {
+        templates: [...templates].sort(),
+        pipelines: [...pipelines].sort(),
+        pathConventions: [...paths].sort(),
+    };
+}
+function buildDraft(c) {
+    const lines = [];
+    lines.push(`defineConstruct({`);
+    lines.push(`  id: '${c.id}',`);
+    lines.push(`  type: '${c.type}',`);
+    lines.push(`  title: '${c.title.replace(/'/g, "\\'")}',`);
+    lines.push(`  description: 'Inferred (${c.confidence} confidence). Replace with a real description.',`);
+    if (c.files.length) {
+        lines.push('  files: [');
+        for (const f of c.files.slice(0, 12))
+            lines.push(`    '${f}',`);
+        lines.push('  ],');
+    }
+    if (c.publicApi.length) {
+        lines.push('  publicApi: [');
+        for (const a of c.publicApi.slice(0, 8))
+            lines.push(`    '${a}',`);
+        lines.push('  ],');
+    }
+    if (c.events?.length) {
+        lines.push(`  events: [${c.events.map((e) => `'${e}'`).join(', ')}],`);
+    }
+    if (c.tokens?.length) {
+        lines.push(`  tokens: [${c.tokens.map((e) => `'${e}'`).join(', ')}],`);
+    }
+    if (c.relatedTemplates?.length) {
+        lines.push(`  relatedTemplates: [${c.relatedTemplates.map((e) => `'${e}'`).join(', ')}],`);
+    }
+    if (c.relatedPipelines?.length) {
+        lines.push(`  relatedPipelines: [${c.relatedPipelines.map((e) => `'${e}'`).join(', ')}],`);
+    }
+    if (c.relatedPathConventions?.length) {
+        lines.push(`  relatedPathConventions: [${c.relatedPathConventions.map((e) => `'${e}'`).join(', ')}],`);
+    }
+    lines.push(`}),`);
+    return lines.join('\n');
+}
+function confidenceRank(c) {
+    if (c === InferredConstructConfidence.High)
+        return 3;
+    if (c === InferredConstructConfidence.Medium)
+        return 2;
+    return 1;
+}
+export async function inferConstructs(inspection, input = {}) {
+    const warnings = [];
+    const builders = new Map();
+    const projectRoot = inspection.projectRoot;
+    const allFiles = existsSync(projectRoot) ? walk(projectRoot) : [];
+    // Pass 1: folder + filename hints.
+    for (const file of allFiles) {
+        if (!/\.(ts|tsx|js|jsx)$/.test(file))
+            continue;
+        if (file.includes('.spec.') || file.includes('.test.') || file.includes('__tests__/')) {
+            continue;
+        }
+        // Filename suffix hints (e.g. user.service.ts).
+        const base = file.split('/').pop() ?? '';
+        let matched = false;
+        for (const fh of FILE_SUFFIX_HINTS) {
+            if (fh.suffix.test(base)) {
+                const name = base.replace(fh.suffix, '');
+                const id = `${fh.type}.${safeId(kebabize(name))}`;
+                let b = builders.get(id);
+                if (!b) {
+                    b = newBuilder(fh.type, id, fh.title(name), fh.confidence);
+                    builders.set(id, b);
+                }
+                b.files.add(file);
+                b.evidence.add(`filename matches /${fh.suffix.source}/`);
+                matched = true;
+            }
+        }
+        if (matched)
+            continue;
+        // Folder hints.
+        for (const fh of FOLDER_HINTS) {
+            if (!fh.match.test(file))
+                continue;
+            // Group by parent folder under the matched segment.
+            const segments = file.split('/');
+            const matchIdx = segments.findIndex((s) => fh.match.test('/' + s + '/'));
+            if (matchIdx < 0 || matchIdx + 1 >= segments.length)
+                continue;
+            const next = segments[matchIdx + 1];
+            // If `next` is also the filename, use the bare name; otherwise treat the folder as the group.
+            const group = next.includes('.') ? basenameNoExt(next) : next;
+            const id = `${fh.type}.${safeId(kebabize(group))}`;
+            let b = builders.get(id);
+            if (!b) {
+                b = newBuilder(fh.type, id, fh.title(projectRoot, group), fh.confidence);
+                builders.set(id, b);
+            }
+            b.files.add(file);
+            b.evidence.add(`folder matches ${fh.match.source}`);
+            break;
+        }
+    }
+    // Pass 2: aggregate by import-graph clusters around publicApi candidates.
+    try {
+        const scan = scanImports({ projectRoot });
+        const importsByTarget = new Map();
+        for (const e of scan.edges) {
+            if (e.kind !== 'internal')
+                continue;
+            if (!e.importSpecifier.startsWith('.'))
+                continue;
+            const target = nodePath.posix.normalize(nodePath.posix.join(nodePath.posix.dirname(e.from), e.importSpecifier));
+            const set = importsByTarget.get(target) ?? new Set();
+            set.add(e.from);
+            importsByTarget.set(target, set);
+        }
+        for (const b of builders.values()) {
+            // Add files that import any of the builder's files as "publicApi" hints.
+            for (const f of [...b.files]) {
+                const target = f.replace(/\.(ts|tsx|js|jsx)$/, '');
+                for (const t of [target, target + '.ts', target + '.tsx', target + '/index.ts']) {
+                    const importers = importsByTarget.get(t);
+                    if (!importers)
+                        continue;
+                    if (importers.size > 0) {
+                        b.publicApi.add(f);
+                        b.evidence.add(`imported by ${importers.size} file(s)`);
+                    }
+                }
+            }
+        }
+    }
+    catch {
+        warnings.push('Import graph scan failed; some confidence hints unavailable.');
+    }
+    // Pass 3: facet detection (events/tokens).
+    for (const b of builders.values()) {
+        for (const f of [...b.files].slice(0, 8)) {
+            const abs = nodePath.join(projectRoot, f);
+            const facets = scanFacets(abs);
+            for (const e of facets.events)
+                b.events.add(e);
+            for (const t of facets.tokens)
+                b.tokens.add(t);
+        }
+    }
+    // Drop builders without files.
+    const existingIds = new Set(listConstructs(inspection).map((c) => c.id));
+    const candidatesAll = [];
+    for (const b of builders.values()) {
+        if (b.files.size === 0)
+            continue;
+        if (existingIds.has(b.baseId)) {
+            // Skip if construct is already defined locally; still allow drafts via --include-existing.
+            continue;
+        }
+        const relAssets = relatedAssets(inspection, [...b.files]);
+        const publicApi = b.publicApi.size > 0 ? [...b.publicApi] : buildPublicApi([...b.files]);
+        const c = {
+            id: b.baseId,
+            type: b.type,
+            title: b.title,
+            confidence: b.confidence,
+            evidence: [...b.evidence].sort(),
+            files: [...b.files].sort(),
+            publicApi: publicApi.sort(),
+            events: [...b.events].slice(0, 6),
+            tokens: [...b.tokens].slice(0, 6),
+            ...(relAssets.templates.length ? { relatedTemplates: relAssets.templates } : {}),
+            ...(relAssets.pipelines.length ? { relatedPipelines: relAssets.pipelines } : {}),
+            ...(relAssets.pathConventions.length
+                ? { relatedPathConventions: relAssets.pathConventions }
+                : {}),
+            draft: '',
+        };
+        c.draft = buildDraft(c);
+        candidatesAll.push(c);
+    }
+    // Sort by confidence desc then file count desc.
+    candidatesAll.sort((a, b) => confidenceRank(b.confidence) - confidenceRank(a.confidence) ||
+        b.files.length - a.files.length ||
+        a.id.localeCompare(b.id));
+    let candidates = candidatesAll;
+    if (input.type)
+        candidates = candidates.filter((c) => c.type === input.type);
+    if (input.minConfidence) {
+        const min = confidenceRank(input.minConfidence);
+        candidates = candidates.filter((c) => confidenceRank(c.confidence) >= min);
+    }
+    if (input.limit && input.limit > 0) {
+        candidates = candidates.slice(0, input.limit);
+    }
+    return {
+        schema: CONSTRUCT_INFERENCE_SCHEMA,
+        generatedAt: new Date().toISOString(),
+        projectRoot,
+        candidates,
+        warnings,
+    };
+}
+export function renderConstructDraftsModule(result) {
+    const lines = [];
+    lines.push("/**");
+    lines.push(" * Inferred SharkCraft construct drafts.");
+    lines.push(" *");
+    lines.push(" * This file is written by `shrk constructs infer --write-drafts`.");
+    lines.push(" * Review carefully and copy the bits you want into `sharkcraft/constructs.ts`.");
+    lines.push(" * SharkCraft does NOT load this file automatically.");
+    lines.push(` * Generated: ${result.generatedAt}`);
+    lines.push(" */");
+    lines.push("import { defineConstruct } from '@shrkcrft/plugin-api';");
+    lines.push('');
+    lines.push('export default [');
+    for (const c of result.candidates) {
+        for (const line of c.draft.split('\n'))
+            lines.push('  ' + line);
+    }
+    lines.push('];');
+    return lines.join('\n') + '\n';
+}

package/dist/construct-registry.d.ts

@@ -0,0 +1,32 @@
+import type { IConstructFacetInput, IConstructFacetValue, IConstructInput } from '@shrkcrft/plugin-api';
+import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
+export declare const CONSTRUCT_REGISTRY_SCHEMA = "sharkcraft.construct-registry/v1";
+export interface IConstruct extends IConstructInput {
+    source: 'local' | 'pack';
+    packageName?: string;
+    sourceFile?: string;
+}
+export interface IConstructFacet extends IConstructFacetInput {
+}
+export declare function loadConstructs(inspection: ISharkcraftInspection): Promise<readonly IConstruct[]>;
+/** Synchronous accessor — falls back to a snapshot cached from the last
+ *  async load. Used by search-index which needs to be sync-friendly. */
+export declare function listConstructs(inspection: ISharkcraftInspection): readonly IConstruct[];
+/** Pre-warm the cache so subsequent sync reads see a populated list. */
+export declare function warmConstructCache(inspection: ISharkcraftInspection): Promise<void>;
+export interface IConstructTrace {
+    construct: IConstruct;
+    files: readonly string[];
+    publicApi: readonly string[];
+    events: readonly string[];
+    tokens: readonly string[];
+    commands: readonly string[];
+    relatedKnowledge: readonly string[];
+    relatedRules: readonly string[];
+    relatedTemplates: readonly string[];
+    relatedPipelines: readonly string[];
+    facets: Record<string, readonly IConstructFacetValue[]>;
+    warnings: readonly string[];
+}
+export declare function traceConstruct(construct: IConstruct): IConstructTrace;
+//# sourceMappingURL=construct-registry.d.ts.map

package/dist/construct-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"construct-registry.d.ts","sourceRoot":"","sources":["../src/construct-registry.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,oBAAoB,EACpB,oBAAoB,EACpB,eAAe,EAChB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAEvE,eAAO,MAAM,yBAAyB,qCAAqC,CAAC;AAE5E,MAAM,WAAW,UAAW,SAAQ,eAAe;IACjD,MAAM,EAAE,OAAO,GAAG,MAAM,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,eAAgB,SAAQ,oBAAoB;CAAG;AA+DhE,wBAAsB,cAAc,CAClC,UAAU,EAAE,qBAAqB,GAChC,OAAO,CAAC,SAAS,UAAU,EAAE,CAAC,CAwFhC;AAED;wEACwE;AACxE,wBAAgB,cAAc,CAAC,UAAU,EAAE,qBAAqB,GAAG,SAAS,UAAU,EAAE,CAGvF;AAED,wEAAwE;AACxE,wBAAsB,kBAAkB,CAAC,UAAU,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAEzF;AAED,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,UAAU,CAAC;IACtB,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7B,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,oBAAoB,EAAE,CAAC,CAAC;IACxD,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B;AAED,wBAAgB,cAAc,CAAC,SAAS,EAAE,UAAU,GAAG,eAAe,CAmBrE"}

package/dist/construct-registry.js

@@ -0,0 +1,198 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { existsSync, readFileSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { pathToFileURL } from 'node:url';
+export const CONSTRUCT_REGISTRY_SCHEMA = 'sharkcraft.construct-registry/v1';
+const CACHE = new Map();
+function readJsonOrEmpty(file) {
+    if (!existsSync(file))
+        return null;
+    try {
+        return JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+async function importDefault(file) {
+    const mod = (await import(__rewriteRelativeImportExtension(pathToFileURL(file).href)));
+    const def = mod.default;
+    if (Array.isArray(def))
+        return def;
+    if (def && typeof def === 'object')
+        return [def];
+    if (Array.isArray(mod.constructs))
+        return mod.constructs;
+    return [];
+}
+function localConstructFiles(inspection) {
+    const out = [];
+    const dir = inspection.sharkcraftDir;
+    if (!dir)
+        return [];
+    const defaults = ['constructs.ts', 'constructs.js', 'constructs/index.ts'];
+    for (const f of defaults) {
+        const full = nodePath.join(dir, f);
+        if (existsSync(full))
+            out.push(full);
+    }
+    const cfg = inspection.config;
+    if (cfg?.constructFiles) {
+        for (const rel of cfg.constructFiles)
+            out.push(nodePath.join(dir, rel));
+    }
+    return out;
+}
+function localFacetFiles(inspection) {
+    const out = [];
+    const dir = inspection.sharkcraftDir;
+    if (!dir)
+        return [];
+    const defaults = ['construct-facets.ts', 'construct-facets/index.ts'];
+    for (const f of defaults) {
+        const full = nodePath.join(dir, f);
+        if (existsSync(full))
+            out.push(full);
+    }
+    const cfg = inspection.config;
+    if (cfg?.constructFacetFiles) {
+        for (const rel of cfg.constructFacetFiles)
+            out.push(nodePath.join(dir, rel));
+    }
+    return out;
+}
+export async function loadConstructs(inspection) {
+    const cacheKey = `${inspection.projectRoot}:${inspection.packs.validPacks
+        .map((p) => p.packageName + '@' + p.packageVersion)
+        .join(',')}`;
+    const cached = CACHE.get(inspection.projectRoot);
+    if (cached && cached.cacheKey === cacheKey)
+        return cached.list;
+    const out = [];
+    // Local definitions.
+    for (const file of localConstructFiles(inspection)) {
+        try {
+            const list = await importDefault(file);
+            for (const c of list) {
+                if (!c?.id)
+                    continue;
+                const entry = { ...c, source: 'local' };
+                entry.sourceFile = nodePath.relative(inspection.projectRoot, file);
+                out.push(entry);
+            }
+        }
+        catch {
+            /* ignore — packs are best-effort */
+        }
+    }
+    // Standalone facet files (folded into matching constructs).
+    const looseFacets = [];
+    for (const file of localFacetFiles(inspection)) {
+        try {
+            const list = await importDefault(file);
+            for (const f of list) {
+                looseFacets.push(f);
+            }
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    // Pack contributions.
+    for (const pack of inspection.packs.validPacks ?? []) {
+        const contributions = (pack.manifest?.contributions ?? {});
+        const packRoot = pack.packageRoot;
+        if (!packRoot)
+            continue;
+        for (const rel of contributions.constructFiles ?? []) {
+            const file = nodePath.resolve(packRoot, rel);
+            if (!existsSync(file))
+                continue;
+            try {
+                const list = await importDefault(file);
+                for (const c of list) {
+                    if (!c?.id)
+                        continue;
+                    out.push({
+                        ...c,
+                        source: 'pack',
+                        packageName: pack.packageName,
+                        sourceFile: rel,
+                    });
+                }
+            }
+            catch {
+                /* ignore */
+            }
+        }
+        for (const rel of contributions.constructFacetFiles ?? []) {
+            const file = nodePath.resolve(packRoot, rel);
+            if (!existsSync(file))
+                continue;
+            try {
+                const list = await importDefault(file);
+                for (const f of list)
+                    looseFacets.push(f);
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    }
+    // Fold loose facets into their target construct.
+    for (const f of looseFacets) {
+        const target = out.find((c) => c.id === f.constructId);
+        if (!target)
+            continue;
+        const facets = (target.facets ?? {});
+        const list = facets[f.kind] ?? [];
+        list.push({
+            id: f.id,
+            value: f.value,
+            ...(f.description ? { description: f.description } : {}),
+            ...(f.source ? { source: f.source } : {}),
+        });
+        facets[f.kind] = list;
+        target.facets = facets;
+    }
+    CACHE.set(inspection.projectRoot, { cacheKey, list: out });
+    return out;
+}
+/** Synchronous accessor — falls back to a snapshot cached from the last
+ *  async load. Used by search-index which needs to be sync-friendly. */
+export function listConstructs(inspection) {
+    const cached = CACHE.get(inspection.projectRoot);
+    return cached?.list ?? [];
+}
+/** Pre-warm the cache so subsequent sync reads see a populated list. */
+export async function warmConstructCache(inspection) {
+    await loadConstructs(inspection);
+}
+export function traceConstruct(construct) {
+    const warnings = [];
+    if ((construct.publicApi ?? []).length === 0) {
+        warnings.push('No publicApi entries declared — `shrk constructs api` will be empty.');
+    }
+    return {
+        construct,
+        files: construct.files ?? [],
+        publicApi: construct.publicApi ?? [],
+        events: construct.events ?? [],
+        tokens: construct.tokens ?? [],
+        commands: construct.commands ?? [],
+        relatedKnowledge: construct.relatedKnowledge ?? [],
+        relatedRules: construct.relatedRules ?? [],
+        relatedTemplates: construct.relatedTemplates ?? [],
+        relatedPipelines: construct.relatedPipelines ?? [],
+        facets: (construct.facets ?? {}),
+        warnings,
+    };
+}
+void readJsonOrEmpty;

package/dist/contract-file-rule.d.ts

@@ -0,0 +1,37 @@
+/**
+ * `IContractFileRule` lets contracts express precise scope: glob,
+ * path-prefix, exact, contains. The legacy `forbiddenFiles: string[]`
+ * field is kept and treated as `kind: 'contains'` for back-compat.
+ */
+export declare enum ContractFileRuleKind {
+    Glob = "glob",
+    PathPrefix = "path-prefix",
+    Exact = "exact",
+    Contains = "contains"
+}
+export declare enum ContractFileRuleSeverity {
+    Error = "error",
+    Warning = "warning"
+}
+export interface IContractFileRule {
+    pattern: string;
+    kind: ContractFileRuleKind;
+    reason?: string;
+    severity?: ContractFileRuleSeverity;
+}
+/** Pure matcher — returns true when `file` is covered by `rule`. */
+export declare function matchContractFileRule(rule: IContractFileRule, file: string): boolean;
+export interface IContractFileRuleMatch {
+    file: string;
+    rule: IContractFileRule;
+}
+/** Returns every (file, rule) pair where the rule covers the file. */
+export declare function matchContractFileRules(rules: readonly IContractFileRule[], files: readonly string[]): readonly IContractFileRuleMatch[];
+/**
+ * Compatibility helper: legacy `forbiddenFiles: string[]` is wrapped as
+ * `kind: 'contains'` rules so the two pathways evaluate identically.
+ */
+export declare function rulesFromLegacyStrings(patterns: readonly string[]): readonly IContractFileRule[];
+/** Detect intended `kind` for a free-text legacy pattern. */
+export declare function inferContractFileRule(pattern: string): IContractFileRule;
+//# sourceMappingURL=contract-file-rule.d.ts.map

package/dist/contract-file-rule.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-file-rule.d.ts","sourceRoot":"","sources":["../src/contract-file-rule.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,oBAAY,oBAAoB;IAC9B,IAAI,SAAS;IACb,UAAU,gBAAgB;IAC1B,KAAK,UAAU;IACf,QAAQ,aAAa;CACtB;AAED,oBAAY,wBAAwB;IAClC,KAAK,UAAU;IACf,OAAO,YAAY;CACpB;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,oBAAoB,CAAC;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,wBAAwB,CAAC;CACrC;AAyCD,oEAAoE;AACpE,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,iBAAiB,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAapF;AAED,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,iBAAiB,CAAC;CACzB;AAED,sEAAsE;AACtE,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,SAAS,iBAAiB,EAAE,EACnC,KAAK,EAAE,SAAS,MAAM,EAAE,GACvB,SAAS,sBAAsB,EAAE,CAQnC;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,SAAS,MAAM,EAAE,GAC1B,SAAS,iBAAiB,EAAE,CAE9B;AAED,6DAA6D;AAC7D,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,iBAAiB,CAQxE"}