bkper 4.9.1 → 4.10.0

package/lib/docs-compliance/live-readme.d.ts

@@ -0,0 +1,14 @@
+export interface LiveCheckConfig {
+    cliCmd: string;
+    bookId: string;
+    accountName?: string;
+    balanceSheetRootGroup?: string;
+    profitAndLossRootGroup?: string;
+}
+export interface MaterializedCommand {
+    command?: string;
+    skipReason?: string;
+}
+export declare function extractRunnableQueryCommands(content: string): string[];
+export declare function materializeCommand(command: string, config: LiveCheckConfig): MaterializedCommand;
+//# sourceMappingURL=live-readme.d.ts.map

package/lib/docs-compliance/live-readme.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"live-readme.d.ts","sourceRoot":"","sources":["../../src/docs-compliance/live-readme.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,eAAe;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,sBAAsB,CAAC,EAAE,MAAM,CAAC;CACnC;AAED,MAAM,WAAW,mBAAmB;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;CACvB;AA4DD,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CActE;AAED,wBAAgB,kBAAkB,CAC9B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,eAAe,GACxB,mBAAmB,CAiCrB"}

package/lib/docs-compliance/live-readme.js

@@ -0,0 +1,89 @@
+function getBashCodeBlocks(content) {
+    const blocks = [];
+    const regex = /```bash\n([\s\S]*?)```/g;
+    let match;
+    while ((match = regex.exec(content)) !== null) {
+        blocks.push(match[1]);
+    }
+    return blocks;
+}
+function flattenContinuationLines(block) {
+    const lines = block.split('\n').map(line => line.trimEnd());
+    const flattened = [];
+    let buffer = '';
+    for (const rawLine of lines) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith('#')) {
+            continue;
+        }
+        if (!buffer) {
+            buffer = line;
+        }
+        else {
+            buffer = `${buffer} ${line}`;
+        }
+        if (line.endsWith('\\')) {
+            buffer = buffer.slice(0, -1).trimEnd();
+            continue;
+        }
+        flattened.push(buffer.replace(/\s+/g, ' ').trim());
+        buffer = '';
+    }
+    if (buffer) {
+        flattened.push(buffer.replace(/\s+/g, ' ').trim());
+    }
+    return flattened;
+}
+function isRunnableQueryCommand(command) {
+    if (command.includes('|')) {
+        return false;
+    }
+    const queryListPattern = /^bkper\s+(transaction|balance)\s+list\b/i;
+    if (!queryListPattern.test(command)) {
+        return false;
+    }
+    return command.includes('-q ') || command.includes('--query ');
+}
+export function extractRunnableQueryCommands(content) {
+    const blocks = getBashCodeBlocks(content);
+    const commands = [];
+    for (const block of blocks) {
+        const flattened = flattenContinuationLines(block);
+        for (const command of flattened) {
+            if (isRunnableQueryCommand(command)) {
+                commands.push(command);
+            }
+        }
+    }
+    return commands;
+}
+export function materializeCommand(command, config) {
+    const replacements = [
+        ['abc123', config.bookId],
+        ['<bookId>', config.bookId],
+        ['$BOOK_ID', config.bookId],
+        ['$BOOK', config.bookId],
+        ['$BOOK_A', config.bookId],
+        ['$SOURCE', config.bookId],
+        ['<accountName>', config.accountName],
+        ['<balanceSheetRootGroup>', config.balanceSheetRootGroup],
+        ['<profitAndLossRootGroup>', config.profitAndLossRootGroup],
+    ];
+    let materialized = command.replace(/^bkper\b/, config.cliCmd);
+    for (const [token, value] of replacements) {
+        if (value) {
+            materialized = materialized.split(token).join(value);
+        }
+    }
+    const unresolvedPlaceholderPattern = /<[^>]+>|\$[A-Z_]+/;
+    if (unresolvedPlaceholderPattern.test(materialized)) {
+        return {
+            skipReason: `unresolved placeholders in command: ${materialized}`,
+        };
+    }
+    if (!materialized.includes('--format ')) {
+        materialized = `${materialized} --format csv`;
+    }
+    return { command: materialized };
+}
+//# sourceMappingURL=live-readme.js.map

package/lib/docs-compliance/live-readme.js.map

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

package/lib/docs-compliance/rules.d.ts

@@ -0,0 +1,10 @@
+export interface ComplianceError {
+    code: string;
+    message: string;
+    line?: number;
+}
+export interface ComplianceResult {
+    errors: ComplianceError[];
+}
+export declare function evaluateReadmeCompliance(content: string): ComplianceResult;
+//# sourceMappingURL=rules.d.ts.map

package/lib/docs-compliance/rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rules.d.ts","sourceRoot":"","sources":["../../src/docs-compliance/rules.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,eAAe;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC7B,MAAM,EAAE,eAAe,EAAE,CAAC;CAC7B;AA4BD,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,GAAG,gBAAgB,CA8E1E"}

package/lib/docs-compliance/rules.js

