@c4a/context 0.6.0-beta.3 → 0.6.0-beta.5

package/docs/guides/agent-dialogue.md

@@ -209,12 +209,19 @@ This means files outside `src/` and non-exported/internal helpers are skipped.
 If you want docs, tests, examples, or internal APIs included, say that before
 extraction.
 
+If the selected package has no standard package entry, do not ask the user to
+change its source or `package.json`. Explain two Context-owned choices: provide
+the source-relative API roots as configured entries, or scan every file matched
+by the confirmed file scope. Entry-based extraction preserves public API
+reachability; scan mode includes internal declarations by default.
+
 I will first generate a preview without writing candidates. The preview will
 show the file count, symbol count, candidate count, and planned `knowledge/`
 tree. I will only run extraction after that preview matches your expectation.
 ```
 
-Mention `extractTs`, `include`, `exportedOnly`, or `reviewValidity` only if the
+Mention `extractTs`, `include`, `entries`, `mode`, `exportedOnly`, or
+`reviewValidity` only if the
 user asks for implementation details, or when editing `src/index.ts` in a code
 summary.
 
@@ -241,6 +248,22 @@ You do not need to save a payload file; I will write a temporary file and run
 the apply command.
 ```
 
+For a repeated codegraph run with no Review delta, say instead:
+
+```text
+The source was checked and no added, changed, or removed code symbols need a
+decision. Existing approved symbols were preserved, so there is no human gate
+for this run and I can continue.
+```
+
+For an explicitly requested CI/CD path, say:
+
+```text
+I will run the codegraph phase with --auto-promote. It will apply only
+deterministic code add/update/remove deltas, run verification, and fail the
+pipeline if verification fails. Semantic knowledge still requires Review.
+```
+
 ## Package Gate
 
 Bad:

package/docs/guides/agent-guide.md

@@ -142,6 +142,13 @@ subdirectory as its own source and write
 `include: ["packages/button/src/**"]` to choose a package from a larger source;
 `include` only filters files inside the selected source.
 
+For a non-standard package, configure source-relative `entries` on `extractTs`;
+every entry must match `include`. If the user wants all declarations in the
+selected files instead of public API reachability, use `mode: "scan"`, which
+needs no entries and defaults to including internal symbols. Never add an entry
+file or package manifest field to the source repository solely to make Context
+run.
+
 Follow the source inspection pattern when scope is unclear: run
 `context source inspect <source-name> --format json`, show the candidate package
 paths from that CLI output, wait for the user to choose the package path(s), then
@@ -155,11 +162,31 @@ context source inspect <source-name> --format json
 context run <extract-phase-id> --dry-run --format json
 ```
 
-Use the `preview.sources[].modules[]`, `candidateEstimate`, and `agent_hints`
+After the preview, run codegraph extraction normally unless the user explicitly
+asked for CI/CD automation. The first normal run requires Review for all code
+candidates. Subsequent normal runs require Review only for added, changed, or
+removed symbols; unchanged approved symbols stay approved. Always inspect
+`next_action.human_gate`: open Review only when it is `true`, and continue when
+it is `false`.
+
+For a non-interactive pipeline, use `context run <extract-phase-id>
+--auto-promote --format json`. This flag applies only to codegraph, applies its
+deterministic deltas, runs verify, and fails the command if verify fails. Never
+use it for semantic knowledge collections.
+
+Use the preview `mode`, optional `entries`, `preview.sources[].modules[]`,
+`candidateEstimate`, and `agent_hints`
 fields as the authoritative scope check. To the user, call it a preview without
 writing candidates; avoid the internal CLI term. Also show `knowledgeTree` and
-`knowledgePathExamples` before first extraction. Explain that approved pages
-will be written under paths derived from collection, containment, and slug:
+`knowledgePathExamples` before first extraction.
+
+Treat `NO_ENTRY_DETECTED` as a configuration failure: choose explicit
+`entries`, or use `mode: "scan"` when the intended scope is all matched files;
+never report an empty extraction as success. Report discovered, AST-analyzed,
+skipped, symbol, and relation counts separately. The extractor follows
+tsconfig/jsconfig `baseUrl` and `paths`, so do not ask users to rewrite `@/`
+imports solely for Context. Explain that approved pages will be written under
+paths derived from collection, containment, and slug:
 
 ```text
 knowledge/<collection>/<containment>/<slug>.md

