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

package/dist/index.d.ts

@@ -2,4 +2,5 @@ export * from './rule.js';
 export * from './rule-query.js';
 export * from './rule-formatter.js';
 export * from './rule-service.js';
+export * from './rule-applicability.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,yBAAyB,CAAC"}

package/dist/index.js

@@ -2,3 +2,4 @@ export * from "./rule.js";
 export * from "./rule-query.js";
 export * from "./rule-formatter.js";
 export * from "./rule-service.js";
+export * from "./rule-applicability.js";

package/dist/rule-applicability.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Heuristic file matchers for knowledge-model rules.
+ *
+ * Rules in the knowledge model don't carry path patterns directly the way
+ * boundary rules do. Consumers that need "which files does this rule apply
+ * to?" derive it from two sources, in order:
+ *
+ *   1. **Explicit**: `rule.metadata.appliesTo` — an array of glob patterns.
+ *      Authoritative when present.
+ *   2. **Tag-based heuristics**: well-known tags map to file patterns. For
+ *      example a rule tagged `mcp` likely applies to files under
+ *      `packages/mcp-server/**`. The map is intentionally conservative — when
+ *      no tag matches, the rule is *not* matched (better silent than noisy).
+ *
+ * Authors who want predictable matching set `metadata.appliesTo`.
+ *
+ * This lives in `@shrkcrft/rules` (a low layer) so BOTH the rule-graph bridge
+ * (`shrk rule-graph for <file>`) and the inspector's `shrk why <file>` share a
+ * single source of truth — otherwise the two surfaces drift on which rules
+ * apply to a file.
+ */
+export interface IRuleApplicability {
+    /** Glob patterns to match against file paths. */
+    patterns: readonly string[];
+    /**
+     * When non-empty, the rule applies to every file whose `tags` array
+     * intersects this set. Currently used by `testing`-tagged rules.
+     */
+    fileTags: readonly string[];
+    /** How we derived the applicability — useful for diagnostics. */
+    source: 'metadata' | 'tags' | 'none';
+}
+export declare function deriveApplicability(rule: {
+    tags?: readonly string[];
+    metadata?: Readonly<Record<string, unknown>>;
+}): IRuleApplicability;
+//# sourceMappingURL=rule-applicability.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"rule-applicability.d.ts","sourceRoot":"","sources":["../src/rule-applicability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAyBH,MAAM,WAAW,kBAAkB;IACjC,iDAAiD;IACjD,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B;;;OAGG;IACH,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,iEAAiE;IACjE,MAAM,EAAE,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;CACtC;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE;IACxC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAC9C,GAAG,kBAAkB,CAwBrB"}

package/dist/rule-applicability.js

@@ -0,0 +1,69 @@
+/**
+ * Heuristic file matchers for knowledge-model rules.
+ *
+ * Rules in the knowledge model don't carry path patterns directly the way
+ * boundary rules do. Consumers that need "which files does this rule apply
+ * to?" derive it from two sources, in order:
+ *
+ *   1. **Explicit**: `rule.metadata.appliesTo` — an array of glob patterns.
+ *      Authoritative when present.
+ *   2. **Tag-based heuristics**: well-known tags map to file patterns. For
+ *      example a rule tagged `mcp` likely applies to files under
+ *      `packages/mcp-server/**`. The map is intentionally conservative — when
+ *      no tag matches, the rule is *not* matched (better silent than noisy).
+ *
+ * Authors who want predictable matching set `metadata.appliesTo`.
+ *
+ * This lives in `@shrkcrft/rules` (a low layer) so BOTH the rule-graph bridge
+ * (`shrk rule-graph for <file>`) and the inspector's `shrk why <file>` share a
+ * single source of truth — otherwise the two surfaces drift on which rules
+ * apply to a file.
+ */
+const TAG_PATTERNS = new Map([
+    // Engine packages.
+    ['mcp', ['packages/mcp-server/**']],
+    ['cli', ['packages/cli/**']],
+    ['dashboard', ['packages/dashboard/**', 'packages/dashboard-api/**']],
+    ['generator', ['packages/generator/**']],
+    ['importer', ['packages/importer/**']],
+    ['inspector', ['packages/inspector/**']],
+    ['packs', ['packages/packs/**']],
+    ['core', ['packages/core/**']],
+    // Asset categories.
+    ['boundaries', ['sharkcraft/boundaries.ts', 'packages/boundaries/**']],
+    ['rules', ['sharkcraft/rules.ts', 'packages/rules/**']],
+    ['paths', ['sharkcraft/paths.ts', 'packages/paths/**']],
+    ['templates', ['sharkcraft/templates.ts', 'packages/templates/**']],
+    ['pipelines', ['sharkcraft/pipelines.ts', 'packages/pipelines/**']],
+    ['presets', ['sharkcraft/presets.ts', 'packages/presets/**']],
+    // Cross-cutting concerns.
+    ['imports', ['packages/**/*.ts']],
+    ['testing', []], // signal-only; consumers attach via the file's `tags: test` separately
+    ['tests', []],
+]);
+export function deriveApplicability(rule) {
+    const explicit = rule.metadata?.['appliesTo'];
+    if (Array.isArray(explicit) && explicit.every((p) => typeof p === 'string')) {
+        return { patterns: explicit, fileTags: [], source: 'metadata' };
+    }
+    const tags = rule.tags ?? [];
+    const patterns = [];
+    const fileTags = [];
+    for (const tag of tags) {
+        if (tag === 'testing' || tag === 'tests') {
+            fileTags.push('test');
+            continue;
+        }
+        const mapped = TAG_PATTERNS.get(tag);
+        if (mapped) {
+            for (const p of mapped) {
+                if (!patterns.includes(p))
+                    patterns.push(p);
+            }
+        }
+    }
+    if (patterns.length === 0 && fileTags.length === 0) {
+        return { patterns: [], fileTags: [], source: 'none' };
+    }
+    return { patterns, fileTags, source: 'tags' };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shrkcrft/rules",
-  "version": "0.1.0-alpha.21",
+  "version": "0.1.0-alpha.22",
   "description": "SharkCraft rules service: typed rule entries, relevance lookup, AI formatting.",
   "license": "MIT",
   "author": "SharkCraft contributors",
@@ -43,8 +43,8 @@
     "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@shrkcrft/core": "^0.1.0-alpha.21",
-    "@shrkcrft/knowledge": "^0.1.0-alpha.21"
+    "@shrkcrft/core": "^0.1.0-alpha.22",
+    "@shrkcrft/knowledge": "^0.1.0-alpha.22"
   },
   "publishConfig": {
     "access": "public"