@shrkcrft/core 0.1.0-alpha.21 → 0.1.0-alpha.22

package/dist/index.d.ts

@@ -1,6 +1,9 @@
 export * from './result/result.js';
 export * from './result/errors.js';
 export * from './delegate/delegate-recipe.js';
+export * from './wiring/wiring-rule.js';
+export * from './policy/policy-rule.js';
+export * from './reuse/reuse-primitive.js';
 export * from './logger/log-level.js';
 export * from './logger/logger.js';
 export * from './fs/file-system.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,yBAAyB,CAAC;AACxC,cAAc,sBAAsB,CAAC;AACrC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,0BAA0B,CAAC;AACzC,cAAc,0BAA0B,CAAC;AACzC,cAAc,aAAa,CAAC;AAC5B,cAAc,gCAAgC,CAAC;AAC/C,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,yBAAyB,CAAC;AACxC,cAAc,yBAAyB,CAAC;AACxC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,yBAAyB,CAAC;AACxC,cAAc,sBAAsB,CAAC;AACrC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,0BAA0B,CAAC;AACzC,cAAc,0BAA0B,CAAC;AACzC,cAAc,aAAa,CAAC;AAC5B,cAAc,gCAAgC,CAAC;AAC/C,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC"}

package/dist/index.js

@@ -1,6 +1,9 @@
 export * from "./result/result.js";
 export * from "./result/errors.js";
 export * from "./delegate/delegate-recipe.js";
+export * from "./wiring/wiring-rule.js";
+export * from "./policy/policy-rule.js";
+export * from "./reuse/reuse-primitive.js";
 export * from "./logger/log-level.js";
 export * from "./logger/logger.js";
 export * from "./fs/file-system.js";

package/dist/policy/policy-rule.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Policy-lint rules — the "template/markup/style/ts" plane.
+ *
+ * Some violations compile AOT-green because they live on surfaces the type
+ * checker and structural search can't see: raw markup in `.html` files and
+ * inline `template:` strings, stylesheet content, and a handful of
+ * AOT-invisible TS shapes. `shrk policy-lint` runs deterministic, data-defined
+ * pattern rules over exactly those surfaces.
+ *
+ * The engine is generic — no framework or project specifics. A project supplies
+ * the rules as data via `sharkcraft.config.ts` `policyRules[]` (or a pack); each
+ * rule names a surface, a regex, and a human message (optionally a suggested
+ * replacement primitive). No AI.
+ */
+/** The content surface a rule scans. */
+export type PolicySurface = 
+/** `.html` files PLUS inline `template:` strings extracted from source files. */
+'template'
+/** Stylesheet files (`.css`/`.scss`/`.sass`/`.less`/`.styl`). */
+ | 'style'
+/** Source files — for AOT-invisible shapes a project wants to forbid. */
+ | 'ts';
+export interface IPolicyRule {
+    /** Stable id, surfaced in findings and selectable with `--only`. */
+    readonly id: string;
+    /** What the rule guards / why it matters. */
+    readonly description?: string;
+    /** Which surface to scan. */
+    readonly surface: PolicySurface;
+    /**
+     * Project-relative globs. When omitted, a surface-appropriate default is used
+     * (`**\/*.html` + inline templates for `template`, common stylesheet
+     * extensions for `style`, `**\/*.ts`/`.tsx` for `ts`).
+     */
+    readonly files?: readonly string[];
+    /**
+     * Regex source matched against the surface content. Capture group 1, when
+     * present, is reported as the offending token; otherwise the whole match is.
+     */
+    readonly pattern: string;
+    /** Extra regex flags combined with the always-on `g` (e.g. `i`, `m`, `s`). */
+    readonly flags?: string;
+    /** Human message describing the violation. */
+    readonly message: string;
+    /** Optional remediation — e.g. the primitive/component to use instead. */
+    readonly suggest?: string;
+    /** `error` (default) fails the check; `warning` reports without failing. */
+    readonly severity?: 'error' | 'warning';
+}
+//# sourceMappingURL=policy-rule.d.ts.map

package/dist/policy/policy-rule.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy-rule.d.ts","sourceRoot":"","sources":["../../src/policy/policy-rule.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,wCAAwC;AACxC,MAAM,MAAM,aAAa;AACvB,iFAAiF;AAC/E,UAAU;AACZ,iEAAiE;GAC/D,OAAO;AACT,yEAAyE;GACvE,IAAI,CAAC;AAET,MAAM,WAAW,WAAW;IAC1B,oEAAoE;IACpE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,6CAA6C;IAC7C,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,6BAA6B;IAC7B,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,8EAA8E;IAC9E,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,8CAA8C;IAC9C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,0EAA0E;IAC1E,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,4EAA4E;IAC5E,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACzC"}

