ai-docs generate

scan -> classify -> map -> symbols -> contracts -> examples
     -> context -> plan -> generate -> verify -> review -> apply
     -> render -> preview -> publish -> km sync

parse args
read files
call API
write output
print done

parse args
load config
resolve workspace
build execution context
run use case
emit diagnostics
write artifacts atomically
return stable exit code

CLI Shell
  -> Command Layer
  -> Application Layer
  -> Domain Layer
  -> Infrastructure Layer
  -> Artifact Store

aidocs-cli/
  src/
    cli/
      main.ts
      commands/
        init.command.ts
        scan.command.ts
        map.command.ts
        context.command.ts
        plan.command.ts
        generate.command.ts
        verify.command.ts
        review.command.ts
        apply.command.ts
        render.command.ts
        preview.command.ts
        km.command.ts
      options/
        global-options.ts
        output-options.ts
        provider-options.ts
      help/
        examples.ts
        usage.ts

    app/
      use-cases/
        init-project.ts
        scan-repository.ts
        build-repository-map.ts
        compile-context.ts
        plan-documentation.ts
        generate-pages.ts
        verify-documentation.ts
        review-proposals.ts
        apply-patches.ts
        render-site.ts
        preview-site.ts
        sync-knowledge.ts
      workflow/
        pipeline-runner.ts
        step-runner.ts
        execution-context.ts
      ports/
        file-system.port.ts
        git.port.ts
        llm-provider.port.ts
        mdx-renderer.port.ts
        knowledge-sink.port.ts
        token-counter.port.ts
        process-runner.port.ts
        clock.port.ts

    domain/
      artifacts/
        artifact-id.ts
        artifact-manifest.ts
        artifact-kind.ts
      repo/
        repository-scan.ts
        repository-map.ts
        file-classification.ts
      context/
        context-unit.ts
        prompt-bundle.ts
        token-budget.ts
      docs/
        page-spec.ts
        doc-plan.ts
        mdx-page.ts
        navigation-plan.ts
      verification/
        verification-report.ts
        diagnostic.ts
        severity.ts
      review/
        review-manifest.ts
        patch.ts
      km/
        knowledge-node.ts
        knowledge-relation.ts

    infra/
      fs/
        node-file-system.ts
        atomic-writer.ts
      git/
        git-cli-adapter.ts
      llm/
        openai-provider.ts
        local-model-provider.ts
        fake-provider.ts
      renderer/
        mdx-renderer.ts
      km/
        logseq-sink.ts
        opennote-export-sink.ts
      tokens/
        tiktoken-counter.ts
        approximate-token-counter.ts
      config/
        config-loader.ts
        config-schema.ts
      logging/
        logger.ts
        progress.ts

    testing/
      fixtures/
      harness/
      golden/

export async function generateCommand(args: GenerateArgs): Promise<number> {
  const shell = await CliShell.boot(args.globalOptions);

  const result = await shell.useCases.generatePages.execute({
    target: args.target,
    dryRun: args.dryRun,
    profile: args.profile,
    changedOnly: args.changedOnly,
    reviewMode: args.review,
  });

  shell.output.render(result);

  return result.exitCode;
}

aidocs generate --profile ci --json --no-color --workspace ./services/billing

export interface ExecutionContext {
  cwd: AbsolutePath;
  workspaceRoot: AbsolutePath;
  profile: string;
  outputMode: 'human' | 'json' | 'ndjson';
  color: boolean;
  interactive: boolean;
  ci: boolean;
  dryRun: boolean;
  config: ResolvedConfig;
  logger: Logger;
  diagnostics: DiagnosticSink;
  artifactStore: ArtifactStore;
  cancellation: CancellationToken;
}

ScanRepository
BuildRepositoryMap
CompileContext
PlanDocumentation
GeneratePages
VerifyDocumentation
ReviewProposals
ApplyPatches
RenderSite
SyncKnowledge

export interface GeneratePagesInput {
  target?: PageTarget;
  changedOnly: boolean;
  dryRun: boolean;
  reviewMode: 'proposal' | 'apply' | 'none';
}

