@windsland52/maa-log-tools 1.2.2 → 1.3.0

package/dist/boundedFileReader.js

@@ -0,0 +1,96 @@
+import { lstat, open } from 'node:fs/promises';
+export class InputFileError extends Error {
+    constructor(code, filePath, message) {
+        super(message);
+        this.code = code;
+        this.filePath = filePath;
+        this.name = 'InputFileError';
+    }
+}
+const READ_CHUNK_BYTES = 64 * 1024;
+export const getFileIdentity = (stats) => ({
+    dev: stats.dev,
+    ino: stats.ino,
+});
+export const sameFileIdentity = (left, right) => left.dev === right.dev && left.ino === right.ino;
+const assertRegularPath = (filePath, stats) => {
+    if (stats.isSymbolicLink()) {
+        throw new InputFileError('symlink', filePath, `Symbolic-link inputs are not allowed: ${filePath}`);
+    }
+    if (!stats.isFile()) {
+        throw new InputFileError('not-regular-file', filePath, `Expected a regular file: ${filePath}`);
+    }
+};
+const assertHandleIdentity = (filePath, expected, actual) => {
+    if (!actual.isFile() || !sameFileIdentity(expected, getFileIdentity(actual))) {
+        throw new InputFileError('identity-changed', filePath, `File identity changed while opening or reading: ${filePath}`);
+    }
+};
+const assertStableContentState = (filePath, expected, actual) => {
+    if (expected.size !== actual.size
+        || expected.mtimeMs !== actual.mtimeMs
+        || expected.ctimeMs !== actual.ctimeMs) {
+        throw new InputFileError('content-changed', filePath, `File content or metadata changed while opening or reading: ${filePath}`);
+    }
+};
+export const readBoundedRegularFile = async (filePath, maxBytes, createLimitError, options = {}) => {
+    if (!Number.isSafeInteger(maxBytes) || maxBytes < 0) {
+        throw new RangeError('Maximum file read size must be a non-negative safe integer');
+    }
+    const beforeOpen = await lstat(filePath);
+    assertRegularPath(filePath, beforeOpen);
+    const beforeIdentity = getFileIdentity(beforeOpen);
+    if (options.expectedIdentity && !sameFileIdentity(options.expectedIdentity, beforeIdentity)) {
+        throw new InputFileError('identity-changed', filePath, `File identity changed after directory discovery: ${filePath}`);
+    }
+    const handle = await open(filePath, 'r');
+    try {
+        const opened = await handle.stat();
+        assertHandleIdentity(filePath, beforeIdentity, opened);
+        assertStableContentState(filePath, beforeOpen, opened);
+        const afterOpen = await lstat(filePath);
+        assertRegularPath(filePath, afterOpen);
+        assertHandleIdentity(filePath, beforeIdentity, afterOpen);
+        assertStableContentState(filePath, opened, afterOpen);
+        if (opened.size > maxBytes)
+            throw createLimitError(opened.size);
+        const chunks = [];
+        let totalBytes = 0;
+        let chunkCount = 0;
+        while (totalBytes <= maxBytes) {
+            const remaining = maxBytes + 1 - totalBytes;
+            if (remaining <= 0)
+                break;
+            const buffer = Buffer.allocUnsafe(Math.min(READ_CHUNK_BYTES, remaining));
+            const { bytesRead } = await handle.read(buffer, 0, buffer.byteLength, totalBytes);
+            if (bytesRead === 0)
+                break;
+            totalBytes += bytesRead;
+            chunkCount += 1;
+            if (totalBytes > maxBytes)
+                throw createLimitError(totalBytes);
+            chunks.push(buffer.subarray(0, bytesRead));
+            await options.onChunkRead?.({ handle, bytesRead: totalBytes, chunkCount });
+        }
+        const finalHandleStats = await handle.stat();
+        assertHandleIdentity(filePath, beforeIdentity, finalHandleStats);
+        const finalPathStats = await lstat(filePath);
+        assertRegularPath(filePath, finalPathStats);
+        assertHandleIdentity(filePath, beforeIdentity, finalPathStats);
+        assertStableContentState(filePath, opened, finalHandleStats);
+        assertStableContentState(filePath, opened, finalPathStats);
+        if (finalHandleStats.size !== totalBytes) {
+            throw new InputFileError('size-changed', filePath, `File size changed after the bounded read completed: ${filePath}`);
+        }
+        const output = new Uint8Array(totalBytes);
+        let outputOffset = 0;
+        for (const chunk of chunks) {
+            output.set(chunk, outputOffset);
+            outputOffset += chunk.byteLength;
+        }
+        return output;
+    }
+    finally {
+        await handle.close();
+    }
+};