package/dist/policy/policy-rule.js

@@ -0,0 +1,15 @@
+/**
+ * Policy-lint rules — the "template/markup/style/ts" plane.
+ *
+ * Some violations compile AOT-green because they live on surfaces the type
+ * checker and structural search can't see: raw markup in `.html` files and
+ * inline `template:` strings, stylesheet content, and a handful of
+ * AOT-invisible TS shapes. `shrk policy-lint` runs deterministic, data-defined
+ * pattern rules over exactly those surfaces.
+ *
+ * The engine is generic — no framework or project specifics. A project supplies
+ * the rules as data via `sharkcraft.config.ts` `policyRules[]` (or a pack); each
+ * rule names a surface, a regex, and a human message (optionally a suggested
+ * replacement primitive). No AI.
+ */
+export {};

package/dist/reuse/reuse-primitive.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Reuse primitives — the "use the existing thing" plane.
+ *
+ * The single most-violated rule in many large codebases is "reuse the canonical
+ * primitive instead of re-implementing it." An agent told to discover the
+ * primitive by `grep` / reading a barrel file structurally cannot: the symbol
+ * name it needs isn't in the barrel text (a barrel is `export *`), and deep
+ * utilities sit many levels down, ungreppable.
+ *
+ * `shrk reuse <intent>` closes that gap. A project declares its canonical
+ * primitives as data via `sharkcraft.config.ts` `reusePrimitives[]`, keyed by
+ * role/intent. The command matches the intent to a primitive, then uses the
+ * code graph to resolve the symbol to its real declaration, its sibling
+ * exports, and real consumer files to copy. For the public import path it uses
+ * the configured `importPath`; if omitted, it surfaces a re-exporting barrel as
+ * a hint (it never fabricates a module specifier from a deep file path).
+ *
+ * The registry is generic — no project specifics live in shrk. No AI.
+ */
+export interface IReusePrimitive {
+    /** The canonical exported symbol to reuse (e.g. `Button`, `useDebounce`). */
+    readonly symbol: string;
+    /**
+     * Role / intent labels this primitive satisfies. `shrk reuse "<intent>"`
+     * matches the query tokens against these (plus `keywords`, `symbol`,
+     * `description`). e.g. `['text input', 'form control']`.
+     */
+    readonly roles: readonly string[];
+    /**
+     * The public import specifier consumers should import the symbol FROM
+     * (the barrel/package entry, e.g. `@scope/ui`). Strongly recommended: it is
+     * the only source of a copy-pasteable import line. When omitted, `shrk reuse`
+     * shows the declaration site and a re-exporting barrel hint instead.
+     */
+    readonly importPath?: string;
+    /** One-line description of when to reach for this primitive. */
+    readonly description?: string;
+    /** Extra free-text keywords to widen intent matching. */
+    readonly keywords?: readonly string[];
+}
+//# sourceMappingURL=reuse-primitive.d.ts.map

package/dist/reuse/reuse-primitive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reuse-primitive.d.ts","sourceRoot":"","sources":["../../src/reuse/reuse-primitive.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,MAAM,WAAW,eAAe;IAC9B,6EAA6E;IAC7E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,gEAAgE;IAChE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,yDAAyD;IACzD,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC"}

package/dist/reuse/reuse-primitive.js

@@ -0,0 +1,20 @@
+/**
+ * Reuse primitives — the "use the existing thing" plane.
+ *
+ * The single most-violated rule in many large codebases is "reuse the canonical
+ * primitive instead of re-implementing it." An agent told to discover the
+ * primitive by `grep` / reading a barrel file structurally cannot: the symbol
+ * name it needs isn't in the barrel text (a barrel is `export *`), and deep
+ * utilities sit many levels down, ungreppable.
+ *
+ * `shrk reuse <intent>` closes that gap. A project declares its canonical
+ * primitives as data via `sharkcraft.config.ts` `reusePrimitives[]`, keyed by
+ * role/intent. The command matches the intent to a primitive, then uses the
+ * code graph to resolve the symbol to its real declaration, its sibling
+ * exports, and real consumer files to copy. For the public import path it uses
+ * the configured `importPath`; if omitted, it surfaces a re-exporting barrel as
+ * a hint (it never fabricates a module specifier from a deep file path).
+ *
+ * The registry is generic — no project specifics live in shrk. No AI.
+ */
+export {};

