@descryy/adapter-python 0.1.0

package/dist/extract.d.ts

@@ -0,0 +1,231 @@
+/**
+ * Parsed Python to Canonical IR.
+ *
+ * The Python side reports what one file says; everything that needs two files
+ * happens here, where the resolution level is tracked and can be claimed
+ * honestly.
+ *
+ * ## Name binding, which is the whole of R2 for this adapter
+ *
+ * There is no type checker (DEC-062). A name is resolved by building, per file,
+ * the set of module-level bindings that Python itself would build:
+ *
+ *   1. imports — `from .money import format_money` binds `format_money`;
+ *   2. module-level declarations — a `def` or `class` in this file;
+ *   3. module-level instantiations — `service = OrderService()`, the one
+ *      inference made anywhere in this adapter.
+ *
+ * Anything else resolves to nothing and is disclosed. `self.repo.save()`,
+ * `getattr(obj, name)()`, a name rebound in a loop — all absent, all recorded.
+ * That is the recall cost of having no checker, and it is stated rather than
+ * covered with a guess.
+ *
+ * ## The re-export hop
+ *
+ * `from . import validate_order` reaches `src/__init__.py`, which is not where
+ * `validate_order` is defined. Golden pattern 03 requires the edge to terminate
+ * at the definition and explicitly forbids it terminating at the package — the
+ * single most common symbol-resolution bug, and the one the TypeScript adapter
+ * hit three separate times. `followReexport` walks the hop, with a visited set
+ * because `a/__init__.py` importing from `b/__init__.py` importing back is legal
+ * Python and must not hang the run.
+ */
+import { type IREdge, type IRNode, type ResolutionLevel, type UnresolvedRef } from "@descryy/ir";
+import { type ImportRecord } from "./module.ts";
+import { type PyAttribute } from "./orm.ts";
+import { type PytestConfig } from "./pytest-config.ts";
+export declare const LANGUAGE = "python";
+interface PyRange {
+    readonly startLine: number;
+    readonly endLine: number;
+}
+interface PyDeclaration {
+    readonly kind: "class" | "function";
+    readonly path: readonly string[];
+    readonly name: string;
+    readonly range: PyRange;
+    readonly returns?: string | null;
+    readonly params?: readonly {
+        name: string;
+        annotation: string | null;
+    }[];
+    readonly bases?: readonly (string | null)[];
+    readonly fields?: readonly {
+        name: string;
+        annotation: string | null;
+        hasDefault: boolean;
+    }[];
+    /** Every assignment in the class body. Optional so a pre-DEC-093 recording still parses. */
+    readonly attributes?: readonly PyAttribute[];
+    readonly decorators?: readonly (string | null)[];
+    /** Decorators that are calls, structured. Optional so a pre-DEC-099 recording still parses. */
+    readonly decoratorCalls?: readonly PyCall[];
+}
+/**
+ * One call as `extract.py` recorded it — receiver, attribute, arguments.
+ *
+ * `literals` and `argNames` are parallel to `args` and are the whole point: a
+ * path written as a string and a path computed at runtime must stay
+ * distinguishable here, because a route emitted for the second joins a caller
+ * to an endpoint that does not exist, and no layer above the graph can tell
+ * that from a correct edge.
+ */
+/** `app = flask.Flask(__name__)` — the target, the callee as written, the line. */
+export interface PyConstruction {
+    readonly local: string;
+    readonly callee: string | null;
+    readonly scope: readonly string[];
+    readonly line: number;
+}
+export interface PyCall {
+    readonly callee: string | null;
+    readonly receiver: string | null;
+    readonly attribute: string | null;
+    readonly args: readonly string[];
+    readonly literals: readonly (string | number | boolean | null)[];
+    readonly argNames: readonly (string | null)[];
+    /** One level of nesting: `path("api/", include("app.urls"))`. */
+    readonly argCalls: readonly (PyCall | null)[];
+    readonly hasLiterals: readonly boolean[];
+    readonly keywords: Readonly<Record<string, unknown>>;
+    readonly keywordNames: Readonly<Record<string, string>>;
+    /** Every keyword's value as source text, bare name or not. */
+    readonly keywordText: Readonly<Record<string, string>>;
+    /** Keyword arguments written as a list or tuple of constants: `methods=["GET"]`. */
+    readonly keywordLists: Readonly<Record<string, readonly unknown[]>>;
+    readonly opaqueKeywords: readonly string[];
+    /** The scope the call is evaluated in — `[]` at module level. */
+    readonly scope: readonly string[];
+    readonly line: number;
+}
+interface PyReference {
+    readonly kind: "call" | "method" | "attribute" | "attribute_write" | "annotation";
+    readonly name: string | null;
+    readonly receiver: string | null;
+    readonly scope: readonly string[];
+    readonly line: number;
+}
+interface PyInstantiation {
+    readonly local: string;
+    readonly typeName: string;
+    readonly scope: readonly string[];
+    readonly line: number;
+}
+/**
+ * A module-level type alias (DEC-069), already classified on the Python side —
+ * `rule` records *which* admission rule accepted it, so a surprising node can be
+ * traced to the rule that produced it rather than re-derived.
+ */
+interface PyAlias {
+    readonly name: string;
+    readonly range: PyRange;
+    readonly rule: string;
+    readonly constituents: readonly string[];
+}
+/**
+ * A class referenced as a *value* — DEC-072.
+ *
+ * `form` is the syntactic position, kept so a form admitted on measurement can
+ * be withdrawn on measurement. Every one was counted on real code before it was
+ * included; two of them, `except` and `match`, were invisible until the AST was
+ * walked and would never have made an intuition-written list.
+ */
+interface PyValueRef {
+    readonly name: string;
+    readonly form: string;
+    readonly scope: readonly string[];
+    readonly line: number;
+}
+interface PyFile {
+    readonly declarations: readonly PyDeclaration[];
+    readonly imports: readonly ImportRecord[];
+    readonly references: readonly PyReference[];
+    readonly instantiations: readonly PyInstantiation[];
+    readonly valueRefs: readonly PyValueRef[];
+    /** Optional so a recording made before DEC-069 still parses. */
+    readonly aliases?: readonly PyAlias[];
+    /** Module-scope calls with their arguments. Optional so a pre-DEC-099 recording still parses. */
+    readonly calls?: readonly PyCall[];
+    /** `name = Call(...)`, dotted callees included. Optional for the same reason. */
+    readonly constructions?: readonly PyConstruction[];
+    /** Module-scope `NAME = "literal"`. Optional so an older recording still parses. */
+    readonly constants?: readonly PyConstant[];
+    /** `url = f"{BASE}/x"` inside a function. Optional for the same reason. */
+    readonly localStrings?: readonly PyLocalString[];
+    /** `attrs.envReads` (DEC-120/121/124). Optional for the same reason. */
+    readonly envReads?: readonly PyEnvRead[];
+    /** Reads with a non-literal key — counted, never named (DEC-121). */
+    readonly envDynamicReads?: number;
+    /** `attrs.migrationOps` (DEC-122/124). Optional for the same reason. */
+    readonly migrationOps?: readonly PyMigrationOp[];
+}
+/** One name this module reads from the environment, and whether it must be set. */
+interface PyEnvRead {
+    readonly name: string;
+    readonly required: boolean;
+    readonly line: number;
+}
+/** One destructive Alembic operation — the exact shape `readMigrationOps` expects. */
+interface PyMigrationOp {
+    readonly kind: "DROP_TABLE" | "DROP_COLUMN" | "DROP_SCHEMA" | "TRUNCATE" | "RENAME";
+    readonly target: string;
+    readonly line: number;
+    readonly section: "forward" | "reverse" | "unknown";
+    readonly guarded: boolean;
+}
+interface PyConstant {
+    readonly name: string;
+    readonly value: string;
+    readonly line: number;
+}
+interface PyLocalString {
+    readonly name: string;
+    /** Source text, not a template — every path rule lives on this side. */
+    readonly value: string;
+    readonly scope: readonly string[];
+    readonly line: number;
+}
+export interface PyResult {
+    readonly pythonVersion: string;
+    readonly files: Readonly<Record<string, PyFile>>;
+    readonly errors: Readonly<Record<string, string>>;
+}
+export interface ExtractInput {
+    readonly repo: string;
+    readonly workspace: string | undefined;
+    readonly producedBy: string;
+    readonly reached: ResolutionLevel;
+    readonly packageName: string;
+    readonly parsed: PyResult;
+    /** The repository's own collection rules. Omitted means pytest's defaults. */
+    readonly pytest?: PytestConfig;
+}
+export interface Extraction {
+    readonly nodes: readonly IRNode[];
+    readonly edges: readonly IREdge[];
+    readonly unresolved: readonly UnresolvedRef[];
+}
+/**
+ * The graph to return when the parse produced nothing but the files are there.
+ *
+ * **A failed analysis must not look like an empty repository.** The two were
+ * indistinguishable, and home-assistant-core and posthog each came back with 0
+ * nodes over ~18,000 files and a successful R0 status.
+ *
+ * A `MODULE` per file is honest at R0 and needs no parse: the file exists and
+ * its module path is a fact about the filesystem. It also gives the disclosure
+ * a real node to hang from — the ledger requires a valid `fromNodeId`, and the
+ * first attempt at this invented one and was rightly rejected by the Normaliser
+ * as `MALFORMED_UNRESOLVED_REF`, which would have thrown away the very warning
+ * it was carrying.
+ *
+ * The result reads as what it is: every module present, every module empty, and
+ * one row saying loudly why.
+ */
+export declare function degradedGraph(input: Omit<ExtractInput, "parsed"> & {
+    readonly files: readonly string[];
+    readonly cause: string;
+}): Extraction;
+export declare function extract(input: ExtractInput): Extraction;
+export {};
+//# sourceMappingURL=extract.d.ts.map

package/dist/extract.d.ts.map

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