morluto/rea

Fork 0

mirror of https://github.com/morluto/rea.git synced 2026-11-05 06:45:22 +00:00

[GH-ISSUE #2604] fix(reference-source): configured API documentation path omits generated classification #920

New issue

Closed

opened 2026-10-15 18:29:35 +00:00 by bsakaguchi · 1 comment

bsakaguchi commented

2026-10-15 18:29:35 +00:00

Owner

Originally created by @coygeek on GitHub (Oct 13, 2026).
Original GitHub issue: https://github.com/morluto/rea/issues/2604

Summary

Historical-source entries under the configured docs/api generated path do not receive the generated classification. A TypeScript file there retains documentation and source labels but loses generated, even though the classification policy lists that exact directory path. The failure affects classification metadata; the reproduced case does not establish an incorrect runtime or source-to-bundle result.

Steps to reproduce

With locked repository dependencies installed, save this test as src/domain/generatedPath.regression.test.ts and run npm run test:focused -- src/domain/generatedPath.regression.test.ts. It supplies a read file entry to the production import projection, then checks its classifications and the existing basename and single-directory controls. No filesystem import or source execution is needed.

import { expect, it } from "vitest";
import { classifyReferenceSourcePath } from "./referenceSourceClassification.js";
import { parseReferenceSourceEntries } from "../application/ReferenceSourceImportEntries.js";

it("retains the configured generated label for imported API documentation", () => {
  const bytes = new TextEncoder().encode("export const client = 1;");
  const imported = parseReferenceSourceEntries({
    root: "fixtures/source", bytesRead: bytes.length, limitations: [],
    entries: [{ status: "read", kind: "file", path: "docs/api/client.ts", bytes, size: bytes.length }],
  }, new Set(["docs/api/client.ts"]));
  console.log(imported.entries[0]?.classifications);
  expect(imported.entries[0]?.classifications).toEqual(["documentation", "generated", "source"]);
});

it("retains existing basename and single-directory rules", () => {
  expect(classifyReferenceSourcePath(".github")).toEqual(["config"]);
  expect(classifyReferenceSourcePath(".husky")).toEqual(["config"]);
  expect(classifyReferenceSourcePath(".gitignore")).toEqual(["config"]);
  expect(classifyReferenceSourcePath("public/client.ts")).toEqual(["generated", "source"]);
  expect(classifyReferenceSourcePath("docs/manual/client.ts")).toEqual(["documentation", "source"]);
  expect(classifyReferenceSourcePath("src/main.ts")).toEqual(["source"]);
});

Expected behavior

The configured generated-directory path should add generated to docs/api/client.ts, while keeping documentation and source. Existing basename and single-directory classification rules should keep their current results.

Actual behavior

The independently executed projection returns ["documentation", "source"] for the file, and the assertion requiring generated fails. The same run passes the control test for .github, .husky, .gitignore, public/client.ts, docs/manual/client.ts, and src/main.ts.

Evidence

Expected source: src/domain/referenceSourceClassification.ts:216 declares docs/api in the generated-directory policy; src/domain/referenceSourceClassification.ts:388 applies that policy additively. src/application/ReferenceSourceImportEntries.ts:130 assigns the classifier's result to imported file entries.
Failure source: src/domain/referenceSourceClassification.ts:318 compares each individual slash-separated segment against that policy, so the two-segment entry cannot match. The complete projection fixture above observed documentation and source without generated.
Evidence provenance: observed
Local verification: reproduced
Reproduction completeness: complete

The normal importer calls this projection after reading admitted files. Its default exclusion list does not exclude docs/api, so that path can reach classification. The test exercises the domain classifier and application projection directly, rather than the filesystem reader or CLI/MCP adapters.

Restoration check

The same read entry should return ["documentation", "generated", "source"]. Preserve the existing controls. Also distinguish the configured docs/api path from adjacent names such as docs/apis and docs/manual so matching cannot accidentally label unrelated documentation as generated.

Runtime or environment

REA 6.4.0 source at 8b181716ac. Node v26.10.0, npm 11.19.1, installed locked dependencies, Vitest 5.0.3. The fixture uses an in-memory read entry and launches no analysis provider.

Triage assessment

Impact level: P3
Assessment status: supported
Impact basis: The demonstrated file loses one configured metadata label. Its source and documentation labels remain, and no incorrect downstream analysis result was observed for this input.
Workaround status: available
Workaround basis: A consumer can use the retained relative path to recognize the configured docs/api directory when the generated label is required.

Originally created by @coygeek on GitHub (Oct 13, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/2604 ## Summary Historical-source entries under the configured `docs/api` generated path do not receive the generated classification. A TypeScript file there retains documentation and source labels but loses generated, even though the classification policy lists that exact directory path. The failure affects classification metadata; the reproduced case does not establish an incorrect runtime or source-to-bundle result. ## Steps to reproduce With locked repository dependencies installed, save this test as `src/domain/generatedPath.regression.test.ts` and run `npm run test:focused -- src/domain/generatedPath.regression.test.ts`. It supplies a read file entry to the production import projection, then checks its classifications and the existing basename and single-directory controls. No filesystem import or source execution is needed. ```ts import { expect, it } from "vitest"; import { classifyReferenceSourcePath } from "./referenceSourceClassification.js"; import { parseReferenceSourceEntries } from "../application/ReferenceSourceImportEntries.js"; it("retains the configured generated label for imported API documentation", () => { const bytes = new TextEncoder().encode("export const client = 1;"); const imported = parseReferenceSourceEntries({ root: "fixtures/source", bytesRead: bytes.length, limitations: [], entries: [{ status: "read", kind: "file", path: "docs/api/client.ts", bytes, size: bytes.length }], }, new Set(["docs/api/client.ts"])); console.log(imported.entries[0]?.classifications); expect(imported.entries[0]?.classifications).toEqual(["documentation", "generated", "source"]); }); it("retains existing basename and single-directory rules", () => { expect(classifyReferenceSourcePath(".github")).toEqual(["config"]); expect(classifyReferenceSourcePath(".husky")).toEqual(["config"]); expect(classifyReferenceSourcePath(".gitignore")).toEqual(["config"]); expect(classifyReferenceSourcePath("public/client.ts")).toEqual(["generated", "source"]); expect(classifyReferenceSourcePath("docs/manual/client.ts")).toEqual(["documentation", "source"]); expect(classifyReferenceSourcePath("src/main.ts")).toEqual(["source"]); }); ``` ## Expected behavior The configured generated-directory path should add generated to `docs/api/client.ts`, while keeping documentation and source. Existing basename and single-directory classification rules should keep their current results. ## Actual behavior The independently executed projection returns `["documentation", "source"]` for the file, and the assertion requiring generated fails. The same run passes the control test for `.github`, `.husky`, `.gitignore`, `public/client.ts`, `docs/manual/client.ts`, and `src/main.ts`. ## Evidence - Expected source: `src/domain/referenceSourceClassification.ts:216` declares `docs/api` in the generated-directory policy; `src/domain/referenceSourceClassification.ts:388` applies that policy additively. `src/application/ReferenceSourceImportEntries.ts:130` assigns the classifier's result to imported file entries. - Failure source: `src/domain/referenceSourceClassification.ts:318` compares each individual slash-separated segment against that policy, so the two-segment entry cannot match. The complete projection fixture above observed documentation and source without generated. - Evidence provenance: observed - Local verification: reproduced - Reproduction completeness: complete The normal importer calls this projection after reading admitted files. Its default exclusion list does not exclude `docs/api`, so that path can reach classification. The test exercises the domain classifier and application projection directly, rather than the filesystem reader or CLI/MCP adapters. ## Restoration check The same read entry should return `["documentation", "generated", "source"]`. Preserve the existing controls. Also distinguish the configured `docs/api` path from adjacent names such as `docs/apis` and `docs/manual` so matching cannot accidentally label unrelated documentation as generated. ## Runtime or environment REA 6.4.0 source at 8b181716aca2cb467be499cba226abfb5ae19141. Node v26.10.0, npm 11.19.1, installed locked dependencies, Vitest 5.0.3. The fixture uses an in-memory read entry and launches no analysis provider. ## Triage assessment - Impact level: P3 - Assessment status: supported - Impact basis: The demonstrated file loses one configured metadata label. Its source and documentation labels remain, and no incorrect downstream analysis result was observed for this input. - Workaround status: available - Workaround basis: A consumer can use the retained relative path to recognize the configured docs/api directory when the generated label is required.

bsakaguchi

2026-10-15 18:29:35 +00:00

closed this issue
added the
area: setup

bug
labels

bsakaguchi commented

2026-10-15 18:29:36 +00:00

Author

Owner

@morluto commented on GitHub (Oct 14, 2026):

Reference-source import now preserves generated classification for configured API documentation paths while keeping nearby non-generated documentation paths distinct. The production import boundary regression passes on current main.

Root cause: Generated classification matched individual directory names but did not recognize the configured multi-segment docs/api path.

Validation: tests/boundary/filesystem/referenceSourceImport.test.ts: 'retains manifest, test, generated and language classifications through import' checks docs/api/client.ts as documentation+generated+source and adjacent docs/apis, docs/manual/api, docs/api.ts controls. These assertions passed in CI at 500e32399; the reviewed implementation is present on current main. Fix: ec271121e4996f89f666a5a2ed1cd2f3229411b4.

Verification scope: The classification is verified through the local filesystem import boundary; no remote VCS fetch is exercised.

@morluto commented on GitHub (Oct 14, 2026): Reference-source import now preserves generated classification for configured API documentation paths while keeping nearby non-generated documentation paths distinct. The production import boundary regression passes on current main. Root cause: Generated classification matched individual directory names but did not recognize the configured multi-segment docs/api path. Validation: tests/boundary/filesystem/referenceSourceImport.test.ts: 'retains manifest, test, generated and language classifications through import' checks docs/api/client.ts as documentation+generated+source and adjacent docs/apis, docs/manual/api, docs/api.ts controls. These assertions passed in [CI at 500e32399](https://github.com/morluto/rea/actions/runs/38514789942); the reviewed implementation is present on current main. Fix: [ec271121e4996f89f666a5a2ed1cd2f3229411b4](https://github.com/morluto/rea/commit/ec271121e4996f89f666a5a2ed1cd2f3229411b4). Verification scope: The classification is verified through the local filesystem import boundary; no remote VCS fetch is exercised.

bsakaguchi referenced this issue

2026-10-16 21:17:37 +00:00

[PR #920] [MERGED] perf(cli): defer unused catalog work during command startup #2346

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

morluto/rea#920

No description provided.

Rows
Columns