codictator 0.0.0-stage → 0.1.2

package/dist/features/packs/enforcers/py-checks.js

@@ -0,0 +1,131 @@
+import { ok } from "../../../kernel/index.js";
+import { bindRule, findingFor, readErrorFinding, readLossyText, selectFiles, } from "./binding.js";
+import { baseEnforcer } from "./health-measures.js";
+import { blankPythonCode, isPythonFile } from "./py-lex.js";
+// SPEC §6.3 python/typecheck as the L1 static approximation: an annotated
+// literal of the wrong primitive type is a type error the checker would
+// also reject. An `int` annotation holding a `float` literal stays clean
+// (mypy accepts the promotion); a `float` holding an `int` literal is the
+// narrowing the checker flags. The repo mypy/pyright run stays on the
+// external contract.
+export function resolvePythonTypecheck(decl, rule, ports) {
+    const binding = bindRule(rule);
+    const mismatch = /:\s*(int|float|str|bool)\s*=\s*("[^"\n]*"|'[^'\n]*'|-?\b\d+\.\d+\b|-?\b\d+\b|\bTrue\b|\bFalse\b|\bNone\b)/;
+    return ok(baseEnforcer(rule, binding, decl, async (ctx) => {
+        const findings = [];
+        for (const file of selectFiles(ctx.scope.files, binding.scopeGlobs)) {
+            if (!isPythonFile(file)) {
+                continue;
+            }
+            const loaded = await readLossyText(ports.fs, file);
+            if (!loaded.ok) {
+                findings.push(readErrorFinding(binding, file, loaded.error, "read"));
+                continue;
+            }
+            let line = 0;
+            for (const content of loaded.value.text.split("\n")) {
+                line += 1;
+                const hit = mismatch.exec(content);
+                if (hit === null) {
+                    continue;
+                }
+                const annotated = hit[1] ?? "";
+                const literal = hit[2] ?? "";
+                const literalKind = literal.startsWith('"') || literal.startsWith("'")
+                    ? "str"
+                    : literal === "True" || literal === "False"
+                        ? "bool"
+                        : literal === "None"
+                            ? "none"
+                            : literal.includes(".")
+                                ? "float"
+                                : "int";
+                const clean = (annotated === "float" && literalKind === "int") ||
+                    annotated === literalKind;
+                if (!clean) {
+                    findings.push(findingFor(binding, {
+                        path: file,
+                        line,
+                        message: `type error in ${file}:${String(line)}: ${annotated} assigned ${literal}`,
+                        vars: { path: file, line: String(line), value: literal },
+                    }));
+                }
+            }
+        }
+        return findings;
+    }));
+}
+// The names an import statement binds: `import a.b` binds `a`,
+// `import a as b` binds `b`, `from m import x, y` binds `x` and `y`.
+// A `from m import *` binds nothing observable, so it never flags.
+function boundImportNames(text) {
+    const blanked = blankPythonCode(text);
+    const bound = new Map();
+    const importLine = /^[ \t]*import[ \t]+(.+)$/;
+    const fromLine = /^[ \t]*from[ \t]+(\.*)([A-Za-z_][A-Za-z0-9_.]*)?[ \t]+import[ \t]+(.+)$/;
+    let line = 0;
+    for (const content of blanked.split("\n")) {
+        line += 1;
+        const plain = importLine.exec(content);
+        if (plain !== null) {
+            for (const part of (plain[1] ?? "").split(",")) {
+                const alias = part.split(/\s+as\s+/);
+                const dotted = (alias.length > 1 ? alias[1] : alias[0])?.trim() ?? "";
+                const top = dotted.split(".", 1)[0] ?? "";
+                if (/^[A-Za-z_][A-Za-z0-9_]*$/.test(top) && !bound.has(top)) {
+                    bound.set(top, line);
+                }
+            }
+            continue;
+        }
+        const from = fromLine.exec(content);
+        if (from !== null) {
+            if ((from[3] ?? "").trim().startsWith("*")) {
+                continue;
+            }
+            for (const part of (from[3] ?? "").split(",")) {
+                const alias = part.split(/\s+as\s+/);
+                const name = (alias.length > 1 ? alias[1] : alias[0])
+                    ?.trim()
+                    .replace(/[()]/g, "") ?? "";
+                if (/^[A-Za-z_][A-Za-z0-9_]*$/.test(name) && !bound.has(name)) {
+                    bound.set(name, line);
+                }
+            }
+        }
+    }
+    return bound;
+}
+// SPEC §6.3 python/lint as the L1 static approximation: never-read imports
+// (ruff F401). The repo ruff check and format --check runs stay on the
+// external contract. Quoted forward references do not count as uses.
+export function resolvePythonLint(decl, rule, ports) {
+    const binding = bindRule(rule);
+    return ok(baseEnforcer(rule, binding, decl, async (ctx) => {
+        const findings = [];
+        for (const file of selectFiles(ctx.scope.files, binding.scopeGlobs)) {
+            if (!isPythonFile(file)) {
+                continue;
+            }
+            const loaded = await readLossyText(ports.fs, file);
+            if (!loaded.ok) {
+                findings.push(readErrorFinding(binding, file, loaded.error, "read"));
+                continue;
+            }
+            const blanked = blankPythonCode(loaded.value.text);
+            for (const [name, atLine] of boundImportNames(loaded.value.text)) {
+                const word = new RegExp(`\\b${name}\\b`, "g");
+                const uses = blanked.match(word) ?? [];
+                if (uses.length <= 1) {
+                    findings.push(findingFor(binding, {
+                        path: file,
+                        line: atLine,
+                        message: `unused import ${name} in ${file}:${String(atLine)}`,
+                        vars: { path: file, line: String(atLine), value: name },
+                    }));
+                }
+            }
+        }
+        return findings;
+    }));
+}

