spec-controller 0.1.0-alpha.4 → 0.1.0-alpha.41

package/dist/ingest/ingestScenarios.js

@@ -1,11 +1,14 @@
 /**
  * Ingest the target's feature files — the IMPURE reader that walks features/ on disk
- * and parses each file's feature code + scenario codes into DiscoveredFeature
- * records (split out of the old spec/featureCodes.ts). The pure per-source
- * parsers (extractFeatureCode / parseScenarioCodes) live here with their sole consumer;
- * the `scnId → feature-code` grammar helper is engine-side (packages/core/src/lib/
- * featureCode.ts); the duplicate-code lint is engine-side too since 3F-3313, as @SCN-STG-010 in
- * parse/corpusFaults.ts, and no longer a private check under tests/checks/.
+ * and reads each file's header code into DiscoveredFeature records (split out of the old
+ * spec/featureCodes.ts). The pure header parser (extractFeatureCode) lives here with its sole
+ * consumer; the `scnId → feature-code` grammar helper is engine-side (packages/core/src/lib/
+ * featureCode.ts); the duplicate-code lint is engine-side too, in
+ * parse/scenarioCodeErrors.ts, and no longer a private check under tests/checks/.
+ *
+ * NO PER-FILE LIST OF SCENARIO CODES. One used to ride here, read by a copy of the
+ * @SCN grammar of its own, and nothing but its own test read it; a scenario's code is read by the
+ * engine's scenario walk, which is the reading the ledger's accounts are minted from.
  *
  * The foundation, folded into the @LDG runtime spine.
  */
@@ -21,56 +24,32 @@ const CODE_PATTERN = /^[A-Z0-9]{2,5}$/;
  */
 export function extractFeatureCode(source) {
     const lines = source.split(/\r?\n/);
-    for (let i = 0; i < lines.length; i++) {
-        const line = lines[i].trim();
-        if (line === "" || line.startsWith("#"))
-            continue;
-        if (line.startsWith("Feature:")) {
-            for (let j = i - 1; j >= 0; j--) {
-                const prev = lines[j].trim();
-                if (prev === "")
-                    continue;
-                if (!prev.startsWith("@"))
-                    break;
-                const tags = prev.split(/\s+/).filter((t) => t.startsWith("@"));
-                for (const tag of tags) {
-                    const bare = tag.slice(1);
-                    if (bare.startsWith("SCN-"))
-                        continue;
-                    if (["unit", "integration", "e2e", "performance", "smoke"].includes(bare))
-                        continue;
-                    if (CODE_PATTERN.test(bare))
-                        return bare;
-                }
-            }
-            return null;
-        }
-    }
-    return null;
+    const featureLine = lines.findIndex((line) => line.trim().startsWith("Feature:"));
+    if (featureLine < 0)
+        return null;
+    return headerTagsAbove(lines, featureLine).find(isHeaderCode) ?? null;
+}
+/** The tags a tier or routing concern owns, which are never a file's header code. */
+const NON_CODE_TAGS = ["unit", "integration", "e2e", "performance", "smoke"];
+/** Is this bare tag the file's header code — not an @SCN id, not a tier tag, and code-shaped? */
+function isHeaderCode(bare) {
+    return !bare.startsWith("SCN-") && !NON_CODE_TAGS.includes(bare) && CODE_PATTERN.test(bare);
 }
 /**
- * Parse every @SCN-<FFF>-<NNN> scenario code in a feature file's source, in
- * document order, duplicates preserved. Only genuine TAG LINES are scanned (a
- * line whose first non-blank character is `@` and whose every whitespace-
- * separated token is a tag) — prose that merely mentions a code is skipped.
+ * The bare tags on the tag lines directly above the `Feature:` line, nearest line first and each
+ * line left to right. Blank lines are passed over; the first line that is not a tag line ends it.
  */