export interface GeneratePagesResult {
  generatedPages: GeneratedPageSummary[];
  skippedPages: SkippedPageSummary[];
  verificationReportId?: ArtifactId;
  reviewManifestId?: ArtifactId;
  diagnostics: Diagnostic[];
  exitCode: ExitCode;
}

A generated page cannot claim behavior unless supported by source refs.

export class PageSpec {
  constructor(
    readonly id: PageId,
    readonly title: string,
    readonly audience: Audience,
    readonly sourceRefs: SourceRef[],
    readonly allowedClaimTypes: ClaimType[],
    readonly forbiddenClaims: ForbiddenClaim[],
    readonly requiredSections: SectionSpec[],
  ) {}

  validate(): DomainViolation[] {
    const violations: DomainViolation[] = [];

    if (this.sourceRefs.length === 0) {
      violations.push({
        code: 'PAGE_SPEC_WITHOUT_SOURCE_REFS',
        message: 'Page spec must include at least one source ref.',
      });
    }

    return violations;
  }
}

FileSystemAdapter
GitAdapter
LLMProvider
TokenCounter
MDXRenderer
KnowledgeSink
ProcessRunner
SecretScanner
OpenAPILoader

export interface LlmProvider {
  complete(input: LlmRequest): Promise<LlmResponse>;
  stream?(input: LlmRequest): AsyncIterable<LlmEvent>;
  estimateCost?(input: LlmRequest): Promise<CostEstimate>;
}

OpenAIProvider
AnthropicProvider
LocalModelProvider
ReplayProvider
FakeProvider

scan.v1.json
classification.v1.json
repo-map.v1.json
symbols.v1.json
contracts.v1.json
examples.v1.json
knowledge-graph.v1.json
retrieval-index.v1.json
prompt-bundle.v1.json
page-spec.v1.json
doc-plan.v1.json
generated-page.v1.mdx
verification-report.v1.json
review-manifest.v1.json
navigation-plan.v1.json
render-manifest.v1.json

aidocs artifacts list

KIND                    ID                 CREATED               STATUS
scan.v1                 scan_8f21          2026-07-04 10:22      ok
repo-map.v1             map_c612           2026-07-04 10:22      ok
prompt-bundle.v1        pb_7119            2026-07-04 10:23      ok
generated-page.v1       page_991a          2026-07-04 10:24      needs-review
verification-report.v1  ver_12ac           2026-07-04 10:25      failed

export interface ArtifactRegistry {
  put<T extends Artifact>(artifact: T): Promise<ArtifactRef<T>>;
  get<T extends Artifact>(ref: ArtifactRef<T>): Promise<T>;
  find(query: ArtifactQuery): Promise<ArtifactRef<Artifact>[]>;
  latest(kind: ArtifactKind, scope?: ArtifactScope): Promise<ArtifactRef<Artifact> | null>;
}

export interface PipelineStep<I, O> {
  id: string;
  name: string;
  run(input: I, ctx: ExecutionContext): Promise<O>;
  cacheKey?(input: I, ctx: ExecutionContext): Promise<string>;
  canSkip?(input: I, ctx: ExecutionContext): Promise<SkipReason | null>;
}

Error: failed

✘ API reference generation failed

Reason:
  OpenAPI document contains duplicate operationId: createUser

Where:
  openapi/public.yaml#/paths/~1users/post
  openapi/admin.yaml#/paths/~1users/post

Impact:
  Cannot generate stable endpoint page IDs.

Fix:
  Rename one operationId or configure operationIdConflictStrategy.

Docs:
  aidocs explain OPERATION_ID_CONFLICT

export interface Diagnostic {
  code: string;
  severity: 'info' | 'warning' | 'error' | 'fatal';
  message: string;
  location?: DiagnosticLocation;
  impact?: string;
  suggestion?: string;
  sourceRefs?: SourceRef[];
  docsUrl?: string;
}

export enum ExitCode {
  Ok = 0,
  UsageError = 2,
  ConfigError = 3,
  WorkspaceError = 4,
  VerificationFailed = 10,
  DriftDetected = 11,
  ReviewRequired = 12,
  GenerationFailed = 20,
  ProviderUnavailable = 21,
  SecurityViolation = 30,
  InternalError = 70,
}

