depyo 1.0.1 → 1.0.2

package/README.md

@@ -32,6 +32,9 @@ node depyo.js --out /path/to/file.pyc
 # Marshal-only blob (no .pyc header)
 node depyo.js --marshal --py-version 3.11 /path/to/blob.bin
 node depyo.js --marshal /path/to/blob.bin
+
+# Fast marshal scan (no decompile)
+node depyo.js --marshal-scan /path/to/blob.bin
 ```
 Without `--py-version`, depyo scans supported versions (oldest → newest) and accepts the first clean output when all clean candidates agree. If outputs diverge (ambiguous), it stops and asks for `--py-version`. Use `--debug` to see scan results.
 
@@ -45,6 +48,7 @@ Without `--py-version`, depyo scans supported versions (oldest → newest) and a
 - `--skip-path` flatten output paths (write next to input)
 - `--out` print source to stdout instead of files
 - `--marshal` treat input as raw marshalled data (no .pyc header, auto-scan versions)
+- `--marshal-scan` fast scan marshal blobs and print version candidates
 - `--py-version <x.y>` bytecode version hint (use with `--marshal`)
 - `--basedir <dir>` override output root (default: alongside input)
 - `--file-ext <ext>` change emitted extension (default `py`)

package/depyo.js

@@ -21,6 +21,7 @@ global.g_cliArgs = {
     skipPath: false,
     sendToStdout: false,
     marshal: false,
+    marshalScan: false,
     pyVersion: null,
     silent: false,
     fileExt: 'py',
@@ -33,6 +34,7 @@ let g_totalOutThroughput = 0;
 let g_totalExecTime = 0;
 let g_totalFiles = 0;
 let g_pyVersionInfo = null;
+let g_marshalScanStats = {ok: 0, ambiguous: 0, failed: 0};
 
 function printUsage() {
     console.log(`Usage: node depyo.js [options] <file.pyc|archive.zip> [...]
@@ -48,6 +50,7 @@ Options:
   --skip-path         Flatten output paths (write files next to inputs)
   --out               Print decompiled source to stdout instead of files
   --marshal           Treat input as raw marshalled data (no .pyc header)
+  --marshal-scan      Fast scan of marshal blobs (no decompile, prints version)
   --py-version <x.y>  Python bytecode version hint (auto-scan if omitted)
   --basedir <path>    Output base directory (default: alongside input)
   --file-ext <ext>    Extension for generated source (default: py)
