isthmus-cli 0.4.0 → 0.5.0

package/dist/cli/command-support.d.ts

@@ -0,0 +1,48 @@
+import type { BridgeFactsDocument } from '../exchange/parse.ts';
+/**
+ * 모든 분석 하위 명령이 공유하는 CLI 인프라다.
+ *
+ * 입력 문서 읽기·예산, 입력 실패의 분류와 메시지, 프로세스 경계 결과 형태를
+ * 한 곳에 모아 check-command의 편중을 떼어낸다. baseline 같은 명령 고유
+ * 오류는 각 명령이 자신의 실패 매퍼를 덧붙이는 방식으로 확장한다.
+ */
+/** 파일 경로를 받아 UTF-8 텍스트를 읽는 주입 경계다. */
+export type ReadTextFile = (path: string) => Promise<string>;
+/** 파일 경로에 UTF-8 텍스트를 쓰는 주입 경계다. */
+export type WriteTextFile = (path: string, text: string) => Promise<void>;
+/** 생성 시각을 테스트 가능하게 주입하는 시계다. */
+export type Clock = () => Date;
+/** CLI가 프로세스 경계에 쓸 출력과 종료 코드다. */
+export interface CommandResult {
+    readonly standardOutput: string;
+    readonly standardError: string;
+    readonly exitCode: 0 | 1 | 2 | 64;
+}
+/** 한 입력 파일에서 허용하는 최대 UTF-16 문자열 길이다. */
+export declare const MAX_INPUT_TEXT_LENGTH: number;
+/** 한 명령에서 허용하는 전체 UTF-16 입력 문자열 길이다. */
+export declare const MAX_TOTAL_INPUT_TEXT_LENGTH: number;
+/** 입력을 순서대로 읽어 파일 수·메모리 상한 안에서 교환 문서로 파싱한다. */
+export declare function readBridgeDocuments(inputPaths: readonly string[], readTextFile: ReadTextFile): Promise<BridgeFactsDocument[]>;
+/**
+ * 사용자 입력 JSON 파싱 실패인지 확인한다.
+ *
+ * 깊은 중첩은 SyntaxError가 아니라 RangeError(스택 초과)로 실패한다.
+ * 둘 다 입력 탓이라 내부 오류 메시지로 오분류하지 않는다.
+ */
+export declare function isJsonParseFailure(error: unknown): boolean;
+/** 알려진 입력·조인 실패를 원인별 해결 방향을 담은 코드 2 결과로 바꾼다.
+
+명령 고유의 입력(baseline 등)은 각 명령이 자신의 매퍼를 이 뒤에 붙인다. */
+export declare function inputFailureResult(error: unknown): CommandResult | undefined;
+/** 원인 메시지만 stdout 없이 코드 2로 내보낸다. */
+export declare function inputFailure(standardError: string): CommandResult;
+/**
+ * 전체 조인 보류를 깨끗한 결과와 구분하는 코드 2 결과로 바꾼다.
+ *
+ * 관찰량을 숫자 보간으로 함께 알린다. 보류된 조인은 문서를 출력하지 않으므로,
+ * 이 숫자가 "몇 개를 봤는데 못 조인했는지"가 도달하는 유일한 경로다.
+ */
+export declare function bridgeJoinDeferredError(observedFacts: number, documentCount: number): CommandResult;
+/** 내부 결함을 입력 탓으로 돌리지 않는 경로 없는 코드 2 결과다. */
+export declare function internalError(): CommandResult;

package/dist/cli/command-support.js

@@ -0,0 +1,144 @@
+import { BridgeFactsValidationError, parseBridgeFactsDocument, } from "../exchange/parse.js";
+import { BridgeJoinValidationError } from "../join/join.js";
+/** 한 입력 파일에서 허용하는 최대 UTF-16 문자열 길이다. */
+export const MAX_INPUT_TEXT_LENGTH = 16 * 1024 * 1024;
+/** 한 명령에서 허용하는 전체 UTF-16 입력 문자열 길이다. */
+export const MAX_TOTAL_INPUT_TEXT_LENGTH = 64 * 1024 * 1024;
+/** 입력을 순서대로 읽어 파일 수·메모리 상한 안에서 교환 문서로 파싱한다. */
+export async function readBridgeDocuments(inputPaths, readTextFile) {
+    const documents = [];
+    let totalTextLength = 0;
+    for (const [index, path] of inputPaths.entries()) {
+        const inputPosition = index + 1;
+        let text;
+        try {
+            text = await readTextFile(path);
+        }
+        catch {
+            throw new BridgeInputReadError(inputPosition);
+        }
+        totalTextLength += text.length;
+        if (text.length > MAX_INPUT_TEXT_LENGTH ||
+            totalTextLength > MAX_TOTAL_INPUT_TEXT_LENGTH) {
+            throw new BridgeInputLimitError(inputPosition);
+        }
+        // JSON 구문 오류와 문서 검증 실패를 같은 try로 감싸면 검증기의 예외가
+        // 구문 오류로 오분류된다. 파싱과 검증을 나눠 분류 경계를 지킨다.
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch (error) {
+            if (isJsonParseFailure(error)) {
+                throw new BridgeInputJsonError(inputPosition);
+            }
+            throw error;
+        }
+        try {
+            documents.push(parseBridgeFactsDocument(parsed));
+        }
+        catch (error) {
+            if (error instanceof BridgeFactsValidationError) {
+                throw new BridgeInputContractError(inputPosition, error.message);
+            }
+            throw error;
+        }
+    }
+    return documents;
+}
+/**
+ * 사용자 입력 JSON 파싱 실패인지 확인한다.
+ *
+ * 깊은 중첩은 SyntaxError가 아니라 RangeError(스택 초과)로 실패한다.
+ * 둘 다 입력 탓이라 내부 오류 메시지로 오분류하지 않는다.
+ */
+export function isJsonParseFailure(error) {
+    return error instanceof SyntaxError || error instanceof RangeError;
+}
+/** 실패한 입력의 1부터 시작하는 순서를 보존하는 입력 오류다. */
+class BridgeInputError extends Error {
+    inputPosition;
+    constructor(name, inputPosition) {
+        super(`${name} at input ${inputPosition}`);
+        this.name = name;
+        this.inputPosition = inputPosition;
+    }
+}
+/** 입력 파일을 읽지 못한 경우를 구분한다. */
+class BridgeInputReadError extends BridgeInputError {
+    constructor(inputPosition) {
+        super('BridgeInputReadError', inputPosition);
+    }
+}
+/** 입력 텍스트가 JSON이 아닌 경우를 구분한다. */
+class BridgeInputJsonError extends BridgeInputError {
+    constructor(inputPosition) {
+        super('BridgeInputJsonError', inputPosition);
+    }
+}
+/** 입력 문서가 교환 계약을 어긴 경우와 그 이유를 구분한다. */
+class BridgeInputContractError extends BridgeInputError {
+    reason;
+    constructor(inputPosition, reason) {
+        super('BridgeInputContractError', inputPosition);
+        this.reason = reason;
+    }
+}
+/** 입력 텍스트의 크기만 계약을 넘은 경우를 구분한다. */
+class BridgeInputLimitError extends BridgeInputError {
+    constructor(inputPosition) {
+        super('BridgeInputLimitError', inputPosition);
+    }
+}
+/** 알려진 입력·조인 실패를 원인별 해결 방향을 담은 코드 2 결과로 바꾼다.
+
+명령 고유의 입력(baseline 등)은 각 명령이 자신의 매퍼를 이 뒤에 붙인다. */
+export function inputFailureResult(error) {
+    if (error instanceof BridgeInputReadError) {
+        return inputFailure(`Unable to read bridge facts input ${error.inputPosition}; `
+            + 'check that the file exists and is readable.\n');
+    }
+    if (error instanceof BridgeInputJsonError) {
+        return inputFailure(`Bridge facts input ${error.inputPosition} is not valid JSON; `
+            + 'regenerate it with a bridge-facts producer.\n');
+    }
+    if (error instanceof BridgeInputContractError) {
+        return inputFailure(`Bridge facts input ${error.inputPosition} violates the bridge-facts `
+            + `contract: ${error.reason}\n`);
+    }
+    if (error instanceof BridgeInputLimitError) {
+        return inputFailure(`Bridge facts input ${error.inputPosition} exceeds the input size limits; `
+            + 'split the extraction into smaller documents.\n');
+    }
+    if (error instanceof BridgeJoinValidationError) {
+        return inputFailure(`${error.message}\n`);
+    }
+    return undefined;
+}
+/** 원인 메시지만 stdout 없이 코드 2로 내보낸다. */
+export function inputFailure(standardError) {
+    return { standardOutput: '', standardError, exitCode: 2 };
+}
+/**
+ * 전체 조인 보류를 깨끗한 결과와 구분하는 코드 2 결과로 바꾼다.
+ *
+ * 관찰량을 숫자 보간으로 함께 알린다. 보류된 조인은 문서를 출력하지 않으므로,
+ * 이 숫자가 "몇 개를 봤는데 못 조인했는지"가 도달하는 유일한 경로다.
+ */
+export function bridgeJoinDeferredError(observedFacts, documentCount) {
+    return {
+        standardOutput: '',
+        standardError: 'Bridge facts could not be joined; split mixed bridge targets and retry. '
+            + `The inputs observed ${observedFacts} facts across ${documentCount} documents.\n`,
+        exitCode: 2,
+    };
+}
+/** 내부 결함을 입력 탓으로 돌리지 않는 경로 없는 코드 2 결과다. */
+export function internalError() {
+    return {
+        standardOutput: '',
+        standardError: 'Internal isthmus error; retry with a current version.\n',
+        exitCode: 2,
+    };
+}
+//# sourceMappingURL=command-support.js.map