package/dist/wiring/wiring-rule.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Wiring rules — the "completeness plane".
+ *
+ * Boundary/architecture rules cover the DIRECTION plane: which imports a file
+ * may NOT make. Wiring rules cover the complementary COMPLETENESS plane: a
+ * value/identifier that is DECLARED in one place must also be REGISTERED
+ * (wired up) somewhere else, or the build is green but the feature silently
+ * does nothing at runtime ("declared but not wired").
+ *
+ * A rule is a pure, data-defined set-membership check across files — the same
+ * extraction the boundary engine runs, but over captured string tokens instead
+ * of import paths. Each rule:
+ *   - collects the DECLARED token set (capture group 1 of `declared.pattern`
+ *     over the files matching `declared.files`), and
+ *   - the REGISTERED token set (likewise from `registered`), then
+ *   - flags every declared token that is NOT in the registered set.
+ *
+ * The engine is generic and deterministic (no AI, no language-specific
+ * knowledge). Projects supply the rules as data via
+ * `sharkcraft.config.ts` `wiringRules[]` (or a pack), so the engine never
+ * hard-codes any project-specific identifier.
+ */
+/** One side (declared or registered) of a wiring rule: where to look + what to capture. */
+export interface IWiringSource {
+    /** Project-relative globs selecting the files to scan (`**`/`*`/`?` supported). */
+    readonly files: readonly string[];
+    /**
+     * Regex source. Capture group 1 is the token. Matched per-file with the `g`
+     * flag always applied; add others (e.g. `i`, `m`) via `flags`.
+     */
+    readonly pattern: string;
+    /** Extra regex flags to combine with the always-on `g`. */
+    readonly flags?: string;
+}
+export interface IWiringRule {
+    /** Stable id, surfaced in findings and usable with `--only`. */
+    readonly id: string;
+    /** Human-readable description of what the rule guarantees. */
+    readonly description?: string;
+    /** `error` (default) fails the check / gate; `warning` reports without failing. */
+    readonly severity?: 'error' | 'warning';
+    /** Tokens that are declared/used and therefore MUST be wired up. */
+    readonly declared: IWiringSource;
+    /** The registered superset the declared tokens must belong to. */
+    readonly registered: IWiringSource;
+    /** Remediation hint shown on every violation of this rule. */
+    readonly hint?: string;
+}
+//# sourceMappingURL=wiring-rule.d.ts.map

package/dist/wiring/wiring-rule.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wiring-rule.d.ts","sourceRoot":"","sources":["../../src/wiring/wiring-rule.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,2FAA2F;AAC3F,MAAM,WAAW,aAAa;IAC5B,mFAAmF;IACnF,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,WAAW;IAC1B,gEAAgE;IAChE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,mFAAmF;IACnF,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACxC,oEAAoE;IACpE,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,kEAAkE;IAClE,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC;IACnC,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB"}

package/dist/wiring/wiring-rule.js

@@ -0,0 +1,23 @@
+/**
+ * Wiring rules — the "completeness plane".
+ *
+ * Boundary/architecture rules cover the DIRECTION plane: which imports a file
+ * may NOT make. Wiring rules cover the complementary COMPLETENESS plane: a
+ * value/identifier that is DECLARED in one place must also be REGISTERED
+ * (wired up) somewhere else, or the build is green but the feature silently
+ * does nothing at runtime ("declared but not wired").
+ *
+ * A rule is a pure, data-defined set-membership check across files — the same
+ * extraction the boundary engine runs, but over captured string tokens instead
+ * of import paths. Each rule:
+ *   - collects the DECLARED token set (capture group 1 of `declared.pattern`
+ *     over the files matching `declared.files`), and
+ *   - the REGISTERED token set (likewise from `registered`), then
+ *   - flags every declared token that is NOT in the registered set.
+ *
+ * The engine is generic and deterministic (no AI, no language-specific
+ * knowledge). Projects supply the rules as data via
+ * `sharkcraft.config.ts` `wiringRules[]` (or a pack), so the engine never
+ * hard-codes any project-specific identifier.
+ */
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shrkcrft/core",
-  "version": "0.1.0-alpha.21",
+  "version": "0.1.0-alpha.22",
   "description": "SharkCraft core primitives: Result, AppError, logger, file-system abstraction, path/string/object utils, IDs.",
   "license": "MIT",
   "author": "SharkCraft contributors",