@shrkcrft/inspector 0.1.0-alpha.1

package/dist/contract-file-rule.js

@@ -0,0 +1,99 @@
+/**
+ * `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 var ContractFileRuleKind;
+(function (ContractFileRuleKind) {
+    ContractFileRuleKind["Glob"] = "glob";
+    ContractFileRuleKind["PathPrefix"] = "path-prefix";
+    ContractFileRuleKind["Exact"] = "exact";
+    ContractFileRuleKind["Contains"] = "contains";
+})(ContractFileRuleKind || (ContractFileRuleKind = {}));
+export var ContractFileRuleSeverity;
+(function (ContractFileRuleSeverity) {
+    ContractFileRuleSeverity["Error"] = "error";
+    ContractFileRuleSeverity["Warning"] = "warning";
+})(ContractFileRuleSeverity || (ContractFileRuleSeverity = {}));
+function toPosix(p) {
+    return p.replace(/\\/g, '/').replace(/^\.\//, '');
+}
+function escapeRegex(s) {
+    return s.replace(/[.+^$(){}|\\[\]]/g, '\\$&');
+}
+/** Translate a deterministic POSIX-style glob to a regex anchored at both ends. */
+function globToRegex(pattern) {
+    const p = toPosix(pattern);
+    let re = '';
+    let i = 0;
+    while (i < p.length) {
+        const c = p[i];
+        if (c === '*') {
+            // `**` matches across path separators, `*` matches within a segment.
+            if (p[i + 1] === '*') {
+                // Optional trailing `/`: treat `**/` and `/**` and bare `**` uniformly.
+                re += '.*';
+                i += 2;
+                if (p[i] === '/')
+                    i += 1; // consume one separator after `**`
+                continue;
+            }
+            re += '[^/]*';
+            i += 1;
+            continue;
+        }
+        if (c === '?') {
+            re += '[^/]';
+            i += 1;
+            continue;
+        }
+        re += escapeRegex(c);
+        i += 1;
+    }
+    return new RegExp('^' + re + '$');
+}
+/** Pure matcher — returns true when `file` is covered by `rule`. */
+export function matchContractFileRule(rule, file) {
+    const f = toPosix(file).toLowerCase();
+    const p = toPosix(rule.pattern).toLowerCase();
+    switch (rule.kind) {
+        case ContractFileRuleKind.Exact:
+            return f === p;
+        case ContractFileRuleKind.PathPrefix:
+            return f === p || f.startsWith(p.endsWith('/') ? p : p + '/');
+        case ContractFileRuleKind.Contains:
+            return p.length > 0 && f.includes(p);
+        case ContractFileRuleKind.Glob:
+            return globToRegex(p).test(f);
+    }
+}
+/** Returns every (file, rule) pair where the rule covers the file. */
+export function matchContractFileRules(rules, files) {
+    const out = [];
+    for (const file of files) {
+        for (const rule of rules) {
+            if (matchContractFileRule(rule, file))
+                out.push({ file, rule });
+        }
+    }
+    return out;
+}
+/**
+ * Compatibility helper: legacy `forbiddenFiles: string[]` is wrapped as
+ * `kind: 'contains'` rules so the two pathways evaluate identically.
+ */
+export function rulesFromLegacyStrings(patterns) {
+    return patterns.map((p) => ({ pattern: p, kind: ContractFileRuleKind.Contains }));
+}
+/** Detect intended `kind` for a free-text legacy pattern. */
+export function inferContractFileRule(pattern) {
+    const p = toPosix(pattern);
+    if (p.includes('*') || p.includes('?'))
+        return { pattern: p, kind: ContractFileRuleKind.Glob };
+    if (p.endsWith('/'))
+        return { pattern: p, kind: ContractFileRuleKind.PathPrefix };
+    if (/\.[a-z0-9]+$/i.test(p) && !p.includes('/')) {
+        return { pattern: p, kind: ContractFileRuleKind.Contains };
+    }
+    return { pattern: p, kind: ContractFileRuleKind.Contains };
+}

package/dist/contract-template-registry.d.ts