@@ -77,6 +80,9 @@ function parseCLIParams() {
             g_cliArgs.sendToStdout = true;
         } else if (cliParam.toLowerCase() == "--marshal") {
             g_cliArgs.marshal = true;
+        } else if (cliParam.toLowerCase() == "--marshal-scan" || cliParam.toLowerCase() == "--marshal-smoke") {
+            g_cliArgs.marshalScan = true;
+            g_cliArgs.marshal = true;
         } else if (cliParam.toLowerCase() == "--py-version") {
             g_cliArgs.pyVersion = process.argv[++idx];
         } else if (cliParam.toLowerCase() == "--basedir") {
@@ -103,6 +109,44 @@ function normalizeMarshalOutput(src) {
         .trim();
 }
 
+function scanMarshalBuffer(buffer, filenameLabel) {
+    if (g_pyVersionInfo) {
+        const trial = PycReader.TryParseMarshal(buffer, g_pyVersionInfo);
+        if (!trial) {
+            g_marshalScanStats.failed++;
+            console.log(`${filenameLabel}: no parse with ${g_pyVersionInfo.major}.${g_pyVersionInfo.minor}`);
+            return;
+        }
+        g_marshalScanStats.ok++;
+        console.log(`${filenameLabel}: forced ${g_pyVersionInfo.major}.${g_pyVersionInfo.minor} unknown=${trial.unknown}/${trial.total} remaining=${trial.remaining}`);
+        return;
+    }
+
+    const results = PycReader.ScanMarshalCandidates(buffer);
+    if (!results.length) {
+        g_marshalScanStats.failed++;
+        console.log(`${filenameLabel}: no candidates`);
+        return;
+    }
+
+    const best = results[0];
+    const ambiguous = results.filter(r =>
+        r.unknown === best.unknown &&
+        r.remaining === best.remaining &&
+        r.unknownRatio === best.unknownRatio
+    );
+
+    if (ambiguous.length > 1) {
+        g_marshalScanStats.ambiguous++;
+        const versions = ambiguous.map(r => `${r.versionInfo.major}.${r.versionInfo.minor}`).join(', ');
+        console.log(`${filenameLabel}: ambiguous candidates (${versions})`);
+        return;
+    }
+
+    g_marshalScanStats.ok++;
+    console.log(`${filenameLabel}: best=${best.versionInfo.major}.${best.versionInfo.minor} unknown=${best.unknown}/${best.total} remaining=${best.remaining}`);
+}
+
 function attemptMarshalDecompile(buffer, versionInfo, opts = {}) {
     const prevSilent = g_cliArgs.silent;
     const prevDebug = g_cliArgs.debug;
@@ -195,6 +239,11 @@ function decompilePycObject(data) {
         if (!Buffer.isBuffer(buffer)) {
             buffer = fs.readFileSync(data);
         }
+        if (g_cliArgs.marshalScan) {
+            const label = typeof data === 'string' ? data : '<buffer>';
+            scanMarshalBuffer(buffer, label);
+            return;
+        }
         let rdr = null;
         let pySrc = null;
         let genSecs = 0;
@@ -369,6 +418,17 @@ g_baseDir = Path.resolve(baseInputDir, 'decompiled') + '/';
 
 DecompileModule(g_cliArgs.filenames);
 
+if (g_cliArgs.marshalScan) {
+    console.log(`Marshal scan summary: ok=${g_marshalScanStats.ok}, ambiguous=${g_marshalScanStats.ambiguous}, failed=${g_marshalScanStats.failed}`);
+    if (g_marshalScanStats.failed > 0) {
+        process.exit(1);
+    }
+    if (g_marshalScanStats.ambiguous > 0) {
+        process.exit(2);
+    }
+    process.exit(0);
+}
+
 if (!g_cliArgs.sendToStdout) {
     const inRate = (g_totalInThroughput / g_totalExecTime).toFixed(2);
     const outRate = (g_totalOutThroughput / g_totalExecTime).toFixed(2);

package/lib/PycReader.js

@@ -280,6 +280,34 @@ class PycReader
         return best ? best.candidate : null;
     }
 
+    static ScanMarshalCandidates(buffer) {
+        const candidates = PycReader.ListSupportedVersions(false);
+        const results = [];
+        for (const candidate of candidates) {
+            const trial = PycReader.TryParseMarshal(buffer, candidate);
+            if (!trial) {
+                continue;
+            }
+            results.push({...trial, versionInfo: candidate});
+        }
+        results.sort((a, b) => {
+            if (a.unknownRatio !== b.unknownRatio) {
+                return a.unknownRatio - b.unknownRatio;
+            }
+            if (a.remaining !== b.remaining) {
+                return a.remaining - b.remaining;
+            }
+            if (a.unknown !== b.unknown) {
+                return a.unknown - b.unknown;
+            }
+            if (a.versionInfo.major !== b.versionInfo.major) {
+                return a.versionInfo.major - b.versionInfo.major;
+            }
+            return a.versionInfo.minor - b.versionInfo.minor;
+        });
+        return results;
+    }
+
     static CountUnknownOpcodes(codeObject, reader, opCodeList) {
         const code = codeObject?.Code?.Value;
         if (!code || !opCodeList) {
@@ -356,7 +384,7 @@ class PycReader
             if (obj.Names?.ClassName === "Py_Tuple") {
                 score += 1;
             }
-            return {score, remaining, unknown, unknownRatio};
+            return {score, remaining, unknown, total, unknownRatio};
         } catch (ex) {
             return null;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "depyo",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Python bytecode decompiler (Python 1.0–3.14) implemented in Node.js",
   "bin": {
     "depyo": "./depyo.js"