package/dist/cli.js

@@ -50,6 +50,9 @@ const renderOutput = (output, pretty, noEvents) => {
     return JSON.stringify(payload, null, pretty ? 2 : 0);
 };
 export const MLA_PREFLIGHT_SCHEMA_VERSION = 'mla-preflight/v1';
+const isTaskLifecycleProjection = (task) => {
+    return !task.uuid.startsWith('synthetic:resource_loading:');
+};
 const EMPTY_FRAMEWORK_EXTRACTION = {
     sessions: [],
     summary: { status: 'none', versions: [] },
@@ -71,8 +74,9 @@ export const buildPreflightOutput = (output, framework = EMPTY_FRAMEWORK_EXTRACT
             warnings: framework.warnings,
         };
     }
+    const taskLifecycleCount = output.tasks.filter(isTaskLifecycleProjection).length;
     const reason = output.events.length > 0
-        ? output.tasks.length > 0
+        ? taskLifecycleCount > 0
             ? 'notify_events_parsed'
             : 'no_task_lifecycle'
         : output.warnings.includes('Empty log content.')
@@ -83,7 +87,7 @@ export const buildPreflightOutput = (output, framework = EMPTY_FRAMEWORK_EXTRACT
         status: reason === 'notify_events_parsed' ? 'supported' : 'unsupported',
         reason,
         parserVersion: output.meta.parserVersion,
-        taskCount: output.tasks.length,
+        taskCount: taskLifecycleCount,
         eventCount: output.events.length,
         nodeStatisticCount: output.stats.nodes.length,
         recognitionStatisticCount: output.stats.recognitionActions.length,

package/dist/frameworkInput.d.ts

@@ -1,2 +1,6 @@
 import type { FrameworkLogSource } from './frameworkVersion.js';
-export declare const loadFrameworkLogSources: (targetPath: string) => Promise<FrameworkLogSource[]>;
+import { type ArchiveLimits } from './archiveLimits.js';
+export interface LoadFrameworkLogSourcesOptions {
+    archiveLimits?: Partial<ArchiveLimits>;
+}
+export declare const loadFrameworkLogSources: (targetPath: string, options?: LoadFrameworkLogSourcesOptions) => Promise<FrameworkLogSource[]>;

package/dist/frameworkInput.js

@@ -1,7 +1,7 @@
-import { readFile, readdir, stat } from 'node:fs/promises';
+import { lstat } from 'node:fs/promises';
 import path from 'node:path';
-import { unzipSync } from 'fflate';
-import { readNodeTextFileContent } from './nodeInput.js';
+import { extractInspectedZipEntriesWithinLimits, inspectZipDirectory, resolveArchiveLimits, } from './archiveLimits.js';
+import { createNodeInputBudgetContext, findExistingRegularNodeFile, InputFileError, readNodeArchiveFileBytes, readNodeTextFileContent, readNodeTextFilesContent, resolveNodeDebugDirectory, } from './nodeInput.js';
 const MAIN_LOG_NAMES = ['maafw.log', 'maa.log'];
 const BAK_LOG_NAMES = ['maafw.bak.log', 'maa.bak.log'];
 const toPosixPath = (value) => value.replace(/\\/g, '/');
@@ -31,9 +31,10 @@ const findZipBasePath = (paths) => {
     }
     return null;
 };
-const loadZipSources = async (zipPath) => {
-    const files = unzipSync(new Uint8Array(await readFile(zipPath)));
-    const paths = Object.keys(files);
+const loadZipSources = async (zipPath, limits) => {
+    const bytes = await readNodeArchiveFileBytes(zipPath, limits);
+    const entries = inspectZipDirectory(bytes, limits);
+    const paths = entries.map((entry) => entry.name);
     const basePath = findZipBasePath(paths);
     if (basePath == null)
         return [];
@@ -45,6 +46,8 @@ const loadZipSources = async (zipPath) => {
         if (candidate && MAIN_LOG_NAMES.includes(name))
             break;
     }
+    const selectedPaths = new Set(selected);
+    const { files } = extractInspectedZipEntriesWithinLimits(bytes, entries, (entryPath) => selectedPaths.has(entryPath), limits);
     return selected.flatMap((entryPath) => {
         const bytes = files[entryPath];
         if (!bytes)
@@ -58,67 +61,43 @@ const loadZipSources = async (zipPath) => {
             }];
     });
 };
