@codyswann/lisa 2.217.8 → 2.219.0

package/all/create-only/.claude/rules/PROJECT_LEARNINGS.md

@@ -0,0 +1,7 @@
+# Project Learnings
+
+<!-- lisa-learnings-contract:v1 -->
+
+```jsonl
+
+```

package/dist/core/learnings-contract.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Executable contract shared by every project-learnings writer and checker.
+ * Keeping the numeric limits here prevents documentation, writers, and CI
+ * from drifting to different budgets.
+ * @module learnings-contract
+ */
+export declare const LEARNING_CONFIDENCE_VALUES: readonly ["low", "medium", "high"];
+/** Confidence vocabulary persisted in every learning entry. */
+export type LearningConfidence = (typeof LEARNING_CONFIDENCE_VALUES)[number];
+export declare const LEARNINGS_CONTRACT: Readonly<{
+    readonly version: 1;
+    readonly fields: readonly ["id", "rule", "why", "provenance", "first_learned", "last_confirmed", "confidence"];
+    readonly maxRuleCharacters: 240;
+    readonly maxRuleLines: 2;
+    readonly maxProvenanceReferences: 20;
+    readonly maxEntries: 20;
+    readonly maxTokens: 4000;
+    readonly measurement: "utf8-bytes-upper-bound";
+}>;
+/** Complete persisted schema for one project learning. */
+export interface LearningEntry {
+    readonly id: string;
+    readonly rule: string;
+    readonly why: string;
+    readonly provenance: readonly string[];
+    readonly first_learned: string;
+    readonly last_confirmed: string;
+    readonly confidence: LearningConfidence;
+}
+/**
+ * Estimate tokens deterministically without coupling the persisted contract to
+ * a model-specific tokenizer. A byte count is a conservative upper bound for
+ * byte-level tokenizers and is reproducible in both the writer and CI.
+ * @param content - Canonical full Markdown document
+ * @returns Reproducible estimated token count
+ */
+export declare function estimateLearningTokens(content: string): number;
+//# sourceMappingURL=learnings-contract.d.ts.map

package/dist/core/learnings-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"learnings-contract.d.ts","sourceRoot":"","sources":["../../src/core/learnings-contract.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAO,MAAM,0BAA0B,oCAAqC,CAAC;AAE7E,+DAA+D;AAC/D,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,0BAA0B,CAAC,CAAC,MAAM,CAAC,CAAC;AAE7E,eAAO,MAAM,kBAAkB;;;;;;;;;EAiBpB,CAAC;AAEZ,0DAA0D;AAC1D,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,UAAU,EAAE,kBAAkB,CAAC;CACzC;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE9D"}

package/dist/core/learnings-contract.js

@@ -0,0 +1,36 @@
+/**
+ * Executable contract shared by every project-learnings writer and checker.
+ * Keeping the numeric limits here prevents documentation, writers, and CI
+ * from drifting to different budgets.
+ * @module learnings-contract
+ */
+export const LEARNING_CONFIDENCE_VALUES = ["low", "medium", "high"];
+export const LEARNINGS_CONTRACT = Object.freeze({
+    version: 1,
+    fields: Object.freeze([
+        "id",
+        "rule",
+        "why",
+        "provenance",
+        "first_learned",
+        "last_confirmed",
+        "confidence",
+    ]),
+    maxRuleCharacters: 240,
+    maxRuleLines: 2,
+    maxProvenanceReferences: 20,
+    maxEntries: 20,
+    maxTokens: 4000,
+    measurement: "utf8-bytes-upper-bound",
+});
+/**
+ * Estimate tokens deterministically without coupling the persisted contract to
+ * a model-specific tokenizer. A byte count is a conservative upper bound for
+ * byte-level tokenizers and is reproducible in both the writer and CI.
+ * @param content - Canonical full Markdown document
+ * @returns Reproducible estimated token count
+ */
+export function estimateLearningTokens(content) {
+    return Buffer.byteLength(content, "utf8");
+}
+//# sourceMappingURL=learnings-contract.js.map

