{"id":19356232,"url":"https://github.com/github/issue-parser","last_synced_at":"2025-04-23T10:32:34.150Z","repository":{"id":261260325,"uuid":"882001152","full_name":"github/issue-parser","owner":"github","description":"Convert issue form responses to JSON","archived":false,"fork":false,"pushed_at":"2025-04-01T15:26:40.000Z","size":641,"stargazers_count":10,"open_issues_count":1,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-01T15:26:59.173Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/github.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT","threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":"SECURITY","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-11-01T17:07:19.000Z","updated_at":"2025-04-01T15:25:28.000Z","dependencies_parsed_at":"2024-11-05T15:55:53.879Z","dependency_job_id":"37316c3d-815e-490b-a8c5-c08c2cd282f4","html_url":"https://github.com/github/issue-parser","commit_stats":{"total_commits":22,"total_committers":1,"mean_commits":22.0,"dds":0.0,"last_synced_commit":"826c84e37d5ef1870c75b1f8785ff7498a336afb"},"previous_names":["github/issue-parser"],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/github%2Fissue-parser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/github%2Fissue-parser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/github%2Fissue-parser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/github%2Fissue-parser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/github","download_url":"https://codeload.github.com/github/issue-parser/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250416685,"owners_count":21427030,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-10T07:03:31.460Z","updated_at":"2025-04-23T10:32:29.126Z","avatar_url":"https://github.com/github.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Issue Forms Parser\n\n![Check dist/](https://github.com/github/issue-parser/actions/workflows/check-dist.yml/badge.svg)\n![Code Coverage](./badges/coverage.svg)\n![CodeQL](https://github.com/github/issue-parser/actions/workflows/codeql.yml/badge.svg)\n![Continuous Integration](https://github.com/github/issue-parser/actions/workflows/continuous-integration.yml/badge.svg)\n![Continuous Delivery](https://github.com/github/issue-parser/actions/workflows/continuous-delivery.yml/badge.svg)\n![Linter](https://github.com/github/issue-parser/actions/workflows/linter.yml/badge.svg)\n\nConvert issue form responses to JSON\n\n## About\n\nThis package can be used to parse GitHub issues into machine-readable JSON for\nprocessing. In particular, it is designed to work with\n[issue forms](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms)\nto perform basic transformations on the issue body, resulting in a consistent\nJSON output.\n\nIssues submitted using issue forms use a structured Markdown format. **So long\nas the issue body is not heavily modified by the user,** we can reliably parse\nthe issue body into a JSON object.\n\n## Installation\n\n```bash\nnpm i @github/issue-parser\n```\n\n## Example\n\nHere is a simple example of how to use this package in your project.\n\n```typescript\nimport { parseIssue } from '@github/issue-parser'\n\nconst issue = parseIssue('\u003cissue body\u003e', '\u003ctemplate\u003e')\n```\n\nAssuming the issue and template look like these examples:\n\n- [Example Issue Markdown](./__fixtures__/example/issue.md)\n- [Example Template YAML](./__fixtures__/example/template.yml)\n\nThe resulting `issue` object will look like the following:\n\n```typescript\n{\n  name: 'this-thing',\n  nickname: 'thing',\n  color: ['blue'],\n  shape: ['square'],\n  sounds: ['re', 'mi'],\n  topics: [],\n  description: \"This is a description.\\n\\nIt has multiple lines.\\n\\nIt's pretty cool!\",\n  notes: '- Note\\n- Another note\\n- Lots of notes',\n  code: 'const thing = new Thing()\\nthing.doThing()',\n  'code-string': 'thing.toString()',\n  'is-thing': {\n    selected: ['Yes'],\n    unselected: ['No']\n  },\n  'is-thing-useful': {\n    selected: ['Sometimes'],\n    unselected: ['Yes', 'No']\n  },\n  'read-team': 'IssueOps-Demo-Readers',\n  'write-team': 'IssueOps-Demo-Writers'\n}\n```\n\n## Usage\n\n### `parseIssue`\n\nThis is the main function of the package. It takes two arguments:\n\n- `issue: string` - The body of the issue to be parsed\n- `template: string` - (Optional) The issue form template used to create the\n  issue\n- `options?: { slugify?: boolean }` - (Optional) Additional parsing options to\n  use when processing the issue body\n\nIf the `template` value is provided, the package will attempt to transform the\nissue response values into different types based on the `type` property of the\nspecific field in the template. If the `template` value is omitted, all parsed\nvalues will be returned as strings. For information on the transformations that\nare applied, see the [Transformations](#transformations) section.\n\n#### Parsing Options\n\n- `slugify: boolean` - If set to `true`, any parsed keys that are not found in\n  the issue forms template (if provided) will be converted to\n  [slugs](https://en.wikipedia.org/wiki/Clean_URL#Slug) using the\n  [slugify](https://www.npmjs.com/package/slugify) package. Otherwise, the\n  original header value will be used as the object key.\n\n### `parseTemplate(template?: string)`\n\nParses an issue form template and returns an object. This can be used to match\nform responses in the issue body with the fields, so that you can perform\nadditional validation.\n\nWhen parsing an issue and the associated form template, this package will\nattempt to match field IDs with response values. If a match is found, the field\nID will be used in the parsed object keys (instead of the header value from the\nmarkdown response). If no match is found, the header text is used as the object\nkey.\n\nFor example, if you have the following issue form template:\n\n```yaml\nname: Example Request\ndescription: Submit an example request\ntitle: '[Request] Example'\n\nbody:\n  - type: input\n    id: name\n    attributes:\n      label: The Name of the Thing\n      description: The name of the thing you want to create.\n      placeholder: this-is-the-thing\n    validations:\n      required: true\n```\n\nAnd the following issue body:\n\n```markdown\n### The Name of the Thing\n\nthis-thing\n\n### The Nickname of the Thing\n\nthing\n```\n\nThe resulting parsed issue would be:\n\n```jsonc\n{\n  // Uses the ID value from the issue form template as the key\n  \"name\": \"this-thing\",\n  // Uses the original header value from the issue body\n  \"The Nickname of the Thing\": \"thing\"\n}\n```\n\n## Transformations\n\nThe following transformations will take place for responses, depending on the\ninput type. The type is inferred from the issue form template. For information\non each specific type, see\n[Syntax for GitHub's form schema](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-githubs-form-schema).\n\n### Single Line\n\n[Type: `input`](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-githubs-form-schema#input)\n\nBefore:\n\n```plain\nThis is a response\n```\n\nAfter (no change):\n\n```plain\nThis is a response\n```\n\n### Multiline\n\n[Type: `textarea`](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-githubs-form-schema#textarea)\n\n\u003e [!NOTE]\n\u003e\n\u003e Empty lines are preserved in multiline responses.\n\nBefore:\n\n```plain\nFirst line :D\n\nThird line!\n```\n\nAfter:\n\n```plain\nFirst line :D\\n\\nThird line!\n```\n\n### Dropdown Selections\n\n[Type: `dropdown`](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-githubs-form-schema#dropdown)\n\nBefore:\n\n```plain\nred, blue, green\n```\n\nAfter:\n\n```json\n[\"red\", \"blue\", \"green\"]\n```\n\n### Checkboxes\n\n[Type: `checkboxes`](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-githubs-form-schema#checkboxes)\n\nBefore:\n\n```plain\n- [x] Pick me!\n- [ ] Don't pick me D:\n```\n\nAfter:\n\n```json\n{\n  \"selected\": [\"Pick me!\"],\n  \"unselected\": [\"Don't pick me D:\"]\n}\n```\n\n## Omitting Inputs\n\nIn the following situations, an input will be omitted from the output JSON:\n\n| Scenario        | Example                 |\n| --------------- | ----------------------- |\n| Invalid Heading | `## This is invalid`    |\n| Empty Heading   | `###`                   |\n|                 | `This is a value`       |\n| No Value        | `### This is a heading` |\n|                 |                         |\n|                 | `### This is another`   |\n|                 | `This is a value`       |\n\nNormally, if a form is submitted with empty field(s), they will be included in\nthe issue body as one of the following, depending on the input type in the form\ntemplate.\n\n| Type       | No Response     |\n| ---------- | --------------- |\n| `dropdown` | `None`          |\n| `input`    | `_No response_` |\n| `textarea` | `_No response_` |\n\n```markdown\n### Dropdown Field\n\nNone\n\n### Input or Textarea Field\n\n_No response_\n\n### Checkboxes Field\n\n- [ ] Item A\n- [ ] Item B\n```\n\nThese will be converted to one of the following, based on the type of input\nspecified in the issue form template:\n\n| Type         | Output                                |\n| ------------ | ------------------------------------- |\n| `checkboxes` | `{ \"selected\": [], \"unselected\": []}` |\n| `dropdown`   | `[]`                                  |\n| `input`      | `undefined`                           |\n| `textarea`   | `undefined`                           |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgithub%2Fissue-parser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgithub%2Fissue-parser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgithub%2Fissue-parser/lists"}