-export function parseScenarioCodes(source) {
-    const codes = [];
-    const codePattern = /^SCN-[A-Z0-9]+-\d+$/;
-    for (const rawLine of source.split(/\r?\n/)) {
-        const line = rawLine.trim();
-        if (!line.startsWith("@"))
+function headerTagsAbove(lines, featureLine) {
+    const tags = [];
+    for (let j = featureLine - 1; j >= 0; j--) {
+        const prev = lines[j].trim();
+        if (prev === "")
             continue;
-        const tokens = line.split(/\s+/);
-        if (!tokens.every((t) => t.startsWith("@")))
-            continue;
-        for (const token of tokens) {
-            const bare = token.slice(1);
-            if (codePattern.test(bare))
-                codes.push(bare);
-        }
+        if (!prev.startsWith("@"))
+            break;
+        tags.push(...prev.split(/\s+/).filter((t) => t.startsWith("@")).map((t) => t.slice(1)));
     }
-    return codes;
+    return tags;
 }
 /**
  * Locate the default features/ directory — `./features` under the current
@@ -83,21 +62,19 @@ function featuresDir() {
     return join(process.cwd(), "features");
 }
 /**
- * List the corpus directory, REFUSING an absent one by name rather than by `ENOENT` (@SCN-CLI-017,
- * 3F-3345).
+ * List the corpus directory, REFUSING an absent one by name rather than by `ENOENT`.
  *
  * Absence stays a REFUSAL AT THE READER — what changed is that it is typed, so a caller can decide.
  * `balance` opts in to reporting on a target that has no corpus (most targets have no `features/`
- * at all, and `new-client` is a supported adoption state); `tags` keeps refusing, unedited, because
- * a `MissingFeatureCorpusError` is still an `Error` and still lands in its generic catch. Returning
- * `[]` here instead would make that decision for both, and measured it turns two named refusals
- * into `tags: OK …` at exit 0.
+ * at all, and `new-client` is a supported adoption state) by catching `MissingFeatureCorpusError` by
+ * name. Returning `[]` here instead would make that decision for every caller, and one that
+ * certifies a corpus would certify an absent one as empty.
  *
  * ONLY `ENOENT`. A `features` path that exists but is a FILE, or one the process may not read, is
  * a different fault and is not ours to reinterpret — it rethrows.
  *
  * A SUPPLIED `--features` never reaches here absent: `checkInputsExist` refuses it at the CLI edge
- * with exit 2 (@SCN-CLI-002). Supplied-but-absent is the operator mistyping; absent-by-default is
+ * with exit 2. Supplied-but-absent is the operator mistyping; absent-by-default is
  * the target's honest shape.
  */
 function corpusFileNames(dir) {
@@ -110,9 +87,23 @@ function corpusFileNames(dir) {
         throw err;
     }
 }
+/**
+ * A feature file's text. A read the operating system refuses keeps its error, and gains the file's
+ * path when it has none: reading a directory fails with no path at all.
+ */
+function readFeatureSource(path) {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch (err) {
+        const errno = err;
+        errno.path ??= path;
+        throw err;
+    }
+}
 /**
  * Discover every feature file on disk and its header code — REFUSING a corpus the Gherkin
- * parser rejects (@SCN-GPG-001, 3F-2817).
+ * parser rejects.
  *
  * The refusal lives HERE, in the one reader every corpus consumer already goes through, so a
  * consumer INHERITS it rather than restating it. It is not a second parser: it is the existing
@@ -120,7 +111,7 @@ function corpusFileNames(dir) {
  * balance CLI's edge. One answer to "what is a feature file".
  *
  * WHY THE WHOLE CORPUS, NOT THE FIRST BAD FILE. `featureCorpusParseErrors` reports every
- * unreadable file and the balance CLI prints them all (@SCN-CLI-016). Refusing at the first
+ * unreadable file and the balance CLI prints them all. Refusing at the first
  * failure would silently narrow that message, so every file is parsed and the refusal is raised
  * once, carrying the lot in discovery order.
  *
@@ -133,7 +124,7 @@ export function discoverFeatures(dir = featuresDir()) {
         .sort()
         .map((name) => {
         const path = join(dir, name);
-        return { name, path, source: readFileSync(path, "utf8") };
+        return { name, path, source: readFeatureSource(path) };
     });
     const parseErrors = files.flatMap(({ path, source }) => parseErrorsIn(path, source));
     if (parseErrors.length > 0)
@@ -142,7 +133,6 @@ export function discoverFeatures(dir = featuresDir()) {
         slug: name.replace(/\.feature$/, ""),
         path,
         featureCode: extractFeatureCode(source),
-        scenarioCodes: parseScenarioCodes(source),
     }));
 }
 //# sourceMappingURL=ingestScenarios.js.map

package/dist/ingest/ingestScenarios.js.map

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

package/dist/ingest/inputShapes.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The shape each JSON input `balance` reads must have before its reader is handed it: the fields
+ * that reader goes on to read, and nothing more. A report is its producer's document, so a field
+ * the reader never touches is never checked, and a well-formed empty report is still a report.
+ *
+ * A document that is not this shape is an input the tool cannot read. Read anyway, it either
+ * throws part-way or is read as nothing and reaches a verdict about evidence it discarded, and
+ * both of those end on the out-of-balance code.
+ */
+/** A leaf kind, a list of one shape, a record of named fields, or a map whose entries share one. */
+export type Shape = "string" | "number" | "boolean" | "anything" | {
+    readonly list: Shape;
+} | {
+    readonly fields: Readonly<Record<string, Shape>>;
+    readonly required?: readonly string[];
+} | {
+    readonly entries: Shape;
+    readonly keys?: RegExp;
+};
+/** What the Vitest JSON reporter writes, as far as the Vitest reader reads it. */
+export declare const VITEST_REPORT: Shape;
+/** What the Cucumber JSON formatter writes, as far as the Cucumber reader reads it. */
+export declare const CUCUMBER_REPORT: Shape;
+/**
+ * A CI run's step record, as far as the step-record reader reads it: an object of steps keyed by
+ * step id, of which it credits only those keyed by a scenario code, reading each one's `outcome`.
+ * The key grammar is the reader's own, so a step it never credits is never checked.
+ */
+export declare const CI_STEP_RECORD: Shape;
+/**
+ * A package.json, as far as the run reads it outside the `specController` block: an object whose
+ * `scripts` are a map of commands. The `specController` block is left to its own resolvers, which
+ * read a value they cannot use as absent rather than refuse the run over it.
+ */
+export declare const PACKAGE_MANIFEST: Shape;
+/**
+ * A reconciliation this tool saved, at its top: the sections every one carries, and the optional
+ * ones in their kind. Below the top the renderer is the reader, and a document it cannot render
+ * is refused where it renders.
+ */
+export declare const SAVED_RECONCILIATION: Shape;
+/**
+ * The first place `value` is not `shape`, said as the path to it and what was found there, or null
+ * when the whole value is that shape. `where` is the path so far; the top level has none.
+ */
+export declare function shapeFaultIn(value: unknown, shape: Shape, where?: string): string | null;
+//# sourceMappingURL=inputShapes.d.ts.map

package/dist/ingest/inputShapes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inputShapes.d.ts","sourceRoot":"","sources":["../../src/ingest/inputShapes.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,oGAAoG;AACpG,MAAM,MAAM,KAAK,GACb,QAAQ,GACR,QAAQ,GACR,SAAS,GACT,UAAU,GACV;IAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAA;CAAE,GACxB;IAAE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC;IAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAC3F;IAAE,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAKxD,kFAAkF;AAClF,eAAO,MAAM,aAAa,EAAE,KAc3B,CAAC;AAEF,uFAAuF;AACvF,eAAO,MAAM,eAAe,EAAE,KAe7B,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,cAAc,EAAE,KAG5B,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,EAAE,KAAsD,CAAC;AAEtF;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,EAAE,KAWlC,CAAC;AAkBF;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,SAAK,GAAG,MAAM,GAAG,IAAI,CASpF"}

package/dist/ingest/inputShapes.js

@@ -0,0 +1,143 @@
+/**
+ * The shape each JSON input `balance` reads must have before its reader is handed it: the fields
+ * that reader goes on to read, and nothing more. A report is its producer's document, so a field
+ * the reader never touches is never checked, and a well-formed empty report is still a report.
+ *
+ * A document that is not this shape is an input the tool cannot read. Read anyway, it either
+ * throws part-way or is read as nothing and reaches a verdict about evidence it discarded, and
+ * both of those end on the out-of-balance code.
+ */
+/** What the Vitest JSON reporter writes, as far as the Vitest reader reads it. */
+export const VITEST_REPORT = {
+    fields: {
+        testResults: {
+            list: {
+                fields: {
+                    name: "string",
+                    status: "string",
+                    message: "string",
+                    assertionResults: { list: { fields: { fullName: "string", title: "string", status: "string" } } },
+                },
+            },
+        },
+    },
+    required: ["testResults"],
+};
+/** What the Cucumber JSON formatter writes, as far as the Cucumber reader reads it. */
+export const CUCUMBER_REPORT = {
+    list: {
+        fields: {
+            uri: "string",
+            name: "string",
+            elements: {
+                list: {
+                    fields: {
+                        tags: { list: { fields: { name: "string" } } },
+                        steps: { list: { fields: { keyword: "string", name: "string", result: { fields: { status: "string" } } } } },
+                    },
+                },
+            },
+        },
+    },
+};
+/**
+ * A CI run's step record, as far as the step-record reader reads it: an object of steps keyed by
+ * step id, of which it credits only those keyed by a scenario code, reading each one's `outcome`.
+ * The key grammar is the reader's own, so a step it never credits is never checked.
+ */
+export const CI_STEP_RECORD = {
+    entries: { fields: { outcome: "string" } },
+    keys: /^SCN-[A-Z0-9]{2,5}-\d+$/,
+};
+/**
+ * A package.json, as far as the run reads it outside the `specController` block: an object whose
+ * `scripts` are a map of commands. The `specController` block is left to its own resolvers, which
+ * read a value they cannot use as absent rather than refuse the run over it.
+ */
+export const PACKAGE_MANIFEST = { fields: { scripts: { entries: "string" } } };
+/**
+ * A reconciliation this tool saved, at its top: the sections every one carries, and the optional
+ * ones in their kind. Below the top the renderer is the reader, and a document it cannot render
+ * is refused where it renders.
+ */
+export const SAVED_RECONCILIATION = {
+    fields: {
+        runProvenance: { fields: {} },
+        summary: { fields: {} },
+        ledger: { fields: { scenarioReconciliations: { list: "anything" } }, required: ["scenarioReconciliations"] },
+        scenarioCodeErrors: { list: "anything" },
+        scenarioCodePopulation: { fields: {} },
+        evidenceObligations: { fields: {} },
+        metadata: { fields: {} },
+    },
+    required: ["runProvenance", "summary", "ledger"],
+};
+function kindOf(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "a list";
+    if (typeof value === "object")
+        return "an object";
+    return `a ${typeof value}`;
+}
+function expectedKindOf(shape) {
+    if (typeof shape === "string")
+        return `a ${shape}`;
+    return "list" in shape ? "a list" : "an object";
+}
+function pathOf(where, key) {
+    return where === "" ? key : `${where}.${key}`;
+}
+/**
+ * The first place `value` is not `shape`, said as the path to it and what was found there, or null
+ * when the whole value is that shape. `where` is the path so far; the top level has none.
+ */
+export function shapeFaultIn(value, shape, where = "") {
+    if (shape === "anything")
+        return null;
+    const found = kindOf(value);
+    const expected = expectedKindOf(shape);
+    if (found !== expected)
+        return `${where === "" ? "the top level" : where} is ${found}, not ${expected}`;
+    if (typeof shape === "string")
+        return null;
+    if ("list" in shape)
+        return listFault(value, shape.list, where);
+    if ("entries" in shape)
+        return entriesFault(value, shape, where);
+    return fieldsFault(value, shape, where);
+}
+function listFault(items, item, where) {
+    for (const [index, value] of items.entries()) {
+        const fault = shapeFaultIn(value, item, `${where}[${index}]`);
+        if (fault !== null)
+            return fault;
+    }
+    return null;
+}
+function fieldsFault(record, shape, where) {
+    for (const [key, field] of Object.entries(shape.fields)) {
+        const path = pathOf(where, key);
+        if (record[key] === undefined) {
+            if (shape.required?.includes(key) === true)
+                return `${path} is missing`;
+            continue;
+        }
+        const fault = shapeFaultIn(record[key], field, path);
+        if (fault !== null)
+            return fault;
+    }
+    return null;
+}
+function entriesFault(record, shape, where) {
+    for (const [key, value] of Object.entries(record)) {
+        if (shape.keys !== undefined && !shape.keys.test(key))
+            continue;
+        const fault = shapeFaultIn(value, shape.entries, pathOf(where, key));
+        if (fault !== null)
+            return fault;
+    }
+    return null;
+}
+//# sourceMappingURL=inputShapes.js.map

package/dist/ingest/inputShapes.js.map

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

package/dist/outputLocation.d.ts

@@ -0,0 +1,48 @@
+export declare function unwritableRefusal(subject: string, path: string, err: unknown): string;
+/**
+ * The catch sits on the one write it guards rather than on the process, so a refusal can only ever
+ * name a location this call was asked to write, and a crash anywhere else is not dressed up as one.
+ */
+export declare function writeOrRefuse(subject: string, path: string, write: () => void): void;
+/** Refuses the run on the usage code with one line, for a refusal decided before anything is written. */
+export declare function refuse(message: string): never;
+/** The operating system's identity for a regular file; anything else has none. */
+export interface RegularFileIdentity {
+    readonly dev: bigint;
+    readonly ino: bigint;
+}
+/** What opening a destination found: the identity of the regular file it is, and the file it had to create, if any. */
+export interface ProbedDestination {
+    readonly identity: RegularFileIdentity | undefined;
+    readonly created: string | undefined;
+}
+/**
+ * Throws the operating system's own error when `path` cannot be written as a file, and otherwise
+ * answers which regular file it is. An existing file is opened write-only without truncation (not
+ * "r+", which would also demand read permission). An absent one is created and left in place for the
+ * caller to remove once every destination has been identified: two names for one absent file share
+ * an identity only once one of them exists. So a missing, read-only or non-directory parent answers
+ * with its real reason instead of one this module would have to invent.
+ *
+ * The creation is not exclusive, because the write-only open has already answered that nothing exists
+ * at the end of the path, and an exclusive create would refuse a link whose target does not exist yet
+ * although the write would follow it. What the caller removes is the real file created, never the
+ * link that led to it.
+ */
+export declare function probeDestination(path: string): ProbedDestination;
+/**
+ * The first of `others` that is the same regular file as `file`, or undefined when none is. Every
+ * file created to find out is removed again. A path that cannot be opened shares nothing here: the
+ * write that would use it refuses it on its own terms.
+ */
+export declare function firstSharingFile(file: string, others: readonly string[]): string | undefined;
+/** The identity of the regular file standard output is, when it is one. */
+export declare function stdoutIdentity(): RegularFileIdentity | undefined;
+/**
+ * Whether `path` names standard output: spelled as file descriptor 1, or reaching such a spelling
+ * through links, followed one at a time as `realpath` would. Asking what the path spells rather than
+ * which file it opens is deliberate: when standard output and standard error share one terminal or
+ * one pipe, /dev/stderr opens the very same file, and it does not name standard output.
+ */
+export declare function namesStdout(path: string): boolean;
+//# sourceMappingURL=outputLocation.d.ts.map

package/dist/outputLocation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"outputLocation.d.ts","sourceRoot":"","sources":["../src/outputLocation.ts"],"names":[],"mappings":"AAKA,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,GAAG,MAAM,CAGrF;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,IAAI,GAAG,IAAI,CAOpF;AAED,yGAAyG;AACzG,wBAAgB,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,CAG7C;AAED,kFAAkF;AAClF,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,uHAAuH;AACvH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,GAAG,SAAS,CAAC;IACnD,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;CACtC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,CAQhE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,GAAG,SAAS,CAS5F;AAgBD,2EAA2E;AAC3E,wBAAgB,cAAc,IAAI,mBAAmB,GAAG,SAAS,CAMhE;AAoBD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAOjD"}

package/dist/outputLocation.js

@@ -0,0 +1,140 @@
+import { closeSync, constants, fstatSync, lstatSync, openSync, readlinkSync, realpathSync, unlinkSync } from "node:fs";
+import { dirname, resolve, sep } from "node:path";
+const USAGE_EXIT_CODE = 2;
+export function unwritableRefusal(subject, path, err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    return `${subject}: ${path} (${reason})`;
+}
+/**
+ * The catch sits on the one write it guards rather than on the process, so a refusal can only ever
+ * name a location this call was asked to write, and a crash anywhere else is not dressed up as one.
+ */
+export function writeOrRefuse(subject, path, write) {
+    try {
+        write();
+    }
+    catch (err) {
+        process.stderr.write(unwritableRefusal(subject, path, err) + "\n");
+        process.exit(USAGE_EXIT_CODE);
+    }
+}
+/** Refuses the run on the usage code with one line, for a refusal decided before anything is written. */
+export function refuse(message) {
+    process.stderr.write(message + "\n");
+    return process.exit(USAGE_EXIT_CODE);
+}
+/**
+ * Throws the operating system's own error when `path` cannot be written as a file, and otherwise
+ * answers which regular file it is. An existing file is opened write-only without truncation (not
+ * "r+", which would also demand read permission). An absent one is created and left in place for the
+ * caller to remove once every destination has been identified: two names for one absent file share
+ * an identity only once one of them exists. So a missing, read-only or non-directory parent answers
+ * with its real reason instead of one this module would have to invent.
+ *
+ * The creation is not exclusive, because the write-only open has already answered that nothing exists
+ * at the end of the path, and an exclusive create would refuse a link whose target does not exist yet
+ * although the write would follow it. What the caller removes is the real file created, never the
+ * link that led to it.
+ */
+export function probeDestination(path) {
+    try {
+        return { identity: identityOf(openSync(path, constants.O_WRONLY)), created: undefined };
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err;
+    }
+    const identity = identityOf(openSync(path, constants.O_WRONLY | constants.O_CREAT));
+    return { identity, created: realpathSync(path) };
+}
+/**
+ * The first of `others` that is the same regular file as `file`, or undefined when none is. Every
+ * file created to find out is removed again. A path that cannot be opened shares nothing here: the
+ * write that would use it refuses it on its own terms.
+ */
+export function firstSharingFile(file, others) {
+    const created = [];
+    try {
+        const identity = identityOrNone(file, created);
+        if (identity === undefined)
+            return undefined;
+        return others.find((other) => sameIdentity(identityOrNone(other, created), identity));
+    }
+    finally {
+        for (const path of created)
+            unlinkSync(path);
+    }
+}
+function identityOrNone(path, created) {
+    try {
+        const probed = probeDestination(path);
+        if (probed.created !== undefined)
+            created.push(probed.created);
+        return probed.identity;
+    }
+    catch {
+        return undefined;
+    }
+}
+function sameIdentity(a, b) {
+    return a !== undefined && a.dev === b.dev && a.ino === b.ino;
+}
+/** The identity of the regular file standard output is, when it is one. */
+export function stdoutIdentity() {
+    try {
+        return regularIdentity(fstatSync(1, { bigint: true }));
+    }
+    catch {
+        return undefined;
+    }
+}
+function identityOf(fd) {
+    try {
+        return regularIdentity(fstatSync(fd, { bigint: true }));
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function regularIdentity(stats) {
+    return stats.isFile() ? { dev: stats.dev, ino: stats.ino } : undefined;
+}
+/** The spellings of file descriptor 1 itself, on macOS and on Linux. */
+const STDOUT_SPELLINGS = new Set(["/dev/stdout", "/dev/fd/1", "/proc/self/fd/1", "/proc/thread-self/fd/1", `/proc/${process.pid}/fd/1`]);
+/** A bound on the links followed, as the kernel sets one, so a loop of links answers rather than spins. */
+const MAX_LINKS_FOLLOWED = 40;
+/**
+ * Whether `path` names standard output: spelled as file descriptor 1, or reaching such a spelling
+ * through links, followed one at a time as `realpath` would. Asking what the path spells rather than
+ * which file it opens is deliberate: when standard output and standard error share one terminal or
+ * one pipe, /dev/stderr opens the very same file, and it does not name standard output.
+ */
+export function namesStdout(path) {
+    let current = resolve(path);
+    for (let followed = 0; current !== undefined && followed <= MAX_LINKS_FOLLOWED; followed++) {
+        if (STDOUT_SPELLINGS.has(current))
+            return true;
+        current = withFirstLinkFollowed(current);
+    }
+    return false;
+}
+/** `path` with its first linked component replaced by the link's target, or undefined when none is a link. */
+function withFirstLinkFollowed(path) {
+    const parts = path.split(sep).filter((part) => part !== "");
+    for (let length = 1; length <= parts.length; length++) {
+        const prefix = sep + parts.slice(0, length).join(sep);
+        const target = linkTarget(prefix);
+        if (target !== undefined)
+            return resolve(dirname(prefix), target, ...parts.slice(length));
+    }
+    return undefined;
+}
+function linkTarget(path) {
+    try {
+        return lstatSync(path).isSymbolicLink() ? readlinkSync(path) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=outputLocation.js.map

package/dist/outputLocation.js.map

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