package/dist/cli/command-support.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-support.js","sourceRoot":"","sources":["../../src/cli/command-support.ts"],"names":[],"mappings":"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","sourcesContent":["import type { BridgeFactsDocument } from '../exchange/parse.ts';\nimport {\n  BridgeFactsValidationError,\n  parseBridgeFactsDocument,\n} from '../exchange/parse.ts';\nimport { BridgeJoinValidationError } from '../join/join.ts';\n\n/**\n * 모든 분석 하위 명령이 공유하는 CLI 인프라다.\n *\n * 입력 문서 읽기·예산, 입력 실패의 분류와 메시지, 프로세스 경계 결과 형태를\n * 한 곳에 모아 check-command의 편중을 떼어낸다. baseline 같은 명령 고유\n * 오류는 각 명령이 자신의 실패 매퍼를 덧붙이는 방식으로 확장한다.\n */\n\n/** 파일 경로를 받아 UTF-8 텍스트를 읽는 주입 경계다. */\nexport type ReadTextFile = (path: string) => Promise<string>;\n\n/** 파일 경로에 UTF-8 텍스트를 쓰는 주입 경계다. */\nexport type WriteTextFile = (path: string, text: string) => Promise<void>;\n\n/** 생성 시각을 테스트 가능하게 주입하는 시계다. */\nexport type Clock = () => Date;\n\n/** CLI가 프로세스 경계에 쓸 출력과 종료 코드다. */\nexport interface CommandResult {\n  readonly standardOutput: string;\n  readonly standardError: string;\n  readonly exitCode: 0 | 1 | 2 | 64;\n}\n\n/** 한 입력 파일에서 허용하는 최대 UTF-16 문자열 길이다. */\nexport const MAX_INPUT_TEXT_LENGTH = 16 * 1024 * 1024;\n\n/** 한 명령에서 허용하는 전체 UTF-16 입력 문자열 길이다. */\nexport const MAX_TOTAL_INPUT_TEXT_LENGTH = 64 * 1024 * 1024;\n\n/** 입력을 순서대로 읽어 파일 수·메모리 상한 안에서 교환 문서로 파싱한다. */\nexport async function readBridgeDocuments(\n  inputPaths: readonly string[],\n  readTextFile: ReadTextFile,\n): Promise<BridgeFactsDocument[]> {\n  const documents: BridgeFactsDocument[] = [];\n  let totalTextLength = 0;\n  for (const [index, path] of inputPaths.entries()) {\n    const inputPosition = index + 1;\n    let text: string;\n    try {\n      text = await readTextFile(path);\n    } catch {\n      throw new BridgeInputReadError(inputPosition);\n    }\n    totalTextLength += text.length;\n    if (\n      text.length > MAX_INPUT_TEXT_LENGTH ||\n      totalTextLength > MAX_TOTAL_INPUT_TEXT_LENGTH\n    ) {\n      throw new BridgeInputLimitError(inputPosition);\n    }\n    // JSON 구문 오류와 문서 검증 실패를 같은 try로 감싸면 검증기의 예외가\n    // 구문 오류로 오분류된다. 파싱과 검증을 나눠 분류 경계를 지킨다.\n    let parsed: unknown;\n    try {\n      parsed = JSON.parse(text);\n    } catch (error) {\n      if (isJsonParseFailure(error)) {\n        throw new BridgeInputJsonError(inputPosition);\n      }\n      throw error;\n    }\n    try {\n      documents.push(parseBridgeFactsDocument(parsed));\n    } catch (error) {\n      if (error instanceof BridgeFactsValidationError) {\n        throw new BridgeInputContractError(inputPosition, error.message);\n      }\n      throw error;\n    }\n  }\n  return documents;\n}\n\n/**\n * 사용자 입력 JSON 파싱 실패인지 확인한다.\n *\n * 깊은 중첩은 SyntaxError가 아니라 RangeError(스택 초과)로 실패한다.\n * 둘 다 입력 탓이라 내부 오류 메시지로 오분류하지 않는다.\n */\nexport function isJsonParseFailure(error: unknown): boolean {\n  return error instanceof SyntaxError || error instanceof RangeError;\n}\n\n/** 실패한 입력의 1부터 시작하는 순서를 보존하는 입력 오류다. */\nclass BridgeInputError extends Error {\n  readonly inputPosition: number;\n\n  constructor(name: string, inputPosition: number) {\n    super(`${name} at input ${inputPosition}`);\n    this.name = name;\n    this.inputPosition = inputPosition;\n  }\n}\n\n/** 입력 파일을 읽지 못한 경우를 구분한다. */\nclass BridgeInputReadError extends BridgeInputError {\n  constructor(inputPosition: number) {\n    super('BridgeInputReadError', inputPosition);\n  }\n}\n\n/** 입력 텍스트가 JSON이 아닌 경우를 구분한다. */\nclass BridgeInputJsonError extends BridgeInputError {\n  constructor(inputPosition: number) {\n    super('BridgeInputJsonError', inputPosition);\n  }\n}\n\n/** 입력 문서가 교환 계약을 어긴 경우와 그 이유를 구분한다. */\nclass BridgeInputContractError extends BridgeInputError {\n  readonly reason: string;\n\n  constructor(inputPosition: number, reason: string) {\n    super('BridgeInputContractError', inputPosition);\n    this.reason = reason;\n  }\n}\n\n/** 입력 텍스트의 크기만 계약을 넘은 경우를 구분한다. */\nclass BridgeInputLimitError extends BridgeInputError {\n  constructor(inputPosition: number) {\n    super('BridgeInputLimitError', inputPosition);\n  }\n}\n\n/** 알려진 입력·조인 실패를 원인별 해결 방향을 담은 코드 2 결과로 바꾼다.\n\n명령 고유의 입력(baseline 등)은 각 명령이 자신의 매퍼를 이 뒤에 붙인다. */\nexport function inputFailureResult(error: unknown): CommandResult | undefined {\n  if (error instanceof BridgeInputReadError) {\n    return inputFailure(\n      `Unable to read bridge facts input ${error.inputPosition}; `\n      + 'check that the file exists and is readable.\\n',\n    );\n  }\n  if (error instanceof BridgeInputJsonError) {\n    return inputFailure(\n      `Bridge facts input ${error.inputPosition} is not valid JSON; `\n      + 'regenerate it with a bridge-facts producer.\\n',\n    );\n  }\n  if (error instanceof BridgeInputContractError) {\n    return inputFailure(\n      `Bridge facts input ${error.inputPosition} violates the bridge-facts `\n      + `contract: ${error.reason}\\n`,\n    );\n  }\n  if (error instanceof BridgeInputLimitError) {\n    return inputFailure(\n      `Bridge facts input ${error.inputPosition} exceeds the input size limits; `\n      + 'split the extraction into smaller documents.\\n',\n    );\n  }\n  if (error instanceof BridgeJoinValidationError) {\n    return inputFailure(`${error.message}\\n`);\n  }\n  return undefined;\n}\n\n/** 원인 메시지만 stdout 없이 코드 2로 내보낸다. */\nexport function inputFailure(standardError: string): CommandResult {\n  return { standardOutput: '', standardError, exitCode: 2 };\n}\n\n/**\n * 전체 조인 보류를 깨끗한 결과와 구분하는 코드 2 결과로 바꾼다.\n *\n * 관찰량을 숫자 보간으로 함께 알린다. 보류된 조인은 문서를 출력하지 않으므로,\n * 이 숫자가 \"몇 개를 봤는데 못 조인했는지\"가 도달하는 유일한 경로다.\n */\nexport function bridgeJoinDeferredError(\n  observedFacts: number,\n  documentCount: number,\n): CommandResult {\n  return {\n    standardOutput: '',\n    standardError:\n      'Bridge facts could not be joined; split mixed bridge targets and retry. '\n      + `The inputs observed ${observedFacts} facts across ${documentCount} documents.\\n`,\n    exitCode: 2,\n  };\n}\n\n/** 내부 결함을 입력 탓으로 돌리지 않는 경로 없는 코드 2 결과다. */\nexport function internalError(): CommandResult {\n  return {\n    standardOutput: '',\n    standardError: 'Internal isthmus error; retry with a current version.\\n',\n    exitCode: 2,\n  };\n}\n"]}

package/dist/cli/diff-command.d.ts

@@ -1,4 +1,4 @@
-import { type CommandResult, type ReadTextFile } from './check-command.ts';
+import { type CommandResult, type ReadTextFile } from './command-support.ts';
 /** 전후 교환 파일을 하나의 입력 예산으로 읽어 새 경계 오류만 CI 실패로 표시한다. */
 export declare function runDiffCommand(arguments_: readonly string[], readTextFile: ReadTextFile): Promise<CommandResult>;
 /** 각 snapshot은 caller와 receiver 문서를 함께 제공해야 한다. */

package/dist/cli/diff-command.js

@@ -1,7 +1,7 @@
 import { MAX_DOCUMENTS_PER_JOIN } from "../join/join.js";
 import { createBridgeDiff } from "../report/diff.js";
 import { encodeSortedJson } from "../report/sorted-json.js";
-import { internalError, inputFailureResult, readBridgeDocuments, } from "./check-command.js";
+import { inputFailureResult, internalError, readBridgeDocuments, } from "./command-support.js";
 /** 전후 교환 파일을 하나의 입력 예산으로 읽어 새 경계 오류만 CI 실패로 표시한다. */
 export async function runDiffCommand(arguments_, readTextFile) {
     const strictFlags = arguments_.filter((argument) => argument === '--strict');

package/dist/cli/diff-command.js.map

@@ -1 +1 @@
-{"version":3,"file":"diff-command.js","sourceRoot":"","sources":["../../src/cli/diff-command.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AACzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EACL,aAAa,EACb,kBAAkB,EAClB,mBAAmB,GAGpB,MAAM,oBAAoB,CAAC;AAE5B,qDAAqD;AACrD,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,UAA6B,EAC7B,YAA0B;IAE1B,MAAM,WAAW,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,KAAK,UAAU,CAAC,CAAC;IAC7E,MAAM,IAAI,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,KAAK,UAAU,CAAC,CAAC;IACtE,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAC1C,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;IAC7C,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC;IAC7C,MAAM,KAAK,GAAG,CAAC,GAAG,WAAW,EAAE,GAAG,UAAU,CAAC,CAAC;IAC9C,IACE,IAAI,CAAC,CAAC,CAAC,KAAK,MAAM;QAClB,IAAI,CAAC,CAAC,CAAC,KAAK,UAAU;QACtB,WAAW,CAAC,MAAM,GAAG,CAAC;QACtB,SAAS,GAAG,CAAC;QACb,WAAW,CAAC,MAAM,GAAG,CAAC;QACtB,UAAU,CAAC,MAAM,GAAG,CAAC;QACrB,KAAK,CAAC,MAAM,GAAG,sBAAsB;QACrC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,EACtE,CAAC;QACD,OAAO,EAAE,cAAc,EAAE,EAAE,EAAE,aAAa,EAAE,GAAG,SAAS,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;IAC/E,CAAC;IACD,IAAI,CAAC;QACH,MAAM,SAAS,GAAG,MAAM,mBAAmB,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC;QACjE,MAAM,MAAM,GAAG,gBAAgB,CAC7B,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,EACtC,SAAS,CAAC,KAAK,CAAC,WAAW,CAAC,MAAM,CAAC,CACpC,CAAC;QACF,OAAO;YACL,cAAc,EAAE,gBAAgB,CAAC,MAAM,CAAC;YACxC,aAAa,EAAE,EAAE;YACjB,QAAQ,EAAE,WAAW,CAAC,MAAM,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,gBAAgB,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;SAClF,CAAC;IACJ,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,kBAAkB,CAAC,KAAK,CAAC,IAAI,aAAa,EAAE,CAAC;IACtD,CAAC;AACH,CAAC;AAED,mDAAmD;AACnD,MAAM,CAAC,MAAM,SAAS,GACpB,kEAAkE;MAChE,uDAAuD,CAAC","sourcesContent":["import { MAX_DOCUMENTS_PER_JOIN } from '../join/join.ts';\nimport { createBridgeDiff } from '../report/diff.ts';\nimport { encodeSortedJson } from '../report/sorted-json.ts';\nimport {\n  internalError,\n  inputFailureResult,\n  readBridgeDocuments,\n  type CommandResult,\n  type ReadTextFile,\n} from './check-command.ts';\n\n/** 전후 교환 파일을 하나의 입력 예산으로 읽어 새 경계 오류만 CI 실패로 표시한다. */\nexport async function runDiffCommand(\n  arguments_: readonly string[],\n  readTextFile: ReadTextFile,\n): Promise<CommandResult> {\n  const strictFlags = arguments_.filter((argument) => argument === '--strict');\n  const args = arguments_.filter((argument) => argument !== '--strict');\n  const separator = args.indexOf('--after');\n  const beforePaths = args.slice(2, separator);\n  const afterPaths = args.slice(separator + 1);\n  const paths = [...beforePaths, ...afterPaths];\n  if (\n    args[0] !== 'diff' ||\n    args[1] !== '--before' ||\n    strictFlags.length > 1 ||\n    separator < 4 ||\n    beforePaths.length < 2 ||\n    afterPaths.length < 2 ||\n    paths.length > MAX_DOCUMENTS_PER_JOIN ||\n    paths.some((path) => path.trim().length === 0 || path.startsWith('-'))\n  ) {\n    return { standardOutput: '', standardError: `${diffUsage}\\n`, exitCode: 64 };\n  }\n  try {\n    const documents = await readBridgeDocuments(paths, readTextFile);\n    const report = createBridgeDiff(\n      documents.slice(0, beforePaths.length),\n      documents.slice(beforePaths.length),\n    );\n    return {\n      standardOutput: encodeSortedJson(report),\n      standardError: '',\n      exitCode: strictFlags.length === 1 && report.summary.introducedErrors > 0 ? 1 : 0,\n    };\n  } catch (error) {\n    return inputFailureResult(error) ?? internalError();\n  }\n}\n\n/** 각 snapshot은 caller와 receiver 문서를 함께 제공해야 한다. */\nexport const diffUsage =\n  'Usage: isthmus diff --before <dart.json> <swift.json> [more...] '\n  + '--after <dart.json> <swift.json> [more...] [--strict]';\n"]}
+{"version":3,"file":"diff-command.js","sourceRoot":"","sources":["../../src/cli/diff-command.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AACzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EACL,kBAAkB,EAClB,aAAa,EACb,mBAAmB,GAGpB,MAAM,sBAAsB,CAAC;AAE9B,qDAAqD;AACrD,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,UAA6B,EAC7B,YAA0B;IAE1B,MAAM,WAAW,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,KAAK,UAAU,CAAC,CAAC;IAC7E,MAAM,IAAI,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,KAAK,UAAU,CAAC,CAAC;IACtE,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAC1C,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;IAC7C,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC;IAC7C,MAAM,KAAK,GAAG,CAAC,GAAG,WAAW,EAAE,GAAG,UAAU,CAAC,CAAC;IAC9C,IACE,IAAI,CAAC,CAAC,CAAC,KAAK,MAAM;QAClB,IAAI,CAAC,CAAC,CAAC,KAAK,UAAU;QACtB,WAAW,CAAC,MAAM,GAAG,CAAC;QACtB,SAAS,GAAG,CAAC;QACb,WAAW,CAAC,MAAM,GAAG,CAAC;QACtB,UAAU,CAAC,MAAM,GAAG,CAAC;QACrB,KAAK,CAAC,MAAM,GAAG,sBAAsB;QACrC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,EACtE,CAAC;QACD,OAAO,EAAE,cAAc,EAAE,EAAE,EAAE,aAAa,EAAE,GAAG,SAAS,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;IAC/E,CAAC;IACD,IAAI,CAAC;QACH,MAAM,SAAS,GAAG,MAAM,mBAAmB,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC;QACjE,MAAM,MAAM,GAAG,gBAAgB,CAC7B,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,EACtC,SAAS,CAAC,KAAK,CAAC,WAAW,CAAC,MAAM,CAAC,CACpC,CAAC;QACF,OAAO;YACL,cAAc,EAAE,gBAAgB,CAAC,MAAM,CAAC;YACxC,aAAa,EAAE,EAAE;YACjB,QAAQ,EAAE,WAAW,CAAC,MAAM,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,gBAAgB,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;SAClF,CAAC;IACJ,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,kBAAkB,CAAC,KAAK,CAAC,IAAI,aAAa,EAAE,CAAC;IACtD,CAAC;AACH,CAAC;AAED,mDAAmD;AACnD,MAAM,CAAC,MAAM,SAAS,GACpB,kEAAkE;MAChE,uDAAuD,CAAC","sourcesContent":["import { MAX_DOCUMENTS_PER_JOIN } from '../join/join.ts';\nimport { createBridgeDiff } from '../report/diff.ts';\nimport { encodeSortedJson } from '../report/sorted-json.ts';\nimport {\n  inputFailureResult,\n  internalError,\n  readBridgeDocuments,\n  type CommandResult,\n  type ReadTextFile,\n} from './command-support.ts';\n\n/** 전후 교환 파일을 하나의 입력 예산으로 읽어 새 경계 오류만 CI 실패로 표시한다. */\nexport async function runDiffCommand(\n  arguments_: readonly string[],\n  readTextFile: ReadTextFile,\n): Promise<CommandResult> {\n  const strictFlags = arguments_.filter((argument) => argument === '--strict');\n  const args = arguments_.filter((argument) => argument !== '--strict');\n  const separator = args.indexOf('--after');\n  const beforePaths = args.slice(2, separator);\n  const afterPaths = args.slice(separator + 1);\n  const paths = [...beforePaths, ...afterPaths];\n  if (\n    args[0] !== 'diff' ||\n    args[1] !== '--before' ||\n    strictFlags.length > 1 ||\n    separator < 4 ||\n    beforePaths.length < 2 ||\n    afterPaths.length < 2 ||\n    paths.length > MAX_DOCUMENTS_PER_JOIN ||\n    paths.some((path) => path.trim().length === 0 || path.startsWith('-'))\n  ) {\n    return { standardOutput: '', standardError: `${diffUsage}\\n`, exitCode: 64 };\n  }\n  try {\n    const documents = await readBridgeDocuments(paths, readTextFile);\n    const report = createBridgeDiff(\n      documents.slice(0, beforePaths.length),\n      documents.slice(beforePaths.length),\n    );\n    return {\n      standardOutput: encodeSortedJson(report),\n      standardError: '',\n      exitCode: strictFlags.length === 1 && report.summary.introducedErrors > 0 ? 1 : 0,\n    };\n  } catch (error) {\n    return inputFailureResult(error) ?? internalError();\n  }\n}\n\n/** 각 snapshot은 caller와 receiver 문서를 함께 제공해야 한다. */\nexport const diffUsage =\n  'Usage: isthmus diff --before <dart.json> <swift.json> [more...] '\n  + '--after <dart.json> <swift.json> [more...] [--strict]';\n"]}

package/dist/cli/graph-command.d.ts

@@ -1,4 +1,4 @@
-import { type CommandResult, type ReadTextFile } from './check-command.ts';
+import { type CommandResult, type ReadTextFile } from './command-support.ts';
 /** graph 인자를 실행해 경계 그래프와 종료 코드를 반환한다. */
 export declare function runGraphCommand(arguments_: readonly string[], readTextFile: ReadTextFile): Promise<CommandResult>;
 /** graph 명령의 한 줄 사용법이다. */

package/dist/cli/graph-command.js

@@ -1,6 +1,7 @@
 import { isBridgeJoinDeferred, joinBridgeDocuments, MAX_DOCUMENTS_PER_JOIN, } from "../join/join.js";
 import { BridgeGraphLimitError, BridgeGraphValidationError, createBridgeGraph, renderBridgeGraph, } from "../report/graph.js";
-import { bridgeJoinDeferredError, internalError, inputFailureResult, readBridgeDocuments, } from "./check-command.js";
+import { bridgeJoinDeferredError, inputFailureResult, internalError, readBridgeDocuments, } from "./command-support.js";
+import { parseCommandArguments } from "./parse-arguments.js";
 /** graph 인자를 실행해 경계 그래프와 종료 코드를 반환한다. */
 export async function runGraphCommand(arguments_, readTextFile) {
     const options = parseGraphArguments(arguments_);
@@ -9,8 +10,9 @@ export async function runGraphCommand(arguments_, readTextFile) {
     try {
         const documents = await readBridgeDocuments(options.inputPaths, readTextFile);
         const joined = joinBridgeDocuments(documents);
-        if (isBridgeJoinDeferred(joined))
-            return bridgeJoinDeferredError();
+        if (isBridgeJoinDeferred(joined)) {
+            return bridgeJoinDeferredError(joined.observedFacts, documents.length);
+        }
         const graph = createBridgeGraph(joined);
         return {
             standardOutput: renderBridgeGraph(graph, options.format),
@@ -30,23 +32,22 @@ export async function runGraphCommand(arguments_, readTextFile) {
         return inputFailureResult(error) ?? internalError();
     }
 }
-/** graph의 입력 파일과 선택 출력 형식을 검증한다. */
+/** graph의 입력 파일과 선택 출력 형식을 검증한다. 플래그는 어디에 와도 된다. */
 function parseGraphArguments(arguments_) {
     if (arguments_[0] !== 'graph')
         return undefined;
-    const formatIndex = arguments_.indexOf('--format');
-    const inputPaths = arguments_.slice(1, formatIndex < 0 ? undefined : formatIndex);
+    const parsed = parseCommandArguments(arguments_.slice(1), ['--format'], []);
+    if (parsed === undefined)
+        return undefined;
+    const format = parsed.valueFlags.get('--format');
+    if (format !== undefined && !isGraphFormat(format))
+        return undefined;
+    const inputPaths = [...parsed.positionals];
     if (inputPaths.length < 2 ||
-        inputPaths.length > MAX_DOCUMENTS_PER_JOIN ||
-        inputPaths.some((path) => path.startsWith('-'))) {
+        inputPaths.length > MAX_DOCUMENTS_PER_JOIN) {
         return undefined;
     }
-    if (formatIndex < 0)
-        return { inputPaths, format: 'json' };
-    if (formatIndex !== arguments_.length - 2)
-        return undefined;
-    const format = arguments_[formatIndex + 1];
-    return isGraphFormat(format) ? { inputPaths, format } : undefined;
+    return { inputPaths, format: format ?? 'json' };
 }
 /** 지원하는 그래프 형식인지 확인한다. */
 function isGraphFormat(value) {

package/dist/cli/graph-command.js.map

@@ -1 +1 @@
-{"version":3,"file":"graph-command.js","sourceRoot":"","sources":["../../src/cli/graph-command.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  isBridgeJoinDeferred,\n  joinBridgeDocuments,\n  MAX_DOCUMENTS_PER_JOIN,\n} from '../join/join.ts';\nimport {\n  BridgeGraphLimitError,\n  BridgeGraphValidationError,\n  createBridgeGraph,\n  renderBridgeGraph,\n} from '../report/graph.ts';\nimport {\n  bridgeJoinDeferredError,\n  internalError,\n  inputFailureResult,\n  readBridgeDocuments,\n  type CommandResult,\n  type ReadTextFile,\n} from './check-command.ts';\n\n/** graph 인자를 실행해 경계 그래프와 종료 코드를 반환한다. */\nexport async function runGraphCommand(\n  arguments_: readonly string[],\n  readTextFile: ReadTextFile,\n): Promise<CommandResult> {\n  const options = parseGraphArguments(arguments_);\n  if (options === undefined) return graphUsageError();\n  try {\n    const documents = await readBridgeDocuments(options.inputPaths, readTextFile);\n    const joined = joinBridgeDocuments(documents);\n    if (isBridgeJoinDeferred(joined)) return bridgeJoinDeferredError();\n    const graph = createBridgeGraph(joined);\n    return {\n      standardOutput: renderBridgeGraph(graph, options.format),\n      standardError: '',\n      exitCode: 0,\n    };\n  } catch (error) {\n    if (\n      error instanceof BridgeGraphLimitError ||\n      error instanceof BridgeGraphValidationError\n    ) {\n      return {\n        standardOutput: '',\n        standardError: `${error.message}\\n`,\n        exitCode: 2,\n      };\n    }\n    return inputFailureResult(error) ?? internalError();\n  }\n}\n\n/** graph의 입력 파일과 선택 출력 형식을 검증한다. */\nfunction parseGraphArguments(arguments_: readonly string[]): GraphOptions | undefined {\n  if (arguments_[0] !== 'graph') return undefined;\n  const formatIndex = arguments_.indexOf('--format');\n  const inputPaths = arguments_.slice(1, formatIndex < 0 ? undefined : formatIndex);\n  if (\n    inputPaths.length < 2 ||\n    inputPaths.length > MAX_DOCUMENTS_PER_JOIN ||\n    inputPaths.some((path) => path.startsWith('-'))\n  ) {\n    return undefined;\n  }\n  if (formatIndex < 0) return { inputPaths, format: 'json' };\n  if (formatIndex !== arguments_.length - 2) return undefined;\n  const format = arguments_[formatIndex + 1];\n  return isGraphFormat(format) ? { inputPaths, format } : undefined;\n}\n\n/** 지원하는 그래프 형식인지 확인한다. */\nfunction isGraphFormat(value: string | undefined): value is GraphFormat {\n  return value === 'json' || value === 'dot' || value === 'mermaid';\n}\n\n/** graph 사용 오류를 경로 없는 코드 64로 바꾼다. */\nfunction graphUsageError(): CommandResult {\n  return {\n    standardOutput: '',\n    standardError: `${graphUsage}\\n`,\n    exitCode: 64,\n  };\n}\n\n/** 검증된 graph 명령 옵션이다. */\ninterface GraphOptions {\n  readonly inputPaths: readonly string[];\n  readonly format: GraphFormat;\n}\n\ntype GraphFormat = 'json' | 'dot' | 'mermaid';\n\n/** graph 명령의 한 줄 사용법이다. */\nexport const graphUsage =\n  'Usage: isthmus graph <bridge-facts.json> <bridge-facts.json> '\n  + '[more...] [--format json|dot|mermaid]';\n"]}
+{"version":3,"file":"graph-command.js","sourceRoot":"","sources":["../../src/cli/graph-command.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  isBridgeJoinDeferred,\n  joinBridgeDocuments,\n  MAX_DOCUMENTS_PER_JOIN,\n} from '../join/join.ts';\nimport {\n  BridgeGraphLimitError,\n  BridgeGraphValidationError,\n  createBridgeGraph,\n  renderBridgeGraph,\n} from '../report/graph.ts';\nimport {\n  bridgeJoinDeferredError,\n  inputFailureResult,\n  internalError,\n  readBridgeDocuments,\n  type CommandResult,\n  type ReadTextFile,\n} from './command-support.ts';\nimport { parseCommandArguments } from './parse-arguments.ts';\n\n/** graph 인자를 실행해 경계 그래프와 종료 코드를 반환한다. */\nexport async function runGraphCommand(\n  arguments_: readonly string[],\n  readTextFile: ReadTextFile,\n): Promise<CommandResult> {\n  const options = parseGraphArguments(arguments_);\n  if (options === undefined) return graphUsageError();\n  try {\n    const documents = await readBridgeDocuments(options.inputPaths, readTextFile);\n    const joined = joinBridgeDocuments(documents);\n    if (isBridgeJoinDeferred(joined)) {\n      return bridgeJoinDeferredError(joined.observedFacts, documents.length);\n    }\n    const graph = createBridgeGraph(joined);\n    return {\n      standardOutput: renderBridgeGraph(graph, options.format),\n      standardError: '',\n      exitCode: 0,\n    };\n  } catch (error) {\n    if (\n      error instanceof BridgeGraphLimitError ||\n      error instanceof BridgeGraphValidationError\n    ) {\n      return {\n        standardOutput: '',\n        standardError: `${error.message}\\n`,\n        exitCode: 2,\n      };\n    }\n    return inputFailureResult(error) ?? internalError();\n  }\n}\n\n/** graph의 입력 파일과 선택 출력 형식을 검증한다. 플래그는 어디에 와도 된다. */\nfunction parseGraphArguments(arguments_: readonly string[]): GraphOptions | undefined {\n  if (arguments_[0] !== 'graph') return undefined;\n  const parsed = parseCommandArguments(arguments_.slice(1), ['--format'], []);\n  if (parsed === undefined) return undefined;\n  const format = parsed.valueFlags.get('--format');\n  if (format !== undefined && !isGraphFormat(format)) return undefined;\n  const inputPaths = [...parsed.positionals];\n  if (\n    inputPaths.length < 2 ||\n    inputPaths.length > MAX_DOCUMENTS_PER_JOIN\n  ) {\n    return undefined;\n  }\n  return { inputPaths, format: format ?? 'json' };\n}\n\n/** 지원하는 그래프 형식인지 확인한다. */\nfunction isGraphFormat(value: string): value is GraphFormat {\n  return value === 'json' || value === 'dot' || value === 'mermaid';\n}\n\n/** graph 사용 오류를 경로 없는 코드 64로 바꾼다. */\nfunction graphUsageError(): CommandResult {\n  return {\n    standardOutput: '',\n    standardError: `${graphUsage}\\n`,\n    exitCode: 64,\n  };\n}\n\n/** 검증된 graph 명령 옵션이다. */\ninterface GraphOptions {\n  readonly inputPaths: readonly string[];\n  readonly format: GraphFormat;\n}\n\ntype GraphFormat = 'json' | 'dot' | 'mermaid';\n\n/** graph 명령의 한 줄 사용법이다. */\nexport const graphUsage =\n  'Usage: isthmus graph <bridge-facts.json> <bridge-facts.json> '\n  + '[more...] [--format json|dot|mermaid]';\n"]}

package/dist/cli/main.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { readFile } from 'node:fs/promises';
-import { checkUsage, runCheckCommand, } from "./check-command.js";
 import { writeTextAtomically } from "./atomic-write.js";
+import { checkUsage, runCheckCommand } from "./check-command.js";
 import { graphUsage, runGraphCommand } from "./graph-command.js";
 import { diffUsage, runDiffCommand } from "./diff-command.js";
 import { queryUsage, runQueryCommand } from "./query-command.js";
@@ -23,9 +23,10 @@ Commands:
   graph        Render matched boundary edges
   diff         Compare bridge observations before and after a change
   retentions   Produce external retention evidence
+  help         Show command help
 
 Options:
-  -h, --help   Show help
+  -h, --help   Show help; after a command it shows that command's usage
   --version    Show version
 `;
 const arguments_ = process.argv.slice(2);
@@ -46,22 +47,28 @@ function handleStreamError(error) {
 }
 /** 도움말과 버전처럼 입력 문서가 필요 없는 명령을 실행한다. */
 async function runInformationalCommand(commandArguments) {
-    const first = commandArguments[0];
-    if (commandArguments.length === 1 &&
-        (first === '--help' || first === '-h')) {
-        return successfulText(rootHelp);
+    // 도움말 플래그는 어느 위치에 있든 이긴다. 긴 호출 끝에 붙여도 사용법을 본다.
+    const helpFlagIndex = commandArguments.findIndex((argument) => argument === '--help' || argument === '-h');
+    if (helpFlagIndex >= 0)
+        return commandHelp(commandArguments[0]);
+    if (commandArguments[0] === 'help') {
+        return commandHelp(commandArguments[1]);
     }
-    if (commandArguments.length === 1 && first === '--version') {
+    if (commandArguments.length === 1 &&
+        commandArguments[0] === '--version') {
         return readVersion();
     }
-    if (commandArguments.length === 2 &&
-        (commandArguments[1] === '--help' || commandArguments[1] === '-h')) {
-        const usage = first === undefined ? undefined : commandUsages.get(first);
-        if (usage !== undefined)
-            return successfulText(`${usage}\n`);
-    }
     return undefined;
 }
+/** 명령 이름에 맞는 사용법을, 모르면 루트 도움말을 돌려준다. */
+function commandHelp(command) {
+    if (command === undefined)
+        return successfulText(rootHelp);
+    const usage = commandUsages.get(command);
+    return usage === undefined
+        ? successfulText(rootHelp)
+        : successfulText(`${usage}\n`);
+}
 /** 알려진 분석 하위 명령으로만 라우팅한다. */
 async function dispatchCommand(commandArguments) {
     switch (commandArguments[0]) {

package/dist/cli/main.js.map

@@ -1 +1 @@
-{"version":3,"file":"main.js","sourceRoot":"","sources":["../../src/cli/main.ts"],"names":[],"mappings":"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","sourcesContent":["#!/usr/bin/env node\n\nimport { readFile } from 'node:fs/promises';\n\nimport {\n  checkUsage,\n  runCheckCommand,\n  type CommandResult,\n} from './check-command.ts';\nimport { writeTextAtomically } from './atomic-write.ts';\nimport { graphUsage, runGraphCommand } from './graph-command.ts';\nimport { diffUsage, runDiffCommand } from './diff-command.ts';\nimport { queryUsage, runQueryCommand } from './query-command.ts';\nimport {\n  retentionUsage,\n  runRetentionsCommand,\n} from './retentions-command.ts';\n\nprocess.stdout.on('error', handleStreamError);\nprocess.stderr.on('error', handleStreamError);\n\nconst commandUsages = new Map([\n  ['check', checkUsage],\n  ['graph', graphUsage],\n  ['diff', diffUsage],\n  ['query', queryUsage],\n  ['retentions', retentionUsage],\n]);\n\nconst rootHelp = `Usage: isthmus <command> [options]\n\nCommands:\n  check        Report unmatched bridge calls and handlers\n  query        Find both sides of a channel or method\n  graph        Render matched boundary edges\n  diff         Compare bridge observations before and after a change\n  retentions   Produce external retention evidence\n\nOptions:\n  -h, --help   Show help\n  --version    Show version\n`;\n\nconst arguments_ = process.argv.slice(2);\nconst readTextFile = (path: string) => readFile(path, 'utf8');\nconst writeTextFile = (path: string, text: string) =>\n  writeTextAtomically(path, text);\nconst informationalResult = await runInformationalCommand(arguments_);\nconst result = informationalResult ?? await dispatchCommand(arguments_);\n\nprocess.stdout.write(result.standardOutput);\nprocess.stderr.write(result.standardError);\nprocess.exitCode = result.exitCode;\n\n/** 파이프 소비자가 먼저 닫힌 정상 상황만 조용히 종료한다. */\nfunction handleStreamError(error: NodeJS.ErrnoException): void {\n  if (error.code === 'EPIPE') {\n    process.exitCode = 0;\n    return;\n  }\n  throw error;\n}\n\n/** 도움말과 버전처럼 입력 문서가 필요 없는 명령을 실행한다. */\nasync function runInformationalCommand(\n  commandArguments: readonly string[],\n): Promise<CommandResult | undefined> {\n  const first = commandArguments[0];\n  if (\n    commandArguments.length === 1 &&\n    (first === '--help' || first === '-h')\n  ) {\n    return successfulText(rootHelp);\n  }\n  if (commandArguments.length === 1 && first === '--version') {\n    return readVersion();\n  }\n  if (\n    commandArguments.length === 2 &&\n    (commandArguments[1] === '--help' || commandArguments[1] === '-h')\n  ) {\n    const usage = first === undefined ? undefined : commandUsages.get(first);\n    if (usage !== undefined) return successfulText(`${usage}\\n`);\n  }\n  return undefined;\n}\n\n/** 알려진 분석 하위 명령으로만 라우팅한다. */\nasync function dispatchCommand(\n  commandArguments: readonly string[],\n): Promise<CommandResult> {\n  switch (commandArguments[0]) {\n    case 'check':\n      // SARIF driver에만 필요하므로 메타데이터 부재는 json 보고서를 막지 않는다.\n      return runCheckCommand(\n        commandArguments,\n        readTextFile,\n        writeTextFile,\n        undefined,\n        await readPackageVersion(),\n      );\n    case 'graph':\n      return runGraphCommand(commandArguments, readTextFile);\n    case 'diff':\n      return runDiffCommand(commandArguments, readTextFile);\n    case 'query':\n      return runQueryCommand(commandArguments, readTextFile);\n    case 'retentions': {\n      const version = await readPackageVersion();\n      return version === undefined\n        ? packageMetadataError()\n        : runRetentionsCommand(\n            commandArguments,\n            readTextFile,\n            () => new Date(),\n            version,\n          );\n    }\n    default:\n      return {\n        standardOutput: '',\n        standardError: rootHelp,\n        exitCode: 64,\n      };\n  }\n}\n\n/** 설치된 package.json을 단일 출처로 사용해 버전을 출력한다. */\nasync function readVersion(): Promise<CommandResult> {\n  const version = await readPackageVersion();\n  return version === undefined\n    ? packageMetadataError()\n    : successfulText(`${version}\\n`);\n}\n\n/** 설치된 package.json에서 검증된 버전 문자열을 읽는다. */\nasync function readPackageVersion(): Promise<string | undefined> {\n  try {\n    const text = await readFile(new URL('../../package.json', import.meta.url), 'utf8');\n    const document: unknown = JSON.parse(text);\n    return isVersionDocument(document) ? document.version : undefined;\n  } catch {\n    return undefined;\n  }\n}\n\n/** package metadata가 비어 있지 않은 버전을 제공하는지 확인한다. */\nfunction isVersionDocument(value: unknown): value is { readonly version: string } {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    'version' in value &&\n    typeof value.version === 'string' &&\n    value.version.length > 0\n  );\n}\n\n/** stdout 텍스트와 성공 종료 코드를 만든다. */\nfunction successfulText(standardOutput: string): CommandResult {\n  return { standardOutput, standardError: '', exitCode: 0 };\n}\n\n/** package metadata 실패를 민감정보 없는 코드 2로 바꾼다. */\nfunction packageMetadataError(): CommandResult {\n  return {\n    standardOutput: '',\n    standardError: 'Unable to read package metadata.\\n',\n    exitCode: 2,\n  };\n}\n"]}
+{"version":3,"file":"main.js","sourceRoot":"","sources":["../../src/cli/main.ts"],"names":[],"mappings":"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","sourcesContent":["#!/usr/bin/env node\n\nimport { readFile } from 'node:fs/promises';\n\nimport { writeTextAtomically } from './atomic-write.ts';\nimport { checkUsage, runCheckCommand } from './check-command.ts';\nimport type { CommandResult } from './command-support.ts';\nimport { graphUsage, runGraphCommand } from './graph-command.ts';\nimport { diffUsage, runDiffCommand } from './diff-command.ts';\nimport { queryUsage, runQueryCommand } from './query-command.ts';\nimport {\n  retentionUsage,\n  runRetentionsCommand,\n} from './retentions-command.ts';\n\nprocess.stdout.on('error', handleStreamError);\nprocess.stderr.on('error', handleStreamError);\n\nconst commandUsages = new Map([\n  ['check', checkUsage],\n  ['graph', graphUsage],\n  ['diff', diffUsage],\n  ['query', queryUsage],\n  ['retentions', retentionUsage],\n]);\n\nconst rootHelp = `Usage: isthmus <command> [options]\n\nCommands:\n  check        Report unmatched bridge calls and handlers\n  query        Find both sides of a channel or method\n  graph        Render matched boundary edges\n  diff         Compare bridge observations before and after a change\n  retentions   Produce external retention evidence\n  help         Show command help\n\nOptions:\n  -h, --help   Show help; after a command it shows that command's usage\n  --version    Show version\n`;\n\nconst arguments_ = process.argv.slice(2);\nconst readTextFile = (path: string) => readFile(path, 'utf8');\nconst writeTextFile = (path: string, text: string) =>\n  writeTextAtomically(path, text);\nconst informationalResult = await runInformationalCommand(arguments_);\nconst result = informationalResult ?? await dispatchCommand(arguments_);\n\nprocess.stdout.write(result.standardOutput);\nprocess.stderr.write(result.standardError);\nprocess.exitCode = result.exitCode;\n\n/** 파이프 소비자가 먼저 닫힌 정상 상황만 조용히 종료한다. */\nfunction handleStreamError(error: NodeJS.ErrnoException): void {\n  if (error.code === 'EPIPE') {\n    process.exitCode = 0;\n    return;\n  }\n  throw error;\n}\n\n/** 도움말과 버전처럼 입력 문서가 필요 없는 명령을 실행한다. */\nasync function runInformationalCommand(\n  commandArguments: readonly string[],\n): Promise<CommandResult | undefined> {\n  // 도움말 플래그는 어느 위치에 있든 이긴다. 긴 호출 끝에 붙여도 사용법을 본다.\n  const helpFlagIndex = commandArguments.findIndex(\n    (argument) => argument === '--help' || argument === '-h',\n  );\n  if (helpFlagIndex >= 0) return commandHelp(commandArguments[0]);\n  if (commandArguments[0] === 'help') {\n    return commandHelp(commandArguments[1]);\n  }\n  if (\n    commandArguments.length === 1 &&\n    commandArguments[0] === '--version'\n  ) {\n    return readVersion();\n  }\n  return undefined;\n}\n\n/** 명령 이름에 맞는 사용법을, 모르면 루트 도움말을 돌려준다. */\nfunction commandHelp(command: string | undefined): CommandResult {\n  if (command === undefined) return successfulText(rootHelp);\n  const usage = commandUsages.get(command);\n  return usage === undefined\n    ? successfulText(rootHelp)\n    : successfulText(`${usage}\\n`);\n}\n\n/** 알려진 분석 하위 명령으로만 라우팅한다. */\nasync function dispatchCommand(\n  commandArguments: readonly string[],\n): Promise<CommandResult> {\n  switch (commandArguments[0]) {\n    case 'check':\n      // SARIF driver에만 필요하므로 메타데이터 부재는 json 보고서를 막지 않는다.\n      return runCheckCommand(\n        commandArguments,\n        readTextFile,\n        writeTextFile,\n        undefined,\n        await readPackageVersion(),\n      );\n    case 'graph':\n      return runGraphCommand(commandArguments, readTextFile);\n    case 'diff':\n      return runDiffCommand(commandArguments, readTextFile);\n    case 'query':\n      return runQueryCommand(commandArguments, readTextFile);\n    case 'retentions': {\n      const version = await readPackageVersion();\n      return version === undefined\n        ? packageMetadataError()\n        : runRetentionsCommand(\n            commandArguments,\n            readTextFile,\n            () => new Date(),\n            version,\n          );\n    }\n    default:\n      return {\n        standardOutput: '',\n        standardError: rootHelp,\n        exitCode: 64,\n      };\n  }\n}\n\n/** 설치된 package.json을 단일 출처로 사용해 버전을 출력한다. */\nasync function readVersion(): Promise<CommandResult> {\n  const version = await readPackageVersion();\n  return version === undefined\n    ? packageMetadataError()\n    : successfulText(`${version}\\n`);\n}\n\n/** 설치된 package.json에서 검증된 버전 문자열을 읽는다. */\nasync function readPackageVersion(): Promise<string | undefined> {\n  try {\n    const text = await readFile(new URL('../../package.json', import.meta.url), 'utf8');\n    const document: unknown = JSON.parse(text);\n    return isVersionDocument(document) ? document.version : undefined;\n  } catch {\n    return undefined;\n  }\n}\n\n/** package metadata가 비어 있지 않은 버전을 제공하는지 확인한다. */\nfunction isVersionDocument(value: unknown): value is { readonly version: string } {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    'version' in value &&\n    typeof value.version === 'string' &&\n    value.version.length > 0\n  );\n}\n\n/** stdout 텍스트와 성공 종료 코드를 만든다. */\nfunction successfulText(standardOutput: string): CommandResult {\n  return { standardOutput, standardError: '', exitCode: 0 };\n}\n\n/** package metadata 실패를 민감정보 없는 코드 2로 바꾼다. */\nfunction packageMetadataError(): CommandResult {\n  return {\n    standardOutput: '',\n    standardError: 'Unable to read package metadata.\\n',\n    exitCode: 2,\n  };\n}\n"]}

package/dist/cli/parse-arguments.d.ts

@@ -0,0 +1,18 @@
+/** 플래그와 위치 인수로 나뉜 명령 인수다. */
+export interface ParsedCommandArguments {
+    /** 값 플래그 이름과 그 값이다. 같은 플래그를 두 번 주면 사용법 오류다. */
+    readonly valueFlags: ReadonlyMap<string, string>;
+    /** 값 없는 플래그 이름들이다. 반복은 한 번과 같다. */
+    readonly booleanFlags: ReadonlySet<string>;
+    /** 플래그가 아닌 인수다. `--` 뒤는 `-`로 시작해도 모두 여기에 담긴다. */
+    readonly positionals: readonly string[];
+}
+/**
+ * 모든 분석 하위 명령이 같은 규칙으로 인수를 읽게 하는 공유 파서다.
+ *
+ * 플래그는 위치 인수 앞뒤 어디에 와도 된다. 값 플래그의 값은 비어 있지 않고
+ * `-`로 시작하지 않아야 한다. `--` 이후는 모두 위치 인수로 읽어 `-`로
+ * 시작하는 경로·이름도 전달할 수 있다. 모르는 플래그, 중복 값 플래그, 빈
+ * 플래그 값은 사용법 오류다(undefined).
+ */
+export declare function parseCommandArguments(arguments_: readonly string[], valueFlagNames: readonly string[], booleanFlagNames: readonly string[]): ParsedCommandArguments | undefined;

package/dist/cli/parse-arguments.js

@@ -0,0 +1,48 @@
+/**
+ * 모든 분석 하위 명령이 같은 규칙으로 인수를 읽게 하는 공유 파서다.
+ *
+ * 플래그는 위치 인수 앞뒤 어디에 와도 된다. 값 플래그의 값은 비어 있지 않고
+ * `-`로 시작하지 않아야 한다. `--` 이후는 모두 위치 인수로 읽어 `-`로
+ * 시작하는 경로·이름도 전달할 수 있다. 모르는 플래그, 중복 값 플래그, 빈
+ * 플래그 값은 사용법 오류다(undefined).
+ */
+export function parseCommandArguments(arguments_, valueFlagNames, booleanFlagNames) {
+    const valueFlags = new Set(valueFlagNames);
+    const booleanFlags = new Set(booleanFlagNames);
+    const values = new Map();
+    const booleans = new Set();
+    const positionals = [];
+    let onlyPositionals = false;
+    for (let index = 0; index < arguments_.length; index++) {
+        const argument = arguments_[index];
+        if (argument === undefined)
+            return undefined;
+        if (onlyPositionals || !argument.startsWith('-')) {
+            positionals.push(argument);
+            continue;
+        }
+        if (argument === '--') {
+            onlyPositionals = true;
+            continue;
+        }
+        if (valueFlags.has(argument)) {
+            if (values.has(argument))
+                return undefined;
+            const value = arguments_[index + 1];
+            // 빈 값은 경로가 아니라 호출 오류다. 읽기 실패(코드 2)보다 사용법(64)이 맞다.
+            if (value === undefined || value.length === 0 || value.startsWith('-')) {
+                return undefined;
+            }
+            values.set(argument, value);
+            index++;
+            continue;
+        }
+        if (booleanFlags.has(argument)) {
+            booleans.add(argument);
+            continue;
+        }
+        return undefined;
+    }
+    return { valueFlags: values, booleanFlags: booleans, positionals };
+}
+//# sourceMappingURL=parse-arguments.js.map

package/dist/cli/parse-arguments.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-arguments.js","sourceRoot":"","sources":["../../src/cli/parse-arguments.ts"],"names":[],"mappings":"AAUA;;;;;;;GAOG;AACH,MAAM,UAAU,qBAAqB,CACnC,UAA6B,EAC7B,cAAiC,EACjC,gBAAmC;IAEnC,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,cAAc,CAAC,CAAC;IAC3C,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,gBAAgB,CAAC,CAAC;IAC/C,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;IACzC,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAU,CAAC;IACnC,MAAM,WAAW,GAAa,EAAE,CAAC;IACjC,IAAI,eAAe,GAAG,KAAK,CAAC;IAC5B,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,UAAU,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC;QACvD,MAAM,QAAQ,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC;QACnC,IAAI,QAAQ,KAAK,SAAS;YAAE,OAAO,SAAS,CAAC;QAC7C,IAAI,eAAe,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YACjD,WAAW,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YAC3B,SAAS;QACX,CAAC;QACD,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;YACtB,eAAe,GAAG,IAAI,CAAC;YACvB,SAAS;QACX,CAAC;QACD,IAAI,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC7B,IAAI,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;gBAAE,OAAO,SAAS,CAAC;YAC3C,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;YACpC,kDAAkD;YAClD,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;gBACvE,OAAO,SAAS,CAAC;YACnB,CAAC;YACD,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;YAC5B,KAAK,EAAE,CAAC;YACR,SAAS;QACX,CAAC;QACD,IAAI,YAAY,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC/B,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;YACvB,SAAS;QACX,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,QAAQ,EAAE,WAAW,EAAE,CAAC;AACrE,CAAC","sourcesContent":["/** 플래그와 위치 인수로 나뉜 명령 인수다. */\nexport interface ParsedCommandArguments {\n  /** 값 플래그 이름과 그 값이다. 같은 플래그를 두 번 주면 사용법 오류다. */\n  readonly valueFlags: ReadonlyMap<string, string>;\n  /** 값 없는 플래그 이름들이다. 반복은 한 번과 같다. */\n  readonly booleanFlags: ReadonlySet<string>;\n  /** 플래그가 아닌 인수다. `--` 뒤는 `-`로 시작해도 모두 여기에 담긴다. */\n  readonly positionals: readonly string[];\n}\n\n/**\n * 모든 분석 하위 명령이 같은 규칙으로 인수를 읽게 하는 공유 파서다.\n *\n * 플래그는 위치 인수 앞뒤 어디에 와도 된다. 값 플래그의 값은 비어 있지 않고\n * `-`로 시작하지 않아야 한다. `--` 이후는 모두 위치 인수로 읽어 `-`로\n * 시작하는 경로·이름도 전달할 수 있다. 모르는 플래그, 중복 값 플래그, 빈\n * 플래그 값은 사용법 오류다(undefined).\n */\nexport function parseCommandArguments(\n  arguments_: readonly string[],\n  valueFlagNames: readonly string[],\n  booleanFlagNames: readonly string[],\n): ParsedCommandArguments | undefined {\n  const valueFlags = new Set(valueFlagNames);\n  const booleanFlags = new Set(booleanFlagNames);\n  const values = new Map<string, string>();\n  const booleans = new Set<string>();\n  const positionals: string[] = [];\n  let onlyPositionals = false;\n  for (let index = 0; index < arguments_.length; index++) {\n    const argument = arguments_[index];\n    if (argument === undefined) return undefined;\n    if (onlyPositionals || !argument.startsWith('-')) {\n      positionals.push(argument);\n      continue;\n    }\n    if (argument === '--') {\n      onlyPositionals = true;\n      continue;\n    }\n    if (valueFlags.has(argument)) {\n      if (values.has(argument)) return undefined;\n      const value = arguments_[index + 1];\n      // 빈 값은 경로가 아니라 호출 오류다. 읽기 실패(코드 2)보다 사용법(64)이 맞다.\n      if (value === undefined || value.length === 0 || value.startsWith('-')) {\n        return undefined;\n      }\n      values.set(argument, value);\n      index++;\n      continue;\n    }\n    if (booleanFlags.has(argument)) {\n      booleans.add(argument);\n      continue;\n    }\n    return undefined;\n  }\n  return { valueFlags: values, booleanFlags: booleans, positionals };\n}\n"]}

package/dist/cli/query-command.d.ts

@@ -1,4 +1,4 @@
-import { type CommandResult, type ReadTextFile } from './check-command.ts';
+import { type CommandResult, type ReadTextFile } from './command-support.ts';
 /** query 인자를 실행해 bridge 질의 JSON과 종료 코드를 반환한다. */
 export declare function runQueryCommand(arguments_: readonly string[], readTextFile: ReadTextFile): Promise<CommandResult>;
 /** query 명령의 한 줄 사용법이다. */

package/dist/cli/query-command.js

@@ -1,27 +1,30 @@
 import { isBridgeJoinDeferred, joinBridgeDocuments, MAX_DOCUMENTS_PER_JOIN, } from "../join/join.js";
 import { createBridgeQuery, encodeBridgeQuery } from "../report/query.js";
-import { bridgeJoinDeferredError, internalError, inputFailureResult, readBridgeDocuments, } from "./check-command.js";
+import { bridgeJoinDeferredError, inputFailureResult, internalError, readBridgeDocuments, } from "./command-support.js";
+import { parseCommandArguments } from "./parse-arguments.js";
 /** query 인자를 실행해 bridge 질의 JSON과 종료 코드를 반환한다. */
 export async function runQueryCommand(arguments_, readTextFile) {
-    const requested = arguments_[1];
-    const inputPaths = arguments_.slice(2);
-    if (arguments_[0] !== 'query' ||
-        requested === undefined ||
+    const parsed = parseCommandArguments(arguments_.slice(1), [], []);
+    if (parsed === undefined)
+        return queryUsageError();
+    const requested = parsed.positionals[0];
+    const inputPaths = parsed.positionals.slice(1);
+    if (requested === undefined ||
         requested.trim().length === 0 ||
         inputPaths.length < 2 ||
-        inputPaths.length > MAX_DOCUMENTS_PER_JOIN ||
-        inputPaths.some((path) => path.startsWith('-'))) {
+        inputPaths.length > MAX_DOCUMENTS_PER_JOIN) {
         return queryUsageError();
     }
     try {
         const documents = await readBridgeDocuments(inputPaths, readTextFile);
         const joined = joinBridgeDocuments(documents);
-        if (isBridgeJoinDeferred(joined))
-            return bridgeJoinDeferredError();
+        if (isBridgeJoinDeferred(joined)) {
+            return bridgeJoinDeferredError(joined.observedFacts, documents.length);
+        }
         const query = createBridgeQuery(joined, requested);
         return {
             standardOutput: encodeBridgeQuery(query),
-            standardError: '',
+            standardError: queryStatusHint(query),
             exitCode: query.status === 'found' ? 0 : 64,
         };
     }
@@ -29,6 +32,23 @@ export async function runQueryCommand(arguments_, readTextFile) {
         return inputFailureResult(error) ?? internalError();
     }
 }
+/**
+ * 찾지 못한 질의에 원인을 한 줄로 알린다.
+ *
+ * 문서 자체는 stdout JSON이 이미 다 담고 있으므로, 사람이 종료 코드만 봐도
+ * "인수가 잘못됐는지"와 "이름이 없는지"를 구분할 수 있게 하는 보조 문구다.
+ * 정적 문자열과 숫자만 보간한다.
+ */
+function queryStatusHint(query) {
+    if (query.status === 'found')
+        return '';
+    if (query.status === 'ambiguous') {
+        return `The requested name matches ${query.candidates?.length ?? 0} bridge keys; `
+            + 'repeat the query with a qualifiedName from candidates.\n';
+    }
+    return 'No bridge channel or method matches the requested name; '
+        + 'query a channel or method name that the inputs observed.\n';
+}
 /** 잘못된 query 호출을 사용법과 코드 64로 바꾼다. */
 function queryUsageError() {
     return {