package/docs/reference/project-api.md

@@ -259,9 +259,40 @@ Options:
 | `source` | `source("name")` |
 | `collection` | Code extraction uses `"codegraph"` |
 | `include` | Optional glob list inside the selected source; default is `["src/**/*.{ts,tsx}"]` |
-| `exportedOnly` | Default `true` |
+| `mode` | `"exports"` (default) traces public exports from automatic or configured entries; `"scan"` uses every file matched by `include` as an entry root |
+| `entries` | Optional source-relative entry files for `"exports"` mode. They override `package.json` entry detection and live only in the Context project configuration |
+| `exportedOnly` | Defaults to `true` in `"exports"` mode and `false` in `"scan"` mode |
 | `transform` | Optional markdown transform function or functions |
 
+`source` is the only package/module boundary. `include` narrows files inside
+that source; it does not select a second module. Standard packages can omit
+`entries` and use `package.json` `exports`, `main`, or `bin` detection. For a
+non-standard package, configure `entries` in the Context project instead of
+editing the source repository:
+
+```ts
+extractTs({
+  source: componentLib,
+  collection: "codegraph",
+  include: ["src/**/*.ts"],
+  entries: ["src/api.ts"],
+});
+```
+
+When the intended knowledge scope is every declaration in the selected files
+rather than a public export graph, use `mode: "scan"`. Scan mode does not accept
+`entries`; `include` supplies its file roots.
+
+Entry failures use the stable machine code `NO_ENTRY_DETECTED`. This includes
+`entries: []`, exports mode with no detected/configured entry, and scan mode
+with no files matched by `include`; these cases never succeed silently.
+
+TypeScript extraction reads the selected module's `tsconfig.json` or
+`jsconfig.json`. JSONC comments/trailing commas, local or installed `extends`,
+`compilerOptions.baseUrl`, and `compilerOptions.paths` are used for export
+tracing and internal dependency relations, so aliases such as `@/*` resolve to
+their source files.
+
 In monorepos, make the package/subdirectory the source boundary. Register the
 chosen package path with `context source add repo --local <package-dir>` and
 reference the CLI-returned date source name with `source("<source-name>")`.
@@ -274,6 +305,9 @@ boundaries before choosing the source. Use `context run <phase-id> --dry-run
 candidate estimate before writing `unapproved/entities.jsonl`. The dry-run
 preview also includes `knowledgeTree` and `knowledgePathExamples`, which show
 where approved Markdown will land after review apply.
+Its module and total summaries distinguish `discoveredFiles`, `analyzedFiles`,
+`skippedFiles`, `symbols`, and `relations`; modules with skipped files include
+the reason, such as files not reachable from exports-mode entries.
 
 Phase id shape:
 
@@ -281,6 +315,21 @@ Phase id shape:
 extract:<source-name-or-repo>:codegraph
 ```
 
+Codegraph extraction has two execution policies:
+
+- `context run <phase-id>` is the Agent/user default. The first run sends every
+  code symbol to Review. Later runs preserve unchanged approved symbols and send
+  only `add`, `update`, and `remove` deltas to Review. If there is no delta, the
+  result returns `next_action.human_gate=false` and the Agent continues.
+- `context run <phase-id> --auto-promote` is the explicit CI/CD path. It is valid
+  only for `phase.extract.ts` codegraph phases, applies deterministic code deltas
+  without Review, then runs project verification. Verification errors make the
+  command fail; JSON output reports applied/materialized/removed counts.
+
+This policy never auto-promotes architecture, business, decision, test, or
+other semantic knowledge. Agents must follow the returned
+`next_action.human_gate` instead of assuming every extraction requires Review.
+
 ### `reviewValidity`
 
 Declare the review step for a collection:
