@shrkcrft/context-planner 0.1.0-alpha.10

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export * from './schema/context-pack.js';
+export * from './intent/classify-intent.js';
+export * from './intent/benchmark.js';
+export * from './intent/starter-benchmark.js';
+export * from './ranker/score-files.js';
+export * from './planner/plan-context.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":"AAAA,cAAc,0BAA0B,CAAC;AACzC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,uBAAuB,CAAC;AACtC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,yBAAyB,CAAC;AACxC,cAAc,2BAA2B,CAAC"}

package/dist/index.js

@@ -0,0 +1,6 @@
+export * from "./schema/context-pack.js";
+export * from "./intent/classify-intent.js";
+export * from "./intent/benchmark.js";
+export * from "./intent/starter-benchmark.js";
+export * from "./ranker/score-files.js";
+export * from "./planner/plan-context.js";

package/dist/intent/benchmark.d.ts

@@ -0,0 +1,56 @@
+import type { TaskIntent } from '../schema/context-pack.js';
+export declare const INTENT_BENCHMARK_SCHEMA: "sharkcraft.intent-benchmark/v1";
+/**
+ * One labelled task → expected-intent pair. The benchmark runs every
+ * case through `classifyIntent` and reports per-case + aggregate
+ * accuracy. Optional `notes` lets authors leave a hint about why a
+ * particular phrasing was added (often after a regression).
+ */
+export interface IIntentBenchmarkCase {
+    task: string;
+    expected: TaskIntent;
+    notes?: string;
+}
+export interface IIntentBenchmark {
+    schema: typeof INTENT_BENCHMARK_SCHEMA;
+    cases: readonly IIntentBenchmarkCase[];
+}
+export interface IIntentBenchmarkRunCase {
+    task: string;
+    expected: TaskIntent;
+    actual: TaskIntent;
+    passed: boolean;
+}
+export interface IIntentBenchmarkRun {
+    schema: typeof INTENT_BENCHMARK_SCHEMA;
+    total: number;
+    passed: number;
+    failed: number;
+    /** Accuracy in [0, 1]. */
+    accuracy: number;
+    cases: readonly IIntentBenchmarkRunCase[];
+    /** ISO timestamp the run completed. */
+    ranAt: string;
+}
+/**
+ * Read the benchmark fixture from `sharkcraft/intent-benchmark.json`
+ * (NOT under `.sharkcraft/` — this is an author-provided, checked-in
+ * fixture, not derived state). Returns undefined when missing or when
+ * the file is unparseable; the caller should treat that as "no
+ * benchmark configured" rather than an error.
+ */
+export declare function loadIntentBenchmark(projectRoot: string): IIntentBenchmark | undefined;
+/**
+ * Run the benchmark in-process. Pure — no side effects, no I/O beyond
+ * the input. Callers persist the run via `writeBenchmarkRun` when they
+ * want the doctor to surface it.
+ */
+export declare function runIntentBenchmark(benchmark: IIntentBenchmark): IIntentBenchmarkRun;
+export declare const INTENT_BENCHMARK_RUN_REL: ".sharkcraft/context-planner/intent-benchmark.json";
+/**
+ * Persist a benchmark run so the doctor can surface accuracy without
+ * re-running the fixture on every doctor invocation.
+ */
+export declare function writeBenchmarkRun(projectRoot: string, run: IIntentBenchmarkRun): string;
+export declare function readBenchmarkRun(projectRoot: string): IIntentBenchmarkRun | undefined;
+//# sourceMappingURL=benchmark.d.ts.map

package/dist/intent/benchmark.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"benchmark.d.ts","sourceRoot":"","sources":["../../src/intent/benchmark.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAE5D,eAAO,MAAM,uBAAuB,EAAG,gCAAyC,CAAC;AAEjF;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,UAAU,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,OAAO,uBAAuB,CAAC;IACvC,KAAK,EAAE,SAAS,oBAAoB,EAAE,CAAC;CACxC;AAED,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,UAAU,CAAC;IACrB,MAAM,EAAE,UAAU,CAAC;IACnB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,OAAO,uBAAuB,CAAC;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,0BAA0B;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,SAAS,uBAAuB,EAAE,CAAC;IAC1C,uCAAuC;IACvC,KAAK,EAAE,MAAM,CAAC;CACf;AAID;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS,CAWrF;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,gBAAgB,GAC1B,mBAAmB,CAmBrB;AAED,eAAO,MAAM,wBAAwB,EACnC,mDAA4D,CAAC;AAE/D;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,MAAM,EACnB,GAAG,EAAE,mBAAmB,GACvB,MAAM,CAKR;AAED,wBAAgB,gBAAgB,CAC9B,WAAW,EAAE,MAAM,GAClB,mBAAmB,GAAG,SAAS,CAUjC"}