package/dist/core/learnings-contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"learnings-contract.js","sourceRoot":"","sources":["../../src/core/learnings-contract.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,MAAM,CAAU,CAAC;AAK7E,MAAM,CAAC,MAAM,kBAAkB,GAAG,MAAM,CAAC,MAAM,CAAC;IAC9C,OAAO,EAAE,CAAC;IACV,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC;QACpB,IAAI;QACJ,MAAM;QACN,KAAK;QACL,YAAY;QACZ,eAAe;QACf,gBAAgB;QAChB,YAAY;KACJ,CAAC;IACX,iBAAiB,EAAE,GAAG;IACtB,YAAY,EAAE,CAAC;IACf,uBAAuB,EAAE,EAAE;IAC3B,UAAU,EAAE,EAAE;IACd,SAAS,EAAE,IAAI;IACf,WAAW,EAAE,wBAAwB;CAC7B,CAAC,CAAC;AAaZ;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CAAC,OAAe;IACpD,OAAO,MAAM,CAAC,UAAU,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;AAC5C,CAAC"}

package/dist/core/learnings-entry.d.ts

@@ -0,0 +1,9 @@
+/** Strict validation for the seven-field project learning schema. */
+import { type LearningEntry } from "./learnings-contract.js";
+/**
+ * Validate an untrusted entry and return a normalized immutable copy.
+ * @param candidate - Value to validate against the executable contract
+ * @returns Validated learning entry
+ */
+export declare function validateLearningEntry(candidate: unknown): LearningEntry;
+//# sourceMappingURL=learnings-entry.d.ts.map

package/dist/core/learnings-entry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"learnings-entry.d.ts","sourceRoot":"","sources":["../../src/core/learnings-entry.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,OAAO,EAIL,KAAK,aAAa,EACnB,MAAM,yBAAyB,CAAC;AAOjC;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,OAAO,GAAG,aAAa,CA0BvE"}

package/dist/core/learnings-entry.js