@@ -304,7 +353,7 @@ review:all:validity
 
 The review HTML and apply flow are CLI-owned.
 
-This phase marks a human review gate. Agents should open `context review html
+This phase marks a human review gate when current candidates exist. Agents should open `context review html
 <collection> --open` or `context review html --all --open` and wait for the
 user-copied payload; they should not run the phase as an automatic approval step
 or synthesize a payload themselves.

package/index.d.ts

@@ -5,7 +5,7 @@ export type { CodegraphCollection, DocumentMainlineCollection, EntityStatus, Kno
 export { assertDocumentMainlineCollection, assertKnowledgeCollection, assertMainlineCollection, assertOkfRoot, assertTopLevelNamespace, DOC_MAINLINE_COLLECTIONS, KNOWLEDGE_COLLECTIONS, MAINLINE_COLLECTIONS, OKF_ROOTS, TOP_LEVEL_NAMESPACES, } from "./contracts.js";
 export { assertDocumentEvidenceSectionMetadata, DOCUMENT_COMPILE_ACTION_SCHEMA_VERSION, DOCUMENT_EVIDENCE_SECTION_VALIDATION_STAGES, DOCUMENT_SECTION_CONTENT_MODES, DOCUMENT_STRUCTURE_SCHEMA_VERSION, } from "./documentEvidence.js";
 export type { DocumentEvidenceSectionMetadata, DocumentEvidenceSectionValidationOptions, DocumentEvidenceSectionValidationStage, DocumentSectionContentMode, } from "./documentEvidence.js";
-export { alignProse, captureFile, captureLark, compileProse, customPhase, extractTs, mdxJsonDocs, reviewValidity, } from "./phases.js";
+export { alignProse, captureFile, captureLark, compileProse, customPhase, extractTs, ExtractTsConfigurationError, NO_ENTRY_DETECTED, mdxJsonDocs, reviewValidity, } from "./phases.js";
 export type { AlignProsePhaseDefinition, CaptureFilePhaseDefinition, CaptureLarkPhaseDefinition, CompileProsePhaseDefinition, ContextPhase, ContextPhaseContext, CustomPhaseDefinition, ExtractTsPhaseDefinition, PhaseDefinition, PhaseResourceReference, ReviewValidityPhaseDefinition, ReviewValidityScope, } from "./phases.js";
 export { allSources, DEFAULT_FILE_SOURCES_REGISTRY_PATH, DEFAULT_LARK_SOURCES_REGISTRY_PATH, DEFAULT_REPO_SOURCES_REGISTRY_PATH, loadSourcesRegistry, resolveSourceReference, source, } from "./sources.js";
 export type { DocumentSourceDefinition, DocumentSourceReference, DocumentSourceType, FileSourceDefinition, FileSourceReference, FileSourceRegistryEntry, LarkSourceDefinition, LarkSourceReference, LarkSourceRegistryEntry, LoadSourcesRegistryOptions, ProjectSourceDefinition, RepoProjectSourceDefinition, RepoSourceDefinition, RepoSourceReference, RepoSourceRegistryEntry, RepoSourcesRegistry, SourceCollectionReference, SourceDefinition, SourceReference, SourcesRegistry, SourceType, } from "./sources.js";

package/index.js

@@ -7016,6 +7016,23 @@ var assertDocumentEvidenceSectionMetadata = (section, options, field = "document
   assertHasSourceRefs(section, field);
 };
 // src/phases.ts
+var NO_ENTRY_DETECTED = "NO_ENTRY_DETECTED";
+
+class ExtractTsConfigurationError extends TypeError {
+  code = NO_ENTRY_DETECTED;
+  constructor(message) {
+    super(message);
+    this.name = "ExtractTsConfigurationError";
+  }
+}
+function normalizeExtractEntry(value) {
+  const slashPath = value.trim().replace(/\\/gu, "/");
+  const segments = slashPath.replace(/^\.\//u, "").split("/");
+  if (slashPath.length === 0 || slashPath.startsWith("/") || /^[A-Za-z]:\//u.test(slashPath) || segments.some((segment) => segment.length === 0 || segment === "." || segment === "..")) {
+    throw new TypeError(`extractTs entries must be source-relative file paths: ${value}`);
+  }
+  return segments.join("/");
+}
 var getSourceType = (sourceDefinition) => {
   if (sourceDefinition.kind === "source.collection" || sourceDefinition.kind === "source.ref") {
     if (!("type" in sourceDefinition)) {
@@ -7197,6 +7214,14 @@ var extractTs = (definition) => {
     throw new TypeError(`extractTs collection must be codegraph: ${definition.collection}`);
   }
   const sourceId = sourceDefinition.kind === "source.collection" ? sourceDefinition.type : sourceDefinition.name;
+  const mode = definition.mode ?? "exports";
+  if (mode === "scan" && definition.entries !== undefined) {
+    throw new TypeError("extractTs entries cannot be combined with mode: scan; scan mode uses every file matched by include");
+  }
+  if (definition.entries !== undefined && definition.entries.length === 0) {
+    throw new ExtractTsConfigurationError("extractTs entries must contain at least one source-relative file path");
+  }
+  const entries = definition.entries === undefined ? undefined : [...new Set(definition.entries.map(normalizeExtractEntry))];
   const phase = {
     kind: "phase.extract.ts",
     id: `extract:${sourceId}:${definition.collection}`,
@@ -7213,7 +7238,9 @@ var extractTs = (definition) => {
     source: sourceDefinition,
     collection: definition.collection,
     include: definition.include ?? ["src/**/*.{ts,tsx}"],
-    exportedOnly: definition.exportedOnly ?? true,
+    mode,
+    ...entries !== undefined ? { entries } : {},
+    exportedOnly: definition.exportedOnly ?? mode === "exports",
     out: {
       kind: "codegraph-entities",
       candidateFile: "unapproved/entities.jsonl",
@@ -11797,8 +11824,10 @@ export {
   alignProse,
   TOP_LEVEL_NAMESPACES,
   OKF_ROOTS,
+  NO_ENTRY_DETECTED,
   MAINLINE_COLLECTIONS,
   KNOWLEDGE_COLLECTIONS,
+  ExtractTsConfigurationError,
   DOC_MAINLINE_COLLECTIONS,
   DOCUMENT_STRUCTURE_SCHEMA_VERSION,
   DOCUMENT_SECTION_CONTENT_MODES,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c4a/context",
-  "version": "0.6.0-beta.3",
+  "version": "0.6.0-beta.5",
   "type": "module",
   "dependencies": {
     "yaml": "^2.5.1",

package/phases.d.ts

@@ -60,6 +60,8 @@ export type ExtractTsPhaseDefinition = {
     source: RepoProjectSourceDefinition;
     collection: "codegraph";
     include: readonly string[];
+    mode: "exports" | "scan";
+    entries?: readonly string[];
     exportedOnly: boolean;
     transform?: MarkdownTransform | readonly MarkdownTransform[];
     out: {
@@ -69,6 +71,11 @@ export type ExtractTsPhaseDefinition = {
         initialStatus: "draft";
     };
 };
+export declare const NO_ENTRY_DETECTED: "NO_ENTRY_DETECTED";
+export declare class ExtractTsConfigurationError extends TypeError {
+    readonly code: "NO_ENTRY_DETECTED";
+    constructor(message: string);
+}
 export type CaptureFilePhaseDefinition = {
     kind: "phase.capture.file";
     id: string;
@@ -153,6 +160,8 @@ export declare const extractTs: (definition: {
     source: RepoProjectSourceDefinition;
     collection: "codegraph";
     include?: readonly string[];
+    mode?: "exports" | "scan";
+    entries?: readonly string[];
     exportedOnly?: boolean;
     transform?: MarkdownTransform | readonly MarkdownTransform[];
 }) => ExtractTsPhaseDefinition;