human
json
ndjson

aidocs verify

Verification failed: 3 errors, 5 warnings

Errors:
  DOC-LINK-001  Broken internal link: /api/users/create
  MDX-003       Invalid MDX component: <UnknownCallout>
  SRC-009       Claim has no source ref: docs/guides/auth.mdx:42

Next:
  aidocs verify --fix
  aidocs explain SRC-009

aidocs verify --json

aidocs generate --ndjson

{"type":"step.started","step":"compile-context","time":"2026-07-04T10:00:00Z"}
{"type":"diagnostic","severity":"warning","code":"CTX-LOW-COVERAGE","message":"Only 42% of required source refs were included."}
{"type":"step.finished","step":"compile-context","durationMs":1820}

aidocs review

Apply 3 safe patches? [y/N]

aidocs review --apply --ci

REVIEW_DECISION_REQUIRED

CI mode must never wait for stdin.

.aidocs/
aidocs.config.yaml
docs.json
.git/
package.json
pom.xml
go.mod
Cargo.toml

start from cwd
walk upward
if aidocs.config.yaml found -> workspace root
else if docs.json + .git found -> docs workspace
else if .git found -> repo root
else fail with WORKSPACE_NOT_FOUND

repo/
  aidocs.config.yaml
  services/
    billing/
      aidocs.config.yaml
    identity/
      aidocs.config.yaml
  docs/
    docs.json

aidocs scan --workspace services/billing

export interface FileSystemPort {
  readText(path: AbsolutePath): Promise<string>;
  writeText(path: AbsolutePath, content: string): Promise<void>;
  writeTextAtomic(path: AbsolutePath, content: string): Promise<void>;
  exists(path: AbsolutePath): Promise<boolean>;
  list(path: AbsolutePath): Promise<DirEntry[]>;
  stat(path: AbsolutePath): Promise<FileStat>;
}

write temp file in same directory
fsync if needed
rename temp -> final

export interface GitPort {
  root(cwd: AbsolutePath): Promise<AbsolutePath | null>;
  status(): Promise<GitStatus>;
  changedFiles(base?: string): Promise<RepoPath[]>;
  diff(paths?: RepoPath[]): Promise<string>;
  blame(path: RepoPath): Promise<BlameInfo[]>;
  currentBranch(): Promise<string | null>;
}

CLI may read Git state by default, but must not commit or push unless explicitly requested.

export interface LlmProvider {
  id: string;
  capabilities(): LlmCapabilities;
  complete(request: LlmRequest): Promise<LlmResponse>;
}

export interface LlmRequest {
  model: string;
  messages: LlmMessage[];
  temperature: number;
  maxOutputTokens?: number;
  responseFormat?: ResponseFormat;
  metadata: RequestMetadata;
}

prompt bundle validation
secret redaction
visibility check
cost estimate
rate-limit policy
request audit

schema validation
MDX parse
claim extraction
source ref check
verification
artifact persistence

On cancellation, finish current atomic write or rollback temp files, then emit cancellation report.

export interface CancellationToken {
  readonly cancelled: boolean;
  throwIfCancelled(): void;
  onCancel(handler: () => Promise<void> | void): void;
}

for await (const file of scanner.walk(root)) {
  ctx.cancellation.throwIfCancelled();
  await processFile(file);
}

export interface ConcurrencyPolicy {
  fileWorkers: number;
  parserWorkers: number;
  providerRequests: number;
  renderWorkers: number;
}

✓ scan repository                 1.2s   1,842 files
✓ classify files                  0.6s   412 documentable
✓ build repo map                  0.2s   12 modules
✓ compile context                 1.8s   42k tokens
⠼ generate API guide                    provider call 2/5

A user-facing problem must be diagnostic, not only log.
A reproducible pipeline result must be artifact, not only terminal output.

export interface AnalyzerPlugin {
  id: string;
  supports(file: ClassifiedFile): boolean;
  extract(input: AnalyzerInput): Promise<AnalyzerOutput>;
}

read selected files
emit diagnostics
emit artifacts
access config namespace plugin.<id>

aidocs doctor

