@contractkit/plugin-python 0.11.6 → 0.11.7

package/src/codegen-models.ts

@@ -1,4 +1,4 @@
-import type { ContractRootNode, ModelNode, FieldNode, ContractTypeNode } from '@contractkit/core';
+import type { ContractRootNode, ModelNode, FieldNode, ContractTypeNode, ScalarTypeNode } from '@contractkit/core';
 import { computeModelsWithInput, topoSortModels, collectExternalRefs, collectExternalInputRefs } from '@contractkit/core';
 
 // ─── Public entry point ────────────────────────────────────────────────────
@@ -173,6 +173,15 @@ function scanTypeImports(type: ContractTypeNode, imports: ImportTracker): void {
 
 // ─── Type rendering ───────────────────────────────────────────────────────
 
+/**
+ * Render a ContractKit type node as its Python type annotation (Pydantic v2 conventions).
+ *
+ * @param modelsWithInput - Model names that have a distinct `Input` variant; a `ref` to one of
+ *   these renders as `<Name>Input` when `forInput` is set.
+ * @param forInput - When true, request-side refs use their `Input` variant.
+ * @throws {Error} Via the scalar renderer, if a scalar name has no Python mapping (guards against
+ *   a scalar being added to core without updating this plugin).
+ */
 export function renderPyType(type: ContractTypeNode, modelsWithInput?: Set<string>, forInput = false): string {
     switch (type.kind) {
         case 'scalar':
@@ -209,7 +218,7 @@ export function renderPyType(type: ContractTypeNode, modelsWithInput?: Set<strin
     }
 }
 
-function renderScalar(name: string): string {
+function renderScalar(name: ScalarTypeNode['name']): string {
     switch (name) {
         case 'string':
         case 'email':
@@ -231,6 +240,8 @@ function renderScalar(name: string): string {
             return 'datetime';
         case 'duration':
             return 'timedelta';
+        case 'interval':
+            return 'str';
         case 'uuid':
             return 'UUID';
         case 'null':
@@ -241,8 +252,10 @@ function renderScalar(name: string): string {
         case 'json':
         case 'object':
             return 'Any';
-        default:
-            return 'Any';
+        default: {
+            const _exhaustive: never = name;
+            throw new Error(`plugin-python: unmapped scalar '${String(_exhaustive)}' — add a case`);
+        }
     }
 }
 
@@ -261,6 +274,19 @@ export function toPythonFieldName(name: string): string {
     return result;
 }
 
+// ─── Comment emission ─────────────────────────────────────────────────────
+
+/**
+ * Render `text` as one `#`-prefixed Python comment line per source line.
+ * Descriptions come from `#` doc comments and may contain embedded newlines;
+ * emitting them verbatim would leave every line after the first uncommented
+ * (a SyntaxError in the generated module). `indent` is the whitespace prefix
+ * that precedes `# ` at the call site.
+ */
+function commentLines(text: string, indent: string): string[] {
+    return text.split('\n').map(line => `${indent}# ${line}`);
+}
+
 // ─── Model generation ─────────────────────────────────────────────────────
 
 function generateModel(model: ModelNode, allModelsWithInput: Set<string>, imports: ImportTracker): string[] {
@@ -278,7 +304,7 @@ function generateModel(model: ModelNode, allModelsWithInput: Set<string>, import
 
 function generateTypeAlias(model: ModelNode, allModelsWithInput: Set<string>, _: ImportTracker): string[] {
     const lines: string[] = [];
-    if (model.description) lines.push(`# ${model.description}`);
+    if (model.description) lines.push(...commentLines(model.description, ''));
     if (model.deprecated) lines.push('# @deprecated');
     lines.push(`${model.name} = ${renderPyType(model.type!, allModelsWithInput)}`);
     if (allModelsWithInput.has(model.name)) {
@@ -289,7 +315,7 @@ function generateTypeAlias(model: ModelNode, allModelsWithInput: Set<string>, _:
 
 function generateSimpleModel(model: ModelNode, allModelsWithInput: Set<string>, imports: ImportTracker): string[] {
     const lines: string[] = [];
-    if (model.description) lines.push(`# ${model.description}`);
+    if (model.description) lines.push(...commentLines(model.description, ''));
     if (model.deprecated) lines.push('# @deprecated');
 
     const baseList = model.bases && model.bases.length > 0 ? model.bases.join(', ') : 'BaseModel';
@@ -317,7 +343,7 @@ function generateSplitModel(model: ModelNode, allModelsWithInput: Set<string>, i
 
     // Read model — omit writeonly fields
     const readFields = model.fields.filter(f => f.visibility !== 'writeonly');
-    if (model.description) lines.push(`# ${model.description}`);
+    if (model.description) lines.push(...commentLines(model.description, ''));
     if (model.deprecated) lines.push('# @deprecated');
 
     const readBaseList = model.bases && model.bases.length > 0 ? model.bases.join(', ') : 'BaseModel';
@@ -387,7 +413,7 @@ function renderField(field: FieldNode, allModelsWithInput: Set<string>, imports:
     }
 
     if (field.deprecated) lines.push(`    # @deprecated`);
-    if (field.description) lines.push(`    # ${field.description}`);
+    if (field.description) lines.push(...commentLines(field.description, '    '));
 
     let rhs: string;
     if (fieldAnnotations.length > 0) {

package/tests/codegen-client.test.ts

@@ -358,4 +358,68 @@ describe('generatePythonClient', () => {
             expect(output).not.toContain('_fetch_with_headers');
         });
     });
+
+    // ─── Docstring injection (regression) ─────────────────────────────────
+
+    describe('docstring safety', () => {
+        it('escapes """ in op name/description so it cannot close the docstring early', () => {
+            const root = opRoot([
+                opRoute('/payments', [
+                    opOperation('get', {
+                        sdk: 'getPayment',
+                        name: 'Bad """ name',
+                        description: 'desc with """ triple quote',
+                        responses: [opResponse(200, 'Payment')],
+                    }),
+                ]),
+            ]);
+            const output = generatePythonClient(root);
+
+            // The escaped form is emitted...
+            expect(output).toContain('Bad \\"\\"\\" name');
+            expect(output).toContain('desc with \\"\\"\\" triple quote');
+
+            // ...and the docstring body is only closed by the real delimiter, not the
+            // injected one. Between the two `"""` fences there must be exactly the two
+            // sanitized body lines and nothing that terminates early.
+            const idx = output.indexOf('async def get_payment');
+            const body = output.slice(idx);
+            const open = body.indexOf('        """');
+            const close = body.indexOf('        """', open + 1);
+            const between = body.slice(open + '        """'.length, close);
+            expect(between).not.toMatch(/"""/); // no unescaped triple-quote inside the docstring
+            // The method body after the docstring is intact.
+            expect(body.slice(close)).toContain('await self._fetch');
+        });
+
+        it('guards a trailing backslash in a description', () => {
+            const root = opRoot([
+                opRoute('/payments', [
+                    opOperation('get', {
+                        sdk: 'getPayment',
+                        description: 'ends with backslash\\',
+                        responses: [opResponse(200, 'Payment')],
+                    }),
+                ]),
+            ]);
+            const output = generatePythonClient(root);
+            // Trailing backslash is neutralized (space appended) so it can't escape the delimiter.
+            expect(output).toContain('        ends with backslash\\ \n');
+        });
+
+        it('keeps each line of a multi-line description indented in the docstring', () => {
+            const root = opRoot([
+                opRoute('/payments', [
+                    opOperation('get', {
+                        sdk: 'getPayment',
+                        description: 'first line\nsecond line',
+                        responses: [opResponse(200, 'Payment')],
+                    }),
+                ]),
+            ]);
+            const output = generatePythonClient(root);
+            expect(output).toContain('        first line');
+            expect(output).toContain('        second line');
+        });
+    });
 });

package/tests/codegen-models.test.ts

@@ -27,6 +27,11 @@ describe('renderPyType', () => {
         expect(renderPyType(scalarType('unknown'))).toBe('Any');
         expect(renderPyType(scalarType('json'))).toBe('Any');
         expect(renderPyType(scalarType('object'))).toBe('Any');
+        expect(renderPyType(scalarType('interval'))).toBe('str');
+    });
+
+    it('throws on an unmapped scalar name', () => {
+        expect(() => renderPyType({ kind: 'scalar', name: 'decimal' } as any)).toThrow(/unmapped scalar 'decimal'/);
     });
 
     it('renders enum', () => {
@@ -293,3 +298,47 @@ describe('generatePydanticModels', () => {
         expect(output).toContain('meta: dict[str, str]');
     });
 });
+
+// ─── Multi-line descriptions (regression) ─────────────────────────────────
+
+describe('multi-line descriptions', () => {
+    it('comments every line of a multi-line model description', () => {
+        const root = contractRoot([
+            model('Payment', [field('amount', scalarType('number'))], {
+                description: 'A payment record.\nSecond line of docs.',
+            }),
+        ]);
+        const output = generatePydanticModels(root);
+        expect(output).toContain('# A payment record.');
+        expect(output).toContain('# Second line of docs.');
+        // No physical line of a description may be left uncommented (would be a SyntaxError).
+        expect(output).not.toMatch(/^Second line of docs\.$/m);
+    });
+
+    it('comments every line of a multi-line field description with field indent', () => {
+        const root = contractRoot([
+            model('Payment', [
+                field('amount', scalarType('number'), {
+                    description: 'Amount in cents.\nMust be non-negative.',
+                }),
+            ]),
+        ]);
+        const output = generatePydanticModels(root);
+        expect(output).toContain('    # Amount in cents.');
+        expect(output).toContain('    # Must be non-negative.');
+        expect(output).not.toMatch(/^\s*Must be non-negative\.$/m);
+    });
+
+    it('comments every line of a multi-line type-alias description', () => {
+        const root = contractRoot([
+            model('Status', [], {
+                type: enumType('pending', 'done'),
+                description: 'Lifecycle status.\nExtra detail line.',
+            }),
+        ]);
+        const output = generatePydanticModels(root);
+        expect(output).toContain('# Lifecycle status.');
+        expect(output).toContain('# Extra detail line.');
+        expect(output).not.toMatch(/^Extra detail line\.$/m);
+    });
+});

package/coverage/base.css

@@ -1,224 +0,0 @@
-body, html {
-  margin:0; padding: 0;
-  height: 100%;
-}
-body {
-    font-family: Helvetica Neue, Helvetica, Arial;
-    font-size: 14px;
-    color:#333;
-}
-.small { font-size: 12px; }
-*, *:after, *:before {
-  -webkit-box-sizing:border-box;
-     -moz-box-sizing:border-box;
-          box-sizing:border-box;
-  }
-h1 { font-size: 20px; margin: 0;}
-h2 { font-size: 14px; }
-pre {
-    font: 12px/1.4 Consolas, "Liberation Mono", Menlo, Courier, monospace;
-    margin: 0;
-    padding: 0;
-    -moz-tab-size: 2;
-    -o-tab-size:  2;
-    tab-size: 2;
-}
-a { color:#0074D9; text-decoration:none; }
-a:hover { text-decoration:underline; }
-.strong { font-weight: bold; }
-.space-top1 { padding: 10px 0 0 0; }
-.pad2y { padding: 20px 0; }
-.pad1y { padding: 10px 0; }
-.pad2x { padding: 0 20px; }
-.pad2 { padding: 20px; }
-.pad1 { padding: 10px; }
-.space-left2 { padding-left:55px; }
-.space-right2 { padding-right:20px; }
-.center { text-align:center; }
-.clearfix { display:block; }
-.clearfix:after {
-  content:'';
-  display:block;
-  height:0;
-  clear:both;
-  visibility:hidden;
-  }
-.fl { float: left; }
-@media only screen and (max-width:640px) {
-  .col3 { width:100%; max-width:100%; }
-  .hide-mobile { display:none!important; }
-}
-
-.quiet {
-  color: #7f7f7f;
-  color: rgba(0,0,0,0.5);
-}
-.quiet a { opacity: 0.7; }
-
-.fraction {
-  font-family: Consolas, 'Liberation Mono', Menlo, Courier, monospace;
-  font-size: 10px;
-  color: #555;
-  background: #E8E8E8;
-  padding: 4px 5px;
-  border-radius: 3px;
-  vertical-align: middle;
-}
-
-div.path a:link, div.path a:visited { color: #333; }
-table.coverage {
-  border-collapse: collapse;
-  margin: 10px 0 0 0;
-  padding: 0;
-}
-
-table.coverage td {
-  margin: 0;
-  padding: 0;
-  vertical-align: top;
-}
-table.coverage td.line-count {
-    text-align: right;
-    padding: 0 5px 0 20px;
-}
-table.coverage td.line-coverage {
-    text-align: right;
-    padding-right: 10px;
-    min-width:20px;
-}
-
-table.coverage td span.cline-any {
-    display: inline-block;
-    padding: 0 5px;
-    width: 100%;
-}
-.missing-if-branch {
-    display: inline-block;
-    margin-right: 5px;
-    border-radius: 3px;
-    position: relative;
-    padding: 0 4px;
-    background: #333;
-    color: yellow;
-}
-
-.skip-if-branch {
-    display: none;
-    margin-right: 10px;
-    position: relative;
-    padding: 0 4px;
-    background: #ccc;
-    color: white;
-}
-.missing-if-branch .typ, .skip-if-branch .typ {
-    color: inherit !important;
-}
-.coverage-summary {
-  border-collapse: collapse;
-  width: 100%;
-}
-.coverage-summary tr { border-bottom: 1px solid #bbb; }
-.keyline-all { border: 1px solid #ddd; }
-.coverage-summary td, .coverage-summary th { padding: 10px; }
-.coverage-summary tbody { border: 1px solid #bbb; }
-.coverage-summary td { border-right: 1px solid #bbb; }
-.coverage-summary td:last-child { border-right: none; }
-.coverage-summary th {
-  text-align: left;
-  font-weight: normal;
-  white-space: nowrap;
-}
-.coverage-summary th.file { border-right: none !important; }
-.coverage-summary th.pct { }
-.coverage-summary th.pic,
-.coverage-summary th.abs,
-.coverage-summary td.pct,
-.coverage-summary td.abs { text-align: right; }
-.coverage-summary td.file { white-space: nowrap;  }
-.coverage-summary td.pic { min-width: 120px !important;  }
-.coverage-summary tfoot td { }
-
-.coverage-summary .sorter {
-    height: 10px;
-    width: 7px;
-    display: inline-block;
-    margin-left: 0.5em;
-    background: url(sort-arrow-sprite.png) no-repeat scroll 0 0 transparent;
-}
-.coverage-summary .sorted .sorter {
-    background-position: 0 -20px;
-}
-.coverage-summary .sorted-desc .sorter {
-    background-position: 0 -10px;
-}
-.status-line {  height: 10px; }
-/* yellow */
-.cbranch-no { background: yellow !important; color: #111; }
-/* dark red */
-.red.solid, .status-line.low, .low .cover-fill { background:#C21F39 }
-.low .chart { border:1px solid #C21F39 }
-.highlighted,
-.highlighted .cstat-no, .highlighted .fstat-no, .highlighted .cbranch-no{
-  background: #C21F39 !important;
-}
-/* medium red */
-.cstat-no, .fstat-no, .cbranch-no, .cbranch-no { background:#F6C6CE }
-/* light red */
-.low, .cline-no { background:#FCE1E5 }
-/* light green */
-.high, .cline-yes { background:rgb(230,245,208) }
-/* medium green */
-.cstat-yes { background:rgb(161,215,106) }
-/* dark green */
-.status-line.high, .high .cover-fill { background:rgb(77,146,33) }
-.high .chart { border:1px solid rgb(77,146,33) }
-/* dark yellow (gold) */
-.status-line.medium, .medium .cover-fill { background: #f9cd0b; }
-.medium .chart { border:1px solid #f9cd0b; }
-/* light yellow */
-.medium { background: #fff4c2; }
-
-.cstat-skip { background: #ddd; color: #111; }
-.fstat-skip { background: #ddd; color: #111 !important; }
-.cbranch-skip { background: #ddd !important; color: #111; }
-
-span.cline-neutral { background: #eaeaea; }
-
-.coverage-summary td.empty {
-    opacity: .5;
-    padding-top: 4px;
-    padding-bottom: 4px;
-    line-height: 1;
-    color: #888;
-}
-
-.cover-fill, .cover-empty {
-  display:inline-block;
-  height: 12px;
-}
-.chart {
-  line-height: 0;
-}
-.cover-empty {
-    background: white;
-}
-.cover-full {
-    border-right: none !important;
-}
-pre.prettyprint {
-    border: none !important;
-    padding: 0 !important;
-    margin: 0 !important;
-}
-.com { color: #999 !important; }
-.ignore-none { color: #999; font-weight: normal; }
-
-.wrapper {
-  min-height: 100%;
-  height: auto !important;
-  height: 100%;
-  margin: 0 auto -48px;
-}
-.footer, .push {
-  height: 48px;
-}

package/coverage/block-navigation.js

@@ -1,87 +0,0 @@
-/* eslint-disable */
-var jumpToCode = (function init() {
-    // Classes of code we would like to highlight in the file view
-    var missingCoverageClasses = ['.cbranch-no', '.cstat-no', '.fstat-no'];
-
-    // Elements to highlight in the file listing view
-    var fileListingElements = ['td.pct.low'];
-
-    // We don't want to select elements that are direct descendants of another match
-    var notSelector = ':not(' + missingCoverageClasses.join('):not(') + ') > '; // becomes `:not(a):not(b) > `
-
-    // Selector that finds elements on the page to which we can jump
-    var selector =
-        fileListingElements.join(', ') +
-        ', ' +
-        notSelector +
-        missingCoverageClasses.join(', ' + notSelector); // becomes `:not(a):not(b) > a, :not(a):not(b) > b`
-
-    // The NodeList of matching elements
-    var missingCoverageElements = document.querySelectorAll(selector);
-
-    var currentIndex;
-
-    function toggleClass(index) {
-        missingCoverageElements
-            .item(currentIndex)
-            .classList.remove('highlighted');
-        missingCoverageElements.item(index).classList.add('highlighted');
-    }
-
-    function makeCurrent(index) {
-        toggleClass(index);
-        currentIndex = index;
-        missingCoverageElements.item(index).scrollIntoView({
-            behavior: 'smooth',
-            block: 'center',
-            inline: 'center'
-        });
-    }
-
-    function goToPrevious() {
-        var nextIndex = 0;
-        if (typeof currentIndex !== 'number' || currentIndex === 0) {
-            nextIndex = missingCoverageElements.length - 1;
-        } else if (missingCoverageElements.length > 1) {
-            nextIndex = currentIndex - 1;
-        }
-
-        makeCurrent(nextIndex);
-    }
-
-    function goToNext() {
-        var nextIndex = 0;
-
-        if (
-            typeof currentIndex === 'number' &&
-            currentIndex < missingCoverageElements.length - 1
-        ) {
-            nextIndex = currentIndex + 1;
-        }
-
-        makeCurrent(nextIndex);
-    }
-
-    return function jump(event) {
-        if (
-            document.getElementById('fileSearch') === document.activeElement &&
-            document.activeElement != null
-        ) {
-            // if we're currently focused on the search input, we don't want to navigate
-            return;
-        }
-
-        switch (event.which) {
-            case 78: // n
-            case 74: // j
-                goToNext();
-                break;
-            case 66: // b
-            case 75: // k
-            case 80: // p
-                goToPrevious();
-                break;
-        }
-    };
-})();
-window.addEventListener('keydown', jumpToCode);