@makehash/nocap 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hash_kim
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ko.md

@@ -0,0 +1,108 @@
+<h1 align="center">nocap</h1>
+
+<p align="center">명세 문서와 테스트를 연결해 어떤 명세가 아직 검증되지 않았는지 추적합니다.</p>
+
+<p align="center">
+  <a href="https://github.com/makeUgreat/nocap/actions/workflows/ci.yml"><img src="https://github.com/makeUgreat/nocap/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
+  <a href="https://github.com/makeUgreat/nocap/blob/master/packages/nocap/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="Package License" /></a>
+</p>
+
+<p align="center"><a href="https://github.com/makeUgreat/nocap/blob/master/packages/nocap/README.md">English</a></p>
+
+## 소개
+
+nocap은 Markdown 명세와 테스트를 ID로 연결합니다.  
+명세 항목에 ID를 붙이고 테스트에는 그 테스트가 검증하는 ID를 붙입니다.
+
+nocap은 아래와 같은 문제를 찾고 보고합니다.
+- 테스트가 없는 명세 항목
+- 없는 ID를 가리키는 테스트
+- 중복 ID
+- 형식이 틀린 태그
+
+> **참고:** nocap은 주석만 읽고 테스트를 실행하지 않습니다.  
+> 그래서 `it`, `test`, `describe`, `suite`를 쓰는 테스트 러너라면 어디서든 동작합니다.
+
+## 설치
+
+```bash
+$ npm i --save-dev @makehash/nocap
+```
+
+Node.js 22.12 이상이 필요합니다.
+
+## 사용법
+
+```bash
+$ nocap --spec <glob> --test <glob>
+```
+
+| 옵션 | 값 |
+| --- | --- |
+| `--spec <glob>` | 명세 문서의 glob 패턴. 필수. 여러 번 쓸 수 있음 |
+| `--test <glob>` | 테스트 파일의 glob 패턴. 필수. 여러 번 쓸 수 있음 |
+
+nocap은 명령을 실행한 디렉토리를 기준으로 패턴을 찾습니다. 셸이 패턴을 먼저 펼치지 않도록 패턴마다 따옴표로 감쌉니다.
+
+자주 쓰는 명령은 `package.json`의 스크립트로 저장해 둘 수 있습니다. 예:
+
+```json
+{
+  "scripts": {
+    "nocap": "nocap --spec \"docs/**/*.md\" --test \"src/**/*.test.ts\""
+  }
+}
+```
+
+```bash
+$ npm run nocap
+```
+
+> **주의:** `package.json`에서는 위처럼 이스케이프한 큰따옴표를 씁니다. 작은따옴표는 Windows에서 동작하지 않습니다.
+
+## 빠른 시작
+
+예를 들어 프로젝트에 로그인 잠금 기능이 있고, 규칙이 2개라고 합시다.
+
+1. 5회 연속 실패하면 계정을 잠금
+2. 잠금은 30분 후 풀림
+
+그런데 테스트는 첫 번째 규칙에만 있습니다. nocap으로 빠진 테스트를 찾는 방법은 아래와 같습니다.
+
+**1단계.** 명세 문서 `docs/auth.md`의 규칙마다 ID를 붙입니다.
+
+```md
+## 로그인 잠금
+- 5회 연속 실패하면 계정을 잠금 <!-- nocap: AUTH-001 -->
+- 잠금은 30분 후 풀림 <!-- nocap: AUTH-002 -->
+```
+
+**2단계.** `src/auth.test.ts`의 테스트에 그 테스트가 검증하는 규칙의 ID를 붙입니다.
+
+```ts
+// nocap: AUTH-001
+it('5번째 실패에서 계정을 잠근다', () => {})
+```
+
+**3단계.** [사용법](#사용법)의 `nocap` 스크립트를 실행합니다.
+
+```bash
+$ npm run nocap
+docs/auth.md:3: error[uncovered-spec]: "AUTH-002" has no test: 잠금은 30분 후 풀림
+1 error in 1 file: 1 uncovered-spec
+1 of 2 specs covered
+```
+
+nocap은 두 번째 규칙(`AUTH-002`)에 테스트가 없다고 보고하고 `1`로 끝납니다.  
+`// nocap: AUTH-002`를 붙인 테스트를 추가하면 `0`으로 끝납니다.
+
+> **팁:** CI에서 nocap을 실행하면 테스트 없는 명세를 남기는 변경을 막을 수 있습니다.
+
+## 문서
+
+- [문법](https://github.com/makeUgreat/nocap/blob/master/docs/syntax.md) - 태그를 두는 위치와 ID 규칙
+- [CLI](https://github.com/makeUgreat/nocap/blob/master/docs/specs/cli.md) - 옵션, 출력 형식, 종료 코드
+
+## 라이선스
+
+nocap은 [MIT 라이선스](https://github.com/makeUgreat/nocap/blob/master/packages/nocap/LICENSE)를 따릅니다.

package/README.md

@@ -1,3 +1,112 @@
-# Temporary Holding Version
+<h1 align="center">nocap</h1>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<p align="center">Link spec docs to tests, and track which specs are not verified yet.</p>
+
+<p align="center">
+  <a href="https://github.com/makeUgreat/nocap/actions/workflows/ci.yml"><img src="https://github.com/makeUgreat/nocap/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
+  <a href="https://github.com/makeUgreat/nocap/blob/master/packages/nocap/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="Package License" /></a>
+</p>
+
+<p align="center"><a href="https://github.com/makeUgreat/nocap/blob/master/packages/nocap/README.ko.md">한국어</a></p>
+
+## Description
+
+nocap links Markdown specs to tests by ID.
+
+Tag each spec item with an ID. Tag each test with the IDs it covers. nocap then reports:
+
+- spec items with no test
+- tests that reference an unknown ID
+- duplicate IDs
+- malformed tags
+
+> **Note:** nocap reads comments only. It does not run your tests, so it works with any runner that uses `it`, `test`, `describe`, or `suite`.
+
+## Installation
+
+```bash
+$ npm i --save-dev @makehash/nocap
+```
+
+Requires Node.js 22.12 or later.
+
+## Usage
+
+```bash
+$ nocap --spec <glob> --test <glob>
+```
+
+| Option | Value |
+| --- | --- |
+| `--spec <glob>` | Glob for spec documents. Required. Can be repeated. |
+| `--test <glob>` | Glob for test files. Required. Can be repeated. |
+
+nocap resolves the globs from the current directory. Put each glob in quotes so that your shell does not expand it first.
+
+You can save the command as a script in `package.json`. For example:
+
+```json
+{
+  "scripts": {
+    "nocap": "nocap --spec \"docs/**/*.md\" --test \"src/**/*.test.ts\""
+  }
+}
+```
+
+```bash
+$ npm run nocap
+```
+
+> **Warning:** In `package.json`, use escaped double quotes as above. Single quotes do not work on Windows.
+
+## Quick Start
+
+For example, say your project has a login lockout feature with two rules:
+
+1. Lock the account after 5 failed logins.
+2. Unlock the account after 30 minutes.
+
+You have written a test for the first rule only. Here is how nocap finds the missing one.
+
+**Step 1.** Give each rule an ID in the spec document `docs/auth.md`:
+
+```md
+## Login lockout
+- Lock the account after 5 failed logins <!-- nocap: AUTH-001 -->
+- Unlock the account after 30 minutes <!-- nocap: AUTH-002 -->
+```
+
+**Step 2.** Mark the test with the ID of the rule it verifies, in `src/auth.test.ts`:
+
+```ts
+// nocap: AUTH-001
+it('locks the account on the 5th failure', () => {})
+```
+
+**Step 3.** Run the `nocap` script from [Usage](#usage):
+
+```bash
+$ npm run nocap
+docs/auth.md:3: error[uncovered-spec]: "AUTH-002" has no test: Unlock the account after 30 minutes
+1 error in 1 file: 1 uncovered-spec
+1 of 2 specs covered
+```
+
+nocap reports that the second rule (`AUTH-002`) has no test, and exits with `1`. Add a test marked `// nocap: AUTH-002`, and nocap exits with `0`.
+
+> **Tip:** Run nocap in CI to block changes that leave a spec without a test.
+
+## Documentation
+
+The documentation is in Korean.
+
+- [Syntax](https://github.com/makeUgreat/nocap/blob/master/docs/syntax.md) - where to put tags and which IDs are valid
+- [CLI](https://github.com/makeUgreat/nocap/blob/master/docs/specs/cli.md) - options, output format, and exit codes
+
+## Stay in touch
+
+- Author - [hash_kim](https://github.com/makeUgreat)
+
+## License
+
+nocap is [MIT licensed](https://github.com/makeUgreat/nocap/blob/master/packages/nocap/LICENSE).

package/dist/application/coverage/coverage-check.result.d.ts

@@ -0,0 +1,109 @@
+import type { Coverage as DomainCoverage } from '../../domain/coverage/coverage.js';
+import type { SpecInvalidTag } from '../../domain/spec/spec-item.js';
+import type { TestInvalidTag } from '../../domain/test/test-item.js';
+/** A place in a spec document or a test file. */
+export type Location = {
+    readonly path: string;
+    /** Starts at 1. */
+    readonly line: number;
+};
+/** A place where the link between spec items and test items is broken. */
+export type CoverageProblem = {
+    /** A spec item whose id no other spec item has, and that no test item points to. */
+    readonly kind: 'uncovered-spec';
+    readonly id: string;
+    readonly location: Location;
+    /** The sentence of the spec item. Empty when the list item has no text. */
+    readonly text: string;
+} | {
+    /** An id that test items point to, but that no spec item has. */
+    readonly kind: 'unknown-id';
+    readonly id: string;
+    /** Where the test items that point to the id are, in the order of the test items. */
+    readonly testLocations: readonly [Location, ...Location[]];
+} | {
+    /** An id that two or more spec items have. These spec items are not judged as covered or uncovered. */
+    readonly kind: 'duplicate-id';
+    readonly id: string;
+    /** Where the spec items that have the id are, in the order of the spec items. */
+    readonly specLocations: readonly [Location, Location, ...Location[]];
+};
+/** An id candidate that broke the id rule, with the reason taken from the first character the rule does not allow. */
+export type InvalidIdCandidate = {
+    readonly kind: 'invalid-whitespace';
+    readonly value: string;
+} | {
+    readonly kind: 'invalid-char';
+    readonly value: string;
+    readonly firstInvalidChar: string;
+};
+/** A spec tag or a test tag that broke a rule, at the line where the tag starts. No spec item or test item is made from it. */
+export type InvalidTag = {
+    readonly kind: 'id-rule-violation';
+    readonly location: Location;
+    readonly invalidCandidates: readonly [InvalidIdCandidate, ...InvalidIdCandidate[]];
+} | {
+    readonly kind: 'missing-id';
+    readonly location: Location;
+} | {
+    /** A spec tag has two or more ids. Only spec tags have this reason. */
+    readonly kind: 'multiple-ids';
+    readonly location: Location;
+    readonly ids: readonly [string, string, ...string[]];
+};
+/** A file that took no part in the coverage judgment. */
+export type FileError = {
+    readonly kind: 'read-error';
+    readonly path: string;
+    readonly message: string;
+} | {
+    readonly kind: 'unsupported-extension';
+    readonly path: string;
+    readonly extension: string;
+    /** The extensions the test file parser supports, in the order the parser lists them. */
+    readonly supportedExtensions: readonly [string, ...string[]];
+} | {
+    readonly kind: 'syntax-error';
+    readonly path: string;
+    readonly messages: readonly [string, ...string[]];
+};
+/** A glob pattern that matched no file, with the side it was given for. */
+export type UnmatchedPattern = {
+    readonly side: 'spec' | 'test';
+    readonly pattern: string;
+};
+/** Glob patterns that matched no file. When there is one, the check reads no file and judges nothing. */
+export type UnmatchedPatterns = {
+    readonly kind: 'unmatched-patterns';
+    /** Spec patterns first, then test patterns. Each side is in the order given, and each pattern appears once. */
+    readonly patterns: readonly [UnmatchedPattern, ...UnmatchedPattern[]];
+};
+type CoverageCheckResultData = {
+    readonly specCount: number;
+    readonly coveredSpecCount: number;
+    readonly coverageProblems: readonly CoverageProblem[];
+    readonly invalidTags: readonly InvalidTag[];
+    readonly fileErrors: readonly FileError[];
+};
+/** The result of one coverage check. It holds plain data only, so that code outside application does not depend on the domain model. */
+export declare class CoverageCheckResult {
+    readonly specCount: number;
+    readonly coveredSpecCount: number;
+    /** Spec side problems in the order their ids first appear in the spec items, then unknown ids in the order they first appear in the test items. */
+    readonly coverageProblems: readonly CoverageProblem[];
+    /** Invalid tags of the spec documents, then those of the test files. Each group is in code unit order of the paths, then in document order. */
+    readonly invalidTags: readonly InvalidTag[];
+    /** Errors of the spec documents, then those of the test files. Each group is in code unit order of the paths. */
+    readonly fileErrors: readonly FileError[];
+    readonly kind = "checked";
+    private constructor();
+    static of(data: CoverageCheckResultData): CoverageCheckResult;
+    static fromDomain({ coverage, invalidTags, fileErrors, }: {
+        readonly coverage: DomainCoverage;
+        readonly invalidTags: readonly (SpecInvalidTag | TestInvalidTag)[];
+        readonly fileErrors: readonly FileError[];
+    }): CoverageCheckResult;
+    hasProblems(): boolean;
+    isFullyCovered(): boolean;
+}
+export {};

package/dist/application/coverage/coverage-check.result.js

@@ -0,0 +1,93 @@
+/** The result of one coverage check. It holds plain data only, so that code outside application does not depend on the domain model. */
+export class CoverageCheckResult {
+    specCount;
+    coveredSpecCount;
+    coverageProblems;
+    invalidTags;
+    fileErrors;
+    kind = 'checked';
+    constructor(specCount, coveredSpecCount, 
+    /** Spec side problems in the order their ids first appear in the spec items, then unknown ids in the order they first appear in the test items. */
+    coverageProblems, 
+    /** Invalid tags of the spec documents, then those of the test files. Each group is in code unit order of the paths, then in document order. */
+    invalidTags, 
+    /** Errors of the spec documents, then those of the test files. Each group is in code unit order of the paths. */
+    fileErrors) {
+        this.specCount = specCount;
+        this.coveredSpecCount = coveredSpecCount;
+        this.coverageProblems = coverageProblems;
+        this.invalidTags = invalidTags;
+        this.fileErrors = fileErrors;
+    }
+    static of(data) {
+        return new CoverageCheckResult(data.specCount, data.coveredSpecCount, data.coverageProblems, data.invalidTags, data.fileErrors);
+    }
+    static fromDomain({ coverage, invalidTags, fileErrors, }) {
+        return CoverageCheckResult.of({
+            specCount: coverage.specCount,
+            coveredSpecCount: coverage.coveredSpecCount,
+            coverageProblems: coverage.problems.map(coverageProblemOf),
+            invalidTags: invalidTags.map(invalidTagOf),
+            fileErrors,
+        });
+    }
+    hasProblems() {
+        return this.coverageProblems.length > 0 || this.invalidTags.length > 0 || this.fileErrors.length > 0;
+    }
+    isFullyCovered() {
+        return this.coveredSpecCount === this.specCount;
+    }
+}
+function coverageProblemOf(problem) {
+    switch (problem.kind) {
+        case 'uncovered-spec':
+            return {
+                kind: 'uncovered-spec',
+                id: problem.specItem.id.value,
+                location: locationOf(problem.specItem.location),
+                text: problem.specItem.text,
+            };
+        case 'unknown-id': {
+            const [first, ...rest] = problem.testItems;
+            return {
+                kind: 'unknown-id',
+                id: problem.id.value,
+                testLocations: [locationOf(first.location), ...rest.map((testItem) => locationOf(testItem.location))],
+            };
+        }
+        case 'duplicate-id': {
+            const [first, second, ...rest] = problem.specItems;
+            return {
+                kind: 'duplicate-id',
+                id: problem.id.value,
+                specLocations: [locationOf(first.location), locationOf(second.location), ...rest.map((specItem) => locationOf(specItem.location))],
+            };
+        }
+    }
+}
+function invalidTagOf(invalidTag) {
+    const location = locationOf(invalidTag.location);
+    switch (invalidTag.kind) {
+        case 'id-rule-violation': {
+            const [first, ...rest] = invalidTag.invalidCandidates;
+            return { kind: 'id-rule-violation', location, invalidCandidates: [invalidIdCandidateOf(first), ...rest.map(invalidIdCandidateOf)] };
+        }
+        case 'missing-id':
+            return { kind: 'missing-id', location };
+        case 'multiple-ids': {
+            const [first, second, ...rest] = invalidTag.ids;
+            return { kind: 'multiple-ids', location, ids: [first.value, second.value, ...rest.map((id) => id.value)] };
+        }
+    }
+}
+function invalidIdCandidateOf(candidate) {
+    switch (candidate.kind) {
+        case 'invalid-whitespace':
+            return { kind: 'invalid-whitespace', value: candidate.value };
+        case 'invalid-char':
+            return { kind: 'invalid-char', value: candidate.value, firstInvalidChar: candidate.firstInvalidChar };
+    }
+}
+function locationOf(location) {
+    return { path: location.path, line: location.line };
+}

package/dist/application/coverage/coverage-check.usecase.d.ts

@@ -0,0 +1,23 @@
+import type { FileFinder } from '../file/file.finder.js';
+import type { FileReader } from '../file/file.reader.js';
+import type { SpecDocumentParser } from '../spec/spec-document.parser.js';
+import type { TestFileParser } from '../test/test-file.parser.js';
+import { CoverageCheckResult, type UnmatchedPatterns } from './coverage-check.result.js';
+export type CoverageCheckInput = {
+    /** Glob patterns of the spec documents. */
+    readonly specPatterns: readonly [string, ...string[]];
+    /** Glob patterns of the test files. */
+    readonly testPatterns: readonly [string, ...string[]];
+};
+export declare class CoverageCheckUsecase {
+    private readonly fileFinder;
+    private readonly fileReader;
+    private readonly specDocumentParser;
+    private readonly testFileParser;
+    constructor(fileFinder: FileFinder, fileReader: FileReader, specDocumentParser: SpecDocumentParser, testFileParser: TestFileParser);
+    run(input: CoverageCheckInput): Promise<CoverageCheckResult | UnmatchedPatterns>;
+    private findFiles;
+    private readFiles;
+    private parseSpecDocument;
+    private parseTestFile;
+}

package/dist/application/coverage/coverage-check.usecase.js

@@ -0,0 +1,76 @@
+import { Coverage } from '../../domain/coverage/coverage.js';
+import { SpecDocument } from '../../domain/spec/spec-document.js';
+import { TestFile } from '../../domain/test/test-file.js';
+import { isNonEmpty } from '../../lib/array-length.js';
+import { CoverageCheckResult } from './coverage-check.result.js';
+export class CoverageCheckUsecase {
+    fileFinder;
+    fileReader;
+    specDocumentParser;
+    testFileParser;
+    constructor(fileFinder, fileReader, specDocumentParser, testFileParser) {
+        this.fileFinder = fileFinder;
+        this.fileReader = fileReader;
+        this.specDocumentParser = specDocumentParser;
+        this.testFileParser = testFileParser;
+    }
+    async run(input) {
+        const [specPaths, testPaths] = await Promise.all([this.findFiles(input.specPatterns), this.findFiles(input.testPatterns)]);
+        const unmatchedPatterns = [
+            ...specPaths.unmatchedPatterns.map((pattern) => ({ side: 'spec', pattern })),
+            ...testPaths.unmatchedPatterns.map((pattern) => ({ side: 'test', pattern })),
+        ];
+        if (isNonEmpty(unmatchedPatterns)) {
+            return { kind: 'unmatched-patterns', patterns: unmatchedPatterns };
+        }
+        const [specFiles, testFiles] = await Promise.all([this.readFiles(specPaths.paths), this.readFiles(testPaths.paths)]);
+        const specs = collect(specFiles, (path, content) => this.parseSpecDocument(path, content));
+        const tests = collect(testFiles, (path, content) => this.parseTestFile(path, content));
+        return CoverageCheckResult.fromDomain({
+            coverage: Coverage.of({ specItems: specs.items, testItems: tests.items }),
+            invalidTags: [...specs.invalidTags, ...tests.invalidTags],
+            fileErrors: [...specs.fileErrors, ...tests.fileErrors],
+        });
+    }
+    async findFiles(patterns) {
+        const uniquePatterns = [...new Set(patterns)];
+        const found = await Promise.all(uniquePatterns.map(async (pattern) => ({ pattern, paths: await this.fileFinder.find([pattern]) })));
+        const unmatchedPatterns = found.filter(({ paths }) => paths.length === 0).map(({ pattern }) => pattern);
+        const uniquePaths = [...new Set(found.flatMap(({ paths }) => paths))];
+        return { paths: uniquePaths.sort(), unmatchedPatterns };
+    }
+    async readFiles(pathsInCodeUnitOrder) {
+        return Promise.all(pathsInCodeUnitOrder.map(async (path) => ({ path, result: await this.fileReader.read(path) })));
+    }
+    parseSpecDocument(path, content) {
+        const document = SpecDocument.of(path, this.specDocumentParser.parse(content));
+        return { kind: 'parsed', items: document.specItems, invalidTags: document.invalidTags };
+    }
+    parseTestFile(path, content) {
+        const result = this.testFileParser.parse(path, content);
+        switch (result.kind) {
+            case 'parsed': {
+                const testFile = TestFile.of(path, result.sites);
+                return { kind: 'parsed', items: testFile.items, invalidTags: testFile.invalidTags };
+            }
+            case 'unsupported-extension':
+                return { kind: 'unsupported-extension', path, extension: result.extension, supportedExtensions: result.supportedExtensions };
+            case 'syntax-error':
+                return { kind: 'syntax-error', path, messages: result.messages };
+        }
+    }
+}
+function collect(files, parse) {
+    const collected = { items: [], invalidTags: [], fileErrors: [] };
+    for (const { path, result } of files) {
+        const outcome = result.kind === 'read-error' ? { kind: 'read-error', path, message: result.message } : parse(path, result.content);
+        if (outcome.kind === 'parsed') {
+            collected.items.push(...outcome.items);
+            collected.invalidTags.push(...outcome.invalidTags);
+        }
+        else {
+            collected.fileErrors.push(outcome);
+        }
+    }
+    return collected;
+}

package/dist/application/file/file.finder.d.ts

@@ -0,0 +1,12 @@
+export interface FileFinder {
+    /**
+     * Finds the files that match any of the glob patterns.
+     *
+     * @param patterns - Glob patterns relative to the root directory of the finder.
+     * @returns Paths relative to the root directory, with `/` as the separator.
+     * Files under a `node_modules` or `.git` directory are left out.
+     * The order is not specified, and a path may appear more than once.
+     * Empty when no file matches or the root directory does not exist.
+     */
+    find(patterns: readonly [string, ...string[]]): Promise<string[]>;
+}

package/dist/application/file/file.finder.js

@@ -0,0 +1 @@
+export {};

package/dist/application/file/file.reader.d.ts

@@ -0,0 +1,21 @@
+/** The whole file was read. */
+export type FileRead = {
+    readonly kind: 'read';
+    /** Full text of the file, decoded as UTF-8. */
+    readonly content: string;
+};
+/** The file could not be read, for example because permission is missing or the file was removed. */
+export type FileReadError = {
+    readonly kind: 'read-error';
+    /** Error message reported by the file system. */
+    readonly message: string;
+};
+export type FileReadResult = FileRead | FileReadError;
+export interface FileReader {
+    /**
+     * Reads one file as text.
+     *
+     * @param path - Path relative to the root directory of the reader, as returned by `FileFinder`.
+     */
+    read(path: string): Promise<FileReadResult>;
+}

package/dist/application/file/file.reader.js

@@ -0,0 +1 @@
+export {};

package/dist/application/spec/spec-document.parser.d.ts

@@ -0,0 +1,11 @@
+import type { SpecTagSite } from '../../domain/spec/spec-tag-site.boundary.js';
+export interface SpecDocumentParser {
+    /**
+     * Finds the tag sites of the list items in one spec document.
+     *
+     * @param content - Full text of the spec document.
+     * @returns The tag sites in the order they appear in the document. Empty when the document has none.
+     * The text of each tag site is the spec sentence: the first paragraph of the list item without the comment, on one line.
+     */
+    parse(content: string): SpecTagSite[];
+}

package/dist/application/spec/spec-document.parser.js

@@ -0,0 +1 @@
+export {};

package/dist/application/test/test-file.parser.d.ts

@@ -0,0 +1,37 @@
+import type { TagSite } from '../../domain/shared/tag-site.boundary.js';
+/** The whole file was read. */
+export type TestFileParsed = {
+    readonly kind: 'parsed';
+    /** The tag sites of the test calls in the order they appear in the file. Empty when the file has none. */
+    readonly sites: readonly TagSite[];
+};
+/** The language of the file could not be determined from the extension of `path`. */
+export type UnsupportedExtension = {
+    readonly kind: 'unsupported-extension';
+    /** The extension including the leading dot, for example `.py`. Empty when `path` has no extension. */
+    readonly extension: string;
+    /** The extensions the parser supports, including the leading dot, for example `.ts`. */
+    readonly supportedExtensions: readonly [string, ...string[]];
+};
+/**
+ * The file has a syntax error.
+ *
+ * @remarks
+ * A test runner cannot load such a file either, so none of its tests run.
+ * For that reason no test items are returned, even when part of the file could be read.
+ */
+export type TestFileSyntaxError = {
+    readonly kind: 'syntax-error';
+    /** Error messages reported by the parser. */
+    readonly messages: readonly [string, ...string[]];
+};
+export type TestFileParseResult = TestFileParsed | UnsupportedExtension | TestFileSyntaxError;
+export interface TestFileParser {
+    /**
+     * Finds the tag sites of the test calls in one test file.
+     *
+     * @param path - Path of the test file. Its extension selects the language.
+     * @param content - Full text of the test file.
+     */
+    parse(path: string, content: string): TestFileParseResult;
+}

package/dist/application/test/test-file.parser.js

@@ -0,0 +1 @@
+export {};

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};