Workspace
  root: /repo
  config: aidocs.config.yaml
  docs: docs/

Tools
  git: ok 2.45.0
  node: ok 22.x
  mermaid: missing optional

Providers
  openai: configured via env OPENAI_API_KEY
  local: disabled

Security
  secret scanning: enabled
  provider logging: redacted

Docs
  docs.json: ok
  mdx pages: 42
  broken links: 0

aidocs explain SRC-009

SRC-009: Claim has no source reference

Meaning:
  A generated documentation claim was not linked to any known source artifact.

Why it matters:
  Ungrounded claims can become hallucinated documentation.

Fix:
  Add source refs to the page spec, remove the claim, or mark it as human-authored.

Related:
  aidocs verify --grounding
  aidocs review --show-claims

Command tests
  -> args/flags/output/exit code

Application tests
  -> workflow behavior with fake ports

Domain tests
  -> rules, validation, scoring, artifact invariants

Infrastructure tests
  -> real FS/Git/provider contract tests

Golden tests
  -> generated prompt bundle, MDX output, diagnostics output

End-to-end tests
  -> sample repo -> docs output

test('generate does not write docs when review mode is proposal', async () => {
  const harness = await createCliHarness({ fixture: 'simple-api' });

  const result = await harness.run([
    'generate',
    '--page',
    'api/users',
    '--review',
  ]);

  expect(result.exitCode).toBe(ExitCode.ReviewRequired);
  expect(await harness.fs.exists('docs/api/users.mdx')).toBe(false);
  expect(await harness.artifacts.find({ kind: 'review-manifest.v1' })).toHaveLength(1);
});

tests/golden/
  simple-api/
    expected/
      scan.v1.json
      repo-map.v1.json
      doc-plan.v1.json
      docs/
        quickstart.mdx
        api/users.mdx

export class ReplayProvider implements LlmProvider {
  constructor(private cassetteDir: AbsolutePath) {}

  async complete(request: LlmRequest): Promise<LlmResponse> {
    const key = hashStableRequest(request);
    return await readCassette(this.cassetteDir, key);
  }
}

aidocs generate --provider replay --cassette tests/cassettes/simple-api

before scanning:
  path sandboxing
  ignore unsafe directories

before prompt bundle:
  file visibility classification
  secret redaction
  token budget

before provider call:
  provider policy check
  audit log
  cost/rate limit check

before writing docs:
  generated region check
  verification
  review policy

before km sync:
  visibility downgrade prevention

No external provider call may happen before the prompt bundle passes security validation.

async function main(argv: string[]): Promise<void> {
  const parsed = parseCli(argv);
  const shell = await CliShell.boot(parsed.globalOptions);

  try {
    const exitCode = await dispatch(parsed, shell);
    process.exitCode = exitCode;
  } catch (error) {
    const diagnostic = shell.errors.toDiagnostic(error);
    shell.output.renderDiagnostic(diagnostic);
    process.exitCode = diagnosticToExitCode(diagnostic);
  } finally {
    await shell.shutdown();
  }
}

resolve cwd
load env
load config
resolve workspace
create logger
create diagnostics sink
create artifact store
wire ports
wire use cases
install signal handlers

commands/generate.ts
  scan repo
  build prompt
  call LLM
  parse MDX
  write file
  verify links

GlobalConfig.provider = 'openai';

aidocs verify

openAiResponseId: string

Kenapa halaman ini berubah?

1. CLI shell + global options
2. config loader minimal
3. workspace detection
4. artifact store
5. diagnostics model
6. scan command
7. classify/map commands
8. context command with fake provider
9. generate command with replay provider
10. verify command
11. review/apply workflow
12. render/preview
13. km sync
14. provider abstraction production
15. plugin system

CLI command is thin.
Use case owns workflow.
Domain owns rules.
Infrastructure owns external systems.
Artifact registry owns reproducibility.
Diagnostics own user-facing failure explanation.
Provider response is never applied without verification.
CI mode never waits for input.
Exit codes are stable API.

aidocs
  command parser
  execution context
  config loader
  artifact registry
  use cases
  domain rules
  adapters
  diagnostics
  exit code contract
  testing harness