package/dist/intent/benchmark.js

@@ -0,0 +1,79 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { classifyIntent } from "./classify-intent.js";
+export const INTENT_BENCHMARK_SCHEMA = 'sharkcraft.intent-benchmark/v1';
+const BENCHMARK_REL = 'sharkcraft/intent-benchmark.json';
+/**
+ * Read the benchmark fixture from `sharkcraft/intent-benchmark.json`
+ * (NOT under `.sharkcraft/` — this is an author-provided, checked-in
+ * fixture, not derived state). Returns undefined when missing or when
+ * the file is unparseable; the caller should treat that as "no
+ * benchmark configured" rather than an error.
+ */
+export function loadIntentBenchmark(projectRoot) {
+    const abs = nodePath.join(projectRoot, BENCHMARK_REL);
+    if (!existsSync(abs))
+        return undefined;
+    try {
+        const raw = JSON.parse(readFileSync(abs, 'utf8'));
+        if (raw.schema !== INTENT_BENCHMARK_SCHEMA)
+            return undefined;
+        if (!Array.isArray(raw.cases))
+            return undefined;
+        return raw;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Run the benchmark in-process. Pure — no side effects, no I/O beyond
+ * the input. Callers persist the run via `writeBenchmarkRun` when they
+ * want the doctor to surface it.
+ */
+export function runIntentBenchmark(benchmark) {
+    const cases = [];
+    let passed = 0;
+    for (const c of benchmark.cases) {
+        const actual = classifyIntent(c.task);
+        const ok = actual === c.expected;
+        if (ok)
+            passed += 1;
+        cases.push({ task: c.task, expected: c.expected, actual, passed: ok });
+    }
+    const total = benchmark.cases.length;
+    return {
+        schema: INTENT_BENCHMARK_SCHEMA,
+        total,
+        passed,
+        failed: total - passed,
+        accuracy: total === 0 ? 1 : passed / total,
+        cases,
+        ranAt: new Date().toISOString(),
+    };
+}
+export const INTENT_BENCHMARK_RUN_REL = '.sharkcraft/context-planner/intent-benchmark.json';
+/**
+ * Persist a benchmark run so the doctor can surface accuracy without
+ * re-running the fixture on every doctor invocation.
+ */
+export function writeBenchmarkRun(projectRoot, run) {
+    const abs = nodePath.join(projectRoot, INTENT_BENCHMARK_RUN_REL);
+    mkdirSync(nodePath.dirname(abs), { recursive: true });
+    writeFileSync(abs, JSON.stringify(run, null, 2), 'utf8');
+    return abs;
+}
+export function readBenchmarkRun(projectRoot) {
+    const abs = nodePath.join(projectRoot, INTENT_BENCHMARK_RUN_REL);
+    if (!existsSync(abs))
+        return undefined;
+    try {
+        const raw = JSON.parse(readFileSync(abs, 'utf8'));
+        if (raw.schema !== INTENT_BENCHMARK_SCHEMA)
+            return undefined;
+        return raw;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/intent/classify-intent.d.ts

@@ -0,0 +1,13 @@
+import type { TaskIntent } from '../schema/context-pack.js';
+/**
+ * Deterministic, keyword-based task intent classifier.
+ *
+ * No embedded model. Maps free-text task strings to an intent label so
+ * the ranker can tune its weights. Conflicts resolve in priority order:
+ *   release > migration > bug-fix > refactor > docs > feature
+ *
+ * `unknown` is returned when no keyword matches — the ranker then uses
+ * its neutral baseline weights.
+ */
+export declare function classifyIntent(task: string): TaskIntent;
+//# sourceMappingURL=classify-intent.d.ts.map

package/dist/intent/classify-intent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"classify-intent.d.ts","sourceRoot":"","sources":["../../src/intent/classify-intent.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAE5D;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAoBvD"}

package/dist/intent/classify-intent.js

@@ -0,0 +1,42 @@
+/**
+ * Deterministic, keyword-based task intent classifier.
+ *
+ * No embedded model. Maps free-text task strings to an intent label so
+ * the ranker can tune its weights. Conflicts resolve in priority order:
+ *   release > migration > bug-fix > refactor > docs > feature
+ *
+ * `unknown` is returned when no keyword matches — the ranker then uses
+ * its neutral baseline weights.
+ */
+export function classifyIntent(task) {
+    const t = task.toLowerCase();
+    if (matchAny(t, ['release', 'cut release', 'publish', 'preflight', 'tag ']))
+        return 'release';
+    if (matchAny(t, ['migration', 'migrate', 'upgrade', 'deprecat']))
+        return 'migration';
+    if (matchAny(t, ['bug', 'fix', 'error', 'broken', 'regression', 'crash', 'throws', 'fails']))
+        return 'bug-fix';
+    if (matchAny(t, ['refactor', 'cleanup', 'simplify', 'extract', 'rename', 'move']))
+        return 'refactor';
+    if (matchAny(t, ['docs', 'document', 'readme', 'guide', 'tutorial', 'explain']))
+        return 'docs';
+    if (matchAny(t, [
+        'add ',
+        'create ',
+        'implement',
+        'feature',
+        'support for',
+        'enable ',
+        'introduce',
+        'new ',
+    ]))
+        return 'feature';
+    return 'unknown';
+}
+function matchAny(t, needles) {
+    for (const n of needles) {
+        if (t.includes(n))
+            return true;
+    }
+    return false;
+}

package/dist/intent/starter-benchmark.d.ts

@@ -0,0 +1,13 @@
+import { type IIntentBenchmark } from './benchmark.js';
+/**
+ * Curated starter benchmark covering the canonical phrasings the
+ * classifier should handle on day one. Used by `shrk context
+ * benchmark seed` to bootstrap a fresh fixture. Authors are expected
+ * to grow the set per project — especially when a new task verb
+ * starts cropping up in real PRs but lands in `unknown`.
+ *
+ * Conflict-resolution priority in the classifier today:
+ *   release > migration > bug-fix > refactor > docs > feature
+ */
+export declare const STARTER_INTENT_BENCHMARK: IIntentBenchmark;
+//# sourceMappingURL=starter-benchmark.d.ts.map

package/dist/intent/starter-benchmark.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"starter-benchmark.d.ts","sourceRoot":"","sources":["../../src/intent/starter-benchmark.ts"],"names":[],"mappings":"AAAA,OAAO,EAA2B,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEhF;;;;;;;;;GASG;AACH,eAAO,MAAM,wBAAwB,EAAE,gBAoCtC,CAAC"}

package/dist/intent/starter-benchmark.js

@@ -0,0 +1,43 @@
+import { INTENT_BENCHMARK_SCHEMA } from "./benchmark.js";
+/**
+ * Curated starter benchmark covering the canonical phrasings the
+ * classifier should handle on day one. Used by `shrk context
+ * benchmark seed` to bootstrap a fresh fixture. Authors are expected
+ * to grow the set per project — especially when a new task verb
+ * starts cropping up in real PRs but lands in `unknown`.
+ *
+ * Conflict-resolution priority in the classifier today:
+ *   release > migration > bug-fix > refactor > docs > feature
+ */
+export const STARTER_INTENT_BENCHMARK = {
+    schema: INTENT_BENCHMARK_SCHEMA,
+    cases: [
+        // bug-fix
+        { task: 'fix the broken login flow', expected: 'bug-fix' },
+        { task: 'auth crashes when password is empty', expected: 'bug-fix' },
+        { task: 'regression on date parsing', expected: 'bug-fix' },
+        { task: 'NPE in the dashboard renderer', expected: 'bug-fix', notes: 'NPE keyword maps via `error`' },
+        // feature
+        { task: 'add a dark mode toggle to settings', expected: 'feature' },
+        { task: 'create a new export-as-csv command', expected: 'feature' },
+        { task: 'implement webhook delivery retries', expected: 'feature' },
+        { task: 'introduce per-tenant rate limiting', expected: 'feature' },
+        // refactor
+        { task: 'refactor the dashboard panel registry', expected: 'refactor' },
+        { task: 'rename `processRow` to `applyRow`', expected: 'refactor' },
+        { task: 'extract auth helpers into their own module', expected: 'refactor' },
+        { task: 'simplify the search-index builder', expected: 'refactor' },
+        // docs
+        { task: 'update the README quickstart', expected: 'docs' },
+        { task: 'document the new context-planner API', expected: 'docs' },
+        { task: 'write a guide for arch contracts', expected: 'docs' },
+        // release
+        { task: 'cut release 0.2.0', expected: 'release' },
+        { task: 'run release preflight', expected: 'release' },
+        { task: 'publish alpha tag for the cli package', expected: 'release' },
+        // migration
+        { task: 'migrate from joi to zod', expected: 'migration' },
+        { task: 'upgrade typescript to 5.6', expected: 'migration' },
+        { task: 'deprecate the legacy boundary API', expected: 'migration' },
+    ],
+};

package/dist/planner/plan-context.d.ts

@@ -0,0 +1,29 @@
+import { type IContextPack } from '../schema/context-pack.js';
+export interface IPlanContextOptions {
+    projectRoot: string;
+    /** Free-text task description. */
+    task: string;
+    /** Hard token budget. Default 8000. */
+    budgetTokens?: number;
+    /** Pre-selected file hints (will be boosted in ranking). */
+    hintedFiles?: readonly string[];
+    /** Pre-selected package hints (path prefix `packages/<x>`). */
+    hintedPackages?: readonly string[];
+    /** Cap on returned files. Default 30 (after budget pruning). */
+    maxFiles?: number;
+    /**
+     * If true and the bridge isn't built, fall back to no rule/path/template
+     * info (still produces a useful pack). Default true.
+     */
+    tolerateMissingBridge?: boolean;
+}
+/**
+ * Produce a deterministic context pack for an AI coding agent.
+ *
+ * Inputs are graph + bridge + free-text task. Output fits the requested
+ * token budget within a small tolerance. The same task on the same repo
+ * returns the same pack — a property that lets agents share / replay
+ * context.
+ */
+export declare function planContext(options: IPlanContextOptions): IContextPack;
+//# sourceMappingURL=plan-context.d.ts.map

package/dist/planner/plan-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan-context.d.ts","sourceRoot":"","sources":["../../src/planner/plan-context.ts"],"names":[],"mappings":"AAKA,OAAO,EAEL,KAAK,YAAY,EAMlB,MAAM,2BAA2B,CAAC;AAInC,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,uCAAuC;IACvC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,4DAA4D;IAC5D,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,+DAA+D;IAC/D,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,gEAAgE;IAChE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,mBAAmB,GAAG,YAAY,CAwGtE"}

package/dist/planner/plan-context.js

@@ -0,0 +1,219 @@
+import { GraphQueryApi, GraphStore, } from '@shrkcrft/graph';
+import { BridgeStore, RuleGraphQueryApi } from '@shrkcrft/rule-graph';
+import { CONTEXT_PACK_SCHEMA, } from "../schema/context-pack.js";
+import { classifyIntent } from "../intent/classify-intent.js";
+import { scoreFiles } from "../ranker/score-files.js";
+/**
+ * Produce a deterministic context pack for an AI coding agent.
+ *
+ * Inputs are graph + bridge + free-text task. Output fits the requested
+ * token budget within a small tolerance. The same task on the same repo
+ * returns the same pack — a property that lets agents share / replay
+ * context.
+ */
+export function planContext(options) {
+    const diagnostics = [];
+    const budgetTokens = options.budgetTokens ?? 8000;
+    const maxFiles = options.maxFiles ?? 30;
+    const tolerate = options.tolerateMissingBridge ?? true;
+    const graphStore = new GraphStore(options.projectRoot);
+    if (!graphStore.exists()) {
+        diagnostics.push("code-graph store missing — run `shrk graph index`");
+        return emptyPack(options.task, budgetTokens, diagnostics);
+    }
+    const api = GraphQueryApi.fromStore(options.projectRoot);
+    const intent = classifyIntent(options.task);
+    // 1. Rank.
+    const scored = scoreFiles(api, {
+        task: options.task,
+        intent,
+        ...(options.hintedFiles ? { hintedFiles: options.hintedFiles } : {}),
+        ...(options.hintedPackages ? { hintedPackages: options.hintedPackages } : {}),
+    });
+    // 2. Estimate tokens (deterministic, BPE-ish approximation).
+    const ranked = scored
+        .slice(0, maxFiles * 3) // start with a generous pre-pool before budget pruning
+        .map((s) => toRankedFile(s, api));
+    // 3. Token-budget pruning. Greedy include in score order until budget filled.
+    const accepted = [];
+    let used = 0;
+    let truncated = false;
+    for (const f of ranked) {
+        if (accepted.length >= maxFiles)
+            break;
+        if (used + f.estimatedTokens > budgetTokens) {
+            truncated = true;
+            continue;
+        }
+        accepted.push(f);
+        used += f.estimatedTokens;
+    }
+    if (scored.length > accepted.length)
+        truncated = true;
+    // 4. Bridge lookups for the selected file set.
+    let rules = [];
+    let paths = [];
+    let templates = [];
+    const bridgeStore = new BridgeStore(options.projectRoot);
+    if (bridgeStore.exists()) {
+        const bridgeApi = RuleGraphQueryApi.fromStores(options.projectRoot);
+        const seenRule = new Set();
+        const seenPath = new Set();
+        const seenTpl = new Set();
+        for (const f of accepted) {
+            const view = bridgeApi.forFile(f.path);
+            if (!view)
+                continue;
+            for (const h of view.rules) {
+                if (seenRule.has(h.target.id))
+                    continue;
+                seenRule.add(h.target.id);
+                rules.push({
+                    id: h.target.id,
+                    label: h.target.label,
+                    severity: h.edge.data?.['severity'] ?? undefined,
+                });
+            }
+            for (const h of view.paths) {
+                if (seenPath.has(h.target.id))
+                    continue;
+                seenPath.add(h.target.id);
+                paths.push({ id: h.target.id, label: h.target.label });
+            }
+            for (const h of view.templates) {
+                if (seenTpl.has(h.target.id))
+                    continue;
+                seenTpl.add(h.target.id);
+                templates.push({ id: h.target.id, label: h.target.label });
+            }
+        }
+    }
+    else if (tolerate) {
+        diagnostics.push("bridge store missing — rules/paths/templates omitted (run `shrk rule-graph index`)");
+    }
+    else {
+        diagnostics.push("bridge store missing");
+    }
+    // 5. Likely tests for the selected file set (importers + co-located).
+    const tests = collectTests(api, accepted);
+    // 6. Surface risks: cross-package edges, public-API touches, cycles in the selected set.
+    const risks = collectRisks(api, accepted);
+    // 7. Do-not-touch zones — generated files, vendored, dist, lock.
+    const doNotTouch = computeDoNotTouch(accepted);
+    return {
+        schema: CONTEXT_PACK_SCHEMA,
+        intent,
+        task: options.task,
+        files: accepted,
+        rules,
+        paths,
+        templates,
+        tests,
+        risks,
+        doNotTouch,
+        budget: { requested: budgetTokens, used, truncated },
+        diagnostics,
+    };
+}
+function toRankedFile(s, api) {
+    const node = s.node;
+    // Token estimate: 1 token ≈ 4 chars, plus a small fixed overhead.
+    const sizeBytes = node.data?.['sizeBytes'] ?? 2000;
+    const estimatedTokens = Math.max(40, Math.ceil(sizeBytes / 4));
+    // Bound the score to [0, 1].
+    const bounded = Math.max(0, Math.min(1, s.score / 3));
+    void api;
+    return {
+        path: node.path,
+        nodeId: node.id,
+        score: Math.round(bounded * 100) / 100,
+        estimatedTokens,
+        reasons: s.reasons,
+    };
+}
+function collectTests(api, files) {
+    const out = new Set();
+    for (const f of files) {
+        // Co-located: `__tests__/<name>.test.ts` or `<base>.test.ts`.
+        const candidates = guessTestPaths(f.path);
+        for (const c of candidates) {
+            const t = api.findFile(c);
+            if (t)
+                out.add(t.path);
+        }
+        // Importer tests: any file tagged `test` that imports this one.
+        for (const importer of api.importersOf(f.nodeId)) {
+            if (!(importer.tags ?? []).includes('test'))
+                continue;
+            if (importer.path)
+                out.add(importer.path);
+        }
+    }
+    return [...out].sort().slice(0, 50);
+}
+function guessTestPaths(path) {
+    // `packages/foo/src/bar.ts` → check `__tests__/bar.test.ts`, `bar.test.ts`, etc.
+    const out = [];
+    const lastSlash = path.lastIndexOf('/');
+    const dir = lastSlash >= 0 ? path.slice(0, lastSlash) : '.';
+    const base = (lastSlash >= 0 ? path.slice(lastSlash + 1) : path).replace(/\.[tj]sx?$/, '');
+    for (const ext of ['.test.ts', '.test.tsx', '.spec.ts']) {
+        out.push(`${dir}/__tests__/${base}${ext}`);
+        out.push(`${dir}/${base}${ext}`);
+    }
+    return out;
+}
+function collectRisks(api, files) {
+    const out = [];
+    let publicApiCount = 0;
+    let crossPackageCount = 0;
+    for (const f of files) {
+        if (/\/index\.ts$/.test(f.path) || /^index\.ts$/.test(f.path) || f.path.endsWith('.d.ts')) {
+            publicApiCount += 1;
+        }
+        for (const importer of api.importersOf(f.nodeId)) {
+            const pkgImporter = importer.path?.split('/').slice(0, 2).join('/');
+            const pkgFile = f.path.split('/').slice(0, 2).join('/');
+            if (pkgImporter && pkgFile && pkgImporter !== pkgFile)
+                crossPackageCount += 1;
+        }
+    }
+    if (publicApiCount > 0) {
+        out.push({
+            kind: 'public-api',
+            label: `${publicApiCount} selected file(s) are public-API entrypoints — changes ripple to consumers`,
+        });
+    }
+    if (crossPackageCount >= 5) {
+        out.push({
+            kind: 'cross-package',
+            label: `${crossPackageCount} cross-package importers of selected files`,
+        });
+    }
+    return out;
+}
+function computeDoNotTouch(files) {
+    const out = [];
+    for (const f of files) {
+        if (/\bdist\b|\bbuild\b|\.generated\.|\.lock$/.test(f.path)) {
+            out.push(f.path);
+        }
+    }
+    return out;
+}
+function emptyPack(task, budget, diagnostics) {
+    return {
+        schema: CONTEXT_PACK_SCHEMA,
+        intent: classifyIntent(task),
+        task,
+        files: [],
+        rules: [],
+        paths: [],
+        templates: [],
+        tests: [],
+        risks: [],
+        doNotTouch: [],
+        budget: { requested: budget, used: 0, truncated: false },
+        diagnostics,
+    };
+}

package/dist/ranker/score-files.d.ts

@@ -0,0 +1,45 @@
+import { GraphQueryApi, type INode } from '@shrkcrft/graph';
+import type { TaskIntent } from '../schema/context-pack.js';
+export interface IScoredFile {
+    node: INode;
+    score: number;
+    reasons: readonly string[];
+}
+export interface IScoreInput {
+    /** Free-text task. */
+    task: string;
+    /** Classified intent (drives weights). */
+    intent: TaskIntent;
+    /** Optional file hints from the caller (pre-selected). */
+    hintedFiles?: readonly string[];
+    /** Optional package hints. */
+    hintedPackages?: readonly string[];
+    /** Per-package weight multipliers from intent. */
+    weights?: Partial<IRankerWeights>;
+}
+export interface IRankerWeights {
+    /** Match between task keywords and file path. */
+    pathKeyword: number;
+    /** Match between task keywords and any declared symbol in the file. */
+    symbolKeyword: number;
+    /** File is among the caller's hints. */
+    hintedFile: number;
+    /** File belongs to a hinted package. */
+    hintedPackage: number;
+    /** File is a test for a ranked source file (followed-up only). */
+    testFollowup: number;
+    /** Penalty for generated files (subtract). */
+    generatedPenalty: number;
+    /** Penalty for test files when intent != bug-fix. */
+    testPenalty: number;
+}
+/**
+ * Rank every file node in the graph against the task. Returns scored
+ * files sorted descending by score, with explicit reasons attached so
+ * the agent can see why a file was picked.
+ *
+ * Deterministic — no LLM calls. Weights are intent-tunable but the
+ * keyword extractor and the scoring formula are pure.
+ */
+export declare function scoreFiles(api: GraphQueryApi, input: IScoreInput): readonly IScoredFile[];
+//# sourceMappingURL=score-files.d.ts.map

package/dist/ranker/score-files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"score-files.d.ts","sourceRoot":"","sources":["../../src/ranker/score-files.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,KAAK,KAAK,EAAE,MAAM,iBAAiB,CAAC;AAC5D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAE5D,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,KAAK,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,WAAW;IAC1B,sBAAsB;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,0CAA0C;IAC1C,MAAM,EAAE,UAAU,CAAC;IACnB,0DAA0D;IAC1D,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,8BAA8B;IAC9B,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,kDAAkD;IAClD,OAAO,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,cAAc;IAC7B,iDAAiD;IACjD,WAAW,EAAE,MAAM,CAAC;IACpB,uEAAuE;IACvE,aAAa,EAAE,MAAM,CAAC;IACtB,wCAAwC;IACxC,UAAU,EAAE,MAAM,CAAC;IACnB,wCAAwC;IACxC,aAAa,EAAE,MAAM,CAAC;IACtB,kEAAkE;IAClE,YAAY,EAAE,MAAM,CAAC;IACrB,8CAA8C;IAC9C,gBAAgB,EAAE,MAAM,CAAC;IACzB,qDAAqD;IACrD,WAAW,EAAE,MAAM,CAAC;CACrB;AAkBD;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,aAAa,EAAE,KAAK,EAAE,WAAW,GAAG,SAAS,WAAW,EAAE,CAkDzF"}

package/dist/ranker/score-files.js

@@ -0,0 +1,112 @@
+const DEFAULT_WEIGHTS = {
+    pathKeyword: 1.0,
+    symbolKeyword: 0.7,
+    hintedFile: 2.0,
+    hintedPackage: 0.5,
+    testFollowup: 0.4,
+    generatedPenalty: 0.6,
+    testPenalty: 0.3,
+};
+const STOPWORDS = new Set([
+    'a', 'an', 'and', 'or', 'the', 'of', 'for', 'to', 'in', 'on', 'with', 'add', 'make', 'do',
+    'is', 'are', 'be', 'as', 'at', 'by', 'from', 'that', 'this', 'it', 'i', 'we', 'our', 'your',
+    'should', 'want', 'need', 'please', 'can', 'could', 'would', 'use', 'using', 'also',
+]);
+/**
+ * Rank every file node in the graph against the task. Returns scored
+ * files sorted descending by score, with explicit reasons attached so
+ * the agent can see why a file was picked.
+ *
+ * Deterministic — no LLM calls. Weights are intent-tunable but the
+ * keyword extractor and the scoring formula are pure.
+ */
+export function scoreFiles(api, input) {
+    const weights = { ...DEFAULT_WEIGHTS, ...applyIntentTuning(input.intent), ...input.weights };
+    const keywords = extractKeywords(input.task);
+    const hintedFiles = new Set(input.hintedFiles ?? []);
+    const hintedPackages = new Set(input.hintedPackages ?? []);
+    const candidates = [];
+    for (const node of api.allFiles()) {
+        const reasons = [];
+        let score = 0;
+        if (hintedFiles.has(node.path)) {
+            score += weights.hintedFile;
+            reasons.push('hinted file');
+        }
+        if (hintedPackages.size > 0) {
+            const pkg = node.path.split('/').slice(0, 2).join('/');
+            if (hintedPackages.has(pkg)) {
+                score += weights.hintedPackage;
+                reasons.push('hinted package');
+            }
+        }
+        if (keywords.size > 0) {
+            const pathHits = countKeywordHits(node.path, keywords);
+            if (pathHits > 0) {
+                score += weights.pathKeyword * Math.min(1, pathHits / 2);
+                reasons.push(`path matches ${pathHits} keyword(s)`);
+            }
+            // Symbol-name matches.
+            const symbolMatches = api.symbolsIn(node.id).filter((s) => keywords.has(s.label.toLowerCase()));
+            if (symbolMatches.length > 0) {
+                score += weights.symbolKeyword * Math.min(1, symbolMatches.length / 3);
+                reasons.push(`declares ${symbolMatches.length} matching symbol(s)`);
+            }
+        }
+        // Penalty for generated/test files (unless intent justifies them).
+        if ((node.tags ?? []).includes('generated')) {
+            score -= weights.generatedPenalty;
+            reasons.push('generated (penalty)');
+        }
+        if ((node.tags ?? []).includes('test')) {
+            if (input.intent !== 'bug-fix') {
+                score -= weights.testPenalty;
+                reasons.push('test (intent-mismatched penalty)');
+            }
+        }
+        if (score <= 0)
+            continue;
+        candidates.push({ node, score, reasons });
+    }
+    candidates.sort((a, b) => b.score - a.score || a.node.path.localeCompare(b.node.path));
+    return candidates;
+}
+function applyIntentTuning(intent) {
+    switch (intent) {
+        case 'bug-fix':
+            return { testFollowup: 0.6, testPenalty: -0.2 }; // negative penalty = boost
+        case 'refactor':
+            return { symbolKeyword: 0.9 };
+        case 'docs':
+            return { pathKeyword: 1.2 };
+        case 'release':
+            return { hintedPackage: 0.7 };
+        case 'migration':
+            return { symbolKeyword: 1.0, pathKeyword: 1.1 };
+        case 'feature':
+        case 'unknown':
+        default:
+            return {};
+    }
+}
+function extractKeywords(task) {
+    const out = new Set();
+    const tokens = task.toLowerCase().split(/[^a-z0-9_$]+/).filter(Boolean);
+    for (const t of tokens) {
+        if (t.length < 3)
+            continue;
+        if (STOPWORDS.has(t))
+            continue;
+        out.add(t);
+    }
+    return out;
+}
+function countKeywordHits(text, keywords) {
+    const lower = text.toLowerCase();
+    let n = 0;
+    for (const k of keywords) {
+        if (lower.includes(k))
+            n += 1;
+    }
+    return n;
+}

package/dist/schema/context-pack.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Compact, deterministic context pack consumable by AI coding agents.
+ *
+ * Output of `@shrkcrft/context-planner`. Stable JSON shape so an agent
+ * can persist node ids across turns and verify what was cut.
+ *
+ * Schema: sharkcraft.context-pack/v1.
+ */
+export declare const CONTEXT_PACK_SCHEMA: "sharkcraft.context-pack/v1";
+export type TaskIntent = 'feature' | 'bug-fix' | 'refactor' | 'docs' | 'release' | 'migration' | 'unknown';
+export interface IRankedFile {
+    /** Project-relative POSIX path. */
+    path: string;
+    /** Code-graph node id (`file:<path>`). */
+    nodeId: string;
+    /** Score in [0, 1]. Higher = more relevant. */
+    score: number;
+    /** Estimated token cost (approximate; deterministic). */
+    estimatedTokens: number;
+    /** Free-form reasons the file ranked. */
+    reasons: readonly string[];
+}
+export interface IRuleHit {
+    id: string;
+    label: string;
+    severity?: string;
+}
+export interface IPathHit {
+    id: string;
+    label: string;
+}
+export interface ITemplateHit {
+    id: string;
+    label: string;
+}
+export interface IRiskHit {
+    /** Risk category, e.g. 'cycle', 'public-api', 'cross-package'. */
+    kind: string;
+    /** Display label. */
+    label: string;
+    /** Related node ids (optional). */
+    refs?: readonly string[];
+}
+export interface IContextPack {
+    schema: typeof CONTEXT_PACK_SCHEMA;
+    intent: TaskIntent;
+    /** Free-text task as provided by the caller. */
+    task: string;
+    /** Ranked relevant files (after token-budget pruning). */
+    files: readonly IRankedFile[];
+    /** Rule-graph hits over the selected file set. */
+    rules: readonly IRuleHit[];
+    paths: readonly IPathHit[];
+    templates: readonly ITemplateHit[];
+    /** Likely tests for the file set. */
+    tests: readonly string[];
+    /** Surfaced risks: cycles, public-API touches, etc. */
+    risks: readonly IRiskHit[];
+    /**
+     * Files the agent should NOT modify in this pack — generated files,
+     * vendored code, lock files, dist/build outputs.
+     */
+    doNotTouch: readonly string[];
+    /** Token budget summary. */
+    budget: {
+        requested: number;
+        used: number;
+        /** True when the selection was capped by budget. */
+        truncated: boolean;
+    };
+    /** Free-form diagnostics. */
+    diagnostics: readonly string[];
+}
+//# sourceMappingURL=context-pack.d.ts.map

package/dist/schema/context-pack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-pack.d.ts","sourceRoot":"","sources":["../../src/schema/context-pack.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,EAAG,4BAAqC,CAAC;AAEzE,MAAM,MAAM,UAAU,GAClB,SAAS,GACT,SAAS,GACT,UAAU,GACV,MAAM,GACN,SAAS,GACT,WAAW,GACX,SAAS,CAAC;AAEd,MAAM,WAAW,WAAW;IAC1B,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,0CAA0C;IAC1C,MAAM,EAAE,MAAM,CAAC;IACf,+CAA+C;IAC/C,KAAK,EAAE,MAAM,CAAC;IACd,yDAAyD;IACzD,eAAe,EAAE,MAAM,CAAC;IACxB,yCAAyC;IACzC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,QAAQ;IACvB,kEAAkE;IAClE,IAAI,EAAE,MAAM,CAAC;IACb,qBAAqB;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,mCAAmC;IACnC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,OAAO,mBAAmB,CAAC;IACnC,MAAM,EAAE,UAAU,CAAC;IACnB,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,KAAK,EAAE,SAAS,WAAW,EAAE,CAAC;IAC9B,kDAAkD;IAClD,KAAK,EAAE,SAAS,QAAQ,EAAE,CAAC;IAC3B,KAAK,EAAE,SAAS,QAAQ,EAAE,CAAC;IAC3B,SAAS,EAAE,SAAS,YAAY,EAAE,CAAC;IACnC,qCAAqC;IACrC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,uDAAuD;IACvD,KAAK,EAAE,SAAS,QAAQ,EAAE,CAAC;IAC3B;;;OAGG;IACH,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B,4BAA4B;IAC5B,MAAM,EAAE;QACN,SAAS,EAAE,MAAM,CAAC;QAClB,IAAI,EAAE,MAAM,CAAC;QACb,oDAAoD;QACpD,SAAS,EAAE,OAAO,CAAC;KACpB,CAAC;IACF,6BAA6B;IAC7B,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CAChC"}

package/dist/schema/context-pack.js

@@ -0,0 +1,9 @@
+/**
+ * Compact, deterministic context pack consumable by AI coding agents.
+ *
+ * Output of `@shrkcrft/context-planner`. Stable JSON shape so an agent
+ * can persist node ids across turns and verify what was cut.
+ *
+ * Schema: sharkcraft.context-pack/v1.
+ */
+export const CONTEXT_PACK_SCHEMA = 'sharkcraft.context-pack/v1';

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@shrkcrft/context-planner",
+  "version": "0.1.0-alpha.10",
+  "description": "SharkCraft context planner: deterministic, token-budgeted context packs for AI coding agents. Combines code graph, rule-graph, and intent classification to pick the minimal relevant file set for a task.",
+  "license": "MIT",
+  "author": "SharkCraft contributors",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sharkcraft/sharkcraft.git",
+    "directory": "packages/context-planner"
+  },
+  "homepage": "https://github.com/sharkcraft/sharkcraft",
+  "bugs": {
+    "url": "https://github.com/sharkcraft/sharkcraft/issues"
+  },
+  "keywords": [
+    "sharkcraft",
+    "context-planner",
+    "ai-agent",
+    "ranker"
+  ],
+  "engines": {
+    "bun": ">=1.1.0",
+    "node": ">=18"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "@shrkcrft/core": "^0.1.0-alpha.10",
+    "@shrkcrft/graph": "^0.1.0-alpha.10",
+    "@shrkcrft/rule-graph": "^0.1.0-alpha.10"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}