package/dist/features/packs/enforcers/py-lex.d.ts

@@ -0,0 +1,10 @@
+export declare function isPythonFile(path: string): boolean;
+export declare function blankPythonCode(text: string): string;
+export interface PythonSpecifier {
+    readonly spec: string;
+    readonly line: number;
+}
+export declare function extractPythonSpecifiers(text: string): Array<PythonSpecifier>;
+export declare function isRelativePythonSpec(spec: string): boolean;
+export declare function pythonTopSegment(spec: string): string;
+export declare function isPythonStdlib(top: string): boolean;

package/dist/features/packs/enforcers/py-lex.js

@@ -0,0 +1,271 @@
+// SPEC §6.3: lexer-light Python supplies for the pack enforcers. The
+// precise import extractor lives in builtin-packs/python; this module
+// mirrors its blanking and statement scan locally because §3.3 forbids the
+// packs module from importing the pack supplies (the same split as
+// health-lex-imports.ts keeps for the typescript supply). Manifest-side
+// mirrors (requirements pins, pyproject names) live in py-pins.ts.
+export function isPythonFile(path) {
+    const lowered = path.toLowerCase();
+    return lowered.endsWith(".py") || lowered.endsWith(".pyi");
+}
+// Blank `count` chars to spaces, returning the index past the run.
+function blankRun(out, index, count) {
+    for (let seen = 0; seen < count; seen += 1) {
+        out[index] = " ";
+        index += 1;
+    }
+    return index;
+}
+// Blank a quoted Python string from its opening quote char: the opening
+// run, escapes and body to the closing run, keeping every newline. A
+// single-quoted string unterminated on its line ends at the newline.
+function blankPythonString(out, text, index, char) {
+    const triple = text.charAt(index + 1) === char && text.charAt(index + 2) === char;
+    const quote = triple ? char.repeat(3) : char;
+    index = blankRun(out, index, quote.length);
+    while (index < text.length) {
+        const next = text.charAt(index);
+        if (next === "\\") {
+            out[index] = " ";
+            if (index + 1 < text.length && text.charAt(index + 1) !== "\n") {
+                out[index + 1] = " ";
+            }
+            index += 2;
+            continue;
+        }
+        if (!triple && next === "\n") {
+            break;
+        }
+        if (text.startsWith(quote, index)) {
+            index = blankRun(out, index, quote.length);
+            break;
+        }
+        if (next !== "\n") {
+            out[index] = " ";
+        }
+        index += 1;
+    }
+    return index;
+}
+// Blank Python strings and comments to spaces, keeping every newline so
+// reported lines stay exact. Local mirror of the extractor blanking (§3.3).
+export function blankPythonCode(text) {
+    const out = text.split("");
+    const length = text.length;
+    let index = 0;
+    while (index < length) {
+        const char = text.charAt(index);
+        if (char === "#") {
+            while (index < length && text.charAt(index) !== "\n") {
+                out[index] = " ";
+                index += 1;
+            }
+            continue;
+        }
+        if (char === "'" || char === '"') {
+            index = blankPythonString(out, text, index, char);
+            continue;
+        }
+        index += 1;
+    }
+    return out.join("");
+}
+const GAP = String.raw `(?:[ \t]|\\(?:\r\n|[\r\n]))+`;
+const GAPZ = String.raw `(?:[ \t]|\\(?:\r\n|[\r\n]))*`;
+const DOTTED = "[A-Za-z_][A-Za-z0-9_.]*";
+const ALIAS = "[A-Za-z_][A-Za-z0-9_]*";
+const SPEC_SCAN = new RegExp(`\\bfrom${GAP}(\\.*)(${DOTTED})?${GAP}import\\b|\\bimport${GAP}(${DOTTED}(?:${GAP}as${GAP}${ALIAS})?(?:${GAPZ},${GAPZ}${DOTTED}(?:${GAP}as${GAP}${ALIAS})?)*)`, "g");
+function lineAtIndex(text, index) {
+    let line = 1;
+    for (let cursor = 0; cursor < index; cursor += 1) {
+        if (text.charAt(cursor) === "\n") {
+            line += 1;
+        }
+    }
+    return line;
+}
+// The imported modules of a file: one entry per dotted name, `from` edges
+// carrying their leading dots. Local mirror of extractPythonImports (§3.3).
+export function extractPythonSpecifiers(text) {
+    const blanked = blankPythonCode(text);
+    const found = [];
+    const scan = new RegExp(SPEC_SCAN.source, "g");
+    for (let hit = scan.exec(blanked); hit !== null; hit = scan.exec(blanked)) {
+        const line = lineAtIndex(blanked, hit.index);
+        if (hit[1] !== undefined || hit[2] !== undefined) {
+            found.push({ spec: `${hit[1] ?? ""}${hit[2] ?? ""}`, line });
+            continue;
+        }
+        for (const part of (hit[3] ?? "").split(",")) {
+            const name = part.split(/\s+as\s+/)[0]?.trim() ?? "";
+            if (name !== "") {
+                found.push({ spec: name, line });
+            }
+        }
+    }
+    return found;
+}
+export function isRelativePythonSpec(spec) {
+    return spec.startsWith(".");
+}
+// The top-level package of a dotted module: `os.path` rides on `os`, and
+// a relative edge rides on the importing package, never a registry name.
+export function pythonTopSegment(spec) {
+    const absolute = spec.replace(/^\.+/, "");
+    return absolute.split(".", 1)[0] ?? "";
+}
+// SPEC §6.3 driver `pypi`: the standard-library top levels, mirrored here
+// because §3.3 forbids importing the pack supply. Relative and stdlib
+// imports are never phantom.
+const PYTHON_STDLIB = [
+    "__future__",
+    "abc",
+    "argparse",
+    "ast",
+    "asyncio",
+    "base64",
+    "builtins",
+    "collections",
+    "concurrent",
+    "configparser",
+    "contextlib",
+    "contextvars",
+    "copy",
+    "csv",
+    "ctypes",
+    "dataclasses",
+    "datetime",
+    "decimal",
+    "difflib",
+    "dis",
+    "email",
+    "enum",
+    "errno",
+    "faulthandler",
+    "fnmatch",
+    "fractions",
+    "functools",
+    "gc",
+    "getpass",
+    "gettext",
+    "glob",
+    "gzip",
+    "hashlib",
+    "heapq",
+    "hmac",
+    "html",
+    "http",
+    "idlelib",
+    "importlib",
+    "inspect",
+    "io",
+    "ipaddress",
+    "itertools",
+    "json",
+    "keyword",
+    "lib2to3",
+    "linecache",
+    "locale",
+    "logging",
+    "lzma",
+    "mailbox",
+    "marshal",
+    "math",
+    "mimetypes",
+    "mmap",
+    "multiprocessing",
+    "numbers",
+    "operator",
+    "os",
+    "pathlib",
+    "pdb",
+    "pickle",
+    "pickletools",
+    "pkgutil",
+    "platform",
+    "plistlib",
+    "pprint",
+    "profile",
+    "pstats",
+    "pty",
+    "pwd",
+    "py_compile",
+    "pyclbr",
+    "pydoc",
+    "queue",
+    "quopri",
+    "random",
+    "re",
+    "readline",
+    "reprlib",
+    "resource",
+    "rlcompleter",
+    "runpy",
+    "sched",
+    "secrets",
+    "select",
+    "selectors",
+    "shelve",
+    "shlex",
+    "shutil",
+    "signal",
+    "site",
+    "smtpd",
+    "smtplib",
+    "socket",
+    "socketserver",
+    "sqlite3",
+    "ssl",
+    "stat",
+    "statistics",
+    "string",
+    "stringprep",
+    "struct",
+    "subprocess",
+    "symtable",
+    "sys",
+    "sysconfig",
+    "tabnanny",
+    "tarfile",
+    "telnetlib",
+    "tempfile",
+    "termios",
+    "textwrap",
+    "threading",
+    "time",
+    "timeit",
+    "tkinter",
+    "token",
+    "tokenize",
+    "tomllib",
+    "trace",
+    "traceback",
+    "tracemalloc",
+    "tty",
+    "turtle",
+    "turtledemo",
+    "types",
+    "typing",
+    "unicodedata",
+    "unittest",
+    "urllib",
+    "uu",
+    "uuid",
+    "venv",
+    "warnings",
+    "wave",
+    "weakref",
+    "webbrowser",
+    "wsgiref",
+    "xdrlib",
+    "xml",
+    "xmlrpc",
+    "zipapp",
+    "zipfile",
+    "zipimport",
+    "zlib",
+    "zoneinfo",
+];
+export function isPythonStdlib(top) {
+    return PYTHON_STDLIB.includes(top);
+}

