@shrkcrft/structural-search 0.1.0-alpha.10

package/dist/engine/sign-rewrite.d.ts

@@ -0,0 +1,39 @@
+import { type ISignedRewritePlan } from '../schema/signed-rewrite.js';
+import type { IRewritePlan } from '../schema/rewrite.js';
+/**
+ * Sign a rewrite plan with HMAC-SHA256.
+ *
+ * Canonicalisation: the plan + provenance are serialised with sorted
+ * keys (deep) before HMAC. This guarantees the signature matches when
+ * the plan is round-tripped through any tool that preserves the data.
+ *
+ * `secret` is required; callers can read it from a project config or
+ * environment (e.g. `SHRKCRFT_REWRITE_SECRET`). There's no built-in
+ * default — passing an empty secret throws to prevent accidentally
+ * "signing" with the empty string.
+ */
+export declare function signRewritePlan(plan: IRewritePlan, options: {
+    secret: string;
+    signedBy?: string;
+}): ISignedRewritePlan;
+export interface IVerifySignedPlanResult {
+    ok: boolean;
+    /** Set when `ok` is false. Stable, machine-readable code. */
+    reason?: 'schema-mismatch' | 'algo-mismatch' | 'invalid-signature' | 'malformed-plan';
+    /** Human-readable detail (free-form). */
+    message?: string;
+    /** Computed HMAC, hex, for diagnostics. */
+    expectedHmac?: string;
+}
+/**
+ * Verify a signed rewrite plan. Constant-time HMAC comparison.
+ *
+ * Verification can fail for three reasons (each surfaced via
+ * `reason`): a different schema (forward-incompat), a different algo
+ * (different version of the signer), or a signature mismatch (wrong
+ * secret OR tampered plan).
+ */
+export declare function verifySignedRewritePlan(signed: ISignedRewritePlan, options: {
+    secret: string;
+}): IVerifySignedPlanResult;
+//# sourceMappingURL=sign-rewrite.d.ts.map

package/dist/engine/sign-rewrite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sign-rewrite.d.ts","sourceRoot":"","sources":["../../src/engine/sign-rewrite.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,kBAAkB,EAExB,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEzD;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,YAAY,EAClB,OAAO,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7C,kBAAkB,CAiBpB;AAED,MAAM,WAAW,uBAAuB;IACtC,EAAE,EAAE,OAAO,CAAC;IACZ,6DAA6D;IAC7D,MAAM,CAAC,EACH,iBAAiB,GACjB,eAAe,GACf,mBAAmB,GACnB,gBAAgB,CAAC;IACrB,yCAAyC;IACzC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,2CAA2C;IAC3C,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,kBAAkB,EAC1B,OAAO,EAAE;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,GAC1B,uBAAuB,CAoBzB"}

package/dist/engine/sign-rewrite.js