@@ -0,0 +1,233 @@
+/** Strict validation for the seven-field project learning schema. */
+import { LEARNINGS_CONTRACT, LEARNING_CONFIDENCE_VALUES, } from "./learnings-contract.js";
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
+const STABLE_ID = /^[a-z0-9]+(?:[._-][a-z0-9]+)*$/;
+/**
+ * Validate an untrusted entry and return a normalized immutable copy.
+ * @param candidate - Value to validate against the executable contract
+ * @returns Validated learning entry
+ */
+export function validateLearningEntry(candidate) {
+    const descriptors = requireEntryDescriptors(candidate);
+    const value = (field) => readDataProperty(descriptors, field);
+    const id = requireStableId(value("id"));
+    const rule = requireRule(value("rule"));
+    const why = requireWhy(value("why"));
+    const provenance = requireProvenance(value("provenance"));
+    const firstLearned = requireIsoDate(value("first_learned"), "first_learned");
+    const lastConfirmed = requireIsoDate(value("last_confirmed"), "last_confirmed");
+    const confidence = requireConfidence(value("confidence"));
+    if (lastConfirmed < firstLearned) {
+        throw new Error("Invalid dates: last_confirmed precedes first_learned");
+    }
+    return Object.freeze({
+        id,
+        rule,
+        why,
+        provenance: Object.freeze(provenance),
+        first_learned: firstLearned,
+        last_confirmed: lastConfirmed,
+        confidence,
+    });
+}
+/**
+ * Require an object with exactly seven accessor-free own fields.
+ * @param candidate - Untrusted candidate object
+ * @returns Exact own-property descriptor map
+ */
+function requireEntryDescriptors(candidate) {
+    if (candidate === null ||
+        typeof candidate !== "object" ||
+        Array.isArray(candidate)) {
+        throw new Error("Invalid learning entry: expected an object");
+    }
+    const descriptors = Object.getOwnPropertyDescriptors(candidate);
+    const ownKeys = Reflect.ownKeys(descriptors);
+    if (ownKeys.some(key => typeof key !== "string")) {
+        throw new Error("Invalid learning entry fields: symbol keys are not allowed");
+    }
+    if (ownKeys.length !== LEARNINGS_CONTRACT.fields.length ||
+        LEARNINGS_CONTRACT.fields.some(field => descriptors[field] === undefined)) {
+        throw new Error(`Invalid learning entry fields: expected exactly ${LEARNINGS_CONTRACT.fields.join(", ")}`);
+    }
+    return descriptors;
+}
+/**
+ * Read one exact-schema field without invoking an accessor.
+ * @param descriptors - Candidate descriptor map
+ * @param field - Required contract field
+ * @returns Stored data value
+ */
+function readDataProperty(descriptors, field) {
+    const descriptor = descriptors[field];
+    if (descriptor === undefined || !("value" in descriptor)) {
+        throw new Error(`Invalid ${field}: accessors are not allowed`);
+    }
+    return descriptor.value;
+}
+/**
+ * Require and bound a stable learning id.
+ * @param value - Untrusted id value
+ * @returns Valid stable id
+ */
+function requireStableId(value) {
+    const id = requireNonEmptyString(value, "id");
+    assertUtf8Budget(id, "id");
+    if (!STABLE_ID.test(id)) {
+        throw new Error("Invalid learning id: use lowercase letters, numbers, dots, underscores, or hyphens");
+    }
+    return id;
+}
+/**
+ * Require a rule within both hard character and line caps.
+ * @param value - Untrusted rule value
+ * @returns Valid bounded rule
+ */
+function requireRule(value) {
+    const rule = requireNonEmptyString(value, "rule");
+    if (rule.length > LEARNINGS_CONTRACT.maxRuleCharacters) {
+        throw new Error(`rule exceeds maxRuleCharacters ${LEARNINGS_CONTRACT.maxRuleCharacters}`);
+    }
+    const ruleLines = rule
+        .replaceAll("\r\n", "\n")
+        .replaceAll("\r", "\n")
+        .replaceAll("\u0085", "\n")
+        .replaceAll("\u2028", "\n")
+        .replaceAll("\u2029", "\n")
+        .split("\n").length;
+    if (ruleLines > LEARNINGS_CONTRACT.maxRuleLines) {
+        throw new Error(`rule exceeds maxRuleLines ${LEARNINGS_CONTRACT.maxRuleLines}`);
+    }
+    return rule;
+}
+/**
+ * Require bounded explanatory text.
+ * @param value - Untrusted why value
+ * @returns Valid bounded explanation
+ */
+function requireWhy(value) {
+    const why = requireNonBlankText(value, "why");
+    assertUtf8Budget(why, "why");
+    return why;
+}
+/**
+ * Validate a dense, accessor-free provenance list with bounded allocation.
+ * @param value - Untrusted provenance value
+ * @returns Valid provenance references
+ */
+function requireProvenance(value) {
+    if (!Array.isArray(value)) {
+        throw new Error("Invalid provenance: expected an array of references");
+    }
+    const descriptors = Object.getOwnPropertyDescriptors(value);
+    const length = Object.getOwnPropertyDescriptor(value, "length")?.value;
+    if (typeof length !== "number" ||
+        !Number.isSafeInteger(length) ||
+        length < 1 ||
+        length > LEARNINGS_CONTRACT.maxProvenanceReferences) {
+        throw new Error(`Invalid provenance: expected 1-${LEARNINGS_CONTRACT.maxProvenanceReferences} references`);
+    }
+    const provenance = Array.from({ length }, (_unused, index) => requireProvenanceItem(descriptors, index));
+    if (new Set(provenance).size !== provenance.length) {
+        throw new Error("Invalid provenance: duplicate references are not allowed");
+    }
+    return provenance;
+}
+/**
+ * Read and bound one accessor-free provenance element.
+ * @param descriptors - Provenance array descriptors
+ * @param index - Reference index
+ * @returns Valid provenance reference
+ */
+function requireProvenanceItem(descriptors, index) {
+    const descriptor = descriptors[String(index)];
+    if (descriptor === undefined || !("value" in descriptor)) {
+        throw new Error(`Invalid provenance[${index}]: accessors are not allowed`);
+    }
+    const reference = requireNonEmptyString(descriptor.value, `provenance[${index}]`);
+    assertUtf8Budget(reference, `provenance[${index}]`);
+    return reference;
+}
+/**
+ * Require one of the persisted confidence values.
+ * @param value - Untrusted confidence value
+ * @returns Valid confidence
+ */
+function requireConfidence(value) {
+    if (typeof value !== "string" ||
+        !LEARNING_CONFIDENCE_VALUES.includes(value)) {
+        throw new Error(`Invalid confidence: expected ${LEARNING_CONFIDENCE_VALUES.join(" | ")}`);
+    }
+    return value;
+}
+/**
+ * Require a trimmed, non-empty, control-character-free string.
+ * @param value - Untrusted string value
+ * @param field - Field name for errors
+ * @returns Valid non-empty string
+ */
+function requireNonEmptyString(value, field) {
+    if (typeof value !== "string" ||
+        value.length === 0 ||
+        value.trim() !== value ||
+        containsForbiddenTextControl(value)) {
+        throw new Error(`Invalid ${field}: expected a trimmed non-empty string`);
+    }
+    return value;
+}
+/**
+ * Require non-blank text and normalize its outer whitespace.
+ * @param value - Untrusted text value
+ * @param field - Field name for errors
+ * @returns Normalized non-blank text
+ */
+function requireNonBlankText(value, field) {
+    if (typeof value !== "string" ||
+        value.trim().length === 0 ||
+        containsForbiddenTextControl(value)) {
+        throw new Error(`Invalid ${field}: expected non-blank text`);
+    }
+    return value.trim();
+}
+/**
+ * Require a real calendar date in ISO date form.
+ * @param value - Untrusted date value
+ * @param field - Field name for errors
+ * @returns Valid ISO date
+ */
+function requireIsoDate(value, field) {
+    const result = requireNonEmptyString(value, field);
+    const date = new Date(`${result}T00:00:00.000Z`);
+    if (!ISO_DATE.test(result) ||
+        Number.isNaN(date.valueOf()) ||
+        date.toISOString().slice(0, 10) !== result) {
+        throw new Error(`Invalid ${field}: expected a real YYYY-MM-DD date`);
+    }
+    return result;
+}
+/**
+ * Bound individual untrusted fields before document rendering allocates them.
+ * @param value - Valid string value
+ * @param field - Field name for errors
+ */
+function assertUtf8Budget(value, field) {
+    if (Buffer.byteLength(value, "utf8") > LEARNINGS_CONTRACT.maxTokens) {
+        throw new Error(`${field} exceeds maxTokens ${LEARNINGS_CONTRACT.maxTokens}`);
+    }
+}
+/**
+ * Reject non-whitespace controls while allowing rule line separators.
+ * @param value - Entry text
+ * @returns True when a forbidden control is present
+ */
+function containsForbiddenTextControl(value) {
+    return Array.from(value).some(character => {
+        const code = character.charCodeAt(0);
+        return (code <= 8 ||
+            code === 11 ||
+            code === 12 ||
+            (code >= 14 && code <= 31) ||
+            code === 127);
+    });
+}
+//# sourceMappingURL=learnings-entry.js.map

