@h1v35/hivex 0.2.0 → 0.2.2

package/src/source-relocation.ts

@@ -0,0 +1,222 @@
+import { compareSerializedStrings } from './ordering.ts';
+import { HivexError } from './errors.ts';
+import { isMarkdownPath } from './markdown.ts';
+import type { Project } from './documents.ts';
+import type { Graph } from './knowledge-model.ts';
+
+const protectedParts = new Set(['', '.', '..', '.git', '.hivex', 'node_modules']);
+
+const isPortablePath = function isPortablePath(value: string) {
+  if (!isMarkdownPath(value) || value.startsWith('/')) {
+    return false;
+  }
+  if (value.includes('\\') || value.includes('\0')) {
+    return false;
+  }
+  return value.split('/').every((part) => !protectedParts.has(part));
+};
+
+const fail = function fail(code: string, message: string): never {
+  throw new HivexError({ code, message });
+};
+
+const relationshipVersions = function relationshipVersions(
+  relationship: Graph['relationships'][number],
+  document: string
+) {
+  return relationship.evidence
+    .filter((evidence) => evidence.document === document)
+    .flatMap((evidence) => (evidence.version === undefined ? [] : [evidence.version]));
+};
+
+const warningVersions = function warningVersions(
+  warning: Graph['warnings'][number],
+  document: string
+) {
+  if (typeof warning === 'string') {
+    return [];
+  }
+  return warning.scope.filter((scope) => scope.document === document).map((scope) => scope.version);
+};
+
+const sourceVersions = function sourceVersions(graph: Graph, document: string) {
+  const versions = [
+    graph.documents[document],
+    ...Object.values(graph.units)
+      .filter((unit) => unit.document === document)
+      .map((unit) => unit.version),
+    ...graph.decisions
+      .filter((decision) => decision.document === document)
+      .map((decision) => decision.version),
+    ...graph.relationships.flatMap((relationship) => relationshipVersions(relationship, document)),
+    ...graph.warnings.flatMap((warning) => warningVersions(warning, document)),
+  ].filter((version): version is string => version !== undefined);
+  return [...new Set(versions)].toSorted(compareSerializedStrings);
+};
+
+const hasKnowledge = function hasKnowledge(graph: Graph, document: string) {
+  if (graph.documents[document] !== undefined) {
+    return true;
+  }
+  if (Object.values(graph.units).some((unit) => unit.document === document)) {
+    return true;
+  }
+  if (graph.decisions.some((decision) => decision.document === document)) {
+    return true;
+  }
+  if (
+    graph.relationships.some((relationship) =>
+      relationship.evidence.some((evidence) => evidence.document === document)
+    )
+  ) {
+    return true;
+  }
+  return graph.warnings.some(
+    (warning) =>
+      typeof warning !== 'string' && warning.scope.some((scope) => scope.document === document)
+  );
+};
+
+const selectedDocument = function selectedDocument(project: Project, id: string) {
+  return project.documents.find((document) => document.id === id);
+};
+
+const mapCitation = function mapCitation<T extends { document: string }>(
+  citation: T,
+  from: string,
+  to: string
+) {
+  return citation.document === from ? { ...citation, document: to } : citation;
+};
+
+const mapUnitId = function mapUnitId(id: string, from: string, to: string) {
+  const prefix = `${from}:`;
+  return id.startsWith(prefix) ? `${to}${id.slice(from.length)}` : id;
+};
+
+const mapWarning = function mapWarning(
+  warning: Graph['warnings'][number],
+  from: string,
+  to: string
+): Graph['warnings'][number] {
+  return typeof warning === 'string'
+    ? warning
+    : { ...warning, scope: warning.scope.map((scope) => mapCitation(scope, from, to)) };
+};
+
+const mapDecision = function mapDecision(
+  decision: Graph['decisions'][number],
+  from: string,
+  to: string
+) {
+  return { ...decision, document: decision.document === from ? to : decision.document };
+};
+
+const mapRelationship = function mapRelationship(
+  relationship: Graph['relationships'][number],
+  from: string,
+  to: string
+) {
+  return {
+    ...relationship,
+    evidence: relationship.evidence.map((evidence) => mapCitation(evidence, from, to)),
+  };
+};
+
+const mapUnits = function mapUnits(
+  graph: Graph,
+  from: string,
+  to: string,
+  isCoverageRelocated: boolean
+) {
+  const entries = Object.entries(graph.units).flatMap(([id, unit]) => {
+    if (!isCoverageRelocated && (unit.document === from || unit.document === to)) {
+      return [];
+    }
+    if (unit.document !== from) {
+      return [[id, unit] as const];
+    }
+    const relocatedId = mapUnitId(id, from, to);
+    return [[relocatedId, { ...unit, document: to }] as const];
+  });
+  return Object.fromEntries(entries);
+};
+
+const mapDocuments = function mapDocuments(
+  graph: Graph,
+  from: string,
+  to: string,
+  options: { isCoverageRelocated: boolean; sourceVersion: string | undefined }
+) {
+  const entries = Object.entries(graph.documents).filter(([id]) => id !== from && id !== to);
+  if (options.isCoverageRelocated && options.sourceVersion !== undefined) {
+    entries.push([to, options.sourceVersion]);
+  }
+  return Object.fromEntries(entries);
+};
+
+export interface SourceRelocation {
+  destinationVersion: string;
+  from: string;
+  fromVersions: string[];
+  graph: Graph;
+  reused: boolean;
+  to: string;
+}
+
+export const relocateSource = function relocateSource(
+  graph: Graph,
+  project: Project,
+  from: string,
+  to: string
+): SourceRelocation {
+  if (from === to || !isPortablePath(from) || !isPortablePath(to)) {
+    fail(
+      'INVALID_ARGUMENT',
+      'Source relocation paths must be distinct project-local Markdown files'
+    );
+  }
+  if (!hasKnowledge(graph, from)) {
+    fail('SOURCE_NOT_FOUND', `Source is not present in knowledge: ${from}`);
+  }
+  if (selectedDocument(project, from) !== undefined) {
+    fail('INVALID_ARGUMENT', `Source must no longer be selected: ${from}`);
+  }
+  const destination = project.currentDocuments.find((document) => document.id === to);
+  if (destination === undefined) {
+    return fail('SOURCE_NOT_FOUND', `Destination is not a selected current Markdown source: ${to}`);
+  }
+  const versions = sourceVersions(graph, from);
+  const hasDestinationKnowledge = hasKnowledge(graph, to);
+  const hasUnversionedEvidence = graph.relationships
+    .flatMap((relationship) => relationship.evidence)
+    .some((evidence) => evidence.document === from && evidence.version === undefined);
+  const isReused =
+    !hasDestinationKnowledge &&
+    !hasUnversionedEvidence &&
+    versions.length > 0 &&
+    versions.every((version) => version === destination.hash);
+  const documents = mapDocuments(graph, from, to, {
+    isCoverageRelocated: isReused,
+    sourceVersion: graph.documents[from],
+  });
+  const units = mapUnits(graph, from, to, isReused);
+  const relocated: Graph = {
+    ...graph,
+    decisions: graph.decisions.map((decision) => mapDecision(decision, from, to)),
+    documents,
+    relationships: graph.relationships.map((relationship) =>
+      mapRelationship(relationship, from, to)
+    ),
+    units,
+    warnings: graph.warnings.map((warning) => mapWarning(warning, from, to)),
+  };
+  return {
+    destinationVersion: destination.hash,
+    from,
+    fromVersions: versions,
+    graph: relocated,
+    reused: isReused,
+    to,
+  };
+};