@@ -0,0 +1,87 @@
+import { createHmac } from 'node:crypto';
+import { SIGNED_REWRITE_SCHEMA, } from "../schema/signed-rewrite.js";
+/**
+ * Sign a rewrite plan with HMAC-SHA256.
+ *
+ * Canonicalisation: the plan + provenance are serialised with sorted
+ * keys (deep) before HMAC. This guarantees the signature matches when
+ * the plan is round-tripped through any tool that preserves the data.
+ *
+ * `secret` is required; callers can read it from a project config or
+ * environment (e.g. `SHRKCRFT_REWRITE_SECRET`). There's no built-in
+ * default — passing an empty secret throws to prevent accidentally
+ * "signing" with the empty string.
+ */
+export function signRewritePlan(plan, options) {
+    if (!options.secret) {
+        throw new Error('signRewritePlan: secret is required');
+    }
+    const provenance = {
+        signedAt: new Date().toISOString(),
+        signedBy: options.signedBy ?? '@shrkcrft/structural-search',
+        planSchema: plan.schema,
+    };
+    const hmac = computeHmac(plan, provenance, options.secret);
+    return {
+        schema: SIGNED_REWRITE_SCHEMA,
+        algo: 'sha256',
+        hmac,
+        provenance,
+        plan,
+    };
+}
+/**
+ * Verify a signed rewrite plan. Constant-time HMAC comparison.
+ *
+ * Verification can fail for three reasons (each surfaced via
+ * `reason`): a different schema (forward-incompat), a different algo
+ * (different version of the signer), or a signature mismatch (wrong
+ * secret OR tampered plan).
+ */
+export function verifySignedRewritePlan(signed, options) {
+    if (signed.schema !== SIGNED_REWRITE_SCHEMA) {
+        return { ok: false, reason: 'schema-mismatch', message: `unexpected schema: ${signed.schema}` };
+    }
+    if (signed.algo !== 'sha256') {
+        return { ok: false, reason: 'algo-mismatch', message: `unsupported algo: ${signed.algo}` };
+    }
+    if (!signed.plan || !signed.provenance) {
+        return { ok: false, reason: 'malformed-plan', message: 'missing plan or provenance' };
+    }
+    const expected = computeHmac(signed.plan, signed.provenance, options.secret);
+    if (!constantTimeEqualHex(expected, signed.hmac)) {
+        return {
+            ok: false,
+            reason: 'invalid-signature',
+            message: 'HMAC mismatch — wrong secret or tampered plan',
+            expectedHmac: expected,
+        };
+    }
+    return { ok: true };
+}
+function computeHmac(plan, provenance, secret) {
+    const canonical = canonicalJson({ plan, provenance });
+    return createHmac('sha256', secret).update(canonical).digest('hex');
+}
+function canonicalJson(value) {
+    return JSON.stringify(sortDeep(value));
+}
+function sortDeep(value) {
+    if (Array.isArray(value))
+        return value.map(sortDeep);
+    if (value === null || typeof value !== 'object')
+        return value;
+    const obj = value;
+    const sorted = {};
+    for (const key of Object.keys(obj).sort())
+        sorted[key] = sortDeep(obj[key]);
+    return sorted;
+}
+function constantTimeEqualHex(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let acc = 0;
+    for (let i = 0; i < a.length; i += 1)
+        acc |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    return acc === 0;
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export * from './schema/pattern.js';
+export * from './schema/pattern-registry.js';
+export * from './schema/match.js';
+export * from './schema/rewrite.js';
+export * from './schema/signed-rewrite.js';
+export * from './engine/match-pattern.js';
+export * from './engine/run-search.js';
+export * from './engine/plan-rewrite.js';
+export * from './engine/apply-rewrite.js';
+export * from './engine/sign-rewrite.js';
+export * from './registry/pattern-registry-store.js';
+export * from './registry/starter-patterns.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,qBAAqB,CAAC;AACpC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,wBAAwB,CAAC;AACvC,cAAc,0BAA0B,CAAC;AACzC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,0BAA0B,CAAC;AACzC,cAAc,sCAAsC,CAAC;AACrD,cAAc,gCAAgC,CAAC"}

package/dist/index.js

@@ -0,0 +1,13 @@
+// Public surface of @shrkcrft/structural-search.
+export * from "./schema/pattern.js";
+export * from "./schema/pattern-registry.js";
+export * from "./schema/match.js";
+export * from "./schema/rewrite.js";
+export * from "./schema/signed-rewrite.js";
+export * from "./engine/match-pattern.js";
+export * from "./engine/run-search.js";
+export * from "./engine/plan-rewrite.js";
+export * from "./engine/apply-rewrite.js";
+export * from "./engine/sign-rewrite.js";
+export * from "./registry/pattern-registry-store.js";
+export * from "./registry/starter-patterns.js";

package/dist/registry/pattern-registry-store.d.ts

@@ -0,0 +1,46 @@
+import type { IPatternEnvelope } from '../schema/pattern.js';
+import { type IPatternRegistry, type IPatternValidationResult, type IRegisteredPattern } from '../schema/pattern-registry.js';
+/**
+ * On-disk registry of structural-search patterns. Pattern authors call
+ * `add(envelope)` to register a reusable pattern by id; the doctor
+ * reads the list to surface freshness + validation state without
+ * recomputing matches against the codebase.
+ *
+ * The store deliberately validates the envelope at write time so a
+ * malformed pattern can never sneak past the boundary. Replaying via
+ * `validate()` is a no-op when every entry already has
+ * `lastValidatedAt` newer than the registry's own mtime.
+ */
+export declare class PatternRegistryStore {
+    private readonly projectRoot;
+    readonly absPath: string;
+    constructor(projectRoot: string);
+    exists(): boolean;
+    read(): IPatternRegistry;
+    write(registry: IPatternRegistry): void;
+    /**
+     * Add or replace a pattern by id. Returns the validation result of
+     * the envelope; when invalid the registry is NOT modified.
+     */
+    add(envelope: IPatternEnvelope): {
+        result: IPatternValidationResult;
+        entry?: IRegisteredPattern;
+    };
+    remove(id: string): boolean;
+    clear(): boolean;
+    /**
+     * Re-validate every entry. Updates `lastValidatedAt` on success and
+     * `lastValidationError` on failure (preserving the entry in the
+     * registry — the user can decide whether to remove it). Returns the
+     * count of failed entries.
+     */
+    validateAll(): {
+        total: number;
+        failed: number;
+        errors: ReadonlyArray<{
+            id: string;
+            error: string;
+        }>;
+    };
+}
+//# sourceMappingURL=pattern-registry-store.d.ts.map

package/dist/registry/pattern-registry-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pattern-registry-store.d.ts","sourceRoot":"","sources":["../../src/registry/pattern-registry-store.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EAGL,KAAK,gBAAgB,EACrB,KAAK,wBAAwB,EAC7B,KAAK,kBAAkB,EACxB,MAAM,+BAA+B,CAAC;AAIvC;;;;;;;;;;GAUG;AACH,qBAAa,oBAAoB;IAGnB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAFxC,SAAgB,OAAO,EAAE,MAAM,CAAC;gBAEH,WAAW,EAAE,MAAM;IAIhD,MAAM,IAAI,OAAO;IAIjB,IAAI,IAAI,gBAAgB;IAWxB,KAAK,CAAC,QAAQ,EAAE,gBAAgB,GAAG,IAAI;IAKvC;;;OAGG;IACH,GAAG,CAAC,QAAQ,EAAE,gBAAgB,GAAG;QAC/B,MAAM,EAAE,wBAAwB,CAAC;QACjC,KAAK,CAAC,EAAE,kBAAkB,CAAC;KAC5B;IAwBD,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAQ3B,KAAK,IAAI,OAAO;IAMhB;;;;;OAKG;IACH,WAAW,IAAI;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,aAAa,CAAC;YAAE,EAAE,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAE,CAAC,CAAA;KAAE;CA0BvG"}

package/dist/registry/pattern-registry-store.js

@@ -0,0 +1,120 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { STRUCTURAL_PATTERN_REGISTRY_SCHEMA, validatePatternEnvelope, } from "../schema/pattern-registry.js";
+const REGISTRY_REL = '.sharkcraft/structural/patterns.json';
+/**
+ * On-disk registry of structural-search patterns. Pattern authors call
+ * `add(envelope)` to register a reusable pattern by id; the doctor
+ * reads the list to surface freshness + validation state without
+ * recomputing matches against the codebase.
+ *
+ * The store deliberately validates the envelope at write time so a
+ * malformed pattern can never sneak past the boundary. Replaying via
+ * `validate()` is a no-op when every entry already has
+ * `lastValidatedAt` newer than the registry's own mtime.
+ */
+export class PatternRegistryStore {
+    projectRoot;
+    absPath;
+    constructor(projectRoot) {
+        this.projectRoot = projectRoot;
+        this.absPath = nodePath.join(projectRoot, REGISTRY_REL);
+    }
+    exists() {
+        return existsSync(this.absPath);
+    }
+    read() {
+        if (!this.exists())
+            return emptyRegistry();
+        try {
+            const raw = JSON.parse(readFileSync(this.absPath, 'utf8'));
+            if (raw.schema !== STRUCTURAL_PATTERN_REGISTRY_SCHEMA)
+                return emptyRegistry();
+            return raw;
+        }
+        catch {
+            return emptyRegistry();
+        }
+    }
+    write(registry) {
+        mkdirSync(nodePath.dirname(this.absPath), { recursive: true });
+        writeFileSync(this.absPath, JSON.stringify(registry, null, 2), 'utf8');
+    }
+    /**
+     * Add or replace a pattern by id. Returns the validation result of
+     * the envelope; when invalid the registry is NOT modified.
+     */
+    add(envelope) {
+        if (!envelope.id) {
+            return { result: { ok: false, error: 'pattern envelope is missing required `id`' } };
+        }
+        const result = validatePatternEnvelope(envelope);
+        if (!result.ok)
+            return { result };
+        const now = new Date().toISOString();
+        const entry = {
+            id: envelope.id,
+            ...(envelope.title ? { title: envelope.title } : {}),
+            ...(envelope.description ? { description: envelope.description } : {}),
+            pattern: envelope.pattern,
+            addedAt: now,
+            lastValidatedAt: now,
+        };
+        const reg = this.read();
+        const filtered = reg.patterns.filter((p) => p.id !== envelope.id);
+        this.write({
+            schema: STRUCTURAL_PATTERN_REGISTRY_SCHEMA,
+            patterns: [...filtered, entry].sort((a, b) => a.id.localeCompare(b.id)),
+        });
+        return { result, entry };
+    }
+    remove(id) {
+        const reg = this.read();
+        const next = reg.patterns.filter((p) => p.id !== id);
+        if (next.length === reg.patterns.length)
+            return false;
+        this.write({ schema: STRUCTURAL_PATTERN_REGISTRY_SCHEMA, patterns: next });
+        return true;
+    }
+    clear() {
+        if (!this.exists())
+            return false;
+        rmSync(this.absPath);
+        return true;
+    }
+    /**
+     * Re-validate every entry. Updates `lastValidatedAt` on success and
+     * `lastValidationError` on failure (preserving the entry in the
+     * registry — the user can decide whether to remove it). Returns the
+     * count of failed entries.
+     */
+    validateAll() {
+        const reg = this.read();
+        const failed = [];
+        const now = new Date().toISOString();
+        const next = reg.patterns.map((entry) => {
+            const envelope = {
+                schema: 'sharkcraft.structural-pattern/v1',
+                id: entry.id,
+                ...(entry.title ? { title: entry.title } : {}),
+                ...(entry.description ? { description: entry.description } : {}),
+                pattern: entry.pattern,
+            };
+            const result = validatePatternEnvelope(envelope);
+            if (result.ok) {
+                const cleaned = { ...entry, lastValidatedAt: now };
+                delete cleaned.lastValidationError;
+                return cleaned;
+            }
+            failed.push({ id: entry.id, error: result.error ?? 'invalid pattern' });
+            return { ...entry, lastValidationError: result.error ?? 'invalid pattern' };
+        });
+        if (reg.patterns.length > 0) {
+            this.write({ schema: STRUCTURAL_PATTERN_REGISTRY_SCHEMA, patterns: next });
+        }
+        return { total: reg.patterns.length, failed: failed.length, errors: failed };
+    }
+}
+function emptyRegistry() {
+    return { schema: STRUCTURAL_PATTERN_REGISTRY_SCHEMA, patterns: [] };
+}

package/dist/registry/starter-patterns.d.ts

@@ -0,0 +1,12 @@
+import type { IPatternEnvelope } from '../schema/pattern.js';
+/**
+ * Curated starter pattern set. These are intentionally narrow and
+ * useful out of the box: they catch real DX issues that a clean repo
+ * should have zero of (console.log left in committed code,
+ * `@Controller()` decorators without a route argument, etc.).
+ *
+ * Used by `shrk search-structural registry seed` to populate a fresh
+ * registry. Authors are expected to grow / prune the set per project.
+ */
+export declare const STARTER_PATTERNS: readonly IPatternEnvelope[];
+//# sourceMappingURL=starter-patterns.d.ts.map

package/dist/registry/starter-patterns.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"starter-patterns.d.ts","sourceRoot":"","sources":["../../src/registry/starter-patterns.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAG7D;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,EAAE,SAAS,gBAAgB,EAgFvD,CAAC"}

package/dist/registry/starter-patterns.js

@@ -0,0 +1,84 @@
+import { STRUCTURAL_PATTERN_SCHEMA } from "../schema/pattern.js";
+/**
+ * Curated starter pattern set. These are intentionally narrow and
+ * useful out of the box: they catch real DX issues that a clean repo
+ * should have zero of (console.log left in committed code,
+ * `@Controller()` decorators without a route argument, etc.).
+ *
+ * Used by `shrk search-structural registry seed` to populate a fresh
+ * registry. Authors are expected to grow / prune the set per project.
+ */
+export const STARTER_PATTERNS = [
+    {
+        schema: STRUCTURAL_PATTERN_SCHEMA,
+        id: 'starter.no-console-log',
+        title: 'No console.log calls',
+        description: 'Catches `console.log(...)` left in committed source. Pair with a rule that allows console.warn / console.error.',
+        pattern: {
+            kind: 'CallExpression',
+            callee: { kind: 'Identifier', nameRegex: '^log$' },
+            minArgs: 0,
+        },
+    },
+    {
+        schema: STRUCTURAL_PATTERN_SCHEMA,
+        id: 'starter.no-debugger',
+        title: 'No debugger calls',
+        description: 'Catches `debugger;` statements via a synthetic call shape match. False-positive-prone — use as a quick scan, not a hard gate.',
+        pattern: {
+            kind: 'Identifier',
+            name: 'debugger',
+        },
+    },
+    {
+        schema: STRUCTURAL_PATTERN_SCHEMA,
+        id: 'starter.nest.bare-controller',
+        title: 'NestJS @Controller() decorator without a route argument',
+        description: 'Flags `@Controller()` (no args), which mounts at the app root and is usually a typo. The shape match is callee-only — combine with `argCount: 0` to require zero args.',
+        pattern: {
+            kind: 'CallExpression',
+            callee: { kind: 'Identifier', name: 'Controller' },
+            argCount: 0,
+        },
+    },
+    {
+        schema: STRUCTURAL_PATTERN_SCHEMA,
+        id: 'starter.nest.injectable',
+        title: 'NestJS @Injectable() decorator usage',
+        description: 'Locates every `@Injectable()` call. Useful as a starting point for "find every provider in this app".',
+        pattern: {
+            kind: 'CallExpression',
+            callee: { kind: 'Identifier', name: 'Injectable' },
+        },
+    },
+    {
+        schema: STRUCTURAL_PATTERN_SCHEMA,
+        id: 'starter.react.unsafe-eval',
+        title: 'eval() call',
+        description: 'Catches `eval(...)` — almost always a security smell. Pair with a rule that forbids dynamic code in user-input paths.',
+        pattern: {
+            kind: 'CallExpression',
+            callee: { kind: 'Identifier', name: 'eval' },
+        },
+    },
+    {
+        schema: STRUCTURAL_PATTERN_SCHEMA,
+        id: 'starter.imports.dynamic-require',
+        title: 'Dynamic require() with a variable specifier',
+        description: 'Matches `require(...)` callsites. Useful in TypeScript-first repos that should be using `import` exclusively.',
+        pattern: {
+            kind: 'CallExpression',
+            callee: { kind: 'Identifier', name: 'require' },
+        },
+    },
+    {
+        schema: STRUCTURAL_PATTERN_SCHEMA,
+        id: 'starter.imports.from-internal',
+        title: 'Cross-package import from internal/ path',
+        description: 'Locates imports whose source path mentions `/internal/` — usually a private boundary another package should NOT cross. Combine with `shrk arch check` for the layered enforcement.',
+        pattern: {
+            kind: 'ImportDeclaration',
+            fromRegex: '/internal/',
+        },
+    },
+];

package/dist/schema/match.d.ts

@@ -0,0 +1,25 @@
+export interface IStructuralMatch {
+    /** Project-relative POSIX path. */
+    file: string;
+    /** 1-based line number of the matched node start. */
+    line: number;
+    /** 0-based column number of the matched node start. */
+    column: number;
+    /** AST node kind name (e.g. 'CallExpression'). */
+    nodeKind: string;
+    /** First ~140 chars of the matched text, single-lined. */
+    excerpt: string;
+}
+export interface IStructuralSearchResult {
+    schema: 'sharkcraft.structural-search/v1';
+    pattern: {
+        kind: string;
+        summary: string;
+    };
+    filesScanned: number;
+    matchCount: number;
+    truncated: boolean;
+    matches: readonly IStructuralMatch[];
+    diagnostics: readonly string[];
+}
+//# sourceMappingURL=match.d.ts.map

package/dist/schema/match.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"match.d.ts","sourceRoot":"","sources":["../../src/schema/match.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,gBAAgB;IAC/B,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,IAAI,EAAE,MAAM,CAAC;IACb,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAC;IACf,kDAAkD;IAClD,QAAQ,EAAE,MAAM,CAAC;IACjB,0DAA0D;IAC1D,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,iCAAiC,CAAC;IAC1C,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3C,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACrC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CAChC"}

package/dist/schema/match.js

@@ -0,0 +1 @@
+export {};

package/dist/schema/pattern-registry.d.ts

@@ -0,0 +1,52 @@
+import { type IPatternEnvelope, type StructuralPattern } from './pattern.js';
+export declare const STRUCTURAL_PATTERN_REGISTRY_SCHEMA: "sharkcraft.structural-pattern-registry/v1";
+/**
+ * One entry in the on-disk pattern registry. Carries the full pattern
+ * envelope plus bookkeeping (added / validated timestamps + last error
+ * if any) so the doctor can surface decayed entries.
+ */
+export interface IRegisteredPattern {
+    id: string;
+    title?: string;
+    description?: string;
+    pattern: StructuralPattern;
+    /** ISO timestamp the entry was added. */
+    addedAt: string;
+    /** ISO timestamp the entry was last validated successfully. */
+    lastValidatedAt?: string;
+    /** Last validation error message (set when validation failed). */
+    lastValidationError?: string;
+}
+/**
+ * On-disk pattern registry shape, persisted at
+ * `.sharkcraft/structural/patterns.json`. Lives alongside the pattern
+ * engine so packs can ship patterns and the doctor can check their
+ * health without a custom loader per pack.
+ */
+export interface IPatternRegistry {
+    schema: typeof STRUCTURAL_PATTERN_REGISTRY_SCHEMA;
+    patterns: readonly IRegisteredPattern[];
+}
+/**
+ * Allowed `pattern.kind` strings. Hard-coded so we can validate
+ * entries without invoking the matcher itself — a registry entry with
+ * an unknown kind is rejected at registration time.
+ */
+export declare const KNOWN_PATTERN_KINDS: Set<string>;
+export interface IPatternValidationResult {
+    ok: boolean;
+    error?: string;
+}
+/**
+ * Light-weight envelope validation. Confirms:
+ *   - schema field matches the canonical version,
+ *   - pattern.kind is one of the known matcher kinds,
+ *   - any regex field compiles.
+ *
+ * This is deliberately not a full structural typecheck — TypeScript
+ * already enforces the runtime fields. The goal is to catch
+ * pack-contributed JSON that fails at the boundary instead of at
+ * match time.
+ */
+export declare function validatePatternEnvelope(envelope: IPatternEnvelope): IPatternValidationResult;
+//# sourceMappingURL=pattern-registry.d.ts.map

package/dist/schema/pattern-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pattern-registry.d.ts","sourceRoot":"","sources":["../../src/schema/pattern-registry.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACvB,MAAM,cAAc,CAAC;AAEtB,eAAO,MAAM,kCAAkC,EAC7C,2CAAoD,CAAC;AAEvD;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,iBAAiB,CAAC;IAC3B,yCAAyC;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,+DAA+D;IAC/D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,kEAAkE;IAClE,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,OAAO,kCAAkC,CAAC;IAClD,QAAQ,EAAE,SAAS,kBAAkB,EAAE,CAAC;CACzC;AAED;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,aAQ9B,CAAC;AAEH,MAAM,WAAW,wBAAwB;IACvC,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,gBAAgB,GACzB,wBAAwB,CA+B1B"}

package/dist/schema/pattern-registry.js

@@ -0,0 +1,60 @@
+import { STRUCTURAL_PATTERN_SCHEMA, } from "./pattern.js";
+export const STRUCTURAL_PATTERN_REGISTRY_SCHEMA = 'sharkcraft.structural-pattern-registry/v1';
+/**
+ * Allowed `pattern.kind` strings. Hard-coded so we can validate
+ * entries without invoking the matcher itself — a registry entry with
+ * an unknown kind is rejected at registration time.
+ */
+export const KNOWN_PATTERN_KINDS = new Set([
+    'Identifier',
+    'StringLiteral',
+    'CallExpression',
+    'NewExpression',
+    'ImportDeclaration',
+    'ClassDeclaration',
+    'Decorator',
+]);
+/**
+ * Light-weight envelope validation. Confirms:
+ *   - schema field matches the canonical version,
+ *   - pattern.kind is one of the known matcher kinds,
+ *   - any regex field compiles.
+ *
+ * This is deliberately not a full structural typecheck — TypeScript
+ * already enforces the runtime fields. The goal is to catch
+ * pack-contributed JSON that fails at the boundary instead of at
+ * match time.
+ */
+export function validatePatternEnvelope(envelope) {
+    if (envelope.schema !== STRUCTURAL_PATTERN_SCHEMA) {
+        return {
+            ok: false,
+            error: `schema mismatch: got "${envelope.schema}", expected "${STRUCTURAL_PATTERN_SCHEMA}"`,
+        };
+    }
+    const p = envelope.pattern;
+    if (!p || typeof p.kind !== 'string') {
+        return { ok: false, error: 'pattern.kind is missing or not a string' };
+    }
+    if (!KNOWN_PATTERN_KINDS.has(p.kind)) {
+        return {
+            ok: false,
+            error: `pattern.kind "${p.kind}" is not a known matcher kind (one of ${[...KNOWN_PATTERN_KINDS].sort().join(', ')})`,
+        };
+    }
+    for (const key of ['nameRegex', 'textRegex', 'fromRegex']) {
+        const raw = p[key];
+        if (typeof raw === 'string' && raw.length > 0) {
+            try {
+                new RegExp(raw);
+            }
+            catch (e) {
+                return {
+                    ok: false,
+                    error: `pattern.${key} is not a valid regex: ${e.message}`,
+                };
+            }
+        }
+    }
+    return { ok: true };
+}