package/dist/features/packs/enforcers/py-phantom.d.ts

@@ -0,0 +1,6 @@
+import type { Ports } from "../../../kernel/index.ts";
+import { type Result } from "../../../kernel/index.ts";
+import type { Enforcer } from "../../engine/index.ts";
+import type { PackRule } from "../index.ts";
+import type { EnforcerDecl } from "../manifest.ts";
+export declare function resolvePythonNoPhantomImport(decl: EnforcerDecl, rule: PackRule, ports: Ports): Result<Enforcer>;

package/dist/features/packs/enforcers/py-phantom.js

@@ -0,0 +1,163 @@
+import { makeError, ok } from "../../../kernel/index.js";
+import { bindRule, findingFor, readErrorFinding, readLossyText, selectFiles, } from "./binding.js";
+import { baseEnforcer } from "./health-measures.js";
+import { extractPythonSpecifiers, isPythonFile, isPythonStdlib, isRelativePythonSpec, pythonTopSegment, } from "./py-lex.js";
+import { collectPyprojectNames, parsePythonRequirements } from "./py-pins.js";
+function parentDir(path) {
+    const slash = path.lastIndexOf("/");
+    return slash < 0 ? "" : path.slice(0, slash);
+}
+async function declaredNamesFor(ports, file) {
+    // Nearest requirements.txt or pyproject.toml walking up from the
+    // importing file; no manifest means no declared dependency, so every
+    // third-party import is phantom. A throw reads as missing (the fake
+    // port throws for unseeded paths); a requirements line that parses as
+    // no requirement reports CDX-E903.
+    let dir = parentDir(file);
+    for (let depth = 0; depth < 25; depth += 1) {
+        const reqCandidate = dir === "" ? "requirements.txt" : `${dir}/requirements.txt`;
+        const tomlCandidate = dir === "" ? "pyproject.toml" : `${dir}/pyproject.toml`;
+        let reqText;
+        let tomlText;
+        try {
+            const loaded = await ports.fs.read(reqCandidate);
+            if (loaded.ok) {
+                reqText = new TextDecoder("utf-8", { fatal: false }).decode(loaded.value);
+            }
+        }
+        catch {
+            reqText = undefined;
+        }
+        try {
+            const loaded = await ports.fs.read(tomlCandidate);
+            if (loaded.ok) {
+                tomlText = new TextDecoder("utf-8", { fatal: false }).decode(loaded.value);
+            }
+        }
+        catch {
+            tomlText = undefined;
+        }
+        if (reqText !== undefined || tomlText !== undefined) {
+            const names = new Set();
+            if (tomlText !== undefined) {
+                for (const name of collectPyprojectNames(tomlText)) {
+                    names.add(name);
+                }
+            }
+            if (reqText !== undefined) {
+                const parsed = parsePythonRequirements(reqText);
+                if (parsed.brokenLine !== undefined) {
+                    return { names: new Set(), broken: reqCandidate };
+                }
+                for (const req of parsed.reqs) {
+                    names.add(req.name);
+                }
+            }
+            return { names, broken: undefined };
+        }
+        if (dir === "") {
+            return { names: new Set(), broken: undefined };
+        }
+        dir = parentDir(dir);
+    }
+    return { names: new Set(), broken: undefined };
+}
+// A first-party package maps to a scope file by module path, so `app`
+// claims `app.py` at the root or nested, never `myapp.py`.
+function firstPartyModuleFile(top, normalized) {
+    return (normalized === `${top}.py` ||
+        normalized === `${top}.pyi` ||
+        normalized.endsWith(`/${top}.py`) ||
+        normalized.endsWith(`/${top}.pyi`));
+}
+// A first-party package maps to a scope file by its marker module, so
+// namespace packages without `__init__.py` need the directory match below.
+function firstPartyInitFile(top, normalized) {
+    return (normalized === `${top}/__init__.py` ||
+        normalized === `${top}/__init__.pyi` ||
+        normalized.endsWith(`/${top}/__init__.py`) ||
+        normalized.endsWith(`/${top}/__init__.pyi`));
+}
+// A first-party package maps to a scope file by directory, so namespace
+// packages without `__init__.py` still count. Matching is slash-bounded,
+// so `app` never claims `myapp/` or `appdata/`.
+function firstPartyDir(top, normalized) {
+    return normalized.startsWith(`${top}/`) || normalized.includes(`/${top}/`);
+}
+// A first-party package maps to a scope file by module path or by
+// directory, so namespace packages without `__init__.py` still count.
+// Matching is slash-bounded, so `app` never claims `myapp/` or `appdata/`.
+function isFirstParty(top, files) {
+    for (const file of files) {
+        const normalized = file.replaceAll("\\", "/");
+        if (firstPartyModuleFile(top, normalized) ||
+            firstPartyInitFile(top, normalized) ||
+            firstPartyDir(top, normalized)) {
+            return true;
+        }
+    }
+    return false;
+}
+// Judge one scope file for phantom imports: unreadable files and an
+// unparseable nearest manifest fail closed, otherwise every undeclared,
+// non-stdlib, non-first-party top level blocks.
+async function checkPythonFileForPhantoms(binding, ports, file, scopeFiles) {
+    const findings = [];
+    if (!isPythonFile(file)) {
+        return findings;
+    }
+    const loaded = await readLossyText(ports.fs, file);
+    if (!loaded.ok) {
+        findings.push(readErrorFinding(binding, file, loaded.error, "read"));
+        return findings;
+    }
+    const declared = await declaredNamesFor(ports, file);
+    if (declared.broken !== undefined) {
+        findings.push(readErrorFinding(binding, declared.broken, makeError("CDX-E903", `requirements.txt above ${file} is unparseable`, "Fix the nearest requirements.txt so it parses, then reload."), "read"));
+    }
+    // Import specifiers come from the lexer, never a regex over
+    // raw text, so specifiers inside strings, comments and
+    // fixture text never count.
+    findings.push(...phantomFindings(binding, file, loaded.value.text, declared.names, scopeFiles));
+    return findings;
+}
+// SPEC §6.3 python/no-phantom-import: a top-level import resolves to a
+// declared dependency, the standard library, or a first-party package.
+// Relative and stdlib imports never block.
+export function resolvePythonNoPhantomImport(decl, rule, ports) {
+    const binding = bindRule(rule);
+    return ok(baseEnforcer(rule, binding, decl, async (ctx) => {
+        const findings = [];
+        const scopeFiles = [...ctx.scope.files].sort();
+        for (const file of selectFiles(ctx.scope.files, binding.scopeGlobs)) {
+            findings.push(...(await checkPythonFileForPhantoms(binding, ports, file, scopeFiles)));
+        }
+        return findings;
+    }));
+}
+function phantomFindings(binding, file, text, declared, scopeFiles) {
+    const findings = [];
+    const seen = new Set();
+    for (const { spec, line } of extractPythonSpecifiers(text)) {
+        if (seen.has(spec)) {
+            continue;
+        }
+        seen.add(spec);
+        if (isRelativePythonSpec(spec)) {
+            continue;
+        }
+        const top = pythonTopSegment(spec);
+        if (isPythonStdlib(top) ||
+            isFirstParty(top, scopeFiles) ||
+            declared.has(top)) {
+            continue;
+        }
+        findings.push(findingFor(binding, {
+            path: file,
+            line,
+            message: `phantom import ${spec} in ${file}:${String(line)}`,
+            vars: { path: file, line: String(line), value: spec },
+        }));
+    }
+    return findings;
+}

package/dist/features/packs/enforcers/py-pins.d.ts

@@ -0,0 +1,16 @@
+import type { Finding } from "../../engine/index.ts";
+import type { RuleBinding } from "./binding.ts";
+export declare function isRequirementsFile(path: string): boolean;
+export interface PythonRequirement {
+    readonly name: string;
+    readonly spec: string;
+    readonly line: number;
+}
+export interface PythonRequirements {
+    readonly reqs: Array<PythonRequirement>;
+    readonly brokenLine: number | undefined;
+}
+export declare function parsePythonRequirements(text: string): PythonRequirements;
+export declare function isExactPythonPin(spec: string): boolean;
+export declare function collectPyprojectNames(text: string): Set<string>;
+export declare function checkPythonPins(binding: RuleBinding, file: string, text: string, findings: Array<Finding>): void;