package/dist/core/learnings-entry.js.map

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

package/dist/core/learnings-file-safety.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Resolve the configured target without permitting project-root escape.
+ * @param projectRoot - Host project root
+ * @param relativeFile - Configured project-relative file
+ * @returns Resolved root and target paths
+ */
+export declare function resolveSafeLearningTarget(projectRoot: string, relativeFile: string): {
+    readonly root: string;
+    readonly target: string;
+};
+/**
+ * Read only a bounded regular file from the inode that was safety-checked.
+ * @param target - Resolved learnings file path
+ * @returns Existing content, or undefined when the file does not exist
+ */
+export declare function readExistingLearnings(target: string): Promise<string | undefined>;
+/**
+ * Reject parent-directory symlinks that resolve outside the project root.
+ * @param root - Resolved project root
+ * @param parent - Target parent directory
+ */
+export declare function assertSafeLearningParents(root: string, parent: string): Promise<void>;
+//# sourceMappingURL=learnings-file-safety.d.ts.map

package/dist/core/learnings-file-safety.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"learnings-file-safety.d.ts","sourceRoot":"","sources":["../../src/core/learnings-file-safety.ts"],"names":[],"mappings":"AAMA;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,GACnB;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CASpD;AAED;;;;GAIG;AACH,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAmC7B;AAED;;;;GAIG;AACH,wBAAsB,yBAAyB,CAC7C,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAYf"}

