clinkx 0.3.0 → 1.1.0

package/clinkx-workflows/dist/plan-review/context-policy.js

@@ -0,0 +1,146 @@
+/**
+ * A-7 — the non-overridable plan-review context policy.
+ *
+ * Reviewers see the immutable snapshot and repo source evidence — never the
+ * mutable original plan, and never some *other* plan workspace's `PLAN.md`.
+ * Because preflight runs a default-on full curator+finalizer delegate, one
+ * exclusion point is not enough, so this module supplies both:
+ *
+ *   (a) PRE-DISPATCH  — forced exclude globs folded into the curator's input,
+ *                       so the curator never selects the plan in the first place.
+ *   (b) POST-FILTER   — the finalized selection is stripped of anything that
+ *                       resolves to an excluded plan, because caller
+ *                       `cb_include_globs`/`cb_focus_paths` can otherwise
+ *                       re-admit exactly what (a) excluded.
+ *
+ * Neither is redundant: (a) stops the curator from wasting budget on the plan
+ * and from embedding it in the bundle body; (b) is what makes the exclusion
+ * actually SURVIVE caller globs and focus anchors.
+ */
+import { realpathSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+/**
+ * Any plan-workspace plan document. `generate-implementation-plan` owns this layout, so the
+ * pattern is fixed rather than caller-configurable.
+ */
+export const PLAN_WORKSPACE_EXCLUDE_GLOB = "**/.ai/plans/**/PLAN.md";
+/** Case-sensitive by design: `plan.md` is not the plan-workspace artifact. */
+const PLAN_WORKSPACE_PATH_PATTERN = /(?:^|\/)\.ai\/plans\/(?:[^/]+\/)*PLAN\.md$/;
+/** Whether `absolutePath` is a plan-workspace `.ai/plans/**\/PLAN.md`. */
+export function isPlanWorkspacePlanPath(absolutePath) {
+    return PLAN_WORKSPACE_PATH_PATTERN.test(absolutePath.split("\\").join("/"));
+}
+/**
+ * Best-effort canonicalization for comparison. A path that does not exist is
+ * still normalized, so a caller cannot dodge the check by pointing at a path
+ * they intend to create later.
+ */
+function canonicalize(path, workspaceRoot = process.cwd()) {
+    const normalized = isAbsolute(path) ? resolve(path) : resolve(workspaceRoot, path);
+    try {
+        return realpathSync(normalized);
+    }
+    catch {
+        return normalized;
+    }
+}
+/**
+ * A location-anchored glob for the bound plan itself.
+ *
+ * `cb_exclude_globs` are matched against repo-relative paths, so an absolute
+ * path is NOT a usable glob — it would silently never match. Anchor on the
+ * plan's parent directory + basename instead (`**\/<parent>/<base>`): broad
+ * enough to match wherever the root is rooted, narrow enough not to nuke every
+ * same-named file in the repo. Exact absolute matching is the post-filter's job.
+ */
+function planFileExcludeGlob(planFile) {
+    const parts = resolve(planFile).split(/[\\/]/).filter((part) => part !== "");
+    const base = parts.at(-1);
+    const parent = parts.at(-2);
+    if (base === undefined)
+        return PLAN_WORKSPACE_EXCLUDE_GLOB;
+    return parent === undefined ? `**/${base}` : `**/${parent}/${base}`;
+}
+/** Build the enforced policy for one run. `planFile` is the caller's original. */
+export function buildPlanReviewContextPolicy(planFile) {
+    const canonicalPlan = canonicalize(planFile);
+    // Record BOTH the canonical and the lexically-resolved path: if `plan_file`
+    // reaches an actor through a different symlink route, either form must match.
+    const excluded = [...new Set([canonicalPlan, resolve(planFile)])];
+    const globs = [
+        ...new Set([PLAN_WORKSPACE_EXCLUDE_GLOB, planFileExcludeGlob(planFile)]),
+    ];
+    return {
+        immutable_snapshot_only: true,
+        original_plan_context_allowed: false,
+        plan_workspace_context_allowed: false,
+        original_plan_absolute_path: canonicalPlan,
+        enforced_exclude_globs: globs,
+        excluded_absolute_paths: excluded,
+    };
+}
+/**
+ * Whether `path` is force-excluded: it IS the bound original plan, or it is any
+ * plan-workspace `PLAN.md`.
+ */
+export function isExcludedPlanPath(policy, path, workspaceRoot = process.cwd()) {
+    const resolvedPath = isAbsolute(path) ? resolve(path) : resolve(workspaceRoot, path);
+    const canonical = canonicalize(resolvedPath, workspaceRoot);
+    if (policy.excluded_absolute_paths.some((excluded) => canonicalize(excluded) === canonical)) {
+        return true;
+    }
+    return isPlanWorkspacePlanPath(canonical) || isPlanWorkspacePlanPath(resolvedPath);
+}
+/**
+ * Fold the enforced exclusions into a caller's `cb_exclude_globs` (A-7a).
+ * Order is caller-first then enforced, deduped, so the enforced entries are
+ * always present regardless of what the caller supplied — including `[]`.
+ */
+export function foldPlanReviewExcludeGlobs(policy, callerExcludeGlobs) {
+    const out = [];
+    for (const glob of [...callerExcludeGlobs, ...policy.enforced_exclude_globs]) {
+        if (!out.includes(glob))
+            out.push(glob);
+    }
+    return out;
+}
+/** Strip every force-excluded path from a finalized path list (A-7b). */
+export function filterExcludedPlanPaths(policy, paths, workspaceRoot = process.cwd()) {
+    const kept = [];
+    const removed = [];
+    for (const path of paths) {
+        if (isExcludedPlanPath(policy, path, workspaceRoot)) {
+            removed.push(path);
+        }
+        else {
+            kept.push(path);
+        }
+    }
+    return { kept, removed };
+}
+/**
+ * Reject caller-supplied context anchors that resolve to the original plan or
+ * any plan-workspace `PLAN.md`. Returns every offender so the caller gets one
+ * complete rejection rather than a whack-a-mole loop.
+ */
+export function findRejectedPlanContextAnchors(policy, variables, workspaceRoot = process.cwd()) {
+    const rejections = [];
+    for (const variable of [
+        "context_files",
+        "context_bundle_files",
+        "cb_focus_paths",
+    ]) {
+        const value = variables[variable];
+        if (!Array.isArray(value))
+            continue;
+        for (const entry of value) {
+            if (typeof entry !== "string")
+                continue;
+            if (isExcludedPlanPath(policy, entry, workspaceRoot)) {
+                rejections.push({ variable, path: entry });
+            }
+        }
+    }
+    return rejections;
+}
+//# sourceMappingURL=context-policy.js.map

package/clinkx-workflows/dist/plan-review/context-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-policy.js","sourceRoot":"","sources":["../../src/plan-review/context-policy.ts"],"names":[],"mappings":"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"}