package/docs/engineering.md

@@ -1,174 +0,0 @@
----
-title: Engineering workflow
-status: accepted
----
-
-# Engineering workflow
-
-Hivex is a TypeScript/Bun product. Modules group behavior by domain responsibility and hide internal
-details behind small interfaces. Do not add a second development-session orchestrator or require
-an adopting project's layout, tracker or product packages. Codex, Git/GitHub and CI coordinate work.
-
-## Development and verification
-
-Work is issue-first in `H1V35/hivex`. New vertical work follows discovery where decisions remain open,
-then an agreed spec, verifiable execution tickets, implementation and code review. Reuse settled scope
-instead of reopening an interview. The owning repository carries the execution ticket; a cross-repository
-parent supplies context and coordination, not a substitute for native tracking.
-
-Resolve the existing spec/ticket before changing code and link the PR and verification to it. Absorb
-review findings into the appropriate existing ticket whenever its scope permits. Open a separate issue
-only when strictly necessary to preserve independently actionable work, and record why it cannot be
-absorbed. Read-only retrieval does not need a new ticket. Specs and tickets track work and acceptance;
-resulting durable decisions also enter their repository authority.
-
-Use an existing issue for an already tracked requirement. Create a branch from the current remote
-main, keep each PR to one coherent change and preserve commit history when merging. Never push
-directly to main or force-push a shared branch. Apply review findings before acceptance; an invalid
-review can be rerun, while an adverse finding must be resolved on its merits. Current explicit owner
-authorization governs whether the agent may merge.
-
-Independent code reviewers use the coordinating agent's current model and reasoning effort. Pass
-that profile explicitly when the subagent default differs, and verify the effective configuration
-after dispatch. Do not substitute the cheaper knowledge model for code review. Routine implementation subtasks may use an
-explicitly authorized cheaper model; Hivex's internal knowledge extraction/checking uses the user's
-knowledge-model configuration independently of the development and code-review model.
-
-Choose verification for the affected surfaces. Code changes require typechecking, lint, formatting
-and relevant behavior tests; documentation-only changes need formatting and checks of affected
-references or declared sources. Record the exact revision and the checks actually completed. A later
-change invalidates the affected results. Do not claim an omitted, interrupted or truncated check passed.
-
-GitHub Actions runs the quality workflow on the owner's Mac through an official self-hosted runner,
-using `[self-hosted, macOS, ARM64, hivex]`. GitHub retains secrets, logs and PR checks; no hosted
-runner fallback is configured. No speed benchmark is required. A queued, skipped or interrupted
-run is not a pass. Local verification remains required when the runner is unavailable.
-
-Runner installation is repository administration, outside Hivex's product. Register the admitted
-macOS ARM64 release from GitHub's runner settings in its own directory, verify the official checksum,
-and use the generated `svc.sh install/start/status/stop` commands. Keep automatic updates enabled,
-a stable Homebrew/system PATH and the Mac awake and connected under the logged-in user. The
-runner work directory must be separate from the developer checkout and other repository runners.
-Only trusted code may run on this persistent host; review that boundary before public contributions.
-See [GitHub's runner reference](https://docs.github.com/en/actions/reference/runners/self-hosted-runners).
-
-During a host migration, disable Actions, register and confirm the runner is online, and merge all
-workflow routes before re-enabling Actions. Then dispatch Quality on that exact revision and check
-the assigned runner and completed result. The route change alone is not functional verification.
-
-Use `bun install` for development and `bun ci` for frozen installation. Bun owns dependency
-installation through its native configuration and lockfile; Hivex has no custom installer or
-registry verifier. See the [installation decision](adr/0003-independent-bun-installation.md).
-
-The lint configuration owns executable syntax/complexity constraints: cyclomatic complexity 20,
-cognitive complexity 15, at most four parameters, nesting depth three and no nested/chained
-ternaries. Refactor around meaningful responsibilities rather than adding tiny wrappers merely to
-make a number pass. Changes to those limits require a documented decision.
-
-## Tests protect behavior
-
-TDD guides development through meaningful failing examples; it does not require a test for every
-function, component, wrapper or line. A test must identify a supported behavior, meaningful invariant
-or regression it protects. Prefer the caller's observable interface and results that survive an
-internal refactor.
-
-For UI, test visible content, accessibility, interactions and loading/error/empty-state behavior.
-Do not freeze arbitrary child arrays, wrapper counts or class/style arrangements. A visual dimension
-needs a test only when it is an intentional requirement worth maintaining. For example, displaying
-"2 of 4" is a behavior; representing it as exactly three React children is not.
-
-Mocks, call counts, ordering and exact bytes are not automatically wrong. They can protect an
-external protocol, idempotency, a query budget or faithful source reproduction. Their justification
-must be the contract, not the current arrangement of internal helpers. Expected results must be
-independent examples, not the implementation's own calculation repeated in the test.
-
-Review existing tests as retain, rewrite, consolidate or remove. Remove tests for retired behavior
-with that behavior; preserve still-needed guarantees at the replacement's actual interface. Do not
-port a legacy battery mechanically, chase a test-count target or retain duplicate suites indefinitely.
-
-## Files and runtime data have a lifecycle
-
-Create a source file for a meaningful responsibility and a document for a distinct authoritative
-purpose. Do not create files for every helper, task, turn, attempt or handoff merely to satisfy a
-layout convention or a lint threshold.
-
-Before introducing persistent state, define its purpose, location, owner and retention. Prefer a small
-project-local data store to an unbounded tree of per-event files. A per-unit atomic checkpoint can be
-a database transaction; it does not require a separate file. Fewer filenames alone do not bound data
-growth: cached data, run history and diagnostics also need size/count/age limits and cleanup behavior.
-
-Normal read-only queries should leave no per-query artifacts. Clean up owned temporary resources
-on ordinary completion and handled failures. Interrupted work must remain recoverable without being
-silently retried or discarded. Export diagnostic bundles when needed rather than automatically
-writing a new report for every successful step. Retention must preserve the accepted state and the
-evidence needed by supported historical/recovery operations; it must not invent a successful cleanup.
-
-## Documentation is maintained authority
-
-Code must be self-explanatory through clear names, structure and behavior. Repository Markdown is
-the source of truth for intent, constraints, decisions and reasons that code cannot explain. Do not
-write a parallel implementation manual or use documentation to compensate for unclear code.
-Accepted source history and Markdown retain authority; caches, model output and search hits do not.
-An accepted status alone does not settle amendments, exceptions or contradictions. Keep unresolved
-evidence explicit. Never promote a historical agent's description of an owner ruling without
-checking its provenance and applicability.
-
-Capture every decision worth preserving in its appropriate repository document as part of the work.
-Do not leave accepted knowledge only in a conversation, issue comment or runtime log. Update the
-existing canonical document when it already owns the topic and scope; create a new one only when
-it has a distinct purpose. An issue can track the work and preserve discussion, but it is not a
-substitute for incorporating the resulting doctrine into the documentation.
-
-Keep docs with the monorepo, workspace or module they describe. Link to common rules instead of
-copying them. Recommended new Markdown should state purpose/scope, use stable headings and suitable
-metadata, keep a rule with its conditions/exceptions, and link its sources and replacements. Accept
-compatible existing Markdown without forcing those authors to adopt our template. Do not generate
-empty documentation for every module or add non-Markdown readers to the current scope.
-
-Use repository decisions and review evidence for durable knowledge, not private agent memory.
-Checkpoints identify the exact commit, verified work and remaining work. Choose a context handoff
-when the task needs it; Hivex does not impose the retired machinery's fixed token thresholds.
-Knowledge-model operations use the admitted Luna/max profile and record actual usage, including
-failed or interrupted attempts. Deterministic retrieval and maintenance do not require a model.
-
-The replacement workflow follows [ADR 0010](adr/0010-practical-knowledge-assistance.md). It processes
-bounded document batches with one additional knowledge check, keeps partial knowledge usable and
-preserves a work budget across phases and resumption. A consultation maintains one pending batch
-before answering, and a source-based repair replaces interpretations without changing doctrine.
-Keep check warnings scoped and public evidence limited to source coordinates, version and text. Avoid a new abstraction or protocol unless it
-protects a concrete requirement. The owner-authorized implementation can replace the earlier
-cohort/admission pipeline; its historical evidence remains unchanged.
-
-Hivex assists the principal reviewer with decisions, dependencies, exceptions and possible conflicts.
-The reviewer verifies its findings. Missing context or uncertainty limits the conclusions it affects;
-a definitive finding must refer to the actual document and implementation versions reviewed.
-
-## Retire mechanisms without losing knowledge
-
-Early use in Compi can support validation and recovery before full retirement. Necessary adoption
-and verification work belongs to Hivex completion. Alternative model integrations are evolutionary work;
-keep the current Codex/Luna route usable without spreading its assumptions into the knowledge model.
-
-After knowledge recovery, replacement validation and consumer migration, remove obsolete orchestration
-code, scripts, hooks, configuration, tests, dependencies and active instructions. Do not carry an unused
-legacy framework into Hivex under another name. Preserve useful decisions in their canonical docs and
-retain necessary historical evidence in Git or a bounded private archive outside the active worktree.
-Do not rewrite Git history or destroy the accepted Opus graph before its replacement is admitted.
-
-Early use can precede complete legacy recovery. Complete closure requires useful historical knowledge
-in Markdown, Hivex demonstrated in Compi and the old active machinery retired with its consumers.
-Validate the new workflow against bounded real cases, not identity with an old model's graph or an
-exhaustive replay prerequisite. Release packages exclude private project evidence and retired runtime.
-
-## Distribution
-
-The owner selected `@h1v35/hivex` for the npm package on 2026-09-08, retaining `hivex` as the installed
-command, and approved the MIT license. The scoped name avoids the unrelated existing unscoped npm
-package. Use an authenticated account authorized for that scope; do not infer npm ownership from a
-matching GitHub name. Release preparation must verify the packed contents and exclude private project
-evidence and runtime stores. Compi adopts a pinned published version after the complete cycle is
-validated; this decision alone does not mean a package has been published.
-
-Before publication, inspect and scan the exact package archive for secrets and unintended private
-content. Record its hash and the completed scan result; a repack requires a fresh check. Publish the
-same verified artifact, not an unchecked reconstruction from a changed working tree.