@@ -0,0 +1,28 @@
+import { type IAgentContractTemplate } from './agent-contract-templates.js';
+import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
+export declare const CONTRACT_TEMPLATE_REGISTRY_SCHEMA = "sharkcraft.contract-template-registry/v1";
+export declare enum ContractTemplateSource {
+    Builtin = "builtin",
+    Local = "local",
+    Pack = "pack"
+}
+export interface IContractTemplateEntry {
+    readonly template: IAgentContractTemplate;
+    readonly source: ContractTemplateSource;
+    readonly packageName?: string;
+    readonly sourceFile?: string;
+}
+export interface IContractTemplateRegistryIssue {
+    readonly severity: 'info' | 'warning' | 'error';
+    readonly code: string;
+    readonly message: string;
+    readonly templateId?: string;
+    readonly source?: string;
+}
+export declare function loadAllContractTemplates(inspection: ISharkcraftInspection): Promise<{
+    entries: readonly IContractTemplateEntry[];
+    issues: readonly IContractTemplateRegistryIssue[];
+}>;
+export declare function listAllContractTemplates(inspection: ISharkcraftInspection): Promise<readonly IAgentContractTemplate[]>;
+export declare function clearContractTemplateRegistryCache(projectRoot?: string): void;
+//# sourceMappingURL=contract-template-registry.d.ts.map

package/dist/contract-template-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-template-registry.d.ts","sourceRoot":"","sources":["../src/contract-template-registry.ts"],"names":[],"mappings":"AAOA,OAAO,EAGL,KAAK,sBAAsB,EAC5B,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAEvE,eAAO,MAAM,iCAAiC,6CAA6C,CAAC;AAE5F,oBAAY,sBAAsB;IAChC,OAAO,YAAY;IACnB,KAAK,UAAU;IACf,IAAI,SAAS;CACd;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,QAAQ,EAAE,sBAAsB,CAAC;IAC1C,QAAQ,CAAC,MAAM,EAAE,sBAAsB,CAAC;IACxC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC;IAChD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AA+CD,wBAAsB,wBAAwB,CAC5C,UAAU,EAAE,qBAAqB,GAChC,OAAO,CAAC;IACT,OAAO,EAAE,SAAS,sBAAsB,EAAE,CAAC;IAC3C,MAAM,EAAE,SAAS,8BAA8B,EAAE,CAAC;CACnD,CAAC,CAkGD;AAED,wBAAsB,wBAAwB,CAC5C,UAAU,EAAE,qBAAqB,GAChC,OAAO,CAAC,SAAS,sBAAsB,EAAE,CAAC,CAG5C;AAED,wBAAgB,kCAAkC,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAG7E"}

package/dist/contract-template-registry.js

