pixotope-documentalist 1.0.0

package/README.md

@@ -0,0 +1,189 @@
+# pixotope-documentalist
+
+Parses JSDoc-style API documentation comments from source files (TypeScript, JavaScript, Python) and publishes them as formatted pages to Confluence.
+
+## Installation
+
+```bash
+npm install pixotope-documentalist
+```
+
+Or run directly with npx:
+
+```bash
+npx pixotope-documentalist publish --config ./config.yml
+```
+
+## Quick Start
+
+1. Add doc comments to your source files
+2. Create a `config.yml` pointing to your sources and Confluence pages
+3. Set environment variables for Confluence auth
+4. Run `npx pixotope-documentalist publish`
+
+## Comment Format
+
+### TypeScript / JavaScript
+
+Use JSDoc-style block comments with `@api` as the entry tag:
+
+```typescript
+/**
+ * @api CopyShowFileToLocal
+ * @group Shows
+ * @kind call
+ * @description Copies a show file from the server to this machine.
+ * @param {string} ShowName - Name of the show to copy.
+ * @param {boolean} [Overwrite=false] - Whether to overwrite existing file.
+ * @returns {boolean} Success - Whether the copy succeeded.
+ * @example Copy a show
+ * >>> {"Type":"Call","Target":"Machine1-Daemon","Method":"CopyShowFileToLocal"}
+ * >>> {"Params":{"ShowName":"Show1"}}
+ * <<< {"Type":"CallResult","Method":"CopyShowFileToLocal"}
+ * <<< {"Result":{"Success":true}}
+ * @warning This may take a while for large files.
+ * @since 23.3.0
+ */
+export const copyShowFileToDisk = async (...) => { ... };
+```
+
+### Python
+
+Use `#` comment blocks:
+
+```python
+# @api DiscoverDevices
+# @group Network
+# @kind call
+# @description Discovers available devices on the local network.
+# @param {string} Subnet - The subnet to scan.
+# @param {integer} Timeout - Scan timeout in milliseconds.
+# @returns {boolean} Success - Whether the scan completed.
+def discover_devices(subnet: str, timeout: int) -> dict:
+    pass
+```
+
+## Tag Reference
+
+| Tag | Required | Description |
+|-----|----------|-------------|
+| `@api` | Yes | Endpoint name (displayed as title) |
+| `@group` | No | Section grouping header |
+| `@kind` | No | `call` (default), `get`, `set` |
+| `@description` | No | Multi-line description (continues until next tag) |
+| `@param` | No | `{type} Name - Description`. `[Name]` = optional, `[Name=default]` = with default |
+| `@returns` | No | `{type} Name - Description` |
+| `@example` | No | Title on first line, `>>>` for request messages, `<<<` for response messages |
+| `@warning` | No | Warning/note text |
+| `@since` | No | Version when this was introduced |
+| `@deprecated` | No | Deprecation notice |
+| `@internal` | No | Flag to exclude from published docs |
+| `@value` | No | For state docs: `{type} Name - Description` |
+
+## Configuration
+
+Create a `config.yml` in your project:
+
+```yaml
+confluence:
+  base_url: "https://your-domain.atlassian.net/wiki/rest/api/content"
+
+source_root: "."
+
+documents:
+  - id: daemon_calls
+    title: "Daemon API - Calls"
+    confluence_id:
+      master: "1234567890"
+      release: "0987654321"
+    sources:
+      - path: "packages/Daemon/src/endpoints/calls.ts"
+
+  - id: daemon_get
+    title: "Daemon API - Get"
+    confluence_id:
+      master: "1111111111"
+      release: "2222222222"
+    sources:
+      - path: "packages/Daemon/src/endpoints/get.ts"
+```
+
+- `source_root`: base path for resolving relative source paths (relative to config file location)
+- `confluence_id.master`: page ID for master/development docs
+- `confluence_id.release`: page ID for release docs
+
+## CLI Commands
+
+```bash
+# Parse source files and output JSON (for debugging)
+npx pixotope-documentalist parse --config ./config.yml --verbose
+
+# Parse + render to HTML files locally (no API calls)
+npx pixotope-documentalist preview --config ./config.yml
+
+# Parse + render + upload to Confluence
+npx pixotope-documentalist publish --config ./config.yml --target master
+
+# Show what would change without publishing
+npx pixotope-documentalist diff --config ./config.yml --target master
+```
+
+### Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-c, --config <path>` | Path to config.yml | `config.yml` |
+| `-d, --document <id>` | Process only this document | all documents |
+| `-t, --target <env>` | `master` or `release` | `master` |
+| `--version-stamp <ver>` | Version stamp | `local` |
+| `-v, --verbose` | Verbose logging | off |
+
+## Environment Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `CONFLUENCE_USER` | Confluence account email |
+| `CONFLUENCE_TOKEN` | Confluence API token ([generate here](https://id.atlassian.com/manage-profile/security/api-tokens)) |
+| `PIXOTOPE_DOCS_NPM_TOKEN` | npm publish auth token (only for publishing the package) |
+
+Create a `.env` file (git-ignored) for local use:
+
+```
+CONFLUENCE_USER=your.email@pixotope.com
+CONFLUENCE_TOKEN=your_api_token
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run locally with ts-node
+npx ts-node src/index.ts preview --config example/config.yml
+
+# Run tests
+npm test
+
+# Build
+npm run build
+
+# Publish to npm
+npm publish
+```
+
+## Example
+
+The `example/` folder contains a self-contained demo:
+
+```bash
+npx ts-node src/index.ts preview --config example/config.yml
+# Check output in example/output/formatted/
+```
+
+## Supported File Types
+
+- `.ts`, `.tsx` (TypeScript)
+- `.js`, `.jsx` (JavaScript)
+- `.py` (Python)
+- `.h`, `.cpp`, `.hpp` (C++)

package/dist/config.d.ts

@@ -0,0 +1,4 @@
+import { Config } from "./models";
+export declare function loadConfig(configPath: string): Config;
+export declare function resolveSourcePath(sourceRoot: string, sourcePath: string, configDir: string): string;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAElC,wBAAgB,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CA6CrD;AAED,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,GAChB,MAAM,CAGR"}

package/dist/config.js

@@ -0,0 +1,58 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadConfig = loadConfig;
+exports.resolveSourcePath = resolveSourcePath;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const yaml_1 = __importDefault(require("yaml"));
+function loadConfig(configPath) {
+    const absolutePath = path_1.default.resolve(configPath);
+    if (!fs_1.default.existsSync(absolutePath)) {
+        throw new Error(`Config file not found: ${absolutePath}`);
+    }
+    const content = fs_1.default.readFileSync(absolutePath, "utf-8");
+    const raw = yaml_1.default.parse(content);
+    if (!raw.confluence?.base_url) {
+        throw new Error("Config missing required field: confluence.base_url");
+    }
+    if (!raw.documents || !Array.isArray(raw.documents)) {
+        throw new Error("Config missing required field: documents (array)");
+    }
+    const config = {
+        confluence: {
+            base_url: raw.confluence.base_url,
+        },
+        source_root: raw.source_root || ".",
+        documents: raw.documents.map((doc) => {
+            if (!doc.id)
+                throw new Error("Document missing required field: id");
+            if (!doc.title)
+                throw new Error("Document missing required field: title");
+            if (!doc.confluence_id)
+                throw new Error(`Document "${doc.id}" missing required field: confluence_id`);
+            if (!doc.sources || !Array.isArray(doc.sources)) {
+                throw new Error(`Document "${doc.id}" missing required field: sources (array)`);
+            }
+            return {
+                id: doc.id,
+                title: doc.title,
+                confluenceId: {
+                    master: String(doc.confluence_id.master || ""),
+                    release: String(doc.confluence_id.release || ""),
+                },
+                sources: doc.sources.map((s) => ({
+                    path: typeof s === "string" ? s : s.path,
+                })),
+            };
+        }),
+    };
+    return config;
+}
+function resolveSourcePath(sourceRoot, sourcePath, configDir) {
+    const resolvedRoot = path_1.default.resolve(configDir, sourceRoot);
+    return path_1.default.resolve(resolvedRoot, sourcePath);
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":";;;;;AAKA,gCA6CC;AAED,8CAOC;AA3DD,4CAAoB;AACpB,gDAAwB;AACxB,gDAAwB;AAGxB,SAAgB,UAAU,CAAC,UAAkB;IAC3C,MAAM,YAAY,GAAG,cAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;IAE9C,IAAI,CAAC,YAAE,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;QACjC,MAAM,IAAI,KAAK,CAAC,0BAA0B,YAAY,EAAE,CAAC,CAAC;IAC5D,CAAC;IAED,MAAM,OAAO,GAAG,YAAE,CAAC,YAAY,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;IACvD,MAAM,GAAG,GAAG,cAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAEhC,IAAI,CAAC,GAAG,CAAC,UAAU,EAAE,QAAQ,EAAE,CAAC;QAC9B,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;IACxE,CAAC;IACD,IAAI,CAAC,GAAG,CAAC,SAAS,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;QACpD,MAAM,IAAI,KAAK,CAAC,kDAAkD,CAAC,CAAC;IACtE,CAAC;IAED,MAAM,MAAM,GAAW;QACrB,UAAU,EAAE;YACV,QAAQ,EAAE,GAAG,CAAC,UAAU,CAAC,QAAQ;SAClC;QACD,WAAW,EAAE,GAAG,CAAC,WAAW,IAAI,GAAG;QACnC,SAAS,EAAE,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,GAAQ,EAAE,EAAE;YACxC,IAAI,CAAC,GAAG,CAAC,EAAE;gBAAE,MAAM,IAAI,KAAK,CAAC,qCAAqC,CAAC,CAAC;YACpE,IAAI,CAAC,GAAG,CAAC,KAAK;gBAAE,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAC;YAC1E,IAAI,CAAC,GAAG,CAAC,aAAa;gBAAE,MAAM,IAAI,KAAK,CAAC,aAAa,GAAG,CAAC,EAAE,yCAAyC,CAAC,CAAC;YACtG,IAAI,CAAC,GAAG,CAAC,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;gBAChD,MAAM,IAAI,KAAK,CAAC,aAAa,GAAG,CAAC,EAAE,2CAA2C,CAAC,CAAC;YAClF,CAAC;YAED,OAAO;gBACL,EAAE,EAAE,GAAG,CAAC,EAAE;gBACV,KAAK,EAAE,GAAG,CAAC,KAAK;gBAChB,YAAY,EAAE;oBACZ,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,aAAa,CAAC,MAAM,IAAI,EAAE,CAAC;oBAC9C,OAAO,EAAE,MAAM,CAAC,GAAG,CAAC,aAAa,CAAC,OAAO,IAAI,EAAE,CAAC;iBACjD;gBACD,OAAO,EAAE,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAM,EAAE,EAAE,CAAC,CAAC;oBACpC,IAAI,EAAE,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI;iBACzC,CAAC,CAAC;aACJ,CAAC;QACJ,CAAC,CAAC;KACH,CAAC;IAEF,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAgB,iBAAiB,CAC/B,UAAkB,EAClB,UAAkB,EAClB,SAAiB;IAEjB,MAAM,YAAY,GAAG,cAAI,CAAC,OAAO,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;IACzD,OAAO,cAAI,CAAC,OAAO,CAAC,YAAY,EAAE,UAAU,CAAC,CAAC;AAChD,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const path_1 = __importDefault(require("path"));
+const dotenv_1 = __importDefault(require("dotenv"));
+const config_1 = require("./config");
+const pipeline_1 = require("./pipeline");
+// Load .env file from cwd
+dotenv_1.default.config();
+const program = new commander_1.Command();
+program
+    .name("pixotope-documentalist")
+    .description("Parse API documentation from source files and publish to Confluence")
+    .version("1.0.0");
+function makeOptions(cmd) {
+    const configPath = path_1.default.resolve(cmd.config || "config.yml");
+    const configDir = path_1.default.dirname(configPath);
+    return {
+        config: (0, config_1.loadConfig)(configPath),
+        configDir,
+        document: cmd.document,
+        target: cmd.target || "master",
+        version: cmd.versionStamp || "local",
+        verbose: cmd.verbose || false,
+    };
+}
+program
+    .command("parse")
+    .description("Parse source files and output intermediate JSON")
+    .option("-c, --config <path>", "Path to config.yml", "config.yml")
+    .option("-d, --document <id>", "Process only this document")
+    .option("-v, --verbose", "Verbose logging")
+    .action((cmd) => {
+    const options = makeOptions(cmd);
+    (0, pipeline_1.runParse)(options);
+});
+program
+    .command("preview")
+    .description("Parse + render to HTML files (no API calls)")
+    .option("-c, --config <path>", "Path to config.yml", "config.yml")
+    .option("-d, --document <id>", "Process only this document")
+    .option("-v, --verbose", "Verbose logging")
+    .action((cmd) => {
+    const options = makeOptions(cmd);
+    (0, pipeline_1.runPreview)(options);
+});
+program
+    .command("publish")
+    .description("Parse + render + upload to Confluence")
+    .option("-c, --config <path>", "Path to config.yml", "config.yml")
+    .option("-d, --document <id>", "Process only this document")
+    .option("-t, --target <env>", "master or release", "master")
+    .option("--version-stamp <ver>", "Version stamp", "local")
+    .option("-v, --verbose", "Verbose logging")
+    .action(async (cmd) => {
+    const options = makeOptions(cmd);
+    await (0, pipeline_1.runPublish)(options);
+});
+program
+    .command("diff")
+    .description("Show what would change without publishing")
+    .option("-c, --config <path>", "Path to config.yml", "config.yml")
+    .option("-d, --document <id>", "Process only this document")
+    .option("-t, --target <env>", "master or release", "master")
+    .option("-v, --verbose", "Verbose logging")
+    .action(async (cmd) => {
+    const options = makeOptions(cmd);
+    await (0, pipeline_1.runDiff)(options);
+});
+program.parse();
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/models/index.d.ts

@@ -0,0 +1,64 @@
+export interface Param {
+    name: string;
+    type: string;
+    description: string;
+    optional: boolean;
+    default?: string;
+}
+export interface Example {
+    description: string;
+    request: string[];
+    response: string[];
+}
+export interface Endpoint {
+    name: string;
+    kind: "call" | "get" | "set";
+    description: string;
+    params: Param[];
+    returns: Param[];
+    warnings: string[];
+    examples: Example[];
+    since?: string;
+    deprecated?: string;
+    internal: boolean;
+}
+export interface Value {
+    name: string;
+    type: string;
+    description: string;
+    children: Value[];
+}
+export interface Group {
+    header: string;
+    description: string;
+    endpoints: Endpoint[];
+    values: Value[];
+}
+export interface Document {
+    title: string;
+    version: string;
+    confluenceId: string;
+    groups: Group[];
+}
+export interface DocumentConfig {
+    id: string;
+    title: string;
+    confluenceId: {
+        master: string;
+        release: string;
+    };
+    sources: {
+        path: string;
+    }[];
+}
+export interface Config {
+    confluence: {
+        base_url: string;
+    };
+    source_root: string;
+    documents: DocumentConfig[];
+}
+export declare function createEndpoint(name: string, kind?: Endpoint["kind"]): Endpoint;
+export declare function createGroup(header?: string): Group;
+export declare function createDocument(title?: string): Document;
+//# sourceMappingURL=index.d.ts.map

package/dist/models/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/models/index.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,KAAK;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,OAAO;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,KAAK,GAAG,KAAK,CAAC;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,KAAK,EAAE,CAAC;IAChB,OAAO,EAAE,KAAK,EAAE,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,KAAK;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,KAAK,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,KAAK;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,QAAQ,EAAE,CAAC;IACtB,MAAM,EAAE,KAAK,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,KAAK,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE;QACZ,MAAM,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;IACF,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC7B;AAED,MAAM,WAAW,MAAM;IACrB,UAAU,EAAE;QACV,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC;IACF,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,cAAc,EAAE,CAAC;CAC7B;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,QAAQ,CAAC,MAAM,CAAU,GAAG,QAAQ,CAWtF;AAED,wBAAgB,WAAW,CAAC,MAAM,GAAE,MAAW,GAAG,KAAK,CAOtD;AAED,wBAAgB,cAAc,CAAC,KAAK,GAAE,MAAW,GAAG,QAAQ,CAO3D"}

package/dist/models/index.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createEndpoint = createEndpoint;
+exports.createGroup = createGroup;
+exports.createDocument = createDocument;
+function createEndpoint(name, kind = "call") {
+    return {
+        name,
+        kind,
+        description: "",
+        params: [],
+        returns: [],
+        warnings: [],
+        examples: [],
+        internal: false,
+    };
+}
+function createGroup(header = "") {
+    return {
+        header,
+        description: "",
+        endpoints: [],
+        values: [],
+    };
+}
+function createDocument(title = "") {
+    return {
+        title,
+        version: "",
+        confluenceId: "",
+        groups: [createGroup()],
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/models/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/models/index.ts"],"names":[],"mappings":";;AAkEA,wCAWC;AAED,kCAOC;AAED,wCAOC;AA7BD,SAAgB,cAAc,CAAC,IAAY,EAAE,OAAyB,MAAM;IAC1E,OAAO;QACL,IAAI;QACJ,IAAI;QACJ,WAAW,EAAE,EAAE;QACf,MAAM,EAAE,EAAE;QACV,OAAO,EAAE,EAAE;QACX,QAAQ,EAAE,EAAE;QACZ,QAAQ,EAAE,EAAE;QACZ,QAAQ,EAAE,KAAK;KAChB,CAAC;AACJ,CAAC;AAED,SAAgB,WAAW,CAAC,SAAiB,EAAE;IAC7C,OAAO;QACL,MAAM;QACN,WAAW,EAAE,EAAE;QACf,SAAS,EAAE,EAAE;QACb,MAAM,EAAE,EAAE;KACX,CAAC;AACJ,CAAC;AAED,SAAgB,cAAc,CAAC,QAAgB,EAAE;IAC/C,OAAO;QACL,KAAK;QACL,OAAO,EAAE,EAAE;QACX,YAAY,EAAE,EAAE;QAChB,MAAM,EAAE,CAAC,WAAW,EAAE,CAAC;KACxB,CAAC;AACJ,CAAC"}

package/dist/parser/commentExtractor.d.ts

@@ -0,0 +1,12 @@
+export interface RawDocBlock {
+    lines: string[];
+    startLine: number;
+    filePath: string;
+}
+/**
+ * Extract documentation blocks from a source file.
+ * - JS/TS: Extracts /** ... * / blocks that contain @api tags
+ * - Python: Extracts consecutive # lines that contain @api tags
+ */
+export declare function extractDocBlocks(filePath: string): RawDocBlock[];
+//# sourceMappingURL=commentExtractor.d.ts.map

package/dist/parser/commentExtractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commentExtractor.d.ts","sourceRoot":"","sources":["../../src/parser/commentExtractor.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,EAAE,CAahE"}

package/dist/parser/commentExtractor.js

@@ -0,0 +1,132 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractDocBlocks = extractDocBlocks;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+/**
+ * Extract documentation blocks from a source file.
+ * - JS/TS: Extracts /** ... * / blocks that contain @api tags
+ * - Python: Extracts consecutive # lines that contain @api tags
+ */
+function extractDocBlocks(filePath) {
+    const content = fs_1.default.readFileSync(filePath, "utf-8");
+    const ext = path_1.default.extname(filePath).toLowerCase();
+    if ([".ts", ".tsx", ".js", ".jsx", ".h", ".cpp", ".hpp"].includes(ext)) {
+        return extractJSDocBlocks(content, filePath);
+    }
+    if (ext === ".py") {
+        return extractPythonDocBlocks(content, filePath);
+    }
+    return [];
+}
+/**
+ * Extract /** ... * / blocks from JS/TS/C++ files.
+ * Only returns blocks that contain at least one @api tag.
+ */
+function extractJSDocBlocks(content, filePath) {
+    const blocks = [];
+    const lines = content.split("\n");
+    let inBlock = false;
+    let blockLines = [];
+    let blockStartLine = 0;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const trimmed = line.trim();
+        if (!inBlock) {
+            // Check for /** start
+            if (trimmed.startsWith("/**")) {
+                inBlock = true;
+                blockStartLine = i + 1; // 1-indexed
+                blockLines = [];
+                // Handle single-line: /** @api Foo */
+                if (trimmed.endsWith("*/") && trimmed.length > 5) {
+                    const inner = trimmed.slice(3, -2).trim();
+                    blockLines.push(inner);
+                    inBlock = false;
+                    if (hasDocTag(blockLines)) {
+                        blocks.push({ lines: blockLines, startLine: blockStartLine, filePath });
+                    }
+                    continue;
+                }
+                // First line may have content after /**
+                const afterOpen = trimmed.slice(3).trim();
+                if (afterOpen) {
+                    blockLines.push(afterOpen);
+                }
+            }
+        }
+        else {
+            // Inside a block
+            if (trimmed.endsWith("*/")) {
+                // Last line — may have content before */
+                const beforeClose = trimmed.slice(0, -2).trim();
+                const cleaned = stripLeadingStar(beforeClose);
+                if (cleaned) {
+                    blockLines.push(cleaned);
+                }
+                inBlock = false;
+                if (hasDocTag(blockLines)) {
+                    blocks.push({ lines: blockLines, startLine: blockStartLine, filePath });
+                }
+            }
+            else {
+                // Middle line — strip leading " * "
+                blockLines.push(stripLeadingStar(trimmed));
+            }
+        }
+    }
+    return blocks;
+}
+/**
+ * Extract consecutive # comment blocks from Python files.
+ * Only returns blocks that contain at least one @api tag.
+ */
+function extractPythonDocBlocks(content, filePath) {
+    const blocks = [];
+    const lines = content.split("\n");
+    let blockLines = [];
+    let blockStartLine = 0;
+    for (let i = 0; i < lines.length; i++) {
+        const trimmed = lines[i].trim();
+        if (trimmed.startsWith("#")) {
+            if (blockLines.length === 0) {
+                blockStartLine = i + 1;
+            }
+            // Strip # prefix and trim
+            const commentContent = trimmed.replace(/^#+\s?/, "");
+            blockLines.push(commentContent);
+        }
+        else {
+            // Non-comment line — flush block if it has @api
+            if (blockLines.length > 0) {
+                if (hasDocTag(blockLines)) {
+                    blocks.push({ lines: blockLines, startLine: blockStartLine, filePath });
+                }
+                blockLines = [];
+            }
+        }
+    }
+    // Flush remaining
+    if (blockLines.length > 0 && hasDocTag(blockLines)) {
+        blocks.push({ lines: blockLines, startLine: blockStartLine, filePath });
+    }
+    return blocks;
+}
+function stripLeadingStar(line) {
+    // Remove leading "* " or "*"
+    if (line.startsWith("* "))
+        return line.slice(2);
+    if (line.startsWith("*"))
+        return line.slice(1);
+    return line;
+}
+function hasDocTag(lines) {
+    return lines.some((line) => {
+        const trimmed = line.trim();
+        return trimmed.startsWith("@api") || trimmed.startsWith("@group");
+    });
+}
+//# sourceMappingURL=commentExtractor.js.map

package/dist/parser/commentExtractor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commentExtractor.js","sourceRoot":"","sources":["../../src/parser/commentExtractor.ts"],"names":[],"mappings":"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"}

package/dist/parser/fileScanner.d.ts

@@ -0,0 +1,2 @@
+export declare function scanPath(filePath: string): string[];
+//# sourceMappingURL=fileScanner.d.ts.map

package/dist/parser/fileScanner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fileScanner.d.ts","sourceRoot":"","sources":["../../src/parser/fileScanner.ts"],"names":[],"mappings":"AASA,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAkBnD"}