prae-cli 0.1.1 → 0.2.0

package/lib/src-BrZXeEez.js

@@ -0,0 +1,275 @@
+import { readFileSync, statSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { createHash } from "node:crypto";
+
+//#region ../instructions/src/parse.ts
+const HEADING = /^(#{1,6})\s+(.*)$/;
+const BULLET = /^\s*(?:[-*+]|\d+[.)])\s+(.*)$/;
+const FENCE = /^\s*(?:```|~~~)/;
+const COMMENT_OPEN = /^\s*<!--/;
+const COMMENT_CLOSE = /-->/;
+/** How far a continuation line must be indented to belong to the bullet above. */
+const CONTINUATION = /^\s{1,}\S/;
+/** Trim, drop emphasis markers that carry no meaning for a reviewer. */
+function clean(text) {
+	return text.trim().replace(/\s+/g, " ");
+}
+/** The parse itself. No Node, so this runs anywhere. */
+function parseStatements(text, format = "markdown") {
+	const lines = text.split("\n");
+	if (format === "text") {
+		const statements = [];
+		for (const [index, raw] of lines.entries()) {
+			const line = clean(raw);
+			if (line === "" || line.startsWith("#")) continue;
+			statements.push({
+				text: line,
+				line: index + 1,
+				kind: "bullet",
+				headingPath: []
+			});
+		}
+		return {
+			format,
+			text,
+			sections: [{
+				headingPath: [],
+				level: 0,
+				statements
+			}]
+		};
+	}
+	const sections = [];
+	let path = [];
+	let current = {
+		level: 0,
+		statements: []
+	};
+	let currentPath = [];
+	let fenced = false;
+	let commented = false;
+	/** An open bullet, which an indented line below it continues. */
+	let bulletText;
+	/** Consecutive unindented prose lines, which are one wrapped sentence. */
+	let paragraph;
+	const push = (held, kind) => {
+		if (held === void 0) return;
+		const joined = clean(held.text.join(" "));
+		if (joined !== "") current.statements.push({
+			text: joined,
+			line: held.line,
+			kind,
+			headingPath: currentPath
+		});
+	};
+	const flush = () => {
+		push(bulletText, "bullet");
+		bulletText = void 0;
+		push(paragraph, "paragraph");
+		paragraph = void 0;
+	};
+	const flushSection = () => {
+		flush();
+		if (current.heading === void 0 && current.statements.length === 0) return;
+		sections.push({
+			...current.heading === void 0 ? {} : { heading: current.heading },
+			headingPath: currentPath,
+			level: current.level,
+			statements: current.statements
+		});
+	};
+	for (const [index, raw] of lines.entries()) {
+		if (commented) {
+			if (COMMENT_CLOSE.test(raw)) commented = false;
+			continue;
+		}
+		if (COMMENT_OPEN.test(raw)) {
+			flush();
+			if (!COMMENT_CLOSE.test(raw)) commented = true;
+			continue;
+		}
+		if (FENCE.test(raw)) {
+			flush();
+			fenced = !fenced;
+			continue;
+		}
+		if (fenced) continue;
+		const heading = HEADING.exec(raw);
+		if (heading?.[1] !== void 0 && heading[2] !== void 0) {
+			flushSection();
+			const level = heading[1].length;
+			const title = clean(heading[2]);
+			path = [...path.slice(0, level - 1), title];
+			currentPath = path;
+			current = {
+				heading: title,
+				level,
+				statements: []
+			};
+			continue;
+		}
+		const bullet = BULLET.exec(raw);
+		if (bullet?.[1] !== void 0) {
+			flush();
+			bulletText = {
+				text: [bullet[1]],
+				line: index + 1
+			};
+			continue;
+		}
+		if (clean(raw) === "") {
+			flush();
+			continue;
+		}
+		if (bulletText !== void 0 && CONTINUATION.test(raw)) {
+			bulletText.text.push(raw);
+			continue;
+		}
+		push(bulletText, "bullet");
+		bulletText = void 0;
+		if (paragraph === void 0) paragraph = {
+			text: [raw],
+			line: index + 1
+		};
+		else paragraph.text.push(raw);
+	}
+	flushSection();
+	return {
+		format,
+		text,
+		sections
+	};
+}
+/** Every statement in the document, in file order. */
+function statementsOf(doc) {
+	return doc.sections.flatMap((section) => section.statements);
+}
+
+//#endregion
+//#region ../instructions/src/node.ts
+/** Parse an instruction file and hash it. */
+function parseInstructions(text, format = "markdown") {
+	return {
+		...parseStatements(text, format),
+		hash: createHash("sha256").update(text).digest("hex")
+	};
+}
+
+//#endregion
+//#region ../instructions/src/discover.ts
+/** The formats each recognised filename is read as. */
+const FORMATS = {
+	"AGENTS.md": "markdown",
+	"CLAUDE.md": "markdown",
+	".cursorrules": "text",
+	".windsurfrules": "text"
+};
+const DEFAULT_CANDIDATES = Object.keys(FORMATS);
+const DEFAULT_ROOT_MARKERS = [
+	".git",
+	"package.json",
+	"pyproject.toml",
+	"go.mod"
+];
+const DEFAULT_MAX_BYTES = 256 * 1024;
+const DEFAULT_MAX_DEPTH = 24;
+function exists(path) {
+	try {
+		statSync(path);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
+* Walk up from `from`, collecting instruction files, outermost first.
+*
+* A file larger than `maxBytes` is skipped rather than truncated: half an
+* instruction file is worse than none, because the half that is missing is
+* invisible to whoever reads the result.
+*/
+function discover(from, options = {}) {
+	const candidates = options.candidates ?? DEFAULT_CANDIDATES;
+	const markers = options.rootMarkers ?? DEFAULT_ROOT_MARKERS;
+	const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+	const maxDepth = options.maxDepth ?? DEFAULT_MAX_DEPTH;
+	const dirs = [];
+	let dir = resolve(from);
+	for (let depth = 0; depth < maxDepth; depth += 1) {
+		dirs.push(dir);
+		if (markers.some((marker) => exists(join(dir, marker)))) break;
+		const parent = dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+	const found = [];
+	for (const directory of dirs.reverse()) for (const name of candidates) {
+		const path = join(directory, name);
+		if (!exists(path)) continue;
+		let size;
+		try {
+			size = statSync(path).size;
+		} catch {
+			continue;
+		}
+		if (size > maxBytes) continue;
+		let text;
+		try {
+			text = readFileSync(path, "utf8");
+		} catch {
+			continue;
+		}
+		if (text.trim() === "") continue;
+		found.push({
+			...parseInstructions(text, FORMATS[name] ?? "markdown"),
+			path,
+			name,
+			layer: "project",
+			depth: found.length
+		});
+	}
+	return found;
+}
+
+//#endregion
+//#region ../instructions/src/index.ts
+/**
+* Read every instruction file that governs work at `from`.
+*
+* Ordered least specific to most: operator files first, then project files
+* outermost-in. A reader looking at the stack can see which layer a sentence
+* came from without opening anything.
+*/
+function ingest(from, options = {}) {
+	const operator = [];
+	for (const path of options.operator ?? []) {
+		let text;
+		try {
+			text = readFileSync(path, "utf8");
+		} catch {
+			continue;
+		}
+		if (text.trim() === "") continue;
+		const name = basename(path);
+		operator.push({
+			...parseInstructions(text, FORMATS[name] ?? "markdown"),
+			path,
+			name,
+			layer: "operator",
+			depth: operator.length
+		});
+	}
+	const files = [...operator, ...discover(from, options)];
+	return {
+		files,
+		statements: files.flatMap((file) => statementsOf(file).map((statement) => ({
+			...statement,
+			path: file.path,
+			layer: file.layer
+		}))),
+		hash: createHash("sha256").update(files.map((file) => `${file.layer}:${file.path}:${file.hash}`).join("\n")).digest("hex")
+	};
+}
+
+//#endregion
+export { DEFAULT_CANDIDATES, DEFAULT_ROOT_MARKERS, FORMATS, discover, ingest, parseInstructions, parseStatements, statementsOf };

package/lib/src-Dd2_8m2g.js

@@ -0,0 +1,153 @@
+//#region ../extract/src/index.ts
+/** Backticked or quoted literals, which is where a real path or host appears. */
+function literals(text) {
+	const found = /* @__PURE__ */ new Set();
+	for (const match of text.matchAll(/`([^`]+)`|"([^"]+)"|'([^']+)'/g)) {
+		const value = (match[1] ?? match[2] ?? match[3] ?? "").trim();
+		if (value !== "") found.add(value);
+	}
+	return [...found];
+}
+const PATH_LIKE = /^[./~]|\/$|^[\w.-]+\/|\*\*/;
+const HOST_LIKE = /^(?:https?:\/\/)?([a-z0-9-]+\.)+[a-z]{2,}(?:\/|$)/i;
+function paths(text) {
+	return literals(text).filter((value) => PATH_LIKE.test(value) && !HOST_LIKE.test(value)).map((value) => value.endsWith("/") ? `${value}**` : value);
+}
+function hosts(text) {
+	return literals(text).filter((value) => HOST_LIKE.test(value)).map((value) => value.replace(/^https?:\/\//, "").replace(/\/.*$/, ""));
+}
+/** `PRAE-P01` — proposals are numbered apart from anything hand-written. */
+function id(index) {
+	return `PRAE-P${String(index + 1).padStart(2, "0")}`;
+}
+/**
+* The readings, kept few on purpose.
+*
+* Each one is a phrasing whose meaning is not in doubt *and* which names what
+* it applies to. Adding a looser pattern here trades precision for recall, and
+* the whole value of a proposal is that a reviewer can agree with it in a
+* second without opening the file.
+*/
+const READINGS = [
+	{
+		test: /\bwrites?\b[^.]*\b(?:stay|remain|live|only|confined)\b[^.]*\b(?:in|inside|within|under)\b/i,
+		confidence: "high",
+		why: "names where writes are allowed, so anything outside is not",
+		build: (found) => found.paths.length === 0 ? void 0 : {
+			title: "Writes stay in the workspace",
+			when: {
+				capability: "fs:write",
+				path: { outside: found.paths }
+			},
+			effect: {
+				kind: "deny",
+				because: `writes outside ${found.paths.join(", ")} are not granted in this pack`
+			}
+		}
+	},
+	{
+		test: /\b(?:never|do not|don't|no)\b[^.]*\bwrit\w*\b[^.]*\b(?:outside|beyond|above)\b/i,
+		confidence: "high",
+		why: "forbids writing outside the paths it names",
+		build: (found) => found.paths.length === 0 ? void 0 : {
+			title: "Writes stay in the workspace",
+			when: {
+				capability: "fs:write",
+				path: { outside: found.paths }
+			},
+			effect: {
+				kind: "deny",
+				because: `writes outside ${found.paths.join(", ")} are not granted in this pack`
+			}
+		}
+	},
+	{
+		test: /\b(?:never|do not|don't|no)\b[^.]*\b(?:read|open|access|touch)\b/i,
+		confidence: "high",
+		why: "forbids reading the paths it names",
+		build: (found) => found.paths.length === 0 ? void 0 : {
+			title: "Secrets are not readable",
+			when: {
+				capability: "fs:read",
+				path: { inside: found.paths }
+			},
+			effect: {
+				kind: "deny",
+				because: `reads of ${found.paths.join(", ")} are not granted in this pack`
+			}
+		}
+	},
+	{
+		test: /\bonly\b[^.]*\b(?:fetch|request|call|download)\b[^.]*\bfrom\b/i,
+		confidence: "high",
+		why: "names the only hosts allowed, so any other host is not",
+		build: (found) => found.hosts.length === 0 ? void 0 : {
+			title: "Fetches stay on listed hosts",
+			when: {
+				capability: "net:fetch",
+				host: { notIn: found.hosts }
+			},
+			effect: {
+				kind: "deny",
+				because: `this host is not on the pack allowlist (${found.hosts.join(", ")})`
+			}
+		}
+	},
+	{
+		test: /\b(?:never|do not|don't|no)\b[^.]*\b(?:fetch|request|download|call)\b/i,
+		confidence: "medium",
+		why: "forbids reaching the hosts it names, though the phrasing is broad",
+		build: (found) => found.hosts.length === 0 ? void 0 : {
+			title: "Listed hosts are refused",
+			when: {
+				capability: "net:fetch",
+				host: { in: found.hosts }
+			},
+			effect: {
+				kind: "deny",
+				because: `${found.hosts.join(", ")} is refused by this pack`
+			}
+		}
+	}
+];
+/** Read statements and propose rules. Deterministic; no model involved. */
+function extract(statements, options = {}) {
+	const proposals = [];
+	const skipped = [];
+	for (const statement of statements) {
+		const found = {
+			paths: paths(statement.text),
+			hosts: hosts(statement.text)
+		};
+		let proposed = false;
+		for (const reading of READINGS) {
+			if (!reading.test.test(statement.text)) continue;
+			const built = reading.build(found);
+			if (built === void 0) continue;
+			const effect = options.as === void 0 ? built.effect : {
+				kind: options.as,
+				because: built.effect.because
+			};
+			proposals.push({
+				rule: {
+					id: id(proposals.length),
+					...built,
+					effect
+				},
+				from: statement,
+				confidence: reading.confidence,
+				why: reading.why
+			});
+			proposed = true;
+			break;
+		}
+		if (!proposed) skipped.push(statement);
+	}
+	return {
+		proposals,
+		skipped
+	};
+}
+
+//#endregion
+export { extract };