@@ -0,0 +1,161 @@
+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;
+};
+/**
+ * Contract template registry. Merges engine built-ins with
+ * pack-contributed contract templates via `contractTemplateFiles`.
+ */
+import { existsSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { ALL_CONTRACT_TEMPLATES, AGENT_CONTRACT_TEMPLATE_SCHEMA, } from "./agent-contract-templates.js";
+export const CONTRACT_TEMPLATE_REGISTRY_SCHEMA = 'sharkcraft.contract-template-registry/v1';
+export var ContractTemplateSource;
+(function (ContractTemplateSource) {
+    ContractTemplateSource["Builtin"] = "builtin";
+    ContractTemplateSource["Local"] = "local";
+    ContractTemplateSource["Pack"] = "pack";
+})(ContractTemplateSource || (ContractTemplateSource = {}));
+const CACHE = new Map();
+async function importDefault(file) {
+    const mod = (await import(__rewriteRelativeImportExtension(pathToFileURL(file).href)));
+    if (Array.isArray(mod.default))
+        return mod.default;
+    if (mod.default && typeof mod.default === 'object')
+        return [mod.default];
+    if (Array.isArray(mod.contractTemplates))
+        return mod.contractTemplates;
+    return [];
+}
+function localFiles(inspection) {
+    const out = [];
+    const dir = inspection.sharkcraftDir;
+    if (!dir)
+        return [];
+    for (const name of ['contract-templates.ts', 'contract-templates/index.ts']) {
+        const full = nodePath.join(dir, name);
+        if (existsSync(full))
+            out.push(full);
+    }
+    const cfg = inspection.config;
+    for (const rel of cfg?.contractTemplateFiles ?? []) {
+        out.push(nodePath.isAbsolute(rel) ? rel : nodePath.join(dir, rel));
+    }
+    return out;
+}
+function isValidTemplate(raw) {
+    if (!raw || typeof raw !== 'object')
+        return false;
+    const o = raw;
+    return (typeof o.id === 'string' &&
+        typeof o.title === 'string' &&
+        (o.schema === AGENT_CONTRACT_TEMPLATE_SCHEMA || o.schema === undefined) &&
+        Array.isArray(o.defaultForbiddenFilesDetailed));
+}
+export async function loadAllContractTemplates(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 { entries: cached.entries, issues: cached.issues };
+    }
+    const seen = new Map();
+    const entries = [];
+    const issues = [];
+    const ingest = (raw, source, packageName, sourceFile) => {
+        if (!isValidTemplate(raw)) {
+            issues.push({
+                severity: 'warning',
+                code: 'invalid-template',
+                message: `Invalid contract template at ${sourceFile ?? source}; skipped.`,
+                source: sourceFile,
+            });
+            return;
+        }
+        const tpl = raw;
+        const existing = seen.get(tpl.id);
+        if (existing) {
+            issues.push({
+                severity: 'error',
+                code: 'duplicate-id',
+                message: `Contract template id "${tpl.id}" already loaded from ${existing.source}${existing.sourceFile ? ' (' + existing.sourceFile + ')' : ''}; skipping ${source}${sourceFile ? ' (' + sourceFile + ')' : ''}.`,
+                templateId: tpl.id,
+                source: sourceFile,
+            });
+            return;
+        }
+        const entry = {
+            template: tpl,
+            source,
+            ...(packageName ? { packageName } : {}),
+            ...(sourceFile ? { sourceFile } : {}),
+        };
+        seen.set(tpl.id, entry);
+        entries.push(entry);
+    };
+    for (const t of ALL_CONTRACT_TEMPLATES) {
+        ingest(t, ContractTemplateSource.Builtin, undefined, undefined);
+    }
+    for (const file of localFiles(inspection)) {
+        try {
+            const list = await importDefault(file);
+            const rel = nodePath.relative(inspection.projectRoot, file) || file;
+            for (const raw of list)
+                ingest(raw, ContractTemplateSource.Local, undefined, rel);
+        }
+        catch (e) {
+            issues.push({
+                severity: 'warning',
+                code: 'load-failed',
+                message: `Failed to load ${file}: ${e.message}`,
+                source: file,
+            });
+        }
+    }
+    for (const pack of inspection.packs.validPacks ?? []) {
+        const contributions = (pack.manifest?.contributions ?? {});
+        for (const rel of contributions.contractTemplateFiles ?? []) {
+            const file = nodePath.resolve(pack.packageRoot, rel);
+            if (!existsSync(file)) {
+                issues.push({
+                    severity: 'warning',
+                    code: 'missing-file',
+                    message: `Pack ${pack.packageName} declares contract template ${rel} but the file is missing.`,
+                    source: file,
+                });
+                continue;
+            }
+            try {
+                const list = await importDefault(file);
+                for (const raw of list)
+                    ingest(raw, ContractTemplateSource.Pack, pack.packageName, rel);
+            }
+            catch (e) {
+                issues.push({
+                    severity: 'warning',
+                    code: 'load-failed',
+                    message: `Pack ${pack.packageName} (${rel}): ${e.message}`,
+                    source: file,
+                });
+            }
+        }
+    }
+    CACHE.set(inspection.projectRoot, { cacheKey, entries, issues });
+    return { entries, issues };
+}
+export async function listAllContractTemplates(inspection) {
+    const { entries } = await loadAllContractTemplates(inspection);
+    return entries.map((e) => e.template);
+}
+export function clearContractTemplateRegistryCache(projectRoot) {
+    if (projectRoot)
+        CACHE.delete(projectRoot);
+    else
+        CACHE.clear();
+}