@@ -0,0 +1,74 @@
+function getLineNumber(content, index) {
+    return content.slice(0, index).split('\n').length;
+}
+function findMissingQueryErrors(content, commandPattern, code, message) {
+    const errors = [];
+    const regex = new RegExp(commandPattern.source, 'g');
+    let match;
+    while ((match = regex.exec(content)) !== null) {
+        const command = match[0];
+        if (!command.includes('-q ') && !command.includes('--query ')) {
+            errors.push({
+                code,
+                message,
+                line: getLineNumber(content, match.index),
+            });
+        }
+    }
+    return errors;
+}
+export function evaluateReadmeCompliance(content) {
+    const errors = [];
+    errors.push(...findMissingQueryErrors(content, /^\s*bkper\s+transaction\s+list\b.*$/gm, 'transaction-list-missing-query', 'Found `bkper transaction list` example without `-q/--query`.'));
+    errors.push(...findMissingQueryErrors(content, /^\s*bkper\s+balance\s+list\b.*$/gm, 'balance-list-missing-query', 'Found `bkper balance list` example without `-q/--query`.'));
+    const sameDayRangePattern = /after:\$DATE\s+before:\$DATE/g;
+    let sameDayMatch;
+    while ((sameDayMatch = sameDayRangePattern.exec(content)) !== null) {
+        errors.push({
+            code: 'same-day-range-antipattern',
+            message: 'Found `after:$DATE before:$DATE` anti-pattern. Prefer `on:$DATE`.',
+            line: getLineNumber(content, sameDayMatch.index),
+        });
+    }
+    const periodInQueryPattern = /-q\s+"[^"]*period:/g;
+    let periodMatch;
+    while ((periodMatch = periodInQueryPattern.exec(content)) !== null) {
+        errors.push({
+            code: 'period-operator-in-query-example',
+            message: 'Found `period:` in query example. Prefer documented query operators such as `on:`, `after:`, `before:`, and `by:`.',
+            line: getLineNumber(content, periodMatch.index),
+        });
+    }
+    if (!content.includes('LLM-first output guidance (important):')) {
+        errors.push({
+            code: 'missing-llm-guidance-title',
+            message: 'Missing `LLM-first output guidance (important):` section.',
+        });
+    }
+    if (!content.includes('**LLM consumption of lists/reports** → CSV')) {
+        errors.push({
+            code: 'missing-csv-guidance',
+            message: 'Missing guidance mapping LLM list/report consumption to CSV.',
+        });
+    }
+    if (!content.includes('**Programmatic processing / pipelines** → JSON')) {
+        errors.push({
+            code: 'missing-json-guidance',
+            message: 'Missing guidance mapping programmatic pipelines to JSON.',
+        });
+    }
+    if (!content.includes('### Query semantics (transactions and balances)')) {
+        errors.push({
+            code: 'missing-query-semantics-section',
+            message: 'Missing `Query semantics (transactions and balances)` section.',
+        });
+    }
+    if (!content.includes('`after:` is **inclusive** and `before:` is **exclusive**.')) {
+        errors.push({
+            code: 'missing-after-before-semantics',
+            message: 'Missing explicit semantics for `after:` and `before:`.',
+        });
+    }
+    return { errors };
+}
+//# sourceMappingURL=rules.js.map

package/lib/docs-compliance/rules.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "bkper",
-    "version": "4.9.1",
+    "version": "4.10.0",
     "description": "Command line client for Bkper",
     "bin": {
         "bkper": "./lib/cli.js"
@@ -32,7 +32,7 @@
         "build:compile": "tsc",
         "api:platform": "openapi-typescript https://platform.bkper.app/openapi.json -o src/platform/types.d.ts",
         "api:platform:local": "openapi-typescript http://localhost:8790/openapi.json -o src/platform/types.d.ts",
-        "build:copy-docs": "mkdir -p lib/docs && cp -f docs/*.md lib/docs/ 2>/dev/null || true",
+        "build:copy-docs": "mkdir -p lib/docs && cp -f docs/*.md lib/docs/ 2>/dev/null || true && cp -f README.md lib/docs/cli-reference.md",
         "predev": "bun run build",
         "dev": "tsc -w",
         "ports": "devpod ssh ../ -L 6274",
@@ -41,6 +41,8 @@
         "test:integration": "BKPER_API_URL=${BKPER_API_URL:-http://localhost:8081/_ah/api/bkper} TS_NODE_PROJECT=tsconfig.test.json mocha --config .mocharc.integration.json",
         "test:deploy": "BKPER_PLATFORM_URL=http://localhost:8790 BKPER_API_URL=https://api-dev.bkper.app TS_NODE_PROJECT=tsconfig.test.json mocha --config .mocharc.deploy.json",
         "test:all": "bun run test:unit && bun run test:integration",
+        "docs:compliance": "TS_NODE_PROJECT=tsconfig.test.json node --loader ts-node/esm ./test/tools/docs-compliance/check.ts",
+        "docs:compliance:live": "TS_NODE_PROJECT=tsconfig.test.json node --loader ts-node/esm ./test/tools/docs-compliance/live.ts",
         "upgrade:api": "bun update @bkper/bkper-api-types --latest && bun update bkper-js --latest",
         "patch": "yarn version --patch",
         "minor": "yarn version --minor",
@@ -50,7 +52,7 @@
     },
     "dependencies": {
         "@mariozechner/pi-coding-agent": "^0.60.0",
-        "bkper-js": "^2.29.4",
+        "bkper-js": "^2.31.1",
         "commander": "^13.1.0",
         "dotenv": "^8.2.0",
         "esbuild": "^0.27.2",