package/dist/core/learnings-file-safety.js

@@ -0,0 +1,84 @@
+/** Filesystem containment and safe reads for project learnings. */
+import * as fse from "fs-extra";
+import { lstat, open, realpath } from "node:fs/promises";
+import * as path from "node:path";
+import { LEARNINGS_CONTRACT } from "./learnings-contract.js";
+/**
+ * Resolve the configured target without permitting project-root escape.
+ * @param projectRoot - Host project root
+ * @param relativeFile - Configured project-relative file
+ * @returns Resolved root and target paths
+ */
+export function resolveSafeLearningTarget(projectRoot, relativeFile) {
+    const root = path.resolve(projectRoot);
+    const target = path.resolve(root, relativeFile);
+    if (target === root || !target.startsWith(`${root}${path.sep}`)) {
+        throw new Error("Unsafe projectRulesFile: learnings path escapes project root");
+    }
+    return { root, target };
+}
+/**
+ * Read only a bounded regular file from the inode that was safety-checked.
+ * @param target - Resolved learnings file path
+ * @returns Existing content, or undefined when the file does not exist
+ */
+export async function readExistingLearnings(target) {
+    try {
+        const beforeOpen = await lstat(target);
+        if (!beforeOpen.isFile()) {
+            throw new Error("Unsafe project learnings path: target is not a regular file");
+        }
+        const handle = await open(target, "r");
+        try {
+            const opened = await handle.stat();
+            if (!opened.isFile() ||
+                opened.dev !== beforeOpen.dev ||
+                opened.ino !== beforeOpen.ino) {
+                throw new Error("Unsafe project learnings path: target changed during open");
+            }
+            if (opened.size > LEARNINGS_CONTRACT.maxTokens) {
+                throw new Error(`Project learnings payload exceeds maxTokens ${LEARNINGS_CONTRACT.maxTokens}`);
+            }
+            return handle.readFile({ encoding: "utf8" });
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return undefined;
+        }
+        throw error;
+    }
+}
+/**
+ * Reject parent-directory symlinks that resolve outside the project root.
+ * @param root - Resolved project root
+ * @param parent - Target parent directory
+ */
+export async function assertSafeLearningParents(root, parent) {
+    const realRoot = await realpath(root);
+    const cursor = await findExistingAncestor(parent);
+    const realParent = await realpath(cursor);
+    if (realParent !== realRoot &&
+        !realParent.startsWith(`${realRoot}${path.sep}`)) {
+        throw new Error("Unsafe project learnings path: parent escapes project root");
+    }
+}
+/**
+ * Find the nearest existing ancestor without mutable traversal state.
+ * @param candidate - Starting filesystem path
+ * @returns Nearest existing ancestor
+ */
+async function findExistingAncestor(candidate) {
+    if (await fse.pathExists(candidate)) {
+        return candidate;
+    }
+    const parent = path.dirname(candidate);
+    if (parent === candidate) {
+        throw new Error("Unsafe project learnings path: no project ancestor");
+    }
+    return findExistingAncestor(parent);
+}
+//# sourceMappingURL=learnings-file-safety.js.map

package/dist/core/learnings-file-safety.js.map

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

package/dist/core/learnings-lock.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Serialize same-target writers across processes with an exclusive hard link.
+ * @param target - Absolute learnings target
+ * @param operation - Complete read, validate, and atomic-write transaction
+ * @returns Operation result
+ */
+export declare function withLearningTargetLock<T>(target: string, operation: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=learnings-lock.d.ts.map

package/dist/core/learnings-lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"learnings-lock.d.ts","sourceRoot":"","sources":["../../src/core/learnings-lock.ts"],"names":[],"mappings":"AAoBA;;;;;GAKG;AACH,wBAAsB,sBAAsB,CAAC,CAAC,EAC5C,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAC1B,OAAO,CAAC,CAAC,CAAC,CAaZ"}