package/dist/contradictions.d.ts

@@ -0,0 +1,52 @@
+import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
+export declare const CONTRADICTIONS_SCHEMA = "sharkcraft.contradictions/v1";
+export declare enum ContradictionKind {
+    MissingPath = "missing-path",
+    MissingCommand = "missing-command",
+    StalePath = "stale-path",
+    OldCliPath = "old-cli-path",
+    MissingExport = "missing-export",
+    DocVsConfigConflict = "doc-vs-config-conflict",
+    DeprecatedRecommendation = "deprecated-recommendation"
+}
+export declare enum ContradictionSeverity {
+    Error = "error",
+    Warning = "warning",
+    Info = "info"
+}
+export interface IContradictionFinding {
+    id: string;
+    kind: ContradictionKind;
+    severity: ContradictionSeverity;
+    message: string;
+    /** Where the contradiction is referenced. */
+    source: string;
+    /** Optional 1-based line number in the source. */
+    line?: number;
+    /** The thing being referenced incorrectly. */
+    reference: string;
+    suggestion?: string;
+    reason: string;
+}
+export interface IContradictionReport {
+    schema: typeof CONTRADICTIONS_SCHEMA;
+    projectRoot: string;
+    findings: readonly IContradictionFinding[];
+    /** Files scanned. */
+    filesScanned: number;
+    /** Limitations / sampling notes. */
+    limitations: readonly string[];
+}
+export interface IBuildContradictionReportOptions {
+    inspection: ISharkcraftInspection;
+    /** Max doc files to scan. Default 80. */
+    docScanLimit?: number;
+    /** Max bytes per doc. Default 200_000. */
+    bytesPerDoc?: number;
+}
+export declare function buildContradictionReport(options: IBuildContradictionReportOptions): IContradictionReport;
+export declare function renderContradictionReportText(report: IContradictionReport): string;
+export declare function renderContradictionReportMarkdown(report: IContradictionReport): string;
+export declare function renderContradictionReportHtml(report: IContradictionReport): string;
+export declare function renderContradictionReportJson(report: IContradictionReport): string;
+//# sourceMappingURL=contradictions.d.ts.map

package/dist/contradictions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contradictions.d.ts","sourceRoot":"","sources":["../src/contradictions.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAEvE,eAAO,MAAM,qBAAqB,iCAAiC,CAAC;AAEpE,oBAAY,iBAAiB;IAC3B,WAAW,iBAAiB;IAC5B,cAAc,oBAAoB;IAClC,SAAS,eAAe;IACxB,UAAU,iBAAiB;IAC3B,aAAa,mBAAmB;IAChC,mBAAmB,2BAA2B;IAC9C,wBAAwB,8BAA8B;CACvD;AAED,oBAAY,qBAAqB;IAC/B,KAAK,UAAU;IACf,OAAO,YAAY;IACnB,IAAI,SAAS;CACd;AAED,MAAM,WAAW,qBAAqB;IACpC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,iBAAiB,CAAC;IACxB,QAAQ,EAAE,qBAAqB,CAAC;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,6CAA6C;IAC7C,MAAM,EAAE,MAAM,CAAC;IACf,kDAAkD;IAClD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8CAA8C;IAC9C,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,OAAO,qBAAqB,CAAC;IACrC,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,SAAS,qBAAqB,EAAE,CAAC;IAC3C,qBAAqB;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,oCAAoC;IACpC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CAChC;AAED,MAAM,WAAW,gCAAgC;IAC/C,UAAU,EAAE,qBAAqB,CAAC;IAClC,yCAAyC;IACzC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,0CAA0C;IAC1C,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AA2BD,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,gCAAgC,GACxC,oBAAoB,CAqKtB;AA0GD,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,oBAAoB,GAAG,MAAM,CAgClF;AAED,wBAAgB,iCAAiC,CAAC,MAAM,EAAE,oBAAoB,GAAG,MAAM,CA2BtF;AAED,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,oBAAoB,GAAG,MAAM,CAOlF;AAMD,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,oBAAoB,GAAG,MAAM,CAElF"}