-const pathExists = async (candidate) => {
-    try {
-        await stat(candidate);
-        return true;
-    }
-    catch {
-        return false;
-    }
-};
-const findDebugDirectory = async (root) => {
-    for (const name of MAIN_LOG_NAMES) {
-        if (await pathExists(path.join(root, name)))
-            return root;
-    }
-    const directDebug = path.join(root, 'debug');
-    for (const name of MAIN_LOG_NAMES) {
-        if (await pathExists(path.join(directDebug, name)))
-            return directDebug;
-    }
-    for (const entry of await readdir(root, { withFileTypes: true })) {
-        if (!entry.isDirectory())
-            continue;
-        const found = await findDebugDirectory(path.join(root, entry.name));
-        if (found)
-            return found;
-    }
-    return null;
-};
-const firstExisting = async (root, names) => {
-    for (const name of names) {
-        const candidate = path.join(root, name);
-        if (await pathExists(candidate))
-            return candidate;
-    }
-    return null;
-};
-const loadDirectorySources = async (directoryPath) => {
-    const debugPath = await findDebugDirectory(directoryPath);
+const loadDirectorySources = async (directoryPath, limits) => {
+    const context = await createNodeInputBudgetContext(directoryPath, limits);
+    const debugPath = await resolveNodeDebugDirectory(directoryPath, context);
     if (!debugPath)
         return [];
     const selected = [
-        await firstExisting(debugPath, BAK_LOG_NAMES),
-        await firstExisting(debugPath, MAIN_LOG_NAMES),
+        await findExistingRegularNodeFile(context, debugPath, BAK_LOG_NAMES),
+        await findExistingRegularNodeFile(context, debugPath, MAIN_LOG_NAMES),
     ].filter((candidate) => candidate != null);
-    return Promise.all(selected.map(async (absolutePath) => ({
+    const contents = await readNodeTextFilesContent(selected, {
+        archiveLimits: limits,
+        budgetContext: context,
+    });
+    return selected.map((absolutePath, index) => ({
         path: toPosixPath(path.relative(debugPath, absolutePath)),
         name: path.basename(absolutePath),
-        content: await readNodeTextFileContent(absolutePath),
+        content: contents[index] ?? '',
         reference: `file:${toPosixPath(absolutePath)}`,
-    })));
+    }));
 };
-export const loadFrameworkLogSources = async (targetPath) => {
-    const targetStat = await stat(targetPath);
+export const loadFrameworkLogSources = async (targetPath, options = {}) => {
+    const limits = resolveArchiveLimits(options.archiveLimits);
+    const targetStat = await lstat(targetPath);
+    if (targetStat.isSymbolicLink()) {
+        throw new InputFileError('symlink', targetPath, `Symbolic-link inputs are not allowed: ${targetPath}`);
+    }
     if (targetStat.isDirectory())
-        return loadDirectorySources(targetPath);
+        return loadDirectorySources(targetPath, limits);
+    if (!targetStat.isFile()) {
+        throw new InputFileError('not-regular-file', targetPath, `Expected a regular file: ${targetPath}`);
+    }
     if (targetPath.toLowerCase().endsWith('.zip'))
-        return loadZipSources(targetPath);
+        return loadZipSources(targetPath, limits);
     return [{
             path: toPosixPath(targetPath),
             name: path.basename(targetPath),
-            content: await readNodeTextFileContent(targetPath),
+            content: await readNodeTextFileContent(targetPath, { archiveLimits: limits }),
             reference: `file:${toPosixPath(targetPath)}`,
         }];
 };

package/dist/index.d.ts

@@ -1,23 +1,26 @@
 import type { KernelOutput } from '@windsland52/maa-log-kernel';
 import type { AnalyzeLogContentInput, ParseFileOptions } from '@windsland52/maa-log-runtime';
-import { type LogBundleFocus } from './nodeInput.js';
+import { type ArchiveLimits, type LogBundleFocus } from './nodeInput.js';
 type ParseOptions = ParseFileOptions;
 export interface AnalyzeZipBufferInput {
     zipData: Uint8Array;
     sourceRef?: string;
     focus?: LogBundleFocus;
+    archiveLimits?: Partial<ArchiveLimits>;
     parseOptions?: ParseOptions;
     parserVersion?: string;
 }
 export interface AnalyzeZipFileInput {
     zipFilePath: string;
     focus?: LogBundleFocus;
+    archiveLimits?: Partial<ArchiveLimits>;
     parseOptions?: ParseOptions;
     parserVersion?: string;
 }
 export interface AnalyzeDirectoryInput {
     directoryPath: string;
     focus?: LogBundleFocus;
+    archiveLimits?: Partial<ArchiveLimits>;
     parseOptions?: ParseOptions;
     parserVersion?: string;
 }

package/dist/index.js

@@ -10,6 +10,7 @@ export const analyzeLogContent = async (input) => {
 export const analyzeZipBuffer = async (input) => {
     const extracted = extractZipContentFromNodeBuffer(input.zipData, input.sourceRef, {
         focus: input.focus,
+        archiveLimits: input.archiveLimits,
     });
     if (!extracted)
         return null;
@@ -25,6 +26,7 @@ export const analyzeZipBuffer = async (input) => {
 export const analyzeZipFile = async (input) => {
     const extracted = await extractZipContentFromNodeFile(input.zipFilePath, {
         focus: input.focus,
+        archiveLimits: input.archiveLimits,
     });
     if (!extracted)
         return null;
@@ -40,6 +42,7 @@ export const analyzeZipFile = async (input) => {
 export const analyzeDirectory = async (input) => {
     const extracted = await loadNodeLogDirectory(input.directoryPath, {
         focus: input.focus,
+        archiveLimits: input.archiveLimits,
     });
     if (!extracted)
         return null;

package/dist/nodeInput.d.ts

@@ -1,4 +1,9 @@
 import type { SourceSegment } from './runtimeInspection.js';
+import { type ArchiveDirectoryBudget, type ArchiveLimits, type ExtractionBudget } from './archiveLimits.js';
+import { type FileIdentity } from './boundedFileReader.js';
+export { ArchiveFormatError, ArchiveLimitError, DEFAULT_ARCHIVE_LIMITS, resolveArchiveLimits, } from './archiveLimits.js';
+export { InputFileError } from './boundedFileReader.js';
+export type { ArchiveFormatCode, ArchiveLimitCode, ArchiveLimits } from './archiveLimits.js';
 export interface KernelTextFile {
     path: string;
     name: string;
@@ -20,11 +25,32 @@ export interface LogBundleFocus {
 }
 export interface ExtractZipContentOptions {
     focus?: LogBundleFocus;
+    archiveLimits?: Partial<ArchiveLimits>;
 }
 export interface LoadNodeLogDirectoryOptions {
     focus?: LogBundleFocus;
+    archiveLimits?: Partial<ArchiveLimits>;
 }
-export declare const readNodeTextFileContent: (filePath: string) => Promise<string>;
+export interface ReadNodeTextFileOptions {
+    archiveLimits?: Partial<ArchiveLimits>;
+    budgetContext?: NodeInputBudgetContext;
+}
+export interface NodeInputBudgetContext {
+    readonly limits: Readonly<ArchiveLimits>;
+    readonly rootPath: string;
+    readonly rootRealPath: string;
+    directory: ArchiveDirectoryBudget;
+    extraction: ExtractionBudget;
+    readonly chargedPaths: Set<string>;
+    readonly discoveredIdentities: Map<string, FileIdentity>;
+}
+export declare const createNodeInputBudgetContext: (rootPath: string, limits: Readonly<ArchiveLimits>, requireDirectoryRoot?: boolean) => Promise<NodeInputBudgetContext>;
+export declare const readNodeTextFileContent: (filePath: string, options?: ReadNodeTextFileOptions) => Promise<string>;
+export declare const readNodeTextFilesContent: (filePaths: readonly string[], options?: ReadNodeTextFileOptions) => Promise<string[]>;
 export declare const extractZipContentFromNodeBuffer: (zipData: Uint8Array, sourceRef?: string, options?: ExtractZipContentOptions) => NodeExtractedLogContent | null;
 export declare const extractZipContentFromNodeFile: (zipFilePath: string, options?: ExtractZipContentOptions) => Promise<NodeExtractedLogContent | null>;
+export declare const readNodeArchiveFileBytes: (zipFilePath: string, limits: Readonly<ArchiveLimits>) => Promise<Uint8Array>;
+export declare const hasNodeMainLogInDirectory: (context: NodeInputBudgetContext, directoryPath: string) => Promise<boolean>;
+export declare const findExistingRegularNodeFile: (context: NodeInputBudgetContext, directoryPath: string, names: readonly string[]) => Promise<string | null>;
+export declare const resolveNodeDebugDirectory: (inputPath: string, context: NodeInputBudgetContext) => Promise<string | null>;
 export declare const loadNodeLogDirectory: (inputDirectoryPath: string, options?: LoadNodeLogDirectoryOptions) => Promise<NodeExtractedLogContent | null>;